@catena/sdk 0.0.0-bootstrap.0 → 0.4.0

package/README.md

@@ -1,4 +1,912 @@
 # @catena/sdk
 
-Bootstrap placeholder. Use @catena/sdk@latest once the CI-published release is
-available.
+**Build agents that can move money without bypassing policy or approvals.**
+
+`@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.
+
+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
+```
+
+## 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 })
+```
+
+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
+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 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,
+})
+```
+
+`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
+for (const { network, available } of balance.balances?.byNetwork ?? []) {
+  console.log(network, available.amount)
+}
+```
+
+`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.
+
+`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.
+
+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:
+
+```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,
+    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",
+    },
+  },
+})
+```
+
+`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.
+
+</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",
+    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".
+}
+```
+
+`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 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",
+  },
+})
+```
+
+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({ privateKeyHex })
+const fetchWithPayment = wrapFetchWithX402Payment(client, {
+  accountId: walletAccountId,
+  maxAtomicAmount: 1_000_000n,
+})
+
+const response = await fetchWithPayment("https://api.example.com/paid-thing")
+```
+
+`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.
+
+</details>
+
+### Pay MPP challenges
+
+Install the optional peers with the SDK:
+
+```sh
+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 {
+  MppCounterpartyNotFoundError,
+  wrapFetchWithMppPayment,
+} from "@catena/sdk/mpp"
+
+const client = createCatenaClient({ privateKeyHex })
+const fetchWithPayment = wrapFetchWithMppPayment(client, {
+  accountId: walletAccountId,
+  maxAtomicAmount: 1_000_000n,
+})
+
+const response = await fetchWithPayment("https://api.example.com/paid-thing")
+```
+
+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({ privateKeyHex })
+
+const mppx = Mppx.create({
+  methods: [
+    catena({
+      client,
+      accountId: walletAccountId,
+      maxAtomicAmount: 1_000_000n,
+    }),
+  ],
+  maxPaymentRetries: 1,
+  polyfill: false,
+})
+
+const response = await mppx.fetch("https://api.example.com/paid-thing")
+```
+
+`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 }`:
+
+```sh
+npm install @catena/sdk viem@^2.21
+```
+
+```ts
+import { createCatenaClient } from "@catena/sdk"
+import { createCatenaAccount } from "@catena/sdk/viem"
+
+const client = createCatenaClient({ privateKeyHex })
+const account = await createCatenaAccount(client, {
+  accountId: walletAccountId,
+  network: "base",
+})
+```
+
+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
+
+[Apache-2.0](./LICENSE)