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:

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:

{
  "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 for key policy and Realtime for WebSocket recovery.

​REST API overview

​Request conventions

​Pagination and consistency

​Indexed and live sources

​Idempotent writes

​Receipt capabilities

​Errors

Authentication and limits