Data Formats and Conventions

These rules apply to every endpoint. Most integration bugs that are not signing bugs are on this page.

Money is always a string

Balances, prices, quantities and fees are decimal strings, stored internally with 18 decimal places.

{ "availableBalance": "1500.25", "lockedBalance": "200" }

Never parse a monetary value into a float. By the time JSON.parse has returned a JSON number, precision is already lost. Use a decimal library: decimal.js in JavaScript, Decimal in Python, BigDecimal in Java.

Decimal strings are not zero-padded

The wire format strips trailing zeros. A balance of 1500.250000000000000000 is sent as "1500.25", and zero is sent as "0", never "0.000000000000000000". Two consequences:

Never compare money with string equality. In JavaScript "1.5" !== "1.50", but they are the same amount. Always compare through your decimal type.

Do not assume a fixed number of decimal places. Full precision is preserved, so "0.000000000000000001" survives a round trip exactly. It just is not padded.

Amounts you send

You do not need to pad either. "0.001", "0.0010" and "0.00100000" are all accepted and identical.

The format allows up to 20 digits before the decimal point and up to 18 after it, with no sign and no exponent. 1e-18 and +5 are both rejected.

One number that is not a string

leverage on futures orders is a plain JSON integer. It is the only non-string numeric on an order object.

Base units appear in exactly one place

pending.<tokenId>.pendingAmountBaseUnits on GET /v1/wallets/balance is in base units (satoshi, wei), not a human decimal like everything else. Convert it using the asset's decimals before you show it to anyone.

Timestamps

In responses: ISO-8601 UTC strings, for example 2026-08-18T09:20:43.000Z.

In the X-MG-TIMESTAMP header: Unix time in milliseconds.

Mixing these up is the cause of most INVALID_TIMESTAMP errors.

Symbols

BASE-QUOTE, uppercase, hyphen-separated: BTC-USDT, ETH-USDT. Lowercase input is accepted on order placement and uppercased for you, but match on the uppercase form.

Idempotency

Every POST and DELETE requires an Idempotency-Key header. Any unique string works, and a UUID is the obvious choice.

Reusing a key replays the original response instead of performing the action again. That is what makes it safe to retry after a network timeout: you cannot accidentally place the same order twice.

Use a fresh key for each new logical operation.

Reuse a key only when retrying that same operation.

A retry still needs a new signature, even with the same idempotency key.

If the original request is still running when the retry arrives, you get 409 IDEMPOTENCY_IN_PROGRESS. Wait briefly and try again.

Your own data, and nothing else

Every read and write is scoped to the account that owns the API key. Passing an id that belongs to another user returns 404, never 403 and never their data. The API will not confirm that someone else's id exists.

Response shapes worth knowing in advance

Endpoint	Shape	Watch out for
`GET /v1/wallets/balance`	Object with `balances` array and `pending` object	`pending` is keyed by `tokenId` as a string key, not an array
`GET /v1/transfers/balances`	Object keyed by coin ticker	Slot keys are lowercase (`spot`, `asset`, `future`) while `walletType` elsewhere is uppercase
`GET /v1/orders`	A bare JSON array	Not wrapped in an object. No `total`, `page` or `hasMore`
`GET /v1/futures/orders`	A bare JSON array	Each element carries a `fills` array
Everything else	Object

The uppercase and lowercase asymmetry between wallet endpoints is real. Do not normalize one to the other and assume they match.

Optional fields that are absent, not null

rejectReason and venueCode are added only to orders whose status is REJECTED. On every other order the keys are missing entirely. Check for presence, not for null.

Request size

Bodies are capped at 32 KB. Anything larger returns 413 PAYLOAD_TOO_LARGE.

Every response is JSON

Including every error. See 06. Errors and Troubleshooting for the envelope.

05. Data Formats and Conventions

Data Formats and Conventions#

Money is always a string#

Decimal strings are not zero-padded#

Amounts you send#

One number that is not a string#

Base units appear in exactly one place#

Timestamps#

Symbols#

Idempotency#

Your own data, and nothing else#

Response shapes worth knowing in advance#

Optional fields that are absent, not null#

Request size#

Every response is JSON#