NAV
python

La API de Buda.com

Qué bien! Has llegado a la documentación de la API de Buda.com. Si no eres desarrollador, quizás te sientas un poco perdido, pero no te preocupes, queremos que todos puedan entender cómo funciona y cómo podemos ayudarte.

La API de Buda.com es un puente que facilita la comunicación entre otros sistemas y nuestra plataforma. Consta de un conjunto de endpoints (rutas) mediante las cuales puedes realizar diversas consultas o acciones, ya sea sobre información pública o sobre tu cuenta de Buda.com si realizas la autenticación necesaria.

Si quieres seguir profundizando, en esta página se encuentra el detalle sobre cada uno de los endpoints que ofrece Buda.com, se describen sus propósitos, la estructura necesaria y la información que retornan.

Ahora que tienes una idea general de qué es la API, te contamos que ofrecemos APIs Rest y Websocket para ti o tu empresa. Estas te permiten construir lo que necesites de la manera más cómoda y flexible. Aquí encontrarás la documentación de ambos protocolos.

Si no eres desarrollador pero crees que a alguien de tu empresa o amigos les puede interesar, ¡no dudes en compartirles esta web para que se informen!

REST API

Introducción

Un ejemplo de llamada utilizando la librería requests

import requests # install requests with `pip install requests`

url = 'https://www.buda.com/api/v2/markets/eth-btc/ticker'
response = requests.get(url)
print(response.json())

La API de Buda.com, como la de la mayoría de los exchanges de criptomonedas, se divide en llamadas públicas y llamadas privadas:

En general, los URL de nuestra API se forman así

https://www.buda.com/api/[version]/[path].[format]

Donde, por el momento:

Parameter Value
version v2
format json

Librerias Open Source

Clientes

Si te quieres ahorrar un poco de trabajo, aquí tienes una recopilación de clientes de nuestra API en distintos lenguajes.

Ojo, estas librerías no son oficiales ni han sido probadas por el equipo de Buda.com, pero hemos hablado con sus autores y se ven buenas personas 😉

Lenguaje Link
Go https://github.com/niedbalski/go-buda
Java https://github.com/FeroSalgado/java-surbtc-api
Java https://github.com/daplay/jsurbtc
Javascript https://github.com/ajunge/buda-promise
Python https://github.com/delta575/trading-api-wrappers
Python https://github.com/CriptoPagos/surbtc-api-client-python

Si quieres compartir tu librería o ejemplo con la comunidad, escríbenos a [email protected]

Otras librerías

No podemos dejar de contarte sobre CCXT, una librería muy útil que te permite conectarte a más de 100 exchanges (incluyendo a Buda ❤️) usando Python, Javascript o PHP. Sí, en serio.

Llamadas Públicas

Mercados

import requests

url = 'https://www.buda.com/api/v2/markets'
response = requests.get(url)
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
  "markets": [
    {
      "id": "BTC-CLP",
      "name": "btc-clp",
      "base_currency": "BTC",
      "quote_currency": "CLP",
      "minimum_order_amount": ["0.001", "BTC"],
      "taker_fee": "0.8",
      "maker_fee": "0.4",
      "max_orders_per_minute":100,
      "maker_discount_percentage":"0.0",
      "taker_discount_percentage":"0.0",
      "maker_discount_tiers":{
        "*": 0.5
      },
      "taker_discount_tiers":{
        "*": 0.0,
        "6": 0.2,
        "7": 0.3
      }
    },
    {
      "id": "BTC-COP",
      "name": "btc-cop",
      "base_currency": "BTC",
      "quote_currency": "COP",
      "minimum_order_amount": ["0.001", "BTC"],
      "taker_fee": "0.8",
      "maker_fee": "0.4",
      "max_orders_per_minute":100,
      "maker_discount_percentage":"0.0",
      "taker_discount_percentage":"0.0",
      "maker_discount_tiers":{
        "*": 0.5
      },
      "taker_discount_tiers":{
        "*": 0.0,
        "6": 0.2,
        "7": 0.3
      }
    },
    ...
  ]
}

Obtener detalles de un mercado

import requests

market_id = 'btc-clp'
url = f'https://www.buda.com/api/v2/markets/{market_id}'
response = requests.get(url)
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
  "market": {
    "id": "BTC-CLP",
    "name": "btc-clp",
    "base_currency": "BTC",
    "quote_currency": "CLP",
    "minimum_order_amount": ["0.001", "BTC"],
    "taker_fee": "0.8",
    "maker_fee": "0.4",
    "max_orders_per_minute":100,
    "maker_discount_percentage":"0.0",
    "taker_discount_percentage":"0.0",
    "maker_discount_tiers":{},
    "taker_discount_tiers":{}
  }
}

Un mercado permite separar las compras y ventas por moneda. En un mercado se compra y vende un tipo de moneda (base_currency) y se usa otro tipo de moneda para pagar por estas compras y ventas (quote_currency). Por lo tanto, un mercado está identificado por las siglas que representa a este par de monedas.

Por ejemplo: el nombre del mercado en el cual se transan ethers (ETH) contra bitcoins (BTC) es: eth-btc.

HTTP Request

GET /markets

GET /markets/<market_id>

Path Parameters

Parámetro Descripción
market_id (opcional) La ID del mercado (Ej: btc-clp, eth-btc, etc).
Puedes obtener un listado completo de estos identificadores realizando la llamada sin incluir este parámetro.

Response Details

Key Tipo Descripción
id [string] Identificador del mercado
name [string] Nombre del mercado el cual corresponde al market_id
base_currency [string] Moneda de cambio
quote_currency [string] Moneda de pago
minimum_order_amount [amount, currency] Tamaño de orden mínimo aceptado
taker_fee [amount] Tarifa pagada por una orden taker
maker_fee [amount] Tarifa pagada por una orden maker
max_orders_per_minute [amount] Rate Limit para trading que tiene este mercado
maker_discount_percentage [string] Descuento Maker que tiene el mercado
taker_discount_percentage [string] Descuento Taker que tiene el mercado
maker_discount_tiers [hash] Descuento Maker por tiers que tiene el mercado
taker_discount_tiers [hash] Descuento Taker por tiers que tiene el mercado

Volumen transado

import requests

market_id = 'btc-clp'
url = f'https://www.buda.com/api/v2/markets/{market_id}/volume'
response = requests.get(url)
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
  "volume": {
    "ask_volume_24h": ["4.97241513", "BTC"],
    "ask_volume_7d": ["43.15391694", "BTC"],
    "bid_volume_24h": ["8.03642037", "BTC"],
    "bid_volume_7d": ["35.77704356", "BTC"],
    "market_id": "BTC-CLP"
  }
}

Esta llamada permite acceder a información del volumen transado en un determinado mercado, donde ask_volume representa el monto transado en órdenes de venta y bid_volume corresponde al monto transado de órdenes de compra.

HTTP Request

GET /markets/<market_id>/volume

Response Details

Key Tipo Descripción
ask_volume_24h [amount, currency] Monto transado de órdenes de venta durante las últimas 24 horas
ask_volume_7d [string] Monto transado de órdenes de venta durante las últimos 7 dias
bid_volume_24h [amount, currency] Monto transado de órdenes de compra durante las últimas 24 horas
bid_volume_7d [string] Monto transado de órdenes de compra durante las últimos 7 dias
market_id [string] Identificador del mercado consultado

Ticker

import requests

market_id = 'btc-clp'
url = f'https://www.buda.com/api/v2/markets/{market_id}/ticker'
response = requests.get(url)
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
  "ticker": {
    "last_price": ["879789.0", "CLP"],
    "market_id": "BTC-CLP",
    "max_bid": ["879658.0", "CLP"],
    "min_ask": ["876531.11", "CLP"],
    "price_variation_24h": "0.005",
    "price_variation_7d": "0.1",
    "volume": ["102.0", "BTC"]
  }
}

El ticker permite ver el estado actual de un determinado mercado. La respuesta a esta llamada entrega las mejores ofertas de compra y venta (bid y ask), asi como el precio de la ultima transacción (last_price) para el mercado solicitado. También incluye información como el volumen diario y cuanto ha cambiado el precio en las últimas 24 hrs.

HTTP Request

GET /markets/<market_id>/ticker

Path Parameters

Parámetro Descripción
market_id La ID del mercado (Ej: btc-clp, eth-btc, etc).
Puedes obtener un listado completo de estos identificadores a través de la llamada al endpoint de Mercados.

Response Details

Key Tipo Descripción
market_id [currency] Identificador del mercado consultado
last_price [amount, currency] Precio de la última orden ejecutada
min_ask [amount, currency] Menor precio de venta
max_bid [amount, currency] Máximo precio de compra
volume [amount, currency] Volumen transado en las últimas 24 horas
price_variation_24h [float] Cuanto ha variado el precio en las últimas 24 horas (porcentaje)
price_variation_7d [float] Cuanto ha variado el precio el los últimos 7 días (porcentaje)

Todos los Tickers

import requests

url = f'https://www.buda.com/api/v2/tickers'
response = requests.get(url)
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
  "tickers": [
    {"market_id":"BTC-CLP","price_variation_24h":"0.001","price_variation_7d":"-0.004","last_price":["14525279.0","CLP"]},
    {"market_id":"ETH-CLP","price_variation_24h":"-0.002","price_variation_7d":"0.024","last_price":["1105000.0","CLP"]},
    ...
  ]
}

Permite ver el estado actual de todos los mercados. La respuesta a esta llamada entrega la varianción del precio en el último día y en la última semana, junto con el precio de la última transacción (last_price) para cada mercado.

HTTP Request

GET /tickers

Response Details

Key Tipo Descripción
market_id [currency] Identificador del mercado consultado
last_price [amount, currency] Precio de la última orden ejecutada
price_variation_24h [float] Cuanto ha variado el precio en las últimas 24 horas (porcentaje)
price_variation_7d [float] Cuanto ha variado el precio el los últimos 7 días (porcentaje)

Libro de órdenes

import requests

market_id = 'btc-clp'
url = f'https://www.buda.com/api/v2/markets/{market_id}/order_book'
response = requests.get(url)
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
  "order_book": {
    "asks": [
      ["836677.14", "0.447349"],
      ["837462.23", "1.43804963"],
      ["837571.89", "1.41498541"],
      ["837597.23", "0.13177617"],
      ["837753.25", "1.40724154"],
      ["837858.51", "1.40988433"],
      ["837937.0", "1.46619702"],
      ["838000.57", "1.4527277"],
      ["838305.78", "0.8317892"],
      ...
    ],
    "bids": [
      ["821580.0", "0.25667389"],
      ["821211.0", "0.27827307"],
      ["819882.39", "1.40003128"],
      ["819622.99", "1.40668862"],
      ["819489.9", "1.41736995"],
      ["818942.2", "1.41001753"],
      ["818820.29", "0.93677863"],
      ["816879.83", "1.44022295"],
      ...
    ]
  }
}

Obtén el listado de todas las órdenes que se encuentran activas en el mercado seleccionado.

HTTP Request

GET /markets/<market_id>/order_book

Path Parameters

Parámetro Descripción
market_id El ID del mercado (Ej: eth-btc, btc-clp, etc).
Puedes obtener un listado completo de estos identificadores a través de la llamada al endpoint de Mercados

Response Details

Key Tipo Descripción
asks [price, amount] Arreglo de ordenes del libro de ventas
bids [price, amount] Arreglo de ordenes del libro de compras

Trades

import time
import requests

market_id = 'btc-clp'
url = f'https://www.buda.com/api/v2/markets/{market_id}/trades'
response = requests.get(url, params={
    'timestamp': int(time.time()) - 60 * 60 * 24 * 7,
    'limit': 50,
})
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
  "trades": {
    "timestamp": "1476905551698",
    "last_timestamp": "1476380738941",
    "market_id": "BTC-CLP",
    "entries": [
      ["1476905551687", "0.00984662", "435447.12", "buy"],
      ["1476905551676", "3.01572553", "435283.3", "buy"],
      ...
    ]
  }
}

Obtén el listado de las transacciones más recientes del mercado indicado.

HTTP Request

GET markets/<market_id>/trades

Path Parameters

Parámetro Descripción
market_id El ID del mercado (Ej: eth-btc, btc-clp, etc).
Puedes obtener un listado completo de estos identificadores a través de la llamada al endpoint de Mercados

URL Parameters

Se incluyen al final del URL ej: GET /markets/BTC-CLP/trades?timestamp=1502472564000

Parameter Descripción
timestamp (opcional) Unix timestamp en milisegundos del trade más reciente a solicitar.
limit (opcional) Número de trades solicitados [default: 50, max: 100]

Response Details

Key Tipo Descripción
entries [timestamp, amount, price, direction] Arreglo de transacciones
timestamp [timestamp] Unix timestamp del trade más reciente incluido en la respuesta
last_timestamp [timestamp] Unix timestamp del trade más antiguo incluido en la respuesta
market_id [currency] Identificador del mercado consultado

Cotizaciones

import requests

market = 'btc-clp'
url = f'https://www.buda.com/api/v2/markets/{market}/quotations'
response = requests.post(url, json={
    'type': 'bid_given_size',
    'amount': 1,
})
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
  "quotation": {
    "amount": ["1.0", "BTC"],
    "base_balance_change": ["0.99200003", "BTC"],
    "base_exchanged": ["1.0", "BTC"],
    "fee": ["0.00799997", "BTC"],
    "incomplete": false,
    "limit": null,
    "order_amount": ["1.0", "BTC"],
    "quote_balance_change": ["-4872696.01", "CLP"],
    "quote_exchanged": ["4872696.01", "CLP"],
    "type": "bid_given_size"
  }
}

Obtén una cotización de acuerdo al libro de órdenes del momento.

Los tipos de cotizaciones

Dependiendo del dato que quieras saber, este endpoint permite realizar distintos tipos de cotizaciones.

Considerando que los mercados están identificados por el par de monedas <base_currency>-<quote_currency> (a continuación usaremos como ejemplo el mercado eth-btc), a través de este endpoint puedes obtener simulaciones correspondiente a ejecuciones de órdenes de compra o venta de cierta cantidad (amount) de base_currency o quote_currency. (Si no tienes muy claro lo que es una orden de compra o venta puedes revisar la documentación de la sección Mis órdenes).

Para esto, es necesario seleccionar una de las siguientes opciones y enviarla como parámetro type en el payload.

Tipo simulación Descripción
bid_given_size ó bid_given_earned_base Simula una orden de compra donde amount representa la cantidad de base_currency a recibir (ej: ¿Cuánto btc se requiere para obtener amount eth?)
bid_given_value ó bid_given_spent_quote Simula una orden de compra donde amount representa la cantidad de quote_currency a gastar (ej: ¿Cuánto eth obtendré si ejecuto una orden de compra por amount btc?)
ask_given_size ó ask_given_spent_base Simula una orden de venta donde amount representa la cantidad de base_currency a gastar. (ej: ¿Cuánto btc recibiría si ejecuto una orden de venta por amount eth?)
ask_given_value ó ask_given_earned_quote Simula una orden de venta donde amount representa la cantidad de quote_currency a recibir (ej: ¿Cuánto eth se requiere para obtener amount btc?)

HTTP Request

POST '/markets/<market_id>/quotations

Path Parameters

Parámetro Descripción
market_id El ID del mercado (Ej: eth-btc, btc-clp, etc).
Puedes obtener un listado completo de estos identificadores a través de la llamada al endpoint de Mercados

Request Payload

Key Required Descripción
type Yes Tipo de cotización a realizar (ver siguiente tabla)
amount Yes Monto a simular (representa base_currency o quote_currency) dependiendo del parámetro type
limit No El precio pedido para la moneda en la cual se expresa el parámetro amount.

Response Details

Key Tipo Descripción
amount [amount, currency] Es el mismo valor del parámetro amount enviado como parte de la cotización
base_balance_change [amount, currency] Cuanto cambiaría tu saldo en la moneda base_currency (ya considerados los fees). Ten presente que este número puede ser positivo o negativo (tu saldo puede aumentar o disminuir después de la ejecución de una orden)
base_exchanged [amount, currency] El monto total de base_currency que se transaría en el mercado (siempre es un valor positivo)
fee [amount, currency] Tarifa que se cobraría por la ejcución de la orden.
incomplete [boolean] Indica si dadas las actuales condiciones del mercado (profundidad y tu saldo disponible) sólo sería posible ejecutar una porción de la orden.
limit [amount, currency] El parámetro limit enviado junto con la moneda correspondiente
order_amount [amount, currency] Corresponde al mismo valor que base_exchanged
quote_balance_change [amount, currency] Cuanto cambiaría tu saldo en la moneda quote_currency (ya considerados los fees). Ten presente que este número puede ser positivo o negativo (tu saldo puede aumentar o disminuir después de la ejecución de una orden)
quote_exchanged [amount, currency] El monto total de quote_currency que se transaría en el mercado (siempre es un valor positivo)
type [string] Tipo de cotización solicitada

Sobre el cálculo de las tarifas (fee)

Costos de abonos/retiros

import requests

currency = 'btc'
transaction_type = 'withdrawal'
url = f'https://www.buda.com/api/v2/currencies/{currency}/fees/{transaction_type}'
response = requests.get(url)
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
  "fee": {
    "name": "withdrawal",
    "percent": 0,
    "base": ["0.00000015", "BTC"]
  }
}

Entrega los costos asociados a realizar un abono o retiro en la moneda seleccionada.

Ten presente:

HTTP Request

GET /currencies/<currency>/fees/<transaction_type>

Path Parameters

Parameter Descripción
currency Acrónimo de la moneda a consultar
transaction_type Tipo de operación. Puede ser deposit (abono) o withdrawal (retiro)

Response Details (JSON)

Key Tipo Descripción
name [string] Tipo de operación consultada
percent [number] Porcentaje del monto total de la transacción que cobra la red por realizar la operación.
base [amount, currency] Costo fijo por transacción que cobra la red por realizar la operación.

Llamadas Privadas

Las llamadas privadas consisten en endpoints que acceden a información privada del usuario que las invocan, les permiten crear o cancelar órdenes o les permiten abonar o retirar dinero hacia o desde el exchange.

Es por esto que es necesario autenticarse a través de información adicional en base a tu API-KEY y una firma a partir de tu API-SECRET.

Autenticación

Ejemplo de autenticación con la librería Requests

import base64
import hmac
import time
import requests.auth

class BudaHMACAuth(requests.auth.AuthBase):
    """Adjunta la autenticación HMAC de Buda al objeto Request."""

    def __init__(self, api_key: str, secret: str):
        self.api_key = api_key
        self.secret = secret

    def get_nonce(self) -> str:
        # 1. Generar un nonce (timestamp en microsegundos)
        return str(int(time.time() * 1e6))

    def sign(self, r, nonce: str) -> str:
        # 2. Preparar string para firmar
        components = [r.method, r.path_url]
        if r.body:
            encoded_body = base64.b64encode(r.body).decode()
            components.append(encoded_body)
        components.append(nonce)
        msg = ' '.join(components)
        # 3. Obtener la firma
        h = hmac.new(key=self.secret.encode(),
                        msg=msg.encode(),
                        digestmod='sha384')
        signature = h.hexdigest()
        return signature

    def __call__(self, r):
        nonce = self.get_nonce()
        signature = self.sign(r, nonce)
        # 4. Adjuntar API-KEY, nonce y firma al header del request
        r.headers['X-SBTC-APIKEY'] = self.api_key
        r.headers['X-SBTC-NONCE'] = nonce
        r.headers['X-SBTC-SIGNATURE'] = signature
        return r

# Para autenticar una llamada se debe incluir `auth` en el request
request = requests.post(url, auth=BudaHMACAuth(api_key, secret))

Intentamos hacer una autenticación segura pero sencilla. Creo que nos quedó más segura que sencilla, pero no te preocupes que hay buenos ejemplos.

Lo primero que debes hacer es obtener un API-KEY para poder realizar llamados autenticados a la API. Para esto, basta que vayas a la sección "Mi cuenta" y generes un API-KEY y un API-SECRET.

Una vez que tengas tu API-KEY debes usarla para invocar las rutas privadas. Buda.com espera que todas sus llamadas privadas vayan firmadas, siguiendo las siguientes instrucciones:

1. Generar un nonce

El nonce debe ser un número entero que debe siempre cumplir con la condición de ser mayor al último nonce usado. Esto asegura que tus requests no puedan ser repetidos por un "Man in the middle". Una (buena) forma de lograr esto es usando un timestamp.

2. Preparar un string para firmar:

El contenido del string es así:

{GET|POST|PUT} {path} {base64_encoded_body} {nonce}

Donde:

Por ejemplo:

GET /api/v1/orders?open=true 423874932432

3. Obtener la firma

La firma corresponde a un mensaje de autenticación basado en hash (HMAC), que se genera usando la función de hash SHA-384 sobre el API-SECRET y el string generado en el punto anterior 😱. Esta firma debe ir codificada en formato hexadecimal.

No te preocupes, generalmente los lenguajes de programación incorporan funciones para generar HMACs dentro de sus bibliotecas estándar (como sale en el ejemplo acá a la derecha -->)

4. Adjuntar API-KEY, nonce y firma en el header del request

Por ejemplo:

Header Value
X-SBTC-APIKEY 0faea2f360a508a6d105a3bb60247af0
X-SBTC-NONCE 145511231131231
X-SBTC-SIGNATURE 5c873eddb1117b930b1caa058ada3f7...

Paginación

Ejemplo de respuesta de una llamada que usa paginación

{
  "orders": [
    {
      "id": 1,
      "type": "Ask",
      "state": "traded",
      "created_at": "2017-03-10T21:11:42.131Z",
      "market_id": "BTC-CLP",
      "account_id": 5,
      "fee_currency": "CLP",
      "price_type": "limit",
      "limit": ["700000.0", "CLP"],
      "amount": ["0.0", "BTC"],
      "original_amount": ["5.0", "BTC"],
      "traded_amount": ["5.0", "BTC"],
      "total_exchanged": ["3625000.0", "CLP"],
      "paid_fee": ["19937.5", "CLP"]
    },
    ...
  ],
  "meta": {
    "total_pages": 3,
    "total_count": 50,
    "current_page": 1
  }
}

Algunas llamadas pueden devolver una gran cantidad de datos, de manera que devolvemos sólo un conjunto de ellos por cada request para no sobrecargar nuestro servidor ni hacer muy larga la transferencia de datos. Por esto, en estos endpoints usamos paginación para devolver sólo un conjunto de ellos en cada request.

Todos los endpoints que utilizan paginación aceptan los siguientes query parameters:

Query Parameters

Parameter Default Descripción
per 20 Número de elementos por página [min: 1, max: 300]
page 1 Número de página a recibir. La primera página es la página 1

Response Details (JSON)

Estos endpoints siempre devolverán, además de los elementos solicitados, un objeto meta dentro de la respuesta, cuya estructura es la siguiente:

Key Tipo Descripción
total_pages [int] Cantidad total de páginas que ocupan los elementos que representan la respuesta
total_count [int] Cantidad total de elementos que representan la respuesta.
current_page [int] Número de la página que representan los elementos entregados en la actual respuesta.

Información personal

import requests
url = f'https://www.buda.com/api/v2/me'
auth = BudaHMACAuth(api_key, secret)
response = requests.get(url, auth=auth)
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
  "user": {
    "id": "current",
    "email": "[email protected]",
    "category": "personal",
    "display_name": "Satoshi Nakamoto",
    "account_data": {
      "names": "Satoshi",
      "surnames": "Nakamoto",
      "nationality": "CL",
      "document_type": "Documento Nacional de Identidad",
      "document_number": "209999999",
      "birth_date": "2008-10-31",
      "profession": "Economista",
      "residence_address": "Unknown",
    },
    "tags": [
      "basic", "trader", "business"
    ],
    "monthly_transacted": [
      "57157.95",
      "USD"
    ],
    "pubsub_key": "xxxx-xxxx-xxxx-xxxx",
  }
}

Muestra la información personal de tu cuenta.

HTTP Request

GET /me

Response Details (JSON)

Key Tipo Descripción
id [string] Identificador de la cuenta
email [string] Correo asociado a la cuenta
display_name [string] Nombre completo asociado a la cuenta
monthly_transacted [amount, currency] Cantidad transada en los últimos 30 días
pubsub_key [string] Llave para autentificación con websockets

Balances

import requests

url = f'https://www.buda.com/api/v2/balances'
auth = BudaHMACAuth(api_key, secret)
response = requests.get(url, auth=auth)
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
  "balances": [
    {
      "id": "BTC",
      "amount": ["11.5274815", "BTC"],
      "available_amount": ["10.5274815", "BTC"],
      "frozen_amount": ["1.0", "BTC"],
      "pending_withdraw_amount": ["0.0", "BTC"]
    },
    {
      "id": "CLP",
      "amount": ["7349002.46", "CLP"],
      "available_amount": ["7349002.46", "CLP"],
      "frozen_amount": ["0.0", "CLP"],
      "pending_withdraw_amount": ["0.0", "CLP"]
    },
    ...
  ]
}

Ejemplo para una moneda:

import requests

currency = 'btc'
url = f'https://www.buda.com/api/v2/balances/{currency}'
auth = BudaHMACAuth(api_key, secret)
response = requests.get(url, auth=auth)
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
  "balance": {
    "id": "BTC",
    "amount": ["11.5274815", "BTC"],
    "available_amount": ["10.5274815", "BTC"],
    "frozen_amount": ["1.0", "BTC"],
    "pending_withdraw_amount": ["0.0", "BTC"]
  }
}

Muestra los balances de tu cuenta, en cada moneda.

HTTP Request

GET /balances

GET /balances/<currency>

Path Parameters

Parameter Descripción
currency (opcional) - El acrónimo de la moneda: btc, eth, clp,...

Response Details (JSON)

Key Tipo Descripción
id [currency] Identificador de la moneda
amount [amount, currency] Cantidad total asociada a la cuenta
available_amount [amount, currency] Cantidad disponible para crear nuevas órdenes o retiros
frozen_amount [amount, currency] Cantidad retenida en órdenes pendientes
pending_withdrawal_amount [amount, currency] Cantidad retenida en proceso de retiro

Obtener mis órdenes

Ejemplo:

import requests

market_id = 'btc-clp'
url = f'https://www.buda.com/api/v2/markets/{market_id}/orders'
auth = BudaHMACAuth(api_key, secret)
response = requests.get(url, auth=auth, params={
    'state': 'traded',
    'per': 20,
    'page': 1,
})
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
  "orders": [
    {
      "id": 1,
      "type": "Bid",
      "state": "traded",
      "created_at": "2017-06-30T02:14:45.368Z",
      "market_id": "BTC-CLP",
      "fee_currency": "BTC",
      "price_type": "limit",
      "client_id": None,
      "order_type": "gtc",
      "limit": ["1728000.0", "CLP"],
      "amount": ["0.001", "BTC"],
      "original_amount": ["0.001", "BTC"],
      "traded_amount": ["0.0", "BTC"],
      "total_exchanged": ["0.0", "CLP"],
      "paid_fee": ["0.0", "BTC"]
    },
    {
      "id": 2,
      "type": "Ask",
      "state": "traded",
      "created_at": "2017-03-10T21:11:42.131Z",
      "market_id": "BTC-CLP",
      "fee_currency": "CLP",
      "price_type": "limit",
      "client_id": None,
      "order_type": "ioc",
      "limit": ["700000.0", "CLP"],
      "amount": ["0.0", "BTC"],
      "original_amount": ["5.0", "BTC"],
      "traded_amount": ["5.0", "BTC"],
      "total_exchanged": ["3625000.0", "CLP"],
      "paid_fee": ["19937.5", "CLP"]
    },
    ...
  ],
  "meta": {
    "current_page": 1,
    "total_count": 50,
    "total_pages": 3
  }
}

La orden es el núcleo del Exchange. Una orden es una oferta de compra o de venta (según el type) por un cierto monto (amount) de la moneda base del mercado (típicamente la criptomoneda) a precio mercado o límite.

Órdenes mercado

Si la orden es de tipo "mercado" (es decir, price_type = market), se intentará comprar o vender al mejor precio disponible en el mercado (revisando las órdenes límite en el sentido contrario que existan en ese momento).

Órdenes límite

Si la orden es de tipo "límite" (es decir, price_type = limit) debe enviarse el precio al que se colocará la orden, que será el precio al que se desee comprar o vender.

La ejecución de la orden es programada para ser ejecutada inmediatamente luego de su creación, aunque el proceso ocurre asíncronamente, pues entra en una cola en orden de llegada. Es importante notar que una orden de tipo límite podría quedar parcialmente comprada/vendida, pues su límite puede traslaparse con algunas ofertas contrarias, o una orden de mercado más pequeña podría consumirla parcialmente.

Si quieres consultar por varios estados puedes construir el parámetro del payload state de la siguente manera: state=state1,state2,state3.

Tipos de Órdenes Limit

Good-Till-Cancelled (gtc): Una orden limite que se mantendrá vigente hasta que se complete o se cancele.

Immediate-Or-Cancel (ioc): Una orden que debe ser ejecutada de inmediato. Todo lo que no se ejecute de manera inmediata será cancelado.

Fill-Or-Kill (fok): Una orden que debe ser ejecutada de inmediato y por completo. Si no se ejecuta por completo de manera inmediata, será cancelada.

Post Only (post_only): Una orden que debe ser ejecutada como Limit/Maker. Si al ingresar la orden alguna parte se ejecutaría como Market/Taker, no se ingresa al libro y será cancelada.

Good-Till-Date (gtd): Una orden límite que permanecerá activa hasta que se complete o se alcance la fecha de expiración.

Órdenes Stop

Las órdenes Stop están diseñadas para ejecutarse automáticamente cuando el precio del mercado alcanza el precio de activación establecido (Precio Stop). Hay dos tipos principales: Stop Market y Stop Limit.

Después, debes elegir si esta orden será de tipo Stop Loss o Take Profit. Esto dependerá del Type y Precio Stop que elijas en relación al último precio de mercado.

Por ejemplo, si elijes una Stop Loss de tipo Bid, con un Precio Stop superior al Last Price, entonces la orden permanecerá esperando a ser activada con un cambio de precio. En cambio, si el precio es inferior al Last Price, esta se activará de inmediato, ya que se cumplió la condición de que el Last Price sea mayor al Precio Stop.

En este último caso, si se quiere que la orden quedé esperando a ser activada por una bajada del precio, esta orden debe ser una Take Profit.

Si quieres que la orden stop quede esperando el Stop Price, sin ser activada de inmediato, puedes usar esta tabla de referencia:

Type Stop Type Stop Price
bid Stop Loss > Last Price
ask Stop Loss < Last Price
bid Take Profit < Last Price
ask Take Profit > Last Price

Nueva Orden

import requests

market_id = 'btc-clp'
url = f'https://www.buda.com/api/v2/markets/{market_id}/orders'
auth = BudaHMACAuth(api_key, secret)
response = requests.post(url, auth=auth, json={
    'type': 'Bid',
    'price_type': 'limit',
    'limit': {'price':1000000, 'type':'gtc'},
    'amount': 0.05,
    'client_id': 'my-order-1'
})
print(response.json())

# Stop Order Market

market_id = 'btc-clp'
url = f'https://www.buda.com/api/v2/markets/{market_id}/orders'
auth = BudaHMACAuth(api_key, secret)
response = requests.post(url, auth=auth, json={
    'type': 'Bid',
    'price_type': 'market',
    'stop': {'stop_price':100000, 'type':'stop_loss'},
    'amount': 0.05,
    'client_id': 'my-order-1'
})
print(response.json())

# Stop Order Limit

market_id = 'btc-clp'
url = f'https://www.buda.com/api/v2/markets/{market_id}/orders'
auth = BudaHMACAuth(api_key, secret)
response = requests.post(url, auth=auth, json={
    'type': 'Bid',
    'price_type': 'limit',
    'limit': {'price':900000, 'type':None},
    'stop': {'stop_price':100000, 'type':'take_profit'},
    'amount': 0.05,
    'client_id': 'my-order-1'
})
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
  "order": {
    "id": 2,
    "amount": ["0.05", "BTC"],
    "created_at": "2017-04-18T19:54:24.611Z",
    "fee_currency": "BTC",
    "client_id": "my-order-1",
    "order_type": "gtc",
    "limit": ["1000000.0", "CLP"],
    "market_id": "BTC-CLP",
    "original_amount": ["0.05", "BTC"],
    "paid_fee": ["0.0", "BTC"],
    "price_type": "limit",
    "state": "received",
    "total_exchanged": ["0.0", "CLP"],
    "traded_amount": ["0.0", "BTC"],
    "type": "Bid"
  }
}

Crea una nueva orden

HTTP Request

POST /markets/<market_id>/orders

Path Parameters

Parameter Descripción
market_id El ID del mercado (Ej: btc-eth, btc-clp)

Request Payload

Key Required Descripción
type Yes Dirección de la orden (Bid / Ask)
price_type Yes Tipo de orden (limit / market)
limit:price Limit Precio de la orden
limit:type Limit Tipo de orden Limit (gtc / ioc / fok / post_only/ gtd) (más detalles)
stop:stop_price Stop Precio stop del orden
stop:type Stop Tipo de orden Stop (stop_loss / take_profit)
amount Yes Volumen de la orden
client_id No ID único que puedes asignar a una orden. Se rechazará la orden si ya fue utilizado por ti anteriormente.

* Si en limit entregas solo un precio, entonces se tomará como una orden limit gtc.

Response Details (JSON)

Key Tipo Descripción
amount [amount, currency] Volumen pendiente de la orden
created_at [string] Fecha de creación de la orden
fee_currency [currency] Moneda en la cual es cobrada la tarifa (Ej: "BTC", "CLP" ,"COP")
id [int] ID de la orden
client_id [string] Client ID de la orden
limit [amount, currency] Precio de la orden
market_id [string] Identificador del mercado
original_amount [amount, currency] Volumen original de la orden
paid_fee [amount, currency] Tarifa pagada por la orden
price_type [string] Tipo de orden (limit / market)
order_type [string] Tipo de orden específico (market / gtc / ioc / fok / post_only)
state [string] Estado de la orden
total_exchanged [amount, currency] Total transado por la orden
traded_amount [amount, currency] Volumen transado de la orden
type [string] Dirección de la orden (Bid / Ask)

Estados de una orden

Durante el ciclo de vida de una orden, ésta puede pasar por varios estados:

Estado Descripción
received La orden ha sido recibida pero no ha ocurrido ningún procesamiento aún.
pending El monto máximo que la orden puede costar deja de estar disponible para futuras órdenes. A partir de este momento la orden puede hacer match con otras.
active La orden tiene estado received o pending.
traded La orden ha terminado de transarse por completo.
canceled La orden fue cancelada y el monto no transado está nuevamente disponible.
canceled_and_traded La orden fue cancelada pero esta fue transada parcialmente.
unprepared No hay fondos suficientes para procesar la orden (solo ordenes límite).

HTTP Request

GET /markets/<market_id>/orders

Path Parameters

Parameter Descripción
market_id El ID del mercado (Ej: btc-clp, eth-btc, ...)

Query Parameters

Parameter Default Descripción
state None Recuperar sólo ordenes con estado state

Response Details (JSON)

Key Tipo Descripción
amount [amount, currency] Volumen pendiente de la orden
created_at [string] Fecha de creación de la orden
fee_currency [currency] Moneda en la cual es cobrada la tarifa (Ej: "BTC", "CLP" ,"COP")
id [int] ID de la orden
limit [amount, currency] Precio de la orden
market_id [string] Identificador del mercado
original_amount [amount, currency] Volumen original de la orden
paid_fee [amount, currency] Tarifa pagada por la orden
price_type [string] Tipo de orden (limit / market)
state [string] Estado de la orden
total_exchanged [amount, currency] Total transado por la orden
traded_amount [amount, currency] Volumen transado de la orden
type [string] Dirección de la orden (Bid / Ask)

Detalle de Orden

Ejemplo:

import requests

order_id = 1
url = f'https://www.buda.com/api/v2/orders/{order_id}'
auth = BudaHMACAuth(api_key, secret)
response = requests.get(url, auth=auth)
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
  "order": {
    "id": 2,
    "amount": ["0.05", "BTC"],
    "created_at": "2017-04-18T19:54:24.611Z",
    "fee_currency": "BTC",
    "client_id": "my-order-1",
    "order_type": "gtc",
    "limit": ["1000000.0", "CLP"],
    "market_id": "BTC-CLP",
    "original_amount": ["0.05", "BTC"],
    "paid_fee": ["0.0", "BTC"],
    "price_type": "limit",
    "state": "received",
    "total_exchanged": ["0.0", "CLP"],
    "traded_amount": ["0.0", "BTC"],
    "type": "Bid"
  }
}

Permite ver los detalles de una orden

HTTP Request

GET /orders/<id>

Path Parameters

Parameter Descripción
id El ID de la orden a consultar

Response Details (JSON)

Key Tipo Descripción
amount [amount, currency] Volumen pendiente de la orden
created_at [string] Fecha de creación de la orden
fee_currency [currency] Moneda en la cual es cobrada la tarifa (Ej: "BTC", "CLP" ,"COP")
id [int] ID de la orden
client_id [string] Client ID de la orden
limit [amount, currency] Precio de la orden
market_id [string] Identificador del mercado
original_amount [amount, currency] Volumen original de la orden
paid_fee [amount, currency] Tarifa pagada por la orden
price_type [string] Tipo de orden (limit / market)
order_type [string] Tipo de orden específico (market / gtc / ioc / fok / post_only)
state [string] Estado de la orden
total_exchanged [amount, currency] Total transado por la orden
traded_amount [amount, currency] Volumen transado de la orden
type [string] Dirección de la orden (Bid / Ask)

Cancelar Orden

import requests

order_id = 2
url = f'https://www.buda.com/api/v2/orders/{order_id}'
auth = BudaHMACAuth(api_key, secret)
response = requests.put(url, auth=auth, json={
    'state': 'canceling',
})
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
  "order": {
    "id": 2,
    "amount": ["0.05", "BTC"],
    "created_at": "2017-04-18T19:54:24.611Z",
    "fee_currency": "BTC",
    "client_id": "my-order-1",
    "order_type": "gtc",
    "limit": ["1000000.0", "CLP"],
    "market_id": "BTC-CLP",
    "original_amount": ["0.05", "BTC"],
    "paid_fee": ["0.0", "BTC"],
    "price_type": "limit",
    "state": "canceled",
    "total_exchanged": ["0.0", "CLP"],
    "traded_amount": ["0.0", "BTC"],
    "type": "Bid"
  }
}

Permite comenzar la cancelación de una orden, si la llamada responde correctamente, está garantizado que la orden ha sido ingresada para ser cancelada, el estado puede demorar en cambiar dependiendo de la carga del motor de trading.

HTTP Request

PUT /orders/<id>

Path Parameters

Parameter Descripción
id El ID de la orden a cancelar

Request Payload

Key Required Descripción
state Yes Debe indicar "canceling"

Response Details (JSON)

Key Tipo Descripción
amount [amount, currency] Volumen pendiente de la orden
created_at [string] Fecha de creación de la orden
fee_currency [currency] Moneda en la cual es cobrada la tarifa (Ej: "BTC", "CLP" ,"COP")
id [int] ID de la orden
limit [amount, currency] Precio de la orden
market_id [string] Identificador del mercado
original_amount [amount, currency] Volumen original de la orden
paid_fee [amount, currency] Tarifa pagada por la orden
price_type [string] Tipo de orden (limit / market)
state [string] Estado de la orden
total_exchanged [amount, currency] Total transado por la orden
traded_amount [amount, currency] Volumen transado de la orden
type [string] Dirección de la orden (Bid / Ask)

Detalle de Orden por Client ID

Ejemplo:

import requests

client_id = "my_client_id"
url = f'https://www.buda.com/api/v2/orders/by-client-id/{client_id}'
auth = BudaHMACAuth(api_key, secret)
response = requests.get(url, auth=auth)
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
  "order": {
    "id": 1,
    "type": "Bid",
    "state": "traded",
    "created_at": "2017-06-30T02:14:45.368Z",
    "market_id": "BTC-CLP",
    "fee_currency": "BTC",
    "price_type": "limit",
    "client_id": "my_client_id",
    "limit": ["1728000.0", "CLP"],
    "amount": ["0.001", "BTC"],
    "original_amount": ["0.001", "BTC"],
    "traded_amount": ["0.0", "BTC"],
    "total_exchanged": ["0.0", "CLP"],
    "paid_fee": ["0.0", "BTC"]
  }
}

Permite ver los detalles de una orden por medio de su client_id

HTTP Request

GET /orders/by-client-id/<client_id>

Path Parameters

Parameter Descripción
client_id El Client ID de la orden a consultar

Response Details (JSON)

Key Tipo Descripción
amount [amount, currency] Volumen pendiente de la orden
created_at [string] Fecha de creación de la orden
fee_currency [currency] Moneda en la cual es cobrada la tarifa (Ej: "BTC", "CLP" ,"COP")
id [int] ID de la orden
client_id [string] Client ID de la orden
limit [amount, currency] Precio de la orden
market_id [string] Identificador del mercado
original_amount [amount, currency] Volumen original de la orden
paid_fee [amount, currency] Tarifa pagada por la orden
price_type [string] Tipo de orden (limit / market)
state [string] Estado de la orden
total_exchanged [amount, currency] Total transado por la orden
traded_amount [amount, currency] Volumen transado de la orden
type [string] Dirección de la orden (Bid / Ask)

Cancelar Orden por Client ID

import requests

client_id = 'my_client_id'
url = f'https://www.buda.com/api/v2/orders/by-client-id/{client_id}'
auth = BudaHMACAuth(api_key, secret)
response = requests.put(url, auth=auth, json={
    'state': 'canceling',
})
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
  "order": {
    "id": 2,
    "amount": ["0.05", "BTC"],
    "created_at": "2017-04-18T19:54:24.611Z",
    "fee_currency": "BTC",
    "client_id": "my_client_id",
    "limit": ["1000000.0", "CLP"],
    "market_id": "BTC-CLP",
    "original_amount": ["0.05", "BTC"],
    "paid_fee": ["0.0", "BTC"],
    "price_type": "limit",
    "state": "canceled",
    "total_exchanged": ["0.0", "CLP"],
    "traded_amount": ["0.0", "BTC"],
    "type": "Bid"
  }
}

Permite comenzar la cancelación de una orden por medio de su client_id, si la llamada responde correctamente, está garantizado que la orden ha sido ingresada para ser cancelada, el estado puede demorar en cambiar dependiendo de la carga del motor de trading.

HTTP Request

PUT /orders/by-client-id/<client_id>

Path Parameters

Parameter Descripción
client_id El Client ID de la orden a cancelar

Request Payload

Key Required Descripción
state Yes Debe indicar "canceling"

Response Details (JSON)

Key Tipo Descripción
amount [amount, currency] Volumen pendiente de la orden
created_at [string] Fecha de creación de la orden
fee_currency [currency] Moneda en la cual es cobrada la tarifa (Ej: "BTC", "CLP" ,"COP")
id [int] ID de la orden
client_id [string] Client ID de la orden
limit [amount, currency] Precio de la orden
market_id [string] Identificador del mercado
original_amount [amount, currency] Volumen original de la orden
paid_fee [amount, currency] Tarifa pagada por la orden
price_type [string] Tipo de orden (limit / market)
state [string] Estado de la orden
total_exchanged [amount, currency] Total transado por la orden
traded_amount [amount, currency] Volumen transado de la orden
type [string] Dirección de la orden (Bid / Ask)

Cancelar Todas Mis Órdenes

import requests

url = f'http://www.buda.com/api/v2/orders'
auth = BudaHMACAuth(api_key, secret)
response = requests.delete(url, auth=auth, params={ 
    'market':'btc-clp',
    'type': 'Bid'
})
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
  "orders": [{
    "id": 2,
    "amount": ["0.05", "BTC"],
    "created_at": "2017-04-18T19:54:24.611Z",
    "fee_currency": "BTC",
    "client_id": None,
    "limit": ["1000000.0", "CLP"],
    "market_id": "BTC-CLP",
    "original_amount": ["0.05", "BTC"],
    "paid_fee": ["0.0", "BTC"],
    "price_type": "limit",
    "state": "canceled",
    "total_exchanged": ["0.0", "CLP"],
    "traded_amount": ["0.0", "BTC"],
    "type": "Bid"
  },
  {"id": 3,
  ...
  }]
}

Permite comenzar la cancelación de todas las órdenes abiertas. Se puede especificar el o los mercados a cancelar, junto con poder elegir un lado del libro. Si la llamada responde correctamente, está garantizado que las órdenes han sido ingresadas para ser canceladas, el estado puede demorar en cambiar dependiendo de la carga del motor de trading.

Si no se especifica market y/o type, entonces se considerará todos los mercados y/o lados del libro. Este endpoint cuenta como una sola operación con respecto al rate limit de trading, sin importar la cantidad de cancelaciones.

HTTP Request

DELETE /orders

Request Payload

Key Required Descripción
market No ID del mercado a cancelar (Ej: btc-clp, btc-eth, btc-clp,btc-eth)
type No Lado del libro a cancelar (Puede ser Bid o Ask)

Response Details (JSON)

Key Tipo Descripción
amount [amount, currency] Volumen pendiente de la orden
created_at [string] Fecha de creación de la orden
fee_currency [currency] Moneda en la cual es cobrada la tarifa (Ej: "BTC", "CLP" ,"COP")
id [int] ID de la orden
client_id [string] Client ID de la orden
limit [amount, currency] Precio de la orden
market_id [string] Identificador del mercado
original_amount [amount, currency] Volumen original de la orden
paid_fee [amount, currency] Tarifa pagada por la orden
price_type [string] Tipo de orden (limit / market)
state [string] Estado de la orden
total_exchanged [amount, currency] Total transado por la orden
traded_amount [amount, currency] Volumen transado de la orden
type [string] Dirección de la orden (Bid / Ask)

Lote de Ordenes

import requests

url = f'https://www.buda.com/api/v2/orders'
auth = BudaHMACAuth(api_key, secret)
response = requests.post(url, auth=auth, json={
    'diff': [{'mode': 'cancel', 'order_id': 1000},
             {'mode': 'cancel', 'order_id': 1003},
             {'mode': 'cancel', 'client_id': 9999},
             {'mode': 'place', 'order': {'amount': 1.5,
                                         'limit': 3500000.0,
                                         'market_name': 'btc-clp',
                                         'price_type': 'limit',
                                         'type': 'Ask',
                                         'client_id': 'my_client_id'}},
             {'mode': 'place', 'order': {'amount': 10.5,
                                         'market_name': 'eth-clp',
                                         'price_type': 'market',
                                         'type': 'Bid'}}]
})
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
  "success": true
}

Crea y/o cancela órdenes por lotes

HTTP Request

POST /orders

Request Payload

Key Required Descripción
mode Yes Tipo de acción de la orden (place / cancel)
type Yes Dirección de la orden (Bid / Ask)
price_type Yes Tipo de orden (limit / market)
limit Limit Precio de la orden
amount Yes Volumen de la orden
market_name Yes La ID del mercado (Ej: btc-clp, eth-btc, etc)

Response Details (JSON)

Key Tipo Descripción
success [bool] true cuando el lote de operaciones fue ejecutado con éxito

Mis Abonos/Retiros

Ejemplo de abonos:

import requests

currency = 'btc'
url = f'https://www.buda.com/api/v2/currencies/{currency}/deposits'
auth = BudaHMACAuth(api_key, secret)
response = requests.get(url, auth=auth, params={
    'state': 'confirmed',
    'per': 20,
    'page': 1,
})
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
  "deposits": [
    {
      "id": "PnPbY",
      "created_at": "2017-06-09T02:05:24.374Z",
      "amount": ["0.4", "BTC"],
      "currency": "BTC",
      "fee": ["0.0", "BTC"],
      "state": "confirmed",
      "deposit_data": {
        "type": "btc_deposit_data",
        "address": "mo366JJaDU5B1hmnPygyjQVMbUKnBC7DsY",
        "tx_hash":
          "51eaf04f9dbbc1417dc97e789edd0c37ecda88bac490434e367ea81b71b7b015"
      }
    },
    ...
  ],
  "meta": {
    "current_page": 1,
    "total_count": 50,
    "total_pages": 3
  }
}

Ejemplo de retiros:

import requests

currency = 'btc'
url = f'https://www.buda.com/api/v2/currencies/{currency}/withdrawals'
auth = BudaHMACAuth(api_key, secret)
response = requests.get(url, auth=auth, params={
    'state': 'confirmed',
    'per': 20,
    'page': 1,
})
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
  "withdrawals": [
    {
      "id": 1,
      "created_at": "2017-11-11T17:17:57.845Z",
      "state": "confirmed",
      "amount": ["0.35", "BTC"],
      "fee": ["0.00001", "BTC"],
      "currency": "BTC",
      "withdrawal_data": {
        "type": "btc_withdrawal_data",
        "target_address": "mo366JJaDU5B1hmnPygyjQVMbUKnBC7DsY",
        "tx_hash":
          "51eaf04f9dbbc1417dc97e789edd0c37ecda88bac490434e367ea81b71b7b015"
      }
    },
    ...
  ],
  "meta": {
    "current_page": 1,
    "total_count": 50,
    "total_pages": 3
  }
}

Permite consultar el historial de abonos y retiros (fiat y cripto)

Los posibles estados de un abono o retiro (descrito en el atributo state), son:

State Descripción
pending_confirmation El abono no ha sido confirmado
confirmed El abono fué aceptado y el monto abonado
rejected El abono fué rechazado
retained El abono ha sido retenido, posiblemente por alguna violación a los términos del servicio

HTTP Request

GET /currencies/<currency>/deposits

GET /currencies/<currency>/withdrawals

Path Parameters

Parameter Descripción
currency Acrónimo de la moneda a consultar

Query Parameters

Parameter Default Descripción
state None Recuperar sólo abonos/retiros con estado state

Response Details (JSON)

Key Tipo Descripción
id [string] Hash ID del abono/retiro
created_at [time] Fecha de creación de la solicitud
amount [amount, currency] Cantidad asociada al abono/retiro
currency [currency] Moneda asociada al abono/retiro
fee [amount, currency] Tarifa asociada a la ejecución del abono/retiro
state [string] Estado de la solicitud (Ej: confirmed, rejected)
deposit_data / withdrawal_data [object] Objeto con detalles del abono/retiro
type [string] Tipo de data entregada (Ej: btc_deposit_data,fiat_withdrawal_data)
address [address] Dirección del abono
target_address [address] Dirección de destino del retiro
tx_hash [string] ID de la transacción

Nuevo Abono Fiat

import requests

currency = 'clp'
url = f'https://www.buda.com/api/v2/currencies/{currency}/deposits'
auth = BudaHMACAuth(api_key, secret)
response = requests.post(url, auth=auth, json={
    'simulate': True,
    'amount': 25000,
})
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
  "deposit": {
    "id": null,
    "amount": ["250000.0", "CLP"],
    "created_at": "2018-07-18T03:24:08.121Z",
    "currency": "CLP",
    "deposit_data": {
      "created_at": "2018-07-18T03:24:08.106Z",
      "type": "fiat_deposit_data",
      "updated_at": "2018-07-18T03:24:08.106Z",
      "upload_url": null
    },
    "fee": ["0.0", "CLP"],
    "state": "pending_confirmation"
  }
}

Genera una nueva solicitud de abono

El proceso de abono de un monto en Fiat tiene 2 etapas:

  1. Realizar la transferencia bancaria.
  2. Generar una nueva solicitud de abono por el monto de la transferencia anterior utilizando este endpoint.

HTTP Request

POST /currencies/<currency>/deposits

URL Parameters

Parameter Descripción
currency Acrónimo de la moneda a abonar

Request Payload

Key Required Descripción
amount Yes Volumen del abono
simulate No Permite simular la solicitud de abono

Response Details (JSON)

Key Tipo Descripción
id [string] Hash ID del abono/retiro
created_at [time] Fecha de creación de la solicitud
amount [amount, currency] Cantidad asociada al abono
currency [currency] Moneda asociada al abono
fee [amount, currency] Tarifa asociada a la ejecución del abono/retiro
state [string] Estado de la solicitud (Ej: "confirmed", "rejected")
deposit_data [array] Arreglo con detalles depentientes del tipo de consulta

Nuevo Retiro Fiat

import requests

currency = 'clp'
url = f'https://www.buda.com/api/v2/currencies/{currency}/withdrawals'
auth = BudaHMACAuth(api_key, secret)
response = requests.post(url, auth=auth, json={
    'amount': 100000,
    'simulate': True,
    },
})
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
  "withdrawal": {
    "id": null,
    "uuid": null,
    "state": "simulated",
    "currency": "CLP",
    "created_at": "2017-04-26T13:47:42.000Z",
    "amount": ["10000.0", "CLP"],
    "fee": ["0.0", "CLP"],
    "withdrawal_data": {
      "type": "fiat_withdrawal_data",
      "fiat_account": {},
      "expected_arrival_time": "2022-08-25T18:00:00.000Z",
    }
  }
}

Genera una solicitud de retiro para el monto y moneda seleccionada hacía la cuenta FIAT más recientemente agregada.

HTTP Request

POST /currencies/<currency>/withdrawals

Path Parameters

Parámetro Descripción
currency Acrónimo de la moneda a retirar (ARS, CLP, COP, PEN)

Request Payload

Key Required Descripción
amount Yes Volumen del retiro
simulate No Permite simular la solicitud de retiro

Response Details (JSON)

Key Tipo Descripción
id [int] ID del retiro
created_at [time] Fecha de creación de la solicitud
amount [amount, currency] Cantidad asociada al retiro
currency [currency] Moneda asociada al retiro
fee [amount, currency] Tarifa asociada a la ejecución del retiro
state [string] Estado de la solicitud (Ej: confirmed, rejected)
withdrawal_data [object] Objeto con detalles del retiro
withdrawal_data: type [string] Tipo de data entregada (Ej: btc_withdrawal_data,fiat_withdrawal_data)

Nuevo Abono Cripto

import time
import requests

currency = 'btc'
auth = BudaHMACAuth(api_key, secret)

# Crear un nuevo address y obtener el Id
url = f'https://www.buda.com/api/v2/currencies/{currency}/receive_addresses'
response = requests.post(url, auth=auth)
address_id = response.json()['receive_address']['id']

# Esperar que el nuevo address este listo
time.sleep(3)

# Obtener el nuevo address
url = f'https://www.buda.com/api/v2/currencies/{currency}/receive_addresses/{address_id}'
response = requests.get(url, auth=auth)
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
  "receive_address": {
    "id": 1,
    "created_at": "2017-04-26T13:47:42.000Z",
    "address": "mo366JJaDU5B1hmnPygyjQVMbUKnBC7DsY",
    "ready": true,
    "used": false
  }
}

Genera nuevas direcciones (cripto) para abonar criptomonedas a Buda.com.

Ten presente que la creación de direcciones es un proceso asíncrono. Por lo tanto, primero se debe solicitar un abono y luego consultar la dirección cripto a la cual realizar el abono, usando el id de solicitud obtenido en el paso anterior.

HTTP Request

Request Descripción
POST /currencies/<currency>/receive_addresses Solicitar una nueva dirección cripto para realizar un abono.
GET /currencies/<currency>/receive_addresses/<id> Permite consultar la dirección cripto correspondiente al id obtenido en el endpoint anterior.
GET /currencies/<currency>/receive_addresses Entrega un listado con todas las direcciones cripto asociadas a la cuenta (usa paginación).

URL Parameters

Parameter Descripción
currency Acrónimo de la criptomoneda a abonar
id ID de la dirección asociada

Response Details (JSON)

Key Tipo Descripción
id [int] ID de la dirección asociada
created_at [time] Fecha de creación
address [address] Dirección asignada para abonar
ready [bool] Determina si la address esta lista para ser utilizada
used [bool] Determina si la address fue usada con anterioridad

Nuevo Retiro Cripto

import requests

currency = 'btc'
url = f'https://www.buda.com/api/v2/currencies/{currency}/withdrawals'
auth = BudaHMACAuth(api_key, secret)
response = requests.post(url, auth=auth, json={
    'amount': 0.05,
    'simulate': True,
    'amount_includes_fee': True,
    'withdrawal_data': {
        'target_address': 'mo366JJaDU5B1hmnPygyjQVMbUKnBC7DsY',
    },
})
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
  "withdrawal": {
    "id": null,
    "amount": ["0.05", "BTC"],
    "created_at": "2017-04-26T13:47:42.000Z",
    "currency": "BTC",
    "fee": ["0.0", "BTC"],
    "state": "simulated",
    "withdrawal_data": {
      "target_address": "mo366JJaDU5B1hmnPygyjQVMbUKnBC7DsY",
      "tx_hash": null,
      "type": "btc_withdrawal_data"
    }
  }
}

Genera una solicitud de retiro para el monto y moneda seleccionada.

HTTP Request

POST /currencies/<currency>/withdrawals

Path Parameters

Parameter Descripción
currency Acrónimo de la moneda a retirar

Request Payload

Key Required Descripción
amount Yes Volumen del retiro
withdrawal_data: target_address Yes Dirección asignada al retiro
amount_includes_fee No Determina si el fee debería descontarse del amount del retiro
simulate No Permite simular la solicitud de retiro

Response Details (JSON)

Key Tipo Descripción
id [int] ID del retiro
created_at [time] Fecha de creación de la solicitud
amount [amount, currency] Cantidad asociada al retiro
currency [currency] Moneda asociada al retiro
fee [amount, currency] Tarifa asociada a la ejecución del retiro
state [string] Estado de la solicitud (Ej: confirmed, rejected)
withdrawal_data [object] Objeto con detalles del retiro
withdrawal_data: type [string] Tipo de data entregada (Ej: btc_withdrawal_data,fiat_withdrawal_data)
withdrawal_data: target_address [address] Dirección de destino del retiro
withdrawal_data: tx_hash [string] ID de la transacción

Nuevo Retiro Lightning ⚡️

import requests

url = f'https://www.buda.com/api/v2/reserves/ln-btc/withdrawals'
auth = BudaHMACAuth(api_key, secret)
response = requests.post(url, auth=auth, json={
    'amount': 0.0022704,
    'withdrawal_data': {
        'payment_request': 'lnbc227040n1pdmvkw6pp5x7ws3aygr96w75l9z4qmw7z5n8s3ukkcfzmcegkjndlz9pm9fldqdq6ga6kjmrvv4ex6meqf4hhyetwducqzyswf2ey2yv92msm40rzy5wvcpd6t26smjk6k38wtj5gcl65jwttw7pezx8wrsl4h8qn852ltmtg32s8vmkchvt000n3wc6de22mmqtg6qqu7mpr6',
    },
})
print(response.json())

{
  "withdrawal": {
    "id": null,
    "amount": ["0.0022704", "BTC"],
    "created_at": "2017-04-26T13:47:42.000Z",
    "currency": "BTC",
    "fee": ["0.0", "BTC"],
    "state": "confirmed",
    "withdrawal_data": {
      "payment_request": "lnbc227040n1pdmvkw6pp5x7ws3aygr96w75l9z4qmw7z5n8s3ukkcfzmcegkjndlz9pm9fldqdq6ga6kjmrvv4ex6meqf4hhyetwducqzyswf2ey2yv92msm40rzy5wvcpd6t26smjk6k38wtj5gcl65jwttw7pezx8wrsl4h8qn852ltmtg32s8vmkchvt000n3wc6de22mmqtg6qqu7mpr6",
      "type": "lightning_network_withdrawal_data"
      'payment_error': "Description about payment error, if any."
    }
  }
}

Paga un Invoice de Lightning Network ⚡️

Con este endpoint puedes pagar servicios usando Bitcoins a través de esta red. (Puedes echar un vistazo en Mainnet lightning network stores para ver un listado de servicios disponibles).

Ten presente que para realizar un pago a través de Lightning Network primero debes conseguir una solicitud de pago (Invoice) de quien recibirá el pago.

HTTP Request

POST /reserves/ln-btc/withdrawals

Request Payload

Key Required Descripción
amount Yes Volumen del retiro (en BTCs)
withdrawal_data: payment_request Yes Invoice del pago lightning
simulate No Permite simular la solicitud de retiro

Response Details (JSON)

Key Tipo Descripción
id [int] ID del retiro
created_at [time] Fecha de creación de la solicitud
amount [amount, currency] Cantidad asociada al retiro
currency [currency] Moneda asociada al retiro
fee [amount, currency] Tarifa asociada a la ejecución del retiro
state [string] Estado de la solicitud (Ej: confirmed, rejected)
withdrawal_data [object] Objeto con detalles del retiro
withdrawal_data: type [string] Siempre dirá lightning_network_withdrawal_data
withdrawal_data: payment_request [address] Invoice usado para generar el retiro
withdrawal_data: payment_error [string] Información con errores al realizar la transacción lightning, si es que los hay.

Nuevo Abono Lightning ⚡️

import requests

url = f'https://www.buda.com/api/v2/lightning_network_invoices'
auth = BudaHMACAuth(api_key, secret)
response = requests.post(url, auth=auth, json={
    'amount_satoshis': 5000,
    'currency': 'BTC',
    'memo': 'Un computador'
})
print(response.json())

{
  "lightning_network_invoice": {
    "id": 1,
    "currency": "BTC",
    "encoded_payment_request": 'lnbc227040n1pdmvkw6pp5x7ws3aygr96w75l9z4qmw7z5n8s3ukkcfzmcegkjndlz9pm9fldqdq6ga6kjmrvv4ex6meqf4hhyetwducqzyswf2ey2yv92msm40rzy5wvcpd6t26smjk6k38wtj5gcl65jwttw7pezx8wrsl4h8qn852ltmtg32s8vmkchvt000n3wc6de22mmqtg6qqu7mpr6'
  }
}

Crea un Invoice de Lightning Network ⚡️

Con este endpoint puedes solicitar un pago usando Bitcoins a través de esta red. Este invoice se lo puedes enviar a quien te va a pagar.

HTTP Request

POST /lightning_network_invoices

Request Payload

Key Required Descripción
amount_satoshis Yes Monto del invoice en satoshis.
currency Yes Debe tener el valor BTC
memo No La razón del invoice (una breve descripción)
expiry_seconds No La cantidad de tiempo en segundos en la que el invoice expirará

Response Details (JSON)

Key Tipo Descripción
id [int] ID del invoice
currency [time] La moneda del invoice
encoded_payment_request [string] El invoice codificado

Rate Limits

Tomamos alguna medidas para protegernos de ataques DoS o abusos en nuestra api. Esto para poder asegurar que el servicio sea estable para todos nuestros usuarios.

Si tu request es limitado, recibirás una respuesta con el código 429,debes esperar antes de intentar nuevamente.

Los límites se calculan en ventanas de 1 minuto y de 1 segundo. Para las ventanas de 1 segundo, mientras hagas menos 20 requests/segundo no debieras gatillar el límite.

General

Las llamadas anónimas (no autenticadas), serán limitadas por dirección IP a una tasa de 120 requests/minuto. Las llamadas autenticadas, serán limitadas por api key a 375 requests/minuto.

Trading (crear y cancelar órdenes)

Los endpoints para crear y eliminar órdenes son limitados por mercado. El limite es dependiente del tier. Puedes ver más detalles en la página de comisiones.

Tier Volumen 30 días Rate Limit
< 4 < $100 000 100 requests/minuto
>= 4 >= $100 000 250 requests/minuto

Errores

Tratamos que la API se adhiera lo máximo posible a las convenciones de códigos de errores HTTP.

Adicionalmente, en caso de un error, la API además envía un objeto JSON con más información como muestra el ejemplo.

Example error response (HTTP 403):

{
  "code": "forbidden",
  "message": "You dont have access to this resource"
}

Una explicación más detallada de los códigos HTTP que la API de buda.com utiliza es la siguiente:

Código HTTP Significado
400 Bad Request -- La solicitud contiene sintaxis errónea y no debería repetirse. Si estás haciendo una solicitud de tipo POST, revisa que el objeto que estás enviando va como JSON en el body de la solicitud y que estás usando la cabecera Content-Type: application/json.
401 Unauthorized -- Tu API Key es inválida o no estás realizando la autenticación de acuerdo al formato requerido por la API.
403 Forbidden -- La solicitud es válida, pero no cuentas con los permisos para realizarla.
404 Not Found -- Recurso no encontrado. Revisa la URL que estás solicitando.
405 Method Not Allowed -- Has intentado acceder a un endpoint con el método incorrecto (por ejemplo, hacer GET en vez de POST).
406 Not Acceptable -- Has solicitado un formato no soportado por el servidor. Revisa que la cabecera Accept que estás enviando especifique el formato JSON (Accept: application/json)
410 Gone -- El recurso solicitado fue eliminado y no tiene sentido reintentar la solicitud.
422 Unprocessable entity -- Has enviado información en un formato inválido. Revisa que el objeto que estás enviado como body en la solicitud POST calce con esta documentación (p.ej: en general los strings que debes enviar son case-sensitive).
429 Too Many Requests -- Has superado el límite de solicitudes Rate Limits
500 Internal Server Error -- Ha habido un problema con nuestro servidor y probablemente estamos rodeados por llamas mientras lo tratamos de solucionar 🔥. Vuelve a intentarlo más tarde.
503 Service Unavailable -- Estamos temporalmente fuera de servicio por mantenimiento. Vuelve a intentarlo más tarde.

Websockets API

Introducción

import websocket

def on_message(ws, message):
    print(message)

def on_open(ws):
    print('web-socket connected.')

def channels():
    pubsub_key = "pubsub_key"
    chs = [
        "book%40btcclp",
        "book%40ethclp",
        "trades%40btcclp",
        f"balances%40{pubsub_key}",
        f"orders%40{pubsub_key}"
    ]
    return ",".join(chs)



if __name__ == "__main__":
    SOCKET = f"wss://realtime.buda.com/sub?channel={channels()}"
    ws = websocket.WebSocketApp(SOCKET, on_message = on_message)
    ws.on_open = on_open
    ws.run_forever(ping_interval=10)

Los eventos tienen la siguiente estructura:

{
 ev: 'book-sync',
 ts: '123123123.123123',
 mk: 'BTC-CLP',
 ...
}

Los websockets permiten abrir canales entre cliente y servidor, para poder hacer streaming de datos en tiempo real. Con esta API puedes comunicarte con nuestro servidor y recibir respuestas en base a eventos, en vez de tener que estar constantemente consultando.

Para la comunicación realtime estamos usando Nchan, por lo que se puede usar websockets para subscribirse a los eventos. Hay más información de cómo funciona nchan con websockets en https://nchan.io/#subscriber-endpoints.

Para poder acceder a los websockets autenticados necesitas tu pubsub_key, la cual puedes encontrar en tu información personal.

En general, los URL de nuestros websockets se forman así:

wss://realtime.buda.com/sub?channel=[channel]

Para los casos que se requiere autenticación se forman así:

wss://realtime.buda.com/sub?channel=[channel]@[pubsub_key]

En caso de querer suscribirte a varios canales al mismo tiempo entonces se forman así:

wss://realtime.buda.com/sub?channel=[channel1,channel2,channel3@pubsub_key]

Donde:

Path Parameters

Parameter Value
channel canal a utilizar
pubsub-key llave pubsub de tu cuenta que puede ser encontrada en información personal

Event Details

Key Descripción
ev Nombre del evento
ts Unix timestamp del evento (segundos.nanosegundos)
mk ID del mercado que corresponde en caso de haberlo (Ej: ETH-BTC, BTC-CLP, etc).

Canales públicos

Libro de órdenes

import websocket

def on_message(ws, message):
    print(message)

def on_open(ws):
    print('web-socket connected.')

if __name__ == "__main__":
    SOCKET = "wss://realtime.buda.com/sub?channel=book%40btcclp"
    websocket.enableTrace(True)
    ws = websocket.WebSocketApp(SOCKET, on_message = on_message)
    ws.on_open = on_open
    ws.run_forever(ping_interval=10)

Los eventos de este canal tienen la siguiente estructura:

{
  ev: 'book-changed',
  change: [
    'asks'|'bids',
    <nivel de precio>,
    <cambio de monto>
  ]
}

{
  ev: 'book-sync',
  order_book: <libro de órdenes serializado>
}

Para suscribirse al canal de cambios en el libro de órdenes del mercado indicado. Cada 5 minutos se envía un snapshot completo del libro para ayudar en la sincronización.

Channel endpoint

channel=book@<market_id>

Path Parameters

Parámetro Descripción
market_id El ID del mercado (Ej: ethbtc, btcclp, etc).
Puedes obtener un listado completo de estos identificadores a través de la llamada al endpoint de Mercados

Trades

import websocket

def on_message(ws, message):
    print(message)

def on_open(ws):
    print('web-socket connected.')

if __name__ == "__main__":
    SOCKET = "wss://realtime.buda.com/sub?channel=trades%40btcclp"
    websocket.enableTrace(True)
    ws = websocket.WebSocketApp(SOCKET, on_message = on_message)
    ws.on_open = on_open
    ws.run_forever(ping_interval=10)

Los eventos de este canal tienen la siguiente estructura:

{
  ev: 'trade-created',
  trade: [
    <timestamp>,
    <monto trade>,
    <precio trade>,
    'buy'|'sell',
    <id>
  ]
}

Para suscribirse al canal de las nuevas transacciones públicas del mercado indicado.

Channel endpoint

channel=trades@<market_id>

Path Parameters

Parámetro Descripción
market_id El ID del mercado (Ej: ethbtc, btcclp, etc).
Puedes obtener un listado completo de estos identificadores a través de la llamada al endpoint de Mercados

Event Details

Key Descripción
ev Nombre del evento
timestamp Unix timestamp del trade más reciente
monto Monto del trade más reciente
precio Precio del trade más reciente

Canales privados

Balances

import websocket

def on_message(ws, message):
    print(message)

def on_open(ws):
    print('web-socket connected.')

if __name__ == "__main__":
    SOCKET = "wss://realtime.buda.com/sub?channel=balances%40{pubsub_key}"
    websocket.enableTrace(True)
    ws = websocket.WebSocketApp(SOCKET, on_message = on_message)
    ws.on_open = on_open
    ws.run_forever(ping_interval=10)

Los eventos de este canal tienen la siguiente estructura:

{
 ev: 'balance-updated',
 balance: <balance serializado>
}

Para suscribirse al canal de cambios en tu balance.

Channel endpoint

channel=balances@<pubsub_key>

Path Parameters

Parámetro Descripción
pubsub_key llave pubsub de tu cuenta que puede ser encontrada en información personal

Mis Ordenes

import websocket

def on_message(ws, message):
    print(message)

def on_open(ws):
    print('web-socket connected.')

if __name__ == "__main__":
    SOCKET = "wss://realtime.buda.com/sub?channel=orders%40{pubsub_key}}"
    websocket.enableTrace(True)
    ws = websocket.WebSocketApp(SOCKET, on_message = on_message)
    ws.on_open = on_open
    ws.run_forever(ping_interval=10)

Los eventos de este canal tienen la siguiente estructura:

{
 ev: 'order-created'|'order-updated',
 order: <orden serializada>
}

Para suscribirse al canal de cambios en tus órdenes.

Channel endpoint

channel=orders@<pubsub_key>

Path Parameters

Parámetro Descripción
pubsub_key llave pubsub de tu cuenta que puede ser encontrada en información personal

Depositos Confirmados

import websocket

def on_message(ws, message):
    print(message)

def on_open(ws):
    print('web-socket connected.')

if __name__ == "__main__":
    SOCKET = "wss://realtime.buda.com/sub?channel=deposits%40{pubsub_key}"
    websocket.enableTrace(True)
    ws = websocket.WebSocketApp(SOCKET, on_message = on_message)
    ws.on_open = on_open
    ws.run_forever(ping_interval=10)

Los eventos de este canal tienen la siguiente estructura:

{
 ev: 'deposit-confirmed',
 deposit: <deposit serializado>
}

Para suscribirse al canal de confirmación de depósitos.

Channel endpoint

channel=deposits@<pubsub_key>

Path Parameters

Parámetro Descripción
pubsub_key llave pubsub de tu cuenta que puede ser encontrada en información personal

Cross Border Payments

Introducción

Simplifica tus envíos internacionales con Buda.com

En Buda.com abrimos Cross Border Payments, un servicio diseñado para que puedas enviar dinero al extranjero de manera rápida, segura y sin complicaciones.

Hoy, contamos con rutas abiertas para transferencias entre Chile, Colombia y Perú. Con disponibilidad 24/7, transferencias que llegan en minutos y al mejor precio posible, sin costos ocultos.

¿Listo para simplificar tus pagos internacionales? Contáctanos en [email protected] o a través de nuestro equipo de soporte, y te guiaremos en todo el proceso de onboarding. Aprovecha al máximo nuestras soluciones para que tus transferencias sean siempre fáciles y eficientes. Además, estamos trabajando en expandir nuestras rutas y nos encantaría conocer qué otros destinos son importantes para ti. ¡Conversemos!

Cotizar remesa

import requests

market = 'btc-clp'
url = f'https://www.buda.com/api/v2/remittances'
response = requests.post(url, json={
    'origin_amount': 10000,
    'origin_currency': 'CLP',
    'destination_currency': 'PEN',
})
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
    "remittance": {
        "id": 1,
        "state": "quoted",
        "origin_currency": "CLP",
        "destination_currency": "PEN",
        "expires_at": "2024-01-01T00:08:48.000Z",
        "created_at": "2024-01-01T00:07:48.946Z",
        "origin_amount": ["10000.0","CLP"],
        "destination_amount": ["54.45","PEN"],
        "fee_amount": ["0.0","CLP"],
        "withdrawal_fee_amount": ["4.0","PEN"]
    }
}

Obtén una cotización de una remesa de acuerdo al libro de órdenes del momento.

HTTP Request

POST /remittances

Request Payload

Key Required Descripción
origin_amount No
(Excluyente con destination_amount)		 Monto a cotizar expresado en la moneda de origen
destination_amount No
(Excluyente con origin_amount)		 Monto a cotizar expresado en la moneda de destino
origin_currency Yes Moneda de origen
destination_currency Yes Moneda de destino

Response Details (JSON)

Key Tipo Descripción
id [number] ID de la remesa.
state [string] Estado de la remesa.
origin_currency [string] Moneda de origen.
destination_currency [string] Moneda de destino.
expires_at [time] Fecha de expiración de la cotización.
created_at [time] Fecha creación de la cotización.
origin_amount [amount, currency] Monto de origen.
destination_amount [amount, currency] Monto convertido a la moneda de destino.
withdrawal_fee_amount [amount, currency] Comisión de retiro bancario que aplicará sobre el destination_amount.

Aceptar cotización

import requests

remittance_id = 1
url = f'https://www.buda.com/api/v2/remittances/{remittance_id}'
auth = BudaHMACAuth(api_key, secret)
response = requests.put(url, auth=auth, json={
    'state': 'accepted',
    'fiat_account': {
      "names":"Satoshi",
      "surnames":"Nakamoto",
      "bank_code":"002",
      "account_number":"",
      "account_type":"savings_account",
      "document_number":"1111111",
      "inter_bank_number":"11111111111111111111",
    }
})
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
    "remittance": {
        "id": 1,
        "state": "accepted",
        "origin_currency": "CLP",
        "destination_currency": "PEN",
        "expires_at": "2024-01-01T00:08:48.000Z",
        "created_at": "2024-01-01T00:07:48.946Z",
        "origin_amount": ["10000.0","CLP"],
        "destination_amount": ["54.45","PEN"],
        "fee_amount": ["0.0","CLP"],
        "withdrawal_fee_amount": ["4.0","PEN"]
    }
}

Acepta una cotización utilizando su id para que comience la ejecución de la remesa, este request solo será exitoso si es realizado dentro del tiempo de validez de una cotización, el cual se representa con el atributo expires_at.

HTTP Request

PUT /remittances/<id>

En el payload, debes incluir el estado accepted, además de la cuenta bancaria de destino:

Request Payload

Key Required Descripción
state Yes Debe ser el string "accepted" para aceptar la confirmación.
fiat_account Yes Objeto con los datos de la cuenta bancaria de destino. Ver detalle en siguiente tabla.

Fiat Account Payload

Key Required Descripción
names Yes Nombres del destinatario.
surnames Yes Apellidos del destinatario.
bank_code Yes Código del banco de destino (string). Para obtenerlo debes consultar la lista de bancos en el país de destino. Véase el apartado siguiente.
account_number No Número de cuenta.
account_type Yes Tipo de cuenta. Los identificadores posibles se señalan en la tabla Account Type.
document_number Yes Número de documento (DNI) del destinatario.
inter_bank_number Yes Número interbancario CCI (para Perú). Debe contener exactamente 20 dígitos.

Bank Code

Para obtener el código del banco de destino debes realizar la siguiente consulta e identificar el code asociado al banco deseado.

GET /currencies/<destination_currency>/banks

Account Type

String que identifica el tipo de cuenta bancaria de destino:

Tipo Descripción
current_account Cuenta corriente.
savings_account Cuenta de ahorro.

Response Details (JSON)

Key Tipo Descripción
id [number] ID de la remesa.
state [string] Estado de la remesa.
origin_currency [string] Moneda de origen.
destination_currency [string] Moneda de destino.
expires_at [time] Fecha de expiración de la cotización.
created_at [time] Fecha creación de la cotización.
origin_amount [amount, currency] Monto de origen.
destination_amount [amount, currency] Monto convertido a la moneda de destino.
withdrawal_fee_amount [amount, currency] Comisión de retiro bancario que aplicará sobre el destination_amount.

Consultar remesa

import requests

remittance_id = 1
url = f'https://www.buda.com/api/v2/remittances/{remittance_id}'
auth = BudaHMACAuth(api_key, secret)
response = requests.get(url, auth=auth)
print(response.json())

{
  "remittance": {
    "id": 1,
    "state": "completed",
    "origin_currency": "CLP",
    "destination_currency": "PEN",
    "origin_amount":["100000.0","CLP"],
    "destination_amount":["330.12","PEN"],
    "expires_at": "2024-05-16T14:38:21.000Z",
    "fee_amount":["0.0","CLP"],
    "withdrawal_fee_amount":["4.0","PEN"]
  }
}

Consulta la información sobre una remesa específica.

HTTP Request

GET /remittances/<id>

Path Parameters

Parameter Descripción
id ID de la remesa

Response Details (JSON)

Key Tipo Descripción
id [number] ID de la remesa.
state [string] Estado de la remesa.
origin_currency [string] Moneda de origen.
destination_currency [string] Moneda de destino.
expires_at [time] Fecha de expiración de la cotización.
created_at [time] Fecha creación de la cotización.
origin_amount [amount, currency] Monto de origen.
destination_amount [amount, currency] Monto convertido a la moneda de destino.
withdrawal_fee_amount [amount, currency] Comisión de retiro bancario que aplicará sobre el destination_amount.

Los tipos de estado

Estado Descripción
quoted Corresponde a una cotización de remesa que aún no es aceptada por el usuario. (Sólo puede ser aceptada antes de la fecha indicada en expires_at)
accepted Corresponde a una cotización que ha sido aceptada y se está procesando.
pending_withdrawal Corresponde a una remesa cuya transferencia bancaria esta en proceso en el país de destino.
completed Corresponde a una remesa cuya transferencia bancaria ya se realizó exitosamente.
failed Corresponde a una remesa que no llegó a destino por problemas en la operación.

Fee

El parametro withdrawal_fee_amount representa la comisión asociada al retiro bancario en el país de destino. El destinatario final recibirá en su cuenta bancaria el valor de destination_amount menos la comisión withdrawal_fee_amount.

Mis Remesas

Ejemplo:

import requests

url = f'https://www.buda.com/api/v2/remittances'
auth = BudaHMACAuth(api_key, secret)
response = requests.get(url, auth=auth, params={
    'state': 'completed',
    'per': 20,
    'page': 1,
})
print(response.json())

Esta llamada entrega un objeto con el siguiente formato:

{
  "remittances": [
    {
    "id": 1,
    "state": "completed",
    "origin_currency": "CLP",
    "destination_currency": "PEN",
    "origin_amount":["100000.0","CLP"],
    "destination_amount":["330.12","PEN"],
    "expires_at": "2024-05-16T14:38:21.000Z",
    "fee_amount":["0.0","CLP"],
    "withdrawal_fee_amount":["4.0","PEN"]
  },
    {
    "id": 2,
    "state": "completed",
    "origin_currency": "CLP",
    "destination_currency": "PEN",
    "origin_amount":["25000.0","CLP"],
    "destination_amount":["70.20","PEN"],
    "expires_at": "2024-05-16T16:21:02.000Z",
    "fee_amount":["0.0","CLP"],
    "withdrawal_fee_amount":["4.0","PEN"]
  },
    ...
  ],
  "meta": {
    "current_page": 1,
    "total_count": 50,
    "total_pages": 3
  }
}

Muestra las remesas realizadas o en proceso, permitiendo filtrar por estado.

HTTP Request

GET /remittances

Query Parameters

Parameter Default Descripción
state None Recuperar sólo remesas con estado state.

Response Details (JSON)

Key Tipo Descripción
id [number] ID de la remesa.
state [string] Estado de la remesa.
origin_currency [string] Moneda de origen.
destination_currency [string] Moneda de destino.
expires_at [time] Fecha de expiración de la cotización.
created_at [time] Fecha creación de la cotización.
origin_amount [amount, currency] Monto de origen.
destination_amount [amount, currency] Monto convertido a la moneda de destino.
withdrawal_fee_amount [amount, currency] Comisión de retiro bancario que aplicará sobre el destination_amount.

Errores

Tratamos que la API se adhiera lo máximo posible a las convenciones de códigos de errores HTTP.

Adicionalmente, en caso de un error, la API además envía un objeto JSON con más información como muestra el ejemplo.

Example error response (HTTP 403):

{
  "code": "forbidden",
  "message": "You dont have access to this resource"
}

Una explicación más detallada de los códigos HTTP que la API de Cross Border Payments utiliza es la siguiente:

Código HTTP Significado
400 Bad Request -- La solicitud contiene sintaxis errónea y no debería repetirse. En caso de que el error se deba a la invalidez de los parámetros, veras en la respuesta un código indicando el parámetro, estos pueden ser: invalid_currency amounts_mutually_exclusive, invalid_amount, invalid_state o insufficient_balance
410 Gone -- Si la respuesta va acompañada del codigo no_quotations, significa que el servicio de Cross Border Payments no se encuentra operativo temporalmente. Si se responde con el código remittance_expired, representa que has intentado aceptar una cotización ya expirada.
401 Unauthorized -- Puede deberse a que la API Key es inválida o no estás realizando la autenticación de acuerdo al formato requerido por la API. También, puede deberse a que no estás habilitado en nuestros sistemas para esta solicitud, en ese caso verás el codigo remittance_disabled_for_user.
403 Forbidden -- La solicitud es válida, pero no cuentas con los permisos para realizarla.
404 Not Found -- Recurso no encontrado. Revisa la URL que estás solicitando.
405 Method Not Allowed -- Has intentado acceder a un endpoint con el método incorrecto (por ejemplo, hacer GET en vez de POST).
406 Not Acceptable -- Has solicitado un formato no soportado por el servidor. Revisa que la cabecera Accept que estás enviando especifique el formato JSON (Accept: application/json)
422 Unprocessable entity -- Has enviado información en un formato inválido. Revisa que el objeto que estás enviado como body en la solicitud POST calce con esta documentación (p.ej: en general los strings que debes enviar son case-sensitive).
429 Too Many Requests -- Has superado el límite de solicitudes Rate Limits
500 Internal Server Error -- Ha habido un problema con nuestro servidor, por lo que puedes volver a intentarlo, y si el error persiste, comunícate con nosotros.
503 Service Unavailable -- Estamos temporalmente fuera de servicio por mantenimiento. Vuelve a intentarlo más tarde.

OAuth

Nuestra API cuenta con OAuth para una autorización segura y estandarizada. OAuth permite a los usuarios autorizar de forma segura a aplicaciones de terceros para acceder a sus datos sin compartir sus credenciales completas. ¿Quieres mas información? Escríbenos a [email protected].

Últimos cambios

2 de septiembre, 2024

16 de febrero, 2024

13 de diciembre, 2023

20 de junio, 2023

31 de mayo, 2023

12 de enero, 2023

19 de diciembre, 2022

14 de noviembre, 2022

24 de octubre, 2022

30 de agosto, 2022

30 de mayo, 2022

17 de marzo, 2022

17 de febrero, 2022

python