Crypto trading with the Dubu Pay API

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:

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.

curl https://api.dubupay.com/api/v1/trading/balances \
  -H "X-Api-Key: dubu_sk_live_..."

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 for details.

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.

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"
  }'

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"
  }'

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.

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.

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.

Managing orders

curl https://api.dubupay.com/api/v1/trading/orders/{id} \
  -H "X-Api-Key: dubu_sk_live_..."

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

curl -X DELETE https://api.dubupay.com/api/v1/trading/orders/{id} \
  -H "X-Api-Key: dubu_sk_live_..."

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:

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.

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.

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.

Ticker

The ticker gives you a real-time snapshot of the last traded price, 24-hour volume, and price change for all pairs.

curl https://api.dubupay.com/api/v1/trading/market/ticker \
  -H "X-Api-Key: dubu_sk_live_..."

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.

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.

Use cases

Convert USDT earnings to NGN
Buy USDT at a target rate

After accumulating USDT from customer deposits, you can sell it for NGN:

Check your trading balance

Call GET /trading/balances to confirm the available USDT balance in the trading account.

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.

Place a sell order

Submit POST /trading/orders with side: "sell", symbol: "USDT-NGN", and your chosen type and quantity.

Monitor until filled

Poll GET /trading/orders/{id} or subscribe to webhooks to detect when the order status changes to filled.

If you have NGN funds and want to acquire USDT at a specific exchange rate:

Transfer NGN balance

Ensure you have NGN in your trading balance (transferred from the payments engine or received via offramp).

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.

Cancel if the rate moves against you

Call DELETE /trading/orders/{id} to cancel the order and release the reserved NGN.

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.

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

Get Started

Authentication

Core Concepts

Guides

Account & Security

Crypto trading with the Dubu Pay API

Supported trading pairs

Balances

Order types

Placing an order

Order lifecycle

Managing orders

Trade history

Market data

Use cases

Endpoint overview

​Supported trading pairs

​Balances

​Order types

​Placing an order

​Order lifecycle

​Managing orders

​Trade history

​Market data

​Use cases

​Endpoint overview

Supported trading pairs

Balances

Order types

Placing an order

Order lifecycle

Managing orders

Trade history

Market data

Use cases

Endpoint overview