@conto_finance/sdk 0.4.0 → 0.5.1

package/README.md

@@ -1,5 +1,10 @@
 # @conto_finance/sdk
 
+Conto is a buyer-side control layer. Integrate it in the agent owner's runtime or payment tools;
+the owner or budget holder sets policy before the agent pays.
+See [buyer-side control](https://conto.finance/docs/guides/buyer-side-control) for the authorization
+and execution boundary.
+
 TypeScript SDK for Conto. Use it when you control the agent runtime and want typed access to
 payment requests, payment execution, and organization-level provisioning.
 
@@ -95,34 +100,9 @@ await admin.cards.revokeFromAgent('agent_id', card.id);
 ```
 
 The policy overlay stops at approval, claiming, and reconciliation. For a
-customer-hosted payment tool that gates access to customer payment code, use the
-separate
-[`@conto_finance/card-access`](https://conto.finance/docs/card-access/overview) product
-package.
-
-```typescript
-import { ContoCardAccess } from '@conto_finance/card-access';
-
-const cardAccess = new ContoCardAccess({
-  policy: conto.cards,
-  integrationId: 'procurement-agent-production',
-  deployment: {
-    credentialCustody: 'CUSTOMER',
-    agentHasRawCredentialAccess: false,
-    uncontrolledAgentPaymentPath: false,
-  },
-  executor: customerHostedExecutor,
-});
-```
-
-Card Access claims each approved request exactly once before the executor can run. A
-duplicate or uncertain claim cannot invoke the executor again. It remains
-bypassable if another person or tool can access the card, and results are
-self-reported rather than issuer-verified. The executor receives the normalized
-purchase `idempotencyKey`; pass it to the payment processor so ambiguous
-processor responses cannot create duplicate charges. The legacy `conto.cards.controlled()`
-helper remains available for compatibility, but new customer-hosted enforcement
-should use the standalone Card Access package. Use
+customer-hosted payment tool that gates access to customer payment code, see
+[Card Access](https://conto.finance/docs/card-access/overview), available on request.
+The legacy `conto.cards.controlled()` helper remains available for compatibility. Use
 `admin.cards.listRequests({ status: 'EXECUTING' })` for reconciliation and
 `admin.cards.pause(card.id)` to revoke unclaimed grants and stop new approvals
 in the Conto-controlled path.
@@ -144,14 +124,16 @@ const result = await conto.payments.pay({
 ```typescript
 const paymentId = crypto.randomUUID();
 
-await conto.x402.preAuthorize({
+const decision = await conto.x402.preAuthorize({
   amount: 0.01,
   recipientAddress: '0x...',
   resourceUrl: 'https://api.example.com/v1/search',
   paymentId,
   sessionId: 'session_123',
 });
+if (!decision.authorized) throw new Error(decision.message);
 
+// Sign and settle the x402 payment, then record it with the grant.
 await conto.x402.record({
   amount: 0.01,
   recipientAddress: '0x...',
@@ -159,18 +141,53 @@ await conto.x402.record({
   paymentId,
   txHash: '0x...',
   sessionId: 'session_123',
+  grantId: decision.grantId,
+  grantSignature: decision.grantSignature,
 });
 
 const budget = await conto.x402.budget();
 ```
 
+An approved `preAuthorize` returns a single-use grant (`grantId`, `grantSignature`,
+`grantExpiresAt`) for that wallet, recipient, and amount, and reserves the amount against the
+agent's spend limits for 10 minutes. Pass the grant to `record`. A record without a valid,
+unexpired grant is still accepted because the payment already settled, but Conto flags it as a
+policy bypass and raises a critical alert. Organizations can also have the agent frozen
+automatically. The record response then includes `policyBypass: true`, `bypassReason`, and
+`agentFrozen`.
+
+For a Privy-managed EVM wallet, `conto.x402.pay` replaces `preAuthorize`. Pass the same fields
+plus the accepted 402 requirements; when approved, Conto signs the payment and returns the header
+to retry with:
+
+```typescript
+const paid = await conto.x402.pay({
+  amount: 0.01,
+  recipientAddress: requirements.payTo,
+  resourceUrl: 'https://api.example.com/v1/search',
+  paymentId,
+  paymentRequirements: requirements, // accepted entry from the 402 challenge
+});
+if (!paid.authorized) throw new Error(paid.message);
+
+const response = await fetch('https://api.example.com/v1/search', {
+  headers: { [paid.paymentHeaderName!]: paid.xPaymentHeader! },
+});
+// Then record with paid.grantId, paid.grantSignature, and the settlement txHash.
+```
+
+`pay` is not retried automatically: each grant is signed once, and a repeat returns
+`GRANT_ALREADY_SIGNED`. External wallets get `MANAGED_SIGNING_UNAVAILABLE`.
+
 The MPP client mirrors the same shape with `conto.mpp.preAuthorize`, `conto.mpp.record`,
-`conto.mpp.budget`, and `conto.mpp.services`.
+`conto.mpp.budget`, and `conto.mpp.services`. An MPP session grant is a ceiling: several
+`record` calls with the same `sessionId` may draw it down until it is used up or expires.
 
-## Stripe Link Checkout Commerce
+## Stripe Link Checkout Commerce (test only)
 
-For a merchant Conto controls, `LINK_CHECKOUT` evaluates policy before creating an ordinary
-Stripe-hosted Checkout Session with card and Link enabled. It needs no private Link SDK permission,
+`LINK_CHECKOUT` is test-only and works only with a merchant enrolled with Conto. It is not a
+general merchant integration. It evaluates policy before creating an ordinary Stripe-hosted
+Checkout Session with card and Link enabled. It needs no private Link SDK permission,
 Link connection, saved payment-method ID, SPT, or LPT.
 
 Commerce execution responses separate the provider-neutral `executionChannel`, optional
@@ -224,15 +241,16 @@ fallback, surfaced as `actualPaymentMethod: 'CARD'`; it is a valid payment but n
 The read-only `getCommerceExecution` projection redacts action URLs; use the initial begin result or
 the `payments:confirm` refresh path while action remains required.
 The server resolves the exact merchant name, Stripe account, and return URLs from configuration, so
-the caller cannot redirect the approved purchase. This path controls only that merchant's Conto
-channel, not unrelated Checkout pages or the consumer's Link wallet. See
+the caller cannot redirect the approved purchase. This path covers only that enrolled merchant's
+Conto channel, not unrelated Checkout pages or the consumer's Link wallet. See
 `docs/STRIPE_LINK_CHECKOUT_ADAPTER.md` for configuration, webhook, drill, and reconciliation
 requirements.
 
 ## Agent checkout guard
 
-For arbitrary third-party merchants, use `runGuardedCheckout` with
-`executionMethod: 'BROWSER_CHECKOUT'`. It binds and atomically authorizes one exact Link, card,
+For browser checkouts on supported rails (Link, card, Shop Pay, or PayPal), use
+`runGuardedCheckout` with `executionMethod: 'BROWSER_CHECKOUT'`. Other rails and checkout flows are
+not covered. It binds and atomically authorizes one exact Link, card,
 Shop Pay, or PayPal browser action without requiring merchant or private provider integration. The
 privileged browser executor must be available only through this wrapper; an unrestricted click or
 payment tool would bypass the control. Persist its stable dispatch attempt before calling the helper; it owns authorization,
@@ -502,7 +520,9 @@ The SDK automatically adds an idempotency key to wallet payment authorization
 requests. Provide your own stable `idempotencyKey` when a retry may happen in
 another process or job attempt. External-card approvals always require a stable
 caller-supplied `idempotencyKey`; card approval and confirmation are safe to
-retry. x402 and MPP pre-authorization calls are non-mutating policy checks.
+retry. x402 and MPP pre-authorization calls issue a grant and reserve spend. A retry
+with the same `paymentId` (x402) or `challengeId`/`credentialId` (MPP) returns the
+same live grant instead of reserving again.
 Record calls require an explicit stable `paymentId` or `credentialId` so an
 ambiguous failure can be reconciled safely.
 

package/dist/browserbase.d.mts

@@ -2,6 +2,8 @@ import { Browser } from 'playwright-core';
 import { GuardedPlaywrightCheckoutHttpHandler, PlaywrightSessionObservation, GuardedPlaywrightCheckoutClient, PlaywrightCdpSessionRegistryConfig, EncryptedPlaywrightCheckoutTargetStoreConfig, GuardedPlaywrightCheckoutRuntimeConfig } from './playwright.mjs';
 import './index.mjs';
 
+/** Exact provider endpoints verified against Browserbase's session API; never use a wildcard. */
+declare const BROWSERBASE_CONNECT_ORIGINS: readonly string[];
 type BrowserbaseSessionStatus = 'PENDING' | 'RUNNING' | 'ERROR' | 'TIMED_OUT' | 'COMPLETED';
 type BrowserbaseSessionBindingState = 'ACTIVE' | 'REVOKED';
 type BrowserbaseSessionLifecycleOwner = 'CONTO_RUNTIME' | 'AGENT_HOST';
@@ -128,12 +130,23 @@ declare class BrowserbaseSessionError extends Error {
     readonly code: BrowserbaseSessionErrorCode;
     constructor(code: BrowserbaseSessionErrorCode, message: string);
 }
+interface BrowserbaseSessionManager {
+    createSession(): Promise<BrowserbaseOwnedSession>;
+    attachSession(input: BrowserbaseSessionHandoff): Promise<BrowserbaseAttachedSession>;
+    connectUrlForSession(browserSessionId: string): Promise<string | null>;
+    liveViewForSession(browserSessionId: string): Promise<BrowserbaseOwnedLiveView>;
+    revokeSession(browserSessionId: string, lifecycleOwner: BrowserbaseSessionLifecycleOwner): Promise<boolean>;
+    releaseProviderSession(browserSessionId: string): Promise<void>;
+    releaseContextLease(browserSessionId: string): Promise<boolean>;
+}
 /** Creates a short-lived assertion after the trusted agent host creates its Browserbase session. */
 declare function createBrowserbaseSessionHandoffAssertion(input: BrowserbaseSessionHandoffAssertionInput, keyValue: Uint8Array): string;
+/** Server-only capability. Never expose connect URLs or this manager as agent tools. */
+declare function createBrowserbaseSessionManager(config: BrowserbaseSessionConfig): BrowserbaseSessionManager;
 /**
  * Creates the recommended Browserbase deployment boundary. Provider lifecycle, ownership checks,
  * remote connection resolution, guarded execution, and cleanup remain in one privileged object.
  */
 declare function createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost(config: BrowserbaseGuardedPlaywrightCheckoutRuntimeHostConfig): BrowserbaseGuardedPlaywrightCheckoutRuntimeHost;
 
-export { type BrowserbaseAttachedSession, type BrowserbaseGuardedPlaywrightCheckoutRuntimeHost, type BrowserbaseGuardedPlaywrightCheckoutRuntimeHostConfig, type BrowserbaseOwnedLiveView, type BrowserbaseOwnedSession, type BrowserbaseSessionBinding, type BrowserbaseSessionBindingState, type BrowserbaseSessionBindingStore, type BrowserbaseSessionConfig, BrowserbaseSessionError, type BrowserbaseSessionErrorCode, type BrowserbaseSessionHandoff, type BrowserbaseSessionHandoffAssertionInput, type BrowserbaseSessionLifecycleOwner, type BrowserbaseSessionStatus, createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost, createBrowserbaseSessionHandoffAssertion };
+export { BROWSERBASE_CONNECT_ORIGINS, type BrowserbaseAttachedSession, type BrowserbaseGuardedPlaywrightCheckoutRuntimeHost, type BrowserbaseGuardedPlaywrightCheckoutRuntimeHostConfig, type BrowserbaseOwnedLiveView, type BrowserbaseOwnedSession, type BrowserbaseSessionBinding, type BrowserbaseSessionBindingState, type BrowserbaseSessionBindingStore, type BrowserbaseSessionConfig, BrowserbaseSessionError, type BrowserbaseSessionErrorCode, type BrowserbaseSessionHandoff, type BrowserbaseSessionHandoffAssertionInput, type BrowserbaseSessionLifecycleOwner, type BrowserbaseSessionManager, type BrowserbaseSessionStatus, createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost, createBrowserbaseSessionHandoffAssertion, createBrowserbaseSessionManager };

package/dist/browserbase.d.ts

@@ -2,6 +2,8 @@ import { Browser } from 'playwright-core';
 import { GuardedPlaywrightCheckoutHttpHandler, PlaywrightSessionObservation, GuardedPlaywrightCheckoutClient, PlaywrightCdpSessionRegistryConfig, EncryptedPlaywrightCheckoutTargetStoreConfig, GuardedPlaywrightCheckoutRuntimeConfig } from './playwright.js';
 import './index.js';
 
+/** Exact provider endpoints verified against Browserbase's session API; never use a wildcard. */
+declare const BROWSERBASE_CONNECT_ORIGINS: readonly string[];
 type BrowserbaseSessionStatus = 'PENDING' | 'RUNNING' | 'ERROR' | 'TIMED_OUT' | 'COMPLETED';
 type BrowserbaseSessionBindingState = 'ACTIVE' | 'REVOKED';
 type BrowserbaseSessionLifecycleOwner = 'CONTO_RUNTIME' | 'AGENT_HOST';
@@ -128,12 +130,23 @@ declare class BrowserbaseSessionError extends Error {
     readonly code: BrowserbaseSessionErrorCode;
     constructor(code: BrowserbaseSessionErrorCode, message: string);
 }
+interface BrowserbaseSessionManager {
+    createSession(): Promise<BrowserbaseOwnedSession>;
+    attachSession(input: BrowserbaseSessionHandoff): Promise<BrowserbaseAttachedSession>;
+    connectUrlForSession(browserSessionId: string): Promise<string | null>;
+    liveViewForSession(browserSessionId: string): Promise<BrowserbaseOwnedLiveView>;
+    revokeSession(browserSessionId: string, lifecycleOwner: BrowserbaseSessionLifecycleOwner): Promise<boolean>;
+    releaseProviderSession(browserSessionId: string): Promise<void>;
+    releaseContextLease(browserSessionId: string): Promise<boolean>;
+}
 /** Creates a short-lived assertion after the trusted agent host creates its Browserbase session. */
 declare function createBrowserbaseSessionHandoffAssertion(input: BrowserbaseSessionHandoffAssertionInput, keyValue: Uint8Array): string;
+/** Server-only capability. Never expose connect URLs or this manager as agent tools. */
+declare function createBrowserbaseSessionManager(config: BrowserbaseSessionConfig): BrowserbaseSessionManager;
 /**
  * Creates the recommended Browserbase deployment boundary. Provider lifecycle, ownership checks,
  * remote connection resolution, guarded execution, and cleanup remain in one privileged object.
  */
 declare function createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost(config: BrowserbaseGuardedPlaywrightCheckoutRuntimeHostConfig): BrowserbaseGuardedPlaywrightCheckoutRuntimeHost;
 
-export { type BrowserbaseAttachedSession, type BrowserbaseGuardedPlaywrightCheckoutRuntimeHost, type BrowserbaseGuardedPlaywrightCheckoutRuntimeHostConfig, type BrowserbaseOwnedLiveView, type BrowserbaseOwnedSession, type BrowserbaseSessionBinding, type BrowserbaseSessionBindingState, type BrowserbaseSessionBindingStore, type BrowserbaseSessionConfig, BrowserbaseSessionError, type BrowserbaseSessionErrorCode, type BrowserbaseSessionHandoff, type BrowserbaseSessionHandoffAssertionInput, type BrowserbaseSessionLifecycleOwner, type BrowserbaseSessionStatus, createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost, createBrowserbaseSessionHandoffAssertion };
+export { BROWSERBASE_CONNECT_ORIGINS, type BrowserbaseAttachedSession, type BrowserbaseGuardedPlaywrightCheckoutRuntimeHost, type BrowserbaseGuardedPlaywrightCheckoutRuntimeHostConfig, type BrowserbaseOwnedLiveView, type BrowserbaseOwnedSession, type BrowserbaseSessionBinding, type BrowserbaseSessionBindingState, type BrowserbaseSessionBindingStore, type BrowserbaseSessionConfig, BrowserbaseSessionError, type BrowserbaseSessionErrorCode, type BrowserbaseSessionHandoff, type BrowserbaseSessionHandoffAssertionInput, type BrowserbaseSessionLifecycleOwner, type BrowserbaseSessionManager, type BrowserbaseSessionStatus, createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost, createBrowserbaseSessionHandoffAssertion, createBrowserbaseSessionManager };

package/dist/browserbase.js

@@ -20,9 +20,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/browserbase.ts
 var browserbase_exports = {};
 __export(browserbase_exports, {
+  BROWSERBASE_CONNECT_ORIGINS: () => BROWSERBASE_CONNECT_ORIGINS,
   BrowserbaseSessionError: () => BrowserbaseSessionError,
   createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost: () => createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost,
-  createBrowserbaseSessionHandoffAssertion: () => createBrowserbaseSessionHandoffAssertion
+  createBrowserbaseSessionHandoffAssertion: () => createBrowserbaseSessionHandoffAssertion,
+  createBrowserbaseSessionManager: () => createBrowserbaseSessionManager
 });
 module.exports = __toCommonJS(browserbase_exports);
 var import_node_crypto3 = require("crypto");
@@ -1382,7 +1384,10 @@ function createGuardedPlaywrightCheckoutHttpHandler(config) {
 
 // src/browserbase.ts
 var BROWSERBASE_API_ORIGIN = "https://api.browserbase.com";
-var BROWSERBASE_CONNECT_ORIGIN = "wss://connect.browserbase.com";
+var BROWSERBASE_CONNECT_ORIGINS = Object.freeze([
+  "wss://connect.browserbase.com",
+  "wss://connect.usw2.browserbase.com"
+]);
 var BROWSERBASE_LIVE_VIEW_DOMAIN = "browserbase.com";
 var DEFAULT_SESSION_TIMEOUT_SECONDS = 900;
 var MIN_SESSION_TIMEOUT_SECONDS = 60;
@@ -1508,7 +1513,7 @@ function secureConnectUrl(value) {
   const normalized = providerText(value, "connectUrl", 4096);
   try {
     const url = new URL(normalized);
-    if (url.protocol !== "wss:" || url.origin !== BROWSERBASE_CONNECT_ORIGIN || url.username || url.password || url.hash) {
+    if (url.protocol !== "wss:" || !BROWSERBASE_CONNECT_ORIGINS.includes(url.origin) || url.username || url.password || url.hash) {
       throw new Error("unsafe Browserbase connect URL");
     }
     return url.toString();
@@ -1568,7 +1573,9 @@ function parseProviderSession(value, expectedProjectId, expectedSessionId) {
     status,
     createdAt,
     expiresAt,
-    connectUrl: secureConnectUrl(record.connectUrl)
+    // Completed sessions need not retain a connection capability. Validate it
+    // only for active states; identity and timestamps above still must match.
+    connectUrl: status === "PENDING" || status === "RUNNING" ? secureConnectUrl(record.connectUrl) : null
   });
 }
 async function readProviderJson(response) {
@@ -1664,11 +1671,13 @@ function createBrowserbaseSessionManager(config) {
           projectId,
           timeout: durationSeconds,
           keepAlive: true,
-          ...contextId ? {
-            browserSettings: {
-              context: { id: contextId, persist: true }
-            }
-          } : {}
+          proxies: false,
+          browserSettings: {
+            recordSession: false,
+            logSession: false,
+            solveCaptchas: false,
+            ...contextId ? { context: { id: contextId, persist: true } } : {}
+          }
         })
       });
       if (response.status !== 201) {
@@ -1911,7 +1920,7 @@ function createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost(config) {
   const host = createGuardedPlaywrightCheckoutRuntimeHost({
     conto: config.conto,
     browserSessions: {
-      allowedConnectOrigins: [BROWSERBASE_CONNECT_ORIGIN],
+      allowedConnectOrigins: BROWSERBASE_CONNECT_ORIGINS,
       connectUrlForSession: manager.connectUrlForSession,
       connectOverCDP: config.connectOverCDP,
       selectPage: config.selectPage,
@@ -1974,7 +1983,9 @@ function createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost(config) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BROWSERBASE_CONNECT_ORIGINS,
   BrowserbaseSessionError,
   createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost,
-  createBrowserbaseSessionHandoffAssertion
+  createBrowserbaseSessionHandoffAssertion,
+  createBrowserbaseSessionManager
 });

package/dist/browserbase.mjs

@@ -7,7 +7,10 @@ import "./chunk-B7F5QLE5.mjs";
 // src/browserbase.ts
 import { createHmac, timingSafeEqual } from "crypto";
 var BROWSERBASE_API_ORIGIN = "https://api.browserbase.com";
-var BROWSERBASE_CONNECT_ORIGIN = "wss://connect.browserbase.com";
+var BROWSERBASE_CONNECT_ORIGINS = Object.freeze([
+  "wss://connect.browserbase.com",
+  "wss://connect.usw2.browserbase.com"
+]);
 var BROWSERBASE_LIVE_VIEW_DOMAIN = "browserbase.com";
 var DEFAULT_SESSION_TIMEOUT_SECONDS = 900;
 var MIN_SESSION_TIMEOUT_SECONDS = 60;
@@ -133,7 +136,7 @@ function secureConnectUrl(value) {
   const normalized = providerText(value, "connectUrl", 4096);
   try {
     const url = new URL(normalized);
-    if (url.protocol !== "wss:" || url.origin !== BROWSERBASE_CONNECT_ORIGIN || url.username || url.password || url.hash) {
+    if (url.protocol !== "wss:" || !BROWSERBASE_CONNECT_ORIGINS.includes(url.origin) || url.username || url.password || url.hash) {
       throw new Error("unsafe Browserbase connect URL");
     }
     return url.toString();
@@ -193,7 +196,9 @@ function parseProviderSession(value, expectedProjectId, expectedSessionId) {
     status,
     createdAt,
     expiresAt,
-    connectUrl: secureConnectUrl(record.connectUrl)
+    // Completed sessions need not retain a connection capability. Validate it
+    // only for active states; identity and timestamps above still must match.
+    connectUrl: status === "PENDING" || status === "RUNNING" ? secureConnectUrl(record.connectUrl) : null
   });
 }
 async function readProviderJson(response) {
@@ -289,11 +294,13 @@ function createBrowserbaseSessionManager(config) {
           projectId,
           timeout: durationSeconds,
           keepAlive: true,
-          ...contextId ? {
-            browserSettings: {
-              context: { id: contextId, persist: true }
-            }
-          } : {}
+          proxies: false,
+          browserSettings: {
+            recordSession: false,
+            logSession: false,
+            solveCaptchas: false,
+            ...contextId ? { context: { id: contextId, persist: true } } : {}
+          }
         })
       });
       if (response.status !== 201) {
@@ -536,7 +543,7 @@ function createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost(config) {
   const host = createGuardedPlaywrightCheckoutRuntimeHost({
     conto: config.conto,
     browserSessions: {
-      allowedConnectOrigins: [BROWSERBASE_CONNECT_ORIGIN],
+      allowedConnectOrigins: BROWSERBASE_CONNECT_ORIGINS,
       connectUrlForSession: manager.connectUrlForSession,
       connectOverCDP: config.connectOverCDP,
       selectPage: config.selectPage,
@@ -598,7 +605,9 @@ function createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost(config) {
   });
 }
 export {
+  BROWSERBASE_CONNECT_ORIGINS,
   BrowserbaseSessionError,
   createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost,
-  createBrowserbaseSessionHandoffAssertion
+  createBrowserbaseSessionHandoffAssertion,
+  createBrowserbaseSessionManager
 };

package/dist/index.d.mts

@@ -65,7 +65,7 @@ interface PaginatedResponse<T> {
     limit: number;
     offset: number;
 }
-type AgentType = 'OPENAI_ASSISTANT' | 'ANTHROPIC_CLAUDE' | 'LANGCHAIN' | 'AUTOGPT' | 'CUSTOM';
+type AgentType = 'OPENAI_ASSISTANT' | 'ANTHROPIC_CLAUDE' | 'AUTOGPT' | 'CUSTOM';
 type AgentStatus = 'ACTIVE' | 'PAUSED' | 'SUSPENDED' | 'REVOKED' | 'FROZEN' | 'DELETED';
 type AgentEnvironment = 'DEV' | 'STAGING' | 'PROD';
 type AgentRiskTier = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
@@ -1131,7 +1131,7 @@ interface PaymentRequestResult {
     /** Unique request ID - use this to execute or check status */
     requestId: string;
     /** Current status */
-    status: 'APPROVED' | 'DENIED' | 'REQUIRES_APPROVAL' | 'ACTION_REQUIRED' | 'PROCESSING';
+    status: 'APPROVED' | 'DENIED' | 'REQUIRES_APPROVAL' | 'PROCESSING';
     /** Requested amount */
     amount: number;
     /** Currency selected for the payment */
@@ -1164,6 +1164,11 @@ interface PaymentRequestResult {
 interface PaymentExecuteResult {
     /** Payment request ID */
     requestId: string;
+    /**
+     * True when the payment had already been executed, for example by an
+     * approver in Conto. The receipt is the existing one; nothing was sent again.
+     */
+    alreadyExecuted?: boolean;
     /** Customer-facing execution state */
     status: 'processing' | 'completed';
     /** Amount sent */
@@ -1187,7 +1192,7 @@ interface PaymentStatusResult {
     requestId: string;
     /** Unknown for legacy records without execution evidence, or before execution. */
     settlementMode: 'live' | 'test' | 'unknown';
-    status: 'approved' | 'declined' | 'review_required' | 'action_required' | 'reconciliation_required' | 'processing' | 'completed' | 'failed' | 'expired';
+    status: 'approved' | 'declined' | 'review_required' | 'reconciliation_required' | 'processing' | 'completed' | 'failed' | 'expired';
     amount: number;
     currency: string;
     recipient: string;
@@ -1196,10 +1201,9 @@ interface PaymentStatusResult {
     category: string | null;
     expiresAt: string | null;
     createdAt: string;
-    action: {
-        type: 'complete_verification';
-        url: string;
-    } | null;
+    /** Customer-facing reasons for a declined payment or a pending review. */
+    reasons?: string[];
+    action: null;
     transaction: {
         /** Stable Conto transaction ID */
         id: string;
@@ -1858,6 +1862,38 @@ interface ProtocolPreAuthorizeResult {
     authorized: boolean;
     decision: 'approved' | 'declined' | 'review_required';
     message: string;
+    /**
+     * Present when not authorized. Fixed reasons the agent can act on, such as a
+     * spending limit or a service that is not allowed. Never includes rule values.
+     */
+    reasons?: string[];
+    /** Present when not authorized. Codes for `reasons`, for example `SPENDING_LIMIT`. */
+    reasonCodes?: string[];
+    /**
+     * Present when authorized. Pass grantId and grantSignature to record(). A
+     * record without a valid, unexpired grant is accepted but treated as a policy
+     * bypass: the payment is flagged and the owner is alerted. The organization
+     * can also have the agent frozen automatically.
+     */
+    grantId?: string;
+    grantSignature?: string;
+    /** ISO timestamp. Record the payment before this time. */
+    grantExpiresAt?: string;
+}
+interface ProtocolRecordGrant {
+    /** grantId from the approved preAuthorize() response. */
+    grantId?: string;
+    /** grantSignature from the approved preAuthorize() response. */
+    grantSignature?: string;
+}
+interface ProtocolRecordGrantResult {
+    /** Grant consumed by this record. */
+    grantId?: string;
+    /** True when the payment was recorded without a valid grant. */
+    policyBypass?: true;
+    bypassReason?: 'GRANT_MISSING' | 'GRANT_INVALID' | 'GRANT_EXPIRED';
+    /** True when the organization freezes agents on bypass and this record froze it. */
+    agentFrozen?: boolean;
 }
 interface X402PreAuthorizeInput {
     amount: number;
@@ -1884,7 +1920,55 @@ interface X402PreAuthorizeResult extends ProtocolPreAuthorizeResult {
         sessionId?: string;
     };
 }
-interface X402RecordInput {
+/** The accepted entry from a 402 challenge (x402 "exact" scheme on EVM). */
+interface X402PaymentRequirements {
+    scheme: 'exact' | (string & {});
+    /** Network as the challenge sent it: CAIP-2 (eip155:8453) or an x402 v1 name (base). */
+    network: string;
+    /** v1: amount in token base units, as an integer string. */
+    maxAmountRequired?: string;
+    /** v2: amount in token base units, as an integer string. */
+    amount?: string;
+    /** Token contract. Conto signs only for managed USDC. */
+    asset: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    resource?: string;
+    /** EIP-712 domain of the token. */
+    extra?: {
+        name?: string;
+        version?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+interface X402PayInput extends X402PreAuthorizeInput {
+    /** x402 protocol version of the challenge. Defaults to 1. */
+    x402Version?: 1 | 2;
+    paymentRequirements: X402PaymentRequirements;
+}
+interface X402Authorization {
+    from: string;
+    to: string;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: string;
+}
+interface X402PayResult extends ProtocolPreAuthorizeResult {
+    x402: {
+        serviceDomain?: string;
+        amount: number;
+        sessionId?: string;
+    };
+    /** Present when authorized: send as this header when retrying the resource request. */
+    paymentHeaderName?: 'X-PAYMENT' | 'PAYMENT-SIGNATURE';
+    /** Present when authorized: base64 payment payload signed by Conto. */
+    xPaymentHeader?: string;
+    /** Present when authorized: the EIP-3009 authorization Conto signed. */
+    authorization?: X402Authorization;
+}
+interface X402RecordInput extends ProtocolRecordGrant {
     amount: number;
     currency?: string;
     recipientAddress: string;
@@ -1908,7 +1992,7 @@ interface X402RecordInput {
         paymentId: string;
     }>;
 }
-interface X402RecordResult {
+interface X402RecordResult extends ProtocolRecordGrantResult {
     recorded: true;
     confirmed: true;
     txHash: string;
@@ -1939,7 +2023,7 @@ interface MppPreAuthorizeResult extends ProtocolPreAuthorizeResult {
         sessionId?: string;
     };
 }
-interface MppRecordInput {
+interface MppRecordInput extends ProtocolRecordGrant {
     amount: number;
     currency?: string;
     recipientAddress: string;
@@ -1965,7 +2049,7 @@ interface MppRecordInput {
         credentialId: string;
     }>;
 }
-interface MppRecordResult {
+interface MppRecordResult extends ProtocolRecordGrantResult {
     recorded: true;
     txHash?: string;
     explorerUrl?: string;
@@ -2298,7 +2382,9 @@ declare class PaymentsClient {
      * Execute an approved payment.
      *
      * This sends the onchain transaction. Only works for payments
-     * with status 'APPROVED'.
+     * with status 'APPROVED'. If an approver already executed the payment by
+     * approving it in Conto, this returns the existing receipt with
+     * `alreadyExecuted: true` and sends nothing.
      *
      * @param requestId - The requestId from a successful payment request
      *
@@ -2359,6 +2445,16 @@ declare class X402Client {
     private client;
     constructor(client: Conto);
     preAuthorize(input: X402PreAuthorizeInput): Promise<X402PreAuthorizeResult>;
+    /**
+     * Conto-signed x402 for Privy-managed EVM wallets. Conto evaluates the
+     * payment exactly like preAuthorize() and, only when approved, signs the
+     * EIP-3009 authorization for the approved payee and amount. Retry the
+     * resource request with `paymentHeaderName: xPaymentHeader`, then call
+     * record() with the returned grant. Not retried automatically: a grant is
+     * signed at most once, and a repeat returns 409 GRANT_ALREADY_SIGNED.
+     * External wallets get 409 MANAGED_SIGNING_UNAVAILABLE; use preAuthorize().
+     */
+    pay(input: X402PayInput): Promise<X402PayResult>;
     record(input: X402RecordInput): Promise<X402RecordResult>;
     budget(options?: {
         sessionId?: string;
@@ -2382,4 +2478,4 @@ declare class MppClient {
     }): Promise<ProtocolServicesResult>;
 }
 
-export { type AdminExternalCardOverlayEnforcement, type Agent, type AgentCheckoutAction, type AgentCheckoutActionKind, type AgentExternalCard, type AgentSetupResult, type AgentStatus, type AgentType, type AgentWalletLink, type ApprovedExternalCardExecution, type AssignExternalCardInput, type AssignedPolicy, type AuthorizeCheckoutActionResult, type BeginCommerceExecutionInput, type BrowserActionClaimResult, type BrowserActionDispatchObservationInput, BrowserActionFinalizationPendingError, type BrowserActionFinalizeResult, type BrowserCheckoutAction, type BrowserCheckoutTargetResolver, type BrowserCheckoutTargetSnapshot, type BrowserCheckoutTargetVerificationCode, BrowserCheckoutTargetVerificationError, type CanonicalBrowserCheckoutTargetSnapshot, CardsClient, type ChainType, type CheckoutActionAuthorization, type CommerceCheckoutMethod, type CommerceContextRequirement, type CommerceExecution, type CommerceExecutionAdapterKind, type CommerceExecutionArtifactKind, type CommerceExecutionChannel, type CommerceExecutionConstraint, type CommerceExecutionConstraintCoverage, type CommerceExecutionConstraintCoverageLevel, type CommerceExecutionDeliveryMode, type CommerceExecutionEvidence, type CommerceExecutionProvider, type CommerceExecutionResult, type CommerceExecutionSourceKind, type CommerceExecutionStatus, type CommerceFactConfidence, type CommerceFactProvenanceInput, type CommerceFactSource, type CommerceFulfillmentInput, type CommerceLineItemInput, type CommerceProposalFactKey, type CommerceProposalMissingFact, type CommerceProposalResolution, type CommerceProposalState, type CommerceSettlementRail, type CommerceTotalInput, type CommerceTotalType, type ComparePolicyVersionsResponse, type ConnectedCardBrief, type ConnectedCardCredential, type ConnectedCardDrawInput, type ConnectedCardDrawMerchant, type ConnectedCardDrawResult, type ConnectedCardDrawable, type ConnectedCardListResult, type ConnectedCardMandate, type ConnectedCardMandateMerchant, type ConnectedCardReference, ConnectedCardsClient, Conto, ContoAdmin, type ContoAdminConfig, ContoAdminError, type ContoConfig, ContoError, type ContoRequestOptions, type ControlledExternalCardPaymentResult, ControlledExternalCardPaymentTool, type CreateAgentInput, type CreatePolicyInput, type CreatePolicyRuleInput, type CreateSdkKeyInput, type CreateSdkKeyResult, type CreateWalletInput, type CustodyType, type CustomerCustodyMode, type CustomerWalletControlModel, type CustomerWalletKeyAccess, type DelegationType, type ExecuteCommerceExecutionResult, type ExternalCard, type ExternalCardApprovalInput, type ExternalCardApprovalResult, type ExternalCardConfirmationInput, ExternalCardConfirmationPendingError, type ExternalCardConfirmationResult, type ExternalCardExecutionClaimResult, type ExternalCardExecutionResult, type ExternalCardExecutor, type ExternalCardOverlayEnforcement, type ExternalCardRequestStatusResult, type ExternalWalletApprovalInput, type ExternalWalletApprovalResult, type ExternalWalletConfirmationInput, type ExternalWalletConfirmationResult, type FreezeAgentInput, Conto as Giro, type ContoConfig as GiroConfig, ContoError as GiroError, type GuardCheckoutResult, type GuardedBrowserDispatchResult, type GuardedCheckoutInput, type LinkWalletInput, type ListAgentsParams, type ListAgentsResponse, type ListPoliciesParams, type ListPoliciesResponse, type ListPolicyVersionsResponse, type ListStripeLinkPaymentMethodsResult, type ListWalletsParams, type ListWalletsResponse, type MppBudgetResult, type MppPreAuthorizeInput, type MppPreAuthorizeResult, type MppRecordInput, type MppRecordResult, type NormalizeCommerceProposalInput, type OrganizationMember, type PaginatedResponse, type PaginationParams, type PauseExternalCardAssignmentResult, type PaymentExecuteResult, type PaymentRequestInput, type PaymentRequestResult, type PaymentStatusResult, type Policy, type PolicyRule, type PolicyType, type PolicyVersionChangeType, type PolicyVersionDetail, type PolicyVersionDiff, type PolicyVersionFieldChange, type PolicyVersionSnapshot, type PolicyVersionSnapshotRule, type PolicyVersionSummary, type PrivilegedBrowserCheckoutDriver, type ProtocolBudgetResult, type ProtocolPreAuthorizeResult, type ProtocolServiceSummary, type ProtocolServicesResult, type ProvisionWalletResult, type RefreshBalanceResult, type RegisterExternalCardInput, type RollbackPolicyVersionResponse, type RuleAction, type RuleOperator, type RuleType, type RunGuardedCheckoutResult, type SdkKey, type SdkKeyType, type StripeLinkCheckoutReadiness, type StripeLinkCheckoutReadinessResult, type StripeLinkCheckoutReadinessStatus, type StripeLinkCheckoutVerification, type StripeLinkPaymentMethod, type UnfreezeAgentInput, type UpdateAgentInput, type UpdateExternalCardAssignmentInput, type UpdatePolicyInput, type UpdatePolicyRuleInput, type UpdateWalletInput, type VerifiedBrowserCheckoutTarget, type Wallet, type WalletChainBalanceSnapshot, type WalletStatus, type WalletType, type X402BudgetResult, type X402PreAuthorizeInput, type X402PreAuthorizeResult, type X402RecordInput, type X402RecordResult, canonicalizeBrowserCheckoutTarget, createVerifiedBrowserCheckoutDriver, Conto as default, fingerprintBrowserCheckoutTarget };
+export { type AdminExternalCardOverlayEnforcement, type Agent, type AgentCheckoutAction, type AgentCheckoutActionKind, type AgentExternalCard, type AgentSetupResult, type AgentStatus, type AgentType, type AgentWalletLink, type ApprovedExternalCardExecution, type AssignExternalCardInput, type AssignedPolicy, type AuthorizeCheckoutActionResult, type BeginCommerceExecutionInput, type BrowserActionClaimResult, type BrowserActionDispatchObservationInput, BrowserActionFinalizationPendingError, type BrowserActionFinalizeResult, type BrowserCheckoutAction, type BrowserCheckoutTargetResolver, type BrowserCheckoutTargetSnapshot, type BrowserCheckoutTargetVerificationCode, BrowserCheckoutTargetVerificationError, type CanonicalBrowserCheckoutTargetSnapshot, CardsClient, type ChainType, type CheckoutActionAuthorization, type CommerceCheckoutMethod, type CommerceContextRequirement, type CommerceExecution, type CommerceExecutionAdapterKind, type CommerceExecutionArtifactKind, type CommerceExecutionChannel, type CommerceExecutionConstraint, type CommerceExecutionConstraintCoverage, type CommerceExecutionConstraintCoverageLevel, type CommerceExecutionDeliveryMode, type CommerceExecutionEvidence, type CommerceExecutionProvider, type CommerceExecutionResult, type CommerceExecutionSourceKind, type CommerceExecutionStatus, type CommerceFactConfidence, type CommerceFactProvenanceInput, type CommerceFactSource, type CommerceFulfillmentInput, type CommerceLineItemInput, type CommerceProposalFactKey, type CommerceProposalMissingFact, type CommerceProposalResolution, type CommerceProposalState, type CommerceSettlementRail, type CommerceTotalInput, type CommerceTotalType, type ComparePolicyVersionsResponse, type ConnectedCardBrief, type ConnectedCardCredential, type ConnectedCardDrawInput, type ConnectedCardDrawMerchant, type ConnectedCardDrawResult, type ConnectedCardDrawable, type ConnectedCardListResult, type ConnectedCardMandate, type ConnectedCardMandateMerchant, type ConnectedCardReference, ConnectedCardsClient, Conto, ContoAdmin, type ContoAdminConfig, ContoAdminError, type ContoConfig, ContoError, type ContoRequestOptions, type ControlledExternalCardPaymentResult, ControlledExternalCardPaymentTool, type CreateAgentInput, type CreatePolicyInput, type CreatePolicyRuleInput, type CreateSdkKeyInput, type CreateSdkKeyResult, type CreateWalletInput, type CustodyType, type CustomerCustodyMode, type CustomerWalletControlModel, type CustomerWalletKeyAccess, type DelegationType, type ExecuteCommerceExecutionResult, type ExternalCard, type ExternalCardApprovalInput, type ExternalCardApprovalResult, type ExternalCardConfirmationInput, ExternalCardConfirmationPendingError, type ExternalCardConfirmationResult, type ExternalCardExecutionClaimResult, type ExternalCardExecutionResult, type ExternalCardExecutor, type ExternalCardOverlayEnforcement, type ExternalCardRequestStatusResult, type ExternalWalletApprovalInput, type ExternalWalletApprovalResult, type ExternalWalletConfirmationInput, type ExternalWalletConfirmationResult, type FreezeAgentInput, Conto as Giro, type ContoConfig as GiroConfig, ContoError as GiroError, type GuardCheckoutResult, type GuardedBrowserDispatchResult, type GuardedCheckoutInput, type LinkWalletInput, type ListAgentsParams, type ListAgentsResponse, type ListPoliciesParams, type ListPoliciesResponse, type ListPolicyVersionsResponse, type ListStripeLinkPaymentMethodsResult, type ListWalletsParams, type ListWalletsResponse, type MppBudgetResult, type MppPreAuthorizeInput, type MppPreAuthorizeResult, type MppRecordInput, type MppRecordResult, type NormalizeCommerceProposalInput, type OrganizationMember, type PaginatedResponse, type PaginationParams, type PauseExternalCardAssignmentResult, type PaymentExecuteResult, type PaymentRequestInput, type PaymentRequestResult, type PaymentStatusResult, type Policy, type PolicyRule, type PolicyType, type PolicyVersionChangeType, type PolicyVersionDetail, type PolicyVersionDiff, type PolicyVersionFieldChange, type PolicyVersionSnapshot, type PolicyVersionSnapshotRule, type PolicyVersionSummary, type PrivilegedBrowserCheckoutDriver, type ProtocolBudgetResult, type ProtocolPreAuthorizeResult, type ProtocolRecordGrant, type ProtocolRecordGrantResult, type ProtocolServiceSummary, type ProtocolServicesResult, type ProvisionWalletResult, type RefreshBalanceResult, type RegisterExternalCardInput, type RollbackPolicyVersionResponse, type RuleAction, type RuleOperator, type RuleType, type RunGuardedCheckoutResult, type SdkKey, type SdkKeyType, type StripeLinkCheckoutReadiness, type StripeLinkCheckoutReadinessResult, type StripeLinkCheckoutReadinessStatus, type StripeLinkCheckoutVerification, type StripeLinkPaymentMethod, type UnfreezeAgentInput, type UpdateAgentInput, type UpdateExternalCardAssignmentInput, type UpdatePolicyInput, type UpdatePolicyRuleInput, type UpdateWalletInput, type VerifiedBrowserCheckoutTarget, type Wallet, type WalletChainBalanceSnapshot, type WalletStatus, type WalletType, type X402Authorization, type X402BudgetResult, type X402PayInput, type X402PayResult, type X402PaymentRequirements, type X402PreAuthorizeInput, type X402PreAuthorizeResult, type X402RecordInput, type X402RecordResult, canonicalizeBrowserCheckoutTarget, createVerifiedBrowserCheckoutDriver, Conto as default, fingerprintBrowserCheckoutTarget };

package/dist/index.d.ts

@@ -65,7 +65,7 @@ interface PaginatedResponse<T> {
     limit: number;
     offset: number;
 }
-type AgentType = 'OPENAI_ASSISTANT' | 'ANTHROPIC_CLAUDE' | 'LANGCHAIN' | 'AUTOGPT' | 'CUSTOM';
+type AgentType = 'OPENAI_ASSISTANT' | 'ANTHROPIC_CLAUDE' | 'AUTOGPT' | 'CUSTOM';
 type AgentStatus = 'ACTIVE' | 'PAUSED' | 'SUSPENDED' | 'REVOKED' | 'FROZEN' | 'DELETED';
 type AgentEnvironment = 'DEV' | 'STAGING' | 'PROD';
 type AgentRiskTier = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
@@ -1131,7 +1131,7 @@ interface PaymentRequestResult {
     /** Unique request ID - use this to execute or check status */
     requestId: string;
     /** Current status */
-    status: 'APPROVED' | 'DENIED' | 'REQUIRES_APPROVAL' | 'ACTION_REQUIRED' | 'PROCESSING';
+    status: 'APPROVED' | 'DENIED' | 'REQUIRES_APPROVAL' | 'PROCESSING';
     /** Requested amount */
     amount: number;
     /** Currency selected for the payment */
@@ -1164,6 +1164,11 @@ interface PaymentRequestResult {
 interface PaymentExecuteResult {
     /** Payment request ID */
     requestId: string;
+    /**
+     * True when the payment had already been executed, for example by an
+     * approver in Conto. The receipt is the existing one; nothing was sent again.
+     */
+    alreadyExecuted?: boolean;
     /** Customer-facing execution state */
     status: 'processing' | 'completed';
     /** Amount sent */
@@ -1187,7 +1192,7 @@ interface PaymentStatusResult {
     requestId: string;
     /** Unknown for legacy records without execution evidence, or before execution. */
     settlementMode: 'live' | 'test' | 'unknown';
-    status: 'approved' | 'declined' | 'review_required' | 'action_required' | 'reconciliation_required' | 'processing' | 'completed' | 'failed' | 'expired';
+    status: 'approved' | 'declined' | 'review_required' | 'reconciliation_required' | 'processing' | 'completed' | 'failed' | 'expired';
     amount: number;
     currency: string;
     recipient: string;
@@ -1196,10 +1201,9 @@ interface PaymentStatusResult {
     category: string | null;
     expiresAt: string | null;
     createdAt: string;
-    action: {
-        type: 'complete_verification';
-        url: string;
-    } | null;
+    /** Customer-facing reasons for a declined payment or a pending review. */
+    reasons?: string[];
+    action: null;
     transaction: {
         /** Stable Conto transaction ID */
         id: string;
@@ -1858,6 +1862,38 @@ interface ProtocolPreAuthorizeResult {
     authorized: boolean;
     decision: 'approved' | 'declined' | 'review_required';
     message: string;
+    /**
+     * Present when not authorized. Fixed reasons the agent can act on, such as a
+     * spending limit or a service that is not allowed. Never includes rule values.
+     */
+    reasons?: string[];
+    /** Present when not authorized. Codes for `reasons`, for example `SPENDING_LIMIT`. */
+    reasonCodes?: string[];
+    /**
+     * Present when authorized. Pass grantId and grantSignature to record(). A
+     * record without a valid, unexpired grant is accepted but treated as a policy
+     * bypass: the payment is flagged and the owner is alerted. The organization
+     * can also have the agent frozen automatically.
+     */
+    grantId?: string;
+    grantSignature?: string;
+    /** ISO timestamp. Record the payment before this time. */
+    grantExpiresAt?: string;
+}
+interface ProtocolRecordGrant {
+    /** grantId from the approved preAuthorize() response. */
+    grantId?: string;
+    /** grantSignature from the approved preAuthorize() response. */
+    grantSignature?: string;
+}
+interface ProtocolRecordGrantResult {
+    /** Grant consumed by this record. */
+    grantId?: string;
+    /** True when the payment was recorded without a valid grant. */
+    policyBypass?: true;
+    bypassReason?: 'GRANT_MISSING' | 'GRANT_INVALID' | 'GRANT_EXPIRED';
+    /** True when the organization freezes agents on bypass and this record froze it. */
+    agentFrozen?: boolean;
 }
 interface X402PreAuthorizeInput {
     amount: number;
@@ -1884,7 +1920,55 @@ interface X402PreAuthorizeResult extends ProtocolPreAuthorizeResult {
         sessionId?: string;
     };
 }
-interface X402RecordInput {
+/** The accepted entry from a 402 challenge (x402 "exact" scheme on EVM). */
+interface X402PaymentRequirements {
+    scheme: 'exact' | (string & {});
+    /** Network as the challenge sent it: CAIP-2 (eip155:8453) or an x402 v1 name (base). */
+    network: string;
+    /** v1: amount in token base units, as an integer string. */
+    maxAmountRequired?: string;
+    /** v2: amount in token base units, as an integer string. */
+    amount?: string;
+    /** Token contract. Conto signs only for managed USDC. */
+    asset: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    resource?: string;
+    /** EIP-712 domain of the token. */
+    extra?: {
+        name?: string;
+        version?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+interface X402PayInput extends X402PreAuthorizeInput {
+    /** x402 protocol version of the challenge. Defaults to 1. */
+    x402Version?: 1 | 2;
+    paymentRequirements: X402PaymentRequirements;
+}
+interface X402Authorization {
+    from: string;
+    to: string;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: string;
+}
+interface X402PayResult extends ProtocolPreAuthorizeResult {
+    x402: {
+        serviceDomain?: string;
+        amount: number;
+        sessionId?: string;
+    };
+    /** Present when authorized: send as this header when retrying the resource request. */
+    paymentHeaderName?: 'X-PAYMENT' | 'PAYMENT-SIGNATURE';
+    /** Present when authorized: base64 payment payload signed by Conto. */
+    xPaymentHeader?: string;
+    /** Present when authorized: the EIP-3009 authorization Conto signed. */
+    authorization?: X402Authorization;
+}
+interface X402RecordInput extends ProtocolRecordGrant {
     amount: number;
     currency?: string;
     recipientAddress: string;
@@ -1908,7 +1992,7 @@ interface X402RecordInput {
         paymentId: string;
     }>;
 }
-interface X402RecordResult {
+interface X402RecordResult extends ProtocolRecordGrantResult {
     recorded: true;
     confirmed: true;
     txHash: string;
@@ -1939,7 +2023,7 @@ interface MppPreAuthorizeResult extends ProtocolPreAuthorizeResult {
         sessionId?: string;
     };
 }
-interface MppRecordInput {
+interface MppRecordInput extends ProtocolRecordGrant {
     amount: number;
     currency?: string;
     recipientAddress: string;
@@ -1965,7 +2049,7 @@ interface MppRecordInput {
         credentialId: string;
     }>;
 }
-interface MppRecordResult {
+interface MppRecordResult extends ProtocolRecordGrantResult {
     recorded: true;
     txHash?: string;
     explorerUrl?: string;
@@ -2298,7 +2382,9 @@ declare class PaymentsClient {
      * Execute an approved payment.
      *
      * This sends the onchain transaction. Only works for payments
-     * with status 'APPROVED'.
+     * with status 'APPROVED'. If an approver already executed the payment by
+     * approving it in Conto, this returns the existing receipt with
+     * `alreadyExecuted: true` and sends nothing.
      *
      * @param requestId - The requestId from a successful payment request
      *
@@ -2359,6 +2445,16 @@ declare class X402Client {
     private client;
     constructor(client: Conto);
     preAuthorize(input: X402PreAuthorizeInput): Promise<X402PreAuthorizeResult>;
+    /**
+     * Conto-signed x402 for Privy-managed EVM wallets. Conto evaluates the
+     * payment exactly like preAuthorize() and, only when approved, signs the
+     * EIP-3009 authorization for the approved payee and amount. Retry the
+     * resource request with `paymentHeaderName: xPaymentHeader`, then call
+     * record() with the returned grant. Not retried automatically: a grant is
+     * signed at most once, and a repeat returns 409 GRANT_ALREADY_SIGNED.
+     * External wallets get 409 MANAGED_SIGNING_UNAVAILABLE; use preAuthorize().
+     */
+    pay(input: X402PayInput): Promise<X402PayResult>;
     record(input: X402RecordInput): Promise<X402RecordResult>;
     budget(options?: {
         sessionId?: string;
@@ -2382,4 +2478,4 @@ declare class MppClient {
     }): Promise<ProtocolServicesResult>;
 }
 
-export { type AdminExternalCardOverlayEnforcement, type Agent, type AgentCheckoutAction, type AgentCheckoutActionKind, type AgentExternalCard, type AgentSetupResult, type AgentStatus, type AgentType, type AgentWalletLink, type ApprovedExternalCardExecution, type AssignExternalCardInput, type AssignedPolicy, type AuthorizeCheckoutActionResult, type BeginCommerceExecutionInput, type BrowserActionClaimResult, type BrowserActionDispatchObservationInput, BrowserActionFinalizationPendingError, type BrowserActionFinalizeResult, type BrowserCheckoutAction, type BrowserCheckoutTargetResolver, type BrowserCheckoutTargetSnapshot, type BrowserCheckoutTargetVerificationCode, BrowserCheckoutTargetVerificationError, type CanonicalBrowserCheckoutTargetSnapshot, CardsClient, type ChainType, type CheckoutActionAuthorization, type CommerceCheckoutMethod, type CommerceContextRequirement, type CommerceExecution, type CommerceExecutionAdapterKind, type CommerceExecutionArtifactKind, type CommerceExecutionChannel, type CommerceExecutionConstraint, type CommerceExecutionConstraintCoverage, type CommerceExecutionConstraintCoverageLevel, type CommerceExecutionDeliveryMode, type CommerceExecutionEvidence, type CommerceExecutionProvider, type CommerceExecutionResult, type CommerceExecutionSourceKind, type CommerceExecutionStatus, type CommerceFactConfidence, type CommerceFactProvenanceInput, type CommerceFactSource, type CommerceFulfillmentInput, type CommerceLineItemInput, type CommerceProposalFactKey, type CommerceProposalMissingFact, type CommerceProposalResolution, type CommerceProposalState, type CommerceSettlementRail, type CommerceTotalInput, type CommerceTotalType, type ComparePolicyVersionsResponse, type ConnectedCardBrief, type ConnectedCardCredential, type ConnectedCardDrawInput, type ConnectedCardDrawMerchant, type ConnectedCardDrawResult, type ConnectedCardDrawable, type ConnectedCardListResult, type ConnectedCardMandate, type ConnectedCardMandateMerchant, type ConnectedCardReference, ConnectedCardsClient, Conto, ContoAdmin, type ContoAdminConfig, ContoAdminError, type ContoConfig, ContoError, type ContoRequestOptions, type ControlledExternalCardPaymentResult, ControlledExternalCardPaymentTool, type CreateAgentInput, type CreatePolicyInput, type CreatePolicyRuleInput, type CreateSdkKeyInput, type CreateSdkKeyResult, type CreateWalletInput, type CustodyType, type CustomerCustodyMode, type CustomerWalletControlModel, type CustomerWalletKeyAccess, type DelegationType, type ExecuteCommerceExecutionResult, type ExternalCard, type ExternalCardApprovalInput, type ExternalCardApprovalResult, type ExternalCardConfirmationInput, ExternalCardConfirmationPendingError, type ExternalCardConfirmationResult, type ExternalCardExecutionClaimResult, type ExternalCardExecutionResult, type ExternalCardExecutor, type ExternalCardOverlayEnforcement, type ExternalCardRequestStatusResult, type ExternalWalletApprovalInput, type ExternalWalletApprovalResult, type ExternalWalletConfirmationInput, type ExternalWalletConfirmationResult, type FreezeAgentInput, Conto as Giro, type ContoConfig as GiroConfig, ContoError as GiroError, type GuardCheckoutResult, type GuardedBrowserDispatchResult, type GuardedCheckoutInput, type LinkWalletInput, type ListAgentsParams, type ListAgentsResponse, type ListPoliciesParams, type ListPoliciesResponse, type ListPolicyVersionsResponse, type ListStripeLinkPaymentMethodsResult, type ListWalletsParams, type ListWalletsResponse, type MppBudgetResult, type MppPreAuthorizeInput, type MppPreAuthorizeResult, type MppRecordInput, type MppRecordResult, type NormalizeCommerceProposalInput, type OrganizationMember, type PaginatedResponse, type PaginationParams, type PauseExternalCardAssignmentResult, type PaymentExecuteResult, type PaymentRequestInput, type PaymentRequestResult, type PaymentStatusResult, type Policy, type PolicyRule, type PolicyType, type PolicyVersionChangeType, type PolicyVersionDetail, type PolicyVersionDiff, type PolicyVersionFieldChange, type PolicyVersionSnapshot, type PolicyVersionSnapshotRule, type PolicyVersionSummary, type PrivilegedBrowserCheckoutDriver, type ProtocolBudgetResult, type ProtocolPreAuthorizeResult, type ProtocolServiceSummary, type ProtocolServicesResult, type ProvisionWalletResult, type RefreshBalanceResult, type RegisterExternalCardInput, type RollbackPolicyVersionResponse, type RuleAction, type RuleOperator, type RuleType, type RunGuardedCheckoutResult, type SdkKey, type SdkKeyType, type StripeLinkCheckoutReadiness, type StripeLinkCheckoutReadinessResult, type StripeLinkCheckoutReadinessStatus, type StripeLinkCheckoutVerification, type StripeLinkPaymentMethod, type UnfreezeAgentInput, type UpdateAgentInput, type UpdateExternalCardAssignmentInput, type UpdatePolicyInput, type UpdatePolicyRuleInput, type UpdateWalletInput, type VerifiedBrowserCheckoutTarget, type Wallet, type WalletChainBalanceSnapshot, type WalletStatus, type WalletType, type X402BudgetResult, type X402PreAuthorizeInput, type X402PreAuthorizeResult, type X402RecordInput, type X402RecordResult, canonicalizeBrowserCheckoutTarget, createVerifiedBrowserCheckoutDriver, Conto as default, fingerprintBrowserCheckoutTarget };
+export { type AdminExternalCardOverlayEnforcement, type Agent, type AgentCheckoutAction, type AgentCheckoutActionKind, type AgentExternalCard, type AgentSetupResult, type AgentStatus, type AgentType, type AgentWalletLink, type ApprovedExternalCardExecution, type AssignExternalCardInput, type AssignedPolicy, type AuthorizeCheckoutActionResult, type BeginCommerceExecutionInput, type BrowserActionClaimResult, type BrowserActionDispatchObservationInput, BrowserActionFinalizationPendingError, type BrowserActionFinalizeResult, type BrowserCheckoutAction, type BrowserCheckoutTargetResolver, type BrowserCheckoutTargetSnapshot, type BrowserCheckoutTargetVerificationCode, BrowserCheckoutTargetVerificationError, type CanonicalBrowserCheckoutTargetSnapshot, CardsClient, type ChainType, type CheckoutActionAuthorization, type CommerceCheckoutMethod, type CommerceContextRequirement, type CommerceExecution, type CommerceExecutionAdapterKind, type CommerceExecutionArtifactKind, type CommerceExecutionChannel, type CommerceExecutionConstraint, type CommerceExecutionConstraintCoverage, type CommerceExecutionConstraintCoverageLevel, type CommerceExecutionDeliveryMode, type CommerceExecutionEvidence, type CommerceExecutionProvider, type CommerceExecutionResult, type CommerceExecutionSourceKind, type CommerceExecutionStatus, type CommerceFactConfidence, type CommerceFactProvenanceInput, type CommerceFactSource, type CommerceFulfillmentInput, type CommerceLineItemInput, type CommerceProposalFactKey, type CommerceProposalMissingFact, type CommerceProposalResolution, type CommerceProposalState, type CommerceSettlementRail, type CommerceTotalInput, type CommerceTotalType, type ComparePolicyVersionsResponse, type ConnectedCardBrief, type ConnectedCardCredential, type ConnectedCardDrawInput, type ConnectedCardDrawMerchant, type ConnectedCardDrawResult, type ConnectedCardDrawable, type ConnectedCardListResult, type ConnectedCardMandate, type ConnectedCardMandateMerchant, type ConnectedCardReference, ConnectedCardsClient, Conto, ContoAdmin, type ContoAdminConfig, ContoAdminError, type ContoConfig, ContoError, type ContoRequestOptions, type ControlledExternalCardPaymentResult, ControlledExternalCardPaymentTool, type CreateAgentInput, type CreatePolicyInput, type CreatePolicyRuleInput, type CreateSdkKeyInput, type CreateSdkKeyResult, type CreateWalletInput, type CustodyType, type CustomerCustodyMode, type CustomerWalletControlModel, type CustomerWalletKeyAccess, type DelegationType, type ExecuteCommerceExecutionResult, type ExternalCard, type ExternalCardApprovalInput, type ExternalCardApprovalResult, type ExternalCardConfirmationInput, ExternalCardConfirmationPendingError, type ExternalCardConfirmationResult, type ExternalCardExecutionClaimResult, type ExternalCardExecutionResult, type ExternalCardExecutor, type ExternalCardOverlayEnforcement, type ExternalCardRequestStatusResult, type ExternalWalletApprovalInput, type ExternalWalletApprovalResult, type ExternalWalletConfirmationInput, type ExternalWalletConfirmationResult, type FreezeAgentInput, Conto as Giro, type ContoConfig as GiroConfig, ContoError as GiroError, type GuardCheckoutResult, type GuardedBrowserDispatchResult, type GuardedCheckoutInput, type LinkWalletInput, type ListAgentsParams, type ListAgentsResponse, type ListPoliciesParams, type ListPoliciesResponse, type ListPolicyVersionsResponse, type ListStripeLinkPaymentMethodsResult, type ListWalletsParams, type ListWalletsResponse, type MppBudgetResult, type MppPreAuthorizeInput, type MppPreAuthorizeResult, type MppRecordInput, type MppRecordResult, type NormalizeCommerceProposalInput, type OrganizationMember, type PaginatedResponse, type PaginationParams, type PauseExternalCardAssignmentResult, type PaymentExecuteResult, type PaymentRequestInput, type PaymentRequestResult, type PaymentStatusResult, type Policy, type PolicyRule, type PolicyType, type PolicyVersionChangeType, type PolicyVersionDetail, type PolicyVersionDiff, type PolicyVersionFieldChange, type PolicyVersionSnapshot, type PolicyVersionSnapshotRule, type PolicyVersionSummary, type PrivilegedBrowserCheckoutDriver, type ProtocolBudgetResult, type ProtocolPreAuthorizeResult, type ProtocolRecordGrant, type ProtocolRecordGrantResult, type ProtocolServiceSummary, type ProtocolServicesResult, type ProvisionWalletResult, type RefreshBalanceResult, type RegisterExternalCardInput, type RollbackPolicyVersionResponse, type RuleAction, type RuleOperator, type RuleType, type RunGuardedCheckoutResult, type SdkKey, type SdkKeyType, type StripeLinkCheckoutReadiness, type StripeLinkCheckoutReadinessResult, type StripeLinkCheckoutReadinessStatus, type StripeLinkCheckoutVerification, type StripeLinkPaymentMethod, type UnfreezeAgentInput, type UpdateAgentInput, type UpdateExternalCardAssignmentInput, type UpdatePolicyInput, type UpdatePolicyRuleInput, type UpdateWalletInput, type VerifiedBrowserCheckoutTarget, type Wallet, type WalletChainBalanceSnapshot, type WalletStatus, type WalletType, type X402Authorization, type X402BudgetResult, type X402PayInput, type X402PayResult, type X402PaymentRequirements, type X402PreAuthorizeInput, type X402PreAuthorizeResult, type X402RecordInput, type X402RecordResult, canonicalizeBrowserCheckoutTarget, createVerifiedBrowserCheckoutDriver, Conto as default, fingerprintBrowserCheckoutTarget };

package/dist/index.js

@@ -39,7 +39,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@conto_finance/sdk",
-      version: "0.4.0",
+      version: "0.5.1",
       description: "Conto SDK for AI agent payment authorization",
       main: "./dist/index.js",
       module: "./dist/index.mjs",
@@ -172,7 +172,10 @@ var PUBLIC_PAYMENT_REASONS = /* @__PURE__ */ new Set([
   "This payment is outside the permitted schedule.",
   "The available payment budget is insufficient.",
   "This payment does not meet the current payment controls.",
-  "This payment requires approval before it can proceed."
+  "This payment requires approval before it can proceed.",
+  "No usable wallet is linked to this agent.",
+  "This payee needs review before payments to it can proceed automatically.",
+  "A reviewer declined this payment."
 ]);
 function customerPaymentReasons(value) {
   return Array.isArray(value) ? [
@@ -352,9 +355,11 @@ function responseErrorMetadata(response, data) {
   const body = record(data);
   const code = safeErrorCode(body.code, response.status);
   const bodyRetryAfter = typeof body.retryAfter === "number" || typeof body.retryAfter === "string" ? parseRetryAfter(String(body.retryAfter)) : void 0;
+  const reasons = customerPaymentReasons(body.reasons);
   return {
     code,
     status: response.status,
+    ...reasons.length > 0 ? { reasons } : {},
     fieldErrors: customerFieldErrors(body, response.status),
     requestId: safeRequestId(
       response.headers.get("x-request-id"),
@@ -1705,6 +1710,27 @@ var ConnectedCardsClient = class {
     return this.client.request("GET", "/api/sdk/connected-cards");
   }
 };
+function approvalRetryGuidance(requestId) {
+  const id = JSON.stringify(requestId);
+  return `An approver in Conto executes the payment when they approve it. After approval, call payments.execute(${id}) or payments.status(${id}) to get the receipt. Do not request the payment again.`;
+}
+function executeRetryGuidance(code, requestId) {
+  const id = JSON.stringify(requestId);
+  switch (code) {
+    case "APPROVAL_PENDING":
+      return approvalRetryGuidance(requestId);
+    case "POLICY_DENIED_AT_EXECUTION":
+    case "PAYMENT_DENIED":
+      return "This payment was declined and will not execute. Do not retry it; review the reasons before requesting a new payment.";
+    case "POLICY_REAPPROVAL_REQUIRED":
+      return "This payment now needs approval and will not execute. Request a new payment and wait for approval.";
+    case "PAYMENT_PROCESSING":
+    case "NEEDS_RECONCILIATION":
+      return `Do not execute again. Check payments.status(${id}) for the outcome.`;
+    default:
+      return void 0;
+  }
+}
 var PaymentsClient = class {
   constructor(client) {
     this.client = client;
@@ -1778,7 +1804,9 @@ var PaymentsClient = class {
    * Execute an approved payment.
    *
    * This sends the onchain transaction. Only works for payments
-   * with status 'APPROVED'.
+   * with status 'APPROVED'. If an approver already executed the payment by
+   * approving it in Conto, this returns the existing receipt with
+   * `alreadyExecuted: true` and sends nothing.
    *
    * @param requestId - The requestId from a successful payment request
    *
@@ -1800,18 +1828,17 @@ var PaymentsClient = class {
         {}
       );
     } catch (error) {
-      if (error instanceof ContoError && error.status === 0) {
-        throw new ContoError(error.message, {
-          code: error.code,
-          status: error.status,
-          requestId: error.requestId,
-          retryAfter: error.retryAfter,
-          retryGuidance: `Check payments.status(${JSON.stringify(
-            requestId
-          )}) before attempting execution again.`
-        });
-      }
-      throw error;
+      if (!(error instanceof ContoError)) throw error;
+      const retryGuidance = error.status === 0 ? `Check payments.status(${JSON.stringify(requestId)}) before attempting execution again.` : executeRetryGuidance(error.code, requestId);
+      if (!retryGuidance) throw error;
+      throw new ContoError(error.message, {
+        code: error.code,
+        status: error.status,
+        requestId: error.requestId,
+        retryAfter: error.retryAfter,
+        reasons: error.reasons,
+        retryGuidance
+      });
     }
   }
   /**
@@ -1876,17 +1903,9 @@ var PaymentsClient = class {
       throw new ContoError("Payment requires manual approval", {
         code: "REQUIRES_APPROVAL",
         status: 202,
+        reasons: customerPaymentReasons(request.reasons),
         requestId: request.requestId,
-        retryGuidance: "Wait for approval, then execute the same request ID."
-      });
-    }
-    if (request.status === "ACTION_REQUIRED") {
-      throw new ContoError("Payment requires an additional action", {
-        code: "ACTION_REQUIRED",
-        status: 402,
-        requestId: request.requestId,
-        actionUrl: request.actionUrl,
-        retryGuidance: request.actionUrl ? `Complete the required action at ${request.actionUrl}, then check the payment status.` : "Complete the required action, then check the payment status."
+        retryGuidance: approvalRetryGuidance(request.requestId)
       });
     }
     if (request.status === "PROCESSING") {
@@ -1912,6 +1931,22 @@ var X402Client = class {
       { idempotent: true }
     );
   }
+  /**
+   * Conto-signed x402 for Privy-managed EVM wallets. Conto evaluates the
+   * payment exactly like preAuthorize() and, only when approved, signs the
+   * EIP-3009 authorization for the approved payee and amount. Retry the
+   * resource request with `paymentHeaderName: xPaymentHeader`, then call
+   * record() with the returned grant. Not retried automatically: a grant is
+   * signed at most once, and a repeat returns 409 GRANT_ALREADY_SIGNED.
+   * External wallets get 409 MANAGED_SIGNING_UNAVAILABLE; use preAuthorize().
+   */
+  async pay(input) {
+    return this.client.request(
+      "POST",
+      "/api/sdk/x402/pay",
+      input
+    );
+  }
   async record(input) {
     const paymentId = requireFinancialIdentifier(input.paymentId, "paymentId");
     const requestInput = {

package/dist/index.mjs

@@ -14,7 +14,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@conto_finance/sdk",
-      version: "0.4.0",
+      version: "0.5.1",
       description: "Conto SDK for AI agent payment authorization",
       main: "./dist/index.js",
       module: "./dist/index.mjs",
@@ -128,7 +128,10 @@ var PUBLIC_PAYMENT_REASONS = /* @__PURE__ */ new Set([
   "This payment is outside the permitted schedule.",
   "The available payment budget is insufficient.",
   "This payment does not meet the current payment controls.",
-  "This payment requires approval before it can proceed."
+  "This payment requires approval before it can proceed.",
+  "No usable wallet is linked to this agent.",
+  "This payee needs review before payments to it can proceed automatically.",
+  "A reviewer declined this payment."
 ]);
 function customerPaymentReasons(value) {
   return Array.isArray(value) ? [
@@ -308,9 +311,11 @@ function responseErrorMetadata(response, data) {
   const body = record(data);
   const code = safeErrorCode(body.code, response.status);
   const bodyRetryAfter = typeof body.retryAfter === "number" || typeof body.retryAfter === "string" ? parseRetryAfter(String(body.retryAfter)) : void 0;
+  const reasons = customerPaymentReasons(body.reasons);
   return {
     code,
     status: response.status,
+    ...reasons.length > 0 ? { reasons } : {},
     fieldErrors: customerFieldErrors(body, response.status),
     requestId: safeRequestId(
       response.headers.get("x-request-id"),
@@ -1544,6 +1549,27 @@ var ConnectedCardsClient = class {
     return this.client.request("GET", "/api/sdk/connected-cards");
   }
 };
+function approvalRetryGuidance(requestId) {
+  const id = JSON.stringify(requestId);
+  return `An approver in Conto executes the payment when they approve it. After approval, call payments.execute(${id}) or payments.status(${id}) to get the receipt. Do not request the payment again.`;
+}
+function executeRetryGuidance(code, requestId) {
+  const id = JSON.stringify(requestId);
+  switch (code) {
+    case "APPROVAL_PENDING":
+      return approvalRetryGuidance(requestId);
+    case "POLICY_DENIED_AT_EXECUTION":
+    case "PAYMENT_DENIED":
+      return "This payment was declined and will not execute. Do not retry it; review the reasons before requesting a new payment.";
+    case "POLICY_REAPPROVAL_REQUIRED":
+      return "This payment now needs approval and will not execute. Request a new payment and wait for approval.";
+    case "PAYMENT_PROCESSING":
+    case "NEEDS_RECONCILIATION":
+      return `Do not execute again. Check payments.status(${id}) for the outcome.`;
+    default:
+      return void 0;
+  }
+}
 var PaymentsClient = class {
   constructor(client) {
     this.client = client;
@@ -1617,7 +1643,9 @@ var PaymentsClient = class {
    * Execute an approved payment.
    *
    * This sends the onchain transaction. Only works for payments
-   * with status 'APPROVED'.
+   * with status 'APPROVED'. If an approver already executed the payment by
+   * approving it in Conto, this returns the existing receipt with
+   * `alreadyExecuted: true` and sends nothing.
    *
    * @param requestId - The requestId from a successful payment request
    *
@@ -1639,18 +1667,17 @@ var PaymentsClient = class {
         {}
       );
     } catch (error) {
-      if (error instanceof ContoError && error.status === 0) {
-        throw new ContoError(error.message, {
-          code: error.code,
-          status: error.status,
-          requestId: error.requestId,
-          retryAfter: error.retryAfter,
-          retryGuidance: `Check payments.status(${JSON.stringify(
-            requestId
-          )}) before attempting execution again.`
-        });
-      }
-      throw error;
+      if (!(error instanceof ContoError)) throw error;
+      const retryGuidance = error.status === 0 ? `Check payments.status(${JSON.stringify(requestId)}) before attempting execution again.` : executeRetryGuidance(error.code, requestId);
+      if (!retryGuidance) throw error;
+      throw new ContoError(error.message, {
+        code: error.code,
+        status: error.status,
+        requestId: error.requestId,
+        retryAfter: error.retryAfter,
+        reasons: error.reasons,
+        retryGuidance
+      });
     }
   }
   /**
@@ -1715,17 +1742,9 @@ var PaymentsClient = class {
       throw new ContoError("Payment requires manual approval", {
         code: "REQUIRES_APPROVAL",
         status: 202,
+        reasons: customerPaymentReasons(request.reasons),
         requestId: request.requestId,
-        retryGuidance: "Wait for approval, then execute the same request ID."
-      });
-    }
-    if (request.status === "ACTION_REQUIRED") {
-      throw new ContoError("Payment requires an additional action", {
-        code: "ACTION_REQUIRED",
-        status: 402,
-        requestId: request.requestId,
-        actionUrl: request.actionUrl,
-        retryGuidance: request.actionUrl ? `Complete the required action at ${request.actionUrl}, then check the payment status.` : "Complete the required action, then check the payment status."
+        retryGuidance: approvalRetryGuidance(request.requestId)
       });
     }
     if (request.status === "PROCESSING") {
@@ -1751,6 +1770,22 @@ var X402Client = class {
       { idempotent: true }
     );
   }
+  /**
+   * Conto-signed x402 for Privy-managed EVM wallets. Conto evaluates the
+   * payment exactly like preAuthorize() and, only when approved, signs the
+   * EIP-3009 authorization for the approved payee and amount. Retry the
+   * resource request with `paymentHeaderName: xPaymentHeader`, then call
+   * record() with the returned grant. Not retried automatically: a grant is
+   * signed at most once, and a repeat returns 409 GRANT_ALREADY_SIGNED.
+   * External wallets get 409 MANAGED_SIGNING_UNAVAILABLE; use preAuthorize().
+   */
+  async pay(input) {
+    return this.client.request(
+      "POST",
+      "/api/sdk/x402/pay",
+      input
+    );
+  }
   async record(input) {
     const paymentId = requireFinancialIdentifier(input.paymentId, "paymentId");
     const requestInput = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@conto_finance/sdk",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Conto SDK for AI agent payment authorization",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",