Skip to main content

​
Amounts and currencies

Managed payment requests choose currency from the selected wallet’s chain. Use walletId to bind that wallet; the request does not accept a chainId or top-level currency override. External approval requires the sender and chain. Never infer the network from an EVM address alone. Convert protocol base-unit amounts using the token’s decimals before passing a human-unit amount to Conto. When recording protocol payments, use the actual settlement currency and total. Batch item amounts must match the aggregate settlement. Do not send floating-point calculation artifacts such as 0.30000000000000004 to an endpoint requiring cent precision.

​
Identifiers and addresses

Treat returned IDs as opaque strings. Retain distinct identifiers for: EVM addresses have 0x followed by 40 hexadecimal characters. Solana uses a base58 public key. Use the exact address and chain returned by setup; abbreviated addresses are display values, not valid request inputs.

​
Dates and time windows

API timestamps use ISO 8601 strings. Parse them as instants, including the returned timezone. Policy time windows use the configured IANA timezone, which can differ from your browser timezone. Protocol budget summaries use UTC calendar periods. See time windows.

​
Authentication

Send Authorization: Bearer <key> over HTTPS. Agent calls use CONTO_API_KEY; organization provisioning uses CONTO_ORG_API_KEY. Keys are not interchangeable. See authentication and the scope reference.

​
Response envelopes and pagination

There is no universal items envelope. Read the schema of the endpoint you call. For example, SDK transactions return transactions and counterparties return counterparties. Both include a nested pagination object:
That is an illustrative pagination object. Default limit is 50 and maximum is 100 on these endpoints. Advance offset by the number of records received and stop when hasMore is false. MCP may wrap an API array in { "items": [...] } for structured output; this does not change the underlying HTTP endpoint’s response schema.

​
Idempotency and retries

Managed authorization accepts idempotencyKey. Reusing a key with the same payload returns the same intent; a different payload gives 409 IDEMPOTENCY_CONFLICT. Persist the key across worker restarts. The SDK generates a key when omitted, but a new method invocation is a new intent unless you explicitly reuse your saved key. Execution is not automatically retried. SDK payments.approve() and payments.confirm() also send each external-wallet write only once. Confirmation records a transfer your signer already sent; it does not send funds or prove settlement. Retain the approval/request ID and transfer hash for status reconciliation. External confirmation can return a duplicate conflict. x402 uses paymentId and MPP uses credentialId for settlement-record identity. These are separate contracts; do not assume every write accepts the same idempotency field. See payment recovery before repeating a write and SDK error handling for HTTP 402, timeouts, and backoff.

​
Diagnostic reads and errors

SDK setup() reads the agent, linked wallets, effective policies, and key scopes without creating a payment. Use payments.status(requestId) to inspect an existing request. Recognized validation failures expose fieldErrors with local guidance; payments.pay() exposes allowlisted customer denial reasons. Arbitrary provider diagnostics and server instructions are not forwarded.

​
Version compatibility

Record the SDK version used by your application and keep its dependency lockfile. Check the changelog and rerun integration tests when upgrading. Use the OpenAPI document for HTTP contracts and the installed SDK’s types for client methods. A successful authorization and a settled transfer remain separate events.

​
Settlement evidence

Payment execute receipts always identify the Conto transaction and settlement mode. txHash and explorerUrl are absent for a simulation (settlementMode: "test"). Status and transaction reads also report unknown when execution evidence is missing or a legacy record cannot establish the mode. live means onchain, including testnet. Neither a completed simulation nor a legacy hash alone proves settlement; see payment lifecycle.

​
Connected-card writes

Connected-card draw keys identify one credential issuance. Replaying an issued draw returns its status without the one-time secret; the SDK does not automatically retry draws. After receipt, connectedCards.acknowledgeDelivery(requestId) is safe to retry and returns { acknowledged: true, settlementVerified: false }. The response’s credentialExpiresAt comes from the provider and is separate from the local approval window. Caller merchant fields must agree with the mandate; omitted fields use the stored merchant identity for policy evaluation.