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

# REST API overview

> Understand Tayho REST conventions, pagination, idempotent submission, receipts, and response metadata.

# REST API overview

The Tayho API is the supported application boundary for indexed reads, live unsigned calculations,
relayed writes, and realtime ticket issuance.

| Environment | Base URL                       |
| ----------- | ------------------------------ |
| Development | `https://api.testnet.tayho.io` |
| Production  | Not deployed                   |

Do not infer or construct a production hostname. Until Tayho publishes one, the SDK requires an
explicit `apiUrl` for `environment: "production"`. Read `GET /v1/config` before relying on a
deployment feature.

## Request conventions

Send JSON request bodies with `Content-Type: application/json`. Integers that map to EVM integer
types are encoded as unsigned decimal strings in raw REST payloads. The SDK converts supported
numeric response fields to `bigint`.

Every authenticated request sends:

```http theme={null}
X-API-Key: th_pk_example
Accept: application/json
```

You may supply `X-Request-ID` using 8–128 letters, digits, dots, underscores, colons, or hyphens.
Otherwise the API generates one. The resulting `x-request-id` is the correlation value to include
in a support request.

## Pagination and consistency

List endpoints accept the query parameters shown in their generated operation reference. A
response can contain:

```json theme={null}
{
  "data": [],
  "cursor": "opaque-next-page-token",
  "checkpoint": "123456",
  "requestId": "request-12345678"
}
```

* Treat `cursor` as opaque. Pass it back unchanged only to the same operation and filter set.
* A missing or `null` cursor means there is no next page.
* `checkpoint` identifies the indexed chain boundary represented by the response. It can be `null`
  before an indexed checkpoint is available.
* Do not compare cursors or construct one from IDs.

Endpoint-specific maximum page sizes are enforced at the API boundary. The generated operation
reference is authoritative.

## Indexed and live sources

Responses can include `x-tayho-source`:

| Value        | Semantics                                     |
| ------------ | --------------------------------------------- |
| `indexed`    | Canonical indexed chain history or projection |
| `automation` | Current automatic-order lifecycle             |
| `live`       | Block-pinned unsigned RPC calculation         |

Live quote, risk, simulation, and action-preparation reads can fail independently of indexed
history. A live response is not a transaction guarantee; preparation still validates bounds and the
relayer still executes against current chain state.

## Idempotent writes

Relayed action, intent, batch-intent, and cancellation operations require an
`Idempotency-Key`. Use 8–128 safe characters and keep the same value with the same signed body.

The SDK creates one key per prepared action or order and reuses both the signed envelope and key
when `submit()` is called again. If a transport failure is ambiguous, retry the same prepared
object. Do not prepare a replacement just to retry.

An accepted order can report `duplicate: true`; this means the existing submission was recovered.
It does not mean another order was created.

## Receipt capabilities

Action and intent intake returns a status identifier plus a receipt capability. Status calls must
send that receipt exactly as returned. Treat it as sensitive application state:

* do not log it in analytics or place it in a public URL;
* do not share it between users;
* keep it available until the lifecycle is terminal; and
* use it for protected realtime `action:` or `intent:` channels when needed.

A missing, invalid, or mismatched capability does not grant status access.

## Errors

Public failures use an HTTP status plus a stable lowercase code where available. Responses can also
include `retry-after`, `x-ratelimit-limit`, and `x-ratelimit-scope`.

* Correct `400`/`422` validation failures before retrying.
* Correct `401` credentials and `403` scope/restriction failures.
* Back off after `429` for at least `Retry-After`.
* Retry safe reads after `502`/`503` with bounded exponential backoff.
* Retry signed submissions only with the original body and idempotency key.

See [Authentication and limits](/public/reference/authentication-and-limits) for key policy and
[Realtime](/public/reference/realtime) for WebSocket recovery.