API reference
Use the Cleared REST API to integrate invoicing, customer records, payment reporting, and owner-controlled account management. The API origin is https://api.clearedpay.xyz; endpoints below include the /v1 prefix. Website /api/... routes are browser proxies, not the integration API.
Start with getting started, create an organization, and complete its business profile. Configure API keys for HMAC REST integrations; hosted MCP uses browser OAuth instead. In API responses, an organization is called a studio. Use a test organization for development.
Choose an integration#
| Interface | Use it for |
|---|---|
| REST with HMAC | Backend invoice issuance and cancellation, customer management, reads, and exports |
| REST with Privy JWT | Signed-in user operations and owner-only management |
| MCP | Hosted agent tools with OAuth; local stdio with HMAC is an advanced alternative |
| Repository SDK | TypeScript utilities and selected contract interactions; read the compatibility notes before using transaction methods |
An API key is not a Bearer token and does not grant the ability to sign arbitrary Safe transactions. See the authorization matrix and executable read example.
Endpoint families#
| Family | Current surface | Reference |
|---|---|---|
/v1/invoices | List, detail, issue, prepare/submit, cancel, PDF, email delivery, share links, access tokens | Invoices |
/v1/customers | Create, list, retrieve, update, delete | Customers |
/v1/pay | Public invoice and metadata reads, PDF, payer-signed payment preparation/submission | Payments |
/v1/payments | Received payments and CSV/JSON exports | Payments |
/v1/withdrawals | Prepare and submit an owner-signed withdrawal, list history | Withdrawals |
/v1/studios | Organization, balance, invoice statistics, transactions, quotas, profile, withdrawal destination, Safe provisioning | Management |
/v1/studios/:studioId/api-keys, /signer, /agents, /upgrade-7579 | Owner management and signed Safe lifecycle operations | Management |
/v1/auth | Privy login synchronization and current user | Management |
/v1/accounts/:address/metrics | Authenticated read of public on-chain account aggregates | Below |
/v1/protocol/stats | Public protocol aggregates | Below |
/v1/leads | Public enterprise enquiry submission | Management |
/v1/webhooks/resend | Provider callback for invoice email delivery, not merchant payment webhooks | Webhooks |
The OpenAPI document is available for tooling. Coverage can lag route behavior; consult the endpoint pages for authentication, response-shape, and compatibility details.
Operational probes sit outside /v1: GET /health reports process liveness ({ ok, service, timestamp }); GET /ready checks database/migration readiness; GET /ready/deep checks additional configured dependencies. They are unauthenticated operational endpoints and can return 503 when not ready. A healthy probe does not guarantee a particular invoice operation will succeed.
Identifiers, units, and networks#
- Invoice
idis the numeric on-chain identifier, represented as a decimal string. It is distinct from the merchant's sequentialinvoiceNumberand formatted labels such asINV-2026-000042. Never derive the ID from the printed number. - Customer and studio IDs are UUIDs. An agent-management ID identifies an integration record, not an on-chain issuing address.
- Invoice amounts and payment fee fields are integer strings in USDC base units:
"1000000"means 1 USDC. Usebigintor exact decimal arithmetic. Display strings and exports have different units, documented per endpoint. - Invoice
issuedAt,dueAt,paidAt, date filters, and permit deadlines use Unix seconds. HMAC timestamps use Unix milliseconds. Customer/management database dates and invoice metadata dates use date-time strings. - Authenticated chain-aware routes use the studio's configured Safe chain. Changing a query parameter or an MCP chain setting does not switch that studio's network. Public pay endpoints use the deployment's default chain. Check contract addresses before contract integration.
Invoice lifecycle: Issued becomes either Paid or Canceled. There is no Cleared status. Transaction results such as pending and confirmed describe submission processing, not additional invoice states.
Response handling and consistency#
There is no universal response envelope. Invoice lists use data.items and data.page; customer lists use a data array and meta; server-signed issuance returns top-level fields. Read metadata is generally named metadata, not meta, on hybrid blockchain reads. Keep endpoint-specific parsers.
Invoice reads support eventual, hybrid (default), and strong modes. Eventual reads rely on the indexer; strong reads favor chain state; hybrid reads reconcile according to data availability. Strong mode does not make an indexer-backed list a guaranteed complete view of newly submitted transactions. Inspect returned read metadata and reconcile pending operations separately.
GET /v1/accounts/:address/metrics accepts HMAC or JWT and returns { data, metadata }. The address must be an EVM address. It intentionally permits querying any address's public on-chain aggregates, not private customer metadata. Volume fields are raw integer strings.
GET /v1/protocol/stats needs no authentication and returns { data, metadata }. Pass chainId=8453 (Base) or chainId=84532 (Base Sepolia); without it the route uses the deployment's default chain, which is Base on api.clearedpay.xyz. data.chain names the chain the totals belong to, and data.fees carries the live retail rate and cap read from the registry. Quote-related fields in historical aggregate schemas do not imply a current quote API.
For 202, timeouts, idempotency, and error envelopes, read errors and retries. Review known limitations before production integration.