> ## Documentation Index
> Fetch the complete documentation index at: https://conto.finance/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API conventions

> Amount units, identifiers, time formats, response envelopes, and retry behavior.

## Amounts and currencies

| Operation                               | Amount encoding                                                                | Example                                                               |
| --------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
| Standard stablecoin payment request     | Positive JSON number, at most two decimal places                               | `10.50` means 10.50 units of the wallet's stablecoin, not 1,050 cents |
| x402 or MPP pre-authorization/recording | Positive, finite JSON number; sub-cent values supported; maximum 1,000,000,000 | `0.005` means 0.005 units of the payment currency                     |

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:

| Identifier                                 | Purpose                                                              |
| ------------------------------------------ | -------------------------------------------------------------------- |
| Your business action ID                    | Connect one purchase or job to payment attempts                      |
| `idempotencyKey`                           | Deduplicate retries of one managed authorization intent              |
| `requestId`                                | Execute or read the payment request                                  |
| `receipt.transactionId` / `transaction.id` | Reconcile the Conto transaction                                      |
| `txHash`                                   | Inspect the network transaction; not interchangeable with a Conto ID |

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](/docs/policies/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](/docs/sdk/authentication) and the [scope reference](/docs/reference/auth-scopes).

## 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:

```json theme={null}
{
  "total": 75,
  "limit": 50,
  "offset": 0,
  "hasMore": true
}
```

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](/docs/guides/payment-lifecycle) before repeating a write and
[SDK error handling](/docs/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](/docs/changelog/overview) and rerun integration tests when upgrading. Use the
[OpenAPI document](https://conto.finance/api/openapi) 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](/docs/guides/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.