@catena/sdk 0.0.0-bootstrap.0 → 0.1.0

package/dist/viem.d.mts

@@ -0,0 +1,135 @@
+import { F as OnchainNetworkInput, U as X402Authorization, W as X402PaymentRequirements, a as IntentSubmitError, n as CatenaClient, t as ApiError } from "./client-Cm2wNUuB.mjs";
+import { X402ApprovalPendingError, X402PaymentError, X402SubmitInterruptedError } from "./x402.mjs";
+import { LocalAccount } from "viem";
+//#region src/viem.d.ts
+/**
+ * The account was asked for a capability a custodial Catena wallet does not
+ * have. The wallet's signing policy authorizes only EIP-3009
+ * `TransferWithAuthorization` typed data; `signMessage`, `signTransaction`,
+ * and raw-hash signing are structurally unavailable.
+ */
+declare class UnsupportedAccountCapabilityError extends Error {
+  readonly capability: "signMessage" | "signTransaction";
+  constructor(capability: "signMessage" | "signTransaction");
+}
+/**
+ * Machine-readable reason a typed-data payload was refused before any
+ * request was made. Branch on `reason`, not message prose.
+ */
+type UnsupportedTypedDataReason = "primary_type" | "types" | "network" | "asset" | "domain" | "message" | "nonce" | "from_mismatch" | "recipient" | "expired" | "window";
+/**
+ * The typed data is not something a Catena wallet can sign. Thrown
+ * client-side, before any intent exists; nothing was submitted or paid.
+ */
+declare class UnsupportedTypedDataError extends Error {
+  readonly reason: UnsupportedTypedDataReason;
+  constructor(reason: UnsupportedTypedDataReason, message: string);
+}
+/**
+ * The account id resolves to a liquidation deposit address rather than the
+ * wallet's own address. x402 authorizations can only be signed for a wallet
+ * account; pick an account whose deposit address source is `wallet`.
+ */
+declare class NotAWalletAccountError extends Error {
+  readonly accountId: string;
+  readonly source: string;
+  constructor(accountId: string, source: string);
+}
+/**
+ * Catena declined the payment (policy block or terminal failure). `reasons`
+ * carries the server's detail; the same struct will not succeed on retry.
+ */
+declare class X402PaymentDeclinedError extends X402PaymentError {
+  readonly intentId: string;
+  constructor(intentId: string, reasons: readonly string[]);
+}
+/**
+ * The payment was accepted and is still in flight, which a synchronous
+ * `signTypedData` cannot resume. Do not pay again on the strength of this:
+ * reconcile the intent instead. Note that polling does not advance an
+ * approved x402 payment resting in this state — it waits for the paid
+ * request to be re-run.
+ */
+declare class X402PaymentInFlightError extends X402PaymentError {
+  readonly intentId: string;
+  constructor(intentId: string, status: string);
+}
+/**
+ * The payment completed but the signature it carried cannot be used — absent,
+ * or an envelope this SDK could not decode. The money has moved, so this is
+ * not a retry: reconcile the intent before paying again. Re-reading it will
+ * return the same unusable value, so recovery here means reconciling the
+ * payment with the operator, not fetching the signature again.
+ */
+declare class X402PaymentSignatureUnusableError extends X402PaymentError {
+  readonly intentId: string;
+  constructor(intentId: string, message: string);
+}
+/**
+ * The completed payment's signature did not recover to the wallet address
+ * for the typed data that was submitted. The signature must not be used;
+ * this indicates server-side drift and is worth reporting.
+ *
+ * An `X402PaymentError` because it is thrown after the payment completed:
+ * money has moved, so it belongs to the family a caller branches on before
+ * deciding whether to pay again. Reconcile with `getIntent(intentId)`.
+ */
+declare class SignatureVerificationFailedError extends X402PaymentError {
+  readonly intentId: string;
+  readonly expectedAddress: string;
+  readonly recoveredAddress: string | undefined;
+  constructor(intentId: string, expectedAddress: string, recoveredAddress: string | undefined);
+}
+interface CatenaAccountOptions {
+  /**
+   * The wallet account payments draw from. Its deposit address must resolve
+   * with source `wallet`.
+   */
+  accountId: string;
+  /**
+   * Network used to resolve the wallet address once at creation, defaulting
+   * to `base`. It must be the network the wallet account is configured for:
+   * a wallet accepts deposits on exactly one network, and asking for another
+   * fails the call rather than falling back. Pass `base-sepolia` explicitly
+   * for a testnet wallet. The same network then bounds what the account can
+   * pay: typed data naming the other supported chain is refused server-side,
+   * because the account cannot fund a payment off its own network.
+   */
+  network?: OnchainNetworkInput;
+}
+/**
+ * The account shape `createCatenaAccount` resolves to: a viem local account
+ * whose only working capability is `signTypedData` for x402 EIP-3009
+ * payment authorizations.
+ */
+type CatenaAccount = LocalAccount;
+/**
+ * Present a Catena wallet as a viem `Account` for x402 client tooling.
+ *
+ * The returned account's `signTypedData` accepts exactly one shape — EIP-3009
+ * `TransferWithAuthorization` for USDC on Base or Base Sepolia, the payload
+ * x402 exact-scheme clients construct — and routes it through a Catena x402
+ * intent: policy evaluates the payment, the custodial key signs the caller's
+ * exact struct, and the signature is verified to recover to the wallet
+ * address before it is returned. `signMessage` and `signTransaction` throw
+ * `UnsupportedAccountCapabilityError`; there is no raw-hash `sign`.
+ *
+ * Failure modes: `UnsupportedTypedDataError` (refused client-side, nothing
+ * submitted), `X402ApprovalPendingError` (parked for a human approval —
+ * approve in the console, then have the tooling retry; a retry with a fresh
+ * nonce still consumes the approval), `X402PaymentDeclinedError` (policy
+ * block or terminal failure), and — all of these after the payment may have
+ * moved, so reconcile with `getIntent(intentId)` rather than paying again —
+ * `SignatureVerificationFailedError` (the returned signature did not verify
+ * and was withheld), `X402SubmitInterruptedError`,
+ * `X402PaymentSignatureUnusableError`, and `X402PaymentInFlightError`. Then
+ * `IntentSubmitError` with `outcome: "not-submitted"` (the
+ * intent exists but nothing was submitted and no money moved, so a retry is
+ * safe), and `ApiError` for request-level failures such as a reused nonce.
+ *
+ * Requires the optional `viem` peer dependency; importing this module
+ * without viem installed fails with a module-not-found error naming it.
+ */
+declare function createCatenaAccount(client: CatenaClient, options: CatenaAccountOptions): Promise<CatenaAccount>;
+//#endregion
+export { ApiError, CatenaAccount, CatenaAccountOptions, IntentSubmitError, NotAWalletAccountError, type OnchainNetworkInput, SignatureVerificationFailedError, UnsupportedAccountCapabilityError, UnsupportedTypedDataError, UnsupportedTypedDataReason, X402ApprovalPendingError, type X402Authorization, X402PaymentDeclinedError, X402PaymentError, X402PaymentInFlightError, type X402PaymentRequirements, X402PaymentSignatureUnusableError, X402SubmitInterruptedError, createCatenaAccount };

package/dist/viem.mjs

@@ -0,0 +1,301 @@
+import { b as x402CredentialFromIntentData, n as IntentSubmitError, t as ApiError } from "./client-CHZMO00P.mjs";
+import { X402ApprovalPendingError, X402PaymentError, X402SubmitInterruptedError } from "./x402.mjs";
+import * as v from "valibot";
+import { getAddress, isAddress, isHex, recoverTypedDataAddress } from "viem";
+import { toAccount } from "viem/accounts";
+//#region src/viem.ts
+const NETWORKS = {
+	"8453": {
+		network: "eip155:8453",
+		usdc: getAddress("0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913")
+	},
+	"84532": {
+		network: "eip155:84532",
+		usdc: getAddress("0x036CbD53842c5426634e7929541eC2318f3dCF7e")
+	}
+};
+const EIP712_DOMAIN_TYPE = [
+	{
+		name: "name",
+		type: "string"
+	},
+	{
+		name: "version",
+		type: "string"
+	},
+	{
+		name: "chainId",
+		type: "uint256"
+	},
+	{
+		name: "verifyingContract",
+		type: "address"
+	}
+];
+const CANONICAL_DOMAIN_FIELDS = new Set([
+	"name",
+	"version",
+	"chainId",
+	"verifyingContract"
+]);
+const TRANSFER_WITH_AUTHORIZATION_TYPES = { TransferWithAuthorization: [
+	{
+		name: "from",
+		type: "address"
+	},
+	{
+		name: "to",
+		type: "address"
+	},
+	{
+		name: "value",
+		type: "uint256"
+	},
+	{
+		name: "validAfter",
+		type: "uint256"
+	},
+	{
+		name: "validBefore",
+		type: "uint256"
+	},
+	{
+		name: "nonce",
+		type: "bytes32"
+	}
+] };
+const MIN_REMAINING_VALIDITY_SECONDS = 5;
+const MAX_TIMEOUT_SECONDS = 3600;
+const VALIDBEFORE_SKEW_SECONDS = 30;
+var UnsupportedAccountCapabilityError = class extends Error {
+	capability;
+	constructor(capability) {
+		super(`A Catena wallet is custodial and its signing policy authorizes only EIP-3009 TransferWithAuthorization typed data; ${capability} is not available. Use signTypedData with an x402 payment authorization.`);
+		this.name = "UnsupportedAccountCapabilityError";
+		this.capability = capability;
+	}
+};
+var UnsupportedTypedDataError = class extends Error {
+	reason;
+	constructor(reason, message) {
+		super(message);
+		this.name = "UnsupportedTypedDataError";
+		this.reason = reason;
+	}
+};
+var NotAWalletAccountError = class extends Error {
+	accountId;
+	source;
+	constructor(accountId, source) {
+		super(`Account ${accountId} resolves to a ${source} deposit address, not the wallet's own address; x402 authorizations can only be signed for a wallet account`);
+		this.name = "NotAWalletAccountError";
+		this.accountId = accountId;
+		this.source = source;
+	}
+};
+var X402PaymentDeclinedError = class extends X402PaymentError {
+	intentId;
+	constructor(intentId, reasons) {
+		super(`Catena declined the payment (intent ${intentId})`, reasons);
+		this.name = "X402PaymentDeclinedError";
+		this.intentId = intentId;
+	}
+};
+var X402PaymentInFlightError = class extends X402PaymentError {
+	intentId;
+	constructor(intentId, status) {
+		super(`The payment is still ${status} (intent ${intentId}); this client cannot resume an in-flight x402 settlement. Reconcile with getIntent("${intentId}") rather than paying again`);
+		this.name = "X402PaymentInFlightError";
+		this.intentId = intentId;
+	}
+};
+var X402PaymentSignatureUnusableError = class extends X402PaymentError {
+	intentId;
+	constructor(intentId, message) {
+		super(`${message} (intent ${intentId}); the payment may have settled — check getIntent("${intentId}") before paying again`);
+		this.name = "X402PaymentSignatureUnusableError";
+		this.intentId = intentId;
+	}
+};
+var SignatureVerificationFailedError = class extends X402PaymentError {
+	intentId;
+	expectedAddress;
+	recoveredAddress;
+	constructor(intentId, expectedAddress, recoveredAddress) {
+		super(`The signature for intent ${intentId} did not recover to the wallet address; do not use it. The payment may have settled — check getIntent("${intentId}") before paying again`);
+		this.name = "SignatureVerificationFailedError";
+		this.intentId = intentId;
+		this.expectedAddress = expectedAddress;
+		this.recoveredAddress = recoveredAddress;
+	}
+};
+const MAX_UINT256 = 2n ** 256n - 1n;
+const uint256Schema = v.pipe(v.union([
+	v.pipe(v.string(), v.regex(/^(0|[1-9]\d*)$/), v.maxLength(78)),
+	v.pipe(v.number(), v.check((value) => Number.isSafeInteger(value) && value >= 0)),
+	v.pipe(v.bigint(), v.check((value) => value >= 0n))
+]), v.check((value) => {
+	const decimal = toDecimalString(value);
+	return /^\d+$/.test(decimal) && BigInt(decimal) <= MAX_UINT256;
+}));
+const typedDataInputSchema = v.looseObject({
+	primaryType: v.string(),
+	domain: v.looseObject({
+		name: v.optional(v.string()),
+		version: v.optional(v.string()),
+		chainId: v.optional(v.union([v.number(), v.bigint()])),
+		verifyingContract: v.optional(v.string())
+	}),
+	types: v.record(v.string(), v.unknown()),
+	message: v.looseObject({
+		from: v.string(),
+		to: v.string(),
+		value: uint256Schema,
+		validAfter: uint256Schema,
+		validBefore: uint256Schema,
+		nonce: v.string()
+	})
+});
+const paymentSignatureEnvelopeSchema = v.looseObject({ payload: v.looseObject({ signature: v.string() }) });
+function decodeBase64Json(value) {
+	const normalized = value.replaceAll("-", "+").replaceAll("_", "/");
+	try {
+		const bytes = Uint8Array.from(atob(normalized), (char) => char.charCodeAt(0));
+		return JSON.parse(new TextDecoder().decode(bytes));
+	} catch {
+		return;
+	}
+}
+function toDecimalString(value) {
+	return typeof value === "string" ? value : value.toString();
+}
+const typeTableSchema = v.array(v.looseObject({
+	name: v.string(),
+	type: v.string()
+}));
+function encodeTypeTable(value) {
+	const parsed = v.safeParse(typeTableSchema, value);
+	return parsed.success ? JSON.stringify(parsed.output.map((entry) => [entry.name, entry.type])) : void 0;
+}
+function encodeCanonicalTable(table) {
+	return JSON.stringify(table.map((entry) => [entry.name, entry.type]));
+}
+const CANONICAL_TRANSFER_TYPE = encodeCanonicalTable(TRANSFER_WITH_AUTHORIZATION_TYPES.TransferWithAuthorization);
+const CANONICAL_DOMAIN_TYPE = encodeCanonicalTable(EIP712_DOMAIN_TYPE);
+function isEvmAddress(value) {
+	return isAddress(value);
+}
+async function createCatenaAccount(client, options) {
+	const deposit = await client.getAccountDepositAddress(options.accountId, {
+		network: options.network ?? "base",
+		asset: "usdc"
+	});
+	if (deposit.source !== "wallet") throw new NotAWalletAccountError(options.accountId, deposit.source);
+	const address = getAddress(deposit.address);
+	return toAccount({
+		address,
+		signMessage: () => Promise.reject(new UnsupportedAccountCapabilityError("signMessage")),
+		signTransaction: () => Promise.reject(new UnsupportedAccountCapabilityError("signTransaction")),
+		signTypedData: (parameters) => signX402TypedData(client, {
+			accountId: options.accountId,
+			address,
+			parameters
+		})
+	});
+}
+async function signX402TypedData(client, args) {
+	const parsed = v.safeParse(typedDataInputSchema, args.parameters);
+	if (!parsed.success) throw new UnsupportedTypedDataError("message", "The typed data is not a TransferWithAuthorization payload this account can sign");
+	const { primaryType, domain, types, message } = parsed.output;
+	if (primaryType !== "TransferWithAuthorization") throw new UnsupportedTypedDataError("primary_type", `This account signs only TransferWithAuthorization typed data; got ${primaryType}`);
+	const transferType = types["TransferWithAuthorization"];
+	if (encodeTypeTable(transferType) !== CANONICAL_TRANSFER_TYPE) throw new UnsupportedTypedDataError("types", "The TransferWithAuthorization type definition does not match EIP-3009");
+	if (domain.chainId === void 0) throw new UnsupportedTypedDataError("network", "The typed data names no chainId");
+	const chain = Object.hasOwn(NETWORKS, String(domain.chainId)) ? NETWORKS[String(domain.chainId)] : void 0;
+	if (!chain) throw new UnsupportedTypedDataError("network", `Chain ${String(domain.chainId)} is not supported; use Base (8453) or Base Sepolia (84532)`);
+	if (domain.verifyingContract === void 0 || !isEvmAddress(domain.verifyingContract) || getAddress(domain.verifyingContract) !== chain.usdc) throw new UnsupportedTypedDataError("asset", `The verifying contract must be USDC ${chain.usdc} on chain ${String(domain.chainId)}`);
+	if (!domain.name || !domain.version) throw new UnsupportedTypedDataError("domain", "The typed-data domain must carry the token's name and version");
+	const unsupportedDomainFields = Object.entries(domain).filter(([key, value]) => !CANONICAL_DOMAIN_FIELDS.has(key) && value !== void 0).map(([key]) => key);
+	if (unsupportedDomainFields.length > 0) throw new UnsupportedTypedDataError("domain", `The typed-data domain carries fields this account cannot sign over: ${unsupportedDomainFields.join(", ")}`);
+	const domainType = types["EIP712Domain"];
+	if (domainType !== void 0 && encodeTypeTable(domainType) !== CANONICAL_DOMAIN_TYPE) throw new UnsupportedTypedDataError("domain", "The EIP712Domain type definition must be the canonical name, version, chainId, verifyingContract");
+	const nonce = message.nonce.toLowerCase();
+	if (!/^0x[0-9a-f]{64}$/.test(nonce) || !isHex(nonce)) throw new UnsupportedTypedDataError("nonce", "The nonce must be 32 bytes of hex");
+	if (!isEvmAddress(message.from) || getAddress(message.from) !== args.address) throw new UnsupportedTypedDataError("from_mismatch", `The authorization must draw from this account's wallet address ${args.address}`);
+	if (!isEvmAddress(message.to)) throw new UnsupportedTypedDataError("recipient", "The authorization's recipient must be a 20-byte hex address, either all-lowercase or with a valid EIP-55 checksum");
+	const nowSeconds = Math.floor(Date.now() / 1e3);
+	const validAfter = BigInt(toDecimalString(message.validAfter));
+	const validBefore = BigInt(toDecimalString(message.validBefore));
+	if (validBefore <= BigInt(nowSeconds + MIN_REMAINING_VALIDITY_SECONDS)) throw new UnsupportedTypedDataError("expired", "The authorization expires too soon to settle; build one with more validity");
+	if (validAfter >= validBefore) throw new UnsupportedTypedDataError("window", "The authorization expires before it becomes valid");
+	if (validAfter > BigInt(nowSeconds)) throw new UnsupportedTypedDataError("window", "The authorization must already be valid; it starts in the future");
+	if (validBefore > BigInt(nowSeconds + MAX_TIMEOUT_SECONDS + VALIDBEFORE_SKEW_SECONDS)) throw new UnsupportedTypedDataError("window", `The authorization is valid for longer than the ${MAX_TIMEOUT_SECONDS}s a payment may be authorized for`);
+	const authorization = {
+		from: message.from,
+		to: message.to,
+		value: toDecimalString(message.value),
+		validAfter: toDecimalString(message.validAfter),
+		validBefore: toDecimalString(message.validBefore),
+		nonce
+	};
+	const paymentRequirements = {
+		scheme: "exact",
+		network: chain.network,
+		asset: getAddress(domain.verifyingContract),
+		amount: authorization.value,
+		payTo: message.to,
+		maxTimeoutSeconds: Math.min(MAX_TIMEOUT_SECONDS, Math.max(1, Number(validBefore - validAfter))),
+		extra: {
+			name: domain.name,
+			version: domain.version
+		}
+	};
+	const intent = await client.submitIntent({
+		action: {
+			type: "x402",
+			accountId: args.accountId,
+			paymentRequirements,
+			authorization
+		},
+		idempotencyKey: crypto.randomUUID()
+	}).catch((err) => {
+		if (err instanceof IntentSubmitError && err.outcome === "unknown") throw new X402SubmitInterruptedError(err.intentId, paymentRequirements, err);
+		throw err;
+	});
+	if (intent.status === "pending") throw new X402ApprovalPendingError(intent.id, intent.reasons, intent.expiresAt);
+	if (intent.status === "blocked" || intent.status === "failed") throw new X402PaymentDeclinedError(intent.id, intent.reasons);
+	if (intent.status !== "completed") throw new X402PaymentInFlightError(intent.id, intent.status);
+	const paymentSignature = x402CredentialFromIntentData(intent.data);
+	if (paymentSignature === void 0) throw new X402PaymentSignatureUnusableError(intent.id, "The completed payment did not carry an x402 payment signature");
+	const envelope = v.safeParse(paymentSignatureEnvelopeSchema, decodeBase64Json(paymentSignature));
+	if (!envelope.success || !isHex(envelope.output.payload.signature)) throw new X402PaymentSignatureUnusableError(intent.id, "The payment signature payload could not be decoded");
+	const signature = envelope.output.payload.signature;
+	let recovered;
+	try {
+		recovered = await recoverTypedDataAddress({
+			domain: {
+				name: domain.name,
+				version: domain.version,
+				chainId: Number(domain.chainId),
+				verifyingContract: getAddress(domain.verifyingContract)
+			},
+			types: TRANSFER_WITH_AUTHORIZATION_TYPES,
+			primaryType: "TransferWithAuthorization",
+			message: {
+				from: getAddress(message.from),
+				to: getAddress(message.to),
+				value: BigInt(authorization.value),
+				validAfter: BigInt(authorization.validAfter),
+				validBefore: BigInt(authorization.validBefore),
+				nonce
+			},
+			signature
+		});
+	} catch {
+		recovered = void 0;
+	}
+	if (recovered !== args.address) throw new SignatureVerificationFailedError(intent.id, args.address, recovered);
+	return signature;
+}
+//#endregion
+export { ApiError, IntentSubmitError, NotAWalletAccountError, SignatureVerificationFailedError, UnsupportedAccountCapabilityError, UnsupportedTypedDataError, X402ApprovalPendingError, X402PaymentDeclinedError, X402PaymentError, X402PaymentInFlightError, X402PaymentSignatureUnusableError, X402SubmitInterruptedError, createCatenaAccount };

package/dist/x402.d.mts

@@ -0,0 +1,206 @@
+import { G as X402Resource, W as X402PaymentRequirements, i as FetchLike, n as CatenaClient } from "./client-Cm2wNUuB.mjs";
+import * as v from "valibot";
+//#region src/x402.d.ts
+declare const paymentRequiredSchema: v.LooseObjectSchema<{
+  /**
+   * Pinned to the wire version this loop speaks. Paying a v1 or future
+   * incompatible challenge would settle money for a retry header the server
+   * cannot consume.
+   */
+  readonly x402Version: v.LiteralSchema<2, undefined>;
+  readonly accepts: v.ArraySchema<v.LooseObjectSchema<{
+    readonly scheme: v.StringSchema<undefined>;
+    readonly network: v.StringSchema<undefined>;
+    readonly asset: v.StringSchema<undefined>;
+    readonly amount: v.StringSchema<undefined>;
+    readonly payTo: v.StringSchema<undefined>;
+    readonly maxTimeoutSeconds: v.NumberSchema<undefined>;
+  }, undefined>, undefined>;
+  readonly resource: v.OptionalSchema<v.LooseObjectSchema<{
+    readonly url: v.StringSchema<undefined>;
+    readonly serviceName: v.SchemaWithFallback<v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 255, undefined>]>, undefined>, undefined>;
+  }, undefined>, undefined>;
+  /**
+   * x402 v2 extension envelope; may carry the seller's signed offers
+   * (offer-receipt extension). Untyped here — extraction is tolerant.
+   */
+  readonly extensions: v.OptionalSchema<v.UnknownSchema, undefined>;
+}, undefined>;
+type X402PaymentRequired = v.InferOutput<typeof paymentRequiredSchema>;
+/**
+ * Decode a 402 response's `PAYMENT-REQUIRED` challenge. Returns undefined for
+ * a 402 that carries no decodable v2 challenge (not an x402 endpoint).
+ */
+declare function decodePaymentRequired(response: Response): X402PaymentRequired | undefined;
+/**
+ * Payment failure raised by this module; `reasons` carries the policy or
+ * decline detail when the server provided any, and subclasses mark the cases
+ * with a specific recovery path. Not every loop failure is one of these:
+ * a create-phase `ApiError` the loop does not absorb as a candidate skip
+ * and a "not-submitted" `IntentSubmitError` propagate unchanged. A create-phase
+ * `TimeoutError` also propagates unchanged; no payment was authorized, so
+ * re-running cannot double-pay.
+ */
+declare class X402PaymentError extends Error {
+  readonly reasons: readonly string[];
+  constructor(message: string, reasons?: readonly string[],
+  /**
+   * Subclasses whose message is a single actionable recovery sentence pass
+   * `false` so `reasons` stays inspection detail on the property instead of
+   * restating server text mid-sentence in the primary output.
+   */
+  options?: {
+    appendReasonsToMessage?: boolean;
+  });
+}
+/**
+ * Every payable candidate in the challenge targets a network the source
+ * account is not on, so nothing could be funded. Distinct from a generic
+ * non-payable requirement: the fix is to fund the payment from a wallet
+ * account on one of `requiredNetworks`, not to change policy. Consumers can
+ * name those networks (and, for a CLI, tell the user how to switch accounts).
+ */
+declare class X402NetworkMismatchError extends X402PaymentError {
+  readonly accountId: string;
+  readonly requiredNetworks: readonly string[];
+  constructor(accountId: string, requiredNetworks: readonly string[], reasons?: readonly string[]);
+}
+/**
+ * The challenge's `payTo` is not a saved counterparty wallet rail, so the
+ * allowlist has nothing to authorize and the payment fails closed. The 402's
+ * `payTo` is attacker-controlled, so Catena never auto-adds it: the fix is a
+ * deliberate `create_counterparty` (itself policy-gated) for `payTo` on
+ * `network`, then a re-run. Consumers can name the recipient (and, for a CLI,
+ * print the exact counterparty-create command).
+ */
+declare class X402CounterpartyNotFoundError extends X402PaymentError {
+  readonly payTo: string;
+  readonly network: string;
+  /**
+   * The challenge's advertised service name, when present — a suggested
+   * counterparty name.
+   */
+  readonly serviceName: string | undefined;
+  constructor(payTo: string, network: string, serviceName?: string, reasons?: readonly string[]);
+}
+/**
+ * The payment exceeded a policy limit and is parked for a human approval.
+ * Not a decline: once an operator approves it in the console, re-running the
+ * same request (same endpoint, same price) consumes the approval and pays.
+ * `expiresAt` is when the pending approval self-expires.
+ */
+declare class X402ApprovalPendingError extends X402PaymentError {
+  readonly intentId: string;
+  readonly expiresAt: string | null;
+  constructor(intentId: string, reasons: readonly string[], expiresAt: string | null);
+}
+/**
+ * The x402 loop failed AFTER the payment settled, either in `onPayment` or the
+ * paid retry. The paid retry may not have been issued. The receipt is the
+ * caller's recovery handle: retry the request manually with its
+ * `paymentSignature` as the `PAYMENT-SIGNATURE` header (also re-readable via
+ * `getIntent(intentId)` at `data.paymentCredential.value` while the
+ * authorization is valid) — re-running the whole loop would mint a second
+ * payment.
+ */
+declare class X402RetryFailedError extends X402PaymentError {
+  readonly receipt: X402PaymentReceipt;
+  constructor(receipt: X402PaymentReceipt, cause: unknown);
+}
+/**
+ * The submission failed after the intent was created with its outcome
+ * unknown — the server may have already claimed and settled (a response lost
+ * in transit is the canonical case). Re-running the loop would mint a second
+ * intent and risk a double-pay, so the caller must reconcile via
+ * `getIntent(intentId)`: if it completed, reuse
+ * `data.paymentCredential.value` as the `PAYMENT-SIGNATURE` header; if
+ * processing, it is mid-settlement — keep polling. Pay again only once it is
+ * terminally blocked or failed.
+ */
+declare class X402SubmitInterruptedError extends X402PaymentError {
+  readonly intentId: string;
+  readonly requirements: X402PaymentRequirements;
+  constructor(intentId: string, requirements: X402PaymentRequirements, cause: unknown);
+}
+interface X402PaymentReceipt {
+  /**
+   * The Catena intent that settled the payment; pass to `getIntent`.
+   */
+  intentId: string;
+  /**
+   * Encoded value for the retry's `PAYMENT-SIGNATURE` header. Re-readable
+   * via `getIntent(intentId)` at `data.paymentCredential.value` while the
+   * authorization is valid.
+   */
+  paymentSignature: string;
+  /**
+   * The challenge candidate that was paid.
+   */
+  requirements: X402PaymentRequirements;
+}
+/**
+ * Pay one decoded 402 challenge from `accountId` and return the
+ * `PAYMENT-SIGNATURE` header value. Tries the challenge's exact-scheme
+ * candidates in order, skipping ones Catena reports as unpayable (wrong
+ * network/asset). When nothing is payable, the terminal error reflects the
+ * most actionable skip — an unsaved counterparty, then an unfunded network —
+ * and every skipped candidate's reason rides its `reasons`. Failures the
+ * loop does not absorb as a skip — policy blocks, counterparty rejections,
+ * signing failures — surface as `X402PaymentError` (or the underlying
+ * `ApiError` / `IntentSubmitError`). A create-phase `TimeoutError`
+ * propagates unchanged; no payment was authorized, so re-running cannot
+ * double-pay.
+ */
+declare function payX402Challenge(client: CatenaClient, args: {
+  accountId: string;
+  paymentRequired: X402PaymentRequired;
+  /**
+   * Display override for the challenge's own `resource` (for example a
+   * suggested counterparty name). The signed offer/receipt evidence is
+   * bound to the resolved resource's `url`, so overriding it with a URL
+   * that differs from the one the seller signed makes the seller's offer
+   * record a resource mismatch in its stored verification. The payment
+   * itself is unaffected. Omit to use the challenge's resource unchanged.
+   */
+  resource?: X402Resource;
+  /**
+   * Per-call ceiling in atomic USDC units (6 decimals; "1000000" = $1).
+   * The org policy's spend limits still govern server-side; this lets the
+   * caller refuse a price it never meant to accept, before any intent.
+   */
+  maxAtomicAmount?: bigint;
+}): Promise<X402PaymentReceipt>;
+interface X402FetchOptions {
+  /**
+   * Source wallet account the payments draw from.
+   */
+  accountId: string;
+  baseFetch?: FetchLike;
+  /**
+   * Per-call price ceiling in atomic USDC units (6 decimals). Challenges
+   * asking for more are refused before any intent is created.
+   */
+  maxAtomicAmount?: bigint;
+  /**
+   * Called after each successful payment, before the retry — for receipts,
+   * logging, or spend telemetry. A thrown error becomes an
+   * `X402RetryFailedError` carrying the receipt.
+   */
+  onPayment?: (receipt: X402PaymentReceipt) => void | Promise<void>;
+}
+/**
+ * Wrap `fetch` so a v2 x402 402 is paid via Catena and retried once with the
+ * `PAYMENT-SIGNATURE` header. Non-402 responses (and 402s without a decodable
+ * challenge) pass through untouched. Throws `X402PaymentError` before paying
+ * when the request body cannot be replayed — pass bodies via the `init`
+ * argument as a string, `URLSearchParams`, Blob, ArrayBuffer, or typed
+ * array/DataView; a `Request` input must be bodiless. Payment failures surface
+ * as `X402PaymentError` (or a subclass documenting its recovery path); an
+ * `ApiError` the loop does not absorb as a candidate skip and a "not-submitted"
+ * `IntentSubmitError` propagate unchanged. A create-phase `TimeoutError` also
+ * propagates unchanged; no payment was authorized, so re-running cannot
+ * double-pay.
+ */
+declare function wrapFetchWithX402Payment(client: CatenaClient, options: X402FetchOptions): FetchLike;
+//#endregion
+export { X402ApprovalPendingError, X402CounterpartyNotFoundError, X402FetchOptions, X402NetworkMismatchError, X402PaymentError, X402PaymentReceipt, X402PaymentRequired, type X402PaymentRequirements, type X402Resource, X402RetryFailedError, X402SubmitInterruptedError, decodePaymentRequired, payX402Challenge, wrapFetchWithX402Payment };