Foxbit REST API (3.0)

We provide an OpenAPI specification for our REST API, which is a standard way to describe the API's endpoints, request and response formats, authentication methods, and other details. This specification can be downloaded at: OpenAPI Specification.
We also provide a Postman collection and environment to help you get started with our API. The instructions are available in the Integrating with Postman section.
Follow our Status Page for real-time updates on system performance and maintenance schedules. You can also subscribe to receive notifications about any incidents or scheduled maintenance that may affect the API's availability.
For support with the Foxbit API, please visit our Help Center.

Introduction

Welcome to the official Foxbit trader and developer documentation! Here, you'll find everything you need to know to integrate and utilize our services effectively. Whether you're a seasoned trader or just starting out, our comprehensive documentation provides clear guidance on how to make the most out of our API.

Features

  • Robust Functionality: Explore the wide range of functionalities our API offers, including fetching real-time market data, placing orders, managing accounts, and much more.
  • Detailed Guides: Step-by-step guides and tutorials help you get started quickly and navigate complex features effortlessly.
  • Comprehensive Reference: Dive deep into our API endpoints, parameters, and response structures with our detailed reference documentation.

We also have a full API usage examples repository demonstrating how to integrate and utilize our API in various programming languages:

Start Exploring

Ready to get started? Dive into our documentation and unleash the full potential of our Exchange API.
Whether you're building trading automations, conducting research, or developing innovative solutions, our API provides the tools you need to succeed.

Happy coding! 🚀

Try out

Want to explore the API without writing a single line of code? We provide an interactive documentation (Swagger) where you can browse every endpoint of this documentation and execute the public ones straight from your browser.

Open the interactive API console.

How it works

  • Public endpoints (Market Data, Banks, System...) can be executed right away — open the endpoint, fill the parameters and hit Execute. Requests run against the real environment behind this documentation.
  • Authenticated endpoints (marked with a padlock) are listed for reference but cannot be executed from the console: they require per-request signatures — HMAC-SHA256 or Ed25519 — and, for your security, the console never asks for your API credentials. To call them, use your own client following the Authentication section.

Throughout this documentation, public endpoints include a Try out link at the end of their description that takes you straight to that endpoint on the interactive page.

Changelog

A changelog is a record of all notable changes made to this API, including new features, bug fixes and updates. It helps users and developers stay informed about the evolution of the project. For more details, visit our changelog page.

Authentication

Before being able to sign any requests, you must create an API key via the Foxbit platform. Foxbit supports two authentication models, and the credentials you need to record depend on which one you choose:

  • HMAC (default) — Foxbit generates a symmetric key pair (Key and Secret). You must record both the Key and the Secret. The Secret cannot be recovered once lost — if you lose it, you must create a new API key. You sign requests with HMAC-SHA256(secret, stringToSign).
  • Ed25519 (asymmetric) — You generate the key pair locally and register only the public key on Foxbit; Foxbit returns the Key (API key identifier). You must record the Key and keep your private key safely stored on your side — Foxbit never sees it and cannot recover it. You sign requests with your private key.

Signing a request with HMAC

All private REST requests must contain the following headers:

  • X-FB-ACCESS-KEY The API key as a string.
  • X-FB-ACCESS-TIMESTAMP The current timestamp of your request. Must be in UNIX timestamp format, which represents the number of milliseconds since January 1, 1970 (the UNIX epoch UTC).
  • X-FB-ACCESS-SIGNATURE The hex-encoded signature. See details below for generating the signature.

Generating the hex-encoded signature

Use your API Secret to encrypt the prehash string using HMAC with the SHA-256 algorithm. The request body is a JSON string and needs to match the parameters passed to the API. Here's an example of how to generate the prehash string:

const preHash = timestamp + httpMethod + requestPath + queryString + rawBody

Where each component is:

  • timestamp — the same value sent in the X-FB-ACCESS-TIMESTAMP header.
  • httpMethod — the HTTP method in uppercase (e.g., GET, POST).
  • requestPath — the full path without the query string (e.g., /rest/v3/orders).
  • queryString — the query parameters concatenated as key1=value1&key2=value2, in the same order they are sent in the URL, using the decoded (raw) parameter values — do not percent-encode values in the prehash — and without the leading ?. If there are no query parameters, use an empty string.
  • rawBody — the raw JSON request body exactly as sent, or an empty string for requests without a body.

We provide example implementations for generating the signature (HMAC-SHA256) in various programming languages, including Javascript, GoLang, Python, and others.

Signing a request with asymmetric keys

The same three headers are required (X-FB-ACCESS-KEY, X-FB-ACCESS-TIMESTAMP, X-FB-ACCESS-SIGNATURE), but the signature is generated with your Ed25519 private key. You generate the key pair locally and register only the public key on the Foxbit platform — Foxbit never sees your private key.

Generate the key pair once on your machine:

openssl genpkey -algorithm ed25519 -out private.pem
openssl pkey -in private.pem -pubout -out public.pem

Register the contents of public.pem at Foxbit platform → Profile → API Key under "Generated by you".

Generating the hex-encoded signature

Use your private key to sign the prehash with Ed25519. The prehash string follows the same format as HMAC:

const preHash = timestamp + httpMethod + requestPath + queryString + rawBody
const signature = crypto.sign(null, Buffer.from(preHash), privateKey).toString('hex')

The signature is hex-encoded (always 128 characters).

Receive Window

The Receive Window mechanism lets a client specify a time tolerance around the server's clock to protect against replay attacks and drop any requests that arrive too late. By bounding how far “ahead” or “behind” a timestamp may be, the server can reject stale or delayed requests before they reach your API logic. For retry safety, we also support Idempotent Requests to ensure duplicate calls have no unintended side effects.

To define a tolerance window (in milliseconds) around the server's current time, you may include the optional header X-FB-RECEIVE-WINDOW in your request.

  • Accepted values: 1000 to 60000 milliseconds (1s-60s). Values outside this range are rejected with the error code 4013 (Invalid receive window header).
  • Example: with X-FB-RECEIVE-WINDOW: 15000, the server only accepts the request if its timestamp is within 15 seconds (before or after) of the server's current time.
  • Requests with timestamps outside this window are rejected with the error code 4014 (Timestamp is out of range).

To synchronize your clock, you may call GET /rest/v3/system/time which returns the server's current UNIX timestamp in milliseconds.

Rate Limit

Our rate limit allows a maximum number of requests (limit) within a time window (TTL).
For public endpoints, your IP address is used as the rate limit key. For private endpoints, your member SN (the unique serial number that identifies your account) is used instead.

If an endpoint does not have rate limit information in its documentation, then it uses our global rate limit values:

Limit TTL Block duration
300 requests 10 seconds 10 seconds

Endpoints with a specific rate limit (described in their documentation) override these values.

When the limit is exceeded, the API responds with HTTP status 429 and blocks further requests for the block duration:

{
  "error": {
    "message": "Too many requests.",
    "code": 429,
    "details": "Request limit exceeded, try again later."
  }
}

Rate limit headers

Every response from a rate-limited endpoint includes headers you can use to track your consumption and pace your requests before hitting the limit:

Header Present Description
X-FB-RATE-LIMIT-REQUESTS-LIMIT Always The maximum number of requests allowed in the current time window. This is your effective limit — if your account has an increased rate limit, it is already reflected here.
X-FB-RATE-LIMIT-REQUESTS-REMAINING Always How many requests you can still make in the current window. 0 means the next request will be rejected until the window resets.
X-FB-RATE-LIMIT-REQUESTS-RESET Always Seconds until the current window resets and your remaining quota is restored.
X-FB-RATE-LIMIT-RETRY-AFTER Only on 429 responses Seconds to wait before sending requests again.

Header names are case-insensitive (HTTP/2 delivers them in lowercase). Example of a 429 response:

HTTP/2 429
x-fb-rate-limit-requests-limit: 30
x-fb-rate-limit-requests-remaining: 0
x-fb-rate-limit-requests-reset: 2
x-fb-rate-limit-retry-after: 2

Idempotent Requests

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to create an order does not respond due to a network connection error, you can retry the request with the same idempotency key to guarantee that no more than one order is created.

To perform an idempotent request, provide an additional X-Idempotent: <key> header to the request.

Foxbit's idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result, including 500 errors.

An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions. Idempotency keys can be up to 36 characters long.

Keys are eligible to be removed from the system automatically after they're at least 72 hours old, and a new request is generated if a key is reused after the original has been pruned.

Results are only saved if an API endpoint started executing.

In case of concurrent requests, only one of them will be processed; the other request will return status code 409 and an error, and the second request is not saved by the idempotency.

All POST requests accept idempotency keys. Sending idempotency keys in GET, PUT or DELETE requests has no effect and should be avoided, as these requests are idempotent by definition.

API Codes

This section provides a list of codes that may be returned by the API.

Errors

If there is an error in the execution of the request or response, the payload will have the following format.

{
  "error": {
    "message": "Invalid symbol.",
    "code": 4004,
    "details": [
        "The market or asset symbol is invalid or was not found.",
    ]
  }
}

Some Common Examples

Code Message Description
400 Bad request. An unknown error occurred while processing request parameters.
429 Too many requests. Request limit exceeded. Try again later.
404 Resource not found. A resource was not found while processing the request.
500 Internal server error. An unknown error occurred while processing the request.
2001 Authentication error. Error authenticating request.
2002 Invalid signature. The signature for this request is not valid.
2003 Invalid access key. / Invalid session. The access key is missing, invalid, disabled, expired or not found; or the session for this request is not valid.
2004 Invalid timestamp. Invalid or missing timestamp.
2005 IP not allowed. The IP address {IP_ADDR} isn't on the trusted list for this API key.
2006 Timestamp out of window. The request timestamp is outside the allowed window. Check the client clock.
2010 This endpoint does not accept Ed25519 API keys at this time. Use an HMAC API key instead. Ed25519 API keys are not supported on this endpoint.
3001 Permission denied. Permission denied for this request.
3002 KYC required. A greater level of KYC verification is required to proceed with this request.
3003 Member disabled. This member is disabled. Please get in touch with our support for more information.
3004 Permission denied. Permission denied for this request. You have not allowed permissions.
3005 Permission denied. Permission denied for this request. You have missing permissions.
3006 Not eligible. Not eligible for this action. The required conditions are not met.
4001 Validation error. A validation error occurred.
4002 Insufficient funds. Insufficient funds to proceed with this request.
4003 Quantity below the minimum allowed. Quantity below the minimum allowed to proceed with this request.
4004 Invalid symbol. The market or asset symbol is invalid or was not found.
4005 Invalid idempotent. Characters allowed are "a-z", "0-9", "_" or "-", and 36 at max. We recommend UUID v4 in lowercase.
4006 Date range not available. Historical data is only available from a minimum date onwards, informed in the error details.
4007 Locked error. There was an error in your allocated balance, please contact us.
4008 Cannot submit order. The order cannot be created.
4009 Invalid level. The sub-member does not have the required level to create the transaction.
4011 Too many open orders. You have reached the limit of open orders per market/side.
4012 Too many simultaneous account operations. We are currently unable to process your balance change due to simultaneous operations on your account. Please retry shortly.
4013 Invalid receive window header. The receive window header is invalid. The value must be between 1000 and 60000.
4014 Timestamp is out of range. The timestamp is out of range. The request timestamp is outside the allowed time window specified on `X-FB-RECEIVE-WINDOW` header.
4015 Market side disabled. The market does not allow orders in this side.
5001 Service unavailable. The requested resource is currently unavailable. Try again later.
5002 Service under maintenance. The requested resource is currently under maintenance. Try again later.
5003 Market under maintenance. The market is under maintenance. Try again later.
5004 Market is not deep enough. The market is not deep enough to complete your request.
5005 Price out of range from market. The order price is out of range from market to complete your request.
5006 Significant price deviation detected, exceeding acceptable limits. The order price is exceeding acceptable limits from market to complete your request.

Cancellation Reasons

When an order is cancelled, the cancellation_reason field contains one of the codes below:

Cancellation reason codes

Code Description
NULL Order is not in the CANCELED state
1 Requested by user
100 Applied by Exchange
101 Applied before failure trade
102 Order Instant with insufficient volume remaining after being filled or not matched
103 Order StopMarket with insufficient volume remaining after being filled
104 Order matched with counter order from the same member
105 Member without document number on Exchange
107 Order StopLimit rejected because its stop price was already triggered when it reached the matching queue
109 Order OCO canceled because its stop price was already reached when it reached the matching queue, or because the market's matching engine does not support OCO orders
200 Limit order with TimeInForce Immediate or Cancel (IOC) did not match
201 Limit order with TimeInForce FillOrKill (FOK) found no trading volume
202 Order PostOnly matched
203 Order Limit or Market with insufficient volume remaining after being filled
204 Order Limit price out of range from Market
205 Significant price deviation detected, exceeding acceptable limits during execution. The remaining volume has been canceled due to a breached price limit
206 Order triggered the STP mechanism with EXPIRE_TAKER action
207 Order triggered the STP mechanism with EXPIRE_MAKER action
208 Order triggered the STP mechanism with EXPIRE_BOTH action
209 Order triggered the STP mechanism with DECREMENT action

Tutorials

How to manage a local copy of the order book

We already provide a full Websocket v3 flow to keep an in-memory order book, which you can see in our Websocket documentation.
We strongly recommend using it because it is simpler and purpose-built for this use case. When subscribing to the order book channel, set the snapshot parameter to true to receive an initial snapshot followed by incremental updates. With that, you can maintain an up-to-date local copy of the order book without needing to make additional REST API calls.

If you decide not to use the websocket snapshot, you can take a REST v3 snapshot and align it with the buffered websocket updates as described below. A runnable JavaScript implementation of this flow is available in the foxbit-api-samples repository.

Follow the steps below in sequential order

  1. Subscribe to the Websocket v3 stream to receive order book updates. When the connection is opened, buffer all incoming messages in memory (see documentation). Each update contains a sequence range (first_sequence_id and last_sequence_id) that represents the order book state covered by that message.
  2. Get a snapshot of the order book from our REST API v3 (see documentation). The property sequence_id returned refers to the current state of the order book at the snapshot time.
  3. Find the buffered websocket message whose sequence range includes the REST sequence_id. If it matches, apply the buffered updates starting from that message up to the most recent one.
  4. From this point forward, keep applying new websocket updates to your local copy and validate continuity: the next message's first_sequence_id must be equal to the previous message's last_sequence_id + 1.

Important

  • While listening to the stream, events can only be processed if their sequence range is continuous. If you find a gap where first_sequence_id is not equal to the previous last_sequence_id + 1, you need to restart the process from the beginning.
  • The data at each event contains the most recent quantity for a price level. If this quantity is zero, please, remove the price level.

How to declare the Travel Rule

A crypto deposit or withdrawal can be held by the Travel Rule: a deposit is not credited and a withdrawal is not sent until you declare who is on the other side. Both follow the same steps; where a call differs, both are linked.

  1. Find the held operation. A withdrawal is held after it is created with POST /withdrawals, and confirm it. List or read your deposits and withdrawals: one waits for the declaration when its state is AWAITING_TRAVEL_RULE and its travel_rule is null. Read the deposit or withdrawal.
  2. Pick the variant. Who holds the wallet the funds came from (deposit) or go to (withdrawal), and where it is, pick one of four bodies. Someone else goes under sender on a deposit and recipient on a withdrawal.
    Who holds the walletwallet_ownerwallet_type
    The client, in a private walletSELFSELF_HOSTED
    The client, at an Exchange/VASPSELFHOSTED
    Someone else, in a private walletTHIRD_PARTYSELF_HOSTED
    Someone else, at an Exchange/VASPTHIRD_PARTYHOSTED
  3. Check the fields your path asks. The same rules apply to both operations. The paths:
    1. Your own private wallet
    2. Your own account at an Exchange/VASP in Brazil
    3. Your own account at an Exchange/VASP abroad, and you are a resident of Brazil
    4. Your own account at an Exchange/VASP abroad, and you are not a resident of Brazil
    5. A counterparty in Brazil, and you are a resident of Brazil
    6. A counterparty in Brazil, and you are not a resident of Brazil
    7. A counterparty abroad
    Field1234567
    vasp_name✕✔✔✔✔/✕✔/✕✔/✕
    vasp_entity_country✕✔✔✔–/✕–/✕✔/✕
    sender (deposit) or recipient (withdrawal)✕✕✕✕✔✔✔
    fx_residence_country✕–○✔○✔–
    entity_category✕––C–C–
    institution_type (when entity_category is FINANCIAL_INSTITUTION)✕––✔–✔–
    same_economic_group (when the counterparty is a legal person)✕✕✕✕––C
    purpose_description$–$$–/$$$
    operation_reason✕–✔✔–✔✔

    ✔ required (400 when missing)
    ○ optional (fx_residence_country is BR when omitted)
    C company accounts only: required for a company account, refused with 422 for a personal one
    $ required above USD 50,000 (422 when missing), ignored up to it
    – ignored when sent
    ✕ not part of the variant (400 when sent)
    Two values, as in ✔/✕: the Exchange/VASP variant/the private wallet variant

    Inside the counterparty, person_type, name, tax_id_number and residence_country are always required; entity_category is required for a legal person abroad and institution_type when it is FINANCIAL_INSTITUTION.

  4. Collect the countries and, when asked, the purpose. Countries are ISO 3166-1 alpha-2 codes from GET /travel_rule/countries, with BR for Brazil. When the path asks for operation_reason, list the purposes of the deposit or withdrawal and keep the chosen code; its required_documents tells which files it will ask for.
  5. Submit the declaration. To the deposit or withdrawal, with the fields of your variant only. A withdrawal must be declared within 24 hours of being held, unless it went back from AWAITING_TRAVEL_RULE_REVIEW to AWAITING_TRAVEL_RULE (step 7): then there is no deadline. The errors:
    Status (code)When
    400 (400)The body does not fit the path: a field outside the variant, one the path asks left out, or a malformed one. details lists every problem at once, naming the field
    422 (422)The operation cannot take the declaration: it is not held for the Travel Rule or the deposit was already declared
    422 (4001)The declaration is refused: a company-only field sent for a personal account or left out by a company, a CPF or CNPJ with an invalid check digit, a purpose the operation does not accept, or purpose_description missing above USD 50,000. A refusal that rejects a withdrawal leaves it REJECTED, with the funds returned
    The response samples of each declaration route show one example of each.
  6. Send the documents, if asked. When the answer brings documents_required true, send every file listed in travel_rule.required_documents in one request to the deposit or withdrawal. Reading the operation lists them again while they are pending; a withdrawal waits 24 hours for them, counted from when they were asked, unless it went back from AWAITING_TRAVEL_RULE_REVIEW to AWAITING_TRAVEL_RULE (step 7): then there is no deadline.
  7. Follow the outcome. By reading the operation:
    OutcomeDepositWithdrawal
    DoneACCEPTED: creditedPROCESSING, then DONE: sent
    Waiting for documentsAWAITING_TRAVEL_RULE with documents_required true (step 6)
    Under reviewAWAITING_TRAVEL_RULE_REVIEW, review.state OPEN
    Back to awaiting declarationBack from AWAITING_TRAVEL_RULE_REVIEW to AWAITING_TRAVEL_RULE, with the declaration null again. Send the declaration again, in full, for the same operation. The declaration sent again is always reviewed, whatever the answers, the purpose or the amount: it goes to AWAITING_TRAVEL_RULE_REVIEW, after the documents when the purpose asks for them (step 6), and the operation is never credited or released directly
    RejectedREJECTED: contact our supportREJECTED: rejection_reason says why; the funds are returned
    Nothing arrivesNever canceled: it stays held, without being creditedCANCELED after 24 hours with the declaration or the documents pending on the client; the funds are returned. The 24 hours restart each time a step is asked of the client again, and stop during the review. A withdrawal that went back from AWAITING_TRAVEL_RULE_REVIEW to AWAITING_TRAVEL_RULE has no deadline from then on, for the declaration or for the documents, and is never canceled automatically
Common mistakes. A field that is not part of your variant answers 400: send only the fields of the variant you picked.

Integrating with Postman

We provide a Postman collection and environment to help you get started with our API quickly and easily. The collection includes all available endpoints, along with example requests and responses, making it easy to test and explore the API. The environment allows you to set up your API key and secret, so you can make authenticated requests without having to manually enter them each time. The zip containing the Postman collection and environment can be downloaded here: Postman collection

To import the API collection into Postman, follow these steps:

  1. Download the zip file containing the Postman collection and environment.
  2. Unzip the file to a location on your computer.
  3. Open Postman and click on the "Import" button in the top left corner.
  4. Select the "Import File" tab and choose the unzipped file named rest-v3.collection.json.
  5. Click on the "Import" button to import the collection.
  6. After importing the collection, you will see a new folder named "Foxbit API" in your Postman workspace.
  7. Click on Environments tab in the left sidebar and click on the "Import" button.
  8. Select the "Import File" tab and choose the unzipped file named rest-v3.environment.json.
  9. Click on the "Import" button to import the environment.
  10. After importing the environment, you will see a new environment named "Foxbit RestV3 Environment" in your Postman workspace.
  11. Go to the imported environment and fill in the following variables:
    Variable Type Initial value Current Value
    API_KEY default your_api_key_here
    API_SECRET secret your_api_secret_here
  12. Back in the collection, click on the "Foxbit API" folder to see all available endpoints.
  13. Select an endpoint you want to test and click on it.

Now you can start using our API directly from Postman! If you have any questions or need further assistance, feel free to reach out to our support team.

Using the official JavaScript/TypeScript SDK

We provide an official JavaScript/TypeScript SDK to help you integrate with the REST API using typed clients and models. The package is available on npm: @foxbit-group/rest-api.

The SDK is generated from our OpenAPI specification, so its methods follow the same endpoints, request bodies and response models described in this documentation. You can use it in Node.js projects with CommonJS or ES Modules.

Installation

Install the package using npm:

npm install @foxbit-group/rest-api

Public endpoints

Public endpoints do not require API credentials. For example, you can list the currencies supported by the REST API with MarketDataApi:

const  = require('@foxbit-group/rest-api');

const marketDataApi = new MarketDataApi();

async function listCurrencies() {
  const  = await marketDataApi.listCurrencies();
  console.log(data);
}

listCurrencies();

Authenticated endpoints

For authenticated endpoints, create a Configuration with your API key and secret, then pass it to the API client you want to use. Keep your credentials in environment variables or another secure secret store; do not hardcode them in your source code.

const  = require('@foxbit-group/rest-api');

const configuration = new Configuration({
  apiKey: process.env.FOXBIT_API_KEY,
  apiSecret: process.env.FOXBIT_API_SECRET,
});

const tradingApi = new TradingApi(configuration);

async function createMarketOrder() {
  const  = await tradingApi.createOrder({
    createOrderRequest: {
      side: 'BUY',
      type: 'MARKET',
      market_symbol: 'btcbrl',
      quantity: '1',
    },
  });

  console.log(data);
}

createMarketOrder();

When apiKey and apiSecret are provided, the SDK automatically generates the timestamp, signs the request and sends the required authentication headers. Make sure the API key has the permissions required by the endpoint you are calling. For example: read, trade, deposit or withdrawal.

Next steps

Use the endpoint reference in this documentation to understand which API client, method and request fields are needed for each operation. You can also check the package README and generated model documentation on npm for additional examples and type details, and find runnable SDK examples in the foxbit-api-samples repository.

Glossary

Key business and technical terms used across the Foxbit REST API.

Term Definition
Custody The safekeeping and management of crypto assets on behalf of a customer.
KYC "Know Your Customer." The identity verification process required to validate customers, define access levels, enable limits, and allow certain operations such as deposits, withdrawals, or trading.
KYC Level The customer's verification level. It may affect transactional limits, product availability, deposit/withdrawal permission, and access to specific flows.
FIAT / Fiat Currency Government-issued currency such as BRL. In Foxbit flows, FIAT usually refers to Brazilian real balances, transfers, settlements, or funding movements.
BRL Brazilian real, the fiat currency used in Brazil.
Crypto Asset A cryptocurrency or digital asset supported by Foxbit, such as BTC, ETH, USDT, or others depending on product and market availability.
Network / network_code The blockchain network used to move a crypto asset (e.g. TRC-20, ERC-20). Each currency exposes its available networks and a default_network_code in the currencies endpoint; the network_code value is what you pass on deposit/withdrawal requests to choose the network.
Market A trading pair or supported asset pair available for a product. For example, a market may define whether a customer can buy or sell a specific crypto asset against BRL or another asset.
Quote A price offer returned by the API for a specific buy or sell operation. A quote usually has a limited validity window and must be executed before it expires.
Order Book A market structure where buy and sell orders are placed and matched. Quote-based products (such as Prime Desk) are different: a firm quote is requested and executed instead of placing traditional order book orders.
Trading A product area related to direct trading flows: placing, listing and cancelling orders on the order book.
Deprecation A notice that a product, endpoint, or feature is being phased out and should not be used for new integrations. Deprecated endpoints may be discontinued in the future.
Spread The difference or margin applied to a market price, defining the final price offered to the customer.
Deposit A movement where funds or assets enter an account. In this API, "Deposits" commonly refers to crypto deposits and address generation.
Crypto Deposit A deposit of cryptocurrency into an account through a supported crypto network.
Deposit Address A blockchain address generated for receiving crypto deposits into an account.
Withdrawal A movement where fiat or crypto leaves an account. Withdrawals may require specific permissions, available balance, compliance rules, and in some cases higher KYC or special authorization.
Crypto Withdrawal A withdrawal of cryptocurrency from an account to an external wallet address or supported destination.
Fiat Withdrawal A withdrawal of fiat currency, such as BRL, from an account.
PIX Brazil's instant payment system. PIX may appear in different Foxbit products with different meanings and must not be assumed to mean the same thing across all of them.
On-ramp A flow where fiat currency is converted into crypto or used to enter a crypto-related product.
Off-ramp A flow where crypto is converted into fiat or used to exit a crypto-related product.
Settlement The final delivery of funds after a payment, ramp, trade, or operational flow is completed.
API Key A credential used to identify and authenticate a private API request. Private endpoints require the API key in the request headers.
API Secret A secret value used to sign API requests. It must be stored securely and cannot be recovered if lost.
X-FB-ACCESS-KEY The request header that carries the API key.
X-FB-ACCESS-TIMESTAMP The request header that carries the request timestamp. It is used as part of request authentication.
X-FB-ACCESS-SIGNATURE The request header that carries the generated request signature.
Prehash String The string built before generating a signature. It is encrypted or signed using the API secret according to the authentication rules.
HMAC SHA-256 A cryptographic method used to generate request signatures with the API secret.
Rate Limit The maximum number of requests allowed in a specific time window. If the limit is exceeded, the API may block or reject requests temporarily.
TTL "Time to Live." In the rate limit context, TTL means the time window during which requests are counted.
Block Duration The amount of time a requester may be blocked after exceeding the rate limit.
X-FB-RATE-LIMIT-REQUESTS-LIMIT A response header with the maximum number of requests allowed in the current rate limit window.
X-FB-RATE-LIMIT-REQUESTS-REMAINING A response header with the number of requests still available in the current rate limit window.
X-FB-RATE-LIMIT-REQUESTS-RESET A response header with the number of seconds until the current rate limit window resets.
X-FB-RATE-LIMIT-RETRY-AFTER A response header sent with 429 responses indicating how many seconds to wait before retrying.
Public Endpoint An endpoint that does not require private API authentication. Rate limits may be based on IP address.
Private Endpoint An endpoint that requires authentication headers, API key, timestamp, and signature.
Required API Key Permission The permission that must be enabled on an API key to use a specific endpoint or product.
Ed25519 API Key A type of API key/signature scheme referenced by some endpoints. It may have different signing or permission requirements than standard API keys.
Ledger A financial record of account movements, trading, funding, and related transactions. Ledger reports are used for reconciliation and audit purposes.
Reconciliation The process of matching Foxbit records with your own internal records, such as balances, trades, deposits, withdrawals, and reports.
OAuth An authorization standard used to allow secure access between systems without directly sharing user credentials.
SSO "Single Sign-On." A login flow that allows users to authenticate into Foxbit-related experiences through an integrated identity flow.
Staking A crypto mechanism where assets are locked or allocated to support a blockchain network or product and may generate rewards.
DeFi Pool A decentralized finance pool where assets may be allocated to generate yield.

Market Data

Public endpoints for accessing real-time and historical market information. Use these endpoints to retrieve available trading pairs, price quotations, order book snapshots, candlestick charts, ticker summaries and recent public trades. No authentication is required.

List currencies

Retrieve a list of all supported currencies, including their symbol, name, type (crypto/fiat), precision, deposit and withdrawal information (minimum amounts, fees, enabled status) and available networks.
To obtain the currency icon, use this URL pattern: https://statics.foxbit.com.br/icons/colored/[CURRENCY_SYMBOL].svg

Cache: 1 minute.
Rate Limit: 6 requests per 1 second.

Try out ↗

query Parameters
category
string
Value: "PREDICTION"
Example: category=PREDICTION

The currency category to filter currencies

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

List markets

Retrieve a list of all available trading markets, including their symbols, base/quote currencies, precision settings, minimum quantities, default fees and allowed order types.

Cache: 1 minute.
Rate Limit: 6 requests per 1 second.

Try out ↗

query Parameters
category
string
Enum: "PREDICTION" "ALL"
Example: category=PREDICTION

Filter by market category. Use PREDICTION to list only prediction markets, or ALL to list every market

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get a market quotation

Simulate a trade and get an estimated quotation based on a market and side (BUY/SELL). You can specify either the amount (in quote currency, e.g. BRL) or the quantity (in base currency, e.g. BTC) to receive the corresponding conversion.

Rate Limit: 2 requests per 2 seconds.

Try out ↗

query Parameters
side
required
string
Enum: "BUY" "SELL"
Example: side=BUY

Book side for quote search

base_currency
required
string
Example: base_currency=btc

The base currency is the currency against which exchange rates are typically quoted. It serves as the reference point for determining the value of other currencies in a currency pair. (e.g. BTC in BTCBRL)

quote_currency
required
string
Example: quote_currency=brl

The quote currency is the second currency in a currency pair. It represents the value of one unit of the base currency in terms of the quote currency. (e.g. BRL in BTCBRL)

amount
string
Example: amount=1000.00

Amount of the quote currency to be quoted (e.g. BRL in BTCBRL). Provide amount or quantity: at least one is required. If both are sent, amount takes precedence

quantity
string

Quantity of the base currency to be quoted (e.g. BTC in BTCBRL). Provide quantity or amount: at least one is required. If both are sent, amount takes precedence

Responses

Response samples

Content type
application/json
{
  • "side": "buy",
  • "market_symbol": "btcbrl",
  • "base_amount": "0.00256410",
  • "quote_amount": "1000.0",
  • "price": "390000.00"
}

Get order book

Retrieve a snapshot of the order book for a specific market, containing arrays of bids and asks with price and quantity at each level. The depth can be limited via query parameter.
See also how to manage a local copy of the order book.

Rate Limit: 10 requests per 2 seconds.

Try out ↗

path Parameters
market_symbol
required
string
Example: btcbrl

The symbol of the market from which the order book data will be exported

query Parameters
depth
integer <= 300
Default: 300
Example: depth=50

The maximum number of asks and bids to be exported

Responses

Response samples

Content type
application/json
{
  • "sequence_id": 1234567890,
  • "timestamp": 1713187921336,
  • "bids": [
    ],
  • "asks": [
    ]
}

Get candlesticks

Retrieve OHLCV (Open, High, Low, Close, Volume) candlestick data for a specific market and time interval. Useful for charting and technical analysis. Supports multiple intervals from 1 minute to 1 month.

Rate Limit: 15 requests per 2 seconds.

Try out ↗

path Parameters
market_symbol
required
string
Example: btcbrl

The symbol of the market from which the candlestick data will be retrieved

query Parameters
interval
required
string
Enum: "1m" "5m" "15m" "30m" "1h" "2h" "4h" "6h" "12h" "1d" "1w" "2w" "1M"
Examples:
  • interval=1m - 1 minute interval
  • interval=5m - 5 minutes interval
  • interval=15m - 15 minutes interval
  • interval=1d - 1 day interval
  • interval=1M - 1 month interval

The time interval of each candlestick. Supported intervals range from 1 minute to 1 month

start_time
string
Examples:
  • start_time=2022-07-18T00:00 - Start of day
  • start_time=2022-08-19T12:10 - Specific time

The earliest date in ticker history, it can be entered with minutes accuracy

end_time
string
Examples:
  • end_time=2022-08-19T12:00 - Start of hour
  • end_time=2022-08-19T12:12 - Specific minute

The most current date in ticker history, can be entered with a precision of minutes

limit
integer [ 1 .. 500 ]
Default: 100
Examples:
  • limit=100 - Default limit
  • limit=500 - Maximum allowed

The maximum number of ticks to be returned (max 500)

order_direction
string
Default: "ASC"
Enum: "ASC" "DESC"

Sort direction of the returned candlesticks by timestamp. ASC returns oldest first, DESC returns most recent first

Responses

Response samples

Content type
application/json
[
  • [
    ],
  • [
    ]
]

Get ticker for a specific market

Retrieve real-time 24-hour ticker information for a given market, including last trade price, price change, volume, high/low and best bid/ask with volume.

Rate Limit: 12 requests per 2 seconds.

Try out ↗

path Parameters
market_symbol
required
string
Example: btcbrl

The symbol of the market from which the ticker data will be retrieved

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get all markets ticker

Retrieve 24-hour ticker data for all active markets in a single request. Each ticker includes last trade, price change, volume and best bid/ask prices.
To obtain the currency icon, use this URL pattern: https://statics.foxbit.com.br/icons/colored/[CURRENCY_SYMBOL].svg

Cache: 10 seconds.
Rate Limit: 2 requests per 4 seconds.

Try out ↗

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get trades

Retrieve the most recent public trades for a specific market. Each trade includes price, volume, taker side and timestamp.
If start_time and end_time are not provided, the most recent trades are returned based on the page_size parameter.

Cache: 10 seconds.
Rate Limit: 5 requests per 2 seconds.

Try out ↗

path Parameters
market_symbol
required
string
Example: btcbrl

The symbol of the market from which the trades will be retrieved

query Parameters
start_time
string
Examples:
  • start_time=2024-01-01 - Date only
  • start_time=2024-01-01T06:25:09 - Date and time

Filter values after this start_time, in the format YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS

end_time
string
Examples:
  • end_time=2024-01-01 - Date only
  • end_time=2024-01-01T06:25:09 - Date and time

Filter values before this end_time, in the format YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS

page
integer >= 1
Default: 1
Examples:
  • page=1 - First page
  • page=10 - Tenth page

Page to be retrieved from the list

page_size
integer [ 1 .. 200 ]
Default: 50
Examples:
  • page_size=50 - Default page size
  • page_size=100 - Larger page size

The number of entries returned

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get sparkline

Retrieve sparkline price data for one or more markets over a specific time window. Returns an array of timestamp/price data points per market, useful for rendering mini price charts. Up to 20 markets can be queried at once.

Cache: 10 seconds.
Rate Limit: 3 requests per 2 seconds.

Try out ↗

path Parameters
window
required
string
Enum: "hour" "day" "week" "month" "year" "all"
Example: week

The time window covered by the sparkline

Window Coverage
hour Last hour
day Last 24 hours
week Last 7 days
month Last 30 days
year Last 365 days
all Entire market history

query Parameters
market_symbols
required
Array of strings <= 20 items
Example: market_symbols=btcbrl,ethbrl,adabrl

Market symbols to include, sent in the query as a comma-separated list

interval
string
Enum: "1m" "5m" "1h" "2h" "1d" "1w"
Example: interval=1h

Time interval for sparkline data points. Available intervals per window:

Window Available Intervals
hour 1m
day 5m
week 1h
month 2h
year 1d
all 1w
If not specified, the default interval for the selected window will be used

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Banks

Public endpoint for retrieving the list of supported Brazilian banks. The bank code returned can be used to validate bank account information when submitting fiat withdrawals. No authentication is required.

List banks

Retrieve a list of all supported Brazilian banks. This data includes bank name, abbreviation and code, which can be used to validate bank account information when submitting fiat withdrawals.

Cache: 5 minutes.
Rate Limit: 1 request per 1 second.

Try out ↗

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

System

Public endpoint for retrieving the API server time. Use this to synchronize your local clock with the server, which is essential for generating valid request signatures for authenticated endpoints. No authentication is required.

Get current time

Returns the API server time in both ISO-8601 and UNIX Timestamp (milliseconds) formats. Use this endpoint to synchronize your local clock with the server, which is required for generating valid request signatures (see Authentication).

Rate Limit: 5 requests per 1 second.

Try out ↗

Responses

Response samples

Content type
application/json
{
  • "iso": "2021-06-15T18:00:00.123Z",
  • "timestamp": 1623780000123
}

Travel Rule

The Travel Rule asks who is on the other side of a crypto deposit or withdrawal. When it applies, the operation is held in AWAITING_TRAVEL_RULE until you declare it: a deposit is not credited and a withdrawal is not sent until then.

Start with the guide: How to declare the Travel Rule, the same steps for a deposit and for a withdrawal.

The declaration, its purposes and its documents live under the operation itself, in Deposit and Withdrawal. This section holds the catalog they read from: GET /travel_rule/countries, the countries a declaration accepts.

List Travel Rule countries

Lists the ISO 3166-1 alpha-2 countries a Travel Rule declaration accepts, with the name localized by the Locale header and ordered by name.

Where they go. vasp_entity_country, sender.residence_country (deposit), recipient.residence_country (withdrawal) and fx_residence_country. BR stands for Brazil. See the Travel Rule section for the declaration flow.

Cache: 10 minutes.
Rate Limit: 2 requests per 2 seconds.

Try out ↗

header Parameters
Locale
string
Default: EN
Enum: "EN" "PT-BR"

Language used to localize the country name field. Accepted values (case-sensitive): EN, PT-BR. Defaults to EN when the header is omitted. Any other value causes the request to fail with 400 Bad Request.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Member Info

Authenticated endpoints for retrieving the current member's profile information, including account details, registration level, status and personalized trading fee rates across all markets.

Get current member details

Retrieve the authenticated member's profile, including their unique identifier (SN), email, registration level and account status.

Rate Limit: 1 request per 1 second.

Responses

Response samples

Content type
application/json
{
  • "sn": "FRR3DTLHGJ7DPB",
  • "email": "[email protected]",
  • "level": 10,
  • "created_at": "2021-11-25T13:23:27.961Z",
  • "disabled": false
}

Trading Fees

Retrieve the maker and taker trading fee rates for all markets, specific to the authenticated member. Fees may vary based on volume tier or promotions.

Rate Limit: 1 request per 2 seconds.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Trading

Authenticated endpoints for managing orders and viewing trade history. Includes operations for creating orders (Limit, Market, Instant, StopLimit, StopMarket, TrailingStopLimit, TrailingStopMarket, Oco), batch order creation, cancel-and-replace, order cancellation and retrieving executed trades.

Create an order

Submit a new order to the exchange. Multiple order types are supported — see the request body schema for details on each type (Limit, Market, Instant, StopLimit, StopMarket, TrailingStopLimit, TrailingStopMarket, Oco).
Required API Key permissions: trade

Rate Limit: 30 requests per 2 seconds. An order, after created, can be presented in the following states:

State Description
ACTIVE The order is in the matching queue, waiting for a match
PARTIALLY_FILLED Part of the order has been filled and the remaining quantity is in the matching queue, waiting for a match
FILLED The order has been fully filled and is no longer in the matching queue
PARTIALLY_CANCELED The order was partially traded, but the remaining quantity was canceled. The order is no longer in the matching queue
PENDING_CANCEL The order has been removed from the matching queue and is awaiting fund release to finalize the cancellation. Further trades will not occur within this order
CANCELED The order was completely canceled and is no longer in the matching queue. There is no trade associated with this order
The valid state transitions are:
From To When
ACTIVE PARTIALLY_FILLED Part of the order quantity is executed
ACTIVE / PARTIALLY_FILLED FILLED The full order quantity is executed
ACTIVE / PARTIALLY_FILLED PENDING_CANCEL A cancellation was requested and is waiting for fund release
ACTIVE / PENDING_CANCEL CANCELED The order is canceled without any executed trades
PARTIALLY_FILLED / PENDING_CANCEL PARTIALLY_CANCELED The order is canceled after partial execution
FILLED, CANCELED and PARTIALLY_CANCELED are terminal states. STOP_LIMIT and STOP_MARKET orders rest outside the order book until the stop price is reached; once triggered, they enter the book as LIMIT and MARKET orders respectively, following the states above.

An OCO order places a take-profit LIMIT at price and arms a stop-loss STOP_LIMIT at stop_price/stop_limit_price under a single order id. The first leg to activate wins and the other is canceled: a first trade of the take-profit cancels the stop-loss; the trigger of the stop-loss cancels the take-profit and the order's price becomes stop_limit_price. A BUY OCO locks max(price, stop_limit_price) × quantity. Canceling the order cancels both legs. OCO orders are always GTC and never post-only. The order_type list of the markets endpoints says where OCO is available.

Request Body schema: application/json
required
One of
side
required
string
Enum: "BUY" "SELL"

The side of the order book you will place the order

type
required
string
Value: "LIMIT"

The type of the order to be created

market_symbol
required
string

The market symbol of the order to be created

client_order_id
string

Client-provided numeric identifier (max. of 2^63 - 1) of the order, sent as a string of digits

remark
string <= 100 characters

A note for the order

stp
string
Enum: "EXPIRE_BOTH" "EXPIRE_MAKER" "EXPIRE_TAKER" "DECREMENT"

Self Trade Prevention (STP) is a mechanism employed by trading platforms to prevent users from inadvertently trading against themselves. You can currently use:
EXPIRE_TAKER: This mode prevents a trade by immediately revoking the taker order's remaining quantity;
EXPIRE_MAKER: This mode prevents a trade by immediately revoking the potential maker order's remaining quantity;
EXPIRE_BOTH: This mode prevents a trade by immediately revoking both the taker and the potential maker order's remaining quantities;
DECREMENT: This mode prevents a trade by immediately revoking the order with the smaller quantity.
Default: EXPIRE_TAKER

slippage_tolerance
string

The slippage tolerance feature protects users from unexpected price changes during trades, ensuring transactions execute within acceptable limits and enhancing trading accuracy.
Each fill is limited to the top-of-book price plus (for buys) or minus (for sells) the tolerance; any remaining quantity that would execute beyond this band is canceled with cancellation reason 205. The effective tolerance may be capped by an exchange-side protection limit.
Must be a decimal string between 0 and 1 with up to 3 decimal places (e.g., 0.025 = 2.5%)

sub_account_type
string
Value: "PREDICTION"

The sub-account type related to orders

quantity
required
string

The quantity of the base currency you want to buy or sell, expressed in string format.
It needs to be a decimal with a maximum of 16 decimal places

price
required
string

The price intended to buy or sell, expressed in the quote currency
and string formatted. It needs to be a decimal with a maximum of 16 decimal places

post_only
boolean

When true your order will not be executed immediately in the market.
It will exist as a maker order on the order book. Maker orders add liquidity to the market.
Only compatible with time_in_force GTC; if the order would match immediately, it is canceled with cancellation reason 202

time_in_force
string
Enum: "GTC" "FOK" "IOC"

TimeInForce (TIF) defines how long an order remains active before it is executed or canceled. Foxbit currently supports:
Good 'til Cancelled (GTC): the order stays active until it is fully filled or canceled manually by the trader;
Fill or Kill (FOK): the order must be fully filled immediately. If 100% of the quantity cannot be filled at once, the entire order is canceled (no partial fills);
Immediate or Cancel (IOC): any part of the order that can be filled immediately is executed, and any remaining quantity is canceled (allows partial fills, unlike FOK).
Only applicable to LIMIT and STOP_LIMIT orders. Default: GTC

Responses

Request samples

Content type
application/json
Example
{
  • "side": "BUY",
  • "type": "LIMIT",
  • "market_symbol": "btcbrl",
  • "client_order_id": "451637946501",
  • "remark": "A remarkable note for the order.",
  • "stp": "EXPIRE_TAKER",
  • "slippage_tolerance": "0.025",
  • "sub_account_type": "PREDICTION",
  • "quantity": "0.42",
  • "price": "250000.0",
  • "post_only": true,
  • "time_in_force": "GTC"
}

Response samples

Content type
application/json
{
  • "id": "1234567890",
  • "sn": "OKMAKSDHRVVREK",
  • "client_order_id": "451637946501"
}

List orders

Retrieve a paginated list of orders for the authenticated member. Supports filtering by market, side, state and date range. By default, returns orders from the last 90 days in descending order.

Rate Limit: 30 requests per 2 seconds.

query Parameters
start_time
string
Example: start_time=2022-02-01T22:06:32.999Z

Filter values after this start_time, must be in ISO-8601 UTC. The range between start_time and end_time is limited to 90 days

end_time
string
Example: end_time=2022-02-18T22:06:32.999Z

Filter values before this end_time, must be in ISO-8601 UTC. The range between start_time and end_time is limited to 90 days

page_size
integer [ 1 .. 100 ]
Default: 10
Example: page_size=10

The number of entries returned, maximum of 100

page
integer >= 1
Default: 1
Example: page=1

Page to be retrieved from the list

market_symbol
string
Example: market_symbol=btcbrl

The market where the order was placed

state
string
Enum: "ACTIVE" "CANCELED" "FILLED" "PARTIALLY_CANCELED" "PARTIALLY_FILLED"
Example: state=ACTIVE

The execution state of the orders

side
string
Enum: "BUY" "SELL"
Example: side=BUY

The order book side where the order was placed

sub_account_type
string
Value: "PREDICTION"

The sub-account type associated with the orders

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create orders in batch

Submit multiple orders in a single request. The request is considered successful if at least one order in the batch is created — partial success returns HTTP 202 with details of each order's result.
The maximum batch size is: 5
Required API Key permissions: trade

Rate Limit: 8 requests per 2 seconds.

Request Body schema: application/json
required
required
Array of OrderLimit (object) or OrderMarket (object) or OrderInstant (object) or OrderStopLimit (object) or OrderStopMarket (object) or OrderTrailingStopLimit (object) or OrderTrailingStopMarket (object) or OrderOco (object) (CreateOrderRequest) [ 1 .. 5 ] items

Order create batch data

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Cancel and replace

Cancel an existing order and create a new one in a single request, e.g. to change its price or quantity. Both are sent at the same time and each can fail on its own, so this is not atomic: the order may still fill before the cancel takes effect. The response reports the result of each operation; when both fail, the API answers 422.
Required API Key permissions: trade

Rate Limit: 20 requests per 2 seconds.

Request Body schema: application/json
required
mode
required
string
Value: "ALLOW_FAILURE"

Mode of the order cancel/replace.

  • ALLOW_FAILURE: In this mode, the cancellation and creation of orders are executed independently. This mode ensures that both operations are attempted without one being dependent on the success of the other.
required
object

Order cancel parameters

required
OrderLimit (object) or OrderMarket (object) or OrderInstant (object) or OrderStopLimit (object) or OrderStopMarket (object) or OrderTrailingStopLimit (object) or OrderTrailingStopMarket (object) or OrderOco (object)

Order create parameters

Responses

Request samples

Content type
application/json
{
  • "mode": "ALLOW_FAILURE",
  • "cancel": {
    },
  • "create": {
    }
}

Response samples

Content type
application/json
{
  • "cancel": {
    },
  • "create": {
    }
}

Get an order by SN Deprecated

Get an order by serial number.
This endpoint is deprecated — use the Get an order by ID endpoint instead

path Parameters
order_sn
required
string
Example: OQMPZNKZPFTKCS

Order serial number

Responses

Response samples

Content type
application/json
{
  • "id": "1234567890",
  • "sn": "OQMPZNKZPFTKCS",
  • "client_order_id": "451637946501",
  • "market_symbol": "btcbrl",
  • "side": "BUY",
  • "type": "LIMIT",
  • "state": "ACTIVE",
  • "price": "290000.0",
  • "price_avg": "0.0",
  • "quantity": "0.42",
  • "quantity_executed": "0.0",
  • "instant_amount": null,
  • "instant_amount_executed": null,
  • "created_at": "2021-02-15T22:06:32.999Z",
  • "trades_count": 0,
  • "fee_paid": "0.0",
  • "post_only": false,
  • "time_in_force": "GTC",
  • "cancellation_reason": null,
  • "cancellation_reason_order_id": null,
  • "stp": "EXPIRE_TAKER",
  • "slippage_tolerance": "0.025"
}

Get an order by ID

Retrieve detailed information about a specific order by its ID, a numeric value sent as a string, including current state, price, quantity, executed amounts, fees and cancellation reason when applicable.

Rate Limit: 30 requests per 2 seconds.

path Parameters
id
required
string
Example: 1234567890

Order ID

query Parameters
sub_account_type
string
Value: "PREDICTION"

The sub-account type to search the order

Responses

Response samples

Content type
application/json
{
  • "id": "1234567890",
  • "sn": "OKMAKSDHRVVREK",
  • "client_order_id": "451637946501",
  • "market_symbol": "btcbrl",
  • "side": "BUY",
  • "type": "LIMIT",
  • "state": "ACTIVE",
  • "price": "290000.0",
  • "price_avg": "0.0",
  • "quantity": "0.42",
  • "quantity_executed": "0.0",
  • "instant_amount": null,
  • "instant_amount_executed": null,
  • "created_at": "2021-02-15T22:06:32.999Z",
  • "trades_count": 0,
  • "fee_paid": "0.0",
  • "post_only": false,
  • "time_in_force": "GTC",
  • "cancellation_reason": null,
  • "cancellation_reason_order_id": null,
  • "stp": "EXPIRE_TAKER",
  • "slippage_tolerance": "0.025",
  • "remark": "A remarkable note for the order."
}

Get an order by client ID

Retrieve detailed information about a specific order using the client-provided numeric identifier (max. of 2^63 - 1, sent as a string of digits) that was assigned at order creation time. Returns the same data as the Get an order by ID endpoint.

Rate Limit: 30 requests per 2 seconds.

path Parameters
client_order_id
required
string
Example: 57354679787653765

Client-provided numeric identifier (max. of 2^63 - 1) of the order, sent as digits

query Parameters
sub_account_type
string
Value: "PREDICTION"

The sub-account type to search the order

Responses

Response samples

Content type
application/json
{
  • "id": "1234567890",
  • "sn": "OKMAKSDHRVVREK",
  • "client_order_id": "57354679787653765",
  • "market_symbol": "btcbrl",
  • "side": "BUY",
  • "type": "LIMIT",
  • "state": "ACTIVE",
  • "price": "290000.0",
  • "price_avg": "0.0",
  • "quantity": "0.42",
  • "quantity_executed": "0.0",
  • "instant_amount": null,
  • "instant_amount_executed": null,
  • "created_at": "2021-02-15T22:06:32.999Z",
  • "trades_count": 0,
  • "fee_paid": "0.0",
  • "post_only": false,
  • "time_in_force": "GTC",
  • "cancellation_reason": null,
  • "cancellation_reason_order_id": null,
  • "stp": "EXPIRE_TAKER",
  • "slippage_tolerance": "0.025",
  • "remark": null
}

Cancel orders

Cancel one or more orders based on the specified criteria. You can cancel by order ID, SN, client order ID, market, market+side, or cancel all open orders at once — see the request body schema for each option.
Order cancellation is asynchronous, so it usually takes some milliseconds to process. Use the Get an order by ID endpoint to confirm the final state.

Required API Key permissions: trade

Rate Limit: 30 requests per 2 seconds.

Request Body schema: application/json
required
One of
sub_account_type
string
Value: "PREDICTION"

The sub-account type to filter orders

type
required
string
Value: "ALL"

Type of cancellation request

Responses

Request samples

Content type
application/json
Example
{
  • "sub_account_type": "PREDICTION",
  • "type": "ALL"
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

List trades

Retrieve a paginated list of the authenticated member's executed trades. Each trade includes price, quantity, fee, fee currency, role (maker/taker) and the associated order ID. Results are returned in descending order (most recent first).
Trade history is available for the last 3 months only. Contact support for longer historical data.

Cache: 10 seconds.
Rate Limit: 5 requests per 1 second.

query Parameters
market_symbol
required
string
Example: market_symbol=btcbrl

Market symbol to filter by

order_id
string
Example: order_id=123456789

The specific order ID identification you want to filter

start_time
string
Example: start_time=2022-02-01T22:06:32.999Z

Filter values after this start_time, must be in ISO-8601 UTC. The range between start_time and end_time is limited to 90 days

end_time
string
Example: end_time=2022-02-18T22:06:32.999Z

Filter values before this end_time, must be in ISO-8601 UTC. The range between start_time and end_time is limited to 90 days

page
integer >= 1
Default: 1
Examples:
  • page=1 - First page
  • page=10 - Tenth page

Page to be retrieved from the list

page_size
integer [ 1 .. 100 ]
Default: 50
Examples:
  • page_size=50 - Default page size
  • page_size=100 - Maximum allowed

The number of entries returned, maximum of 100

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Account

Authenticated endpoints for retrieving currency balances and transaction history. View total, available and locked balances per currency, and query detailed account movements including trades, deposits, withdrawals and internal transfers.

Get member accounts

Retrieve all currency balances for the authenticated member. Each account entry includes the total balance, the available balance (funds ready for trading or withdrawal) and the locked balance (funds reserved by open orders or pending withdrawals).

Rate Limit: 15 requests per 1 second.

query Parameters
sub_account_type
string
Value: "PREDICTION"

The sub-account type to filter accounts

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get member transactions

Retrieve all account movements for a specific currency. Transactions represent every balance change, including trades, deposits, withdrawals and internal transfers. Each entry shows the amount, resulting balance, locked amount and fee, making it possible to reconstruct the full balance history.
The maximum time range is 3 months. Older transactions will not be retrieved. Contact support for longer historical data.

Rate Limit: 1 request per 2 seconds.

path Parameters
currency_symbol
required
string
Example: btc
query Parameters
start_time
string
Example: start_time=2022-02-01T22:06:32.999Z

Filter values after this start_time, must be in ISO-8601 UTC. The range between start_time and end_time is limited to 90 days

end_time
string
Example: end_time=2022-02-18T22:06:32.999Z

Filter values before this end_time, must be in ISO-8601 UTC. The range between start_time and end_time is limited to 90 days

page_size
integer [ 1 .. 100 ]
Default: 10
Example: page_size=10

The number of entries returned, maximum of 100

page
integer >= 1
Default: 1
Example: page=1

Page to be retrieved from the list

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Deposit

Authenticated endpoints for managing deposits. List deposit transactions, retrieve details of a specific deposit by serial number, and get or generate cryptocurrency deposit addresses for supported networks.

List deposits

Retrieve a paginated list of all deposit transactions for the authenticated member, including both cryptocurrency and fiat deposits. Supports filtering by date range.

Rate Limit: 3 requests per 1 second.

query Parameters
start_time
string
Example: start_time=2022-02-01T22:06:32.999Z

Filter values after this start_time, must be in ISO-8601 UTC

end_time
string
Example: end_time=2022-02-18T22:06:32.999Z

Filter values before this end_time, must be in ISO-8601 UTC

page_size
integer [ 1 .. 100 ]
Default: 10
Example: page_size=10

The number of entries returned, maximum of 100

page
integer >= 1
Default: 1
Example: page=1

Page to be retrieved from the list

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get a deposit

Retrieve detailed information about a specific deposit by its unique serial number (SN), including state, amount, fee and cryptocurrency transaction details when applicable.

A crypto deposit in AWAITING_TRAVEL_RULE waits for its Travel Rule declaration: see the step-by-step guide.

Rate Limit: 3 requests per 1 second.

path Parameters
deposit_sn
required
string
Example: DPKXMRDT7H4VBN

The alphanumeric unique identifier of the deposit

Responses

Response samples

Content type
application/json
{
  • "sn": "DPKXMRDT7H4VBN",
  • "state": "ACCEPTED",
  • "currency_symbol": "btc",
  • "amount": "1.0",
  • "fee": "0.1",
  • "created_at": "2022-02-18T22:06:32.999Z",
  • "details_crypto": {
    },
  • "travel_rule": {
    }
}

Submit Travel Rule for a deposit

Declares the Travel Rule of a crypto deposit: who holds the origin wallet and, for a third party, who sends the funds.

Step 5 of 7 of the step-by-step guide.

Before calling. The deposit must be in AWAITING_TRAVEL_RULE with travel_rule null (read it with GET /deposits/{deposit_sn}). Take the countries from GET /travel_rule/countries and, when the declaration asks for operation_reason, the purpose from GET /deposits/{deposit_sn}/travel_rule/operation_reasons.

📘 Before filling this body, read the step-by-step guide
Step 2: which variant to send
Step 3: the fields each path asks
Step 4: the countries and the purpose
Step 5: every error and its code
Step 7: what each answer means

Body. wallet_owner and wallet_type pick one of four variants (DepositTravelRuleOwnPrivateWallet, DepositTravelRuleOwnExchangeWallet, DepositTravelRuleThirdPartyPrivateWallet, DepositTravelRuleThirdPartyExchangeWallet); each lists its fields and when its path asks them, and someone else goes under sender. Send only the fields of your variant, with the names and the shape the deposit read returns in travel_rule.

Outcome. The answer brings the new state and documents_required: credited (ACCEPTED), held for the documents listed in travel_rule.required_documents (send them with POST /deposits/{deposit_sn}/travel_rule/documents) or under review (AWAITING_TRAVEL_RULE_REVIEW). A deposit is never canceled while it waits.

Required API Key permissions: deposit

Rate Limit: 2 requests per 2 seconds.

path Parameters
deposit_sn
required
string
Example: DPKXMRDT7H4VBN

The alphanumeric unique identifier of the deposit

Request Body schema: application/json
required

One of the variants below, picked by wallet_owner and wallet_type

One of
wallet_owner
required
string
Value: "SELF"

The client holds the origin wallet

wallet_type
required
string
Value: "SELF_HOSTED"

A private (unhosted) wallet

purpose_description
string

Purpose of the deposit in the client's own words. Mandatory above USD 50,000 (Annex IV); ignored up to it

Responses

Request samples

Content type
application/json
Example
{
  • "wallet_owner": "SELF",
  • "wallet_type": "SELF_HOSTED",
  • "purpose_description": "Moving my own funds"
}

Response samples

Content type
application/json
{
  • "sn": "DPKXMRDT7H4VBN",
  • "state": "AWAITING_TRAVEL_RULE_REVIEW",
  • "documents_required": false,
  • "travel_rule": {
    }
}

List the Travel Rule operation reasons of a deposit

Lists the BACEN operation reasons (purposes) the Travel Rule declaration of the deposit accepts.

Step 4 of 7 of the step-by-step guide (only when the declaration asks for operation_reason).

When to call. When the declaration asks for operation_reason: an Exchange/VASP or a sender abroad, or a client resident abroad (fx_residence_country other than BR). The deposit must be in AWAITING_TRAVEL_RULE with travel_rule null (read it with GET /deposits/{deposit_sn}).

Then. Send the chosen code as operation_reason to POST /deposits/{deposit_sn}/travel_rule. When the purpose has required_documents, those files go to POST /deposits/{deposit_sn}/travel_rule/documents after the declaration, which lists them again. If the declaration refuses the purpose, call this route again and pick one of the purposes it returns.

Required API Key permissions: deposit

Rate Limit: 2 requests per 2 seconds.

path Parameters
deposit_sn
required
string
Example: DPKXMRDT7H4VBN

The alphanumeric unique identifier of the deposit

header Parameters
Locale
string
Default: EN
Enum: "EN" "PT-BR"

Language used to localize the operation reason description field. Accepted values (case-sensitive): EN, PT-BR. Defaults to EN when the header is omitted. Any other value (including lowercase variants such as en or pt-BR) causes the request to fail with 400 Bad Request.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get a deposit address

Retrieve an existing deposit address for a specific cryptocurrency and network, or schedule the creation of a new one if none exists yet. When an address is being generated, retry the request after a few minutes.

Rate Limit: 3 requests per 1 second.

query Parameters
network_code
string
Example: network_code=bitcoin

Wallet network. To see the deposit networks available for each currency, check our currencies list endpoint

currency_symbol
required
string
Example: currency_symbol=btc

Currency symbol

Responses

Response samples

Content type
application/json
{
  • "currency_symbol": "btc",
  • "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  • "message": "Address was retrieved successfully",
  • "destination_tag": "",
  • "network": {
    }
}

Send the Travel Rule documents of a deposit

Sends the documents the Travel Rule purpose of the deposit requires.

Step 6 of 7 of the step-by-step guide (only when the declaration asks for them).

When to call. After POST /deposits/{deposit_sn}/travel_rule answered documents_required true: the deposit stays in AWAITING_TRAVEL_RULE until the files arrive. Which files to send is travel_rule.required_documents in the declaration answer, and travel_rule.required_documents in GET /deposits/{deposit_sn}.

Files. pdf, jpg, jpeg, png, csv, xls, xlsx; up to 20 files and 25MB per request.

Send the whole set in one request. The first request moves the deposit on — to review, or it is credited — and a later request is refused. Nothing is stored when the deposit is not waiting for documents.

Then. Follow the deposit with GET /deposits/{deposit_sn}.

Required API Key permissions: deposit

Rate Limit: 2 requests per 10 seconds.

path Parameters
deposit_sn
required
string
Example: DPKXMRDT7H4VBN

The alphanumeric unique identifier of the deposit

header Parameters
X-FB-CONTENT-SHA256
required
string

Hex SHA-256 that replaces the body in the signature prehash (recomputed server-side to guarantee file integrity).
Compute it over the concatenation of the raw bytes of every files part, in the order they are sent.
Example: sha256(file1_bytes + file2_bytes).

Request Body schema: multipart/form-data
required
files
required
Array of strings <binary> [ items <binary > ]

The documents requested for the chosen purpose

Responses

Response samples

Content type
application/json
{
  • "sn": "DPKXMRDT7H4VBN",
  • "state": "AWAITING_TRAVEL_RULE_REVIEW",
  • "case_state": "UNDER_REVIEW"
}

Withdrawal

Authenticated endpoints for managing withdrawals. List withdrawal transactions, retrieve details of a specific withdrawal by serial number, and submit new withdrawal requests for both cryptocurrency (to external wallets) and fiat currency (to bank accounts). Creating withdrawals requires the withdraw API key permission.

List withdrawals

Retrieve a paginated list of all withdrawal transactions for the authenticated member, including both cryptocurrency and fiat withdrawals. Supports filtering by date range.

Rate Limit: 3 requests per 1 second.

query Parameters
start_time
string
Example: start_time=2022-02-01T22:06:32.999Z

Filter values after this start_time, must be in ISO-8601 UTC

end_time
string
Example: end_time=2022-02-18T22:06:32.999Z

Filter values before this end_time, must be in ISO-8601 UTC

page_size
integer [ 1 .. 100 ]
Default: 10
Example: page_size=10

The number of entries returned, maximum of 100

page
integer >= 1
Default: 1
Example: page=1

Page to be retrieved from the list

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create a withdrawal

Submit a new withdrawal request for cryptocurrency or fiat currency. The request body differs based on the currency type — see the schema options below.

For cryptocurrency withdrawals, we highly recommend adding your withdrawal address to our whitelist for a seamless and automated process. While not mandatory, non-whitelisted addresses require an email verification and proof of life for each withdrawal, which may delay transactions.
To whitelist an address, open a support ticket here.

Travel Rule: once confirmed, a crypto withdrawal may be held in AWAITING_TRAVEL_RULE until you declare it — see the step-by-step guide.

Required API Key permissions: withdraw

Rate Limit: 3 requests per 1 second.

Request Body schema: application/json
required
One of
amount
required
string

The amount to be withdrawn

currency_symbol
required
string

Currency symbol

required
object

Bank branch data

Responses

Request samples

Content type
application/json
Example
{
  • "amount": "1",
  • "currency_symbol": "brl",
  • "bank": {
    }
}

Response samples

Content type
application/json
{
  • "sn": "WBZYUBF73C4GUU",
  • "state": "SUBMITTED",
  • "currency_symbol": "btc",
  • "amount": "0.5",
  • "fee": "0.0001",
  • "created_at": "2022-09-15T12:38:18.510Z",
  • "details_crypto": {
    }
}

Get a withdrawal

Retrieve detailed information about a specific withdrawal by its unique serial number (SN), including state, amount, fee, rejection reason (if any) and transaction details (crypto hash or bank account data).

A crypto withdrawal in AWAITING_TRAVEL_RULE waits for its Travel Rule declaration: see the step-by-step guide.

Rate Limit: 3 requests per 1 second.

path Parameters
withdrawal_sn
required
string
Example: WDRZN4HKGT8MBP

The alphanumeric unique identifier of the withdrawal

Responses

Response samples

Content type
application/json
{
  • "sn": "WDRZN4HKGT8MBP",
  • "state": "DONE",
  • "rejection_reason": null,
  • "currency_symbol": "btc",
  • "amount": "0.5",
  • "fee": "0.0001",
  • "created_at": "2022-02-18T22:06:32.999Z",
  • "details_crypto": {
    }
}

Submit Travel Rule for a withdrawal

Declares the Travel Rule of a crypto withdrawal: who holds the destination wallet and, for a third party, who receives the funds.

Step 5 of 7 of the step-by-step guide.

Before calling. The withdrawal must be in AWAITING_TRAVEL_RULE with travel_rule null (read it with GET /withdrawals/{withdrawal_sn}). Take the countries from GET /travel_rule/countries and, when the declaration asks for operation_reason, the purpose from GET /withdrawals/{withdrawal_sn}/travel_rule/operation_reasons.

📘 Before filling this body, read the step-by-step guide
Step 2: which variant to send
Step 3: the fields each path asks
Step 4: the countries and the purpose
Step 5: every error and its code
Step 7: what each answer means

Body. wallet_owner and wallet_type pick one of four variants (WithdrawalTravelRuleOwnPrivateWallet, WithdrawalTravelRuleOwnExchangeWallet, WithdrawalTravelRuleThirdPartyPrivateWallet, WithdrawalTravelRuleThirdPartyExchangeWallet); each lists its fields and when its path asks them, and someone else goes under recipient. Send only the fields of your variant, with the names and the shape the withdrawal read returns in travel_rule.

Outcome. The answer brings the new state and documents_required: released (PROCESSING), held for the documents listed in travel_rule.required_documents (send them with POST /withdrawals/{withdrawal_sn}/travel_rule/documents), under review (AWAITING_TRAVEL_RULE_REVIEW), or refused with 422 and REJECTED, with the funds returned. A withdrawal whose declaration or documents are still missing 24 hours after being asked is CANCELED, with the funds returned; the 24 hours restart each time a step is asked again and stop during the review. A withdrawal that went back from AWAITING_TRAVEL_RULE_REVIEW to AWAITING_TRAVEL_RULE has no deadline.

Required API Key permissions: withdraw

Rate Limit: 2 requests per 2 seconds.

path Parameters
withdrawal_sn
required
string
Example: WDRZN4HKGT8MBP

The alphanumeric unique identifier of the withdrawal

Request Body schema: application/json
required

One of the variants below, picked by wallet_owner and wallet_type

One of
wallet_owner
required
string
Value: "SELF"

The client holds the destination wallet

wallet_type
required
string
Value: "SELF_HOSTED"

A private (unhosted) wallet

purpose_description
string

Purpose of the withdrawal in the client's own words. Mandatory above USD 50,000 (Annex IV); ignored up to it

Responses

Request samples

Content type
application/json
Example
{
  • "wallet_owner": "SELF",
  • "wallet_type": "SELF_HOSTED",
  • "purpose_description": "Moving to my own wallet"
}

Response samples

Content type
application/json
{
  • "sn": "WDRZN4HKGT8MBP",
  • "state": "AWAITING_TRAVEL_RULE_REVIEW",
  • "documents_required": false,
  • "travel_rule": {
    }
}

List the Travel Rule operation reasons of a withdrawal

Lists the BACEN operation reasons (purposes) the Travel Rule declaration of the withdrawal accepts.

Step 4 of 7 of the step-by-step guide (only when the declaration asks for operation_reason).

When to call. When the declaration asks for operation_reason: an Exchange/VASP or a recipient abroad, or a client resident abroad (fx_residence_country other than BR). The withdrawal must be in AWAITING_TRAVEL_RULE with travel_rule null (read it with GET /withdrawals/{withdrawal_sn}).

Then. Send the chosen code as operation_reason to POST /withdrawals/{withdrawal_sn}/travel_rule. When the purpose has required_documents, those files go to POST /withdrawals/{withdrawal_sn}/travel_rule/documents after the declaration, which lists them again. If the declaration refuses the purpose, call this route again and pick one of the purposes it returns.

Required API Key permissions: withdraw

Rate Limit: 2 requests per 2 seconds.

path Parameters
withdrawal_sn
required
string
Example: WDRZN4HKGT8MBP

The alphanumeric unique identifier of the withdrawal

header Parameters
Locale
string
Default: EN
Enum: "EN" "PT-BR"

Language used to localize the operation reason description field. Accepted values (case-sensitive): EN, PT-BR. Defaults to EN when the header is omitted. Any other value (including lowercase variants such as en or pt-BR) causes the request to fail with 400 Bad Request.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Send the Travel Rule documents of a withdrawal

Sends the documents the Travel Rule purpose of the withdrawal requires.

Step 6 of 7 of the step-by-step guide (only when the declaration asks for them).

When to call. After POST /withdrawals/{withdrawal_sn}/travel_rule answered documents_required true: the withdrawal stays in AWAITING_TRAVEL_RULE until the files arrive. Which files to send is travel_rule.required_documents in the declaration answer, and travel_rule.required_documents in GET /withdrawals/{withdrawal_sn}.

Files. pdf, jpg, jpeg, png, csv, xls, xlsx; up to 20 files and 25MB per request.

Send the whole set in one request. The first request moves the withdrawal on — to review, or it is released — and a later request is refused. Before the files are read, the withdrawal must be in AWAITING_TRAVEL_RULE; send them only after the declaration asked for them.

Then. Follow the withdrawal with GET /withdrawals/{withdrawal_sn}.

Required API Key permissions: withdraw

Rate Limit: 2 requests per 10 seconds.

path Parameters
withdrawal_sn
required
string
Example: WDRZN4HKGT8MBP

The alphanumeric unique identifier of the withdrawal

header Parameters
X-FB-CONTENT-SHA256
required
string

Hex SHA-256 that replaces the body in the signature prehash (recomputed server-side to guarantee file integrity).
Compute it over the concatenation of the raw bytes of every files part, in the order they are sent.
Example: sha256(file1_bytes + file2_bytes).

Request Body schema: multipart/form-data
required
files
required
Array of strings <binary> [ items <binary > ]

The documents requested for the chosen purpose

Responses

Response samples

Content type
application/json
{
  • "sn": "WDRZN4HKGT8MBP",
  • "state": "AWAITING_TRAVEL_RULE_REVIEW",
  • "case_state": "UNDER_REVIEW"
}

Transactional Limits

Authenticated endpoint for retrieving the member's deposit and withdrawal limits per currency. Each entry shows the total allowed limit and the remaining available amount. Limits may vary based on KYC verification level.

List Transactional Limits

Retrieve the transactional limits for the authenticated member, broken down by currency. Each entry shows the total allowed limit and the remaining available limit for both deposits and withdrawals. Limits may vary based on the member's KYC verification level.

Rate Limit: 1 request per 2 seconds.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Prime Desk

Authenticated endpoints for the Prime Desk trading service, designed for executing large cryptocurrency trades with dedicated pricing and deeper liquidity. The workflow involves requesting a time-limited quote and then executing it.

List markets

Retrieve the list of markets available for Prime Desk trading, including supported trading pairs and their configurations.

Rate Limit: 1 request per 2 seconds.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Request quote

Request a quotation for a large trade at the best available price. The returned quote includes the price, amounts and a time-limited quote ID that can be used to execute the trade via the Execute quote endpoint.

Rate Limit: 5 requests per 10 seconds.

Request Body schema: application/json
required

Provide either quantity (value in base currency) or amount (value in quote currency) — never both

One of
market_symbol
required
string

The market symbol of the order to be created

side
required
string
Enum: "BUY" "SELL"

The side of the operation that you will place the order

quantity
required
string

The quantity of the base currency you want to trade, expressed in string format

Responses

Request samples

Content type
application/json
Example
{
  • "market_symbol": "btcbrl",
  • "side": "BUY",
  • "quantity": "0.42"
}

Response samples

Content type
application/json
{
  • "quote_id": "0856c960-4aa7-401a-b309-23ebd0236191",
  • "market_symbol": "btcbrl",
  • "side": "BUY",
  • "quantity": "0.42",
  • "price": "178195.13",
  • "valid_until": "2021-11-25T13:23:27.961Z"
}

Execute quote

Execute a previously requested quotation by providing its quote ID. The quote must still be within its validity window. Once executed, the trade is settled at the quoted price.
Required API Key permissions: trade

Rate Limit: 5 requests per 10 seconds.

Request Body schema: application/json
required
client_order_id
string

Client self managed order UUID

quote_id
required
string

Generated quote UUID

Responses

Request samples

Content type
application/json
{
  • "client_order_id": "4babec3d-6a59-4775-841c-159f60c8a058",
  • "quote_id": "27d92819-7f8b-4da2-b6cf-8e5e3a7c6de5"
}

Response samples

Content type
application/json
{
  • "quote_id": "27d92819-7f8b-4da2-b6cf-8e5e3a7c6de5",
  • "client_order_id": "4babec3d-6a59-4775-841c-159f60c8a058",
  • "market_symbol": "btcbrl",
  • "price": "350120.32",
  • "quantity": "0.001",
  • "side": "BUY",
  • "status": "CREATED",
  • "created": "2020-12-16T19:47:27.000Z"
}

List executions

Retrieve a paginated history of all executed Prime Desk quotes for the authenticated member, including trade details, prices and timestamps.

Rate Limit: 5 requests per 2 seconds.

query Parameters
page
integer
Default: 1
Example: page=1

Page number. Default: 1

page_size
integer [ 1 .. 20 ]
Default: 10
Example: page_size=10

Page size. Default: 10; Max: 20

Responses

Response samples

Content type
application/json
{
  • "total": 12,
  • "data": [
    ]
}

Get an execution by quote ID

Retrieve detailed information about a specific executed Prime Desk trade by its quote UUID, including price, amounts, side and execution timestamp.

Rate Limit: 6 requests per 2 seconds.

path Parameters
quote_id
required
string
Example: b5f1b6b0-0e4c-4d0e-8b1d-3e0e2a0c3b9a

Generated quote UUID of the execution

Responses

Response samples

Content type
application/json
{
  • "quote_id": "b5f1b6b0-0e4c-4d0e-8b1d-3e0e2a0c3b9a",
  • "client_order_id": "0f80c9e2-1a5f-4f6b-9d3e-6a3a4e2c8f10",
  • "price": "350120.32",
  • "market_symbol": "btcbrl",
  • "quantity": "0.01",
  • "side": "BUY",
  • "status": "FILLED",
  • "created_at": "2020-12-09T14:56:55.000Z"
}