Buda.com's API
Great! You found the API documentation for Buda.com. If you are not a software developer you might be a little lost 😀. We offer REST and Websocket APIs to suit your needs.
REST API
Introduction
An example using the
requests
library
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())
Like many other cryptocurrency exchanges, Buda.com's API has public endpoints and private endpoints:
Public endpoints don't require authentication to use, making them public information. In fact, you can use them directly from your browser by adding
.json
to the end of the path. For example, try the following URL:https://www.buda.com/api/v2/markets/eth-btc/ticker.json
Private endpoints require authentication, so in order to use them, you need to obtain both an API-KEY and an API-SECRET for your account. For this step, you need to log in to buda.com and go to the Configuración section, where you will find the API Keys tab and an option to create new API-KEYS with various levels of permission and expiry dates.
Our API's URLs usually have this format
https://www.buda.com/api/[version]/[path].[format]
Where currently:
Parameter | Value |
---|---|
version |
v2 |
format |
json |
Open Source Libraries
Clients
If you want to save some time, these are some clients for our API in various languages.
These libraries are not official nor have been tested by us, but we have spoken to their creators who seem like good people 😉.
If you want to share your own library with the community, contact us at [email protected].
Other libraries
CCXT is a very useful library that facilitates connecting to over 100 exchanges (including Buda ❤️) using Python, Javascript, or PHP. Yes, really.
Public Endpoints
Markets
import requests
url = 'https://www.buda.com/api/v2/markets'
response = requests.get(url)
print(response.json())
This call returns an object with the following format:
{
"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"
},
{
"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"
},
...
]
}
Obtain market details
import requests
market_id = 'btc-clp'
url = f'https://www.buda.com/api/v2/markets/{market_id}'
response = requests.get(url)
print(response.json())
This call returns an object with the following format:
{
"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"
}
}
A given market separates the buys and sells by currency. In each market, the base_currency
is bought or sold, and the quote_currency
is used to pay for these trades. We use these two currencies to identify each market.
For example, the market in which bitcoins (BTC) are traded against dollars (USDC) is: btc-usdc
.
HTTP Request
GET /markets
GET /markets/<market_id>
Path Parameters
Parameter | Description |
---|---|
market_id |
(optional) The market ID (for example: btc-clp , eth-btc , etc). You can obtain a complete list of all markets by leaving this parameter blank. |
Response Details
Key | Type | Description |
---|---|---|
id |
[string] | Market identifier |
name |
[string] | Market name |
base_currency |
[string] | Currency traded |
quote_currency |
[string] | Currency paid |
minimum_order_amount |
[amount, currency] | Minimumm order amount accepted |
taker_fee |
[amount] | Fee paid by a taker order |
maker_fee |
[amount] | Fee paid by a maker order |
max_orders_per_minute |
[amount] | Trading Rate Limit for given market |
maker_discount_percentage |
[string] | Maker discount for given market |
taker_discount_percentage |
[string] | Taker discount for given market |
Transacted Volume
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())
This call returns an object with the following format:
{
"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"
}
}
This endpoint accesses all the transacted volume in a given market, where ask_volume
is the volume traded in sell orders, while bid_volume
is the volume traded by buy orders.
HTTP Request
GET /markets/<market_id>/volume
Response Details
Key | Type | Description |
---|---|---|
ask_volume_24h |
[amount, currency] | Amount transacted in sell orders in the last 24 hours |
ask_volume_7d |
[string] | Amount transacted in sell orders in the last 7 days |
bid_volume_24h |
[amount, currency] | Amount transacted in buy orders in the last 24 hours |
bid_volume_7d |
[string] | Amount transacted in buy orders in the last 7 days |
market_id |
[string] | Requested market ID |
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())
This call returns an object with the following format:
{
"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"]
}
}
This endpoint gives access to the current state of a given market. This response includes the best buy and sell price currently available (bid
and ask
) and the last traded price (last_price
) for the selected market. There is also information related to the daily volume and price change.
HTTP Request
GET /markets/<market_id>/ticker
Path Parameters
Parameter | Description |
---|---|
market_id |
The market ID (for example: btc-clp , eth-btc , etc). You can obtain a complete list of all markets by calling the Markets endpoint. |
Response Details
Key | Type | Description |
---|---|---|
market_id |
[currency] | Requested market ID |
last_price |
[amount, currency] | Last traded price |
min_ask |
[amount, currency] | Min sell price |
max_bid |
[amount, currency] | Max buy price |
volume |
[amount, currency] | Transacted volume in the last 24 hours |
price_variation_24h |
[float] | Percentage variation of price in the last 24 hours |
price_variation_7d |
[float] | Percentage variation of price in the last 7 days |
All Tickers
import requests
url = f'https://www.buda.com/api/v2/tickers'
response = requests.get(url)
print(response.json())
This call returns an object with the following format:
{
"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"]},
...
]
}
This endpoint gives access to the current state of all markets. This response includes information related to the daily and weekly volume, as well as the last traded price (last_price
) for each market.
HTTP Request
GET /tickers
Response Details
Key | Type | Description |
---|---|---|
market_id |
[currency] | Requested market ID |
last_price |
[amount, currency] | Last traded price |
price_variation_24h |
[float] | Percentage variation of price in the last 24 hours |
price_variation_7d |
[float] | Percentage variation of price in the last 7 days |
Order Book
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())
This call returns an object with the following format:
{
"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"],
...
]
}
}
Get a list of all the limit buy and sell orders currently placed in a given market.
HTTP Request
GET /markets/<market_id>/order_book
Path Parameters
Parameter | Description |
---|---|
market_id |
The market ID (for example: btc-clp , eth-btc , etc). You can obtain a complete list of all markets by calling the Markets endpoint. |
Response Details
Key | Type | Description |
---|---|---|
asks |
[price, amount] | Array with sell orders |
bids |
[price, amount] | Array with buy orders |
Trade History
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())
This call returns an object with the following format:
{
"trades": {
"timestamp": "1476905551698",
"last_timestamp": "1476380738941",
"market_id": "BTC-CLP",
"entries": [
["1476905551687", "0.00984662", "435447.12", "buy"],
["1476905551676", "3.01572553", "435283.3", "buy"],
...
]
}
}
Get a list of all recent trades in a given market.
HTTP Request
GET markets/<market_id>/trades
Path Parameters
Parameter | Description |
---|---|
market_id |
The market ID (for example: btc-clp , eth-btc , etc). You can obtain a complete list of all markets by calling the Markets endpoint. |
URL Parameters
Included at the end of the URL
For example: GET /markets/BTC-CLP/trades?timestamp=1502472564
Parameter | Description |
---|---|
timestamp |
(optional) Unix timestamp indicating trade to request |
limit |
(optional) Amount of trades requested [default: 50, max: 100] |
Response Details
Key | Type | Description |
---|---|---|
entries |
[timestamp, amount, price, direction] | Array with transaction history |
timestamp |
[timestamp] | Most recent Unix timestamp for the given response |
last_timestamp |
[timestamp] | Least recent Unix timestamp for the given response |
market_id |
[currency] | Market ID being requested |
Simulate Orders
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())
This call returns an object with the following format:
{
"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"
}
}
Get a simulated quote for an order in a given market using the current order book.
Quote types
This endpoint can simulate many different types of quotes.
For this, you can choose a specific market for the simulation, where our market IDs are in the <base_currency>-<quote_currency>
format (we will use the eth-btc
market as an example). You can simulate what a buy or sell order would be for a certian amount
of the base_currency
or quote_currency
. (If you want more detail about what is a buy or sell order you con go check My Orders)
For the simulation, you need to choose one of the following types and send it as the type
payload parameter.
Quote type | Description |
---|---|
bid_given_size or bid_given_earned_base |
Simulates a buy order to receive a certain amount of base_currency (for example: How much btc is requiered to obtain a certain amount of eth ?) |
bid_given_value or bid_given_spent_quote |
Simulates a buy order to spend a certain amount of quote_currency (for example: How much eth will I receive if I buy a certain amount of btc ?) |
ask_given_size or ask_given_spent_base |
Simulates a sell order to spend a certain amount of base_currency (for example: How much btc would I receive if I sell a certain amount of eth ?) |
ask_given_value or ask_given_earned_quote |
Simulates a sell order to receive a certain amount of quote_currency (for example: How much eth is requiered to obtain a certain amount of btc ?) |
HTTP Request
POST '/markets/<market_id>/quotations
Path Parameters
Parameter | Description |
---|---|
market_id |
The market ID (for example: btc-clp , eth-btc , etc). You can obtain a complete list of all markets by calling the Markets endpoint. |
Request Payload
Key | Required | Description |
---|---|---|
type |
Yes | Quote type being requested (see previous table) |
amount |
Yes | Amount to simulate quote (represents base_currency or quote_currency ) depending on the type parameter |
limit |
No | Price requested for the currency in which the amount parameter is expressed in |
Response Details
Key | Type | Description |
---|---|---|
amount |
[amount, currency] | The amount value sent in the payload. |
base_balance_change |
[amount, currency] | How much your base_currency balance would change after fees. This can be either positive or negative. |
base_exchanged |
[amount, currency] | Total base_currency amount that would be traded. This is always positive. |
fee |
[amount, currency] | Fee charged for trade. |
incomplete |
[boolean] | Indicates whether or not your simulated order would be completely filled given current market conditions (order book and your current balance). |
limit |
[amount, currency] | The limit value sent in the payload. |
order_amount |
[amount, currency] | The same value as base_exchanged . |
quote_balance_change |
[amount, currency] | How much your quote_currency balance would change after fees. This can be either positive or negative. |
quote_exchanged |
[amount, currency] | Total quote_currency amount that would be traded. This is always positive. |
type |
[string] | Quote type requested. |
About fee calculations (fee
)
- Keep in mind that the fee charged for each trade is dependant on the monthly volume traded by each user.
- If you request this endpoint without authentication then the fee displayed will corresponf to the highest fee for that market.
- If you would like to simulate orders considering your account's corresponding fee then make the request authenticated.
- Depending on the
limit
payload value sent it can occur that part of the order would be executed immediately as a market order, and the rest would be placed as a limit order.- In the case part of the simulated order is executed immediately as a market order, the corresponding fee would be all the market order fee for the amount immediately executed + the corresponding fee for the remaining limit order that would be placed.
Deposit/Withdrawal Fees
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())
This call returns an object with the following format:
{
"fee": {
"name": "withdrawal",
"percent": 0,
"base": ["0.00000015", "BTC"]
}
}
Provides all the related fees to the deposit or withdrawal of a given currency.
Keep in mind:
- These costs do not come from Buda, they are charged by the network of the given currency to execute a transaction. For example, the fee required to have a Bitcoin transaction included in the following 3 blocks.
- Some fiat currencies may incur a deposit/withdrawal fee.
- In case of making a deposit, it is your responsibility to include the necessary transaction fee for it to be confirmed in the corresponding network.
HTTP Request
GET /currencies/<currency>/fees/<transaction_type>
Path Parameters
Parameter | Description |
---|---|
currency |
Acronym of the currency being requested |
transaction_type |
Transaction type. It can be either deposit or withdrawal |
Response Details (JSON)
Key | Type | Description |
---|---|---|
name |
[string] | Transaction type |
percent |
[number] | Variable cost per transaction (percantage) |
base |
[amount, currency] | Fixed cost per transaction |
Private Endpoints
Private endpoints access a user's private information, place/cancel orders, and deposit/withdraw funds.
In order to access these endpoints, it is necessary to authenticate the user. This is done by using an API-KEY and a signature derived from an API-SECRET.
Authentication
Authentication example using the Requests library
import base64
import hmac
import time
import requests.auth
class BudaHMACAuth(requests.auth.AuthBase):
"""Appends the HMAC Buda authentication to the Request object"""
def __init__(self, api_key: str, secret: str):
self.api_key = api_key
self.secret = secret
def get_nonce(self) -> str:
# 1. Generate nonce (timestamp in microseconds)
return str(int(time.time() * 1e6))
def sign(self, r, nonce: str) -> str:
# 2. Prepare string for signing
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. Get the signature
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. Append API-KEY, nonce and signature to request header
r.headers['X-SBTC-APIKEY'] = self.api_key
r.headers['X-SBTC-NONCE'] = nonce
r.headers['X-SBTC-SIGNATURE'] = signature
return r
# To authenticate an API call the `auth` parameter must be included in the request
request = requests.post(url, auth=BudaHMACAuth(api_key, secret))
We did our best to make a secure but simple authentication process. I think it ended up being more secure than simple, but don't worry, there are many great examples.
The first step is to generate an API-KEY for the authenticated API calls. This can be done in "Mi cuenta", where you can generate an API-KEY and an API-SECRET.
Once you have your API-KEY you can use it to request private endpoints. Buda.com expects all private calls to be signed following these steps:
1. Generate a nonce
The nonce is an integer that must be greater than the most recently used nonce. This protects you from a "Man in the middle" attack. The recommended way to do this is by using timestamps.
2. Prepare string for signing
The string content is as follows:
{GET|POST|PUT} {path} {base64_encoded_body} {nonce}
Where:
path
: Corresponds to the complete request path, including the query string without the host. For example:/api/v1/orders?open=true
base64_encoded_body
: Corresponds to the request body with Base64 encoding. This value can be empty if the request doesn't have a body (like a GET request).nonce
: this is the number we explained before.- Every space in the string must be taken into account.
For example:
GET /api/v1/orders?open=true 423874932432
3. Get the signature
The signature is an authentication message based on an HMAC hash, which is generated using the SHA-384 hash function on the API-SECRET and string generated on the previous step 😱. This string must be encoded in hexadecimal format.
Don't worry, most programming languages have an HMAC generator function included in standard libraries. An example can be seen over to your right -->.
4. Append API-KEY, nonce and signature to request header
For example:
Header | Value |
---|---|
X-SBTC-APIKEY |
0faea2f360a508a6d105a3bb60247af0 |
X-SBTC-NONCE |
145511231131231 |
X-SBTC-SIGNATURE |
5c873eddb1117b930b1caa058ada3f7... |
Pagination
This is an example of a paginated response
{
"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
}
}
Some responses may include a lot of data, so in order to prevent our server from being overworked and delaying the response, we use pagination to separate the response into smaller segments.
If an endpoint uses pagination, then it will accept the following query parameters:
Query Parameters
Parameter | Default | Description |
---|---|---|
per |
20 | Elements per page [min: 1, max: 300] |
page |
1 | The number of pages to receive. The first page received is 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:
These endpoint's response will additionally include a meta
object with the following format:
Key | Type | Description |
---|---|---|
total_pages |
[int] | Total page count that represents the complete response |
total_count |
[int] | Total element count the represents the complete response |
current_page |
[int] | Page number that represents the data in the current response |
Account Information
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())
This call returns an object with the following format:
{
"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",
}
}
Shows your account's personal information.
HTTP Request
GET /me
Response Details (JSON)
Key | Type | Description |
---|---|---|
id |
[string] | Account ID |
email |
[string] | Email address associated to account |
display_name |
[string] | Full name associated to account |
monthly_transacted |
[amount, currency] | Amount transacted in the last 30 days |
pubsub_key |
[string] | PubSub Key for WebSocket authentication |
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())
This call returns an object with the following format:
{
"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"]
},
...
]
}
Example for one currency:
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())
This call returns an object with the following format:
{
"balance": {
"id": "BTC",
"amount": ["11.5274815", "BTC"],
"available_amount": ["10.5274815", "BTC"],
"frozen_amount": ["1.0", "BTC"],
"pending_withdraw_amount": ["0.0", "BTC"]
}
}
This endpoint shows your account's balance for each currency.
HTTP Request
GET /balances
GET /balances/<currency>
Path Parameters
Parameter | Description |
---|---|
currency |
(optional) - Acronym for given currency: btc , eth , clp ,... If no currency is provided then all currencies are considered |
Response Details (JSON)
Key | Type | Description |
---|---|---|
id |
[currency] | Acronym for given currency |
amount |
[amount, currency] | Total balance for the account |
available_amount |
[amount, currency] | Available amount for order placement and withdrawals |
frozen_amount |
[amount, currency] | Frozen amount due to placed limit orders |
pending_withdrawal_amount |
[amount, currency] | Frozen amount due to withdrawal request |
My Orders
Example:
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())
This call returns an object with the following format:
{
"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
}
}
An order is a fundamental part of any exchange. It consists of either a sell or buy offer (type
) for a ciertain amount
of a market's base_currency
(usually cypto) at a limit or market price.
Market orders
If the order type (price_type
) is market
, the order will be immediatly executed at the best possible price, taking account the order amount
, with the current order book. These orders are traded against the current limit orders.
Limit orders
If the order type (price_type
) is limit
, an order is created at the desired price, which will execute only if it can trade against an opposing market order.
- For
Bid
orders,limit
price is the highest price you are willing to buy at. - For
Ask
orders,limit
price is the lowest price you are willing to sell at.
These orders are programed to execute immediately after their creation, but this process occurs asynchronously since each order enters a FIFO queue. A limit order can be partially filled, since an opposing market order may not cover it entirely.
If you need to consult for various states then you can set the state
request payload parameter like this: state
=state1,state2,state3
.
Tipos de Órdenes Limit
Good-Till-Canceled (gtc
): A limit order that will remain open until it is completely filled or canceled.
Immediate-Or-Cancel (ioc
): Must be executed immediately. Any portion of an IOC order that cannot be filled immediately will be canceled.
Fill-Or-Kill (fok
): Must be executed immediately. If the FOK order is not completely filled immediately, the entire order will be canceled.
Post Only (post_only
): Must be executed as a Limit/Maker order. If any portion of the order would be filled as a Market/Taker, then the complete order is canceled.
Good-Till-Date (gtd): A limit order that will remain active until it is filled or the expiration date is reached.
Stop Orders
Stop orders are designed to be executed automatically when the market price reaches the set trigger price (Stop Price
). There are two main types: Stop Market and Stop Limit.
Stop Market: This order becomes a market order when the price reaches the trigger price. Execution is carried out at the best available price at that moment.
Stop Limit: In addition to the trigger price, a limit price is set. The order is activated upon reaching the trigger price and is executed as a limit order at the limit price or better.
Then, you must choose whether this order will be a Stop Loss
or Take Profit
. This will depend on the Type
and Stop Price
you choose in relation to the last market price.
For example, if you choose a Stop Loss
of Bid
type, with a Stop Price
higher than the Last Price
, then the order will remain waiting to be activated with a price change. On the other hand, if the price is lower than the Last Price
, it will be activated immediately, as the condition that the Last Price
be higher than the Stop Price
is met.
In the latter case, if you want the order to remain waiting to be activated by a price drop, this order must be a Take Profit
.
If you want the stop order to remain waiting for the Stop Price
, without being activated immediately, you can use this reference table:
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 |
New Order
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',
'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())
This call returns an object with the following format:
{
"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"
}
}
Create a new order.
HTTP Request
POST /markets/<market_id>/orders
Path Parameters
Parameter | Description |
---|---|
market_id |
The market ID (for example: btc-clp , eth-btc , etc). |
Request Payload
Key | Required | Description |
---|---|---|
type |
Yes | Order side (Bid / Ask ) |
price_type |
Yes | Order type (limit / market ) |
limit:price |
Limit | Order price |
limit:type |
Limit | Limit order type (gtc / ioc / fok / post_only / gtd ) (more details) |
stop:stop_price |
Stop | Stop Price for the order |
stop:type |
Stop | Stop Order type (stop_loss / take_profit ) |
amount |
Yes | Order size |
client_id |
No | Unique ID you can assign to an order. The request will be rejected if the ID was aleady used by you. |
* If limit
cotains only the price value, then it will be executed as a gtc
limit order.
Response Details (JSON)
Key | Type | Description |
---|---|---|
amount |
[amount, currency] | Pending order volume |
created_at |
[string] | Order creation timestamp |
fee_currency |
[currency] | Currency in which the fee is payed in (For example: "BTC", "CLP" ,"COP") |
id |
[int] | Order ID |
client_id |
[string] | Order Client ID |
limit |
[amount, currency] | Order price |
market_id |
[string] | Market ID |
original_amount |
[amount, currency] | Original order volume |
paid_fee |
[amount, currency] | Fee paid by the order |
price_type |
[string] | Order type (limit / market ) |
order_type |
[string] | Specific Order type (market / gtc / ioc / fok / post_only ) |
state |
[string] | Order state |
total_exchanged |
[amount, currency] | Total traded |
traded_amount |
[amount, currency] | Volume transacted |
type |
[string] | Order side (Bid / Ask ) |
Order state
An order has many states during its life cycle:
State | Description |
---|---|
received |
The order has been received but hasn't been processed yet. |
pending |
The max amount an order can cost is frozen from your balance, and the order can start matching with other orders. |
active |
The order's state is either received or pending . |
traded |
The order has been completely traded. |
canceled |
The order has been canceled and the max cost is unfrozen from the balance. |
canceled_and_traded |
The order has been canceled but has been partially traded. |
unprepared |
There aren't sufficient funds to process the order (only for limit orders). |
HTTP Request
GET /markets/<market_id>/orders
Path Parameters
Parameter | Description |
---|---|
market_id |
The market ID (for example: btc-clp , eth-btc , etc). |
Query Parameters
Parameter | Default | Description |
---|---|---|
state |
None | Request order with certain state |
Response Details (JSON)
Key | Type | Description |
---|---|---|
amount |
[amount, currency] | Pending order volume |
created_at |
[string] | Order creation timestamp |
fee_currency |
[currency] | Currency in which the fee is payed in (For example: "BTC", "CLP" ,"COP") |
id |
[int] | Order ID |
client_id |
[string] | Order Client ID |
limit |
[amount, currency] | Order price |
market_id |
[string] | Market ID |
original_amount |
[amount, currency] | Original order volume |
paid_fee |
[amount, currency] | Fee paid by the order |
price_type |
[string] | Order type (limit / market ) |
order_type |
[string] | Specific Order type (market / gtc / ioc / fok / post_only ) |
state |
[string] | Order state |
total_exchanged |
[amount, currency] | Total traded |
traded_amount |
[amount, currency] | Volume transacted |
type |
[string] | Order side (Bid / Ask ) |
Order Details
Example:
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())
This call returns an object with the following format:
{
"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",
"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"]
}
}
Provides all details relevant to an order.
HTTP Request
GET /orders/<id>
Path Parameters
Parameter | Description |
---|---|
id |
Order ID to request |
Response Details (JSON)
Key | Type | Description |
---|---|---|
amount |
[amount, currency] | Pending order volume |
created_at |
[string] | Order creation timestamp |
fee_currency |
[currency] | Currency in which the fee is payed in (For example: "BTC", "CLP" ,"COP") |
id |
[int] | Order ID |
client_id |
[string] | Order Client ID |
limit |
[amount, currency] | Order price |
market_id |
[string] | Market ID |
original_amount |
[amount, currency] | Original order volume |
paid_fee |
[amount, currency] | Fee paid by the order |
price_type |
[string] | Order type (limit / market ) |
order_type |
[string] | Specific Order type (market / gtc / ioc / fok / post_only ) |
state |
[string] | Order state |
total_exchanged |
[amount, currency] | Total traded |
traded_amount |
[amount, currency] | Volume transacted |
type |
[string] | Order side (Bid / Ask ) |
Cancel Order
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())
This call returns an object with the following format:
{
"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": "pending",
"total_exchanged": ["0.0", "CLP"],
"traded_amount": ["0.0", "BTC"],
"type": "Bid"
}
}
Provides endpoint for canceling an order. If the request provides a correct response, then the order is guaranteed to have been submitted for cancelation. This process can have a delay depending on the trading engine's load.
HTTP Request
PUT /orders/<id>
Path Parameters
Parameter | Description |
---|---|
id |
Order ID requested for cancelation |
Request Payload
Key | Required | Description |
---|---|---|
state |
Yes | Must indicate "canceling" |
Response Details (JSON)
Key | Type | Description |
---|---|---|
amount |
[amount, currency] | Pending order volume |
created_at |
[string] | Order creation timestamp |
fee_currency |
[currency] | Currency in which the fee is payed in (For example: "BTC", "CLP" ,"COP") |
id |
[int] | Order ID |
client_id |
[string] | Order Client ID |
limit |
[amount, currency] | Order price |
market_id |
[string] | Market ID |
original_amount |
[amount, currency] | Original order volume |
paid_fee |
[amount, currency] | Fee paid by the order |
price_type |
[string] | Order type (limit / market ) |
order_type |
[string] | Specific Order type (market / gtc / ioc / fok / post_only ) |
state |
[string] | Order state |
total_exchanged |
[amount, currency] | Total traded |
traded_amount |
[amount, currency] | Volume transacted |
type |
[string] | Order side (Bid / Ask ) |
Order Details by Client ID
Example:
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())
This call returns an object with the following format:
{
"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"]
}
}
Provides all details relevant to an order using a client_id
.
HTTP Request
GET /orders/by-client-id/<client_id>
Path Parameters
Parameter | Description |
---|---|
client_id |
Order Client ID to request |
Response Details (JSON)
Key | Type | Description |
---|---|---|
amount |
[amount, currency] | Pending order volume |
created_at |
[string] | Order creation timestamp |
fee_currency |
[currency] | Currency in which the fee is payed in (For example: "BTC", "CLP" ,"COP") |
id |
[int] | Order ID |
client_id |
[string] | Order Client ID |
client_id |
[string] | Order Client ID |
limit |
[amount, currency] | Order price |
market_id |
[string] | Market ID |
original_amount |
[amount, currency] | Original order volume |
paid_fee |
[amount, currency] | Fee paid by the order |
price_type |
[string] | Order type (limit / market ) |
order_type |
[string] | Specific Order type (market / gtc / ioc / fok / post_only ) |
state |
[string] | Order state |
total_exchanged |
[amount, currency] | Total traded |
traded_amount |
[amount, currency] | Volume transacted |
type |
[string] | Order side (Bid / Ask ) |
Cancel Order by 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())
This call returns an object with the following format:
{
"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"
}
}
Provides endpoint for canceling an order by client_id
. If the request provides a correct response, then the order is guaranteed to have been submitted for cancelation. This process can have a delay depending on the trading engine's load.
HTTP Request
PUT /orders/by-client-id/<client_id>
Path Parameters
Parameter | Description |
---|---|
client_id |
Order Client ID requested for cancelation |
Request Payload
Key | Required | Description |
---|---|---|
state |
Yes | Must indicate "canceling" |
Response Details (JSON)
Key | Type | Description |
---|---|---|
amount |
[amount, currency] | Pending order volume |
created_at |
[string] | Order creation timestamp |
fee_currency |
[currency] | Currency in which the fee is payed in (For example: "BTC", "CLP" ,"COP") |
id |
[int] | Order ID |
client_id |
[string] | Order Client ID |
client_id |
[string] | Order Client ID |
limit |
[amount, currency] | Order price |
market_id |
[string] | Market ID |
original_amount |
[amount, currency] | Original order volume |
paid_fee |
[amount, currency] | Fee paid by the order |
price_type |
[string] | Order type (limit / market ) |
order_type |
[string] | Specific Order type (market / gtc / ioc / fok / post_only ) |
state |
[string] | Order state |
total_exchanged |
[amount, currency] | Total traded |
traded_amount |
[amount, currency] | Volume transacted |
type |
[string] | Order side (Bid / Ask ) |
Cancel All
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())
This call returns an object with the following format:
{
"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,
...
}]
}
Endpoint that lets you cancel all open orders. You can specify a set of markets and choose an orderbook side. If the request returns a correct response, then the order is guaranteed to have been submitted for cancellation. This process may take a bit of time depending on the trading engine's load.
If either the market
or type
parameter is not defined, then all possible markets and/or books will be canceled. This endpoint counts as only one operation in terms of the trading rate limit.
HTTP Request
DELETE /orders
Request Payload
Key | Required | Description |
---|---|---|
market |
No | Market ID to cancel (Examples: btc-clp , btc-eth , btc-clp,btc-eth ) |
type |
No | Orderbook side to cancel (This can be Bid or Ask ) |
Response Details (JSON)
Key | Type | Description |
---|---|---|
amount |
[amount, currency] | Pending order volume |
created_at |
[string] | Order creation timestamp |
fee_currency |
[currency] | Currency in which the fee is payed in (For example: "BTC", "CLP" ,"COP") |
id |
[int] | Order ID |
client_id |
[string] | Order Client ID |
limit |
[amount, currency] | Order price |
market_id |
[string] | Market ID |
original_amount |
[amount, currency] | Original order volume |
paid_fee |
[amount, currency] | Fee paid by the order |
price_type |
[string] | Order type (limit / market ) |
order_type |
[string] | Specific Order type (market / gtc / ioc / fok / post_only ) |
state |
[string] | Order state |
total_exchanged |
[amount, currency] | Total traded |
traded_amount |
[amount, currency] | Volume transacted |
type |
[string] | Order side (Bid / Ask ) |
Batch Orders
import requests
url = f'https://www.buda.com/api/v2/orders'
auth = BudaHMACAuth(api_key, secret)
response = requests.post(url, auth=auth, json={
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())
This call returns an object with the following format:
{
"success": true
}
Create or cancel orders by batches.
HTTP Request
POST /orders
Request Payload
Key | Required | Description |
---|---|---|
mode |
Yes | Batch order type (place / cancel ) |
type |
Yes | order side (Bid / Ask ) |
price_type |
Yes | Order type (limit / market ) |
limit |
Limit | Order price |
amount |
Yes | Order volume |
market_name |
Yes | The market ID (for example: btc-clp , eth-btc , etc). |
Response Details (JSON)
Key | Type | Description |
---|---|---|
success |
[bool] | true when the batch order has been successful |
Deposit/Withdrawal History
Deposit example:
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())
This call returns an object with the following format:
{
"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
}
}
Withdrawal example:
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())
This call returns an object with the following format:
{
"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
}
}
Provides deposit and withdrawal history for fiat and crypto.
Each deposit or withdrawal can have one of the following states
:
State | Description |
---|---|
pending_confirmation |
The deposit hasn't yet been confirmed |
confirmed |
The deposit has been confirmed and added to your account |
rejected |
The deposit has been rejected |
retained |
The deposit has been retained, usually because it has breached the terms of service agreement |
HTTP Request
GET /currencies/<currency>/deposits
GET /currencies/<currency>/withdrawals
Path Parameters
Parameter | Description |
---|---|
currency |
Acronym of the currency being requested |
Query Parameters
Parameter | Default | Description |
---|---|---|
state |
None | Request deposit or withdrawal with certain state |
Response Details (JSON)
Key | Type | Description |
---|---|---|
id |
[int] | Deposit/withdrawal ID |
created_at |
[time] | Creation timestamp |
amount |
[amount, currency] | Amount requested for deposit/withdrawal |
currency |
[currency] | Currency for deposit/withdrawal |
fee |
[amount, currency] | Fee incurred by deposit/withdrawal |
state |
[string] | Request current state (For example: confirmed , rejected ) |
deposit_data / withdrawal_data |
[object] | Object with deposit/withdrawal details |
type |
[string] | Data type delivered (For example: btc_deposit_data ,fiat_withdrawal_data ) |
address |
[address] | Deposit address |
target_address |
[address] | Withdrawal address |
tx_hash |
[string] | Transaction ID |
New Fiat Deposit
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())
This call returns an object with the following format:
{
"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"
}
}
Generate a new depoist request.
The fiat deposit process has 2 steps:
- Make a bank deposit.
- Generate a new fiat deposit request for the deposited amount using this endpoint.
HTTP Request
POST /currencies/<currency>/deposits
URL Parameters
Parameter | Description |
---|---|
currency |
Acronym of the currency being deposited |
Request Payload
Key | Required | Description |
---|---|---|
amount |
Yes | Depsit size |
simulate |
No | Allows for a deposit simulation |
Response Details (JSON)
Key | Type | Description |
---|---|---|
id |
[string] | Deposit/withdrawal ID hash |
created_at |
[time] | Creation timestamp |
amount |
[amount, currency] | Amount requested for deposit/withdrawal |
currency |
[currency] | Currency for deposit/withdrawal |
fee |
[amount, currency] | Fee incurred by deposit/withdrawal |
state |
[string] | Request current state (For example: confirmed , rejected ) |
deposit_data |
[array] | Array with relevant data |
New Fiat Withdrawl
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())
This call returns an object with the following format:
{
"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",
}
}
}
Generate a new withdrawal request for a requested currency and amount to the most recent registered FIAT account.
HTTP Request
POST /currencies/<currency>/withdrawals
Path Parameters
Parameter | Description |
---|---|
currency |
Acronym of the currency being withdrawn (ARS , CLP , COP , PEN ) |
Request Payload
Key | Required | Description |
---|---|---|
amount |
Yes | Withdrawal size |
simulate |
No | Allows you to simulate withdrawal request |
Response Details (JSON)
Key | Type | Description |
---|---|---|
id |
[int] | Withdrawal ID |
created_at |
[time] | Creation timestamp |
amount |
[amount, currency] | Amount requested for withdrawal |
currency |
[currency] | Currency for withdrawal |
fee |
[amount, currency] | Fee incurred by withdrawal |
state |
[string] | Request current state (For example: confirmed , rejected ) |
withdrawal_data |
[object] | Object with withdrawal data |
withdrawal_data: type |
[string] | Type of data provided (For example: btc_withdrawal_data ,fiat_withdrawal_data ) |
New Crypto Deposit
import time
import requests
currency = 'btc'
auth = BudaHMACAuth(api_key, secret)
# Create a new address and obtain it's 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']
# Wait for the new address to be created
time.sleep(3)
# Obtain the new address
url = f'https://www.buda.com/api/v2/currencies/{currency}/receive_addresses/{address_id}'
response = requests.get(url, auth=auth)
print(response.json())
This call returns an object with the following format:
{
"receive_address": {
"id": 1,
"created_at": "2017-04-26T13:47:42.000Z",
"address": "mo366JJaDU5B1hmnPygyjQVMbUKnBC7DsY",
"ready": true,
"used": false
}
}
Generate a new crypto deposit address from Buda.com.
Keep in mind that the address creation is an asynchronous process, so first, you have to request a deposit and then request the address using the id provided in the first request.
HTTP Request
Request | Description |
---|---|
POST /currencies/<currency>/receive_addresses |
Request the creation of a new crypto deposit address. |
GET /currencies/<currency>/receive_addresses/<id> |
Request the deposit address for the id generated from the previous endpoint. |
GET /currencies/<currency>/receive_addresses |
Provides a list of all cypto addresses related to the account (uses pagination). |
URL Parameters
Parameter | Description |
---|---|
currency |
Acronym of the currency being deposited |
id |
Receive address ID |
Response Details (JSON)
Key | Type | Description |
---|---|---|
id |
[int] | Receive address ID |
created_at |
[time] | Timestamp |
address |
[address] | Assigned address for deposit |
ready |
[bool] | Is the address is ready for use? |
used |
[bool] | Has the address already been used before? |
New Crypto Withdrawal
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())
This call returns an object with the following format:
{
"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"
}
}
}
Generate a new withdrawal request for a requested currency and amount.
HTTP Request
POST /currencies/<currency>/withdrawals
Path Parameters
Parameter | Description |
---|---|
currency |
Acronym of the currency being withdrawn |
Request Payload
Key | Required | Description |
---|---|---|
amount |
Yes | Withdrawal size |
withdrawal_data: target_address |
Yes | Withdrawal target address |
amount_includes_fee |
No | Determines if the withdrawal fee should be subtracted from the withdrawal amount |
simulate |
No | Allows you to simulate withdrawal request |
Response Details (JSON)
Key | Type | Description |
---|---|---|
id |
[int] | Withdrawal ID |
created_at |
[time] | Creation timestamp |
amount |
[amount, currency] | Amount requested for withdrawal |
currency |
[currency] | Currency for withdrawal |
fee |
[amount, currency] | Fee incurred by withdrawal |
state |
[string] | Request current state (For example: confirmed , rejected ) |
withdrawal_data |
[object] | Object with withdrawal data |
withdrawal_data: type |
[string] | Type of data provided (For example: btc_withdrawal_data ,fiat_withdrawal_data ) |
withdrawal_data: target_address |
[address] | Withdrawal target address |
withdrawal_data: tx_hash |
[string] | Transaction ID |
New Lightning Withdrawal ⚡️
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."
}
}
}
Pay a Lightning Network Invoice ⚡️
This endpoint enables you to pay for services using Bitcoin through this network. You can check Mainnet lightning network stores for a list of available services.
Keep in mind that to pay through the Lightning Network you first need to request a payment Invoice from the receiver.
HTTP Request
POST /reserves/ln-btc/withdrawals
Request Payload
Key | Required | Description |
---|---|---|
amount |
Yes | Payment amount (in BTCs) |
withdrawal_data: payment_request |
Yes | Lightning Network Invoice |
simulate |
No | Allows you to simulate payment request |
Response Details (JSON)
Key | Type | Description |
---|---|---|
id |
[int] | Withdrawal ID |
created_at |
[time] | Creation timestamp |
amount |
[amount, currency] | Amount requested for withdrawal |
currency |
[currency] | Currency for withdrawal |
fee |
[amount, currency] | Fee incurred by withdrawal |
state |
[string] | Request current state (For example: confirmed , rejected ) |
withdrawal_data |
[object] | Object with withdrawal data |
withdrawal_data: type |
[string] | It will always say lightning_network_withdrawal_data |
withdrawal_data: payment_request |
[address] | Invoice used |
withdrawal_data: payment_error |
[string] | In case there is an error it will be shown here |
New Lightning Deposit ⚡️
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'
}
}
Create a Lightning Network Invoice ⚡️
You can use this endpoint to request a Bitcoin payment using this network. Send this invoice to whoever you want.
HTTP Request
POST /lightning_network_invoices
Request Payload
Key | Required | Description |
---|---|---|
amount_satoshis |
Yes | Invoice amount in satoshis. |
currency |
Yes | Must be BTC |
memo |
No | Invoice brief description |
expiry_seconds |
No | Invoice expiry time in seconds |
Response Details (JSON)
Key | Type | Description |
---|---|---|
id |
[int] | Invoice ID |
currency |
[time] | Invoice currency |
encoded_payment_request |
[string] | Encoded invoice |
Rate Limits
We take some precautions to protect ourselves from DoS attacks or abuse of our API. This is done to ensure that our service is stable for all our users.
If your request reaches our limit, you will receive a response with the 429
code, and you must wait before trying again.
These limits are calculated in 1 minute and 1 second intervals. For 1 second intervals, as long as you do less than 20 requests/second
you should not trigger our limit.
General
Anonymous (unauthenticated) calls will be limited by IP address at a rate of 120 requests/minute
.
Authenticated calls will be limited by api key at a rate of 375 requests/minute
.
Trading (placing and canceling orders)
The endpoints used to create and cancel orders are limited by market. This limit is dependant on your account tier. You can check out more details here.
Tier | 30 day volume | Rate Limit |
---|---|---|
< 4 | < $100 000 | 100 requests/minute |
>= 4 | >= $100 000 | 250 requests/minute |
Errors
We do our best to adhere to the HTTP error conventions. If an error occurs, our API sends a JSON object containing more details.
Example error response (HTTP 403):
{
"code": "forbidden",
"message": "You dont have access to this resource"
}
Here is a more detailed explanation of HTTP errors you may encounter while using our API:
HTTP Code | Explanation |
---|---|
400 | Bad Request -- The request has an incorrect syntaxis. If you are making a POST request, be sure you are sending a JSON object in the body , and using the Content-Type: application/json header. |
401 | Unauthorized -- Your API Key has expired or is not authenticating in the correct format. |
403 | Forbidden -- The request is valid, but you don't have the required permission for this action. |
404 | Not Found -- Resource not found. Checck URL you are requesting. |
405 | Method Not Allowed -- The method received in the request-line is incorrect (for example: using GET instead of POST ). |
406 | Not Acceptable -- You have requested an unsupported format. Check that your header's Accept paramter is requesting JSON format (Accept: application/json ). |
410 | Gone -- The resource being requested is no longer available. |
422 | Unprocessable entity -- You have sent information in an unsupported format. Check that the object you are sending as body in the POST request is in line with the documentation. (for example: Most of the strings that you must send are case-sensitive). |
429 | Too Many Requests -- You have surpassed our Rate Limits |
500 | Internal Server Error -- There has been a problem with our server and are doing our best to fix it 🔥. Please try again later. |
503 | Service Unavailable -- We are temporarily out of service due to maintenance. Please try again later. |
Websockets API
Introduction
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)
All events have the following structure:
{
ev: 'book-sync',
ts: '123123123.123123',
mk: 'BTC-CLP',
...
}
WebSockets allow you to open channels between client and server, so that you can stream data in real-time. With this API you can communicate with our server and receive responses based on events, instead of having to constantly query.
We currently use Nchan for this real-time communication. You can find more information on how Nchan works with WebSockets at https://nchan.io/#subscriber-endpoints.
To access the authenticated WebSockets, you will need your pubsub_key
, which can be found using the account information endpoint.
Our WebSocket's URLs usually have this format:
wss://realtime.buda.com/sub?channel=[channel]
For cases where authentication is required, they have the following format:
wss://realtime.buda.com/sub?channel=[channel]@[pubsub_key]
For cases where you want to subscribe to multiple channles, they have the following format:
wss://realtime.buda.com/sub?channel=[channel1,channel2,channel3@pubsub_key]
Where:
Path Parameters
Parameter | Value |
---|---|
channel |
Channel to be used |
pubsub-key |
Account's PubSub key, which can be found in account information. |
Event Details
Key | Description |
---|---|
ev |
Event name |
ts |
Unix timestamp (seconds.nanoseconds ) |
mk |
Corresponding market id (for example: ETH-BTC , BTC-CLP , etc) |
Public Channels
Order Book
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)
This channel's events have the following structure:
{
ev: 'book-changed',
change: [
'asks'|'bids',
<price level>,
<amount change>
]
}
{
ev: 'book-sync',
order_book: <serialized order book>
}
Subscribe to the order book channel. A complete snapshot of the order book is sent every 5 minutes.
Channel endpoint
channel=book@<market_id>
Path Parameters
Parameter | Description |
---|---|
market_id |
Market ID (for example: btcclp , ethbtc , etc). You can obtain a complete list of all markets by calling the Markets endpoint. |
Public 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)
This channel's events have the following structure:
{
ev: 'trade-created',
trade: [
<timestamp>,
<traded amount>,
<traded price>,
'buy'|'sell',
<id>
]
}
Subscribe to the public trades history channel.
Channel endpoint
channel=trades@<market_id>
Path Parameters
Parameter | Description |
---|---|
market_id |
Market ID (for example: btcclp , ethbtc , etc). You can obtain a complete list of all markets by calling the Markets endpoint. |
Event Details
Key | Description |
---|---|
ev |
Event name |
timestamp |
Unix timestamp of most recent trade |
amount |
Most recent traded amount |
price |
Most recent traded price |
Private Channels
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)
This channel's events have the following structure:
{
ev: 'balance-updated',
balance: <serialized balance>
}
Subscribe to the balance change channel.
Channel endpoint
channel=balances@<pubsub_key>
Path Parameters
Parameter | Description |
---|---|
pubsub_key |
Account's PubSub key, which can be found in account information. |
My Orders
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)
This channel's events have the following structure:
{
ev: 'order-created'|'order-updated',
order: <serialized order>
}
Subscribe to the order change channel.
Channel endpoint
channel=orders@<pubsub_key>
Path Parameters
Parameter | Description |
---|---|
pubsub_key |
Account's PubSub key, which can be found in account information. |
Confirmed Deposits
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)
This channel's events have the following structure:
{
ev: 'deposit-confirmed',
deposit: <serialized deposit>
}
Subscribe to the confirmed deposit channel.
Channel endpoint
channel=deposits@<pubsub_key>
Path Parameters
Parameter | Description |
---|---|
pubsub_key |
Account's PubSub key, which can be found in account information. |
OAuth
Our API features OAuth for secure and standardized authorization. OAuth enables users to securely authorize third-party applications to access their data without sharing their complete credentials. Need more information? Reach out to us at [email protected].
Latest changes
February 16, 2024
- Added
gtd
andstop
order types
Decemeber 13, 2023
- Added
OAuth
support - Increased rate limit for general authenticated requests
June 20, 2023
- Added
fok
andpost_only
order types - Added rate limit by tier
May 31, 2023
- Added order type
ioc
January 12, 2023
- Added All Tickers endpoint
GET /api/v2/tickers
December 19, 2022
- Changed deposit
id
from int to string
November 14, 2022
- Increased rate limit
- Added Cancel All endpoint
DELETE /api/v2/orders
October 24, 2022
- Changed rate limit to be limited by market
- Added
client_id
to orders - Added
ts
ymk
to websocket events - Added multichannel support for websockets
- Added
canceled_and_traded
state to order
August 30 2022
- Added fiat withdrawal endpoint
- Added
active
order state
May 30 2022
- Added a new Websocket API
March 17 2022
- Added english translation for documentation
- Changed rate limit
February 17 2022
- Added maker and taker fees to Markets endpoint