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

## 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-f2a849596e9afc9233a983b0ed7be8a305c629ff%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-f2a849596e9afc9233a983b0ed7be8a305c629ff%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.

{% 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-f2a849596e9afc9233a983b0ed7be8a305c629ff%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-f2a849596e9afc9233a983b0ed7be8a305c629ff%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-f2a849596e9afc9233a983b0ed7be8a305c629ff%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-f2a849596e9afc9233a983b0ed7be8a305c629ff%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-f2a849596e9afc9233a983b0ed7be8a305c629ff%2Ftrading-api-swagger.yaml?alt=media)
{% endopenapi %}

## Orders

Place market and limit orders, list your open orders, fetch a single order, or cancel one. 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).

{% 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-f2a849596e9afc9233a983b0ed7be8a305c629ff%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-f2a849596e9afc9233a983b0ed7be8a305c629ff%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-f2a849596e9afc9233a983b0ed7be8a305c629ff%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-f2a849596e9afc9233a983b0ed7be8a305c629ff%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-f2a849596e9afc9233a983b0ed7be8a305c629ff%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-f2a849596e9afc9233a983b0ed7be8a305c629ff%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="/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-f2a849596e9afc9233a983b0ed7be8a305c629ff%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-f2a849596e9afc9233a983b0ed7be8a305c629ff%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-f2a849596e9afc9233a983b0ed7be8a305c629ff%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-f2a849596e9afc9233a983b0ed7be8a305c629ff%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-f2a849596e9afc9233a983b0ed7be8a305c629ff%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-f2a849596e9afc9233a983b0ed7be8a305c629ff%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.

{% 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-f2a849596e9afc9233a983b0ed7be8a305c629ff%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-f2a849596e9afc9233a983b0ed7be8a305c629ff%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-f2a849596e9afc9233a983b0ed7be8a305c629ff%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)


---

# Agent Instructions: 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:

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

The question should be specific, self-contained, and written in natural language.
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.