# True Markets Gateway API

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/conductor` |
| UAT (sandbox) | `https://api.uat.truemarkets.co/v1/conductor` |

> 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 <token>` header.

### Getting credentials

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).
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.

### 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":"<UUID>","timestamp":<UNIX_SECONDS>,"signature":"<BASE64URL_ES256_SIG>"}'

# Compute a quote
curl -X POST https://api.truemarkets.co/v1/conductor/quotes \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"base":"BTC","quote":"USD","side":"buy","quantity":"0.01"}'
```

> Need to trade on a CeFi venue directly? CeFi direct FIX/REST/WS is institutional only — see the [CeFi Direct REST API](/apis/cefi-direct/rest/v1) 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 always returns an `order_id` and a `status`.
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 your private key and post the signatures to `POST /orders/{id}/execute`. The order then moves to `pending`.
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.
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.
    - `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.

## Support
- 💬 [Discord](https://discord.gg/SC92xRUZqw) — community and integration help
- 📧 [support@truemarkets.co](mailto:support@truemarkets.co) — account, network, onboarding


Version: 1.0.0

## Servers

Production
```
https://api.truemarkets.co/v1/conductor
```

UAT (sandbox)
```
https://api.uat.truemarkets.co/v1/conductor
```

## Security

### bearerAuth

Type: http
Scheme: bearer
Bearer Format: JWT

## Download OpenAPI description

[True Markets Gateway API](https://docs.truemarkets.co/_bundle/apis/gateway/openapi.yaml)

## Quotes

Request real-time market quotes for trading pairs without creating an order.

### Compute market quote (CeFi only)

 - [POST /quotes](https://docs.truemarkets.co/apis/gateway/openapi/quotes/computequote.md): Non-binding price preview for a CeFi market order. For DeFi, the quote is returned by POST /orders (see CreateOrderResponse.quote).

## Orders

Create, execute, cancel, and monitor orders across CeFi and DeFi.

### Create new order

 - [POST /orders](https://docs.truemarkets.co/apis/gateway/openapi/orders/createorder.md): Creates a new order. For DeFi orders, returns unsigned payloads for client signing.

### List user orders

 - [GET /orders](https://docs.truemarkets.co/apis/gateway/openapi/orders/listorders.md): Returns a paginated list of completed and failed orders with execution data for the authenticated user

### Execute pending order

 - [POST /orders/{id}/execute](https://docs.truemarkets.co/apis/gateway/openapi/orders/executeorder.md): Executes a pending order using client-provided signatures for the unsigned payloads

### Cancel a pending limit order

 - [DELETE /orders/{id}](https://docs.truemarkets.co/apis/gateway/openapi/orders/cancelorder.md): Submits a cancellation request for a pending limit order on CeFi.

Cancellation is asynchronous — the order moves to cancel_pending immediately,
then the order syncer reconciles the final state:
- cancelled if the CeFi exchange confirms the cancellation
- complete if the order filled before the cancel landed (race condition)

Only CeFi limit orders in pending or active status are cancellable.
DeFi orders and market orders return 400.

### Get order status

 - [GET /orders/{id}/status](https://docs.truemarkets.co/apis/gateway/openapi/orders/getorderstatus.md): Returns the current status of an order

## Transfers

Create, execute, and monitor transfers across CeFi and DeFi.

### Create new transfer

 - [POST /transfers](https://docs.truemarkets.co/apis/gateway/openapi/transfers/createtransfer.md): Creates a new on-chain transfer. Returns unsigned payloads for the client to sign before executing.

### List user transfers

 - [GET /transfers](https://docs.truemarkets.co/apis/gateway/openapi/transfers/listtransfers.md): Returns a paginated list of transfers for the authenticated user

### Execute pending transfer

 - [POST /transfers/{id}/execute](https://docs.truemarkets.co/apis/gateway/openapi/transfers/executetransfer.md): Executes a transfer in awaiting_signature status using client-provided signatures

### Get transfer by ID

 - [GET /transfers/{id}](https://docs.truemarkets.co/apis/gateway/openapi/transfers/gettransfer.md): Returns the current state of a transfer

## Assets

Browse the unified catalog of tradeable assets across DeFi and CeFi venues.

### List tradeable assets

 - [GET /assets](https://docs.truemarkets.co/apis/gateway/openapi/assets/listassets.md): Returns a unified catalog of all active tradeable assets across DeFi and CeFi venues

## Balances

Query account balances for the authenticated user.

### List balances

 - [GET /balances/unified](https://docs.truemarkets.co/apis/gateway/openapi/balances/listbalances.md): Returns unified balances across CeFi and DeFi for the authenticated user

### Get user balances

 - [GET /balances](https://docs.truemarkets.co/apis/gateway/openapi/balances/getbalances.md): Returns balances for the authenticated user