1. Find the symbol
There’s no endpoint that lists symbols. The exchange publishes its own lists, by symbol: its listed companies and its exchange-traded products. Before we store a market order or a sell, we check its symbol against the broker’s price list. A symbol that isn’t on it is refused with422 unknown_symbol, and nothing is stored. A limit buy isn’t checked first: it’s sent, and if the broker doesn’t list the symbol, it comes back rejected with reject_reason unknown_symbol. The sandbox lists only its own few symbols: see the sandbox reference.
Prices to show your customers
The API gives no prices or quotes. To show your customers prices, use a licensed market data source: the exchange’s data portal or a registered data vendor. The prices on the exchange’s own price list page are delayed by 30 minutes. For a symbol the account holds,GET /v1/accounts/{account}/positions gives market_price_kobo, the broker’s figure, and market_value_kobo, the position’s worth at that price.
Never show an estimate as a price. It’s the most an order can cost: a market buy is priced at the day’s upper limit, plus charges.
2. Estimate the order
POST /v1/orders/estimate takes the same body as POST /v1/orders and returns estimated_total_kobo without placing or storing anything. For a buy, it’s the estimated cost. For a sell, it’s the estimated proceeds. The figure is the broker’s estimate: it includes the consideration, statutory charges and commission, and it’s indicative. An estimate meets neither daily limit and still works while trading is paused. A symbol the broker doesn’t list comes back 422 order_rejected with reject_reason unknown_symbol, not 422 unknown_symbol.
A market order is priced at the day’s price limit, so a market buy’s estimate uses the upper limit, which nothing trades above. The quickstart works one out.
Before a market buy, check that the account’s available_kobo covers the estimate, not the cost you expect at the fill: we send the order to the broker at the upper limit. If you fund the account first, allocate at least the estimate. In the sandbox, a buy the balance can’t cover at that price gets 422 order_rejected with reject_reason insufficient_funds.
3. Place the order
SendPOST /v1/orders with the same body and a new Idempotency-Key. The quickstart shows the request and its answer. Order types says when to send limit and when market.
If the answer is 503 outcome_not_recorded, the order the error’s order names reads sending until it resolves, as an uncertain order does. Retrieve it, or wait for its event, and don’t place it again under a new key. Idempotency lists every other answer.
Send a market order as day, never gtc: Time in force says why.
Sell only what the account holds
Before a sell, readGET /v1/accounts/{account}/positions, and sell no more than the position’s quantity.
In live, the broker publishes no refusal for a sell of more shares than the account holds. If it refuses one with a reason it doesn’t publish, the order is uncertain until our operations team reconciles it: see Handle an uncertain result. In the sandbox such a sell doesn’t fill: an ioc or fok order expires at once, a day order expires at midnight West Africa Time (WAT), and a gtc order stays open until the sandbox restarts, when it ends expired. A market sell cannot be cancelled: only a limit order can.
4. Follow the order
We check the broker for changes to your open orders about every 30 seconds. Each change sends an event, or you can retrieve the order withGET /v1/orders/{id}. The order is finished once it’s filled, rejected, refused, cancelled or expired. Order states explains each.
If it’s uncertain, or still sending after its request has ended, don’t place it again under a new key. See Handle an uncertain result.
5. Cancel an order
SendDELETE /v1/orders/{id}. You can cancel only a limit order that is pending or partially_filled.
6. Read what it cost
Each fill becomes a trade inGET /v1/accounts/{account}/trades, carrying your order’s order_id. Once the trade settles, its contract note appears in GET /v1/accounts/{account}/contract-notes with the charges, matched to the trade by ticket. After a fill explains each figure and when each appears.