> For the complete documentation index, see [llms.txt](https://thegrid.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://thegrid.ai/docs/api-reference/trading-api.md).

# Trading API

The Trading API exposes everything beyond inference: instrument specifications, market data, balances, past trades, transfers, and direct order placement. You call it to read the state of your account, look up an instrument's spec, or place a limit order yourself instead of letting Auto Mode buy on your behalf.

For the canonical instrument catalog and the spec each instrument is benchmarked against, see [Current instruments](/docs/instrument-specifications/current-instruments.md). For Auto Mode versus Advanced Mode and when to use each, see [Auto Mode vs Advanced Mode](/docs/start-here/auto-mode-vs-advanced-mode.md).

Base URL: `https://trading.api.thegrid.ai/v1`

Authentication uses Ed25519-signed requests with the headers `x-thegrid-signature`, `x-thegrid-timestamp`, and `x-thegrid-fingerprint`. See [Authentication](/docs/api-reference/authentication.md) for the signing scheme and keypair generation.

**Signing payload:** `{timestamp}{METHOD}{path}{body}`. Use the **pathname only** (for example `/v1/orders`), never the query string. Filters such as `?status=filled` are applied after signature verification. On `POST`, the JSON body is included in the signature; query parameters on the URL are not. Full details: [Authentication — Sign a request](/docs/api-reference/authentication.md#sign-a-request).

## Before your first order

Run these checks before placing live orders:

1. `GET /v1/health` without auth to confirm the Trading API is reachable.
2. Signed `GET /v1/me` to verify credentials and read `account_mode`.
3. Signed `GET /v1/trading-accounts` to inspect USD and per-instrument inventory.
4. `GET /v1/markets` to read `order_controls` such as `tick_size`, `lot_size`, `min_order_size`, and `max_order_size`.
5. `GET /v1/account/limits?market_id=...` to read the order rate limit enforced for your user on that market.

{% hint style="warning" %}
There is no bare `GET /v1/account` Trading endpoint. Use signed `GET /v1/me` for identity and account mode, `GET /v1/account/limits?market_id=...` for market-specific order rate limits, then `GET /v1/trading-accounts` and `GET /v1/currency-trading-accounts` for token and USD balances.
{% endhint %}

Auto Mode is the default. Signed reads still work in Auto Mode, but order create/update/cancel returns `403` with `auto_mode_trading_restricted` after onboarding until you switch the account to Advanced Mode in the app or through the Platform API.

For scripts that place or cancel real orders, run Python unbuffered (`python3 -u` or `PYTHONUNBUFFERED=1`) so logs are visible immediately.

## Instruments

Instrument specifications, including which models qualify, the Quality Score floor, and supplier conditions. See [Current instruments](/docs/instrument-specifications/current-instruments.md) for the human-readable catalog.

{% openapi src="/files/97LrfSDtcq2qz2KHTfoZ" path="/instruments" method="get" %}
[trading-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-d5c0e94558530998fb31bdae400f526b906ad889%2Ftrading-api-swagger.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/97LrfSDtcq2qz2KHTfoZ" path="/instruments/{instrument\_id}" method="get" %}
[trading-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-d5c0e94558530998fb31bdae400f526b906ad889%2Ftrading-api-swagger.yaml?alt=media)
{% endopenapi %}

## Markets

A market is a tradable pair: an instrument quoted in a currency. Each instrument has one market. These endpoints expose ticker, depth, and recent trades.

{% hint style="warning" %}
Do not derive IDs by changing case, replacing `-` with `_`, or transforming a symbol such as `TEXT-PRIME` / `text-prime`. Use `market_id` exactly as returned by `/v1/markets` for market endpoints. Use the top-level `instrument_id` on each market, or the same value in `/v1/markets[].instruments[].instrument_id`, for instrument and balance endpoints.
{% endhint %}

{% openapi src="/files/97LrfSDtcq2qz2KHTfoZ" path="/markets" method="get" %}
[trading-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-d5c0e94558530998fb31bdae400f526b906ad889%2Ftrading-api-swagger.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/97LrfSDtcq2qz2KHTfoZ" path="/markets/{market\_id}" method="get" %}
[trading-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-d5c0e94558530998fb31bdae400f526b906ad889%2Ftrading-api-swagger.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/97LrfSDtcq2qz2KHTfoZ" path="/markets/{market\_id}/ticker" method="get" %}
[trading-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-d5c0e94558530998fb31bdae400f526b906ad889%2Ftrading-api-swagger.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/97LrfSDtcq2qz2KHTfoZ" path="/markets/{market\_id}/orderbook" method="get" %}
[trading-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-d5c0e94558530998fb31bdae400f526b906ad889%2Ftrading-api-swagger.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/97LrfSDtcq2qz2KHTfoZ" path="/markets/{market\_id}/trades" method="get" %}
[trading-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-d5c0e94558530998fb31bdae400f526b906ad889%2Ftrading-api-swagger.yaml?alt=media)
{% endopenapi %}

## Orders

Place market and limit orders, list your open orders, fetch a single order, or cancel one. You can both buy and sell tokens on the order book. Purchased tokens are credited to your Trading account. When those tokens are sold, the proceeds are credited to your Currency Trading (USD) account. See [Reselling tokens](/docs/concepts/reselling.md) for the full flow. For when to operate at this level versus letting Auto Mode handle it, see [Auto Mode vs Advanced Mode](/docs/start-here/auto-mode-vs-advanced-mode.md).

{% hint style="warning" %}
For limit orders, send `price` as a JSON string: `"0.68"`, not `0.68`. The Trading API rejects numeric JSON prices with `422` because decimal precision matters. `quantity` is a whole integer lot count.
{% endhint %}

If a 422 response mentions order controls, refresh `/v1/markets` and round to the market's `tick_size` and `lot_size` before retrying. Common order-control failures include `errors.code` and `errors.context`, including your submitted `price` / `quantity`, the `client_order_id` when provided, and relevant limits such as `min_order_size`, `lot_size`, and `tick_size`.

`GET /v1/orders?status=...` accepts public aliases and internal lifecycle values. Use `open` for active resting orders; `active`, `pending`, `partially_filled`, and `cancellation_pending` for specific open states; `filled` for filled orders; and `closed`, `cancelled`, `expired`, or `rejected` for terminal closed orders. Invalid status values return `422`.

{% openapi src="/files/97LrfSDtcq2qz2KHTfoZ" path="/orders" method="get" %}
[trading-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-d5c0e94558530998fb31bdae400f526b906ad889%2Ftrading-api-swagger.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/97LrfSDtcq2qz2KHTfoZ" path="/orders" method="post" %}
[trading-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-d5c0e94558530998fb31bdae400f526b906ad889%2Ftrading-api-swagger.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/97LrfSDtcq2qz2KHTfoZ" path="/orders/{order\_id}" method="get" %}
[trading-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-d5c0e94558530998fb31bdae400f526b906ad889%2Ftrading-api-swagger.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/97LrfSDtcq2qz2KHTfoZ" path="/orders/{order\_id}" method="delete" %}
[trading-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-d5c0e94558530998fb31bdae400f526b906ad889%2Ftrading-api-swagger.yaml?alt=media)
{% endopenapi %}

## Trades

Your filled trades, paginated.

{% openapi src="/files/97LrfSDtcq2qz2KHTfoZ" path="/trades" method="get" %}
[trading-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-d5c0e94558530998fb31bdae400f526b906ad889%2Ftrading-api-swagger.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/97LrfSDtcq2qz2KHTfoZ" path="/trades/{trade\_id}" method="get" %}
[trading-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-d5c0e94558530998fb31bdae400f526b906ad889%2Ftrading-api-swagger.yaml?alt=media)
{% endopenapi %}

## Accounts

You hold three account types: Consumption accounts (token balances per instrument, drawn down by inference calls), Trading accounts (token balances per instrument, used to place orders), and Currency Trading accounts (your USD balance for funding orders). These endpoints expose all three.

{% openapi src="/files/97LrfSDtcq2qz2KHTfoZ" path="/account/limits" method="get" %}
[trading-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-d5c0e94558530998fb31bdae400f526b906ad889%2Ftrading-api-swagger.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/97LrfSDtcq2qz2KHTfoZ" path="/consumption-accounts" method="get" %}
[trading-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-d5c0e94558530998fb31bdae400f526b906ad889%2Ftrading-api-swagger.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/97LrfSDtcq2qz2KHTfoZ" path="/consumption-accounts/{account\_id}" method="get" %}
[trading-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-d5c0e94558530998fb31bdae400f526b906ad889%2Ftrading-api-swagger.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/97LrfSDtcq2qz2KHTfoZ" path="/trading-accounts" method="get" %}
[trading-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-d5c0e94558530998fb31bdae400f526b906ad889%2Ftrading-api-swagger.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/97LrfSDtcq2qz2KHTfoZ" path="/trading-accounts/{account\_id}" method="get" %}
[trading-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-d5c0e94558530998fb31bdae400f526b906ad889%2Ftrading-api-swagger.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/97LrfSDtcq2qz2KHTfoZ" path="/currency-trading-accounts" method="get" %}
[trading-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-d5c0e94558530998fb31bdae400f526b906ad889%2Ftrading-api-swagger.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/97LrfSDtcq2qz2KHTfoZ" path="/currency-trading-accounts/{account\_id}" method="get" %}
[trading-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-d5c0e94558530998fb31bdae400f526b906ad889%2Ftrading-api-swagger.yaml?alt=media)
{% endopenapi %}

## Transfers

Transfers move tokens from a Trading account to a Consumption account. They are one-way and final: once tokens land in a Consumption account, they can only be drawn down by inference calls. This is also the boundary for [reselling](/docs/concepts/reselling.md): tokens are sellable while they sit in the Trading account, so transfer what you plan to consume and leave the rest where it can still be sold.

{% openapi src="/files/97LrfSDtcq2qz2KHTfoZ" path="/transfers/trading-to-consumption" method="post" %}
[trading-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-d5c0e94558530998fb31bdae400f526b906ad889%2Ftrading-api-swagger.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/97LrfSDtcq2qz2KHTfoZ" path="/transfer-histories" method="get" %}
[trading-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-d5c0e94558530998fb31bdae400f526b906ad889%2Ftrading-api-swagger.yaml?alt=media)
{% endopenapi %}

## Price histories

Time-series OHLCV data for instruments.

{% openapi src="/files/97LrfSDtcq2qz2KHTfoZ" path="/price-histories" method="get" %}
[trading-api-swagger.yaml](https://132387983-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAFL4lTMN4MTksJiuTkKd%2Fuploads%2Fgit-blob-d5c0e94558530998fb31bdae400f526b906ad889%2Ftrading-api-swagger.yaml?alt=media)
{% endopenapi %}

## Where next

* [Authentication](/docs/api-reference/authentication.md): Ed25519 keypair generation and the request-signing scheme
* [Current instruments](/docs/instrument-specifications/current-instruments.md): the human-readable instrument catalog
* [Errors and rate limits](/docs/api-reference/errors-and-rate-limits.md)
* [Trading bot safety patterns](/docs/integrations-and-best-practices/trading-bot-safety.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://thegrid.ai/docs/api-reference/trading-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.