WarpCore API Reference

A concise human reference for the WarpCore HTTP API. The typed contract is openapi.yaml (OpenAPI 3.1.0) at the repository root — that spec is the source of truth. If this document and the spec disagree, the spec wins.

Base URL & versioning


Development base URL	`http://localhost:3000`
API prefix	`/v1` (operational probes and metrics are unversioned)
Spec version	OpenAPI 3.1.0

The spec currently declares 160 paths (router↔spec parity enforced by tests/openapi_drift.rs) across the resource groups below. Run grep -cE '^ /' openapi.yaml for the live path count rather than trusting any number quoted in prose.

Authentication

Every authenticated endpoint expects an Authorization: Bearer <token> header. The token is one of:

JWT — signed with RS256 (the production key scheme) or HS256 (dev only), carrying a kid header for key rotation and the claims sub, role, exp, iat. Obtain one from POST /v1/auth/token.
- Production boot refuses to start with HS256 only. If production RSA JWT keys are present-but-invalid, the service refuses to boot rather than silently downgrading to HS256.
- POST /v1/auth/token with username/password is dev-mode only: it issues a token for any credentials only when auth is disabled. In production this username/password path is rejected; obtain tokens via an API key instead.
API key — of the form wk_live_ + hex, passed directly as the bearer token. Keys are stored only as SHA-256 hashes (the raw key is never persisted) and each carries an RBAC role, an optional per-key rate limit, an optional HMAC signing secret, and an optional expiry.

RBAC roles

Role	Capability
`admin`	Full system administration
`operator`	Submit and track payments
`compliance`	Compliance checks, proofs, hold/release
`auditor`	Read-only audit-log access
`readonly`	Status queries only

A missing or invalid token yields 401 (UNAUTHORIZED / AUTHENTICATION_FAILED); a valid token with an insufficient role yields 403 (FORBIDDEN / AUTHORIZATION_DENIED).

Error model

Every error response is a JSON body carrying a machine-parseable, stable error_code string alongside a human-readable message. Clients should branch on error_code and the HTTP status, never on message text.

HTTP status semantics

The status code is derived deterministically from the typed error (WarpCoreError::http_status). The mapping callers most need to handle:

Status	Meaning	Representative error codes
400	Malformed request / bad input	`INVALID_IDEMPOTENCY_KEY`, validation codes (`INVALID_BIC`, `INVALID_CURRENCY`, …)
401	Missing / invalid credentials	`UNAUTHORIZED`, `AUTHENTICATION_FAILED`
403	Authenticated but insufficient role	`FORBIDDEN`, `AUTHORIZATION_DENIED`
404	Resource not found	`PAYMENT_NOT_FOUND`, `INSTITUTION_NOT_FOUND`, `DTI_NOT_FOUND`, `CBDC_NOT_FOUND`, `DB_NOT_FOUND`, `NOT_FOUND`
409	Conflict (duplicate / constraint)	`DUPLICATE_PAYMENT`, `DUPLICATE_ENTRY`, `DB_CONSTRAINT_VIOLATION`
410	Resource expired	`EXPIRED`
422	Business-rule rejection	`COMPLIANCE_REJECTED`, `INSUFFICIENT_BALANCE`, `INSUFFICIENT_RESERVES`, `HOLDING_LIMIT_EXCEEDED`, `INVALID_AMOUNT`, `MBRIDGE_FX_RATE_UNAVAILABLE`, `MBRIDGE_RATE_LOCK_EXPIRED`
429	Queue saturated	`QUEUE_FULL`
502	Upstream (mBridge) failure	`MBRIDGE_CONNECTION_FAILED`, `MBRIDGE_SETTLEMENT_FAILED`
503	Transient DB unavailability (retry may succeed)	`DB_CONNECTION_ERROR`
500	Uncategorised internal fault	`INTERNAL_ERROR`, `DATABASE_ERROR`

Structured database errors

Persistence failures are mapped to typed errors rather than collapsing to an opaque 500:

RowNotFound → DB_NOT_FOUND → 404
unique / foreign-key / exclusion constraint → DB_CONSTRAINT_VIOLATION → 409
pool timeout / connection drop / IO / TLS / closed → DB_CONNECTION_ERROR → 503 (transient — safe to retry)
anything else → DATABASE_ERROR → 500

error_code taxonomy (selected)

error_code values are stable, screaming-snake-case identifiers. Grouped by domain (see crates/warpcore-models/src/error.rs for the exhaustive list):

Message / standards validation: XSD_VALIDATION_FAILED, CBPR_PLUS_VIOLATION, UNSUPPORTED_MESSAGE_TYPE, MESSAGE_PARSING_FAILED, INVALID_BIC, INVALID_LEI, INVALID_IBAN, INVALID_DTI, INVALID_UETR, INVALID_CURRENCY, INVALID_COUNTRY, INVALID_ROUTING_NUMBER, FEDNOW_VALIDATION_FAILED, INVALID_SORT_CODE, CHAPS_VALIDATION_FAILED, INVALID_ISIN.
Compliance: SANCTIONS_HIT, COMPLIANCE_REJECTED, TRAVEL_RULE_NOT_SATISFIED, KYC_CHECK_FAILED.
Zero-knowledge proofs: ZKP_PROOF_GENERATION_FAILED, ZKP_VERIFICATION_FAILED, VPROGS_NOT_AVAILABLE.
Kaspa settlement: KASPA_CONNECTION_FAILED, KASPA_SUBMISSION_FAILED, COVENANT_COMPILATION_FAILED, INSUFFICIENT_UTXOS, CONFIRMATION_TIMEOUT, NETWORK_MISMATCH.
mBridge / settlement: MBRIDGE_CONNECTION_FAILED, MBRIDGE_SETTLEMENT_FAILED, MBRIDGE_FX_RATE_UNAVAILABLE, MBRIDGE_RATE_LOCK_EXPIRED, SETTLEMENT_ROUTING_FAILED.
Payment lifecycle: INVALID_STATE_TRANSITION, PAYMENT_NOT_FOUND, DUPLICATE_PAYMENT.
Platform / business: INSUFFICIENT_BALANCE, INSUFFICIENT_RESERVES, HOLDING_LIMIT_EXCEEDED, OPERATION_REJECTED, EXPIRED, DUPLICATE_ENTRY, INVALID_AMOUNT, RATE_UNAVAILABLE, NETTING_ERROR, QUEUE_FULL, CREDENTIAL_INVALID, BRIDGE_ERROR.
Infrastructure: DATABASE_ERROR, DB_NOT_FOUND, DB_CONSTRAINT_VIOLATION, DB_CONNECTION_ERROR, CONFIGURATION_ERROR, AUTHENTICATION_FAILED, AUTHORIZATION_DENIED, NOT_FOUND, INTERNAL_ERROR.

Idempotency

POST /v1/payments accepts an optional Idempotency-Key request header.

The key may be at most 256 characters; longer values are rejected with 400 INVALID_IDEMPOTENCY_KEY.
A first submission claims the key (atomically, via an INSERT … ON CONFLICT reservation keyed on the payment’s pre-generated UUID, so a concurrent duplicate cannot create an orphan payment row).
A repeat submission with the same key returns the original payment with HTTP 200 instead of creating a duplicate.
Keys expire after 24 hours.

The reservation store is PostgreSQL-backed in durable mode (restart-safe and horizontally safe) and an in-memory map in development.

Money & precision

All monetary amounts are exact decimals (rust_decimal::Decimal), never IEEE floats. On the wire they are JSON numbers/strings with up to 8 fractional digits; the database stores them as NUMERIC(30,8) (FX rates as NUMERIC(20,10)).

Compliance & travel rule

Compliance pre-flight runs sanctions screening, risk scoring, and ZKP proof generation. The FATF Recommendation 16 Travel Rule obligation defaults to the conservative ~USD 1,000 floor; per-jurisdiction deviations are configurable but counsel-gated. Travel-rule data is required on a payment whose USD-equivalent amount meets the configured threshold; a missing payload yields TRAVEL_RULE_NOT_SATISFIED.

Resource groups

The API is grouped by the OpenAPI tags. Below is an orientation map; consult openapi.yaml for the exact request/response schemas of each operation.

Operational (unauthenticated probes)

Path	Purpose
`GET /health`	Liveness probe
`GET /ready`	Readiness probe
`GET /startup`	Startup probe (orchestrator-friendly)
`GET /metrics`	Prometheus exposition (text) — see Observability
`GET /v1/metrics`	Richer JSON metrics view (JWT-gated)

Authentication

Path	Purpose
`POST /v1/auth/token`	Exchange credentials (dev) or an API key for a JWT

Payments (core ISO 20022 lifecycle)

Path	Purpose
`POST /v1/payments`	Submit an ISO 20022 message (pacs.008/pacs.009/pain.001…)
`GET /v1/payments`	List / query payments
`GET /v1/payments/{payment_id}`	Fetch a payment
`GET /v1/payments/{payment_id}/proof`	Retrieve the ZKP compliance proof
`GET /v1/payments/{payment_id}/report`	Settlement report
`GET /v1/payments/{payment_id}/status-report`	pacs.002-style status report
`POST /v1/payments/{payment_id}/cancellation`	Request cancellation
`GET /v1/payments/{payment_id}/spv-proof`	SPV inclusion proof
`POST /v1/payments/batch`, `GET /v1/payments/batch/{batch_id}`	Batch submission & status

Compliance

POST /v1/compliance/preflight (KYC/AML pre-flight + sanctions screening), POST /v1/compliance/uca, and the regulatory-filing helpers POST /v1/compliance/str (suspicious-transaction report) and POST /v1/compliance/ctr (currency-transaction report).

Blockchain / DTI

GET /v1/blockchain/status (Kaspa connectivity & DAA) and GET /v1/dti/{dti} (ISO 24165 Digital Token Identifier lookup).

Institutions & beneficiaries

GET /v1/institutions, GET/POST/DELETE /v1/beneficiaries, GET /v1/beneficiaries/{bic} — the BIC → Kaspa-address routing registry.

Audit

GET /v1/audit/log (tamper-evident hash-chained log) and POST /v1/audit/verify (chain-integrity verification).

mBridge (cross-border CBDC settlement)

GET /v1/mbridge/status, …/rates, …/rates/{source}/{target}, POST …/rates/lock, GET …/participants, GET …/balance/{currency}. These return MBRIDGE_NOT_CONFIGURED when no mBridge connector is wired.

CBDC

The classic token-management surface under /v1/cbdc (issue-by-DTI, mint, burn, distributors, supply, freeze, unfreeze) plus the platform-engine surface (see below).

Privacy & analytics

POST /v1/privacy/seal, POST /v1/privacy/open, POST /v1/analytics/liquidity-sim, POST /v1/settlement/pvp/build-plan, and the settlement fan-out / pool helpers under /v1/settlement/*.

Platform engines (`/v1/platform/*`)

WarpCore exposes 13 platform engines, each backed by a durable PostgreSQL store. Representative endpoints per engine:

Engine	Representative endpoints
CBDC	`cbdc/issue`, `cbdc/mint`, `cbdc/burn`, `cbdc/attest`, `cbdc/reserves`, `cbdc/sweep`, `cbdc/interest/calculate`, `cbdc/holding-limits/{did}`, `cbdc/islamic/{template}`
Liquidity	`liquidity/positions`, `liquidity/netting/start`/`confirm`/`{cycle_id}`, `liquidity/pool/status`/`contribute`/`withdraw`, `liquidity/credit/draw`/`repay`, `liquidity/nostro/fund`/`balance`
FX	`fx/quote`, `fx/pvp`, `fx/pvp-lock`, `fx/order`, `fx/netting/start`/`{cycle_id}`, `fx/ndf-fixing`, `fx/rates`, `fx/exposure`, `fx/windows`
RTGS	`rtgs/submit`, `rtgs/queue`, `rtgs/participants`, `rtgs/gridlock/resolve`, `rtgs/lsm/run`
Exchange	`exchange/order`, `exchange/order/{id}/cancel`, `exchange/orderbook/{pair}`, `exchange/trades/{pair}`, `exchange/surveillance/alerts`
Trade Finance	`trade/lc/create`, `trade/lc/{lc_id}/present`, `trade/bol/tokenise`, `trade/invoice/finance`
Programmable	`programmable/escrow`, `programmable/stream`, `programmable/split`, `programmable/conditional`, `programmable/{id}`, `programmable/{id}/release`, `programmable/{id}/clawback`
Identity	`identity/register`, `identity/directory`, `identity/{did}`, `identity/verify`, `identity/agreement`
Reconciliation	`recon/match`, `recon/exceptions`, `recon/report`, `recon/zkp-verify`
Reporting	`reporting/generate`, `reporting/schedule`, `reporting/list`, `reporting/file`
Bridge	`bridge/transfer`, `bridge/{id}`, `bridge/{id}/claim`, `bridge/{id}/refund` (cross-chain HTLC)
Orchestration	`orchestration/batch`, `orchestration/standing-order`, `orchestration/direct-debit/mandate`, `orchestration/schedule`
Securities	see below

Securities (`/v1/platform/securities`)

Tokenised-securities registry plus the settlement-fails lifecycle: securities/register, GET /v1/platform/securities, securities/{isin}, securities/{isin}/deactivate, securities/fails, securities/fails/{fail_id}, securities/fails/{fail_id}/retry, securities/fails/{fail_id}/partial, plus message parsers securities/mt/parse and securities/fix/parse.

Regional adapters (`/v1/regional/*`)

Five regional compliance/routing adapters, each exposing the same four-endpoint shape:

POST /v1/regional/{region}/payment/route
POST /v1/regional/{region}/compliance/verify
GET  /v1/regional/{region}/compliance/rules/{region}
GET  /v1/regional/{region}/payment/{payment_id}/status

Regions: mena, sghk (Singapore / Hong Kong), brics, asean, africa.

Observability

GET /metrics is Prometheus text exposition (intentionally unauthenticated so in-cluster scrapers can reach it; the richer JSON view at GET /v1/metrics is JWT-gated). The emitted metric set (the only real metrics — see crates/warpcore-api/src/observability.rs):

Metric	Type
`warpcore_http_requests_total`	counter
`warpcore_http_request_duration_ms`	histogram
`warpcore_active_connections`	gauge
`warpcore_payments_total`	counter
`warpcore_payment_duration_ms`	histogram
`warpcore_payment_state_transitions_total`	counter
`warpcore_compliance_checks_total`	counter
`warpcore_compliance_duration_ms`	histogram
`warpcore_sanctions_screened_total`	counter
`warpcore_blockchain_submissions_total`	counter
`warpcore_blockchain_submission_duration_ms`	histogram
`warpcore_kaspa_daa_score`	gauge
`warpcore_regional_requests_total`	counter
`warpcore_regional_request_duration_ms`	histogram

Requests are also trace-correlated by UETR on the request span. SLO burn-rate alerts and a ServiceMonitor ship with the ops manifests.

SDKs

Client SDKs are tracked against openapi.yaml; the spec is authoritative.

Language	Location	Quickstart
TypeScript	`sdks/typescript/`	`README`
Python	`sdks/python/`	`README`
Rust	`sdks/rust/`	`README`
Java (hand-maintained)	`sdks/java/`	—

Cross-cutting concerns shared by every SDK (auth, retries, idempotency, error handling) are documented in sdks/INTEGRATION.md.

API Reference

WarpCore API Reference

Base URL & versioning

Authentication

RBAC roles

Error model

HTTP status semantics

Structured database errors

error_code taxonomy (selected)

Idempotency

Money & precision

Compliance & travel rule

Resource groups

Operational (unauthenticated probes)

Authentication

Payments (core ISO 20022 lifecycle)

Compliance

Blockchain / DTI

Institutions & beneficiaries

Audit

mBridge (cross-border CBDC settlement)

CBDC

Privacy & analytics

Platform engines (/v1/platform/*)

Securities (/v1/platform/securities)

Regional adapters (/v1/regional/*)

Observability

SDKs

Platform engines (`/v1/platform/*`)

Securities (`/v1/platform/securities`)

Regional adapters (`/v1/regional/*`)