# API reference

Versioned routed test USDC operations with exact scopes and purchase bindings.

Cleard provider API · 1.4.0 · Base Sepolia test USDC.

## Routing contract

API 1.4.0 uses https://sandbox.cleard.ai/v1/routing. POST bodies are JSON up to 32 KiB. Program and wallet writes require an 8–100 character Idempotency-Key; access issuance and the signed receiver have separate renewal/event-ID semantics. Preserve the exact body/key after uncertain responses. Read operations do not execute transactions.

[Routing OpenAPI](https://cleard.ai/docs/routing-openapi.json): Authoritative request, response, security and required-scope schemas.

| Operation | Authorization | Result |
| --- | --- | --- |
| GET /v1/routing/capabilities | public | Enabled route metadata |
| POST /v1/routing/access | account | Issue seven-day access; revoke prior credential on renewal |
| GET /v1/routing/programs/{program} | records:read | Scoped program and pinned public contract/key metadata |
| POST /v1/routing/programs/{program}/merchants | merchants:write | Create merchant funding authorization and wallet link |
| POST /v1/routing/programs/{program}/merchants/{id}/enrollment | merchants:write | Confirm exact wallet enrollment and personal signature |
| POST /v1/routing/programs/{program}/purchases | purchases:write | Create signed purchase commitment and buyer wallet link |
| GET /v1/routing/programs/{program}/purchases/{id} | records:read | Fresh approved/paid/outstanding and log receipts |
| POST /v1/routing/programs/{program}/purchases/{id}/activate | purchases:write | Bounded registrar offers this exact purchase |
| POST /v1/routing/programs/{program}/purchases/{id}/registration | purchases:write | Confirm direct merchant registration |
| POST /v1/routing/programs/{program}/purchases/{id}/reconcile | purchases:write | Reconcile all affected receipt logs atomically |
| POST /v1/routing/programs/{program}/purchases/{id}/claims | claims:write | Verify beneficiary signature and timely onchain claim |
| POST /v1/routing/programs/{program}/purchases/{id}/decisions | decisions:write | Verify designated reviewer Ed25519 approval |
| POST /v1/routing/programs/{program}/purchases/{id}/refunds | refunds:execute | Record award and collect from the accepted funding source |
| POST /v1/routing/programs/{program}/notifications | purchases:write | Attempt up to five signed HTTP deliveries |
| GET /v1/routing/programs/{program}/notification-receipts | records:read | Read deduplicated signed delivery receipts |
| GET /v1/routing/programs/{program}/transactions | records:read | Read relayer operation IDs and hashes for the client gas budget |
| POST /v1/routing/notification-receiver | signed_event | Accept exact signed outbox event at pinned receiver |

Wallet routes are scoped to /wallet/{program}/{merchant|purchase}/{id}; the OpenAPI lists their exact permitted actions. A confirmed transaction hash must match the bound wallet, contract, calldata and immutable purchase. Arbitrary callback destinations and general-purpose signing are not exposed.