logo
API docs by Redocly

Ripio Trade - API Documentation (v4.0)

Download OpenAPI specification:

Welcome to the Ripio Trade API documentation.

Version

This API is currently in the version 4.

If there is need for any big change, a new version will be launched and this version will be maintained for at least 3 months.

If you're still using the version 3, access the old documentation and check the migration guide.

Important

Use the Market endpoints for all trading operations. The Public endpoints have a delay (cache) of up to 30 seconds.

All successful requests will result in a 200 HTTP Status.

All requests returns data in JSON format (application/json) and have a default body:

Success

{
  "error_code": null,
  "message": null,
  "data": { }
}

Error

{
  "error_code": [Error code],
  "message": "Error description",
  "data": null
}

Endpoints that have a date filter will return data for the last 6 months if no value is sent in the start_date parameter.

URL structure

The endpoints URL follow this pattern:

https://api.ripiotrade.co/{version}/{method}[/{parameter}][?parameter=value...]

https://api.ripiotrade.co/v4/tickers/BTC_BRL

Limits

The request limits are based on the user's operational limits.

There are two types of limit, one of requests per second and another of daily requests. Both of them should be taken in consideration and the requests should be balanced so the daily limit isn't reached.

Users without approved documentation have 1 request per second or 86.400 daily requests.

Users with approved documentation have 3.5 requests per second or 302.400 daily requests.

These limits can be increased, and the support team should be contacted for that.

When the requests per second limit is reached, the response HTTP Status returned is 429 and the response body is: 

{
  "message": "Too many requests"
}

When the daily requests limit is reached, the response HTTP Status returned is 429 and the response body is: 

{
  "message": "Limit Exceeded"
}

Authorization

You can create API Credentials on: https://trade.ripio.com/market/api/token.

After creating the API Credentials, you'll need to save in a safe place two pieces of information, an API Token and a Secret Key. The credentials are required respectively to Authenticate and Sign all Private REST Requests.

Attention: The Secret Key can only be viewed once and cannot be retrieved later. If you lose the Secret Key, delete the set of credentials and create a new one.

Each endpoint requires a type of access, which can be Read, Buy/Sell, Cryptocurrency withdrawals, or can contain all of these, each one for its own function. It is possible for the token to be Read only, or it may have several types, if it has any other type of access such as: Buy/Sell or Cryptocurrency withdrawals, it will also be Read by default.

Headers

For all private routes, these Headers are required:

Header Description
Authorization The API Token as a string.
Timestamp A timestamp in milliseconds. See the Timestamp Security section for more details.
Timestamp-tolerance An additional, non-required parameter, that you can send to specify the number of milliseconds after the timestamp for the request to be valid. See the Timestamp Security section for more details.
Signature See the Generating Signature section for more details.

Timestamp Security

Timestamp Security is a security method to guarantee the validation of the acceptable time window, in addition to guaranteeing the uniqueness of the request Signature.

  • All Private Requests also require a Header parameter, Timestamp, which must be the timestamp in milliseconds of when the request was created and sent. Can be generated with Date.now() if you're using JavaScript, for example.

  • An additional parameter, Timestamp-tolerance, non-required, may be sent to specify the max number of milliseconds after the timestamp, that the request is valid. If Timestamp-tolerance is not sent, it defaults to 5000 (5 seconds).

  • It is recommended to use a small Timestamp-tolerance of 5000 (5 seconds) or less. The maximum value is 60,000 (60 seconds).

Generating Signature

To create a signature for all Private Requests, you must encrypt the hash-based message using sha256 HMAC and encode it in Base64.

The message must contain:

Timestamp + HTTP Method + Path + JSON Payload

  • Not including the '+' sign, just concatenate the content into a string.

  • The Timestamp is the same as the one sent in the Header.

  • For GET Requests, it is necessary to consider the PATH without Query Params. For example, this route: /withdrawals/estimate-rate/ADA?network=cardano_testnet. Just /withdrawals/estimate-fee is considered. Additionally, the BODY is considered an empty String.

  • JSON Payload must be a string and must be the same as the one sent in the request Body.

IMPORTANT: To prevent an invalid signature, avoid using unnecessary decimal places in the request body properties. For instance, use 1 instead of 1.0. Alternatively, you can also send numbers as strings in the request body, ensuring they are in the same format but as strings. For example: 

{
  'amount': '0.01',
  'pair': 'BTC_BRL',
  'price': '300000', 
  'side': 'buy', 
  'type': 'limit'
}

Examples

We provide functional examples of how to authenticate with this API, written in various programming languages. You can find these examples in our GitHub repository: https://github.com/ripio/trade.

Errors

The error code is returned in the property code of the response body.

Invalid Parameters

HTTP Code: 400

Adjust the request to match what the documentation or the error message says and try again.

  • 40000 - Invalid parameters.
  • 40010 - Order amount below minimum.
  • 40011 - Insufficient funds.
  • 40020 - Order already canceled.
  • 40021 - Order executed completely.
  • 40021 - No orders to cancel.
  • 40030 - Withdrawal limit exceeded.
  • 40031 - Withdrawal amount below minimum.
  • 40032 - Prevention against duplicated withdrawal. Try again after ten minutes.
  • 40033 - Destination wallet not authorized.
  • 40034 - Non existent destination account.
  • 40035 - Minimum amount to create non existent wallet not reached.
  • 40040 - Withdrawals temporarily blocked.
  • 40041 - Withdrawals blocked due to TFA recovery request.
  • 40050 - TFA not enabled.
  • 40090 - Unsupported operation.

Authentication

HTTP Code: 401

The authentication is necessary to access the resource.

  • 40100 - Not authorized

HTTP Code: 401

  • 40100 - Blocked token

Contact the support team to recover access.

Forbidden Access

HTTP Code: 403

Forbidden access to the resource.

  • 40300 - Forbidden Access

Not found

HTTP Code: 404

Check the request URL.

  • 40400 - Not found

Requests limit

HTTP Code: 429

Wait and try again.

  • 42900 - Requests limit reached

Internal server error

HTTP Code: 500

Try again and contact the support team in case the error persists.

  • 50000 - Internal server error
  • 50001 - Error to get data
  • 50002 - External communication error
  • 50003 - Internal communication error

Maintenance

HTTP Code: 503

Wait and try again.

  • 503 - Maintenance in course

Public

The public endpoints have a reduced requests limit and a 30 seconds cache.

For increased limits, use the private endpoints.

Tickers

Returns a 24 hour window statistics for all pairs.

Responses

Response Schema: application/json
required
Array of objects (TickersResponseData)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "ask": 250000.15,
      • "base_code": "BTC",
      • "base_id": "9A5E2EF4-9547-418A-8EC6-C6EADBB8B32F",
      • "bid": 240000.15,
      • "date": "2017-10-20T00:00:00Z",
      • "first": 245000.15,
      • "high": 250000.15,
      • "is_frozen": false,
      • "last": 245000.15,
      • "low": 200000.15,
      • "pair": "BTC_BRL",
      • "price_change_percent_24h": "-12",
      • "quote_code": "BRL",
      • "quote_id": "48898138-8623-4555-9468-B1A1505A9352",
      • "quote_volume": 150.1,
      • "trades_quantity": 123,
      • "volume": 123.12345678
      },
    • {
      • "ask": 15600.12,
      • "base_code": "ETH",
      • "base_id": "13A4B83B-E74F-425C-BC0A-03A9C0F29FAD",
      • "bid": 15400.12,
      • "date": "2017-10-20T00:00:00Z",
      • "first": 15999.15,
      • "high": 15999.12,
      • "is_frozen": false,
      • "last": 15500.12,
      • "low": 15000.12,
      • "pair": "ETH_BRL",
      • "price_change_percent_24h": "-12",
      • "quote_id": "48898138-8623-4555-9468-B1A1505A9352",
      • "quote_code": "BRL",
      • "quote_volume": 180.1,
      • "trades_quantity": 123,
      • "volume": 123.12345678
      }
    ],
  • "error_code": null,
  • "message": null
}

Ticker By Pair

Returns a 24 hour window statistics for a given pair.

path Parameters
pair
required
string
Example: BTC_BRL

Currency pair code

Responses

Response Schema: application/json
required
object (TickersResponseDataV4)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": {
    • "ask": 95629,
    • "base_code": "BTC",
    • "base_id": "9A5E2EF4-9547-418A-8EC6-C6EADBB8B32F",
    • "bid": 94171,
    • "date": "2022-11-11T01:31:35.820Z",
    • "first": 98444,
    • "high": 98444,
    • "is_frozen": false,
    • "last": 94311,
    • "low": 85034,
    • "pair": "BTC_BRL",
    • "price_change_percent_24h": "-12",
    • "quote_id": "48898138-8623-4555-9468-B1A1505A9352",
    • "quote_code": "BRL",
    • "quote_volume": 150.1,
    • "trades_quantity": 1199,
    • "volume": 27.26776846
    },
  • "error_code": null,
  • "message": null
}

Orderbook Level 3

Returns the level 3 orderbook.

query Parameters
pair
required
string
Example: pair=BTC_BRL

Currency pair code
limit
number <int32> (LimitParamV4) [ 1 .. 250 ]
Default: 100
Example: limit=25

Maximum number of registers to be returned

Responses

Response Schema: application/json
required
object (PublicOrdersLevel3ResponseData)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": {
    • "timestamp": 1675708481219,
    • "asks": [
      • {
        • "amount": 0.01187517,
        • "id": "554F2D70-04B9-4E26-9548-9C35B025A018",
        • "price": 14704.45
        },
      • {
        • "amount": 1,
        • "id": "C1C5DA8E-A069-4E20-87D1-12B19426A013",
        • "price": 1873.48
        }
      ],
    • "bids": [
      • {
        • "amount": 0.46097295,
        • "id": "E6D05F51-D79B-47CF-84C5-B157120EBC25",
        • "price": 14650.25
        },
      • {
        • "amount": 1,
        • "id": "CE743407-66BE-4F4C-AD0E-AB376468C5F6",
        • "price": 1610.15
        }
      ],
    • "hash": "16757084812196786445"
    },
  • "error_code": null,
  • "message": null
}

Orderbook Level 2

Returns the level 2 orderbook.

query Parameters
pair
required
string
Example: pair=BTC_BRL

Currency pair code
limit
string <string> (LimitNewParamV4)
Default: 100

Limit of registers to be returned It is possible to specify 'max' to set an upper limit on the number of items we can provide at one time.

Responses

Response Schema: application/json
required
object (PublicOrdersLevel2ResponseData)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": {
    • "timestamp": 1675708481219,
    • "asks": [
      • {
        • "amount": 0.01187517,
        • "price": 14704.45
        },
      • {
        • "amount": 1,
        • "price": 1873.48
        }
      ],
    • "bids": [
      • {
        • "amount": 0.46097295,
        • "price": 14650.25
        },
      • {
        • "amount": 1,
        • "price": 1610.15
        }
      ],
    • "hash": "16757084812196786445"
    },
  • "error_code": null,
  • "message": null
}

Trades

Lists the trades history based on the filtering criteria.

Attention: Due to performance concerns, this endpoint now uses cursor-based pagination. The pagination object currently included in the response is now a placeholder and will be entirely removed as of 2026-01-01. The parameter current_page is also a placeholder and will be removed at the same time. Please update your integration accordingly and refer to the documentation for the correct pagination handling.

query Parameters
pair
required
string
Example: pair=BTC_BRL

Currency pair code
start_time
string <datetime> (StartDateTimeNoMinParamV4)
Default: "[6 months ago]"
Example: start_time=2020-01-01T00:00:00-03:00

Initial datetime filter in ISO-8601 format
end_time
string <datetime> (EndDateTimeNoMinParamV4)
Default: "[Current datetime]"
Example: end_time=2020-01-02T23:59:59-03:00

Final datetime filter in ISO-8601 format
page_size
number <int32> (PageSizeParamV4) [ 1 .. 1000 ]
Default: 200
Example: page_size=100

Number of registers per page
current_page
number <int32> (CurrentPageParamV4)
Default: 1
Example: current_page=3

Current page
c
string

The c parameter is the cursor you should use to fetch the next page of results

Responses

Response Schema: application/json
required
object (TradesResponseData)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": {
    • "trades": [
      • {
        • "amount": 0.2404764,
        • "date": "2019-01-03T02:27:33.947Z",
        • "id": "2B222F22-5235-45FA-97FC-E9DBFA2575EE",
        • "maker_order_id": "F49F5BD8-3F5B-4364-BCEE-F36F62DB966A",
        • "maker_side": "buy",
        • "maker_type": "limit",
        • "pair": "BTC_BRL",
        • "price": 15160,
        • "taker_order_id": "FEAB5CEC-7F9E-4F95-B67D-9E8D5C739BE3",
        • "taker_side": "sell",
        • "taker_type": "market",
        • "timestamp": 1675708481219,
        • "total_value": 3638.4
        },
      • {
        • "amount": 0.00563617,
        • "date": "2019-01-03T02:27:33.943Z",
        • "id": "CDC492A5-B1BF-4353-BE7A-43F51C371388",
        • "maker_order_id": "53BF30D2-901C-43D5-B0D1-62CD05DFD02A",
        • "maker_side": "buy",
        • "maker_type": "limit",
        • "pair": "BTC_BRL",
        • "price": 15163,
        • "taker_order_id": "E4B1B38D-C871-4476-9314-3DC23292F45E",
        • "taker_side": "sell",
        • "taker_type": "limit",
        • "timestamp": 1675708481220,
        • "total_value": 84.91
        },
      • {
        • "amount": 0.00680154,
        • "date": "2019-01-03T02:27:33.940Z",
        • "id": "910AA20F-211F-4755-90A7-94227DB407D8",
        • "maker_order_id": "1FD30735-E055-4200-AD3D-007B02A5BA92",
        • "maker_side": "buy",
        • "maker_type": "limit",
        • "pair": "BTC_BRL",
        • "price": 15163.03,
        • "taker_order_id": "DBC6D4AF-D454-46DF-80EC-E19528A0FB25",
        • "taker_side": "sell",
        • "taker_type": "limit",
        • "timestamp": 1675708481221,
        • "total_value": 104.1
        }
      ],
    • "pagination": {
      • "current_page": 1,
      • "registers_count": 21,
      • "total_pages": 1,
      • "page_size": 100
      },
    • "nc": "string",
    • "pc": "string"
    },
  • "error_code": null,
  • "message": null
}

Currencies

Lists the active currencies available in the platform.

query Parameters
currency_code
string

Currency code
countries
string <string> (CountriesParamV4)
Example: countries=BR,AR

Countries (One or many, use "," to separate)

Responses

Response Schema: application/json
required
Array of objects (PublicCurrencyV4)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "active": true,
      • "can_deposit": true,
      • "can_withdraw": true,
      • "code": "BTC",
      • "id": "e7a079d8-828d-42c8-bf48-8ee3ac1862d1",
      • "min_withdraw_amount": 0.001,
      • "name": "Bitcoin",
      • "needs_block_id_for_tx_sync": true,
      • "networks": [
        • {
          • "code": "bitcoin",
          • "memo": {
            • "deposit": false,
            • "withdrawal": false
            },
          • "tag": {
            • "deposit": false,
            • "withdrawal": false
            }
          }
        ],
      • "precision": 8,
      • "countries": [
        • "BR",
        • "AR"
        ],
      • "logo": { }
      }
    ],
  • "error_code": null,
  • "message": null
}

Pairs

Lists the active currency pairs available in the platform.

query Parameters
pair
string
Example: pair=BTC_BRL

Currency pair code
countries
string <string> (CountriesParamV4)
Example: countries=BR,AR

Countries (One or many, use "," to separate)

Responses

Response Schema: application/json
required
Array of objects (PublicPairV4)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "amount_tick": 0.0001,
      • "base": "BTC",
      • "base_name": "Bitcoin",
      • "enabled": true,
      • "min_amount": 0.0005,
      • "min_value": 10,
      • "price_tick": 1,
      • "quote": "BRL",
      • "quote_name": "Brazilian real",
      • "symbol": "BTC_BRL",
      • "countries": [
        • "BR"
        ],
      • "max_price_variation": 10
      }
    ],
  • "error_code": null,
  • "message": null
}

Countries

Lists the active countries available in the platform.

Responses

Response Schema: application/json
required
Array of objects (CountriesData)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "name": "Brazil",
      • "code": "BR"
      }
    ],
  • "error_code": null,
  • "message": null
}

Get Server Time

Responses

Response Schema: application/json
message
required
string or null
required
object

Response samples

Content type
application/json
{
  • "data": {
    • "timestamp": 1670004661380
    },
  • "message": null
}

General endpoints

Pairs

Lists the active currency pairs available in the platform.

Authorizations:
API Credentials
query Parameters
pair
string
Example: pair=BTC_BRL

Currency pair code
countries
string <string> (CountriesParamV4)
Example: countries=BR,AR

Countries (One or many, use "," to separate)

Responses

Response Schema: application/json
required
Array of objects (PublicPairV4)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "amount_tick": 0.0001,
      • "base": "BTC",
      • "base_name": "Bitcoin",
      • "enabled": true,
      • "min_amount": 0.0005,
      • "min_value": 10,
      • "price_tick": 1,
      • "quote": "BRL",
      • "quote_name": "Brazilian real",
      • "symbol": "BTC_BRL",
      • "countries": [
        • "BR"
        ],
      • "max_price_variation": 10
      }
    ],
  • "error_code": null,
  • "message": null
}

Trades

Lists the trades history based on the filtering criteria.

Authorizations:
API Credentials
query Parameters
pair
required
string
Example: pair=BTC_BRL

Currency pair code
start_time
string <datetime> (StartDateTimeNoMinParamV4)
Default: "[6 months ago]"
Example: start_time=2020-01-01T00:00:00-03:00

Initial datetime filter in ISO-8601 format
end_time
string <datetime> (EndDateTimeNoMinParamV4)
Default: "[Current datetime]"
Example: end_time=2020-01-02T23:59:59-03:00

Final datetime filter in ISO-8601 format
page_size
number <int32> (PageSizeParamV4) [ 1 .. 1000 ]
Default: 200
Example: page_size=100

Number of registers per page
c
string

The c parameter is the cursor you should use to fetch the next page of results

Responses

Response Schema: application/json
required
object (CursorTradesResponseData)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": {
    • "trades": [
      • {
        • "amount": 0.2404764,
        • "date": "2019-01-03T02:27:33.947Z",
        • "id": "2B222F22-5235-45FA-97FC-E9DBFA2575EE",
        • "maker_order_id": "F49F5BD8-3F5B-4364-BCEE-F36F62DB966A",
        • "maker_side": "buy",
        • "maker_type": "limit",
        • "pair": "BTC_BRL",
        • "price": 15160,
        • "taker_order_id": "FEAB5CEC-7F9E-4F95-B67D-9E8D5C739BE3",
        • "taker_side": "sell",
        • "taker_type": "market",
        • "timestamp": 1675708481219,
        • "total_value": 3638.4
        },
      • {
        • "amount": 0.00563617,
        • "date": "2019-01-03T02:27:33.943Z",
        • "id": "CDC492A5-B1BF-4353-BE7A-43F51C371388",
        • "maker_order_id": "53BF30D2-901C-43D5-B0D1-62CD05DFD02A",
        • "maker_side": "buy",
        • "maker_type": "limit",
        • "pair": "BTC_BRL",
        • "price": 15163,
        • "taker_order_id": "E4B1B38D-C871-4476-9314-3DC23292F45E",
        • "taker_side": "sell",
        • "taker_type": "limit",
        • "timestamp": 1675708481220,
        • "total_value": 84.91
        },
      • {
        • "amount": 0.00680154,
        • "date": "2019-01-03T02:27:33.940Z",
        • "id": "910AA20F-211F-4755-90A7-94227DB407D8",
        • "maker_order_id": "1FD30735-E055-4200-AD3D-007B02A5BA92",
        • "maker_side": "buy",
        • "maker_type": "limit",
        • "pair": "BTC_BRL",
        • "price": 15163.03,
        • "taker_order_id": "DBC6D4AF-D454-46DF-80EC-E19528A0FB25",
        • "taker_side": "sell",
        • "taker_type": "limit",
        • "timestamp": 1675708481221,
        • "total_value": 104.1
        }
      ],
    • "nc": "string",
    • "pc": "string"
    },
  • "error_code": null,
  • "message": null
}

Currencies

Lists the active currencies available in the platform.

Authorizations:
API Credentials
query Parameters
currency_code
string

Currency code
countries
string <string> (CountriesParamV4)
Example: countries=BR,AR

Countries (One or many, use "," to separate)

Responses

Response Schema: application/json
required
Array of objects (PublicCurrencyV4)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "active": true,
      • "can_deposit": true,
      • "can_withdraw": true,
      • "code": "BTC",
      • "id": "e7a079d8-828d-42c8-bf48-8ee3ac1862d1",
      • "min_withdraw_amount": 0.001,
      • "name": "Bitcoin",
      • "needs_block_id_for_tx_sync": true,
      • "networks": [
        • {
          • "code": "bitcoin",
          • "memo": {
            • "deposit": false,
            • "withdrawal": false
            },
          • "tag": {
            • "deposit": false,
            • "withdrawal": false
            }
          }
        ],
      • "precision": 8,
      • "countries": [
        • "BR",
        • "AR"
        ],
      • "logo": { }
      }
    ],
  • "error_code": null,
  • "message": null
}

Ticker

Tickers

Returns a 24 hour window statistics for all pairs.

Authorizations:
API Credentials

Responses

Response Schema: application/json
required
Array of objects (TickersResponseData)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "ask": 250000.15,
      • "base_code": "BTC",
      • "base_id": "9A5E2EF4-9547-418A-8EC6-C6EADBB8B32F",
      • "bid": 240000.15,
      • "date": "2017-10-20T00:00:00Z",
      • "first": 245000.15,
      • "high": 250000.15,
      • "is_frozen": false,
      • "last": 245000.15,
      • "low": 200000.15,
      • "pair": "BTC_BRL",
      • "price_change_percent_24h": "-12",
      • "quote_code": "BRL",
      • "quote_id": "48898138-8623-4555-9468-B1A1505A9352",
      • "quote_volume": 150.1,
      • "trades_quantity": 123,
      • "volume": 123.12345678
      },
    • {
      • "ask": 15600.12,
      • "base_code": "ETH",
      • "base_id": "13A4B83B-E74F-425C-BC0A-03A9C0F29FAD",
      • "bid": 15400.12,
      • "date": "2017-10-20T00:00:00Z",
      • "first": 15999.15,
      • "high": 15999.12,
      • "is_frozen": false,
      • "last": 15500.12,
      • "low": 15000.12,
      • "pair": "ETH_BRL",
      • "price_change_percent_24h": "-12",
      • "quote_id": "48898138-8623-4555-9468-B1A1505A9352",
      • "quote_code": "BRL",
      • "quote_volume": 180.1,
      • "trades_quantity": 123,
      • "volume": 123.12345678
      }
    ],
  • "error_code": null,
  • "message": null
}

Ticker By Pair

Returns a 24 hour window statistics for a given pair.

Authorizations:
API Credentials
path Parameters
pair
required
string
Example: BTC_BRL

Currency pair code

Responses

Response Schema: application/json
required
object (TickersResponseDataV4)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": {
    • "ask": 95629,
    • "base_code": "BTC",
    • "base_id": "9A5E2EF4-9547-418A-8EC6-C6EADBB8B32F",
    • "bid": 94171,
    • "date": "2022-11-11T01:31:35.820Z",
    • "first": 98444,
    • "high": 98444,
    • "is_frozen": false,
    • "last": 94311,
    • "low": 85034,
    • "pair": "BTC_BRL",
    • "price_change_percent_24h": "-12",
    • "quote_id": "48898138-8623-4555-9468-B1A1505A9352",
    • "quote_code": "BRL",
    • "quote_volume": 150.1,
    • "trades_quantity": 1199,
    • "volume": 27.26776846
    },
  • "error_code": null,
  • "message": null
}

Book

Orderbook Level 3

Returns the level 3 orderbook.

Authorizations:
API Credentials
query Parameters
pair
required
string
Example: pair=BTC_BRL

Currency pair code
limit
number <int32> (LimitParamV4) [ 1 .. 250 ]
Default: 100
Example: limit=25

Maximum number of registers to be returned

Responses

Response Schema: application/json
required
object (OrdersLevel3Data)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": {
    • "timestamp": 1675708481219,
    • "asks": [
      • {
        • "amount": 0.1283746,
        • "id": "554F2D70-04B9-4E26-9548-9C35B025A018",
        • "price": 1923847
        }
      ],
    • "bids": [
      • {
        • "amount": 0.256566,
        • "id": "E6D05F51-D79B-47CF-84C5-B157120EBC25",
        • "price": 1915200
        }
      ],
    • "hash": "16757084812196786445"
    },
  • "error_code": null,
  • "message": null
}

Orderbook Level 2

Returns the level 2 orderbook.

Authorizations:
API Credentials
query Parameters
pair
required
string
Example: pair=BTC_BRL

Currency pair code
limit
string <string> (LimitNewParamV4)
Default: 100

Limit of registers to be returned It is possible to specify 'max' to set an upper limit on the number of items we can provide at one time.

Responses

Response Schema: application/json
required
object (OrdersLevel2Data)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": {
    • "timestamp": 1675708481219,
    • "asks": [
      • {
        • "amount": 0.1283746,
        • "price": 1923847
        }
      ],
    • "bids": [
      • {
        • "amount": 0.1283746,
        • "price": 1923847
        }
      ]
    },
  • "error_code": null,
  • "message": null
}

User

Balances

Lists the user's balances

Authorizations:
API Credentials
query Parameters
currency_code
string

Currency code (one or many, use "," to separate)

Responses

Response Schema: application/json
required
Array of objects (BalanceResponseDataV4)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": [
    • [
      • {
        • "available_amount": 5.23423423,
        • "currency_code": "BTC",
        • "last_update": "2020-10-20T18:39:45.198Z",
        • "locked_amount": 0
        }
      ]
    ],
  • "error_code": null,
  • "message": null
}

Balance On Date

Lists the user's balances in the given date.

Authorizations:
API Credentials
path Parameters
date
required
string <date> (DateParamV4)

Date filter in ISO-8601 format

Responses

Response Schema: application/json
required
Array of objects (BalanceOnDateResponseDataV4)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "available_amount": 5.23423423,
      • "currency_code": "BTC",
      • "last_update": "2020-10-20T18:39:45.198Z"
      }
    ],
  • "error_code": null,
  • "message": null
}

Fees and Limits

Lists the user's fees and limits.

Authorizations:
API Credentials

Responses

Response Schema: application/json
required
object (UserFeesAndLimitsData)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": {
    • "BRL": [
      • {
        • "amount_limit": 0,
        • "days_to_release_limit": 0,
        • "operation_id": 18,
        • "operation_description": null,
        • "operation_name": "Tax over bank account withdraw",
        • "operation_type": "D",
        • "tax_amount": 4.9,
        • "tax_index": 0.0099,
        • "tax_is_dynamic_index": false
        },
      • {
        • "amount_limit": 0,
        • "days_to_release_limit": 0,
        • "operation_id": 36,
        • "operation_description": null,
        • "operation_name": "Tax over bank account withdraw - Internal",
        • "operation_type": "D",
        • "tax_amount": 4.9,
        • "tax_index": 0.0099,
        • "tax_is_dynamic_index": false
        },
      • {
        • "amount_limit": 0,
        • "days_to_release_limit": 0,
        • "operation_id": 23,
        • "operation_description": null,
        • "operation_name": "Tax over buy, executed",
        • "operation_type": "D",
        • "tax_amount": 0,
        • "tax_index": 0.0025,
        • "tax_is_dynamic_index": false
        },
      • {
        • "amount_limit": 0,
        • "days_to_release_limit": 0,
        • "operation_id": 26,
        • "operation_description": null,
        • "operation_name": "Tax over buy, executor",
        • "operation_type": "D",
        • "tax_amount": 0,
        • "tax_index": 0.005,
        • "tax_is_dynamic_index": false
        },
      • {
        • "amount_limit": 0,
        • "days_to_release_limit": 0,
        • "operation_id": 27,
        • "operation_name": "Tax over sell, executed",
        • "operation_description": null,
        • "operation_type": "D",
        • "tax_amount": 0,
        • "tax_index": 0.0025,
        • "tax_is_dynamic_index": false
        },
      • {
        • "amount_limit": 0,
        • "days_to_release_limit": 0,
        • "operation_id": 24,
        • "operation_name": "Tax over sell, executor",
        • "operation_description": null,
        • "operation_type": "D",
        • "tax_amount": 0,
        • "tax_index": 0.005,
        • "tax_is_dynamic_index": false
        }
      ],
    • "BTC": [
      • {
        • "amount_limit": 0,
        • "days_to_release_limit": 0,
        • "operation_id": 23,
        • "operation_description": null,
        • "operation_name": "Tax over buy, executed",
        • "operation_type": "D",
        • "tax_amount": 0,
        • "tax_index": 0.0025,
        • "tax_is_dynamic_index": false
        },
      • {
        • "amount_limit": 0,
        • "days_to_release_limit": 0,
        • "operation_id": 26,
        • "operation_description": null,
        • "operation_name": "Tax over buy, executor",
        • "operation_type": "D",
        • "tax_amount": 0,
        • "tax_index": 0.005,
        • "tax_is_dynamic_index": false
        },
      • {
        • "amount_limit": 0,
        • "days_to_release_limit": 0,
        • "operation_id": 27,
        • "operation_description": null,
        • "operation_name": "Tax over sell, executed",
        • "operation_type": "D",
        • "tax_amount": 0,
        • "tax_index": 0.0025,
        • "tax_is_dynamic_index": false
        },
      • {
        • "amount_limit": 0,
        • "days_to_release_limit": 0,
        • "operation_id": 24,
        • "operation_description": null,
        • "operation_name": "Tax over sell, executor",
        • "operation_type": "D",
        • "tax_amount": 0,
        • "tax_index": 0.005,
        • "tax_is_dynamic_index": false
        }
      ]
    },
  • "error_code": null,
  • "message": null
}

Monthly withdrawal limits

Gets the user monthly withdrawal limits.

Authorizations:
API Credentials

Responses

Response Schema: application/json
required
Array of objects (UserWithdrawLimitData)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "currency_code": "1INCH",
      • "amount_limit": 58000,
      • "amount_remaining": 58000
      },
    • {
      • "currency_code": "AAVE",
      • "amount_limit": 700,
      • "amount_remaining": 700
      },
    • {
      • "currency_code": "ACA",
      • "amount_limit": 700,
      • "amount_remaining": 700
      }
    ],
  • "error_code": null,
  • "message": null
}

Daily withdrawal limits

Gets the user daily withdrawal limits.

Authorizations:
API Credentials

Responses

Response Schema: application/json
required
Array of objects (UserWithdrawLimitData)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "currency_code": "1INCH",
      • "amount_limit": 1933.3333333333333,
      • "amount_remaining": 1933.3333333333333
      },
    • {
      • "currency_code": "AAVE",
      • "amount_limit": 23.333333333333332,
      • "amount_remaining": 23.333333333333332
      },
    • {
      • "currency_code": "ACA",
      • "amount_limit": 23.333333333333332,
      • "amount_remaining": 23.333333333333332
      }
    ],
  • "error_code": null,
  • "message": null
}

Trading Fees

Get the user trading fees

Authorizations:
API Credentials
query Parameters
pair
required
string

Pair code

Responses

Response Schema: application/json
required
Array of objects (UserPairFeeData)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "side": "buy",
      • "maker": 0.21,
      • "taker": 0.3
      },
    • {
      • "side": "sell",
      • "maker": 0.21,
      • "taker": 0.3
      }
    ],
  • "error_code": null,
  • "message": null
}

Statement

Lists the user's statement.

Authorizations:
API Credentials
query Parameters
start_time
string <datetime> (StartDateTimeParamV4)
Default: "[6 months ago]"
Example: start_time=2020-01-01T00:00:00-03:00

Initial datetime filter in ISO-8601 format (shouldn't be before 2017-10-01)
end_time
string <datetime> (EndDateTimeParamV4)
Default: "[Current datetime]"
Example: end_time=2020-01-02T23:59:59-03:00

Final datetime filter in ISO-8601 format (the interval between the initial and final datetime shouldn't be greater than 6 months)

page_size
number <int32> (PageSizeParamV4) [ 1 .. 1000 ]
Default: 200
Example: page_size=100

Number of registers per page
current_page
number <int32> (CurrentPageParamV4)
Default: 1
Example: current_page=3

Current page

Responses

Response Schema: application/json
required
object (UserStatementData)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": {
    • "statement": [
      • {
        • "amount": -0.00000476,
        • "after_balance": 8605.31353851,
        • "currency": "BTC",
        • "date": "2022-01-27T18:16:10.557Z",
        • "operation": "Tax over buy, executed"
        },
      • {
        • "amount": 0.00119048,
        • "after_balance": 8605.31354327,
        • "currency": "BTC",
        • "date": "2022-01-27T18:16:10.557Z",
        • "operation": "Buy"
        }
      ],
    • "pagination": {
      • "current_page": 1,
      • "registers_count": 21,
      • "total_pages": 1,
      • "page_size": 100
      }
    },
  • "error_code": null,
  • "message": null
}

Statement by Currency

Lists the user's statement by currency.

Authorizations:
API Credentials
path Parameters
currency_code
required
string
Example: BTC

Currency code
query Parameters
start_time
string <datetime> (StartDateTimeNoMinParamV4)
Default: "[6 months ago]"
Example: start_time=2020-01-01T00:00:00-03:00

Initial datetime filter in ISO-8601 format
end_time
string <datetime> (EndDateTimeNoMinParamV4)
Default: "[Current datetime]"
Example: end_time=2020-01-02T23:59:59-03:00

Final datetime filter in ISO-8601 format
page_size
number <int32> (PageSizeParamV4) [ 1 .. 1000 ]
Default: 200
Example: page_size=100

Number of registers per page
current_page
number <int32> (CurrentPageParamV4)
Default: 1
Example: current_page=3

Current page

Responses

Response Schema: application/json
required
object (UserStatementData)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": {
    • "statement": [
      • {
        • "amount": -0.00000476,
        • "after_balance": 8605.31353851,
        • "currency": "BTC",
        • "date": "2022-01-27T18:16:10.557Z",
        • "operation": "Tax over buy, executed"
        },
      • {
        • "amount": 0.00119048,
        • "after_balance": 8605.31354327,
        • "currency": "BTC",
        • "date": "2022-01-27T18:16:10.557Z",
        • "operation": "Buy"
        }
      ],
    • "pagination": {
      • "current_page": 1,
      • "registers_count": 21,
      • "total_pages": 1,
      • "page_size": 100
      }
    },
  • "error_code": null,
  • "message": null
}

Get User Trades

Lists the user's trades.

Attention: Due to performance concerns, this endpoint now uses cursor-based pagination. The pagination object currently included in the response is now a placeholder and will be entirely removed as of 2026-01-01. The parameter current_page is also a placeholder and will be removed at the same time. Please update your integration accordingly and refer to the documentation for the correct pagination handling.

Authorizations:
API Credentials
query Parameters
pair
required
string
Example: pair=BTC_BRL

Currency pair code
start_date
string <date> (StartDateParamV4)
Default: "[10 days ago]"

Initial date filter in ISO-8601 format (shouldn't be before 2017-10-01)
end_date
string <date> (EndDateNoMinParamV4)
Default: "[Current date]"

Final date filter in ISO-8601 format
page_size
number <int32> (PageSizeParamV4) [ 1 .. 1000 ]
Default: 200
Example: page_size=100

Number of registers per page
current_page
number <int32> (CurrentPageParamV4)
Default: 1
Example: current_page=3

Current page
order_id
string
Example: order_id=F49F5BD8-3F5B-4364-BCEE-F36F62DB966A

Order id
external_id
string
Example: external_id=90FcPa1Zm75

External id
c
string

The c parameter is the cursor you should use to fetch the next page of results

Responses

Response Schema: application/json
required
object (UserTradesDataV4)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": {
    • "trades": [
      • {
        • "amount": 0.00270754,
        • "date": "2019-04-02T11:22:22.403Z",
        • "fee": 0.25,
        • "fee_currency": "USDC",
        • "id": "488F9395-47ED-4924-98AB-C860E1733A03",
        • "maker_order_id": "1FD30735-E055-4200-AD3D-007B02A5BA92",
        • "pair_code": "BTC_USDC",
        • "taker_or_maker": "maker",
        • "price": 18550,
        • "side": "sell",
        • "taker_order_id": "DBC6D4AF-D454-46DF-80EC-E19528A0FB25",
        • "timestamp": 1675708481219,
        • "type": "market",
        • "total_value": 50.22
        },
      • {
        • "amount": 0.0026938,
        • "date": "2019-04-02T11:25:41.512Z",
        • "fee": 0.00001347,
        • "fee_currency": "BTC",
        • "id": "C79ED37D-DC21-4D54-8AFC-4262347E3F8D",
        • "maker_order_id": "F49F5BD8-3F5B-4364-BCEE-F36F62DB966A",
        • "pair_code": "BTC_USDC",
        • "taker_or_maker": "taker",
        • "price": 18550,
        • "side": "buy",
        • "taker_order_id": "FEAB5CEC-7F9E-4F95-B67D-9E8D5C739BE3",
        • "timestamp": 1675708481220,
        • "type": "market",
        • "total_value": 49.96
        }
      ],
    • "pagination": {
      • "current_page": 1,
      • "registers_count": 21,
      • "total_pages": 1,
      • "page_size": 100
      },
    • "nc": "string",
    • "pc": "string"
    },
  • "error_code": null,
  • "message": null
}

Orders

Trades

Lists the trades history based on the filtering criteria.

Authorizations:
API Credentials
query Parameters
pair
required
string
Example: pair=BTC_BRL

Currency pair code
start_time
string <datetime> (StartDateTimeNoMinParamV4)
Default: "[6 months ago]"
Example: start_time=2020-01-01T00:00:00-03:00

Initial datetime filter in ISO-8601 format
end_time
string <datetime> (EndDateTimeNoMinParamV4)
Default: "[Current datetime]"
Example: end_time=2020-01-02T23:59:59-03:00

Final datetime filter in ISO-8601 format
page_size
number <int32> (PageSizeParamV4) [ 1 .. 1000 ]
Default: 200
Example: page_size=100

Number of registers per page
c
string

The c parameter is the cursor you should use to fetch the next page of results

Responses

Response Schema: application/json
required
object (CursorTradesResponseData)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": {
    • "trades": [
      • {
        • "amount": 0.2404764,
        • "date": "2019-01-03T02:27:33.947Z",
        • "id": "2B222F22-5235-45FA-97FC-E9DBFA2575EE",
        • "maker_order_id": "F49F5BD8-3F5B-4364-BCEE-F36F62DB966A",
        • "maker_side": "buy",
        • "maker_type": "limit",
        • "pair": "BTC_BRL",
        • "price": 15160,
        • "taker_order_id": "FEAB5CEC-7F9E-4F95-B67D-9E8D5C739BE3",
        • "taker_side": "sell",
        • "taker_type": "market",
        • "timestamp": 1675708481219,
        • "total_value": 3638.4
        },
      • {
        • "amount": 0.00563617,
        • "date": "2019-01-03T02:27:33.943Z",
        • "id": "CDC492A5-B1BF-4353-BE7A-43F51C371388",
        • "maker_order_id": "53BF30D2-901C-43D5-B0D1-62CD05DFD02A",
        • "maker_side": "buy",
        • "maker_type": "limit",
        • "pair": "BTC_BRL",
        • "price": 15163,
        • "taker_order_id": "E4B1B38D-C871-4476-9314-3DC23292F45E",
        • "taker_side": "sell",
        • "taker_type": "limit",
        • "timestamp": 1675708481220,
        • "total_value": 84.91
        },
      • {
        • "amount": 0.00680154,
        • "date": "2019-01-03T02:27:33.940Z",
        • "id": "910AA20F-211F-4755-90A7-94227DB407D8",
        • "maker_order_id": "1FD30735-E055-4200-AD3D-007B02A5BA92",
        • "maker_side": "buy",
        • "maker_type": "limit",
        • "pair": "BTC_BRL",
        • "price": 15163.03,
        • "taker_order_id": "DBC6D4AF-D454-46DF-80EC-E19528A0FB25",
        • "taker_side": "sell",
        • "taker_type": "limit",
        • "timestamp": 1675708481221,
        • "total_value": 104.1
        }
      ],
    • "nc": "string",
    • "pc": "string"
    },
  • "error_code": null,
  • "message": null
}

User Orders

Lists the user's orders.

Authorizations:
API Credentials
query Parameters
pair
required
string
Example: pair=BTC_BRL

Currency pair code
status
Array of strings (OrderStatusParamV4)
Items Enum: "executed_completely" "executed_partially" "open" "canceled"
side
string (OrderSideParamV4)
Enum: "buy" "sell"

Order side (buy or sell)
type
string (OrderTypeParamV4)
Enum: "limit" "market" "stop_limit" "trailing" "ceiling" "iceberg"

Order type (limit, market, stop_limit, trailing, ceiling or iceberg)
ids
string (OrderIdsParamV4)
Example: ids=a6f7f8b3-e531-4522-810c-4f726f796b10,1594d0af-9239-466b-805b-a4f5df5f16d9

Identifiers list separated by commas (maximum of 10 identifiers)
start_date
string <date> (StartDateParamV4)
Default: "[10 days ago]"

Initial date filter in ISO-8601 format (shouldn't be before 2017-10-01)
end_date
string <date> (EndDateParamV4)
Default: "[Current date]"

Final date filter in ISO-8601 format (the interval between the initial and final date shouldn't be greater than 6 months)

page_size
number <int32> (PageSizeParamV4) [ 1 .. 1000 ]
Default: 200
Example: page_size=100

Number of registers per page
current_page
number <int32> (CurrentPageParamV4)
Default: 1
Example: current_page=3

Current page

Responses

Response Schema: application/json
required
object (UserOrdersDataV4)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": {
    • "orders": [
      • {
        • "create_date": "2017-12-08T23:42:54.960Z",
        • "executed_amount": 0.02347418,
        • "external_id": "B4A9F7F4-9C79-4921-9330-224C17260BDF",
        • "id": "857C0A3B-D70F-4256-9051-1C62FADBA8FA",
        • "pair": "BTC_BRL",
        • "price": 42600,
        • "remaining_amount": 0,
        • "remaining_value": 0,
        • "requested_amount": 0.02347418,
        • "requested_value": 1000,
        • "side": "buy",
        • "status": "executed_completely",
        • "total_value": 1000,
        • "type": "limit",
        • "update_date": "2017-12-13T21:48:48.817Z",
        • "fee": 1
        },
      • {
        • "create_date": "2017-10-20T00:26:40.403Z",
        • "executed_amount": 0.00033518,
        • "external_id": "13080055-7357-4110-81B1-981E6699FA57",
        • "id": "3ECBE371-DE24-42E8-841C-4281B3164CCE",
        • "pair": "BTC_BRL",
        • "price": 16352.12,
        • "remaining_amount": 0,
        • "remaining_value": 0,
        • "requested_amount": 0.00033518,
        • "requested_value": 5.48090358,
        • "side": "buy",
        • "status": "executed_completely",
        • "total_value": 5.48090358,
        • "type": "limit",
        • "update_date": "2017-10-20T00:26:40.467Z",
        • "fee": 1
        }
      ],
    • "pagination": {
      • "current_page": 1,
      • "registers_count": 21,
      • "total_pages": 1,
      • "page_size": 100
      }
    },
  • "error_code": null,
  • "message": null
}

Create Order

Creates a new order.

Publishes updates in the following websocket topics: trade (if there is a trade), orderbook, balance and order_status.

Authorizations:
API Credentials
Request Body schema: application/json
required
Any of
external_id
string (OrderExternalIdParamV4)

Order external identifier (maximum of 36 chars)
pair
required
string

Currency pair code
side
required
string
Value: "buy"

Order's side (buy)
type
required
string
Value: "limit"

Order's type (limit)
amount
required
number <double>

Amount
price
required
number <double>

Price
post_only
boolean

If set to true, the order will be added directly to the order book without an initial match, provided the request is valid

expiration
number <double>

If a valid timestamp is provided, the order will be created with an expiration date and time

immediate_or_cancel
boolean

If set to true, the order will not be added to the order book after the initial match, any remaining unfilled amount will result in the order being canceled

fill_or_kill
boolean

If set to true, the order will either be completely filled or canceled

Responses

Response Schema: application/json
required
object (UserOrderOutput)
error_code
required
number or null
Value: null
message
required
string or null

Request samples

Content type
application/json
Example
{
  • "amount": 0.1,
  • "pair": "BTC_BRL",
  • "price": 700000,
  • "side": "buy",
  • "type": "limit",
  • "post_only": false,
  • "expiration": 1723073682,
  • "immediate_or_cancel": false,
  • "fill_or_kill": false
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": "7155ED34-9EC4-4733-8B32-1E4319CB662F",
    • "create_date": "2024-03-27T13:27:19.853Z",
    • "executed_amount": 0,
    • "external_id": "BEAB10B1-45B0-4999-9B2F-D2ED048D6C42",
    • "pair": "BTC_BRL",
    • "remaining_amount": 10,
    • "remaining_value": 1000,
    • "requested_amount": 10,
    • "requested_value": 1000,
    • "side": "buy",
    • "status": "open"
    },
  • "error_code": null,
  • "message": null
}

Cancel Order

Cancels an active order by its id.

Publishes updates in the following websocket topics: orderbook, balance and order_status.

Authorizations:
API Credentials
Request Body schema: application/json
required
id
required
string

Order id

Responses

Response Schema: application/json
required
object (CancelResponseData)
error_code
required
number or null
Value: null
message
required
string or null

Request samples

Content type
application/json
{
  • "id": "7155ED34-9EC4-4733-8B32-1E4319CB662F"
}

Response samples

Content type
application/json
{
  • "data": {
    • "create_date": "2017-12-08T23:42:54.960Z",
    • "executed_amount": 0.02347418,
    • "external_id": "B4A9F7F4-9C79-4921-9330-224C17260BDF",
    • "id": "7155ED34-9EC4-4733-8B32-1E4319CB662F",
    • "pair": "BTC_BRL",
    • "price": 42600,
    • "remaining_amount": 0.1,
    • "remaining_value": 0.6,
    • "requested_amount": 0.02347418,
    • "requested_value": 1000,
    • "side": "buy",
    • "status": "canceled",
    • "total_value": 1000,
    • "type": "limit",
    • "update_date": "2017-12-13T21:48:48.817Z"
    },
  • "error_code": null,
  • "message": null
}

Update the amount and/or price of an order

Allows update the amount and/or price of an order, it is not possible to change a canceled or fully executed order.

Publishes updates in the following websocket topics: orderbook, and balance.

Authorizations:
API Credentials
Request Body schema: application/json
required
unit_price
string

New unit price. If the value executes another order immediately, it will not be possible to make the change

amount
string

New order amount
order_id
required
string

Order id

Responses

Response Schema: application/json
data
required
number or null
Value: null
error_code
required
number or null
Value: null
message
required
string or null

Request samples

Content type
application/json
{
  • "unit_price": "10",
  • "amount": "100",
  • "order_id": "00CE34E9-0168-4050-9D58-10C705A1AC81"
}

Response samples

Content type
application/json
{
  • "data": null,
  • "error_code": null,
  • "message": null
}

Get User Open Orders

Lists the user's open orders.

Authorizations:
API Credentials
query Parameters
pair
string
Example: pair=BTC_BRL

Currency pair code
side
string (OrderSideParamV4)
Enum: "buy" "sell"

Order side (buy or sell)
page_size
number <int32> (PageSizeParamV4) [ 1 .. 1000 ]
Default: 200
Example: page_size=100

Number of registers per page
current_page
number <int32> (CurrentPageParamV4)
Default: 1
Example: current_page=3

Current page

Responses

Response Schema: application/json
required
object (UserOpenOrdersDataV4)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": {
    • "orders": [
      • {
        • "create_date": "2017-12-08T23:42:54.960Z",
        • "executed_amount": 0.02347418,
        • "external_id": "B4A9F7F4-9C79-4921-9330-224C17260BDF",
        • "id": "857C0A3B-D70F-4256-9051-1C62FADBA8FA",
        • "pair": "BTC_BRL",
        • "price": 42600,
        • "remaining_amount": 0,
        • "remaining_value": 0,
        • "requested_amount": 0.02347418,
        • "requested_value": 1000,
        • "side": "buy",
        • "status": "executed_completely",
        • "fee": 0.004,
        • "total_value": 1000,
        • "type": "limit",
        • "update_date": "2017-12-13T21:48:48.817Z"
        },
      • {
        • "create_date": "2017-10-20T00:26:40.403Z",
        • "executed_amount": 0.00033518,
        • "external_id": "13080055-7357-4110-81B1-981E6699FA57",
        • "id": "3ECBE371-DE24-42E8-841C-4281B3164CCE",
        • "pair": "BTC_BRL",
        • "price": 16352.12,
        • "remaining_amount": 0,
        • "remaining_value": 0,
        • "requested_amount": 0.00033518,
        • "requested_value": 5.48090358,
        • "side": "buy",
        • "status": "executed_completely",
        • "fee": 0.004,
        • "total_value": 5.48090358,
        • "type": "limit",
        • "update_date": "2017-10-20T00:26:40.467Z"
        }
      ],
    • "pagination": {
      • "current_page": 1,
      • "registers_count": 21,
      • "total_pages": 1,
      • "page_size": 100
      }
    },
  • "error_code": null,
  • "message": null
}

Get Trades based on a order id

Get the trades from an order.

Attention: Due to performance concerns, this endpoint now uses cursor-based pagination. The pagination object currently included in the response is now a placeholder and will be entirely removed as of 2026-01-01. The parameter current_page is also a placeholder and will be removed at the same time. Please update your integration accordingly and refer to the documentation for the correct pagination handling.

Authorizations:
API Credentials
query Parameters
order_id
required
string

Order id from a valid order
page_size
number <int32> (PageSizeParamV4) [ 1 .. 1000 ]
Default: 200
Example: page_size=100

Number of registers per page
c
string

The c parameter is the cursor you should use to fetch the next page of results

Responses

Response Schema: application/json
required
object (UserTradesDataV4)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": {
    • "trades": [
      • {
        • "amount": 0.00270754,
        • "date": "2019-04-02T11:22:22.403Z",
        • "fee": 0.25,
        • "fee_currency": "USDC",
        • "id": "488F9395-47ED-4924-98AB-C860E1733A03",
        • "maker_order_id": "1FD30735-E055-4200-AD3D-007B02A5BA92",
        • "pair_code": "BTC_USDC",
        • "taker_or_maker": "maker",
        • "price": 18550,
        • "side": "sell",
        • "taker_order_id": "DBC6D4AF-D454-46DF-80EC-E19528A0FB25",
        • "timestamp": 1675708481219,
        • "type": "market",
        • "total_value": 50.22
        },
      • {
        • "amount": 0.0026938,
        • "date": "2019-04-02T11:25:41.512Z",
        • "fee": 0.00001347,
        • "fee_currency": "BTC",
        • "id": "C79ED37D-DC21-4D54-8AFC-4262347E3F8D",
        • "maker_order_id": "F49F5BD8-3F5B-4364-BCEE-F36F62DB966A",
        • "pair_code": "BTC_USDC",
        • "taker_or_maker": "taker",
        • "price": 18550,
        • "side": "buy",
        • "taker_order_id": "FEAB5CEC-7F9E-4F95-B67D-9E8D5C739BE3",
        • "timestamp": 1675708481220,
        • "type": "market",
        • "total_value": 49.96
        }
      ],
    • "pagination": {
      • "current_page": 1,
      • "registers_count": 21,
      • "total_pages": 1,
      • "page_size": 100
      },
    • "nc": "string",
    • "pc": "string"
    },
  • "error_code": null,
  • "message": null
}

User Order by Id

Returns the details of an order belonging to the user (by id).

Authorizations:
API Credentials
path Parameters
id
required
string (OrderIdParamV4)
Example: 1594d0af-9239-466b-805b-a4f5df5f16d9

Order identifier

Responses

Response Schema: application/json
required
object (UserPreparedOrderWithExecutions)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": {
    • "average_execution_price": 42600,
    • "create_date": "2017-12-08T23:42:54.960Z",
    • "external_id": "C90796F2-2CC3-4797-9AC3-A16BCC6936F0",
    • "executed_amount": 0.02347418,
    • "id": "8DE12108-4643-4E9F-8425-0172F1B96876",
    • "remaining_amount": 0,
    • "requested_amount": 0.02347418,
    • "requested_value": 1000,
    • "remaining_value": 0,
    • "pair": "BTC_BRL",
    • "price": 42600,
    • "side": "buy",
    • "status": "executed_completely",
    • "fee": 0.002,
    • "total_value": 1000,
    • "type": "limit",
    • "update_date": "2017-12-13T21:48:48.817Z",
    • "transactions": [
      • {
        • "amount": 0.2,
        • "create_date": "2020-02-21 20:24:43.433",
        • "fee": 0.12,
        • "fee_currency": "BTC",
        • "price": 5000,
        • "total_value": 1000
        },
      • {
        • "amount": 0.2,
        • "create_date": "2020-02-21 20:49:37.450",
        • "fee": 0.12,
        • "fee_currency": "BTC",
        • "price": 5000,
        • "total_value": 1000
        }
      ]
    },
  • "error_code": null,
  • "message": null
}

User Order by External Id

Returns the details of a order belonging to the user (by external id).

Authorizations:
API Credentials
path Parameters
external_id
required
string (OrderExternalIdParamV4)
Example: 0f4a8504-21fb-4be6-9771-25dcf5f68f87

Order external identifier (maximum of 36 chars)

Responses

Response Schema: application/json
required
object (UserPreparedOrderWithExecutions)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": {
    • "average_execution_price": 42600,
    • "create_date": "2017-12-08T23:42:54.960Z",
    • "external_id": "C90796F2-2CC3-4797-9AC3-A16BCC6936F0",
    • "executed_amount": 0.02347418,
    • "id": "8DE12108-4643-4E9F-8425-0172F1B96876",
    • "remaining_amount": 0,
    • "requested_amount": 0.02347418,
    • "requested_value": 1000,
    • "remaining_value": 0,
    • "pair": "BTC_BRL",
    • "price": 42600,
    • "side": "buy",
    • "status": "executed_completely",
    • "fee": 0.002,
    • "total_value": 1000,
    • "type": "limit",
    • "update_date": "2017-12-13T21:48:48.817Z",
    • "transactions": [
      • {
        • "amount": 0.2,
        • "create_date": "2020-02-21 20:24:43.433",
        • "fee": 0.12,
        • "fee_currency": "BTC",
        • "price": 5000,
        • "total_value": 1000
        },
      • {
        • "amount": 0.2,
        • "create_date": "2020-02-21 20:49:37.450",
        • "fee": 0.12,
        • "fee_currency": "BTC",
        • "price": 5000,
        • "total_value": 1000
        }
      ]
    },
  • "error_code": null,
  • "message": null
}

Cancel Order

Cancels an active order by its id using POST.

Publishes updates in the following websocket topics: orderbook, balance and order_status.

Authorizations:
API Credentials
Request Body schema: application/json
required
id
required
string

Order id

Responses

Response Schema: application/json
required
object (CancelResponseData)
error_code
required
number or null
Value: null
message
required
string or null

Request samples

Content type
application/json
{
  • "id": "7155ED34-9EC4-4733-8B32-1E4319CB662F"
}

Response samples

Content type
application/json
{
  • "data": {
    • "create_date": "2017-12-08T23:42:54.960Z",
    • "executed_amount": 0.02347418,
    • "external_id": "B4A9F7F4-9C79-4921-9330-224C17260BDF",
    • "id": "7155ED34-9EC4-4733-8B32-1E4319CB662F",
    • "pair": "BTC_BRL",
    • "price": 42600,
    • "remaining_amount": 0.1,
    • "remaining_value": 0.6,
    • "requested_amount": 0.02347418,
    • "requested_value": 1000,
    • "side": "buy",
    • "status": "canceled",
    • "total_value": 1000,
    • "type": "limit",
    • "update_date": "2017-12-13T21:48:48.817Z"
    },
  • "error_code": null,
  • "message": null
}

Cancel Order By External Id

Cancels an active order by its external_id.

Publishes updates in the following websocket topics: orderbook, balance and order_status.

Authorizations:
API Credentials
Request Body schema: application/json
required
external_id
required
string

Order external_id

Responses

Response Schema: application/json
required
object (CancelResponseData)
error_code
required
number or null
Value: null
message
required
string or null

Request samples

Content type
application/json
{
  • "external_id": "0F4A8504-21FB-4BE6-9771-25DCF5F68F87"
}

Response samples

Content type
application/json
{
  • "data": {
    • "create_date": "2017-12-08T23:42:54.960Z",
    • "executed_amount": 0.02347418,
    • "external_id": "B4A9F7F4-9C79-4921-9330-224C17260BDF",
    • "id": "7155ED34-9EC4-4733-8B32-1E4319CB662F",
    • "pair": "BTC_BRL",
    • "price": 42600,
    • "remaining_amount": 0.1,
    • "remaining_value": 0.6,
    • "requested_amount": 0.02347418,
    • "requested_value": 1000,
    • "side": "buy",
    • "status": "canceled",
    • "total_value": 1000,
    • "type": "limit",
    • "update_date": "2017-12-13T21:48:48.817Z"
    },
  • "error_code": null,
  • "message": null
}

Cancel Order By External Id

Cancels an active order by its external_id using POST.

Publishes updates in the following websocket topics: orderbook, balance and order_status.

Authorizations:
API Credentials
Request Body schema: application/json
required
external_id
required
string

Order external_id

Responses

Response Schema: application/json
required
object (CancelResponseData)
error_code
required
number or null
Value: null
message
required
string or null

Request samples

Content type
application/json
{
  • "external_id": "0F4A8504-21FB-4BE6-9771-25DCF5F68F87"
}

Response samples

Content type
application/json
{
  • "data": {
    • "create_date": "2017-12-08T23:42:54.960Z",
    • "executed_amount": 0.02347418,
    • "external_id": "B4A9F7F4-9C79-4921-9330-224C17260BDF",
    • "id": "7155ED34-9EC4-4733-8B32-1E4319CB662F",
    • "pair": "BTC_BRL",
    • "price": 42600,
    • "remaining_amount": 0.1,
    • "remaining_value": 0.6,
    • "requested_amount": 0.02347418,
    • "requested_value": 1000,
    • "side": "buy",
    • "status": "canceled",
    • "total_value": 1000,
    • "type": "limit",
    • "update_date": "2017-12-13T21:48:48.817Z"
    },
  • "error_code": null,
  • "message": null
}

Cancel All Orders

Cancels all the user's active orders.

Publishes updates in the following websocket topics: orderbook, balance and order_status.

Authorizations:
API Credentials
Request Body schema: application/json
required
pair
string

Currency pair code

Responses

Response Schema: application/json
required
Array of objects (CancelAllOrdersData)
error_code
required
number or null
Value: null
message
required
string or null

Request samples

Content type
application/json
{
  • "pair": "BTC_BRL"
}

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "order_id": "F6D2661E-4D6F-4770-BBE6-CC063CBA3770",
      • "pair_code": "BTC_BRL",
      • "success": true
      },
    • {
      • "order_id": "7155ED34-9EC4-4733-8B32-1E4319CB662F",
      • "pair_code": "BTC_BRL",
      • "success": false
      }
    ],
  • "error_code": null,
  • "message": null
}

Estimate Price

Estimates the market unit price for a specific amount of a given currency pair.

Authorizations:
API Credentials
path Parameters
pair
required
string
Example: BTC_BRL

Currency pair code
query Parameters
amount
required
number <double>

Amount to be used in the estimative.
side
required
string (OrderSideParamV4)
Enum: "buy" "sell"

Order side (buy or sell)

Responses

Response Schema: application/json
required
object (EstimatedPriceResponseDataV4)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": {
    • "price": 54049.12
    },
  • "error_code": null,
  • "message": null
}

Cryptocurrency Deposits

List Cryptocurrency Deposits

Lists the user's cryptocurrency deposits.

Attention: Due to performance concerns, this endpoint now uses cursor-based pagination. The pagination object currently included in the response is now a placeholder and will be entirely removed as of 2026-01-01. The parameter current_page is also a placeholder and will be removed at the same time. Please update your integration accordingly and refer to the documentation for the correct pagination handling.

Authorizations:
API Credentials
query Parameters
currency_code
string
Example: currency_code=BTC

Currency code
status
string (DepositStatusParamV4)
Enum: "confirmation_pending" "confirmed" "canceled"

Deposit status
start_date
string <date> (StartDateNoMinParamV4)
Default: "[6 months ago]"

Initial date filter in ISO-8601 format
end_date
string <date> (EndDateNoMinParamV4)
Default: "[Current date]"

Final date filter in ISO-8601 format
page_size
number <int32> (PageSizeParamV4) [ 1 .. 1000 ]
Default: 200
Example: page_size=100

Number of registers per page
current_page
number <int32> (CurrentPageParamV4)
Default: 1
Example: current_page=3

Current page
network
string
Example: network=bitcoin

Network
c
string
Example: c=BTC

The c parameter is the cursor you should use to fetch the next page of results

Responses

Response Schema: application/json
required
object (DepositsDataV4)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": {
    • "deposits": [
      • {
        • "amount": 2.29999999,
        • "confirmation_date": "2017-10-12T22:40:08.273Z",
        • "create_date": "2017-10-12T22:40:08.273Z",
        • "currency_code": "BTC",
        • "id": "3D41EEF3-A709-4EE5-BDEE-B6435CAA84C8",
        • "is_internal": false,
        • "hash": "4f87d009d88524e627b60c6fbe4ebe671a99lk9ad72aab17e0963c5fbef118e2",
        • "network": "bitcoin",
        • "status": "confirmed"
        },
      • {
        • "amount": 2.29999999,
        • "confirmation_date": "2017-10-12T20:06:52.983Z",
        • "create_date": "2017-10-12T20:06:52.983Z",
        • "currency_code": "BTC",
        • "id": "3011675E-A549-46F3-A70B-0F0B0A01A2D6",
        • "is_internal": false,
        • "hash": "181378774394ec47b9861d9facfcd4d4ea11a447tr82532c654d5ee1306b4857",
        • "network": "bitcoin",
        • "status": "confirmed"
        }
      ],
    • "pagination": {
      • "current_page": 1,
      • "registers_count": 21,
      • "total_pages": 1,
      • "page_size": 100
      },
    • "nc": "string",
    • "pc": "string"
    },
  • "error_code": null,
  • "message": null
}

Get Cryptocurrency Deposit

Gets a cryptocurrency deposit.

Authorizations:
API Credentials
query Parameters
id
string
Example: id=000A650D-F8A5-419A-A4C4-194452345981

Deposit identifier
hash
string
Example: hash=000A650D-F8A5-419A-A4C4-194452345981

Transaction hash

Responses

Response Schema: application/json
required
object (DepositV4)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": {
    • "amount": 2.29999999,
    • "confirmation_date": "2017-10-12T22:40:08.273Z",
    • "create_date": "2017-10-12T22:40:08.273Z",
    • "currency_code": "BTC",
    • "id": "3D41EEF3-A709-4EE5-BDEE-B6435CAA84C8",
    • "is_internal": false,
    • "hash": "4f87d009d88524e627b60c6fbe4ebe671a99lk9ad72aab17e0963c5fbef118e2",
    • "network": "bitcoin",
    • "status": "confirmed"
    },
  • "error_code": null,
  • "message": null
}

Cryptocurrency Withdrawals

List Cryptocurrency Withdrawals

Lists the user's cryptocurrency withdrawals.

Attention: Due to performance concerns, this endpoint now uses cursor-based pagination. The pagination object currently included in the response is now a placeholder and will be entirely removed as of 2026-01-01. The parameter current_page is also a placeholder and will be removed at the same time. Please update your integration accordingly and refer to the documentation for the correct pagination handling.

Authorizations:
API Credentials
query Parameters
currency_code
string
Example: currency_code=BTC

Currency code
status
string (WithdrawalStatusParamV4)
Enum: "pending" "confirmed" "canceled"

Withdrawal status
start_date
string <date> (StartDateNoMinParamV4)
Default: "[6 months ago]"

Initial date filter in ISO-8601 format
end_date
string <date> (EndDateNoMinParamV4)
Default: "[Current date]"

Final date filter in ISO-8601 format
page_size
number <int32> (PageSizeParamV4) [ 1 .. 1000 ]
Default: 200
Example: page_size=100

Number of registers per page
current_page
number <int32> (CurrentPageParamV4)
Default: 1
Example: current_page=3

Current page
network
string
Example: network=bitcoin

Network
c
string
Example: c=BTC

The c parameter is the cursor you should use to fetch the next page of results

Responses

Response Schema: application/json
required
object (WithdrawalsDataV4)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": {
    • "withdrawals": [
      • {
        • "amount": 0.1,
        • "create_date": "2019-01-25T16:37:15.443Z",
        • "currency_code": "BTC",
        • "destination_address": "rw9nf3WgsagJiZnkAeZzXZuqeCQ6LHm2h1",
        • "external_id": "rtd-9012-lkju-908",
        • "is_internal": true,
        • "link": null,
        • "miner_fee": 0.000012,
        • "miner_fee_type": "regular",
        • "network": "bitcoin",
        • "status": "pending",
        • "transaction_id": "5890ASHIUHC089189YSHBNJKHAG978891",
        • "update_date": "2019-01-25T16:37:15.017Z",
        • "id": "A1DCD3B6-1CBD-4F17-ADA0-230ADEC04173",
        • "fee": 0,
        • "hash": null,
        • "memo": "656899",
        • "tag": "0100000020"
        },
      • {
        • "amount": 0.1,
        • "create_date": "2019-01-25T16:37:15.443Z",
        • "currency_code": "BTC",
        • "destination_address": "rw9nf3WgsagJiZnkAeZzXZuqeCQ6LHm2h1",
        • "external_id": "rtd-9012-lkju-908",
        • "is_internal": true,
        • "link": null,
        • "miner_fee": 0.000012,
        • "miner_fee_type": "regular",
        • "network": "bitcoin",
        • "status": "pending",
        • "transaction_id": "5890ASHIUHC089189YSHBNJKHAG978891",
        • "update_date": "2019-01-25T16:37:15.017Z",
        • "id": "A1DCD3B6-1CBD-4F17-ADA0-230ADEC04173",
        • "fee": 0,
        • "hash": null,
        • "memo": "656899",
        • "tag": "0100000020"
        }
      ],
    • "pagination": {
      • "current_page": 1,
      • "registers_count": 21,
      • "total_pages": 1,
      • "page_size": 100
      },
    • "nc": "string",
    • "pc": "string"
    },
  • "error_code": null,
  • "message": null
}

Create Cryptocurrency Withdrawal

Creates a cryptocurrency withdrawal.

Authorizations:
API Credentials
Request Body schema: application/json
required
fee_included
boolean

If true, the fee is deducted from the amount specified. This means the total charge remains exactly equal to the requested amount, and the recipient receives the net amount after the fee is subtracted. Example: If you request a withdrawal of 100 and the fee is 1, the user is charged 100 and receives 99. Default value is true.

external_id
string

Withdrawal external identifier (maximum of 36 chars)
tag
string

Destination tag

⚠️ Check the information about this currency in the public currencies endpoint to check if this currency offers tag for withdrawals, and if has tag for deposit in case of a Ripio Trade address destination

network
string

Destination network
memo
string

Destination memo

⚠️ Check the information about this currency in the public currencies endpoint to check if this currency offers memo for withdrawals, and if has memo for deposit in case of a Ripio Trade address destination

amount
required
number <float>

Amount
destination
required
string

Destination address. This address needs to be bound to a registered wallet. You can register a wallet on: https://trade.ripio.com/market/api/wallets

currency_code
required
string

Currency code

Responses

Response Schema: application/json
required
object (Omit_WithdrawalV4.miner_fee_type-or-is_internal_)

From T, pick a set of properties whose keys are in the union K
error_code
required
number or null
Value: null
message
required
string or null

Request samples

Content type
application/json
{
  • "fee_included": true,
  • "external_id": "2352b104-3f8c-47da-b817-46c942350c95",
  • "tag": null,
  • "network": "bitcoin",
  • "memo": null,
  • "amount": 7.77,
  • "destination": "1AU4BoYaxSunkEWikEMYXJ41c9bvQG6Wa2",
  • "currency_code": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": "A1DCD3B6-1CBD-4F17-ADA0-230ADEC04173",
    • "amount": 0.1,
    • "create_date": "2019-01-25T16:37:15.443Z",
    • "currency_code": "BTC",
    • "destination_address": "rw9nf3WgsagJiZnkAeZzXZuqeCQ6LHm2h1",
    • "external_id": "rtd-9012-lkju-908",
    • "link": null,
    • "miner_fee": 0,
    • "network": "bitcoin",
    • "status": "pending",
    • "transaction_id": null,
    • "update_date": "2019-01-25T16:37:15.443Z",
    • "fee": 0,
    • "hash": null,
    • "memo": "string",
    • "tag": "string"
    },
  • "error_code": null,
  • "message": null
}

Estimate Withdrawal Fee

Estimates the miner fee for a cryptocurrency withdrawal.

Authorizations:
API Credentials
path Parameters
currency_code
required
string
Example: BTC

Currency code
query Parameters
network
string
Example: network=bitcoin

Network
amount
number <double>

Amount

Responses

Response Schema: application/json
required
object (WithdrawalFeeDataV4)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": {
    • "amount": 0.1,
    • "network": "string"
    },
  • "error_code": null,
  • "message": null
}

Get Cryptocurrency Withdrawal

Gets a cryptocurrency withdrawal.

Authorizations:
API Credentials
query Parameters
id
string
Example: id=000A650D-F8A5-419A-A4C4-194452345981

Withdrawal identifier
external_id
string
Example: external_id=000A650D-F8A5-419A-A4C4-194452345981

Withdrawal external identifier

Responses

Response Schema: application/json
required
object (WithdrawalV4)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": {
    • "amount": 0.1,
    • "create_date": "2019-01-25T16:37:15.443Z",
    • "currency_code": "BTC",
    • "destination_address": "rw9nf3WgsagJiZnkAeZzXZuqeCQ6LHm2h1",
    • "external_id": "rtd-9012-lkju-908",
    • "is_internal": false,
    • "link": null,
    • "miner_fee": 0,
    • "miner_fee_type": 1,
    • "network": "bitcoin",
    • "status": "pending",
    • "transaction_id": null,
    • "update_date": "2019-01-25T16:37:15.443Z",
    • "id": "A1DCD3B6-1CBD-4F17-ADA0-230ADEC04173",
    • "fee": 0,
    • "hash": null,
    • "memo": "string",
    • "tag": "string"
    },
  • "error_code": null,
  • "message": null
}

Wallets

API to check addresses of wallets.

Is internal

Indicates if a given wallet belongs to Ripio Trade.

Authorizations:
API Credentials
query Parameters
address
required
string (AddressParamV4)
Example: address=2MsPTuASaY8QjQmKFWDyHzYxzpASzKpv7YF

Wallet address
currency_code
string
Example: currency_code=BTC

Currency code

Responses

Response Schema: application/json
required
object (IsInternalV4)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": {
    • "is_internal": true
    },
  • "error_code": null,
  • "message": null
}

Wallets

Lists the user's wallets.

Authorizations:
API Credentials

Responses

Response Schema: application/json
required
Array of objects (WalletResponseDataV4)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": [
    • [
      • {
        • "address": "3JentmkNdL97VQDtgRMehxPOMS4AveUZJ1",
        • "currency_code": "BTC",
        • "memo": null,
        • "network": "bitcoin",
        • "tag": null
        }
      ]
    ],
  • "error_code": null,
  • "message": null
}

Get User Wallet

Get user network's currency address

Authorizations:
API Credentials
path Parameters
currency_code
required
string
Example: BTC

Currency code
network
required
string
Example: bitcoin

Network

Responses

Response Schema: application/json
required
object (GetUserWalletAndCreateIfNotExistsV4)
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": {
    • "address": "string",
    • "currency_code": "BTC",
    • "tag": "string",
    • "memo": "string",
    • "network": "string"
    },
  • "error_code": null,
  • "message": null
}

Transactions

Synchronize Transaction

Manually synchronize a cryptocurrency deposit.

Authorizations:
API Credentials
Request Body schema: application/json
required
hash
required
string

Transaction hash
currency_code
required
string

Currency code
block_id
number <double>

Transaction block id

⚠️ Check the information about this currency in the public currencies endpoint to check if this currency demands block number for transaction sync

Responses

Response Schema: application/json
data
required
number or null
Value: null
error_code
required
number or null
Value: null
message
required
string or null

Request samples

Content type
application/json
{
  • "block_id": 123456,
  • "currency_code": "BTC",
  • "hash": "7b6155e3d010b530f484e0cd05429328a514dd0158dc31c23cdd3ebb59f335ae"
}

Response samples

Content type
application/json
{
  • "data": null,
  • "error_code": null,
  • "message": null
}

Ticket

WebSocket ticket

Creates a new websocket ticket. Should be sent in the body property called ticket to subscribe to the websocket private topics.

Authorizations:
API Credentials

Responses

Response Schema: application/json
required
object
error_code
required
number or null
Value: null
message
required
string or null

Response samples

Content type
application/json
{
  • "data": {
    • "ticket": "D90A9A10-06AF-44AF-8592-BAF866DD1503"
    },
  • "error_code": null,
  • "message": null
}

WebSocket Stream

Our websocket stream service provides real time updates about market data via websocket protocol.

How to subscribe to topics

After connected to the websocket wss://ws.ripiotrade.co you should send the following json: 

{
  "method": "subscribe", 
  "topics": ["topic@BASE_QUOTE"] 
}

The methods available are:

  • subscribe
  • unsubscribe
  • ping

Private topics

Some of these topics require a ticket authorizing their usage, since these topics contain sensitive user information

To generate a new ticket you should send a POST request on https://api.ripiotrade.co/v4/ticket

You will get a response like this:

{
  "message": null,
  "data": { "ticket": "d90a9a10-06af-44af-8592-baf866dd1503"} 
}

. Then you can subscribe to a private websocket by passing right params incluing the ticket this way: 

{
  "method": "subscribe", 
  "topics": ["order_status"], 
  "ticket": "d90a9a10-06af-44af-8592-baf866dd1503" 
}

trade@BASE_QUOTE Topic

This topic listens for trades of a given pair (BASE_QUOTE), so it will be notified every time a trade happens.

Request Body schema: application/json
method
required
string (MethodEnum)
Enum: "subscribe" "unsubscribe" "ping"

Method to be executed
topics
required
Array of strings (TopicEnum)
Items Enum: "trade" "orderbook/level_3" "orderbook/level_2" "orderbook/level_2_with_users" "orderbook/level_2_delta" "ticker" "order_status" "balance" "user_trades" "deposit" "withdrawal"

Topics to subscribe to

Responses

Response Schema: application/json
required
object (ISocketTrade)
id
required
number <double>

Each WebSocket message includes a sequential numeric id. Each topic has its own unique sequence, and for private topics, the sequence is unique to each topic and user. It's important to note that some topics will send a "welcome message", which will have an id value of -1. Additionally, this sequence may be reset between connections, so be sure to update this value locally whenever you reconnect.

timestamp
required
number <double>

Timestamp in milliseconds
topic
required
string (TopicEnum)
Enum: "trade" "orderbook/level_3" "orderbook/level_2" "orderbook/level_2_with_users" "orderbook/level_2_delta" "ticker" "order_status" "balance" "user_trades" "deposit" "withdrawal"

Request samples

Content type
application/json
{
  • "method": "subscribe",
  • "topics": [
    • "trade@ETH_BRL"
    ]
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "topic": "trade@ETH_BRL",
  • "timestamp": 1672856503549,
  • "body": {
    • "amount": 0.2404764,
    • "date": "2019-01-03T02:27:33.947Z",
    • "id": "2B222F22-5235-45FA-97FC-E9DBFA2575EE",
    • "maker_order_id": "F49F5BD8-3F5B-4364-BCEE-F36F62DB966A",
    • "maker_side": "buy",
    • "maker_type": "limit",
    • "pair": "ETH_BRL",
    • "price": 15160,
    • "taker_order_id": "FEAB5CEC-7F9E-4F95-B67D-9E8D5C739BE3",
    • "taker_side": "sell",
    • "taker_type": "market",
    • "timestamp": 1675780847920,
    • "total_value": 3638.4
    }
}

orderbook/level_3@BASE_QUOTE Topic

This topic will notify whenever an order is opened, canceled or a trade happens for the given pair (BASE_QUOTE). By default, the system notifies the topic every 30 seconds, even if a transaction has not taken place. Each side will contain up to 100 orders.

Request Body schema: application/json
method
required
string (MethodEnum)
Enum: "subscribe" "unsubscribe" "ping"

Method to be executed
topics
required
Array of strings (TopicEnum)
Items Enum: "trade" "orderbook/level_3" "orderbook/level_2" "orderbook/level_2_with_users" "orderbook/level_2_delta" "ticker" "order_status" "balance" "user_trades" "deposit" "withdrawal"

Topics to subscribe to

Responses

Response Schema: application/json
required
object (IOrderBookLevel3)
id
required
number <double>

Each WebSocket message includes a sequential numeric id. Each topic has its own unique sequence, and for private topics, the sequence is unique to each topic and user. It's important to note that some topics will send a "welcome message", which will have an id value of -1. Additionally, this sequence may be reset between connections, so be sure to update this value locally whenever you reconnect.

timestamp
required
number <double>

Timestamp in milliseconds
topic
required
string (TopicEnum)
Enum: "trade" "orderbook/level_3" "orderbook/level_2" "orderbook/level_2_with_users" "orderbook/level_2_delta" "ticker" "order_status" "balance" "user_trades" "deposit" "withdrawal"

Request samples

Content type
application/json
{
  • "method": "subscribe",
  • "topics": [
    • "orderbook/level_3@ETH_BRL"
    ]
}

Response samples

Content type
application/json
{
  • "id": 2,
  • "topic": "orderbook/level_3@ETH_BRL",
  • "timestamp": 1672857013503,
  • "body": {
    • "asks": [
      • {
        • "amount": 184.9,
        • "id": "43758DB1-3257-4C98-A20F-7F246E460A50",
        • "price": 20
        },
      • {
        • "amount": 10,
        • "id": "4B86ACC5-76B2-4003-AF20-F398CE9EDC92",
        • "price": 20
        }
      ],
    • "bids": [
      • {
        • "amount": 400,
        • "id": "B075FDF9-9B68-4299-87E0-5FC8B40B3ABD",
        • "price": 5
        },
      • {
        • "amount": 20,
        • "id": "606763A5-4B95-4216-9F07-69C6B51D64F0",
        • "price": 5
        }
      ],
    • "pair": "ETH_BRL",
    • "hash": "2254383345"
    }
}

orderbook/level_2@BASE_QUOTE Topic

This topic will notify whenever an order is opened, canceled or a trade happens for the given pair (BASE_QUOTE). Since it is a level 2 orderbook, the orders are going to be grouped by price. By default, the system notifies the topic every 30 seconds, even if a transaction has not taken place. Each side will contain up to 100 price levels.

Request Body schema: application/json
method
required
string (MethodEnum)
Enum: "subscribe" "unsubscribe" "ping"

Method to be executed
topics
required
Array of strings (TopicEnum)
Items Enum: "trade" "orderbook/level_3" "orderbook/level_2" "orderbook/level_2_with_users" "orderbook/level_2_delta" "ticker" "order_status" "balance" "user_trades" "deposit" "withdrawal"

Topics to subscribe to

Responses

Response Schema: application/json
required
object (IOrderBookLevel2WithoutUsers)
id
required
number <double>

Each WebSocket message includes a sequential numeric id. Each topic has its own unique sequence, and for private topics, the sequence is unique to each topic and user. It's important to note that some topics will send a "welcome message", which will have an id value of -1. Additionally, this sequence may be reset between connections, so be sure to update this value locally whenever you reconnect.

timestamp
required
number <double>

Timestamp in milliseconds
topic
required
string (TopicEnum)
Enum: "trade" "orderbook/level_3" "orderbook/level_2" "orderbook/level_2_with_users" "orderbook/level_2_delta" "ticker" "order_status" "balance" "user_trades" "deposit" "withdrawal"

Request samples

Content type
application/json
{
  • "method": "subscribe",
  • "topics": [
    • "orderbook/level_2@ETH_BRL"
    ]
}

Response samples

Content type
application/json
{
  • "id": 3,
  • "topic": "orderbook/level_2@ETH_BRL",
  • "timestamp": 1672856653428,
  • "body": {
    • "asks": [
      • {
        • "amount": 184.9,
        • "price": 20
        },
      • {
        • "amount": 10,
        • "price": 25
        }
      ],
    • "bids": [
      • {
        • "amount": 400,
        • "price": 5
        },
      • {
        • "amount": 20,
        • "price": 4
        }
      ],
    • "pair": "ETH_BRL",
    • "hash": "2254383345"
    }
}

orderbook/level_2_delta@BASE_QUOTE Topic

This topic will always notify a change at a price level of the order book when an order is opened, canceled or a trade takes place for a given pair (BASE_QUOTE). In other words, it is the variation in the amount of assets available for buy or sell at a given price level. In each topic event the amount is the absolute quantity for a price level, and if the amount is 0, you should remove the price level from the order book.

Important! In addition to the delta messages, the first message sent upon connection will be a snapshot of the level 2 order book.

Request Body schema: application/json
method
required
string (MethodEnum)
Enum: "subscribe" "unsubscribe" "ping"

Method to be executed
topics
required
Array of strings (TopicEnum)
Items Enum: "trade" "orderbook/level_3" "orderbook/level_2" "orderbook/level_2_with_users" "orderbook/level_2_delta" "ticker" "order_status" "balance" "user_trades" "deposit" "withdrawal"

Topics to subscribe to

Responses

Response Schema: application/json
required
object (IOrderBookLevel2WithoutUsers)
id
required
number <double>

Each WebSocket message includes a sequential numeric id. Each topic has its own unique sequence, and for private topics, the sequence is unique to each topic and user. It's important to note that some topics will send a "welcome message", which will have an id value of -1. Additionally, this sequence may be reset between connections, so be sure to update this value locally whenever you reconnect.

timestamp
required
number <double>

Timestamp in milliseconds
topic
required
string (TopicEnum)
Enum: "trade" "orderbook/level_3" "orderbook/level_2" "orderbook/level_2_with_users" "orderbook/level_2_delta" "ticker" "order_status" "balance" "user_trades" "deposit" "withdrawal"

Request samples

Content type
application/json
{
  • "method": "subscribe",
  • "topics": [
    • "orderbook/level_2_delta@ETH_BRL"
    ]
}

Response samples

Content type
application/json
{
  • "id": 4,
  • "topic": "orderbook/level_2_delta@ETH_BRL",
  • "timestamp": 1672856653428,
  • "body": {
    • "asks": [
      • {
        • "amount": 0,
        • "price": 25
        }
      ],
    • "bids": [
      • {
        • "amount": 20,
        • "price": 25
        }
      ],
    • "pair": "ETH_BRL",
    • "hash": "2254383345"
    }
}

orderbook/level_2_with_users@BASE_QUOTE Topic

This topic will notify whenever an order is opened, canceled or a trade happens for the given pair (BASE_QUOTE). Since it is a level 2 orderbook, the orders are going to be grouped by price, and this also includes an array with users ids that have an order at that level. By default, the system notifies the topic every 30 seconds, even if a transaction has not taken place. Each side will contain up to 100 price levels.

Request Body schema: application/json
method
required
string (MethodEnum)
Enum: "subscribe" "unsubscribe" "ping"

Method to be executed
topics
required
Array of strings (TopicEnum)
Items Enum: "trade" "orderbook/level_3" "orderbook/level_2" "orderbook/level_2_with_users" "orderbook/level_2_delta" "ticker" "order_status" "balance" "user_trades" "deposit" "withdrawal"

Topics to subscribe to

Responses

Response Schema: application/json
required
object (IOrderBookLevel2)
id
required
number <double>

Each WebSocket message includes a sequential numeric id. Each topic has its own unique sequence, and for private topics, the sequence is unique to each topic and user. It's important to note that some topics will send a "welcome message", which will have an id value of -1. Additionally, this sequence may be reset between connections, so be sure to update this value locally whenever you reconnect.

timestamp
required
number <double>

Timestamp in milliseconds
topic
required
string (TopicEnum)
Enum: "trade" "orderbook/level_3" "orderbook/level_2" "orderbook/level_2_with_users" "orderbook/level_2_delta" "ticker" "order_status" "balance" "user_trades" "deposit" "withdrawal"

Request samples

Content type
application/json
{
  • "method": "subscribe",
  • "topics": [
    • "orderbook/level_2_with_users@ETH_BRL"
    ]
}

Response samples

Content type
application/json
{
  • "id": 5,
  • "topic": "orderbook/level_2_with_users@ETH_BRL",
  • "timestamp": 1672856653428,
  • "body": {
    • "asks": [
      • {
        • "amount": 184.9,
        • "price": 20,
        • "users": [
          • "5EF6B2C9-28C9-4C50-99EA-7F3A38958F0A"
          ]
        },
      • {
        • "amount": 10,
        • "price": 25,
        • "users": [
          • "5EF6B2C9-28C9-4C50-99EA-7F3A38958F0A"
          ]
        }
      ],
    • "bids": [
      • {
        • "amount": 400,
        • "price": 5,
        • "users": [
          • "5EF6B2C9-28C9-4C50-99EA-7F3A38958F0A"
          ]
        },
      • {
        • "amount": 20,
        • "price": 4,
        • "users": [
          • "5EF6B2C9-28C9-4C50-99EA-7F3A38958F0A"
          ]
        }
      ],
    • "pair": "ETH_BRL",
    • "hash": "2254383345"
    }
}

ticker@BASE_QUOTE Topic

This topic delivers notifications for 24 hour window statistics for a pair (BASE_QUOTE), and this will happen whenever an order is opened, canceled or a trade happens for the given pair. By default, the system notifies the topic every 30 seconds, even if a transaction has not taken place.

Request Body schema: application/json
method
required
string (MethodEnum)
Enum: "subscribe" "unsubscribe" "ping"

Method to be executed
topics
required
Array of strings (TopicEnum)
Items Enum: "trade" "orderbook/level_3" "orderbook/level_2" "orderbook/level_2_with_users" "orderbook/level_2_delta" "ticker" "order_status" "balance" "user_trades" "deposit" "withdrawal"

Topics to subscribe to

Responses

Response Schema: application/json
required
object (ITickerV4)
id
required
number <double>

Each WebSocket message includes a sequential numeric id. Each topic has its own unique sequence, and for private topics, the sequence is unique to each topic and user. It's important to note that some topics will send a "welcome message", which will have an id value of -1. Additionally, this sequence may be reset between connections, so be sure to update this value locally whenever you reconnect.

timestamp
required
number <double>

Timestamp in milliseconds
topic
required
string (TopicEnum)
Enum: "trade" "orderbook/level_3" "orderbook/level_2" "orderbook/level_2_with_users" "orderbook/level_2_delta" "ticker" "order_status" "balance" "user_trades" "deposit" "withdrawal"

Request samples

Content type
application/json
{
  • "method": "subscribe",
  • "topics": [
    • "ticker@ETH_BRL"
    ]
}

Response samples

Content type
application/json
{
  • "id": 6,
  • "topic": "ticker@ETH_BRL",
  • "timestamp": 1672856683447,
  • "body": {
    • "ask": 4.01,
    • "base_code": "ETH",
    • "base_id": "27698137-8178-4395-9841-C1B1505C9352",
    • "conversions": [
      • {
        • "currency_code": "BRL",
        • "volume": 0
        },
      • {
        • "currency_code": "BTC",
        • "volume": 0
        },
      • {
        • "currency_code": "ETH",
        • "volume": 0
        },
      • {
        • "currency_code": "USD",
        • "volume": 0
        },
      • {
        • "currency_code": "USDC",
        • "volume": 0
        },
      • {
        • "currency_code": "UXD",
        • "volume": 0
        },
      • {
        • "currency_code": "ARS",
        • "volume": 0
        },
      • {
        • "currency_code": "MXN",
        • "volume": 0
        }
      ],
    • "bid": 5,
    • "date": "2022-09-28T19:13:40.887Z",
    • "high": 20,
    • "low": 20,
    • "pair": "ETH_BRL",
    • "price_change_percent_24h": "-16.66",
    • "quote_code": "BRL",
    • "quote_id": "48898138-8623-4555-9468-B1A1505A9352",
    • "quote_volume": 600,
    • "trades_quantity": 10,
    • "volume": 124,
    • "first": 10,
    • "last": 20
    }
}

order_status Topic

This topic is responsible for notifing the user every time one of its orders is updated (created, executed, canceled).

Request Body schema: application/json
method
required
string (MethodEnum)
Enum: "subscribe" "unsubscribe" "ping"

Method to be executed
topics
required
Array of strings (TopicEnum)
Items Enum: "trade" "orderbook/level_3" "orderbook/level_2" "orderbook/level_2_with_users" "orderbook/level_2_delta" "ticker" "order_status" "balance" "user_trades" "deposit" "withdrawal"

Topics to subscribe to
ticket
required
string

Ticket created using the endpoint POST https://api.ripiotrade.co/v4/ticket

Responses

Response Schema: application/json
required
object (IOrderStatus)
id
required
number <double>

Each WebSocket message includes a sequential numeric id. Each topic has its own unique sequence, and for private topics, the sequence is unique to each topic and user. It's important to note that some topics will send a "welcome message", which will have an id value of -1. Additionally, this sequence may be reset between connections, so be sure to update this value locally whenever you reconnect.

timestamp
required
number <double>

Timestamp in milliseconds
topic
required
string (TopicEnum)
Enum: "trade" "orderbook/level_3" "orderbook/level_2" "orderbook/level_2_with_users" "orderbook/level_2_delta" "ticker" "order_status" "balance" "user_trades" "deposit" "withdrawal"

Request samples

Content type
application/json
{
  • "method": "subscribe",
  • "topics": [
    • "order_status"
    ],
  • "ticket": "97794B95-AFE7-454F-81B0-9109112548C2"
}

Response samples

Content type
application/json
{
  • "id": 7,
  • "topic": "order_status",
  • "timestamp": 1672856713677,
  • "body": {
    • "amount": 4,
    • "average_execution_price": 6,
    • "id": "F55E4E01-C39B-4AA7-848B-1C6A362C386E",
    • "created_at": "2023-01-24T17:28:32.247Z",
    • "executed_amount": 4,
    • "external_id": null,
    • "pair": "ETH_BRL",
    • "price": 6,
    • "remaining_amount": 0,
    • "side": "buy",
    • "status": "executed_completely",
    • "type": "limit",
    • "updated_at": "2023-01-24T17:28:33.993Z",
    • "user_id": "30B8CDBB-BDBD-4B60-A90F-860AB46B76F7"
    }
}

balance Topic

Every time there is a change in the user's balance, this topic will be notified. Actions like create / cancel order, deposit / withdraw currency or a trade being executed, are gonna change the use''s balance.

Request Body schema: application/json
method
required
string (MethodEnum)
Enum: "subscribe" "unsubscribe" "ping"

Method to be executed
topics
required
Array of strings (TopicEnum)
Items Enum: "trade" "orderbook/level_3" "orderbook/level_2" "orderbook/level_2_with_users" "orderbook/level_2_delta" "ticker" "order_status" "balance" "user_trades" "deposit" "withdrawal"

Topics to subscribe to
ticket
required
string

Ticket created using the endpoint POST https://api.ripiotrade.co/v4/ticket

Responses

Response Schema: application/json
required
object (SocketBalance)
id
required
number <double>

Each WebSocket message includes a sequential numeric id. Each topic has its own unique sequence, and for private topics, the sequence is unique to each topic and user. It's important to note that some topics will send a "welcome message", which will have an id value of -1. Additionally, this sequence may be reset between connections, so be sure to update this value locally whenever you reconnect.

timestamp
required
number <double>

Timestamp in milliseconds
topic
required
string (TopicEnum)
Enum: "trade" "orderbook/level_3" "orderbook/level_2" "orderbook/level_2_with_users" "orderbook/level_2_delta" "ticker" "order_status" "balance" "user_trades" "deposit" "withdrawal"

Request samples

Content type
application/json
{
  • "method": "subscribe",
  • "topics": [
    • "balance"
    ],
  • "ticket": "97794B95-AFE7-454F-81B0-9109112548C2"
}

Response samples

Content type
application/json
{
  • "id": 8,
  • "topic": "balance",
  • "timestamp": 1672856833684,
  • "body": {
    • "user_id": "299E7131-CE8C-422F-A1CF-497BFA116F89",
    • "balances": [
      • {
        • "available_amount": 1,
        • "currency_code": "BTC",
        • "locked_amount": 0.5,
        • "conversions": [
          • {
            • "available_amount": 50003247,
            • "currency_code": "UXD",
            • "locked_amount": 0
            },
          • {
            • "available_amount": 10000649.4,
            • "currency_code": "BRL",
            • "locked_amount": 0
            },
          • {
            • "available_amount": 1,
            • "currency_code": "BTC",
            • "locked_amount": 0.5
            },
          • {
            • "available_amount": 20001.2988,
            • "currency_code": "ETH",
            • "locked_amount": 0
            },
          • {
            • "available_amount": 20001298.8,
            • "currency_code": "USD",
            • "locked_amount": 0
            },
          • {
            • "available_amount": 20001298.8,
            • "currency_code": "USDC",
            • "locked_amount": 0
            }
          ]
        },
      • {
        • "available_amount": 3,
        • "currency_code": "ETH",
        • "locked_amount": 1,
        • "conversions": [
          • {
            • "available_amount": 4119989.31998,
            • "currency_code": "UXD",
            • "locked_amount": 860.002145
            },
          • {
            • "available_amount": 823997.86,
            • "currency_code": "BRL",
            • "locked_amount": 172
            },
          • {
            • "available_amount": 46.03340022,
            • "currency_code": "BTC",
            • "locked_amount": 0.00960896
            },
          • {
            • "available_amount": 3,
            • "currency_code": "ETH",
            • "locked_amount": 1
            },
          • {
            • "available_amount": 4119989.31,
            • "currency_code": "USD",
            • "locked_amount": 860
            },
          • {
            • "available_amount": 4119989.31998,
            • "currency_code": "USDC",
            • "locked_amount": 860.002145
            }
          ]
        }
      ]
    }
}

user_trades Topic

When orders match, this topic notifies the users involved in the match process. Buyer and seller will get notified about what orders were executed.

Request Body schema: application/json
method
required
string (MethodEnum)
Enum: "subscribe" "unsubscribe" "ping"

Method to be executed
topics
required
Array of strings (TopicEnum)
Items Enum: "trade" "orderbook/level_3" "orderbook/level_2" "orderbook/level_2_with_users" "orderbook/level_2_delta" "ticker" "order_status" "balance" "user_trades" "deposit" "withdrawal"

Topics to subscribe to
ticket
required
string

Ticket created using the endpoint POST https://api.ripiotrade.co/v4/ticket

Responses

Response Schema: application/json
required
object (UserTrades)
id
required
number <double>

Each WebSocket message includes a sequential numeric id. Each topic has its own unique sequence, and for private topics, the sequence is unique to each topic and user. It's important to note that some topics will send a "welcome message", which will have an id value of -1. Additionally, this sequence may be reset between connections, so be sure to update this value locally whenever you reconnect.

timestamp
required
number <double>

Timestamp in milliseconds
topic
required
string (TopicEnum)
Enum: "trade" "orderbook/level_3" "orderbook/level_2" "orderbook/level_2_with_users" "orderbook/level_2_delta" "ticker" "order_status" "balance" "user_trades" "deposit" "withdrawal"

Request samples

Content type
application/json
{
  • "method": "subscribe",
  • "topics": [
    • "user_trades"
    ],
  • "ticket": "97794B95-AFE7-454F-81B0-9109112548C2"
}

Response samples

Content type
application/json
{
  • "id": 9,
  • "topic": "user_trades",
  • "timestamp": 1673271591764,
  • "body": {
    • "trade": {
      • "amount": 1,
      • "date": "2023-01-09T13:39:24.057Z",
      • "fee": 0,
      • "fee_currency": "BCH",
      • "id": "08799ECC-F6B1-498E-B89C-2A05E6A181B9",
      • "maker_order_id": "AF1C3AD2-D5A2-41CC-9A4C-646B600F9E01",
      • "pair_code": "BCH_BRL",
      • "price": 49,
      • "side": "buy",
      • "taker_or_maker": "taker",
      • "taker_order_id": "52B46D87-86A1-4978-B141-4E18E3E47514",
      • "timestamp": 1675780847920,
      • "total_value": 49,
      • "type": "limit"
      },
    • "user_id": "30B8CDBB-BDBD-4B60-A90F-860AB46B76F7"
    }
}

deposit Topic

This topic is responsible for notifing the user when a fiat / cryptocurrency deposit occurs.

Request Body schema: application/json
method
required
string (MethodEnum)
Enum: "subscribe" "unsubscribe" "ping"

Method to be executed
topics
required
Array of strings (TopicEnum)
Items Enum: "trade" "orderbook/level_3" "orderbook/level_2" "orderbook/level_2_with_users" "orderbook/level_2_delta" "ticker" "order_status" "balance" "user_trades" "deposit" "withdrawal"

Topics to subscribe to
ticket
required
string

Ticket created using the endpoint POST https://api.ripiotrade.co/v4/ticket

Responses

Response Schema: application/json
required
SendFiatCashInToSocketUseCaseParams (object) or SendCryptoCashInToSocketUseCaseParams (object) (SendCashInToSocketUseCaseParams)
id
required
number <double>

Each WebSocket message includes a sequential numeric id. Each topic has its own unique sequence, and for private topics, the sequence is unique to each topic and user. It's important to note that some topics will send a "welcome message", which will have an id value of -1. Additionally, this sequence may be reset between connections, so be sure to update this value locally whenever you reconnect.

timestamp
required
number <double>

Timestamp in milliseconds
topic
required
string (TopicEnum)
Enum: "trade" "orderbook/level_3" "orderbook/level_2" "orderbook/level_2_with_users" "orderbook/level_2_delta" "ticker" "order_status" "balance" "user_trades" "deposit" "withdrawal"

Request samples

Content type
application/json
{
  • "method": "subscribe",
  • "topics": [
    • "deposit"
    ],
  • "ticket": "97794B95-AFE7-454F-81B0-9109112548C2"
}

Response samples

Content type
application/json
{
  • "id": 10,
  • "topic": "deposit",
  • "timestamp": 1673271591764,
  • "body": {
    • "id": "08799ECC-F6B1-498E-B89C-2A05E6A181B9",
    • "amount": 1,
    • "hash": "0x79704c92b31061b8f51e26486d6454aff3e3c58aa0d51f0f803d6fd063be8100",
    • "currency_code": "ETH",
    • "is_internal": false,
    • "status": "confirmed",
    • "create_date": "2023-01-09T13:39:24.057Z",
    • "update_date": "2023-01-09T13:39:25.001Z",
    • "user_id": "5B6A43AE-8012-402D-966F-87CF64689535",
    • "confirmation_date": "2023-01-09T13:39:25.001Z",
    • "address": "3PQhyXH1EZs1bZ23ZafqQDyeViqxn5KdXN",
    • "network": "bitcoincash"
    }
}

withdrawal Topic

This topic is responsible for notifing the user when a fiat / cryptocurrency withdrawal occurs.

Request Body schema: application/json
method
required
string (MethodEnum)
Enum: "subscribe" "unsubscribe" "ping"

Method to be executed
topics
required
Array of strings (TopicEnum)
Items Enum: "trade" "orderbook/level_3" "orderbook/level_2" "orderbook/level_2_with_users" "orderbook/level_2_delta" "ticker" "order_status" "balance" "user_trades" "deposit" "withdrawal"

Topics to subscribe to
ticket
required
string

Ticket created using the endpoint POST https://api.ripiotrade.co/v4/ticket

Responses

Response Schema: application/json
required
SendFiatCashOutToSocketUseCaseParams (object) or SendCryptoCashOutToSocketUseCaseParams (object) (SendCashOutToSocketUseCaseParams)
id
required
number <double>

Each WebSocket message includes a sequential numeric id. Each topic has its own unique sequence, and for private topics, the sequence is unique to each topic and user. It's important to note that some topics will send a "welcome message", which will have an id value of -1. Additionally, this sequence may be reset between connections, so be sure to update this value locally whenever you reconnect.

timestamp
required
number <double>

Timestamp in milliseconds
topic
required
string (TopicEnum)
Enum: "trade" "orderbook/level_3" "orderbook/level_2" "orderbook/level_2_with_users" "orderbook/level_2_delta" "ticker" "order_status" "balance" "user_trades" "deposit" "withdrawal"

Request samples

Content type
application/json
{
  • "method": "subscribe",
  • "topics": [
    • "withdrawal"
    ],
  • "ticket": "97794B95-AFE7-454F-81B0-9109112548C2"
}

Response samples

Content type
application/json
{
  • "id": 11,
  • "topic": "withdrawal",
  • "timestamp": 1673271591764,
  • "body": {
    • "id": "2B222F22-5235-45FA-97FC-E9DBFA2575EE",
    • "amount": 100,
    • "currency_code": "ETH",
    • "status": "confirmed",
    • "miner_fee": null,
    • "fee": null,
    • "external_id": "08799ECC-F6B1-498E-B89C-2A05E6A181B9",
    • "create_date": "2023-01-09T13:39:24.057Z",
    • "destination_address": "mpe8FKtvDktBN1FGToFpYN2pdktySxD8wg",
    • "update_date": "2023-01-09T13:39:24.057Z",
    • "hash": "0x79704c92b31061b8f51e26486d6454aff3e3c58aa0d51f0f803d6fd063be8100",
    • "is_internal": false,
    • "network": "bitcoin",
    • "user_id": "5B6A43AE-8012-402D-966F-87CF64689535"
    }
}

WebSocket API

The WebSocket API allows you to perform trading operations (create, cancel, and update orders) via WebSocket connection. This is separate from the WebSocket Stream service which provides real-time market data.

General API Information

  • Base endpoint: wss://ws-api.ripio.com
  • Connections remain active as long as there is activity; idle connections are disconnected after 60 seconds of inactivity
  • The WebSocket server will automatically send ping frames to maintain connection health
  • If the WebSocket server does not receive a pong frame back from the connection within 60 seconds, the connection will be disconnected
  • When you receive a ping, you must send a pong with a copy of ping's payload as soon as possible
  • Unsolicited pong frames are allowed, but will not prevent disconnection
  • Authentication is done using API Token, Secret, and Timestamp (same as REST API)
  • All timestamps are in milliseconds in UTC
  • All field names and values are case-sensitive
  • APIs have a timeout of 10 seconds when processing a request

Authentication

The WebSocket API uses the same authentication mechanism as the REST API, including API Token, Secret, and Timestamp-based signature generation.

For complete authentication details, including signature generation, please refer to the Authorization section.

Key Points for WebSocket API:

  • Use the same API Token and Secret from your REST API credentials
  • Include apiToken, timestamp, and signature in the params object of each request
  • The signature is generated using: Timestamp + JSON Body (business parameters only)

Signature Generation for WebSocket API

Unlike the REST API, the WebSocket signature is simpler because there's no HTTP method or path:

Message to sign: Timestamp + JSON Body

Where:

  • Timestamp: The same timestamp sent in the params.timestamp field (in milliseconds)
  • JSON Body: ONLY the business parameters (pair, side, type, amount, price, etc.). DO NOT include apiToken, timestamp, or signature in the body to sign.

Important: Do NOT include + signs - just concatenate the values directly.

Signature Example

Request to send:

{
  "id": "req-001",
  "method": "order.create",
  "params": {
    "pair": "BTC_BRL",
    "side": "buy",
    "type": "limit",
    "amount": 0.001,
    "price": 100000,
    "external_id": "test-limit-1761758744255",
    "apiToken": "your-api-token",
    "timestamp": 1634567890000,
    "signature": "calculated-signature"
  }
}

Body to sign (only business params):

{
  "pair": "BTC_BRL",
  "side": "buy",
  "type": "limit",
  "amount": 0.001,
  "price": 100000,
  "external_id": "test-limit-1761758744255"
}

Message to sign:

1634567890000{"pair":"BTC_BRL","side":"buy","type":"limit","amount":0.001,"price":100000}

Then generate HMAC SHA256 signature:

const crypto = require('crypto');
const message = timestamp.toString() + JSON.stringify(bodyParams);
const signature = crypto.createHmac('sha256', secretKey).update(message).digest('base64');

Request Format

All WebSocket API requests must follow this format:

{
  "id": "unique-request-id",
  "method": "order.create",
  "params": {
    ...body parameters...,
    "apiToken": "your-api-token",
    "timestamp": 1634567890000,
    "signature": "calculated-signature"
  }
}

Response Format

Success Response

{
  "id": "unique-request-id",
  "status": 200,
  "result": {
    "id": "7155ED34-9EC4-4733-8B32-1E4319CB662F",
    "create_date": "2024-03-27T13:27:19.853Z",
    "executed_amount": 0,
    "external_id": "BEAB10B1-45B0-4999-9B2F-D2ED048D6C42",
    "pair": "BTC_BRL",
    "remaining_amount": 10,
    "remaining_value": 1000,
    "requested_amount": 10,
    "requested_value": 1000,
    "side": "buy",
    "status": "open"
  }
}

Error Response

{
  "id": "unique-request-id",
  "status": 400,
  "result": null,
  "error": {
    "error_code": 40011,
    "message": "Insufficient funds."
  }
}

Create Order via WebSocket Topic

Creates a new trading order via WebSocket API. Supports all order types available in the REST API including limit, market, stop-limit, trailing, ceiling, and iceberg orders.

Request Body schema: application/json
id
required
string

Unique request identifier for correlation
method
required
string
Value: "order.create"

WebSocket API method
required
Buy Limit (object) or Sell Limit (object) or Buy Market (object) or Sell Market (object) or StopLimitBuyOrderBody (object) or StopLimitSellOrderBody (object) or TrailingBuyOrderBody (object) or TrailingSellOrderBody (object) or CeilingBuyOrderBody (object) or CeilingSellOrderBody (object) or IcebergBuyOrderBody (object) or IcebergSellOrderBody (object)

Responses

Response Schema: application/json
id
required
string

Request identifier for correlation
status
required
integer

HTTP status code
required
object (UserOrderOutput)
Response Schema: application/json
id
required
string

Request identifier for correlation
status
required
integer

HTTP error status code
result
required
null

Always null for error responses
required
object

Request samples

Content type
application/json
Example
{
  • "id": "req-001",
  • "method": "order.create",
  • "params": {
    • "apiToken": "your-api-token",
    • "timestamp": 1634567890000,
    • "signature": "calculated-signature",
    • "pair": "BTC_BRL",
    • "side": "buy",
    • "type": "limit",
    • "amount": 0.001,
    • "price": 100000,
    • "external_id": "my-order-123",
    • "post_only": false,
    • "expiration": 1723073682,
    • "immediate_or_cancel": false,
    • "fill_or_kill": false
    }
}

Response samples

Content type
application/json
{
  • "id": "req-001",
  • "status": 200,
  • "result": {
    • "id": "7155ED34-9EC4-4733-8B32-1E4319CB662F",
    • "status": "open",
    • "create_date": "2024-03-27T13:27:19.853Z",
    • "external_id": "my-order-123",
    • "pair": "BTC_BRL",
    • "side": "buy",
    • "executed_amount": 0,
    • "remaining_amount": 0.001,
    • "remaining_value": 100,
    • "requested_amount": 0.001,
    • "requested_value": 100
    }
}

Cancel Order via WebSocket Topic

Cancels an active trading order via WebSocket API. You can cancel by order ID or external ID.

Request Body schema: application/json
id
required
string

Unique request identifier for correlation
method
required
string
Value: "order.cancel"

WebSocket API method
required
object

Responses

Response Schema: application/json
id
required
string

Request identifier for correlation
status
required
integer

HTTP status code
required
object

Canceled order details
Response Schema: application/json
id
required
string

Request identifier for correlation
status
required
integer

HTTP error status code
result
required
null

Always null for error responses
required
object

Request samples

Content type
application/json
Example
{
  • "id": "req-003",
  • "method": "order.cancel",
  • "params": {
    • "apiToken": "your-api-token",
    • "timestamp": 1634567890000,
    • "signature": "calculated-signature",
    • "id": "7155ED34-9EC4-4733-8B32-1E4319CB662F"
    }
}

Response samples

Content type
application/json
{
  • "id": "req-003",
  • "status": 200,
  • "result": {
    • "id": "7155ED34-9EC4-4733-8B32-1E4319CB662F",
    • "create_date": "2024-03-27T13:27:19.853Z",
    • "executed_amount": 0,
    • "remaining_amount": 0.001,
    • "remaining_value": 100,
    • "requested_amount": 0.001,
    • "status": "canceled",
    • "total_value": 100,
    • "type": "limit",
    • "price": 100000,
    • "update_date": "2024-03-27T13:30:45.123Z",
    • "pair": "BTC_BRL",
    • "external_id": "my-order-123"
    }
}

Update Order via WebSocket Topic

Updates the price and/or amount of an existing active order via WebSocket API. It is not possible to change a canceled or fully executed order.

Request Body schema: application/json
id
required
string

Unique request identifier for correlation
method
required
string
Value: "order.update"

WebSocket API method
required
object

Responses

Response Schema: application/json
id
required
string

Request identifier for correlation
status
required
integer

HTTP status code
result
required
null

Always null for update responses
Response Schema: application/json
id
required
string

Request identifier for correlation
status
required
integer

HTTP error status code
result
required
null

Always null for error responses
required
object

Request samples

Content type
application/json
Example
{
  • "id": "req-005",
  • "method": "order.update",
  • "params": {
    • "apiToken": "your-api-token",
    • "timestamp": 1634567890000,
    • "signature": "calculated-signature",
    • "id": "7155ED34-9EC4-4733-8B32-1E4319CB662F",
    • "price": "105000",
    • "amount": "0.002"
    }
}

Response samples

Content type
application/json
{
  • "id": "req-005",
  • "status": 200,
  • "result": null
}