Trading
Buy and sell crypto for a user — request a price quote, then place an order against it.
Buy and sell crypto on a user's behalf. Trading runs in two steps: request a quote for a pair and side, then place an order that references that quote. Quotes are short-lived, so place the order before the quote expires.
Authentication: every endpoint on this page requires the Authorization header with the user token (Bearer).
Authorization: Bearer YOUR_USER_TOKENAll requests accept an optional x-trace-id header for request tracking; if omitted, one is generated. Paths use the user's wallet_id.
Quote and order responses pass straight through from the upstream pricing provider that fills the conversion, so the exact fields and values may vary.
Request Quote
Request a price quote to buy or sell a currency pair. Supply either a quantity (in the base currency) or an amount to price the trade. The returned quote_id is what you pass to Place Order; the quote expires shortly after it's issued.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| pair | string | Yes | Pair to trade in basequote format (e.g. btcusd, dogeusd). |
| side | string | Yes | Trade side. One of buy, sell. |
| quantity | number | No | Quantity of the base currency to trade. |
| amount | number | No | Amount to trade. |
{
"pair": "btcusd",
"side": "buy",
"quantity": 0.5
}Success Response (201 Created):
{
"success": true,
"data": {
"quote_id": "e609df31-3af3-11f0-97c3",
"pair": "btcusd",
"side": "buy",
"amount": 20000,
"quantity": 0.5,
"buy_price": 40000,
"created_at": "2026-01-15T10:30:00.000Z",
"expired_at": "2026-01-15T10:35:00.000Z"
},
"meta": {
"timestamp": "2026-01-15T10:30:00.000Z",
"version": "v1",
"trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
}
}The fields inside data come from the upstream pricing provider and may vary by pair and side.
curl -X POST "https://api.sandbox.sovera.io/sovx/v1/users/{{walletID}}/trading/quotes" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_USER_TOKEN" \
-d '{
"pair": "btcusd",
"side": "buy",
"quantity": 0.5
}'Errors: 400 missing/invalid parameters · 401 invalid key · 404 wallet not found · 500 server error.
Place Order
Execute a trade against a quote. Pass the quote_id from Request Quote; the server derives the pair and side from the quote, so you don't repeat them. Optionally override quantity or amount. The order settles immediately and returns the fill details.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| quote_id | string | Yes | Quote id from the quote request. |
| quantity | number | No | Quantity to trade. Defaults to the quote's quantity. |
| amount | number | No | Amount to trade. Defaults to the quote's amount. |
{
"quote_id": "e609df31-3af3-11f0-97c3",
"quantity": 0.5
}Success Response (201 Created):
{
"success": true,
"data": {
"id": "ord_8f3a9d2c7e4a",
"action": "buy",
"type": "market",
"pair": "btcusd",
"quantity": 0.5,
"price": 40000,
"amount": 20000,
"net_proceeds": 19900,
"fees": 100,
"status": "COMPLETED",
"transaction_id": "tx_1a4d5f0e3c2b",
"client_order_id": "9182",
"quote_id": "e609df31-3af3-11f0-97c3"
},
"meta": {
"timestamp": "2026-01-15T10:30:05.000Z",
"version": "v1",
"trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
}
}The fields inside data come from the upstream pricing provider that fills the order and may vary.
curl -X POST "https://api.sandbox.sovera.io/sovx/v1/users/{{walletID}}/trading/orders" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_USER_TOKEN" \
-d '{
"quote_id": "e609df31-3af3-11f0-97c3",
"quantity": 0.5
}'Errors: 400 missing/invalid parameters · 401 invalid key · 404 wallet or quote not found · 500 server error.