Skip to main content
API docs by Redocly

Smart Order Routing (Preview)

Download OpenAPI specification:Download

Welcome to the preview documentation for the Paxos Smart Order Routing (SOR) APIs. The SOR APIs are in the early preview stage and as a result will be updated regularly as new functionality becomes ready.

This document contains proposed additions to the main Paxos API 2.0 documentation. The additions here are subject to breaking changes until merged into the main documentation.

Learn more about the SOR Preview

Market Data

Retrieve the order book for one or more markets.

Get Order Book

For each market the order book contains the full list of bids and asks at individual price levels with resting quantities per level.

query Parameters
market
string <market>
Enum: "BTCUSD" "ETHUSD" "BCHUSD" "LTCUSD" "LINKUSD" "MATICUSD" "AAVEUSD" "UNIUSD"

Filter by market name.

level
string
Enum: "LEVEL_1" "LEVEL_2"

Filter by order book level.

Responses

Response samples

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

Trading

Smart Order Routing (SOR) is an automated process that evaluates and routes orders across multiple exchanges and liquidity venues to get the best price execution for each order, based on the liquidity available at that time.

The SOR APIs allow you to submit orders using standard order types and then track progress as the orders are routed and executed across multiple venues.

Error Handling

Sync Error Messages

Error messages, such as request validation or server processing errors, are returned in the HTTP response for the majority of endpoints. Following the RFC 7807 standard, the JSON error response includes a title, a status and error details.

Example error message in the HTTP response:

{
    "type": "about:blank",
    "title": "Bad Request",
    "status": 400,
    "detail": "invalid side, available values: ['BUY', 'SELL']"
}

Async Error Messages

Due to the async processing of orders, some order error statuses are provided via the Get Orders and List Orders endpoints in the error_code and error_message fields.

Example error message in the response from Get / List Orders:

{
  "orders": [
        {
            "id": "JE53WYesJHeeSqrT36VkA",
            "error_code": 3000,
            "error_message": "Insufficient Funds",
            "profile_id": "ac1f1128-5521-4806-b4c5-4f992b766f08",
            "status": "REJECTED",
            "ref_id": "fd61ed2b-e1a0-4dd8-a7c9-7873b2911577",
            "market": "BTCUSD",
            …
        }
    ]
}

Async Errors

Orders which fail asynchronously will have a status of REJECTED.
Error CategoryError ScenarioError CodeError Message
SOR Internal ErrorInternal Error1000The order was canceled due to an internal error.
Order Argument ErrorInvalid Argument2000An unsupported argument was provided in the order: {f}:{v}.
Order Argument Errorbase_amount outside allowed range2001The base_amount submitted was outside the supported range.
Order Argument Errorquote_amount outside allowed range2002The quote_amount submitted was outside the supported range.
Account Level ErrorInsufficient Funds3000Mandatory field missing: {f}.
Account Level ErrorPermission Denied3001Your account does not have permission to trade the asset: {asset}.

Create Order

Submit orders to the Smart Order Router.

Supported Order Types

Order Type Status
Market Supported        
Limit * Coming Soon
Algorithmic Order Types * Coming Soon
For market orders, create an order for buying or selling an asset:
  • To buy, set side = BUY and set quote_amount to the dollar amount you want to spend.
  • To sell, set side = SELL and set base_amount to the crypto amount you want to sell.

Acknowledgement Response

This endpoint will respond with a 200 and an order ID. This response does not confirm the order has been validated, accepted or submitted to a venue. To check the status of your order you will use the Get Orders endpoint.

Idempotency

Orders which fail idempotency checks will not be returned from Get Orders or List Orders. Notifications regarding idempotency failures will be added in a future update to the SOR APIs.

Authorizations:
OAuth2
Request Body schema: application/json
profile_id
required
string <uuid>

The Profile ID the order will be associated with.

identity_id
string <uuid>

The end user that requests the trade. This field must be used in conjunction with account_id, otherwise the order is rejected. Depending on your integration type, identity_id and account_id may be required.

account_id
string <uuid>

The account under which this order is placed. The provided identity must be allowed to trade on behalf of this account. This field must be used in conjunction with identity_id, otherwise the order is rejected. Depending on your integration type, account_id and identity_id may be required.

ref_id
string

The idempotence ID for order creation. Can be reused if the order has been closed for more than 24 hours. Up to 100 characters are supported.

market
required
string <market>
Enum: "BTCUSD" "ETHUSD" "BCHUSD" "LTCUSD" "LINKUSD" "MATICUSD" "AAVEUSD" "UNIUSD"

The trading market.

side
required
string <orderside>
Enum: "BUY" "SELL"

Whether this order is for a buy or a sell.

type
string
Value: "MARKET"

Order type.

quote_amount
string <decimal>

The quote currency amount of purchase for a market buy order.

base_amount
string <decimal>

The base currency amount for any limit order or the exact amount to sell for a market sell order.

object <map>

Metadata to store on the quote and created order. Up to 6 key/value pairs may be stored, with each key and value at most 100 characters.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "12f708db-f000-4ec0-9558-efc63cb9d948",
  • "identity_id": "873989a6-8270-4e1a-89f7-d1b3f28fff3f",
  • "account_id": "2d6e0dc5-a816-455d-8cd8-9eb7517799c5",
  • "ref_id": "bcf0c3a12d554e9996b6ec54cca7a41e",
  • "market": "BTCUSD",
  • "side": "BUY",
  • "type": "MARKET",
  • "quote_amount": "1.00",
  • "base_amount": "0.0",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "profile_id": "12f708db-f000-4ec0-9558-efc63cb9d948",
  • "identity_id": "873989a6-8270-4e1a-89f7-d1b3f28fff3f",
  • "account_id": "2d6e0dc5-a816-455d-8cd8-9eb7517799c5",
  • "ref_id": "bcf0c3a12d554e9996b6ec54cca7a41e",
  • "market": "BTCUSD",
  • "side": "BUY",
  • "type": "MARKET",
  • "quote_amount": "1.00",
  • "base_amount": "0.0",
  • "id": "rtZaCnAz1FvArCTVbzFL9",
  • "metadata": {
    }
}

Get Orders

Get the details of any order(s) created within the last 90 days.

Newly created orders may take up to 250ms before they will be returned from this endpoint.

Authorizations:
OAuth2
query Parameters
ids
Array of strings

List of order identifiers assigned by Paxos.

ref_ids
Array of strings

The idempotence IDs provided during order creation.

Responses

Response samples

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

List Executions

Retrieves full details of underlying executions with optional filters. This endpoint returns a maximum of 1000 items per page.

This endpoint will only return executions from orders created via the SOR API.

Authorizations:
OAuth2
query Parameters
profile_id
string <uuid>

Filter executions by the Profile ID associated with the orders.

identity_id
string <uuid>

Filter executions by the end user Identity associated with the orders.

account_id
string <uuid>

Filter executions by the Account ID associated with the orders.

order_id
string

Filter executions to those associated with a single order ID.

ref_id
string

Filter executions to those associated with a single idempotence ID.

created_at.begin
string <rfc3339>

Only return records after this timestamp, inclusive.
RFC3339 format, like 2006-01-02T15:04:05Z.

created_at.end
string <rfc3339>

Only return records before this timestamp, inclusive.
RFC3339 format, like 2006-01-02T15:04:05Z.

page_cursor
string

Cursor token for fetching the next page. If using this then do not use the limit parameter.

limit
integer <int32>

Number of results to return. The Maximum value allowed is 1000.

Responses

Response samples

Content type
application/json
{
  • "executions": [
    ],
  • "next_page_cursor": "39f1766d35a14523"
}

List Orders

Retrieve orders using custom filtering such as status, timeframe, market and side. This endpoint provides access to historical orders for the last 90 days (including last 24 hours).

Newly created orders may take up to 250ms before they will be returned from this endpoint.

Authorizations:
OAuth2
query Parameters
profile_id
string <uuid>

Filter orders by the Profile ID.

identity_id
string <uuid>

Filter orders by the end user Identity.

account_id
string <uuid>

Filter orders by the Account ID.

markets
Array of strings <market>
Items Enum: "BTCUSD" "ETHUSD" "BCHUSD" "LTCUSD" "LINKUSD" "MATICUSD" "AAVEUSD" "UNIUSD"

Filter by the trading pair.

sides
Array of strings <orderside>
Items Enum: "BUY" "SELL"

Filter by the side of the order.

statuses
Array of strings

List of order statuses.

created_at.begin
string <rfc3339>

Only return records created after this timestamp, inclusive (max 90 days) [default: last 24h].
RFC3339 format, like 2006-01-02T15:04:05Z.

created_at.end
string <rfc3339>

Only return records created before this timestamp, inclusive (max 90 days) [default: last 24h].
RFC3339 format, like 2006-01-02T15:04:05Z.

modified_at.begin
string <rfc3339>

Only return records after this timestamp, inclusive.
RFC3339 format, like 2006-01-02T15:04:05Z.

modified_at.end
string <rfc3339>

Only return records before this timestamp, inclusive.
RFC3339 format, like 2006-01-02T15:04:05Z.

page_cursor
string

Cursor token for fetching the next page.

limit
integer <int32>

Number of results to return. The Maximum value allowed is 1000.

Responses

Response samples

Content type
application/json
{
  • "orders": [
    ],
  • "next_page_cursor": "39f1766d35a14523"
}