agent0-sdk 1.5.3 → 1.7.0

package/dist/core/x402-payment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402-payment.d.ts","sourceRoot":"","sources":["../../src/core/x402-payment.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAuEzD;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,UAAU,EAClB,WAAW,EAAE,WAAW,GACvB,OAAO,CAAC,OAAO,CAAC,CAgBlB;AAyDD;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,UAAU,EAClB,WAAW,EAAE,WAAW,EACxB,SAAS,CAAC,EAAE,eAAe,GAC1B,OAAO,CAAC,MAAM,CAAC,CA8FjB"}

package/dist/core/x402-payment.js

@@ -0,0 +1,242 @@
+/**
+ * Build EVM x402 payment payload (EIP-3009 TransferWithAuthorization style).
+ * Uses ChainClient only (no viem) to align with SDK conventions.
+ *
+ * Spec alignment (docs/x402v1.md, docs/x402v2.md):
+ * - V1: header X-PAYMENT, payload { x402Version: 1, scheme, network, payload }; network is human-readable (e.g. "base", "base-sepolia").
+ * - V2: header PAYMENT-SIGNATURE, payload { x402Version: 2, accepted, payload, extensions }; network is CAIP-2 (eip155:chainId).
+ */
+/** Minimal ABI for token name (ERC-20). */
+const NAME_ABI = [
+    { inputs: [], name: 'name', outputs: [{ internalType: 'string', name: '', type: 'string' }], stateMutability: 'view', type: 'function' },
+];
+/** Optional version (EIP-3009 / EIP-712 domain). */
+const VERSION_ABI = [
+    { inputs: [], name: 'version', outputs: [{ internalType: 'string', name: '', type: 'string' }], stateMutability: 'view', type: 'function' },
+];
+/** ERC-20 balanceOf for balance checks (payFirst). */
+const BALANCE_OF_ABI = [
+    { inputs: [{ internalType: 'address', name: 'account', type: 'address' }], name: 'balanceOf', outputs: [{ internalType: 'uint256', name: '', type: 'uint256' }], stateMutability: 'view', type: 'function' },
+];
+/** EIP-3009 TransferWithAuthorization type for EIP-712. */
+const TRANSFER_WITH_AUTHORIZATION_TYPES = [
+    { name: 'from', type: 'address' },
+    { name: 'to', type: 'address' },
+    { name: 'value', type: 'uint256' },
+    { name: 'validAfter', type: 'uint256' },
+    { name: 'validBefore', type: 'uint256' },
+    { name: 'nonce', type: 'bytes32' },
+];
+function randomBytes32Hex() {
+    const bytes = new Uint8Array(32);
+    if (typeof globalThis.crypto !== 'undefined' && globalThis.crypto.getRandomValues) {
+        globalThis.crypto.getRandomValues(bytes);
+    }
+    else {
+        throw new Error('x402: crypto.getRandomValues not available for nonce generation');
+    }
+    let hex = '0x';
+    for (let i = 0; i < bytes.length; i++) {
+        hex += bytes[i].toString(16).padStart(2, '0');
+    }
+    return hex;
+}
+/**
+ * Resolve token contract address from accept (token or asset; must be checksum address).
+ */
+function tokenAddress(accept, chainClient) {
+    const raw = accept.token || accept.asset || '';
+    if (!raw || !chainClient.isAddress(raw)) {
+        throw new Error('x402: accept has no valid token/asset address');
+    }
+    return chainClient.toChecksumAddress(raw);
+}
+/**
+ * Resolve destination (to) address from accept.
+ */
+function destinationAddress(accept, chainClient) {
+    const raw = accept.destination || accept.payTo;
+    if (!raw || !chainClient.isAddress(raw)) {
+        throw new Error('x402: accept has no valid destination/payTo address');
+    }
+    return chainClient.toChecksumAddress(raw);
+}
+/**
+ * Resolve value in smallest units (string for uint256).
+ */
+function valueAmount(accept) {
+    const v = accept.price ?? accept.maxAmountRequired ?? '0';
+    return String(v);
+}
+/**
+ * Check whether the signer has sufficient token balance for the given accept on the given chain.
+ * Returns true if balance >= accept.price, false otherwise or on any error (e.g. no signer, RPC failure, invalid token).
+ * Used by payFirst() to pick the first accept with sufficient balance.
+ */
+export async function checkEvmBalance(accept, chainClient) {
+    try {
+        const token = tokenAddress(accept, chainClient);
+        const signer = await chainClient.ensureAddress();
+        if (!signer)
+            return false;
+        const balance = await chainClient.readContract({
+            address: token,
+            abi: [...BALANCE_OF_ABI],
+            functionName: 'balanceOf',
+            args: [signer],
+        });
+        const price = BigInt(valueAmount(accept));
+        return balance >= price;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * x402 v1 spec §5.2: PaymentPayload.network must be a human-readable network identifier
+ * (e.g. "base-sepolia", "ethereum-mainnet"), not CAIP-2. Map CAIP-2 or chainId to v1 name.
+ */
+const V1_NETWORK_NAMES = {
+    'eip155:1': 'ethereum-mainnet',
+    'eip155:11155111': 'ethereum-sepolia',
+    'eip155:8453': 'base',
+    'eip155:84532': 'base-sepolia',
+    'eip155:43114': 'avalanche',
+    'eip155:43113': 'avalanche-fuji',
+    'eip155:4689': 'iotex',
+    'eip155:4690': 'iotex-testnet',
+};
+function toV1NetworkName(networkOrChainId) {
+    const s = String(networkOrChainId);
+    if (V1_NETWORK_NAMES[s])
+        return V1_NETWORK_NAMES[s];
+    const caip = s.startsWith('eip155:') ? s : `eip155:${s}`;
+    if (V1_NETWORK_NAMES[caip])
+        return V1_NETWORK_NAMES[caip];
+    return s;
+}
+/**
+ * Fetch EIP-712 domain name and version from token contract (for EIP-3009).
+ * Falls back to "Token" / "2" if version() is not present.
+ */
+async function getTokenDomain(tokenAddress, chainId, chainClient) {
+    let name = 'Token';
+    let version = '2';
+    try {
+        name = await chainClient.readContract({
+            address: tokenAddress,
+            abi: [...NAME_ABI],
+            functionName: 'name',
+        });
+    }
+    catch {
+        // keep default
+    }
+    try {
+        version = await chainClient.readContract({
+            address: tokenAddress,
+            abi: [...VERSION_ABI],
+            functionName: 'version',
+        });
+    }
+    catch {
+        // EIP-3009 often uses "2"
+    }
+    return { name: name || 'Token', version: version || '2' };
+}
+/**
+ * Build the base64-encoded PAYMENT-SIGNATURE payload for EVM (x402 style).
+ * Uses EIP-3009 TransferWithAuthorization typed data and ChainClient.signTypedData.
+ *
+ * @param accept - Payment option from 402 response (token, destination, price, etc.)
+ * @param chainClient - SDK chain client (signer required)
+ * @param _snapshot - Unused; reserved for future (e.g. request-specific nonce)
+ * @returns Base64 string to set as PAYMENT-SIGNATURE header
+ */
+export async function buildEvmPayment(accept, chainClient, _snapshot) {
+    const token = tokenAddress(accept, chainClient);
+    const to = destinationAddress(accept, chainClient);
+    const value = valueAmount(accept);
+    const chainId = chainClient.chainId;
+    const { name: domainName, version: domainVersion } = await getTokenDomain(token, chainId, chainClient);
+    const from = await chainClient.ensureAddress();
+    const validAfter = '0';
+    const validBefore = String(Math.floor(Date.now() / 1000) + 3600); // 1 hour
+    const nonce = randomBytes32Hex();
+    const domain = {
+        name: domainName,
+        version: domainVersion,
+        chainId,
+        verifyingContract: token,
+    };
+    const types = {
+        TransferWithAuthorization: TRANSFER_WITH_AUTHORIZATION_TYPES,
+    };
+    const message = {
+        from,
+        to,
+        value: BigInt(value),
+        validAfter: BigInt(validAfter),
+        validBefore: BigInt(validBefore),
+        nonce,
+    };
+    const signature = await chainClient.signTypedData({
+        domain,
+        types,
+        primaryType: 'TransferWithAuthorization',
+        message,
+    });
+    // x402 spec: use server's x402Version from 402 response when available; else infer from CAIP-2 network.
+    const networkStr = accept.network ?? String(chainId);
+    const serverVersion = _snapshot?.x402Version;
+    const isV2 = serverVersion === 2 || (serverVersion == null && /^eip155:\d+$/.test(String(networkStr)));
+    const scheme = accept.scheme ?? 'exact';
+    const amount = value;
+    const payTo = to;
+    if (isV2) {
+        // V2 spec §5.2: client MUST send "accepted" = the chosen PaymentRequirements so server can match.
+        const accepted = {
+            scheme,
+            network: networkStr,
+            amount,
+            asset: token,
+            payTo,
+            maxTimeoutSeconds: typeof accept.maxTimeoutSeconds === 'number'
+                ? accept.maxTimeoutSeconds
+                : 60,
+            ...(accept.extra != null && { extra: accept.extra }),
+        };
+        const payloadV2 = {
+            x402Version: 2,
+            scheme,
+            network: networkStr,
+            ...(_snapshot?.resource != null && { resource: _snapshot.resource }),
+            accepted,
+            payload: {
+                signature,
+                authorization: { from, to, value, validAfter, validBefore, nonce },
+            },
+            extensions: {},
+        };
+        const json = JSON.stringify(payloadV2);
+        const base64 = typeof Buffer !== 'undefined'
+            ? Buffer.from(json, 'utf8').toString('base64')
+            : btoa(unescape(encodeURIComponent(json)));
+        return base64;
+    }
+    const payload = {
+        x402Version: 1,
+        scheme,
+        network: toV1NetworkName(networkStr),
+        payload: {
+            signature,
+            authorization: { from, to, value, validAfter, validBefore, nonce },
+        },
+    };
+    const json = JSON.stringify(payload);
+    const base64 = typeof Buffer !== 'undefined'
+        ? Buffer.from(json, 'utf8').toString('base64')
+        : btoa(unescape(encodeURIComponent(json)));
+    return base64;
+}
+//# sourceMappingURL=x402-payment.js.map

package/dist/core/x402-payment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402-payment.js","sourceRoot":"","sources":["../../src/core/x402-payment.ts"],"names":[],"mappings":"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"}

package/dist/core/x402-request.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Generic HTTP request with x402 (402 Payment Required) handling.
+ * Used by sdk.request() and by A2A methods.
+ */
+import type { X402Accept, X402RequestOptions, X402RequestResult } from './x402-types.js';
+import type { ResourceInfo } from './x402-types.js';
+/** Snapshot of the original request so pay() can retry the same request with PAYMENT-SIGNATURE. */
+export interface RequestSnapshot {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body?: string | ArrayBuffer | Uint8Array;
+    /** x402 version from server's 402 PAYMENT-REQUIRED header (1 or 2). When set, buildPayment uses it for payload shape. */
+    x402Version?: number;
+    /** V2 ResourceInfo from 402 response when present. Passed to buildPayment for V2 payload. */
+    resource?: ResourceInfo;
+    /** V1/V2 error message from 402 response when present. */
+    error?: string;
+}
+export interface X402RequestDeps {
+    fetch: typeof globalThis.fetch;
+    buildPayment: (accept: X402Accept, snapshot: RequestSnapshot) => Promise<string>;
+    /** Optional: used by payFirst() to pick the first accept with sufficient token balance. */
+    checkBalance?: (accept: X402Accept) => Promise<boolean>;
+}
+/**
+ * Perform a single HTTP request with built-in 402 handling.
+ * - 2xx: return parsed result (default: JSON body; or use parseResponse for custom parsing).
+ * - 402: do not throw; return { x402Required: true, x402Payment } with pay(accept?) (uses first-with-balance when checkBalance is set) that retries once.
+ * - Other status or network error: throw.
+ */
+export declare function requestWithX402<T = unknown>(options: X402RequestOptions<T>, deps: X402RequestDeps): Promise<X402RequestResult<T>>;
+//# sourceMappingURL=x402-request.d.ts.map

package/dist/core/x402-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402-request.d.ts","sourceRoot":"","sources":["../../src/core/x402-request.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAe,kBAAkB,EAAwB,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC5H,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAGpD,mGAAmG;AACnG,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,CAAC;IACzC,yHAAyH;IACzH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAC/B,YAAY,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,eAAe,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACjF,2FAA2F;IAC3F,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACzD;AASD;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,CAAC,GAAG,OAAO,EAC/C,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAC9B,IAAI,EAAE,eAAe,GACpB,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAiM/B"}

package/dist/core/x402-request.js

@@ -0,0 +1,195 @@
+/**
+ * Generic HTTP request with x402 (402 Payment Required) handling.
+ * Used by sdk.request() and by A2A methods.
+ */
+import { filterEvmAccepts, parse402FromBody, parse402FromHeader, parse402SettlementFromHeader, parse402FromWWWAuthenticate } from './x402-types.js';
+/**
+ * Default parser when parseResponse is omitted: parse response body as JSON (res.json()).
+ */
+async function defaultParseResponse(res) {
+    return res.json();
+}
+/**
+ * Perform a single HTTP request with built-in 402 handling.
+ * - 2xx: return parsed result (default: JSON body; or use parseResponse for custom parsing).
+ * - 402: do not throw; return { x402Required: true, x402Payment } with pay(accept?) (uses first-with-balance when checkBalance is set) that retries once.
+ * - Other status or network error: throw.
+ */
+export async function requestWithX402(options, deps) {
+    const { url, method, headers = {}, body, payment } = options;
+    const parseResponse = options.parseResponse ?? defaultParseResponse;
+    const snapshot = {
+        url,
+        method,
+        headers: { ...headers },
+        body,
+    };
+    /** x402 spec: V1 uses X-PAYMENT header; V2 uses PAYMENT-SIGNATURE. Fetch to a given requestUrl (default snapshot.url). */
+    const doFetch = async (paymentPayload, paymentHeaderName, requestUrl) => {
+        const targetUrl = requestUrl ?? snapshot.url;
+        const reqHeaders = { ...snapshot.headers };
+        if (paymentPayload !== undefined) {
+            const headerName = paymentHeaderName ?? 'PAYMENT-SIGNATURE';
+            reqHeaders[headerName] = paymentPayload;
+        }
+        return deps.fetch(targetUrl, {
+            method: snapshot.method,
+            headers: reqHeaders,
+            body: snapshot.body,
+        });
+    };
+    const firstPayload = payment !== undefined ? payment : undefined;
+    let response = await doFetch(firstPayload);
+    if (response.status === 402) {
+        // x402 spec: payment requirements in header (PAYMENT-REQUIRED base64) or body (JSON). Fallback: WWW-Authenticate.
+        const headerPayload = response.headers.get('payment-required') ?? response.headers.get('PAYMENT-REQUIRED');
+        let { accepts, x402Version, resource, error } = parse402FromHeader(headerPayload);
+        let responseFromWWWAuthenticate = false;
+        if (accepts.length === 0) {
+            const wwwAuth = response.headers.get('www-authenticate') ?? response.headers.get('WWW-Authenticate');
+            const parsed = parse402FromWWWAuthenticate(wwwAuth);
+            accepts = parsed.accepts;
+            if (accepts.length > 0)
+                responseFromWWWAuthenticate = true;
+            if (x402Version === undefined && parsed.x402Version !== undefined)
+                x402Version = parsed.x402Version;
+        }
+        if (accepts.length === 0) {
+            const bodyText = await response.text();
+            const parsed = parse402FromBody(bodyText);
+            accepts = parsed.accepts;
+            if (x402Version === undefined && parsed.x402Version !== undefined)
+                x402Version = parsed.x402Version;
+            if (resource === undefined && parsed.resource !== undefined)
+                resource = parsed.resource;
+            if (error === undefined && parsed.error !== undefined)
+                error = parsed.error;
+        }
+        accepts = filterEvmAccepts(accepts);
+        const singleAccept = accepts.length === 1 ? accepts[0] : undefined;
+        const payFn = async (accept) => {
+            let chosen;
+            if (accept === undefined) {
+                if (deps.checkBalance) {
+                    for (let i = 0; i < accepts.length; i++) {
+                        const acc = accepts[i];
+                        if (acc && (await deps.checkBalance(acc))) {
+                            chosen = acc;
+                            break;
+                        }
+                    }
+                    if (chosen === undefined) {
+                        throw new Error('x402: no accept with sufficient balance');
+                    }
+                }
+                if (chosen === undefined) {
+                    chosen = singleAccept ?? accepts[0];
+                }
+            }
+            else if (typeof accept === 'number') {
+                chosen = accepts[accept];
+            }
+            else {
+                chosen = accept;
+            }
+            if (!chosen) {
+                throw new Error('x402: no payment option selected (empty accepts or invalid index)');
+            }
+            const payload = await deps.buildPayment(chosen, { ...snapshot, x402Version, resource, error });
+            // When server challenged with WWW-Authenticate: try Authorization: x402 <payload> first (RFC 7235); if 402 again, retry with PAYMENT-SIGNATURE (some servers expect spec header).
+            const paymentHeaderName = responseFromWWWAuthenticate
+                ? 'Authorization'
+                : (x402Version === 1 ? 'X-PAYMENT' : 'PAYMENT-SIGNATURE');
+            const paymentHeaderValue = responseFromWWWAuthenticate ? `x402 ${payload}` : payload;
+            const retryHeaders = { ...snapshot.headers, [paymentHeaderName]: paymentHeaderValue };
+            const tryUrl = async (requestUrl, useAuthHeader = true) => {
+                if (responseFromWWWAuthenticate && !useAuthHeader) {
+                    return doFetch(payload, 'PAYMENT-SIGNATURE', requestUrl);
+                }
+                return doFetch(paymentHeaderValue, paymentHeaderName, requestUrl);
+            };
+            let retryResponse = await tryUrl(snapshot.url);
+            // If we used WWW-Authenticate and server returned 402 again, retry with PAYMENT-SIGNATURE (same payload).
+            if (responseFromWWWAuthenticate && !retryResponse.ok && retryResponse.status === 402) {
+                retryResponse = await tryUrl(snapshot.url, false);
+            }
+            if (!retryResponse.ok) {
+                let body = '';
+                try {
+                    body = await retryResponse.text();
+                }
+                catch {
+                    body = '(failed to read body)';
+                }
+                const paymentRequired = retryResponse.headers.get('payment-required') ?? retryResponse.headers.get('PAYMENT-REQUIRED');
+                const paymentResponse = retryResponse.headers.get('payment-response') ?? retryResponse.headers.get('PAYMENT-RESPONSE');
+                const responseHeaders = {};
+                retryResponse.headers.forEach((v, k) => {
+                    responseHeaders[k] = v;
+                });
+                const msg = retryResponse.status === 402
+                    ? 'x402: payment rejected or insufficient (server returned 402 again)'
+                    : `x402: retry failed with HTTP ${retryResponse.status}`;
+                let requestBody = '';
+                if (snapshot.body !== undefined) {
+                    if (typeof snapshot.body === 'string')
+                        requestBody = snapshot.body;
+                    else if (snapshot.body instanceof ArrayBuffer)
+                        requestBody = new TextDecoder().decode(snapshot.body);
+                    else if (snapshot.body instanceof Uint8Array)
+                        requestBody = new TextDecoder().decode(snapshot.body);
+                }
+                const err = new Error(msg);
+                err.status = retryResponse.status;
+                err.body = body;
+                err.url = snapshot.url;
+                err.method = snapshot.method;
+                err.requestHeaders = retryHeaders;
+                err.requestBody = requestBody;
+                err.responseHeaders = responseHeaders;
+                err.headers = {
+                    ...(paymentRequired && { 'payment-required': paymentRequired }),
+                    ...(paymentResponse && { 'payment-response': paymentResponse }),
+                };
+                if (Object.keys(err.headers).length === 0)
+                    delete err.headers;
+                throw err;
+            }
+            const result = await parseResponse(retryResponse);
+            const paymentResponseHeader = retryResponse.headers.get('payment-response') ?? retryResponse.headers.get('PAYMENT-RESPONSE');
+            const settlement = paymentResponseHeader ? parse402SettlementFromHeader(paymentResponseHeader) : undefined;
+            if (settlement !== undefined &&
+                typeof result === 'object' &&
+                result !== null &&
+                !Array.isArray(result)) {
+                result.x402Settlement = settlement;
+            }
+            return result;
+        };
+        const x402Payment = {
+            accepts,
+            ...(x402Version !== undefined && { x402Version }),
+            ...(error !== undefined && { error }),
+            ...(resource !== undefined && { resource }),
+            ...(singleAccept && {
+                price: singleAccept.price,
+                token: singleAccept.token,
+                network: singleAccept.network,
+            }),
+            pay: payFn,
+            ...(deps.checkBalance && {
+                payFirst: () => payFn(), // pay() with no arg now uses first-with-balance
+            }),
+        };
+        const result = {
+            x402Required: true,
+            x402Payment,
+        };
+        return result;
+    }
+    if (response.ok) {
+        return parseResponse(response);
+    }
+    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+}
+//# sourceMappingURL=x402-request.js.map

package/dist/core/x402-request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402-request.js","sourceRoot":"","sources":["../../src/core/x402-request.ts"],"names":[],"mappings":"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"}

package/dist/core/x402-types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * x402 payment-required types and 402 response parsing.
+ */
+/**
+ * A single payment option from a 402 response (PAYMENT-REQUIRED header).
+ * Each entry has at least price and token; optional fields for network, scheme, etc.
+ */
+export interface X402Accept {
+    /** Amount in smallest units (e.g. USDC 6 decimals). May be string for large values. */
+    price: string;
+    /** Token contract address or symbol. */
+    token: string;
+    /** Chain id (number or string e.g. "base-sepolia", "eip155:84532"). */
+    network?: string;
+    scheme?: string;
+    description?: string;
+    /** Max amount required when variable. */
+    maxAmountRequired?: string;
+    /** Destination / pay-to address (recipient or verifying contract). */
+    destination?: string;
+    /** Asset address (alias for token in some 402 body shapes). */
+    asset?: string;
+    /** Additional fields from server (e.g. payTo, paymentRequirements). */
+    [key: string]: unknown;
+}
+/**
+ * Payment-required payload returned when the server responds with HTTP 402.
+ * Always includes accepts[]; when there is a single accept, convenience fields may be set.
+ */
+export interface X402Payment<T = unknown> {
+    /** Array of accepted payment options. Always present. */
+    accepts: X402Accept[];
+    /** x402 version from server's PAYMENT-REQUIRED header (e.g. 1 or 2). */
+    x402Version?: number;
+    /** V1/V2 human-readable error message from 402 response when present. */
+    error?: string;
+    /** V2 ResourceInfo from 402 response when present. */
+    resource?: ResourceInfo;
+    /** When single accept: convenience price (same as accepts[0].price). */
+    price?: string;
+    /** When single accept: convenience token (same as accepts[0].token). */
+    token?: string;
+    /** When single accept: convenience network (same as accepts[0].network). */
+    network?: string;
+    /**
+     * Performs payment and retries the request.
+     * No arg = use single accept; number = accepts[index]; X402Accept = chosen option.
+     * Resolves to the same shape as a successful request (no x402Required).
+     */
+    pay(accept?: X402Accept | number): Promise<T>;
+    /**
+     * When present (deps provided checkBalance): pays using the first accept for which
+     * the signer has sufficient token balance on that chain. Throws if none have sufficient balance.
+     */
+    payFirst?(): Promise<T>;
+}
+/**
+ * Options for the generic x402 HTTP request.
+ */
+export interface X402RequestOptions<T = unknown> {
+    url: string;
+    method: string;
+    headers?: Record<string, string>;
+    body?: string | ArrayBuffer | Uint8Array;
+    /**
+     * Optional parser for 2xx response body. If omitted, the body is parsed as JSON (res.json()).
+     */
+    parseResponse?: (response: Response) => Promise<T>;
+    /**
+     * Optional payment to send with the first request (e.g. base64 PAYMENT-SIGNATURE payload).
+     * If provided and server returns 2xx, one round trip; if 402, normal x402 flow.
+     */
+    payment?: string;
+}
+/**
+ * Response when server returns HTTP 402. Caller checks x402Required and may call x402Payment.pay().
+ */
+export interface X402RequiredResponse<T> {
+    x402Required: true;
+    x402Payment: X402Payment<T>;
+}
+/**
+ * Result of sdk.request(): either the parsed success value or the 402 response object.
+ * Success branch is typed with x402Required?: false so you can always read result.x402Required
+ * (undefined/false on success, true on 402) and use if (result.x402Required) to narrow.
+ */
+export type X402RequestResult<T> = (T & {
+    x402Required?: false;
+}) | X402RequiredResponse<T>;
+/**
+ * Type guard: result is 402 response. Returns false for null/undefined.
+ */
+export declare function isX402Required<T>(result: X402RequestResult<T> | null | undefined): result is X402RequiredResponse<T>;
+/** Filter accepts to EVM-only (Solana and other non-EVM options removed). Applied when building 402 response. */
+export declare function filterEvmAccepts(accepts: X402Accept[]): X402Accept[];
+/**
+ * Result of parsing PAYMENT-REQUIRED header (accepts + optional version, resource, error).
+ */
+export interface Parse402FromHeaderResult {
+    accepts: X402Accept[];
+    x402Version?: number;
+    /** V2 PaymentRequired top-level resource (ResourceInfo). Present when server sends it. */
+    resource?: ResourceInfo;
+    /** V1 PaymentRequirementsResponse human-readable error message. Present when server sends it. */
+    error?: string;
+}
+/** V2 ResourceInfo: url, optional description and mimeType (x402 spec §5.1). */
+export interface ResourceInfo {
+    url?: string;
+    description?: string;
+    mimeType?: string;
+}
+/** Settlement response (SettlementResponse / SettleResponse) from PAYMENT-RESPONSE header or body after successful pay. */
+export interface X402SettlementResponse {
+    success: boolean;
+    errorReason?: string;
+    transaction?: string;
+    network?: string;
+    payer?: string;
+}
+/**
+ * Parse PAYMENT-REQUIRED header (x402 spec: base64-encoded JSON with accepts array).
+ * Returns accepts, x402Version, and when present resource (v2) and error (v1).
+ */
+export declare function parse402FromHeader(headerValue: string | null): Parse402FromHeaderResult;
+/**
+ * Parse WWW-Authenticate header with x402 challenge (e.g. 402payment-test.com).
+ * Format: x402 address="0x...", amount="0.01", chainId="8453", token="0x..."
+ * Returns a single accept; amount is converted to atomic units if it looks like a decimal (USDC 6 decimals).
+ */
+export declare function parse402FromWWWAuthenticate(headerValue: string | null): Parse402FromHeaderResult;
+/**
+ * Parse 402 response body (JSON with accepts array). Used when server sends payment options in body (e.g. httpay.xyz).
+ * Returns accepts, x402Version, and when present resource (v2) and error (v1).
+ */
+export declare function parse402FromBody(bodyText: string | null): Parse402FromHeaderResult;
+/**
+ * Parse PAYMENT-REQUIRED header (x402 spec: base64-encoded JSON with accepts array).
+ * Server sends payment options in header; body may be empty. Returns [] if header missing/invalid.
+ */
+export declare function parse402AcceptsFromHeader(headerValue: string | null): X402Accept[];
+/**
+ * Parse PAYMENT-RESPONSE header (base64-encoded JSON) after successful pay.
+ * Returns settlement info (success, transaction, network, payer) when present and valid.
+ */
+export declare function parse402SettlementFromHeader(headerValue: string | null): X402SettlementResponse | undefined;
+//# sourceMappingURL=x402-types.d.ts.map

package/dist/core/x402-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402-types.d.ts","sourceRoot":"","sources":["../../src/core/x402-types.ts"],"names":[],"mappings":"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"}