@catena/sdk 0.0.0-bootstrap.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,191 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright (c) 2025-2026 Catena Labs, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,4 +1,481 @@
 # @catena/sdk
 
-Bootstrap placeholder. Use @catena/sdk@latest once the CI-published release is
-available.
+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.
+
+## Status
+
+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.
+
+```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.
+
+```ts
+import { createCatenaClient } from "@catena/sdk"
+
+const client = createCatenaClient({
+  privateKeyHex: privateKeyFromSecretManager,
+})
+```
+
+```ts
+import { generateP256Keypair } from "@catena/sdk/keypair"
+
+const keypair = generateP256Keypair()
+// Persist keypair.privateKeyHex yourself; link keypair.publicKeyHex to an
+// agent in a host app before the client can authenticate.
+```
+
+## Quickstart
+
+```ts
+import { createCatenaClient } from "@catena/sdk"
+
+// CATENA_SECRET_KEY contains the linked P-256 private key.
+const client = createCatenaClient()
+
+const { accounts } = await client.listAccounts()
+const { counterparties } = await client.listCounterparties()
+
+await client.submitIntent({
+  action: {
+    type: "create_counterparty",
+    name: "Acme Vendor",
+    email: "billing@acme.test",
+  },
+})
+
+// Email-only creation saves a counterparty without sending an email. A completed
+// intent returns data.counterparty with status "awaiting_details" and no rails.
+
+await client.submitIntent({
+  action: {
+    type: "request_counterparty_details",
+    counterpartyId: counterparties[0].id,
+    methods: { bank: true, wallet: false },
+  },
+})
+
+// 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.
+
+// 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")!
+
+const 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",
+  },
+})
+```
+
+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:
+
+```ts
+const client = createCatenaClient({
+  timeout: 30_000,
+})
+```
+
+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.
+
+```ts
+import { createCatenaClient } from "@catena/sdk"
+import { wrapFetchWithX402Payment } from "@catena/sdk/x402"
+
+const client = createCatenaClient()
+
+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.
+
+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.
+
+## Paying 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:
+
+```sh
+npm install @catena/sdk mppx@0.9.0 viem@^2.54.0
+```
+
+```ts
+import { createCatenaClient } from "@catena/sdk"
+import { wrapFetchWithMppPayment } from "@catena/sdk/mpp"
+
+const client = createCatenaClient()
+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:
+
+```ts
+import { createCatenaClient } from "@catena/sdk"
+import { catena } from "@catena/sdk/mpp"
+import { Mppx } from "mppx/client"
+
+const client = createCatenaClient()
+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(...)` 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:
+
+```ts
+const response = await mppx.fetch("https://api.example.com/paid-thing", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ query: "example" }),
+})
+```
+
+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 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.
+
+## License
+
+[Apache-2.0](./LICENSE)