Version: 1.39.0

Trading REST

Gateway API for the True Markets trading platform — unified order orchestration, quotes, transfers, and balance management across CeFi and DeFi venues. Recommended for most integrations.

Base URLs

Environment	Base URL
Production	https://api.truemarkets.co/v1/gateway
UAT (sandbox)	https://api.uat.truemarkets.co/v1/gateway

The legacy /v1/conductor base path continues to work for existing integrations but is deprecated — new integrations should use /v1/gateway.

UAT is the testing environment. It may require VPN/allowlist access for some integrations — contact [email protected] if requests time out from a public network.

Authentication

All endpoints require a JWT access token in the Authorization: Bearer <token> header.

Getting credentials

There are two ways in, and each uses its own keys.

Gateway (an organization trading for its users). Create an organization and an API key in the developer console, then mint a token with POST /v1/auth/api-key/token. An organization token lasts one hour and has no refresh token, so mint a new one before it expires. Sign each user's payloads with their signer key, not the organization API key.

Trading API (your own account).

1. Create an account at https://www.truemarkets.co (passkey, email, magic link, or Sign in with Apple).
2. Register an API key in your account's API Keys settings page. Generate an EC P-256 key pair locally and submit only the public key — the private key never leaves your machine. You'll receive a key_id (UUID). The same key signs you in and signs your payloads.
3. Mint JWTs by calling POST /v1/auth/api-key/token with key_id, a current timestamp (Unix seconds, within ±30s of server UTC time), and signature — an ES256 (ECDSA P-256 + SHA-256) signature of the message {key_id}.{timestamp}, base64url-encoded. The response returns access_token and refresh_token.
4. Call the Gateway with Authorization: Bearer <access_token>.
5. Refresh expired access tokens via POST /v1/auth/token/refresh with the refresh_token — no re-signing required.

Acting for a user

An organization trades for the users it created. Mint a token from an organization API key, then add TM-On-Behalf-Of: <user_id> to any user route: the request reads and writes that user's account. The header is declared on every route that accepts it, and organization-scoped routes reject it.

Quick start

# Mint a JWT
curl -X POST https://api.truemarkets.co/v1/auth/api-key/token \
  -H "Content-Type: application/json" \
  -d '{"key_id":"<UUID>","timestamp":<UNIX_SECONDS>,"signature":"<BASE64URL_ES256_SIG>"}'

# Compute a quote
curl -X POST https://api.truemarkets.co/v1/gateway/quotes \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"base_asset":"BTC","quote_asset":"USD","qty":"1000","qty_unit":"quote","side":"buy"}'

Need to trade on a CeFi venue directly? CeFi direct FIX/REST/WS is institutional only — see the CeFi Direct REST API reference. Retail traders reach CeFi via this Gateway, which proxies and signs the upstream HMAC for you.

Order lifecycle

Orders move through a small set of statuses. The path depends on whether the venue and order type require client-side signing.

1. Create — POST /orders with your trade params. The response returns an order_id and a status. The exception is a DeFi order the account cannot fund (no on-chain balance and no CeFi balance to bridge): the response carries the quote with an Insufficient balance entry in quote.issues, an empty order_id, and no payloads. The quote is informational so the client can still show the expected output, but no order is created and it cannot be executed.
2. Sign and execute — for DeFi orders and CeFi buy orders that need a funding bridge, the create response returns status: initialized along with an array of unsigned payloads. Sign each payload locally with the key that controls the wallet (a Gateway user's signer key, or your own API key) and post the signatures to POST /orders/{id}/execute. A CeFi buy then moves to pending; a DeFi order settles synchronously to complete (immediate fill) or active (a limit order resting on-chain).
3. Submitted directly — for CeFi sell orders and sufficiently funded CeFi buy orders, the create response already returns status: pending with no payloads. The execute step is skipped. In a paper-trading environment DeFi orders also take this path: they settle against the virtual ledger during create and return a terminal status (complete) with no payloads, so clients must treat an empty payloads array as "already submitted" rather than waiting to sign.
4. Settle — the order transitions out of pending to one of:
   • complete — fully filled.
   • active — limit order resting in the order book (can later move to complete or canceled).
   • canceled — canceled by the user or rejected by exchange/market conditions. A CeFi cancel first passes through cancel_pending until the exchange confirms.
   • failed — rejected by the exchange or DeFi execution reverted.

Poll GET /orders/{id}/status (or list orders) to track progression. The payloads field in the create response is the signal: if it's non-empty, you need to sign and call execute. If it's empty or absent, the order is already submitted, unless order_id is empty and quote.issues reports an insufficient-balance problem, which means no order was created.

Support

• 📧 [email protected]

Authentication

HTTP: Bearer Auth

An access token from POST /v1/auth/api-key/token. An organization token lasts one hour and has no refresh token; a personal token can be refreshed.

Security Scheme Type:	http
HTTP Authorization Scheme:	bearer
Bearer format:	JWT

Contact

True Markets support: [email protected]