@catena/sdk 0.1.0 → 0.4.0

package/README.md

@@ -1,316 +1,595 @@
 # @catena/sdk
 
-Typed client for the Catena agent API: read accounts, balances, and policy, move
-money through policy-checked intents, and pay MPP or x402 HTTP 402 challenges.
-Node >= 20; no framework dependencies.
+**Build agents that can move money without bypassing policy or approvals.**
 
-## Status
+`@catena/sdk` is the typed Node.js client for the Catena agent API. Use it to
+read financial data, manage counterparties, move money through policy-checked
+intents, and pay MPP or x402 HTTP 402 challenges.
 
-The SDK is in initial development. Patch releases within a `0.x` minor are
-intended to remain compatible; a new minor may change the public API. Test
-upgrades before moving to a new `0.x` minor.
+Every Catena API request is signed. Every money movement follows Catena policy
+and approval rules.
+
+Node.js 20+. ESM. Framework-free.
+
+## Install
 
 ```sh
 npm install @catena/sdk
 ```
 
-## Entry points
-
-- `@catena/sdk` — the client: `createCatenaClient`, intents, accounts,
-  counterparties, error types.
-- `@catena/sdk/keypair` — generate or derive the P-256 credential and compute
-  its thumbprint.
-- `@catena/sdk/mpp` — a managed MPP `fetch` wrapper plus Catena-backed
-  `evm/charge` and `usdc/charge` methods for custom mppx integrations. Requires
-  `mppx` and its viem peer dependencies (both optional SDK peer dependencies;
-  install `mppx@0.9.0` and `viem@^2.54.0`).
-- `@catena/sdk/x402` — a `fetch` wrapper that pays x402 402 challenges through
-  Catena.
-- `@catena/sdk/viem` — a viem `Account` backed by a Catena wallet, for x402
-  client tooling that expects an account or `{ address, signTypedData }`.
-  Requires `viem` (an optional peer dependency — install it yourself, `^2.21`).
-
-## Authentication
-
-Every request is signed (RFC 9421) with a P-256 private key; there are no API
-tokens or sessions. The key must first be linked to a Catena agent by a host app
-— for example the Catena CLI or the Catena console. How the key was generated
-does not matter to this SDK, only that it is a valid P-256 key whose public half
-is linked.
-
-Pass the key as `privateKeyHex`, or set `CATENA_SECRET_KEY` and omit the option.
-An explicit value always wins, including when it is empty or invalid; the SDK
-reads the environment only when `privateKeyHex` is `undefined`. The resolved key
-is validated and its public half is derived at construction. The SDK never
-persists credentials or reads CLI profiles and credential stores.
+## Contents
+
+- [Quick start](#quick-start)
+- [Common workflows](#common-workflows)
+- [How intents work](#how-intents-work)
+- [Protocol payments](#protocol-payments)
+- [Error handling](#error-handling)
+- [API reference](#api-reference)
+
+## Quick start
+
+Create a client with your linked agent's private key:
 
 ```ts
 import { createCatenaClient } from "@catena/sdk"
 
-const client = createCatenaClient({
-  privateKeyHex: privateKeyFromSecretManager,
+const client = createCatenaClient({ privateKeyHex })
+```
+
+Inspect the available source accounts and counterparty rails:
+
+```ts
+const { accounts } = await client.listAccounts()
+const { counterparties } = await client.listCounterparties()
+```
+
+Choose the intended IDs, then submit a send intent. `counterpartyRailId` is a
+rail ID, not a counterparty ID.
+
+```ts
+const sourceAccountId = "acct_..."
+const counterpartyRailId = "cpr_..."
+
+const intent = await client.submitIntent({
+  action: {
+    type: "send",
+    accountId: sourceAccountId,
+    counterpartyRailId,
+    amount: "12.50",
+    method: "ach",
+  },
 })
+
+console.log(intent.status)
 ```
 
+You may omit `accountId` when policy allows exactly one source account. USD
+intent amounts are decimal strings: `"12.50"` means $12.50, not cents or atomic
+units.
+
+## Common workflows
+
+### Read account data
+
 ```ts
-import { generateP256Keypair } from "@catena/sdk/keypair"
+const agent = await client.whoami()
+const policy = await client.getPolicy()
+const { accounts } = await client.listAccounts()
+
+const account = accounts[0]
+if (!account) throw new Error("No account is available")
 
-const keypair = generateP256Keypair()
-// Persist keypair.privateKeyHex yourself; link keypair.publicKeyHex to an
-// agent in a host app before the client can authenticate.
+const balance = await client.getAccountBalance(account.id)
+const totalBalance = balance.balances?.total ?? balance.balance
+const availableBalance = balance.balances?.available
+const { transactions } = await client.listAccountTransactions(account.id, {
+  limit: 25,
+})
 ```
 
-## Quickstart
+`balances.available` is the most one payment can move. It is below
+`balances.total` when the account holds money it cannot spend in one payment:
+money an in-flight send holds, money in transit between chains, money on another
+network, or money the account cannot spend at all. It is zero while the account
+is not active, and so is every `balances.byNetwork` `available`. The deprecated
+flat `balance` field equals `balances.total`. If `balances` is absent on an
+older API, the available balance is unknown.
+
+`balances.byNetwork` gives `total` and `available` for each network that the
+account holds and agents may use, so it says where the money sits:
 
 ```ts
-import { createCatenaClient } from "@catena/sdk"
+for (const { network, available } of balance.balances?.byNetwork ?? []) {
+  console.log(network, available.amount)
+}
+```
 
-// CATENA_SECRET_KEY contains the linked P-256 private key.
-const client = createCatenaClient()
+`balances.byNetwork` is absent until the money of the account is split by
+network. An empty array means the money is split, but no network of the account
+is open to agents. The entries can add up to less than `balances.total`, which
+also counts a network agents may not use. Their `available` values can add up to
+more than `balances.available`, because one payment binds one network unless a
+plan carries it across them.
 
-const { accounts } = await client.listAccounts()
-const { counterparties } = await client.listCounterparties()
+`policy.capabilities` lists broad permissions. `policy.policyCapabilities`
+contains per-account rules. `policy.counterpartyRules` controls counterparty
+access, while `kind` and `expiresAt` identify an active temporary override.
 
-await client.submitIntent({
+For an on-chain deposit address:
+
+```ts
+const deposit = await client.getAccountDepositAddress(walletAccountId, {
+  network: "base",
+  asset: "usdc",
+})
+```
+
+`deposit.source` is `wallet` or `liquidation`. x402, MPP, and viem require an
+account whose deposit address returns `source: "wallet"` on the chosen network.
+
+### Manage counterparties
+
+Create a counterparty with contact information:
+
+```ts
+const created = await client.submitIntent({
   action: {
     type: "create_counterparty",
     name: "Acme Vendor",
     email: "billing@acme.test",
   },
 })
+```
+
+The action may require approval. Poll it to a final state, then narrow the
+runtime result before reading the new ID:
 
-// Email-only creation saves a counterparty without sending an email. A completed
-// intent returns data.counterparty with status "awaiting_details" and no rails.
+```ts
+let result = created
+while (result.status === "pending" || result.status === "processing") {
+  await new Promise((resolve) => setTimeout(resolve, 2_000))
+  result = await client.getIntent(result.id)
+}
+
+const counterparty = result.data?.counterparty
+
+if (
+  result.status !== "completed" ||
+  typeof counterparty !== "object" ||
+  counterparty === null ||
+  !("id" in counterparty) ||
+  typeof counterparty.id !== "string"
+) {
+  throw new Error(`Counterparty is not ready: ${result.status}`)
+}
+
+const counterpartyId = counterparty.id
+```
 
+An email-only counterparty has no rails, and creating it does not send an email.
+
+Request those details through Catena. Bank details require a KYB-verified
+organization with fiat rails enabled.
+
+```ts
 await client.submitIntent({
   action: {
     type: "request_counterparty_details",
-    counterpartyId: counterparties[0].id,
+    counterpartyId,
     methods: { bank: true, wallet: false },
   },
 })
+```
+
+The request follows policy and may wait for approval. A second request while an
+invitation is active returns HTTP 409 with
+`counterparty_payment_request_conflict`; `error.details.invite` identifies the
+existing invitation. Set at least one requested method to `true`.
+
+You can also create a counterparty with a wallet rail already attached:
+
+```ts
+await client.submitIntent({
+  action: {
+    type: "create_counterparty",
+    name: "Treasury",
+    rail: {
+      type: "wallet",
+      walletAddress: "0x1111111111111111111111111111111111111111",
+      network: "base",
+    },
+  },
+})
+```
+
+<details>
+<summary><strong>Create a counterparty with a bank rail</strong></summary>
+
+Bank rails require a KYB-verified organization with fiat rails enabled.
+
+```ts
+await client.submitIntent({
+  action: {
+    type: "create_counterparty",
+    name: "Acme Vendor",
+    email: "billing@acme.test",
+    rail: {
+      type: "bank",
+      bankName: "Example Bank",
+      routingNumber: "021000021",
+      accountNumber: "123456789",
+      accountType: "checking",
+      addressStreet: "1 Main Street",
+      addressCity: "New York",
+      addressState: "NY",
+      addressPostalCode: "10001",
+      addressCountry: "USA",
+    },
+  },
+})
+```
 
-// The request follows policy and may remain pending for human approval. While
-// an invitation is outstanding, another request returns ApiError status 409
-// with code "counterparty_payment_request_conflict" and details.invite.
+`routingNumber` must contain 9 digits. `accountNumber` accepts 4–17 digits.
+`accountType` is `checking` or `savings`. `accountType`, `addressCountry`, and
+the action-level `email` are optional; the remaining fields are required.
 
-// The rail must match the method: "ach" and "wire" need a bank rail,
-// "on-chain" needs a wallet rail. Pass the rail id, not the counterparty id.
-const bankRail = counterparties
-  .flatMap((counterparty) => counterparty.rails)
-  .find((rail) => rail.type === "bank")!
+</details>
 
+When sending, match the method to the rail: `ach` and `wire` require a bank
+rail; `on-chain` requires a wallet rail.
+
+### Transfer between accounts
+
+```ts
 const intent = await client.submitIntent({
+  action: {
+    type: "transfer",
+    accountId: sourceAccountId,
+    toAccountId: destinationAccountId,
+    amount: "100.00",
+    memo: "Treasury rebalance",
+  },
+})
+```
+
+ACH and wire `send` actions accept an optional `memo`, which is sent with the
+bank payment. All `send` actions accept an optional `description` for an
+internal Catena note. On-chain `memo` remains accepted for compatibility but is
+deprecated and is not sent to the blockchain. `transfer` accepts both fields.
+
+### Sends that cross chains
+
+A `send` to a counterparty wallet on the other side of the Base and Arc lane is
+an ordinary `send`. When the account cannot pay it from its balance on the
+rail's network, the send crosses chains under the same intent: `submitIntent`
+signs the burn toward the agent's own address on the other chain, and
+`continueIntent` signs the send to the counterparty once the funds land. One
+intent covers the whole payment, so policy, spend limits and any approval are
+evaluated once. Gas on both legs is paid by Catena.
+
+```ts
+let intent = await client.submitIntent({
   action: {
     type: "send",
-    counterpartyRailId: bankRail.id,
-    // Decimal USD string: "12.50" is $12.50. Never cents or atomic units.
-    amount: "12.50",
-    method: "ach",
+    accountId,
+    counterpartyRailId: walletRailIdOnTheOtherChain,
+    amount: "250.00",
+    method: "on-chain",
+    description: "Invoice 1042",
   },
 })
+
+while (intent.crossChain && intent.crossChain.nextStep === "wait") {
+  await new Promise((resolve) => setTimeout(resolve, 30_000))
+  intent = await client.getIntent(intent.id)
+}
+
+if (intent.crossChain?.nextStep === "continue") {
+  intent = await client.continueIntent({ intentId: intent.id })
+  // Poll getIntent until crossChain.nextStep reads "done".
+}
 ```
 
-For `send`, omit `accountId` when the agent's current effective policy allows
-sends from exactly one account. Other readable or transfer accounts do not
-count. The server rejects zero send accounts with HTTP 403
-(`policy_send_account_unavailable`) and multiple send accounts with HTTP 400
-(`policy_send_account_required`). An explicit account always stays explicit; it
-is never replaced with another account. Transfers still require `accountId`.
-
-The result's `accountId` is the resolved source, pinned at creation and returned
-by `getIntent` too, including for pending or blocked intents. Approval checks
-the pinned account against the current policy; it never chooses a new source.
-
-Each new accountless operation resolves the current policy. Reusing an explicit
-idempotency key keeps the original intent's source, even if the policy now
-selects another account or no longer has a unique send account. Changed payment
-details or an explicitly different source return HTTP 409. Policy-blocked
-attempts are reevaluated against the current policy with the source still
-pinned. Use a new key for a new operation. If the outcome of a submission is
-unknown, check that intent before submitting again.
-
-`submitIntent` returns a disposition, not a guarantee of execution — branch on
-`intent.status`:
-
-- `"completed"` — the action succeeded: money moved for send, transfer, and
-  wallet_send; for MPP and x402 the payment authorization was delivered
-  (on-chain settlement is verified separately); the counterparty exists for
-  create_counterparty.
-- `"pending"` — parked, typically awaiting a human approval; `reasons` says why,
-  `expiresAt` says when the approval request lapses.
-- `"processing"` — accepted and in progress. Executing intents advance on their
-  own; poll `getIntent(intent.id)`. An approved MPP or x402 payment instead
-  rests here until the paid request is re-run — polling never advances it.
-- `"blocked"` — declined by policy or denied by an operator; `reasons` explains
-  why approval was required, not necessarily why it was denied. Terminal.
-- `"failed"` — failed, expired, or reversed. Terminal.
-
-## Timeouts
-
-Each HTTP exchange with Catena has an 80,000ms deadline by default. Configure a
-different positive integer no greater than 2,147,483,647 at client construction:
+`crossChain` is present only when the send crossed. Its `nextStep` is the whole
+contract: `wait` while the crossing runs, `continue` when `continueIntent` is
+due, `done` once the counterparty was paid, `blocked` when the crossing cannot
+continue, with `failureReason` saying why; read it before choosing a recovery,
+since not every reason needs an operator. `continue` is served only once the
+funds are credited on the destination, and it waits a day for `continueIntent`;
+past that the crossing is `blocked` with `failureReason: "not_continued"`, and
+the funds sit in the account's balance on the destination, so a plain send pays
+the counterparty from there. A few minutes is typical; up to twenty on the
+Standard lane. A network the provider does not sponsor yet is refused with
+`wallet_send_action_not_yet_enabled` rather than charged to you; on
+`continueIntent` the intent stays at `continue`, so call it again later.
+
+### Payments a person approves
+
+A `send` or `transfer` over the organization's approval threshold parks for a
+person rather than being refused. Once a person approves it, an admin signs it
+in the Catena console. You do not finish it: poll it until it is done or
+blocked.
+
+Poll the intent with `getIntent` and read `movement`. It is served on a read,
+not on the `submitIntent` result, and only for a payment carried by a movement
+plan. `movement.nextStep` is what `status` cannot tell you: a payment waiting on
+a person and one an admin is signing both read `processing`.
 
 ```ts
-const client = createCatenaClient({
-  timeout: 30_000,
+const action = {
+  type: "send",
+  accountId,
+  counterpartyRailId,
+  amount: "2500.00",
+  method: "on-chain",
+} as const
+
+const submitted = await client.submitIntent({ action })
+
+// `movement` is served by getIntent, not by submitIntent, so read it first.
+let intent = await client.getIntent(submitted.id)
+while (intent.movement?.nextStep === "wait") {
+  await new Promise((resolve) => setTimeout(resolve, 30_000))
+  intent = await client.getIntent(intent.id)
+}
+```
+
+- `wait` — a person is deciding it, an admin is signing it, or its signature is
+  in flight. Read it again with `getIntent`.
+- `done` — the payment completed.
+- `blocked` — it ended without paying. `reasons` says why, and is empty when an
+  approval lapsed.
+
+`movement.nextStep` never reads `continue`. `continueIntent` refuses a payment a
+person approved with `movement_admin_completes_payment`, and sending the same
+request again on the same idempotency key hands back the payment's intent
+without signing anything. Both are answers, not failures: keep polling.
+
+A payment nobody had to approve is still yours to sign, and `submitIntent` hands
+you its stamp. If you restarted before signing it, send the original request
+again on the same idempotency key. Within about five minutes of the first send
+it answers `movement_authorization_in_progress`; after that it hands the payment
+back for you to sign.
+
+The SDK checks a movement stamp against the `action` you submitted before it
+signs. It is the one check that compares the payment against something Catena
+did not supply. Where every payload that can move value states its amount in a
+field the signature covers, a payment that would not pay the amount you asked
+for is refused before anything is signed. A payment delivered as a raw
+transaction or a batched call instead carries its amount inside call data this
+client reproduces without decoding, so that one check is left unbound rather
+than guessed at.
+
+Signing a movement stamp needs the optional `viem` peer (`>=2.24.0`). A movement
+is signed as pre-hashed digests, and the SDK rebuilds them locally rather than
+trust what it is handed — it will not sign digests it cannot check. Without
+`viem` installed, a movement stamp is refused before anything is signed. A
+crossing needs none of this and works either way.
+
+An approval does not wait forever. If no admin signs the payment before it
+lapses, it expires unpaid and has to be asked for again.
+
+### Request a temporary policy override
+
+Policy overrides always wait for human approval. This example requests a higher
+per-transaction send limit for one hour:
+
+```ts
+const intent = await client.submitIntent({
+  action: {
+    type: "policy_override",
+    operations: [
+      {
+        type: "increase_limit",
+        accountId,
+        capability: "send",
+        limitType: "per_transaction_amount",
+        newLimit: { amount: "5000.00", assetId: "USD" },
+      },
+    ],
+    durationSeconds: 3_600,
+    reason: "Pay an approved vendor invoice",
+  },
 })
 ```
 
-The deadline starts when a signed request is dispatched and remains active
-through complete response-body parsing. Local signing is outside the deadline.
-Operations with more than one HTTP exchange, such as `submitIntent`, receive a
-fresh deadline for each exchange. The timeout is not an overall operation
-deadline, so a multi-exchange operation may take several timeout periods.
-
-## Errors
-
-- `InvalidKeyError` — construction could not resolve a key from either
-  `privateKeyHex` or `CATENA_SECRET_KEY`, or the resolved value is not a valid
-  P-256 private key.
-- `ApiError` — any non-OK API response. Branch on `code` (the stable error
-  code), not on message prose; `status` is the HTTP status.
-- `TimeoutError` — an HTTP exchange exceeded the configured deadline.
-  `timeoutMs` contains that deadline. A create-intent timeout propagates
-  directly; a submit-stamp timeout is the `cause` of an `IntentSubmitError`
-  whose `outcome` is `"unknown"`.
-  - A timeout means the SDK stopped waiting, not that the server did no work.
-  - Each `submitIntent` invocation generates a fresh UUID when `idempotencyKey`
-    is omitted. Matching actions alone are not deduplicated.
-  - To recover an exact submission after a create-intent timeout, choose and
-    persist an explicit `idempotencyKey` before the first call, then retry the
-    unchanged action with that key. Reusing it with a different action
-    returns 409. If the first call omitted the key, do not treat a second call
-    as its retry: it is a new logical operation.
-  - If that retry throws an `ApiError` with status `409` and code
-    `wallet_send_intent_not_executing` or `x402_intent_state_mismatch`, the SDK
-    cannot reissue the co-signing body and the response carries no intent ID.
-    Reconcile with the operator before starting a distinct attempt.
-  - A `TimeoutError` from the x402 wrapper is create-phase only, so no payment
-    was authorized and re-running cannot double-pay. If the first intent was
-    already executing, the retry starts a new intent and leaves the first
-    awaiting expiry. A payment pending or granted approval is instead matched by
-    its canonical requirements and reused; a lapsed approval may park again.
-- `IntentSubmitError` — `submitIntent` failed after the intent was created.
-  Branch on `outcome`:
-
-  - `"not-submitted"` means no money moved. Recover with a new `submitIntent`
-    invocation and a new key, typically after fixing the signing credential.
-    Omit `idempotencyKey` to generate one, or supply a different value. Reusing
-    the original key finds the stranded intent and can return a 409 rather than
-    restart signing.
-  - `"unknown"` means the server may have acted — poll `getIntent(err.intentId)`
-    to a terminal status and resubmit only after blocked or failed, never
-    blindly.
-
-## Paying x402 challenges
-
-`wrapFetchWithX402Payment` returns a drop-in `fetch`: when a response is a 402
-with a decodable v2 challenge, it pays through Catena (policy checks included)
-and retries once with the `PAYMENT-SIGNATURE` header. Everything else passes
-through untouched.
+Amount limits use `per_transaction_amount`, `daily_amount`, `weekly_amount`, or
+`monthly_amount`. Count limits use `hourly_count` or `daily_count` with
+`newLimit: { count }`. `capability` is `send` or `transfer`. Amounts are
+positive decimal strings with up to six fractional digits; counts are positive
+integers. Overrides last from one minute to seven days, starting at approval.
+Submit 1–10 unique account, capability, and limit combinations. `reason` must
+contain 1–280 characters.
+
+## How intents work
+
+Policy-controlled actions use `submitIntent`. Catena evaluates policy, collects
+any required approval, and co-signs the action when needed.
+
+`submitIntent` returns the intent's current state. It does not guarantee that
+execution is finished.
+
+| Status       | Meaning                                                         |
+| ------------ | --------------------------------------------------------------- |
+| `completed`  | The action succeeded.                                           |
+| `pending`    | The intent is waiting for human approval.                       |
+| `processing` | Catena accepted the intent and is still working.                |
+| `blocked`    | Policy or an operator declined the intent. This state is final. |
+| `failed`     | The intent failed, expired, or reversed. This state is final.   |
+
+Read `reasons` for a non-completed outcome and `expiresAt` for an approval
+deadline. For ordinary actions, poll `pending` and `processing` intents with a
+delay until they reach a final state. Treat only `completed` as success.
+
+Two kinds of intent never reach a final state by polling alone. MPP and x402
+payments: after approval, repeat the original paid request so its fresh
+challenge can use the approval. For these protocols, `completed` means Catena
+delivered the payment authorization, and on-chain settlement is verified
+separately. A `send` or `transfer` a person approved: it rests at `processing`
+while an admin signs it, and `movement.nextStep` reads `wait` until it is done
+or blocked — see [Payments a person approves](#payments-a-person-approves).
+
+### Result data
+
+`IntentResult.data` is runtime data. Narrow it before use.
+
+| Action                         | Result data when available                                    |
+| ------------------------------ | ------------------------------------------------------------- |
+| `send`, `transfer`             | `data.transaction`                                            |
+| `create_counterparty`          | `data.counterparty`                                           |
+| `request_counterparty_details` | `data.counterpartyId`, `data.counterpartyName`, `data.invite` |
+| `x402`, `mpp`                  | `data.paymentCredential`, `data.transaction`                  |
+| `policy_override`              | `data.policyOverride.policyId`                                |
+
+`metadata.dataUrl`, when present, links to the relevant approval or result in
+the Catena console.
+
+### Source selection
+
+For `send`, omit `accountId` only when policy allows exactly one source account.
+Zero eligible accounts returns HTTP 403 with `policy_send_account_unavailable`;
+multiple eligible accounts returns HTTP 400 with `policy_send_account_required`.
+
+Catena pins the selected source to the intent. A later policy change does not
+silently switch accounts. Transfers always require `accountId`.
+
+### Idempotency
+
+The SDK generates a fresh idempotency key for every `submitIntent` call unless
+you provide one. Use an explicit key when separate calls or processes must refer
+to the same logical operation.
+
+Reuse a key only with the same action and source. The source account stays
+pinned even if policy changes. A different action or source returns HTTP 409.
+When `intent.replayed` is `true`, Catena returned the existing intent without
+starting the action again.
+
+## Protocol payments
+
+| Use case                        | Import             |
+| ------------------------------- | ------------------ |
+| Managed x402 payment loop       | `@catena/sdk/x402` |
+| Managed or custom MPP loop      | `@catena/sdk/mpp`  |
+| viem-compatible x402 account    | `@catena/sdk/viem` |
+| Direct agent API payment intent | `@catena/sdk`      |
+
+### Pay x402 challenges
+
+The helper supports x402 v2 `exact` EIP-3009 payments on structurally valid EVM
+networks and token contracts. The connected Catena server decides which networks
+and canonical assets are payable. Native USDC on Base and Base Sepolia is
+supported where enabled. Arc support is rolling out. Wrap `fetch` to pay a
+compatible challenge and retry once with `PAYMENT-SIGNATURE`:
 
 ```ts
 import { createCatenaClient } from "@catena/sdk"
 import { wrapFetchWithX402Payment } from "@catena/sdk/x402"
 
-const client = createCatenaClient()
-
+const client = createCatenaClient({ privateKeyHex })
 const fetchWithPayment = wrapFetchWithX402Payment(client, {
-  // Wallet account the payments draw from.
   accountId: walletAccountId,
-  // Refuse challenges above this price, in atomic USDC units ("1000000" = $1).
   maxAtomicAmount: 1_000_000n,
 })
 
 const response = await fetchWithPayment("https://api.example.com/paid-thing")
 ```
 
-Request bodies must be replayable: pass them via the `init` argument as a
-string, `URLSearchParams`, Blob, ArrayBuffer, or typed array — a `Request`
-object carrying a body (or any stream) throws `X402PaymentError` instead of
-paying.
+`maxAtomicAmount` uses atomic USDC units, so `1_000_000n` is 1 USDC. Ordinary
+responses and 402s without a decodable v2 challenge pass through untouched. A
+decoded but unpayable challenge throws `X402PaymentError`.
+
+Request bodies must be replayable. Put a string, `URLSearchParams`, `Blob`,
+`ArrayBuffer`, typed array, or `DataView` in the `init` argument. Body-bearing
+`Request` objects and streams are rejected before payment.
+
+The helper examines at most the first five `exact` candidates and stops at the
+first one Catena can pay.
+
+For direct control, use `decodePaymentRequired(response)` and
+`payX402Challenge(client, options)`. The latter returns a receipt containing the
+intent ID, selected requirements, and `paymentSignature` header value. It pays
+but does not retry the HTTP request for you.
+
+<details>
+<summary><strong>x402 challenge requirements</strong></summary>
+
+A structurally valid challenge must use x402 v2, the `exact` scheme, an EVM
+CAIP-2 network, a valid token contract, and an EIP-3009 authorization. The
+amount must be a canonical atomic-unit integer, `payTo` must be a valid EVM
+address, and `maxTimeoutSeconds` must be from 1 to 3,600. The requirement must
+include an EIP-712 domain name and version. The server separately validates
+network support, the canonical asset and domain, and the saved counterparty.
 
-Payment failures surface as `X402PaymentError` or a subclass documenting its
-recovery path; an `ApiError` the loop does not absorb while skipping unpayable
-candidates, a create-phase `TimeoutError`, and a `"not-submitted"`
-`IntentSubmitError` propagate unchanged. For x402 `TimeoutError` recovery,
-follow the `TimeoutError` guidance in Errors above. Two subclasses deserve care:
-`X402ApprovalPendingError` means the payment is parked for human approval —
-re-run the same request after approval; `X402RetryFailedError` and
-`X402SubmitInterruptedError` mean money may have already moved — follow the
-recovery steps in the error message instead of paying again.
+</details>
 
-## Paying MPP challenges
+### Pay MPP challenges
 
-Install mppx and its compatible viem version alongside the SDK. Catena supports
-the `evm/charge` and `usdc/charge` wire pairs for native USDC on Base and Base
-Sepolia:
+Install the optional peers with the SDK:
 
 ```sh
-npm install @catena/sdk mppx@0.9.0 viem@^2.54.0
+npm install @catena/sdk mppx@^0.9.0 viem@^2.54.0
 ```
 
+The managed wrapper recognizes `evm/charge` and `usdc/charge` for structurally
+valid EVM networks and token contracts. The connected Catena server decides
+which networks and canonical USDC contracts are payable. Native USDC on Base and
+Base Sepolia is supported where enabled. Arc support is rolling out:
+
 ```ts
 import { createCatenaClient } from "@catena/sdk"
-import { wrapFetchWithMppPayment } from "@catena/sdk/mpp"
+import {
+  MppCounterpartyNotFoundError,
+  wrapFetchWithMppPayment,
+} from "@catena/sdk/mpp"
 
-const client = createCatenaClient()
+const client = createCatenaClient({ privateKeyHex })
 const fetchWithPayment = wrapFetchWithMppPayment(client, {
   accountId: walletAccountId,
-  // Refuse a price above 1 USDC before creating an intent.
   maxAtomicAmount: 1_000_000n,
-  onPayment: (receipt) => {
-    recordPayment(receipt)
-  },
 })
 
 const response = await fetchWithPayment("https://api.example.com/paid-thing")
 ```
 
-The managed wrapper passes ordinary responses and undecodable 402s through
-untouched. For an eligible challenge, mppx parses and orders the candidates,
-chooses `Authorization` or `Payment-Authorization`, and attaches the credential.
-The wrapper tries at most the first five supported candidates and moves to the
-next only when Catena returns `mpp_challenge_not_payable`,
-`mpp_network_mismatch`, or `mpp_counterparty_rail_not_found`. It creates at most
-one credential and makes exactly one paid retry.
-
-The payment is bound to the response's final canonical URL. A cross-origin
-redirect is rejected before an intent is created. The credential-bearing retry
-preserves the caller's redirect mode and delegates redirect handling to the
-configured Fetch implementation, consistent with the x402 wrapper. Request
-bodies must be replayable: use a string, `URLSearchParams`, Blob, ArrayBuffer,
-or typed array in the `init` argument; a body-bearing `Request`,
-`ReadableStream`, or raw `FormData` is refused before payment. The wrapper does
-not pre-verify an optional request digest—the seller verifies it when accepting
-the credential.
-
-`onPayment` runs once after Catena completes and validates the credential, but
-before the paid retry. Its `MppPaymentReceipt` contains the intent ID, validated
-method and terms, and canonical resource URL; it never contains the credential.
-If the callback, retry, or a second 402 fails, `MppRetryFailedError.receipt`
-identifies the completed intent so the caller does not pay twice.
-
-Recovery errors are explicit: retry the original request after resolving
-`MppApprovalPendingError`; treat `MppPaymentDeclinedError` as terminal; fund one
-of `MppNetworkMismatchError.requiredNetworks`; and add the rail named by
-`MppCounterpartyNotFoundError`. For `MppSubmitInterruptedError`, first reconcile
-`intentId` with `client.getIntent(...)`, because submission may have succeeded.
-A create-phase `TimeoutError`, non-fallback `ApiError`, and `IntentSubmitError`
-with outcome `"not-submitted"` propagate unchanged.
-
-### Custom mppx integration
-
-Use the lower-level Catena methods when the host needs its own candidate policy,
-retry count, event hooks, or transport behavior:
+The wrapper tries up to five supported candidates, creates at most one
+credential, and retries the request once. `onPayment` runs after payment and
+before the retry. Its receipt contains no credential. Non-replayable bodies and
+cross-origin redirects are rejected before payment.
+
+The receipt contains `intentId`, `method`, `atomicAmount`, `network`,
+`recipient`, and `resourceUrl`.
+
+When a recipient is not saved, the server-resolved `requiredRail` can be passed
+directly to a deliberate counterparty intent:
+
+```ts
+try {
+  await fetchWithPayment(url)
+} catch (error) {
+  if (error instanceof MppCounterpartyNotFoundError && error.requiredRail) {
+    await client.submitIntent({
+      action: {
+        type: "create_counterparty",
+        name: "Approved seller",
+        rail: error.requiredRail,
+      },
+    })
+  }
+}
+```
+
+`X402CounterpartyNotFoundError.requiredRail` has the same contract.
+
+Need custom transport, hooks, or candidate selection? Add Catena's methods to
+your own mppx client:
 
 ```ts
 import { createCatenaClient } from "@catena/sdk"
 import { catena } from "@catena/sdk/mpp"
 import { Mppx } from "mppx/client"
 
-const client = createCatenaClient()
+const client = createCatenaClient({ privateKeyHex })
+
 const mppx = Mppx.create({
   methods: [
     catena({
@@ -326,155 +605,307 @@ const mppx = Mppx.create({
 const response = await mppx.fetch("https://api.example.com/paid-thing")
 ```
 
-`catena.charge(...)` is an equivalent alias for `catena(...)`. mppx parses and
-selects challenges, chooses `Authorization` or `Payment-Authorization`, retries
-the request, and runs its response hooks. The Catena method submits the selected
-challenge through the normal policy and approval lifecycle, then returns the
-serialized credential to mppx.
-
-By default, `mppx@0.9.0` allows up to three automatic payment attempts per
-fetch. If the seller keeps returning payable challenges with fresh IDs, one
-fetch can produce multiple payment authorizations that may be redeemed
-separately. Each attempt still goes through Catena policy and approval checks;
-these checks do not guarantee one payment per fetch.
-
-Set `maxAtomicAmount` when creating the Catena methods to refuse an individual
-challenge above that price before creating an intent. The value uses atomic USDC
-units (6 decimals, so `1_000_000n` is 1 USDC). The server's policy limits still
-apply. This ceiling is checked separately for every challenge and does not limit
-the number of attempts.
-
-To allow only one automatic payment attempt per fetch, set
-`maxPaymentRetries: 1` in `Mppx.create(...)`. This stops automatic negotiation
-of fresh challenges after that attempt, but does not prevent duplicate purchases
-across separate fetch calls.
-
-With `mppx@0.9.0`, pass the HTTP method and body in the fetch `init` argument,
-not only inside a `Request` object. mppx rebuilds the paid retry from `init`, so
-a method or body stored only in `Request` can be lost: a POST may retry as a
-bodiless GET, and even a bodiless DELETE may retry as GET. For example:
+`catena.charge(options)` is an alias for `catena(options)`. By default, mppx can
+make up to three payment attempts per fetch. Set `maxPaymentRetries: 1` to allow
+one. Separate fetch calls can still pay again. `maxAtomicAmount` applies to each
+attempt, not the combined total.
+
+With mppx 0.9, pass the HTTP method and body in the fetch `init` argument, not
+only in a `Request`. Buffer the body first; streams and raw `FormData` are not
+safe to replay.
+
+<details>
+<summary><strong>MPP challenge requirements</strong></summary>
+
+The client forwards structurally valid EVM networks and token contracts to the
+server. The server decides which are payable. Native USDC on Base and Base
+Sepolia is supported where enabled. Arc support is rolling out. A challenge must
+also meet these rules:
+
+- `method` is `evm` or `usdc`, and `intent` is `charge`;
+- `id` and `realm` contain 1–256 characters, the serialized request is at most
+  16 KiB, and the full challenge is at most 32 KiB;
+- `expires` is UTC with a trailing `Z`, has at most three fractional digits, and
+  leaves between 5 seconds and 1 hour;
+- the amount is a positive canonical integer of at most 78 digits and does not
+  exceed `maxAtomicAmount`, when configured;
+- the currency and recipient are valid EVM addresses;
+- method details use 6 decimals and a single authorization credential; splits
+  are unsupported, and an optional Permit2 address must be valid;
+- `description` is at most 1,024 characters and `externalId` is at most 256;
+- `header` is omitted or exactly `Payment-Authorization`;
+- `digest` uses `sha-256=:<base64>:` or `sha-256=<base64>` with canonical,
+  padded standard Base64;
+- `opaque`, when present, is nonempty unpadded Base64url of at most 8 KiB;
+- addresses are lowercase or valid EIP-55;
+- `description` and `externalId` contain valid Unicode.
+
+mppx may report `No method found for challenges` when one of these requirements
+fails, even if `evm.charge` or `usdc.charge` appears available.
+
+</details>
+
+### Use a Catena wallet with viem
+
+`createCatenaAccount` returns a viem `Account` for x402 clients that expect
+`{ address, signTypedData }`:
 
-```ts
-const response = await mppx.fetch("https://api.example.com/paid-thing", {
-  method: "POST",
-  headers: { "Content-Type": "application/json" },
-  body: JSON.stringify({ query: "example" }),
-})
+```sh
+npm install @catena/sdk viem@^2.21
 ```
 
-The body must also be reusable and byte-stable: every attempt must send the same
-bytes, as with the JSON string above. Raw `FormData` can generate a new
-multipart boundary each time it is sent, so identical fields can still fail a
-seller's request-body digest check. Serialize multipart bodies once, then reuse
-the resulting bytes and matching `Content-Type` on every attempt. Do not rely on
-`ReadableStream` bodies being replayed: the first send consumes the stream, and
-the paid retry can fail after authorization. Buffer the body before the first
-request instead; this uses memory and sacrifices streaming uploads.
-
-The method relays a challenge digest unchanged; it does not read or hash the
-HTTP request body. The seller verifies any body binding when it accepts the
-credential. Unsupported methods, intents, currencies, networks, and credential
-types are rejected before a Catena intent is submitted.
-
-Additional selection requirements apply: the UTC challenge expiry must end in
-`Z`, use no more than 3 fractional-second digits, and leave at least 5 seconds
-and no more than 1 hour. The optional credential header must be omitted or be
-exactly `Payment-Authorization`. An optional digest must use
-`sha-256=:<base64>:` or the mppx 0.9 spelling `sha-256=<base64>`, with a
-canonical, padded standard-base64 SHA-256 value. Optional `opaque` data must be
-nonempty, unpadded base64url. Addresses must be lowercase or have a valid EIP-55
-checksum. Request `description` and `externalId` text must contain valid Unicode
-without unpaired surrogates. When `maxAtomicAmount` is configured, the request
-amount must not exceed it.
-
-When Catena declines a challenge during selection, mppx can report
-`No method found for challenges` even when it lists `evm.charge` or
-`usdc.charge` as available. Check these requirements as well as the supported
-payment types when diagnosing that error.
-
-An intent result that does not yield a usable credential throws
-`MppPaymentError`, which exposes `intentId`, `status`, `reasons`, and
-`expiresAt`. A pending payment needs human approval. Inspect an in-flight intent
-with `client.getIntent(error.intentId)`. After approval, re-run the original
-paid request so its fresh challenge can consume the approved grant; polling
-reports the status but never advances an approved MPP payment. Blocked and
-failed payments include the server's reasons in the thrown error.
-
-Submission can also throw `IntentSubmitError` from `@catena/sdk`. An `outcome`
-of `"unknown"` means the server may already have signed an authorization. Poll
-`client.getIntent(error.intentId)` to determine the outcome before making
-another payment attempt.
-
-An HTTP failure (including another 402), network error, or later
-`MppPaymentError` does not prove that earlier authorizations were unused. An
-`MppPaymentError` describes only its own intent; earlier attempts in the same
-fetch may already have produced redeemable credentials. Before retrying the
-original request, including after approval, reconcile all payment attempts, not
-just the intent named in the last error. Use `client.getIntent(intentId)` for
-known intents; for MPP, `completed` means an authorization was produced, not
-proof of settlement or delivery of the purchased resource. If earlier outcomes
-are unclear, reconcile with the operator and seller before making another
-payment attempt. Do not automatically retry an ambiguous payment.
-
-## Using the wallet as a viem account
-
-A Catena wallet is custodial: your credential authenticates requests and
-co-signs intents, and the wallet's own key never leaves the custodian. So the
-account `@catena/sdk/viem` returns signs exactly one thing — x402 EIP-3009
-`TransferWithAuthorization` typed data for USDC on Base or Base Sepolia, routed
-through a policy-checked payment intent. That is the payload x402 client
-libraries build, which makes the account a drop-in signer for tooling that knows
-nothing about Catena:
-
 ```ts
 import { createCatenaClient } from "@catena/sdk"
 import { createCatenaAccount } from "@catena/sdk/viem"
 
-const client = createCatenaClient()
+const client = createCatenaClient({ privateKeyHex })
 const account = await createCatenaAccount(client, {
   accountId: walletAccountId,
-  // Must match the network the wallet account is configured for; defaults to
-  // "base". A testnet wallet needs "base-sepolia" here.
   network: "base",
 })
-
-// Hand `account` to any x402 client that accepts a viem account or
-// an { address, signTypedData } signer, e.g.:
-//   wrapFetchWithPayment(fetch, clientWithScheme(account))
 ```
 
-The contract, in brief:
-
-- `signTypedData` accepts only `TransferWithAuthorization` for USDC on Base
-  (8453) or Base Sepolia (84532). Anything else throws
-  `UnsupportedTypedDataError` client-side, with a machine-readable `reason` —
-  nothing is submitted.
-- The returned signature is verified to recover to the wallet address for the
-  exact typed data you passed before it is returned; a mismatch throws
-  `SignatureVerificationFailedError` instead of surfacing a bad signature. That
-  check runs after the payment completed, so it belongs to the
-  money-may-have-moved group below, not to the client-side refusals above.
-- `signMessage` and `signTransaction` throw `UnsupportedAccountCapabilityError`;
-  there is no raw-hash `sign`.
-- A payment over a policy approval threshold throws `X402ApprovalPendingError`
-  (the same class `@catena/sdk/x402` throws). Approve it in the Catena console,
-  then let the tooling retry — a retry with a fresh nonce still consumes the
-  approval.
-- A policy block or terminal failure throws `X402PaymentDeclinedError` with the
-  server's reasons; request-level failures (for example a reused nonce)
-  propagate as `ApiError` with a stable `code`.
-- Once the payment may have moved, every failure carries the intent id:
-  `X402SubmitInterruptedError` (the submission was interrupted after the payment
-  may have been claimed), `X402PaymentSignatureUnusableError` (it completed
-  carrying a signature this SDK cannot use), `X402PaymentInFlightError` (still
-  in flight — note that polling does not advance an approved x402 payment
-  resting there; it waits for the paid request to be re-run), and
-  `SignatureVerificationFailedError`. Reconcile with `getIntent(intentId)`
-  instead of paying again. Note the shape difference: the intent's
-  `data.paymentCredential.value` is the base64 x402 envelope used as the
-  `PAYMENT-SIGNATURE` header, whereas `signTypedData` returns the inner hex
-  signature decoded out of it — passing the envelope to a viem-based signer path
-  will fail on shape.
+Pass `account` to any x402 client that accepts a viem account or
+`{ address, signTypedData }` signer.
+
+A Catena wallet is custodial. The account signs only structurally valid x402
+EIP-3009 `TransferWithAuthorization` data. The server decides which EVM networks
+and canonical token contracts are payable. `signMessage`, `signTransaction`, and
+raw-hash signing are unavailable.
+
+The account must resolve to a deposit address whose source is `wallet`.
+`network` defaults to `base`; pass `arc` for an Arc wallet when enabled or
+`base-sepolia` for a testnet wallet. The network must match the wallet account.
+
+## Error handling
+
+Branch on stable fields and error classes, not message text.
+
+### Core client errors
+
+| Error               | Recovery                                                                          |
+| ------------------- | --------------------------------------------------------------------------------- |
+| `InvalidKeyError`   | Supply a valid linked P-256 private key.                                          |
+| `ApiError`          | Branch on `code`; inspect `status`, `fields`, and `details`.                      |
+| `TimeoutError`      | Treat the request as uncertain until its operation-specific recovery is complete. |
+| `IntentSubmitError` | Branch on `outcome`; use `intentId` to reconcile an uncertain submission.         |
+
+The SDK combines the API's error summary and field explanations in `message`,
+identifying the affected request fields and what needs correction. `fields`
+preserves the individual explanations keyed by request field path, such as
+`action.memo`. The `request` key represents a request-wide issue rather than a
+field; its explanation appears in `message` without a field-path prefix.
+Malformed `fields` are ignored without discarding the error's message or code.
+
+For `IntentSubmitError`:
+
+- `not-submitted` means no money moved. Fix the cause and submit again with a
+  new idempotency key.
+- `unknown` means Catena may have acted. Poll `getIntent(error.intentId)` and
+  submit again only after the intent becomes `blocked` or `failed`.
+
+A timeout means the SDK stopped waiting, not necessarily that the server stopped
+working. For an exact `submitIntent` retry after a create timeout, you must have
+chosen and persisted an `idempotencyKey` before the first call. Retry the
+unchanged action with that key.
+
+If an exact retry returns `wallet_send_intent_not_executing`,
+`x402_intent_state_mismatch`, or `mpp_intent_state_mismatch`, do not create a
+replacement payment. Reconcile the existing intent with the operator.
+
+Payment errors use CAIP-2 network IDs. Missing-counterparty errors may also
+include a server-resolved `requiredRail` whose product network identifier can be
+passed directly to a `create_counterparty` intent. Known mappings are
+`eip155:8453` to `base`, `eip155:84532` to `base-sepolia`, and `eip155:5042` to
+`arc`.
+
+<details>
+<summary><strong>x402 recovery</strong></summary>
+
+| Error                           | Recovery                                                                                              |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `X402PaymentError`              | Do not retry automatically. If no subclass provides a safe recovery path, escalate to an operator.    |
+| `X402NetworkMismatchError`      | Use an account on one of `requiredNetworks`.                                                          |
+| `X402CounterpartyNotFoundError` | Create a counterparty from `requiredRail` when present; otherwise resolve the rail manually.          |
+| `X402ApprovalPendingError`      | Approve the intent, then repeat the original request.                                                 |
+| `X402RetryFailedError`          | Payment completed. Retry manually with `receipt.paymentSignature`; do not run the payment loop again. |
+| `X402SubmitInterruptedError`    | Check `getIntent(intentId)` before paying again.                                                      |
+
+A create-phase `TimeoutError` from the x402 wrapper means no payment was
+authorized, so the request can be run again. For an interrupted submission:
+
+- `completed`: reuse `data.paymentCredential.value` as `PAYMENT-SIGNATURE`;
+- `processing`: keep polling; and
+- `blocked` or `failed`: a new payment attempt is safe.
+
+</details>
+
+<details>
+<summary><strong>MPP recovery</strong></summary>
+
+| Error                          | Recovery                                                          |
+| ------------------------------ | ----------------------------------------------------------------- |
+| `MppFetchPaymentError`         | If `intentId` is present, reconcile it before paying again.       |
+| `MppNetworkMismatchError`      | Fund the payment from one of `requiredNetworks`.                  |
+| `MppCounterpartyNotFoundError` | Create a counterparty from `requiredRail` when present.           |
+| `MppApprovalPendingError`      | Approve the intent, then repeat the original request.             |
+| `MppPaymentDeclinedError`      | Treat the result as final.                                        |
+| `MppSubmitInterruptedError`    | Reconcile `intentId` before authorizing another payment.          |
+| `MppRetryFailedError`          | Payment completed. Reconcile `receipt.intentId` before any retry. |
+
+An `MppPaymentError` from a custom mppx integration exposes `intentId`,
+`status`, `reasons`, and `expiresAt`. A completed MPP intent proves that Catena
+produced an authorization, not that the seller settled it or delivered the
+resource.
+
+When mppx makes multiple attempts, the final error identifies only its own
+intent. Reconcile every known attempt before paying again.
+
+</details>
+
+<details>
+<summary><strong>viem recovery</strong></summary>
+
+| Error                               | Meaning                                                                              |
+| ----------------------------------- | ------------------------------------------------------------------------------------ |
+| `UnsupportedTypedDataError`         | Refused client-side; nothing was submitted. Inspect `reason`.                        |
+| `UnsupportedAccountCapabilityError` | The requested signing method is not available.                                       |
+| `NotAWalletAccountError`            | Choose an account whose deposit-address source is `wallet`.                          |
+| `X402ApprovalPendingError`          | Approve the intent, then let the x402 tooling retry.                                 |
+| `X402PaymentDeclinedError`          | Policy blocked or failed the payment. This result is final.                          |
+| `X402PaymentInFlightError`          | Reconcile `intentId`. Polling will not advance it; repeat the original paid request. |
+| `X402SubmitInterruptedError`        | Reconcile `intentId`; do not pay again.                                              |
+| `X402PaymentSignatureUnusableError` | Payment completed. Reconcile `intentId`; do not pay again.                           |
+| `SignatureVerificationFailedError`  | Payment completed. Do not use the signature or pay again.                            |
+
+`data.paymentCredential.value` is the Base64 x402 envelope used as the
+`PAYMENT-SIGNATURE` header. `signTypedData` returns the inner hex signature.
+They are not interchangeable.
+
+</details>
+
+## API reference
+
+### Client methods
+
+| Method                                                   | Purpose                                                                                                                                                                                                                                        |
+| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `whoami()`                                               | Return the linked agent.                                                                                                                                                                                                                       |
+| `submitFeedback(body)`                                   | Send integration feedback to Catena operators. This has no money effect.                                                                                                                                                                       |
+| `getPolicy()`                                            | Return the agent's effective policy.                                                                                                                                                                                                           |
+| `listAccounts()`                                         | List accounts visible to the agent.                                                                                                                                                                                                            |
+| `getAccountBalance(accountId)`                           | Return total and available balances, overall and per network.                                                                                                                                                                                  |
+| `listAccountTransactions(accountId, params?)`            | List transactions with optional `start`, `end`, `limit`, and `offset`.                                                                                                                                                                         |
+| `getAccountDepositAddress(accountId, params)`            | Resolve an address for a `network` and `asset`.                                                                                                                                                                                                |
+| `listCounterparties(params?)`                            | List counterparties; address and network filters check wallet ownership within a network class. A wallet rail omits `network` when its configured destination is unavailable to the agent and cannot receive an agent send until that changes. |
+| `submitIntent({ action, idempotencyKey? })`              | Submit a policy-checked action.                                                                                                                                                                                                                |
+| `getIntent(id)`                                          | Read the current intent state.                                                                                                                                                                                                                 |
+| `continueIntent({ intentId, idempotencyKey?, action? })` | Finish the second leg of a send that crossed chains, once `crossChain.nextStep` reads `continue`. A payment carried by a movement plan is refused with `movement_admin_completes_payment`.                                                     |
+| `unlinkAgent()`                                          | Permanently revoke the current agent link and its active keys.                                                                                                                                                                                 |
+| `reportSettlement(params)`                               | Report an on-chain settlement. Managed payment wrappers call this automatically.                                                                                                                                                               |
+
+Transaction ranges use inclusive ISO 8601 `start` and `end` timestamps. `limit`
+defaults to 50 and is capped at 200; `offset` defaults to 0. `reportSettlement`
+accepts `{ intentId, txHash, receipt? }`.
+
+### Intent actions
+
+| Action                         | Purpose                                           |
+| ------------------------------ | ------------------------------------------------- |
+| `send`                         | Send by ACH, wire, or on-chain rail.              |
+| `transfer`                     | Transfer between Catena accounts.                 |
+| `create_counterparty`          | Save a counterparty with contact or rail details. |
+| `request_counterparty_details` | Request bank or wallet details.                   |
+| `x402`                         | Submit a low-level x402 payment requirement.      |
+| `mpp`                          | Submit a low-level MPP charge.                    |
+| `policy_override`              | Request a temporary increase to policy limits.    |
+
+Use the x402 and MPP helpers for ordinary protocol payments. They parse the
+challenge, enforce replay safety, submit the intent, and handle the paid retry.
+
+For direct intents, `x402` requires `accountId` and `paymentRequirements`, with
+optional `resource`, `authorization`, and `signedOffer`. `mpp` requires
+`accountId` and `challenge`, with optional `resource`.
+
+### Payment helper options
+
+| API                        | Required options               | Optional options                            |
+| -------------------------- | ------------------------------ | ------------------------------------------- |
+| `wrapFetchWithX402Payment` | `accountId`                    | `baseFetch`, `maxAtomicAmount`, `onPayment` |
+| `payX402Challenge`         | `accountId`, `paymentRequired` | `resource`, `maxAtomicAmount`               |
+| `wrapFetchWithMppPayment`  | `accountId`                    | `baseFetch`, `maxAtomicAmount`, `onPayment` |
+| `catena` / `catena.charge` | `client`, `accountId`          | `maxAtomicAmount`                           |
+| `createCatenaAccount`      | `accountId`                    | `network`                                   |
+
+`baseFetch` injects a custom transport. `onPayment` runs after Catena completes
+the payment and before the paid retry. If it throws, the payment remains
+complete and the wrapper throws a retry error carrying the receipt.
+
+### Client options
+
+| Option           | Purpose                                                                     |
+| ---------------- | --------------------------------------------------------------------------- |
+| `privateKeyHex`  | Linked 64-character P-256 private key.                                      |
+| `baseUrl`        | API origin. Defaults to the hosted Catena API.                              |
+| `identityUrl`    | Stable signer identity URL. The default follows the key thumbprint.         |
+| `appInfo`        | `{ name, version?, url? }` added to the User-Agent.                         |
+| `defaultHeaders` | Headers merged into every request. The SDK strips auth and sets User-Agent. |
+| `fetch`          | Custom fetch transport for proxies, instrumentation, or tests.              |
+| `timeout`        | Per-exchange deadline in milliseconds. Defaults to 80,000.                  |
+
+You can omit `privateKeyHex` and set `CATENA_SECRET_KEY` instead. An explicit
+value always wins, including when it is empty or invalid. The SDK validates the
+key at construction. It never stores credentials or reads CLI profiles.
+
+Each operation may make more than one HTTP exchange. Every exchange receives a
+fresh timeout; `timeout` is not an overall operation deadline. It must be a
+positive integer no greater than 2,147,483,647.
+
+`identityUrl` must be an HTTP(S) URL of at most 255 printable ASCII characters.
+`appInfo.name` and `version` must be HTTP tokens; its URL must be safe in a
+User-Agent comment.
+
+### Entry points
+
+| Import                | Public surface                                           |
+| --------------------- | -------------------------------------------------------- |
+| `@catena/sdk`         | Client, intent and account types, errors, and constants. |
+| `@catena/sdk/x402`    | Managed and low-level x402 payment APIs.                 |
+| `@catena/sdk/mpp`     | Managed MPP wrapper and Catena-backed mppx methods.      |
+| `@catena/sdk/viem`    | Custodial viem account for x402 typed data.              |
+| `@catena/sdk/keypair` | Low-level P-256 credential utilities.                    |
+
+The root entry point also exports request and response types, action unions,
+error classes, and constants for actions, policies, transactions, and send
+methods.
+
+<details>
+<summary><strong>Low-level key utilities</strong></summary>
+
+Most integrations receive a linked private key through their host flow. The
+keypair entry point is available when the host owns credential creation or
+conversion:
+
+| Export                                    | Purpose                            |
+| ----------------------------------------- | ---------------------------------- |
+| `P256Keypair`                             | P-256 private and public key data. |
+| `InvalidKeyError`                         | Invalid key input.                 |
+| `generateP256Keypair()`                   | Generate a new P-256 keypair.      |
+| `p256KeypairFromPrivateKeyHex(value)`     | Derive and validate a keypair.     |
+| `computeP256PublicKeyThumbprint(value)`   | Compute the public-key thumbprint. |
+| `p256PointFromCompressedHex(value)`       | Decode a compressed public key.    |
+| `p256PublicKeyThumbprintFromPoint(value)` | Thumbprint a decoded public point. |
+
+The SDK never persists a generated private key or links its public half to an
+agent. The host owns both steps.
+
+</details>
+
+## Stability
+
+The SDK is in initial development. Patch releases within a `0.x` minor are
+intended to remain compatible. A new minor may change the public API. Test the
+upgrade before moving to a new `0.x` minor.
 
 ## License