Trading Workflow

Trading on Sovera is quote-driven: you lock a price first, then place an order against it. This guide follows that sequence end to end, so the price you see is the price you trade at.

Overview

A trade always starts with a quote. The quote fixes the price and direction for a short window; the order then executes against that exact quote and settles synchronously. After it settles, you confirm the result by reading the wallet balance.

1. Get a price quote
2. Place an order against the quote
3. Verify balance updates

Estimated time: 2-5 minutes Prerequisites:

• A valid user token (Authorization: Bearer)
• An active user with a wallet
• Enough balance to cover the trade and fees

Step-by-Step Guide

Step 1: Get Price Quote

Lock a price before you commit. A quote pins the pair, side, and amount to a single price for a few minutes, so the order in the next step executes at a known rate rather than whatever the market does between calls. The response returns a quote_id — that's the handle you pass to the order.

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/users/wallet_abc123/trading/quotes" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_USER_TOKEN" \
  -d '{
    "pair": "btcusd",
    "side": "buy",
    "quantity": 0.01
  }'

Request Body:

• pair: Trading pair in basequote format (e.g., btcusd, ethusd)
• side: buy or sell
• quantity: Quantity of the base currency to trade (use amount to specify the quote-currency amount instead)

Response:

{
  "success": true,
  "data": {
    "quote_id": "e609df31-3af3-11f0-97c3",
    "pair": "btcusd",
    "side": "buy",
    "amount": 450,
    "quantity": 0.01,
    "buy_price": 45000,
    "created_at": "2026-03-12T00:00:00.000Z",
    "expired_at": "2026-03-12T00:05:00.000Z"
  },
  "meta": {
    "timestamp": "2026-03-12T00:00:00.000Z",
    "version": "v1",
    "trace_id": "abc-123"
  }
}

See Get Quote for full request details.

Step 2: Create Order

Place the order against the quote you just got. Reference the quote_id from Step 1 and the platform executes at that locked price and side — the pair and side are already carried by the quote, so there's nothing else to restate. The order settles immediately and returns the fill with status: "COMPLETED". The order is scoped to the wallet in the path, so funds settle straight into it.

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/users/wallet_abc123/trading/orders" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_USER_TOKEN" \
  -d '{
    "quote_id": "e609df31-3af3-11f0-97c3",
    "quantity": 0.01
  }'

Request Body:

• quote_id: The quote_id returned in Step 1 (required)
• quantity: Quantity to trade (optional; defaults to the quote's quantity). Use amount instead to trade by quote-currency amount.
• amount: Amount to trade (optional; defaults to the quote's amount). Use it instead of quantity to trade by quote-currency amount.

Response:

{
  "success": true,
  "data": {
    "id": "ord_8f3a9d2c7e4a",
    "action": "buy",
    "type": "market",
    "pair": "btcusd",
    "quantity": 0.01,
    "price": 45000,
    "amount": 450,
    "net_proceeds": 445.5,
    "fees": 4.5,
    "status": "COMPLETED",
    "transaction_id": "tx_1a4d5f0e3c2b",
    "client_order_id": "9182",
    "quote_id": "e609df31-3af3-11f0-97c3"
  },
  "meta": {
    "timestamp": "2026-03-12T00:00:00.000Z",
    "version": "v1",
    "trace_id": "def-456"
  }
}

See Create Order for full request details.

Step 3: Verify Balance Update

Confirm the outcome by reading the wallet balance. After a buy you'll see more of the bought asset and less of what you spent; a sell is the reverse. This is the source of truth that the trade actually moved funds.

curl -X GET "https://api.sandbox.sovera.io/sovx/v1/wallets/wallet_abc123/balance" \
  -H "Authorization: Bearer YOUR_USER_TOKEN"

Response:

{
  "success": true,
  "data": {
    "wallet_id": "wallet_abc123",
    "user_id": "f4057807-52cf-4083-9ecb-283ef354fb2b",
    "balances": [
      {
        "currency": "btc",
        "balance": "0.01000000",
        "available": "0.01000000"
      },
      {
        "currency": "usd",
        "balance": "9545.50000000",
        "available": "9545.50000000"
      }
    ],
    "total_currencies": 2
  },
  "meta": {
    "timestamp": "2026-03-12T00:01:00.000Z",
    "version": "v1",
    "trace_id": "jkl-012"
  }
}

See Account Balances for full request details.

Trading Pairs

Common pairs:

• btcusd — Bitcoin / US Dollar
• ethusd — Ethereum / US Dollar
• ltcusd — Litecoin / US Dollar
• btceur — Bitcoin / Euro
• etheur — Ethereum / Euro

Get all available pairs:

curl -X GET "https://api.sandbox.sovera.io/sovx/v1/currency-pairs" \
  -H "Authorization: Bearer YOUR_USER_TOKEN"

Order Types

Market Order

Executes immediately at current market price.

{
  "order_type": "market",
  "pair": "btcusd",
  "quantity": "0.01"
}

Limit Order (if supported)

Executes only at specified price or better.

{
  "order_type": "limit",
  "pair": "btcusd",
  "quantity": "0.01",
  "limit_price": "45000.00"
}

Fees

Trading fees deduct automatically from the transaction:

• Maker Fee: 0.1% (when adding liquidity)
• Taker Fee: 0.2% (when removing liquidity)
• Minimum Fee: $0.01 USD equivalent

Troubleshooting

Insufficient Balance

Error: INSUFFICIENT_BALANCE Solution: Deposit funds or reduce trade quantity.

Quote Expired

Error: QUOTE_EXPIRED Solution: Request a new quote before placing the order.

Invalid Trading Pair

Error: INVALID_PAIR Solution: Check available pairs with /currency-pairs.

Order Didn't Settle

Issue: Order response didn't come back COMPLETED Solution:

• Confirm the quote hadn't expired before you placed the order
• Check the wallet balance to see whether funds actually moved
• Contact support if the fill never lands

Best Practices

1. Get fresh quotes — Quotes expire after 5 minutes
2. Check balance first — Confirm sufficient funds before trading
3. Confirm the fill — Place Order returns COMPLETED synchronously in the order response
4. Handle errors gracefully — Add retry logic with exponential backoff
5. Verify execution — Check the final executed price and fees

Next Steps

• Check Transaction History — View all trades
• Withdraw Funds — Cash out profits
• Wallet Transfers — Move funds between wallets

Support

Need help? Email [email protected]