--- title: "Trading REST" url: https://docs.truemarkets.co/api/gateway/trading-rest description: "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." --- Docs index: https://docs.truemarkets.co/llms.txt 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 [support@truemarkets.co](mailto:support@truemarkets.co) if requests time out from a public network. ## Authentication All endpoints require a JWT access token in the `Authorization: Bearer ` 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](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 `. 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: ` 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 ```bash # Mint a JWT curl -X POST https://api.truemarkets.co/v1/auth/api-key/token \ -H "Content-Type: application/json" \ -d '{"key_id":"","timestamp":,"signature":""}' # Compute a quote curl -X POST https://api.truemarkets.co/v1/gateway/quotes \ -H "Authorization: Bearer " \ -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](https://docs.truemarkets.co/api/institutional/true-markets-cefi-rest) 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 - 📧 [support@truemarkets.co](mailto:support@truemarkets.co) ## 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: [support@truemarkets.co](mailto:support@truemarkets.co) ## Operations - [Cancel all open orders on a venue](https://docs.truemarkets.co/api/gateway/cancel-all-orders.md): `POST /orders/all/cancel` - [Compute market quote (CeFi only)](https://docs.truemarkets.co/api/gateway/compute-quote.md): `POST /quotes` - [Allocate funds to CeFi](https://docs.truemarkets.co/api/gateway/create-allocation.md): `POST /custody/allocations` - [Create new order](https://docs.truemarkets.co/api/gateway/create-order.md): `POST /orders` - [Add test funds (paper trading only)](https://docs.truemarkets.co/api/gateway/create-paper-deposit.md): `POST /paper/deposits` - [Remove test funds (paper trading only)](https://docs.truemarkets.co/api/gateway/create-paper-withdrawal.md): `POST /paper/withdrawals` - [Create a ramp](https://docs.truemarkets.co/api/gateway/create-ramp.md): `POST /ramps` - [Release funds from CeFi](https://docs.truemarkets.co/api/gateway/create-release.md): `POST /custody/releases` - [Create new transfer](https://docs.truemarkets.co/api/gateway/create-transfer.md): `POST /transfers` - [Execute a resting DeFi order cancellation](https://docs.truemarkets.co/api/gateway/execute-cancel-order.md): `POST /orders/{id}/cancel/execute` - [Execute pending order](https://docs.truemarkets.co/api/gateway/execute-order.md): `POST /orders/{id}/execute` - [Execute a ramp's bridge plan](https://docs.truemarkets.co/api/gateway/execute-ramp-bridge.md): `POST /ramps/{id}/bridge/execute` - [Execute a ramp's on-chain transfer](https://docs.truemarkets.co/api/gateway/execute-ramp-transfer.md): `POST /ramps/{id}/execute` - [Execute pending transfer](https://docs.truemarkets.co/api/gateway/execute-transfer.md): `POST /transfers/{id}/execute` - [Get allocation](https://docs.truemarkets.co/api/gateway/get-allocation.md): `GET /custody/allocations/{id}` - [Get one asset by chain and address](https://docs.truemarkets.co/api/gateway/get-asset.md): `GET /assets/{chain}/{address}` - [Get asset availability for the caller's country](https://docs.truemarkets.co/api/gateway/get-asset-availability.md): `GET /assets/availability` - [Get user balances](https://docs.truemarkets.co/api/gateway/get-balances.md): `GET /balances` - [Get a single order](https://docs.truemarkets.co/api/gateway/get-order.md): `GET /orders/{id}` - [Get order status](https://docs.truemarkets.co/api/gateway/get-order-status.md): `GET /orders/{id}/status` - [Get the authenticated user's portfolio](https://docs.truemarkets.co/api/gateway/get-portfolio.md): `GET /portfolio` - [Get ramp by ID](https://docs.truemarkets.co/api/gateway/get-ramp.md): `GET /ramps/{id}` - [Get release](https://docs.truemarkets.co/api/gateway/get-release.md): `GET /custody/releases/{id}` - [Get transfer by ID](https://docs.truemarkets.co/api/gateway/get-transfer.md): `GET /transfers/{id}` - [List allocations](https://docs.truemarkets.co/api/gateway/list-allocations.md): `GET /custody/allocations` - [List tradeable assets](https://docs.truemarkets.co/api/gateway/list-assets.md): `GET /assets` - [List balances](https://docs.truemarkets.co/api/gateway/list-balances.md): `GET /balances/unified` - [List user orders](https://docs.truemarkets.co/api/gateway/list-orders.md): `GET /orders` - [List organization transactions](https://docs.truemarkets.co/api/gateway/list-organization-transactions.md): `GET /organizations/{organization_id}/transactions` - [List open positions](https://docs.truemarkets.co/api/gateway/list-positions.md): `GET /positions` - [List user ramps](https://docs.truemarkets.co/api/gateway/list-ramps.md): `GET /ramps` - [List releases](https://docs.truemarkets.co/api/gateway/list-releases.md): `GET /custody/releases` - [List user transactions](https://docs.truemarkets.co/api/gateway/list-transactions.md): `GET /transactions` - [List user transfers](https://docs.truemarkets.co/api/gateway/list-transfers.md): `GET /transfers` - [Modify an active limit order](https://docs.truemarkets.co/api/gateway/modify-order.md): `PATCH /orders/{id}` - [Cancel a limit or TP/SL order (CeFi or DeFi)](https://docs.truemarkets.co/api/gateway/prepare-cancel-order.md): `POST /orders/{id}/cancel` - [Prepare a ramp's on-chain transfer](https://docs.truemarkets.co/api/gateway/prepare-ramp-transfer.md): `POST /ramps/{id}/prepare`