Backpack Exchange API (1.0)

Welcome to the Backpack Exchange API. This API is for programmatic trade execution. All of the endpoints require requests to be signed with an ED25519 keypair for authentication.

The API is hosted at https://api.backpack.exchange/ and the WS API is hosted at wss://ws.backpack.exchange/.

Signed requests are required for any API calls that mutate state. Additionally, some read only requests can be performed by signing or via session authentication.

Signed requests require the following additional headers:

• X-Timestamp - Unix time in milliseconds that the request was sent.
• X-Window - Time window in milliseconds that the request is valid for, default is 5000 and maximum is 60000.
• X-API-Key - Base64 encoded verifying key of the ED25519 keypair.
• X-Signature - Base64 encoded signature generated according to the instructions below.

To generate a signature perform the following:

1. The key/values of the request body or query parameters should be ordered alphabetically and then turned into query string format.

2. Append the header values for the timestamp and receive window to the above generated string in the format &timestamp=<timestamp>&window=<window>. If no X-Window header is passed the default value of 5000 still needs to be added to the signing string.

Each request also has an instruction type, valid instructions are:

accountQuery
balanceQuery
borrowHistoryQueryAll
depositAddressQuery
depositQueryAll
fillHistoryQueryAll
interestHistoryQueryAll
orderCancel
orderCancelAll
orderExecute
orderHistoryQueryAll
orderQuery
orderQueryAll
withdraw
withdrawalQueryAll

The correct instruction type should be prefixed to the signing string. The instruction types for each request are documented alongside the request.

For example, an API request to cancel an order with the following body:

{
    "orderId": 28
    "symbol": "BTC_USDT",
}

Would require the following to be signed:

instruction=orderCancel&orderId=28&symbol=BTC_USDT&timestamp=1614550000000&window=5000

If the API endpoint requires query parameters instead of a request body, the same procedure should be used on the query parameters. If the API endpoint does not have a request body or query parameters, only the timestamp and receive window need to be signed.

This message should be signed using the private key of the ED25519 keypair that corresponds to the public key in the X-API-Key header. The signature should then be base64 encoded and submitted in the X-Signature header.

• Convert all error responses to JSON and add a error code.

• Add executedQuantity and executedQuoteQuantity to order history endpoint.

• Add single market order update stream account.orderUpdate.<symbol>.

• Add optional from and to timestamp to get withdrawals endpoint.

• Add optional from and to timestamp to get deposits endpoint.

• Add optional orderId filter to order history endpoint.
• Add optional from and to timestamp to order fills endpoint.

• Return the withdrawal in request withdrawal response.

• An additional field t was added to the private order update stream. It is the trade_id of the fill that generated the order update.
• Added a maximum value for the X-Window header of 60000.

Breaking

• A new websocket API is available at wss://ws.backpack.exchange. Please see the documentation. The previous API remains on the same endpoint and will be deprecated after a migration period. The new API changes the following:
  • Subscription endpoint is now wss://ws.backpack.exchange instead of wss://ws.backpack.exchange/stream.
  • Can subscribe and unsubscribe to/from multiple streams by passing more than one in the params field.
  • Signature should now be sent in a separate signature field.
  • Signature instruction changed from accountQuery to subscribe.
  • Event and engine timestamps are now in microseconds instead of milliseconds.
  • Add engine timestamp to bookTicker, depth, and order streams.
  • Add quote asset volume to ticker stream.
  • Add sequential trade id to trade stream.
  • Rename the event type in the depth stream from depthEvent to depth.
  • Change the format of streams from <symbol>@<type> to <type>.<symbol> or kline.<interval>.<symbol> for K-lines.
  • Flatten the K-Line in the K-line stream so its not nested.

Breaking

• Replaced identifier field on deposits with transaction_hash and provider_id. This aims to provide clearer representation of the field, particularly for fiat deposits.
• Removed duplicate pending values from the WithdrawalStatus and DepositStatus spec enum.

Assets and collateral data.

Public market data.

Account position summary.

Public trade data.

Account settings.

Capital management.

Historical account data.

Order management.

To use the websocket API, connect to wss://ws.backpack.exchange.

To subscribe to a stream with the name stream send a text frame over the websocket connection with the following JSON payload:

{
  "method": "SUBSCRIBE",
  "params": ["stream"]
}

Similarly, to unsubscribe from a stream with the name stream:

{
  "method": "UNSUBSCRIBE",
  "params": ["stream"]
}

You can subscribe or unsubscribe from multiple streams if you include more than one in the params field.

All data from streams is wrapped in a JSON object of the following form:

{
  "stream": "<stream>",
  "data": "<payload>"
}

The following command can be used to test subscribing to a stream:

(sleep 1; \
echo '{"method":"SUBSCRIBE","params":["depth.SOL_USDC"]}';\
cat) |\
wscat -c wss://ws.backpack.exchange

The payloads for each stream time are outlined below.

Timestamps are in microseconds (except for the K-line start and end times). The event timestamp is the time the event was emitted from the websocket server, and the engine timestamp is the time the event was generated by the matching engine.

If a message aggregates more than one event (for example, a depth message), the engine timestamp will be the timestamp of the last matching engine event.

To keep the connection alive, a Ping frame will be sent from the server every 60s, and a Pong is expected to be received from the client. If a Pong is not received within 120s, a Close frame will be sent and the connection will be closed.

If the server is shutting down, a Close frame will be sent and then a grace period of 30s will be given before the connection is closed. The client should reconnect after receiving the Close frame. The client will be reconnected to a server that is not shutting down.

Subscribing to a private stream requires a valid signature generated from an ED25519 keypair. For stream subscriptions, the signature should be of the form:

instruction=subscribe&timestamp=1614550000000&window=5000

Where the timestamp and window are in milliseconds.

Private streams are prefixed with account. and require signature data to be submitted in the subscribe parameters. The verifying key and signature should be base64 encoded.

{
  "method": "SUBSCRIBE",
  "params": ["stream"],
  "signature": ["<verifying key>", "<signature>", "<timestamp>", "<window>"]
}

On any mutation to an order the order will be pushed to the order update stream. The event type of the order update will be one of the following:

• orderAccepted
• orderCancelled
• orderExpired
• orderFill

Stream name format for all markets: account.orderUpdate Stream name format for single market: account.orderUpdate.<symbol>

{
  "e": "orderAccepted",   // Event type
  "E": 1694687692980000,  // Event time in microseconds
  "s": "SOL_USD",         // Symbol
  "c": 123,               // Client order ID
  "S": "Bid",             // Side
  "o": "LIMIT",           // Order type
  "f": "GTC",             // Time in force
  "q": "32123",           // Quantity
  "Q": "32123",           // Quantity in quote
  "p": "20",              // Price
  "P": "21",              // Trigger price
  "X": "Filled",          // Order state
  "i": "1111343026172067" // Order ID
  "t": 567,               // Trade ID
  "l": "1.23",            // Fill quantity
  "z": "321",             // Executed quantity
  "Z": "123",             // Executed quantity in quote
  "L": "20",              // Fill price
  "m": true,              // Whether the order was maker
  "n": "23",              // Fee
  "N": "USD",             // Fee symbol
  "V": "RejectTaker",     // Self trade prevention
  "T": 1694687692989999   // Engine timestamp in microseconds
}

Some fields are conditional on the order settings or event type:

• c - Only present if the order has a client order ID.
• q - Only present if the order has a quantity set.
• Q - Only present if the order is reverse market order.
• p - Only present if the order is a limit order.
• P - Only present if the order is a trigger order.
• t - Only present if the event is a orderFill event.
• l - Only present if the event is a orderFill event.
• L - Only present if the event is a orderFill event.
• m - Only present if the event is a orderFill event.
• n - Only present if the event is a orderFill event.
• N - Only present if the event is a orderFill event.