API overview

The Qustody API is a JSON over HTTPS API. Every endpoint accepts and returns application/json and is versioned under /v1. The full machine-readable spec is available at /api-reference/openapi.json and is rendered at API reference.

Base URL

https://api.your-qustody-host.example

Set CUSTODY_ENV=production to enforce HTTPS for tenant URLs and webhook endpoints. Development environments may use HTTP.

Resource families

Family	Path prefix	What it manages
Tenants	`/v1/tenants`	Tenant accounts (multi-tenant deployments)
Vaults	`/v1/vaults`	Logical groupings of wallets
Wallets	`/v1/wallets`	Quantum Chain addresses with registered post-quantum public keys
Transactions	`/v1/transactions`	Outbound transfers, lifecycle, signing payloads
Approvals	`/v1/transactions/{id}/approvals`	Multi-approver workflow
Policies	`/v1/policies`	Spending limits, whitelists, approval rules
Webhooks	`/v1/webhooks`	Outbound event delivery
Assets	`/v1/assets`	Token metadata for QRC-20 and native assets
Users	`/v1/users`	Human users (when SSO is enabled)
Roles	`/v1/roles`	RBAC role definitions and assignments
Credentials	`/v1/credentials`	API keys, rotation, revocation
Audit	`/v1/audit`	Tamper-evident audit log
Compliance	`/v1/compliance`	AML screenings and travel-rule data

Authentication

All non-public endpoints require authentication. Two modes are supported.

API key

curl "$BASE_URL/v1/wallets" \
  -H "Authorization: Bearer $API_KEY"

API keys are created with POST /v1/credentials and scoped to a tenant. Rotate with POST /v1/credentials/rotate.

SSO (OIDC)

Enabled with CUSTODY_SSO_ENABLED=true. Exchange your IdP token for a Qustody access token at POST /v1/auth/login, then send it in the Authorization: Bearer header. Refresh with POST /v1/auth/refresh.

Idempotency

Every mutating endpoint accepts an Idempotency-Key header. Duplicate requests with the same key within 24 hours return the original response without re-executing.

curl -X POST "$BASE_URL/v1/transactions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: 6a8b8b3e-77d0-4f60-9a18-6f4d3e3e1f3a" \
  -H "Content-Type: application/json" \
  -d '{ "wallet_id": "...", "to_address": "0x...", "value": "1000000000000000000" }'

Use a UUIDv4 per logical operation. Reusing keys across different requests is an error.

Pagination

List endpoints use cursor-based pagination:

curl "$BASE_URL/v1/transactions?limit=50&cursor=eyJpZCI6Li4ufQ==" \
  -H "Authorization: Bearer $API_KEY"

{
  "items": [...],
  "next_cursor": "eyJpZCI6Li4ufQ==",
  "has_more": true
}

When has_more is false, next_cursor is null. limit defaults to 50 and may not exceed 200.

Filtering and sorting

Common query parameters:

Param	Type	Notes
`status`	string	Filter transactions by state (e.g. `PENDING_SIGNATURE`)
`wallet_id`	uuid	Scope to one wallet
`vault_id`	uuid	Scope to one vault
`created_after`, `created_before`	RFC3339	Time range
`sort`	string	`created_at:desc` (default) or `created_at:asc`

Rate limits

Default rate limit is 120 requests per minute per API key with a burst of 20. Configurable via CUSTODY_RATE_LIMIT_RPM and CUSTODY_RATE_LIMIT_BURST. When exceeded, the API returns 429 Too Many Requests with Retry-After header.

HTTP/1.1 429 Too Many Requests
Retry-After: 12

For multi-replica deployments, configure a Redis backend with CUSTODY_RATE_LIMIT_REDIS_URL so limits are enforced cluster-wide.

Standard response shape

Successful single-resource responses return the resource directly:

{
  "id": "...",
  "status": "SUBMITTED",
  "created_at": "2024-..."
}

List responses are wrapped:

{
  "items": [ /* ... */ ],
  "next_cursor": "...",
  "has_more": true
}

Error envelope

All errors return:

{
  "error": {
    "code": 1404,
    "type": "not_found",
    "message": "Wallet not found",
    "request_id": "req_01HXYZ..."
  }
}

The full code catalog is at Errors and codes.

Standard headers

Header	Direction	Purpose
`Authorization: Bearer <token>`	Request	Authentication
`Idempotency-Key: <uuid>`	Request (mutating)	Safe retries
`X-Request-ID`	Response	Trace ID; quote it in support requests
`Retry-After`	Response (429, 503)	Seconds to wait before retrying
`X-Webhook-ID`, `X-Webhook-Timestamp`, `X-Webhook-Signature`	Webhook delivery	HMAC-SHA256 verification

Versioning

The API is versioned in the URL path (/v1). Breaking changes ship as /v2 with a deprecation period announced in the changelog. Additive changes (new fields, new endpoints) are released within /v1.

Health

Endpoint	Auth required	Purpose
`GET /healthz`	No	Liveness
`GET /readyz`	No	Readiness (DB + signer)
`GET /metrics`	No (port 9090)	Prometheus metrics

Getting started

Concepts

Qustody platform

Token management

Reference

Development

Base URL

Resource families

Authentication

API key

SSO (OIDC)

Idempotency

Filtering and sorting

Rate limits

Standard response shape

Error envelope

Standard headers

Versioning

Health

​Base URL

​Resource families

​Authentication

​API key

​SSO (OIDC)

​Idempotency

​Pagination

​Filtering and sorting

​Rate limits

​Standard response shape

​Error envelope

​Standard headers

​Versioning

​Health

​Related

Base URL

Resource families

Authentication

API key

SSO (OIDC)

Idempotency

Pagination

Filtering and sorting

Rate limits

Standard response shape

Error envelope

Standard headers

Versioning

Health

Related