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

Si te quieres ahorrar un poco de trabajo, aqu铆 tienes una recopilaci贸n de librer铆as 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]

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.

Ojo, recuerda que primero debes contactarnos para que activemos tu cuenta en modo developer. Entonces obtendr谩s desde la p谩gina, en la secci贸n “Mi Cuenta”, un API-KEY y un API-SECRET.

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)

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.