Known limitations

These limitations affect current integrations. They distinguish implemented routes and utilities from planned features and incompatible legacy interfaces. Deployment configuration can further limit available chains, sponsorship, and email delivery.

Authorization and management#

  • Granular HMAC API-key scopes are not consistently enforced on legacy routes. Customer routes, /studios/me reads, server-signed invoice writes, core invoice reads, and invoice email routes check granular scopes; prepare/submit routes, share-token mutations, payment/export/withdrawal routes, and account metrics retain legacy behavior. They still require their documented authentication/ownership/signature checks. Do not treat a read-labeled HMAC key as an API-wide read-only sandbox. CLI OAuth is separately allowlisted to explicitly scoped routes and does not inherit those legacy surfaces. See the authorization matrix.
  • This scope gap does not grant an API key owner-signing authority for withdrawals. The invoice server signer is restricted to invoice operations; withdrawals need valid Safe-authorized signatures.
  • Unlinking an agent's key does not revoke it. Disable the linked agent or revoke the credential as appropriate. Signer force revocation is database-only and leaves the on-chain session installed.
  • Activity is sampled. Key-use logging is approximately 10% and asynchronous, not a complete audit. Listed key active status does not by itself prove the key is unexpired or write-ready.

Issuance, indexing, and responses#

  • Invoice creation supports Idempotency-Key; preserve the same business inputs, using either a fixed dueAt or relative dueDays. This is not a universal idempotency guarantee for every mutation.
  • A crash before the receipt hash is stored can require manual reconciliation. The server refuses to rebuild an operation with an unknown submission outcome. Legacy pending operations may lack metadata recovery context. Never create another invoice solely because an ID/share link is missing. See retries.
  • Indexer-backed lists can lag confirmed chain state. Strong reads of known IDs help, but are not a guarantee that a list is complete.
  • Response envelopes differ by endpoint. Invoice lists use data.items, customers use a data array plus meta, and issuance returns top-level fields. Error codes can be in either code or error. OpenAPI coverage can lag behavior.
  • Numeric invoice IDs differ from merchant sequential numbers. Exports, dashboard labels, and MCP formatting are not interchangeable identifiers.
  • Invoice list merchant and agent parameters are accepted by validation but do not select another merchant or apply an agent filter in the current route.
  • Invoice and payment cursors are opaque offsets. Keep filters unchanged when requesting the next page. Invalid or obsolete cursors are rejected; restart without a cursor. Concurrent changes and indexer lag can affect traversal, so lists are not a historical snapshot.
  • Strong-mode invoice lists cap at 25. Chain-only fallback does not fully preserve payer/customer filtering or indexer ordering, and can synthesize historical timestamps. Use verified transaction evidence for historical accounting.
  • Payment list fee fields fall back to zero fee and invoice amount when event details are missing. Verify actual settlement evidence before accounting. Page totals summarize only that page.
  • Studio statistics effectively cap at 50 invoices per status without full pagination. Safe transaction-service failures can return an empty successful transaction list. Neither is an unlimited, authoritative historical audit.
  • Payment exports gather matching results in memory. Use bounded date ranges for large histories.
  • Export amounts use floating-point conversion and two-decimal formatting, not lossless raw-unit serialization. Keep raw payment amounts for exact reconciliation.
  • Public pay routes use the deployment's default network; authenticated routes use studio configuration. The protocol-stats endpoint uses the deployment's default chain unless chainId is passed (Base on api.clearedpay.xyz); data.chain names the chain the totals cover.

SDK compatibility and distribution#

The SDK and local stdio MCP package require private repository access; public-registry installation is not currently supported. The recommended hosted MCP connection is available over OAuth without repository access or an API key.

The SDK's getInvoice tuple ABI and settleWithAuth signature are incompatible with the current registry. buildSettleTypedData belongs to the legacy settlement model. settleFromVault and allowance-vault wrappers are not a current supported payment service. The SDK has no cancellation, sessions, REST customer-management, HMAC client, or webhook-verification API. Use the compatibility table instead of assuming every exported method is production-current.

parseUSDC and formatUSDC use floating-point conversion. Use validated decimal strings and exact bigint conversion for arbitrary-precision amounts. Metadata canonicalization sorts top-level keys only; it is not recursive canonical JSON.

MCP behavior#

  • list_invoices returns one page of up to 50 invoices with a continuation cursor. Follow page.next_cursor while page.has_next_page is true; page summaries are not account-wide totals.
  • Customer listing is limited to 100; customer payment checks read at most 20 outstanding and 10 paid invoices. Summary outputs are not complete accounting.
  • send_invoice without a key intentionally starts a new invoice. Retry with the returned key and unchanged business inputs, including email opt-in; ambiguous failures retain the key and copyable retry parameters.
  • MCP input amounts use floating-point conversion and cent rounding. Use REST raw-unit integer strings for sub-cent or arbitrary-precision amounts.
  • Pending/incomplete issuance must not be treated as a payment-link success. Email is opt-in and can fail independently of issuance.
  • In local stdio mode, CLEARED_CHAIN affects MCP presentation, not the studio's network. A mismatched setting can produce misleading chain/explorer labels. Hosted OAuth instead binds the network during consent. Protocol live-stat fields and dashboard recent-activity fields can be incomplete or mismatched; use REST and chain evidence for reconciliation.

See tool parameters and workarounds.

Planned and conditional capabilities#

Outbound production payment webhooks are planned. The existing Resend callback concerns email delivery only. There is no merchant registration or payment-webhook verification API today. Use the polling guidance.

Private Payments is conditional, not a generally available integration. The current architecture direction (ADR-032) depends on written provider confirmations and sandbox verification before production implementation. It proposes Coinbase Prime with merchant initiation/approval controls; do not assume automated sweeps, private recipient provisioning, or private-payment API routes are available. Standard encrypted invoice metadata also does not make public on-chain payments anonymous. See security and contact the team for availability.