> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dubupay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Crypto trading with the Dubu Pay API

> Learn how to place and manage orders, read market data, check per-asset balances, and use trading to convert USDT earnings or speculate on fiat rates.

The Dubu Pay trading API gives you access to a live crypto/fiat order book where you can place, cancel, and monitor orders on NGN-paired markets. Trading is particularly useful when you want to convert accumulated USDT earnings back to NGN, take a position on exchange rate movements, or execute programmatic hedging strategies. All trading activity is scoped to your merchant account.

## Supported trading pairs

Dubu Pay currently offers three trading pairs:

| Pair       | Base asset | Quote asset | Description                                |
| ---------- | ---------- | ----------- | ------------------------------------------ |
| `USDT-NGN` | USDT       | NGN         | Trade Tether against the Nigerian Naira    |
| `USDC-NGN` | USDC       | NGN         | Trade USD Coin against the Nigerian Naira  |
| `USD-NGN`  | USD        | NGN         | Trade US Dollar against the Nigerian Naira |

To list all currently available pairs and their metadata programmatically:

```bash theme={null}
curl https://api.dubupay.com/api/v1/trading/market/pairs \
  -H "X-Api-Key: dubu_sk_live_..."
```

## Balances

Before placing an order, check your per-asset balance. The balances endpoint returns how much of each currency you hold in the trading account.

```bash theme={null}
curl https://api.dubupay.com/api/v1/trading/balances \
  -H "X-Api-Key: dubu_sk_live_..."
```

<Note>
  Your trading balance is separate from your payments merchant balance. To move USDT from the payments system into trading, call `POST /payments/merchant/balance/transfer` first. See [Payments, deposits, and withdrawals](/concepts/payments) for details.
</Note>

## Order types

Dubu Pay supports two order types:

| Type     | Description                                                                                    |
| -------- | ---------------------------------------------------------------------------------------------- |
| `limit`  | Execute at a specific price or better. Your order sits on the book until matched or cancelled. |
| `market` | Execute immediately at the best available price. No price guarantee.                           |

For limit orders, `price` is required. For market orders, omit `price`.

## Placing an order

Call `POST /trading/orders` with your chosen symbol, side, type, and quantity. All quantities are strings to avoid floating-point precision issues.

<CodeGroup>
  ```bash Limit order theme={null}
  curl -X POST https://api.dubupay.com/api/v1/trading/orders \
    -H "X-Api-Key: dubu_sk_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "symbol": "USDT-NGN",
      "side": "sell",
      "type": "limit",
      "quantity": "100.00",
      "price": "1620.00"
    }'
  ```

  ```bash Market order theme={null}
  curl -X POST https://api.dubupay.com/api/v1/trading/orders \
    -H "X-Api-Key: dubu_sk_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "symbol": "USDT-NGN",
      "side": "sell",
      "type": "market",
      "quantity": "100.00"
    }'
  ```
</CodeGroup>

**Order fields:**

| Field      | Type   | Required         | Description                          |
| ---------- | ------ | ---------------- | ------------------------------------ |
| `symbol`   | string | Yes              | Trading pair, e.g. `USDT-NGN`.       |
| `side`     | string | Yes              | `buy` or `sell`.                     |
| `type`     | string | Yes              | `limit` or `market`.                 |
| `quantity` | string | Yes              | Amount of the base asset to trade.   |
| `price`    | string | For limit orders | Limit price in quote currency (NGN). |

## Order lifecycle

An order moves through states from the moment it is placed until it is fully resolved.

```mermaid theme={null}
flowchart LR
    A[placed] --> B[open]
    B --> C[partially_filled]
    C --> D[filled]
    B --> E[cancelled]
    C --> E
```

| Status             | Description                                                                            |
| ------------------ | -------------------------------------------------------------------------------------- |
| `open`             | Order is on the book, waiting to be matched.                                           |
| `partially_filled` | Some of the quantity has been matched; the remainder is still open.                    |
| `filled`           | The full quantity has been matched. The order is complete.                             |
| `cancelled`        | The order was cancelled before it was fully filled. Any unfilled quantity is released. |

<Tip>
  For time-sensitive conversions, use a market order rather than a limit order. Limit orders can remain open indefinitely if the market does not reach your price.
</Tip>

## Managing orders

<CodeGroup>
  ```bash Get an order theme={null}
  curl https://api.dubupay.com/api/v1/trading/orders/{id} \
    -H "X-Api-Key: dubu_sk_live_..."
  ```

  ```bash List orders theme={null}
  curl "https://api.dubupay.com/api/v1/trading/orders?symbol=USDT-NGN&side=sell&status=open" \
    -H "X-Api-Key: dubu_sk_live_..."
  ```

  ```bash Cancel an order theme={null}
  curl -X DELETE https://api.dubupay.com/api/v1/trading/orders/{id} \
    -H "X-Api-Key: dubu_sk_live_..."
  ```
</CodeGroup>

You can filter listed orders by `symbol`, `status`, `side`, `page`, and `limit` (max 100).

## Trade history

Each matched order produces one or more **trades** — individual fill records. Retrieve your full trade history:

```bash theme={null}
curl https://api.dubupay.com/api/v1/trading/trades \
  -H "X-Api-Key: dubu_sk_live_..."
```

Trade records include the matched price, quantity, and timestamp for each fill. If a single order is partially filled across multiple matches, each match appears as a separate trade.

## Market data

Dubu Pay exposes three market data endpoints you can call without placing any orders.

<AccordionGroup>
  <Accordion title="Order book">
    The order book shows the current bid and ask sides of a market, sorted by price. Use `depth` to control how many price levels are returned.

    ```bash theme={null}
    curl "https://api.dubupay.com/api/v1/trading/market/orderbook?symbol=USDT-NGN&depth=20" \
      -H "X-Api-Key: dubu_sk_live_..."
    ```

    | Parameter | Required | Description                                |
    | --------- | -------- | ------------------------------------------ |
    | `symbol`  | Yes      | Trading pair, e.g. `USDT-NGN`.             |
    | `depth`   | No       | Number of price levels to return per side. |
  </Accordion>

  <Accordion title="Ticker">
    The ticker gives you a real-time snapshot of the last traded price, 24-hour volume, and price change for all pairs.

    ```bash theme={null}
    curl https://api.dubupay.com/api/v1/trading/market/ticker \
      -H "X-Api-Key: dubu_sk_live_..."
    ```
  </Accordion>

  <Accordion title="Klines (candlestick data)">
    Klines return OHLCV (open, high, low, close, volume) candlestick data for a symbol over a time range. This is useful for charting or calculating technical indicators.

    ```bash theme={null}
    curl "https://api.dubupay.com/api/v1/trading/market/klines?symbol=USDT-NGN&interval=1h&limit=100" \
      -H "X-Api-Key: dubu_sk_live_..."
    ```

    | Parameter  | Required | Description                                     |
    | ---------- | -------- | ----------------------------------------------- |
    | `symbol`   | Yes      | Trading pair.                                   |
    | `interval` | Yes      | Candle interval, e.g. `1m`, `5m`, `1h`, `1d`.   |
    | `limit`    | No       | Number of candles to return.                    |
    | `start`    | No       | Unix timestamp (ms) for the start of the range. |
    | `end`      | No       | Unix timestamp (ms) for the end of the range.   |
  </Accordion>
</AccordionGroup>

## Use cases

<Tabs>
  <Tab title="Convert USDT earnings to NGN">
    After accumulating USDT from customer deposits, you can sell it for NGN:

    <Steps>
      <Step title="Check your trading balance">
        Call `GET /trading/balances` to confirm the available USDT balance in the trading account.
      </Step>

      <Step title="Fetch the order book or ticker">
        Call `GET /trading/market/ticker` to see the current USDT-NGN market price and decide whether a limit or market order is appropriate.
      </Step>

      <Step title="Place a sell order">
        Submit `POST /trading/orders` with `side: "sell"`, `symbol: "USDT-NGN"`, and your chosen type and quantity.
      </Step>

      <Step title="Monitor until filled">
        Poll `GET /trading/orders/{id}` or subscribe to webhooks to detect when the order status changes to `filled`.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Buy USDT at a target rate">
    If you have NGN funds and want to acquire USDT at a specific exchange rate:

    <Steps>
      <Step title="Transfer NGN balance">
        Ensure you have NGN in your trading balance (transferred from the payments engine or received via offramp).
      </Step>

      <Step title="Place a limit buy order">
        Set `side: "buy"`, `type: "limit"`, and `price` to your target NGN-per-USDT rate. The order rests on the book until the market reaches your price.
      </Step>

      <Step title="Cancel if the rate moves against you">
        Call `DELETE /trading/orders/{id}` to cancel the order and release the reserved NGN.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Warning>
  Trading involves market risk. Limit orders are not guaranteed to fill, and market orders execute at the prevailing price which may differ from the last quoted price. Test your order logic in sandbox mode before going live.
</Warning>

## Endpoint overview

| Method   | Path                        | Description                                      |
| -------- | --------------------------- | ------------------------------------------------ |
| `GET`    | `/trading/balances`         | Get per-asset balances in the trading account    |
| `POST`   | `/trading/orders`           | Place a new order                                |
| `GET`    | `/trading/orders`           | List orders (filterable by symbol, status, side) |
| `GET`    | `/trading/orders/:id`       | Get a specific order                             |
| `DELETE` | `/trading/orders/:id`       | Cancel an open order                             |
| `GET`    | `/trading/trades`           | List trade history                               |
| `GET`    | `/trading/market/pairs`     | List all available trading pairs                 |
| `GET`    | `/trading/market/orderbook` | Get the live order book for a symbol             |
| `GET`    | `/trading/market/ticker`    | Get 24-hour ticker data for all pairs            |
| `GET`    | `/trading/market/klines`    | Get OHLCV candlestick data                       |