Skip to main content
POST

Authorizations

​
Authorization
string
header
required

Authorization: Bearer <key>. Sandbox keys start with mgw_test_ and live keys start with mgw_live_. Each key works only in its own environment, and a live key works only from the IP addresses or ranges registered for it.

Headers

​
Idempotency-Key
string
required

A key you choose to identify this request. Send the same key every time you retry the request. Once used, a key stays tied to that request permanently. It must be printable ASCII with no spaces, and we compare it byte for byte. Send the header only once.

Required string length: 1 - 255
Pattern: ^[!-~]+$

Body

application/json

Send numbers as JSON numbers, not quoted strings. We reject unknown fields and any field that appears twice, even with different letter case.

​
account
string
required

An account code. Case-insensitive on input, and returned in uppercase.

Pattern: ^[A-Za-z0-9]{1,64}$
​
symbol
string
required

The exchange's symbol, treated as uppercase. The exchange decides whether the symbol exists.

Pattern: ^[A-Za-z0-9.-]{1,20}$
​
side
enum<string>
required
Available options:
buy,
sell
​
quantity
integer<int64>
required

The number of shares, as a whole number.

Required range: 1 <= x <= 100000000
​
type
enum<string>
required
Available options:
limit,
market
​
time_in_force
enum<string>
required
Available options:
day,
gtc,
ioc,
fok
​
price_kobo
integer<int64>

The limit price in kobo, so ₦475.00 is 47500. Required for a limit order. Omit it for a market order.

Required range: 1 <= x <= 1000000000

Response

This idempotency key was already used for this same order, so we didn't send anything new. The body shows the order's current state.

​
object
string
required
Allowed value: "order"
​
id
string
required

Unique identifier for the order. Starts with ord_.

​
state
enum<string>
required

sending: stored, and the send is in progress. pending: the exchange has the order. partially_filled, filled: some or all of the order has traded. uncertain: we don't know whether the exchange received it. We don't send it again; we reconcile it against the exchange's record. rejected: the exchange rejected it; see reject_reason. refused: we refused it, and it never reached the exchange. cancelled: the exchange confirmed the cancel. expired: its time in force ran out.

Available options:
sending,
pending,
partially_filled,
filled,
uncertain,
rejected,
refused,
cancelled,
expired
​
account
string
required

The account code, in uppercase.

​
symbol
string
required

The account code, in uppercase.

​
side
enum<string>
required
Available options:
buy,
sell
​
quantity
integer<int64>
required
​
type
enum<string>
required
Available options:
limit,
market
​
time_in_force
enum<string>
required
Available options:
day,
gtc,
ioc,
fok
​
price_kobo
integer<int64> | null
required

The limit price in kobo. Null for a market order.

​
filled_quantity
integer<int64>
required

The total number of shares traded so far.

​
exchange_order_id
string | null
required

The exchange's identifier for the order, once it has one.

​
reason
string | null
required

A sentence explaining the order's current state. It's for people to read, so don't use it in your logic.

​
reject_reason
enum<string> | null
required

Why the exchange rejected the order. Set only when state is rejected.

Available options:
insufficient_funds,
market_closed,
settlement_lockout,
limit_orders_etf_only,
unknown_symbol,
symbol_not_tradable,
account_not_at_broker,
rejected_by_exchange,
null
​
created_at
string<date-time>
required

In UTC, to the second.

​
updated_at
string<date-time>
required

In UTC, to the second.