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

# API reference

> Base URL, authentication, and the conventions every endpoint follows.

## Base URL

```text theme={"system"}
https://tradingapi.dev/v1
```

Everything is JSON over HTTPS. Send `Content-Type: application/json` with every request body.

## Authentication

Send an API key from the [account page](https://tradingapi.dev/account) as a bearer token:

```bash theme={"system"}
curl https://tradingapi.dev/v1/api_key \
  -H "Authorization: Bearer tapi_..."
```

A missing, unknown or revoked key gets `401`. A key's limits apply to every order it places; see [API keys and limits](/concepts/api-keys).

## Requests

* **Decimals** can be strings or JSON numbers: `"value": "25.00"` and `"value": 25` are the same. We read the number exactly as written, so nothing is lost to floating point.
* **Enum values** are case-insensitive: `"buy"` and `"BUY"` are the same.
* **Market symbols** are case-insensitive: `btc` is `BTC`.
* **Unknown fields are refused**, with a suggestion when the name is close to a real one. A typo never goes unnoticed.

## Responses

* **Every object has an `object` field** naming its type: `market`, `order`, `order_preview`, `position`, `fill`, `account`, `api_key`, `withdrawal` or `list`.
* **Decimals are strings**, so no precision is lost: `"84012.4"`. USD amounts have two decimal places (`"248.68"`), except `fee`, which is exact to six. Prices and sizes are exact.
* **Times** are RFC 3339 in UTC with milliseconds: `"2026-09-27T14:30:00.123Z"`.
* **Missing values are `null`**, never omitted. Every field in an object's schema is always present.
* **Enum values** are lower case.

## Lists

Lists share one shape:

```json theme={"system"}
{
  "object": "list",
  "data": [ ... ],
  "next_cursor": "c2Vx..."
}
```

Results are newest first. Pass `?limit=` (1 to 100, default 50) and, for the next page, `?cursor=` with the `next_cursor` you received. When `next_cursor` is `null`, there are no more results. Markets and positions are short lists and are never paged.

## Expanding

Some objects have extra detail you can ask for with `expand[]`. Orders take `expand[]=timeline`:

```bash theme={"system"}
curl "https://tradingapi.dev/v1/orders/ord_7kq2m4x9h3v8r5t2w6y4n8p3za?expand[]=timeline" \
  -H "Authorization: Bearer $TRADINGAPI_KEY"
```

## Idempotency

Placing an order and closing a position both require a `client_order_id`. Sending the same request with the same `client_order_id` never creates a second order: you get the first one back with `200` and `Idempotent-Replayed: true`. A new order returns `201`. See [Retries and idempotency](/guides/retries).

## Waiting for a result

Placing an order waits up to 5 seconds for it to finish, so the response is almost always final. Change the wait with the `Prefer` header, from 0 to 15 seconds:

```bash theme={"system"}
curl https://tradingapi.dev/v1/orders \
  -H "Authorization: Bearer $TRADINGAPI_KEY" \
  -H "Prefer: wait=0" \
  ...
```

The response's `Preference-Applied` header says which wait was used.

## Status codes

| Status | Meaning |
| - | - |
| `200` | Success. For orders: an earlier, identical request's order (`Idempotent-Replayed: true`). |
| `201` | An order was created. Read `status` for the outcome. |
| `400` | The request is invalid. Nothing was recorded. |
| `401` | The API key is missing, wrong or revoked. |
| `403` | The key's limits refuse the request. |
| `404` | The market, order, position or endpoint does not exist. |
| `409` | The `client_order_id` names a different order, or the account can't trade. |
| `422` | The request is valid, but your balance or position doesn't allow it. |
| `429` | The key made too many requests. Retry after `retry_after`. |
| `500` | Something failed on our side. Retry with the same `client_order_id`. |
| `503` | A service we depend on failed. Retry with the same `client_order_id`. |

Every error has the same body; see [Errors](/api-reference/errors).

## Compatibility

`/v1` changes only in ways that don't break correct clients. We may add:

* new endpoints, and new optional request fields;
* new fields in responses;
* new values in enums, such as order statuses, error codes and note codes.

Write clients that ignore fields they don't know, and treat an unknown status as not final. A breaking change would come as a new version, `/v2`, with notice.