> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tradingapi.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Build with AI agents

> Give an AI agent a limited key and a working loop: check, preview, place, read the summary.

The Trading API is designed to be used by AI agents as well as by people. The inputs forgive the mistakes models commonly make. Every response says what happened in plain English, and every error says how to fix the request.

## Start with a limited key

An agent's key is its only power, so give it the least it needs. On the [account page](https://tradingapi.dev/account), create a key for the agent alone:

* **Markets**: only the markets it should trade.
* **Max order** and **Max per 24 hours**: amounts you are comfortable losing.

The key cannot withdraw money or change its own limits, whatever the agent does. Revoke it on the account page at any time; it stops working on its next request.

## A loop that works

<Steps>
  <Step title="Learn what the key may do">
    `GET /v1/api_key` returns the key's markets, its maximum order, and how much of its daily limit remains.
  </Step>

  <Step title="Find the market">
    `GET /v1/markets?q=tesla` searches by name, symbol and common aliases. Use the `symbol` it returns in orders.
  </Step>

  <Step title="Preview the order">
    `POST /v1/orders/preview` returns `valid`, every error at once, the estimated fill and the resulting position, without placing anything.
  </Step>

  <Step title="Place the order">
    `POST /v1/orders` with a new `client_order_id`. After a timeout or a `503`, send the identical request again with the same `client_order_id`: it never places a second order.
  </Step>

  <Step title="Read the result">
    Report `summary` to the user. Check `status`, and read any `notes`. If the order is still `pending`, read it again with `GET /v1/orders/{id}`.
  </Step>
</Steps>

## What agents can rely on

* **Forgiving input.** Numbers can be JSON numbers or strings (`25` or `"25.00"`). Enum values can be in any case (`"BUY"`). A field with a near-miss name gets a suggestion: `amount` gives "Did you mean value?".
* **Strict where it matters.** Orders never guess a market. A near miss, such as `TESLA`, is refused with the right symbol suggested.
* **Errors you can act on.** Every error has a `code`, a `message` with the numbers involved, and a `hint` with one concrete fix. When several fields are wrong, all of them are reported at once. See [Handling errors](/guides/errors).
* **Plain-English results.** Orders and positions have a `summary` sentence written for people and models. `notes` point out anything surprising, such as rounding or a flip.
* **A record of intent.** `metadata` on an order stores up to 20 values of the agent's own, such as its reasoning. They are returned with the order, so a person reviewing the account later can see why each trade was made.
* **Nothing ambiguous.** `value` is always US dollars of the asset bought or sold. There is no leverage, so it is also what the order costs.

## A system prompt

Give your agent instructions like these, adjusted to your use:

<Prompt description="System prompt for an agent that trades with the Trading API" actions={["copy"]}>
  You can trade perpetual futures through the Trading API at [https://tradingapi.dev/v1](https://tradingapi.dev/v1), authenticating with the header "Authorization: Bearer \$TRADINGAPI\_KEY". Every order trades real money.

  Rules:

  1. Before trading, call GET /v1/api\_key to learn which markets you may trade and how much remains of your daily limit. Never try to exceed them.
  2. Find markets with `GET /v1/markets?q=NAME`, where NAME is what the user called it. Use the exact symbol returned.
  3. Before every order, call POST /v1/orders/preview with the same body. Place the order only if "valid" is true. If it is false, read each error's "hint" and fix the request.
  4. Place orders with POST /v1/orders. Size them with "value" in US dollars. Create a new, unique client\_order\_id for each new order, and reuse it only to retry that exact request after a timeout or a 503 or 500 error.
  5. After placing an order, report its "summary" to the user. If "status" is "pending", read it again with GET /v1/orders/{id} after a few seconds.
  6. Put your reason for each trade in "metadata", for example `{"reason": "..."}`.
  7. To exit a position, use POST /v1/positions/{symbol}/close.
  8. If an error is not retryable and its hint does not help, stop and tell the user what the error says.
</Prompt>

## Docs for agents

These docs are available in forms agents can read:

* **`/llms.txt`** lists every page, and **`/llms-full.txt`** has all the content in one file.
* **Any page as Markdown**: add `.md` to its URL.
* **`/skill.md`** describes what an agent can do with the Trading API, in the [Agent Skills](https://agentskills.io) format. Install it into your agent:

<Prompt description="Install the Trading API skill into your agent" actions={["copy", "cursor"]}>
  npx skills add [https://docs.tradingapi.dev](https://docs.tradingapi.dev)
</Prompt>

* **The OpenAPI spec** describes every endpoint and field. Download it from the menu at the top of any page, which can also copy the page or open it in Claude, ChatGPT or Cursor.