Skip to main content

Quickstart

Integrate market orders with SOR in 5 minutes or less.

To submit buy or sell orders using the Smart Order Routing (SOR) service, we recommend the following workflow:

  • Authenticate in the Sandbox environment.
  • Fund your Sandbox Account if necessary.
  • Create an order for the amount you want to buy or sell using Create Order.
  • Use Get Orders to retrieve the order status, including order completion time and average execution price.

1. Authenticate​

Add the trading:read_client_order and trading:write_client_order scopes to your Sandbox Account under the API Management setting and then authenticate in Sandbox using the scopes. Also include funding:read_profile for funding Profiles.

curl --location 'https://oauth.sandbox.paxos.com/oauth2/token' \
--form grant_type=client_credentials \
--form client_id={paxos_client_id} \
--form client_secret={paxos_secret} \
--form scope='trading:read_client_order trading:write_client_order funding:read_profile'

Confirm the response includes requisite scopes and save the access_token to use in the request authorization header throughout this guide.

{
  "access_token": "{access_token}",
  "expires_in": 3599, // Seconds (59 Minutes and 59 Seconds)
  "scope": "trading:read_client_order trading:write_client_order funding:read_profile",
  "token_type": "bearer"
}

2. Sandbox Funding​

Next, use Create Sandbox Deposit to fund your Sandbox Account if not already done so.

curl --location 'https://api.sandbox.paxos.com/v2/sandbox/profiles/{profile_id}/deposit' \
--header 'Authorization: Bearer {access_token}' \
--data '{
  "asset": "USD",
  "amount": "1000"
}'

Contact your Entity Manager or Support if you run into any issues or don't have access to a Sandbox Account.

3. Create Market Order​

Once you have the market data, create a trade using the Create Order endpoint by passing in body parameters.

Body ParameterPossible ValuesDescription
profile_idRetrieve UUID from List Profiles.The Profile ID the order will be associated with.
marketETHUSD BTCUSD BCHUSD LTCUSD LINKUSD MATICUSD* AAVEUSD UNIUSDAvailable markets.
sideBUY SELLTrade side.
quote_amountstring^[0-9]*\.?[0-9]+$The amount in USD to buy.
ref_idstringOptional. User provided string.

* Effective September 17, 2024, users can no longer buy MATIC. Users should exit their MATIC positions or transfer MATIC off-platform. As of October 3, 2024, users can only transfer MATIC off-platform. Contact support@paxos.com with questions or issues during the migration period.

Include the following body parameters in your request to buy $1,000USD of BTC:

curl --location 'https://api.sandbox.paxos.com/v2/trading/orders' \
--header 'Authorization: Bearer {access_token}' \
-data '{
"profile_id": "{profile_id}",
    "ref_id": "optional_idempotence_id",
    "market": "BTCUSD",
    "side": "BUY",
    "type": "MARKET",
    "quote_amount": "1000"
}'

Upon successful request, the acknowledgment response confirms your request has been received.

info

This acknowledgment response does not confirm the order has been validated, accepted or submitted to a venue. Use Get Orders to monitor the order status.

{
    "profile_id": "{profile_id}",
    "ref_id": "optional_idempotence_id", // Use for order lookup
    "market": "BTCUSD",
    "side": "BUY",
    "type": "MARKET",
    "quote_amount": "1000",
    "id": "{order_id}"} // Use for order lookup

4. Monitor Order Status​

Retrieve the status for a single order by passing either your custom ID or the system-generated ID as a query parameter using Get Orders.

Query ParameterPossible ValuesDescription
ref_idsstringOptional. Use only if a value was provided during order creation. Do not use with ids.
idsSystem provided UUID of the order.Retrieve from the order-creation acknowledgement response. Do not use with ref_ids.
tip

Most market orders complete near instantaneous (within a few milliseconds); however, it is possible that a submitted order may not be included in the Get Orders response. Querying the service a second time usually rectifies the situation.

To retrieve the status of the our BTC buy order, use a value from the previous ref_id or id query parameter. Attempting to use both parameters results in an error.

curl --location "https://api.sandbox.paxos.com/v2/trading/orders?ref_ids=optional_idempotence_id" \
--header "Authorization: Bearer {access_token}"

To response is similar to the acknowledgement response from the previous step, except it includes additional parameters, including status and additional order information. Because we executed a market buy order, execution occurred immediately.

{
    "orders": [
        {
            "id": "{order_id}",
            "profile_id": "{profile_id}",
            "status": "FILLED",
            "ref_id": "optional_idempotence_id",
            "market": "BTCUSD",
            "side": "BUY",
            "type": "MARKET",
            "time_in_force": "IMMEDIATE_OR_CANCEL",
            "quote_amount": "1000",
            "created_at": "YYYY-MM-DDT00:00:00Z",
            "modified_at": "YYYY-MM-DDT00:00:00Z",
            "filled_base_amount": "0.02664393",
            "filled_quote_amount": "999.99998076",
            "unfilled_base_amount": "0",
            "unfilled_quote_amount": "0",
            "volume_weighted_average_price": "37532"
        }
    ]
}

5. View Order Executions​

Retrieve the full execution details for one or more orders. Use either order_id or ref_id to filter the results to a single order.

Find execution details using the ref_id set during order creation.

curl --location 'https://api.sandbox.paxos.com/v2/trading/executions?ref_id=optional_idempotence_id' \
--header 'Authorization: Bearer {access_token}'

The response includes the execution_id, which can be used for lookup, and commission details.

{
    "executions": [
        {
            "profile_id": "{profile_id}",
            "execution_id": "{execution_id}", // Use for execution lookup
            "created_at": "YYYY-MM-DDT00:00:00Z",
            "order_id": "{order_id}", // id from the order creation response
            "ref_id": "optional_idempotence_id", // ref_id used at order creation
            "market": "BTCUSD",
            "type": "MARKET",
            "side": "BUY",
            "filled_base_amount": "0.02664393",
            "filled_quote_amount": "999.99998076",
            "price": "37532",
            "commission": "0",
            "commission_asset": "USD"
        }
    ]
}

Next Steps​