Overview

One base URL, one version prefix, and one error envelope — and every amount on the wire is an integer string of the asset's smallest unit.

https://api.gowarrant.xyz/v1

Amounts, before anything else

This is the single thing most likely to break a first integration:

"8400000"    8.40 USDC
8400000      rejected — a JSON number
"8.40"       rejected — not the smallest unit

Validated against ^[0-9]+$. A JSON number would silently lose precision as a double past 2^53, and this is a payments API. The decimal point is a display concern and lives in the console.

The surface

Section	What it covers
Authentication	API keys for agents, sessions for people.
Idempotency	Required on every money-moving POST.
Errors	The envelope and the codes.
Rate limits	600 reads, 60 writes, per minute.
Warrants	The whole money surface.
Verifiers	The eight clause kinds.
Policies	Bands and overrides.
Agents	Read-back only.
Sessions	Enforced, with no API of its own.
Webhooks	Five events, HMAC-signed.
Pagination	Cursor or offset, depending on sort.

What is public, and what is not

Of the 49 routes mounted, most are not a public API and this reference does not pretend otherwise:

/v1/warrants/* is the public API. Agents and people both use it.
/v1/console/* serves the console. Session-authenticated, viewer and up, and an API key cannot call it. Read-backs only — there is no CRUD for agents, policies, verifiers or webhooks over HTTP.
/auth/* is the sign-in flow for a person.
/internal/* and /telegram/webhook are worker surfaces behind a shared secret. Not for callers.
/t/:id, /bench/run, /health and / need no caller.

Where something is not built, the page for it says so rather than being left out. Sessions has no endpoints at all, and its page says that in the first line.

Versioning

/v1 is the only version. A breaking change gets /v2; /v1 will not change shape underneath you.

Additive changes — a new field on a response, a new optional request field, a new error code — can arrive at any time. Parse permissively: ignore fields you do not recognise, and do not fail on an unknown code.

Every response

Success bodies carry an object field naming the type: "warrant", "list", "push_subscription". Errors are always:

{
  "error": {
    "type": "invalid_request",
    "code": "deadline_in_past",
    "message": "A warrant deadline must be in the future.",
    "doc_url": "https://docs.gowarrant.xyz/api-reference/errors#deadline_in_past",
    "request_id": "req_537c915a-c1dd-4625-93a2-21fa7ec5d938"
  }
}

Branch on code. Every response, error or not, carries X-Request-Id; send your own and it is echoed rather than replaced.

Environments

Key prefixes decide the environment and nothing else does:

wr_test_...   sandbox
wr_live_...   production

A wr_live_ key presented against a sandbox organisation resolves to no principal at all, which is a 401 rather than a 403 — there is nobody to refuse.