Conventions#

The public Agent API is served from:

https://api.hightop.com

Agent API v1 routes live under /v1/agent/*. Endpoint examples on these pages use that host unless noted otherwise.

Response Envelopes#

Successful responses include ok: true.

{
  "ok": true
}

Write responses create an AgentOperation and return the operation id, current status, affected resource, and fee.

{
  "ok": true,
  "operation_id": "00000000-0000-0000-0000-000000000000",
  "status": "submitted",
  "resource": {
    "type": "operation",
    "id": "00000000-0000-0000-0000-000000000000"
  },
  "fee_usd": "0"
}

Errors use:

{
  "ok": false,
  "error": {
    "code": "validation_failed",
    "message": "Request body is invalid."
  }
}

Branch on error.code first. Treat error.details, error.remediation, and additive response fields as optional.

Amounts#

For Agent API v1 amount fields, decimal strings are asset-unit amounts unless a field name explicitly says USD.

{
  "asset": "USDC",
  "amount": "1"
}

In that example, "1" means 1 USDC. Fields named amount_usd, fee_usd, balance_usd, and similar are USD-denominated decimal strings.

Several write schemas accept either amount or amount_usd, but not both. The endpoint cards call that out where it applies.

Pagination#

List endpoints use forward-only pagination.

?cursor=<cursor>&limit=50

The default limit is 50. The maximum accepted limit is 100.

Paginated responses use:

{
  "ok": true,
  "items": [],
  "next_cursor": null,
  "has_more": false
}

Request Body Limit#

Agent API requests reject bodies larger than 64 KB.

Idempotency#

Most POST, PATCH, and DELETE requests require an Idempotency-Key header.

Exceptions:

• POST /v1/agent/simulate
• POST /v1/agent/recipients/resolve

POST /v1/agent/conversions/quote does require idempotency because it creates a short-lived server-side quote.

Keys must be nonblank and no longer than 200 characters.

Idempotency-Key: payment-<uuid>

Use one key per logical mutation. If the network result is unknown, retry the same method, path, body, and key.

Hightop stores completed idempotency responses for 24 hours. A replay with the same method, path, validated body, and key returns the original stored response and sets:

X-Idempotency-Replayed: true

Important details:

• The comparison uses the server-validated payload, not raw request bytes.
• Object key order does not matter.
• Fields stripped by validation are not part of identity.
• Fields rejected by validation fail before idempotency resolution.
• Replays count against rate limits.
• Rate-limited requests do not create idempotency records.
• Reusing a key with a different method, path, or body returns idempotency_key_reuse_mismatch.
• A concurrent duplicate while the first request is still running returns idempotency_request_in_progress.

Rate Limits#

Responses include:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset
X-RateLimit-Window-Seconds

Default rate-limit classes:

X-RateLimit-Limit reports the effective limit plus burst for the current window.

Protective Caps#

Agent API v1 also enforces per-agent growth caps:

Cap rejects return limit_exceeded.

Versioning#

Clients should:

• tolerate unknown enum values
• ignore additive response fields
• keep handling reserved errors and events even if current v1 routes do not emit them

Reserved v1 error codes may become emitted without a v2:

• cooldown_active
• timelock_not_elapsed
• rule_changed_during_execution
• batch_step_failed