Navbar
Logo dark
python

Introduccion

La API de Buda.com

Qué bien! Encontraste la documentación de la API REST de Buda.com. Si no eres un desarrollador de software, andas muy perdido 😀.

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 Publicas

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"]
    },
    {
      "id": "BTC-COP",
      "name": "btc-cop",
      "base_currency": "BTC",
      "quote_currency": "COP",
      "minimum_order_amount": ["0.001", "BTC"]
    },
    ...
  ]
}

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"]
  }
}

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

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)

Libro de ordenes

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=1502472564

Parameter Descripción
timestamp (opcional) Unix timestamp 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
ask_given_size 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?)
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 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_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.

Autenticacion

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…

Paginacion

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.

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

Mis Ordenes

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",
      "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",
      "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 (usando el atributo limit), 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.

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.
traded La orden ha terminado de transarse por completo.
canceling La orden ha recibido una petición de cancelación.
canceled La orden fue cancelada y el monto no transado está nuevamente disponible.

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
minimum_exchanged None Recuperar órdenes con al menos minimum_exchaged transado

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 una 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": 1,
    "type": "Bid",
    "state": "traded",
    "created_at": "2017-06-30T02:14:45.368Z",
    "market_id": "BTC-CLP",
    "fee_currency": "BTC",
    "price_type": "limit",
    "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

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
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)

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': 1000000,
    'amount': 0.05,
})
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",
    "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 Limit Precio de la orden
amount Yes Volumen de la orden

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)

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",
    "limit": ["1000000.0", "CLP"],
    "market_id": "BTC-CLP",
    "original_amount": ["0.05", "BTC"],
    "paid_fee": ["0.0", "BTC"],
    "price_type": "limit",
    "state": "canceling",
    "total_exchanged": ["0.0", "CLP"],
    "traded_amount": ["0.0", "BTC"],
    "type": "Bid"
  }
}

Permite comenzar la cancelación de una orden. No se puede realizar ningún otro cambio con este endpoint.

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)

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': 'place', 'order': {'amount': 1.5,
                                         'limit': 3500000.0,
                                         'market_name': 'btc-clp',
                                         'price_type': 'limit',
                                         'type': 'Ask'}},
             {'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": 1,
      "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 [int] 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 [int] 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 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 cirecciones 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

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 seleccionadas

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/currencies/BTC/withdrawals'
auth = BudaHMACAuth(api_key, secret)
response = requests.post(url, auth=auth, json={
    'amount': 0.0022704,
    'reserve_code': 'ln-btc'
    '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 /currencies/BTC/withdrawals

Request Payload

Key Required Descripción
amount Yes Volumen del retiro (en BTCs)
reserve_code Yes Debe tener el valor ln-btc
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.

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 por segundo (~2 req/s).
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.