@conto_finance/sdk 0.1.0 → 0.3.1

package/dist/index.d.ts

@@ -1,3 +1,12 @@
+interface ApiErrorMetadata {
+    code: string;
+    status: number;
+    requestId?: string;
+    retryAfter?: number;
+    retryGuidance?: string;
+    actionUrl?: string;
+}
+
 /**
  * Conto Admin SDK
  *
@@ -24,6 +33,7 @@
  * await admin.agents.assignPolicy(agentId, policy.id);
  * ```
  */
+
 interface ContoAdminConfig {
     /** Your organization API key (conto_xxx...) */
     orgApiKey: string;
@@ -32,9 +42,13 @@ interface ContoAdminConfig {
     /** Request timeout in milliseconds. Defaults to 30000 */
     timeout?: number;
 }
-interface ContoAdminError extends Error {
-    code: string;
-    status: number;
+declare class ContoAdminError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly requestId?: string;
+    readonly retryAfter?: number;
+    readonly retryGuidance?: string;
+    constructor(message: string, metadata: ApiErrorMetadata);
 }
 interface PaginationParams {
     limit?: number;
@@ -53,7 +67,9 @@ type AgentRiskTier = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
 type AgentAttestationMode = 'KEY_ONLY' | 'SIGNED_REQUEST' | 'SIGNED_REQUEST_WITH_CONTEXT';
 type DelegationType = 'FULL' | 'LIMITED' | 'VIEW_ONLY' | 'PREAPPROVED' | 'ALLOWLIST';
 type ChainType = 'EVM' | 'SOLANA';
-type CustodyType = 'PRIVY' | 'SPONGE' | 'EXTERNAL' | 'SMART_CONTRACT';
+type CustomerCustodyMode = 'MANAGED' | 'EXTERNAL' | 'SMART_CONTRACT';
+/** @deprecated Use CustomerCustodyMode. */
+type CustodyType = CustomerCustodyMode;
 type WalletType = 'EOA' | 'SMART_WALLET' | 'MULTISIG';
 type WalletStatus = 'ACTIVE' | 'FROZEN' | 'CLOSED' | 'ARCHIVED';
 type PolicyType = 'SPEND_LIMIT' | 'MERCHANT' | 'TIME_WINDOW' | 'CATEGORY' | 'VELOCITY' | 'COMPOSITE' | 'GEOGRAPHIC' | 'APPROVAL_THRESHOLD' | 'COUNTERPARTY' | 'BUDGET_ALLOCATION' | 'WHITELIST' | 'EXPIRATION' | 'CONTRACT_ALLOWLIST' | 'BLACKOUT_PERIOD';
@@ -72,25 +88,37 @@ interface Agent {
     riskTier?: AgentRiskTier;
     publicKey: string;
     status: AgentStatus;
-    externalId: string | null;
     attestationMode?: AgentAttestationMode;
     identityTags?: string[];
-    ownerMembershipId?: string | null;
+    externalId: string | null;
+    allowedContexts: string[];
+    webhookConfigured: boolean;
+    /** Callback query and fragment values are redacted in API responses. */
+    callbackUrl: string | null;
     owner?: {
         membershipId: string;
-        role: string;
-        userId?: string | null;
         name?: string | null;
-        email?: string | null;
     } | null;
-    allowedContexts: string | null;
-    organizationId: string;
+    setup: {
+        status: 'READY' | 'ACTION_REQUIRED';
+        issueCount: number;
+        issues: Array<{
+            code: 'OWNER_REQUIRED' | 'IDENTITY_SLUG_REQUIRED' | 'PURPOSE_REQUIRED';
+            field: 'ownerMembershipId' | 'agentIdSlug' | 'purpose';
+            severity: 'BLOCKING' | 'RECOMMENDED';
+            message: string;
+        }>;
+    };
     createdAt: string;
     updatedAt: string;
+    linkedWalletCount: number;
+    transactionCount: number;
     wallets?: AgentWalletLink[];
-    _count?: {
-        sentTransactions: number;
-    };
+    nextSteps?: Record<'createSdkKey' | 'linkWallet' | 'assignPolicy', {
+        method: 'POST';
+        path: string;
+        description: string;
+    }>;
 }
 interface CreateAgentInput {
     name: string;
@@ -106,6 +134,7 @@ interface CreateAgentInput {
     attestationMode?: AgentAttestationMode;
     identityTags?: string[];
     allowedContexts?: string[];
+    callbackUrl?: string;
 }
 interface UpdateAgentInput {
     name?: string;
@@ -120,6 +149,7 @@ interface UpdateAgentInput {
     attestationMode?: AgentAttestationMode;
     identityTags?: string[] | null;
     allowedContexts?: string[];
+    callbackUrl?: string | null;
 }
 interface ListAgentsParams extends PaginationParams {
     status?: string;
@@ -132,23 +162,26 @@ interface ListAgentsResponse {
     offset: number;
 }
 interface FreezeAgentInput {
-    reason: string;
     freezeWallets?: boolean;
 }
 interface UnfreezeAgentInput {
-    reason: string;
     unfreezeWallets?: boolean;
-    resetCounters?: boolean;
 }
 interface AgentWalletLink {
     id: string;
-    agentId: string;
     walletId: string;
     delegationType: DelegationType;
-    spendLimitPerTx: number;
-    spendLimitDaily: number;
+    spendLimitPerTx: number | null;
+    spendLimitDaily: number | null;
     spendLimitWeekly: number | null;
     spendLimitMonthly: number | null;
+    spentToday: number;
+    spentThisWeek: number;
+    spentThisMonth: number;
+    allowedHoursStart: number;
+    allowedHoursEnd: number;
+    allowedDays: string[];
+    timezone: string;
     isActive: boolean;
     wallet?: {
         id: string;
@@ -156,13 +189,203 @@ interface AgentWalletLink {
         address: string;
         usdcBalance: number;
         status: string;
-        custodyType?: string;
+        custodyMode?: CustomerCustodyMode;
     };
+    createdAt: string;
+    updatedAt: string;
+}
+interface AdminExternalCardOverlayEnforcement {
+    enforcementMode: 'POLICY_OVERLAY';
+    integrationMode: 'SDK_REQUIRED';
+    canBypass: true;
+    credentialStored: false;
+    credentialReleased: false;
+    executionResponsibility: 'CUSTOMER';
+    transactionVerification: 'SELF_REPORTED';
+}
+interface ExternalCard {
+    id: string;
+    name: string;
+    last4: string;
+    brand: 'VISA' | 'MASTERCARD' | 'AMEX' | 'DISCOVER' | 'OTHER' | null;
+    cardType: 'VIRTUAL' | 'PHYSICAL';
+    fundingType: 'DEBIT' | 'CREDIT';
+    status: 'ACTIVE' | 'PAUSED' | 'LOCKED' | 'EXPIRED' | 'CANCELLED';
+    isActive: boolean;
+    spendLimitDaily: number;
+    spendLimitWeekly: number | null;
+    spendLimitMonthly: number | null;
+    spendLimitPerTx: number;
+    spentToday: number;
+    spentThisWeek: number;
+    spentThisMonth: number;
+    remainingToday: number;
+    agentCount: number;
+    transactionCount: number;
+    enforcement: AdminExternalCardOverlayEnforcement;
+    createdAt: string;
+    updatedAt: string;
+}
+interface RegisterExternalCardInput {
+    name: string;
+    last4: string;
+    brand?: 'VISA' | 'MASTERCARD' | 'AMEX' | 'DISCOVER' | 'OTHER';
+    cardType?: 'VIRTUAL' | 'PHYSICAL';
+    fundingType?: 'DEBIT' | 'CREDIT';
+    spendLimitDaily?: number;
+    spendLimitWeekly?: number;
+    spendLimitMonthly?: number;
+    spendLimitPerTx?: number;
+    notes?: string;
+}
+interface AssignExternalCardInput {
+    cardId: string;
+    spendLimitDaily?: number;
+    spendLimitWeekly?: number;
+    spendLimitMonthly?: number;
+    spendLimitPerTx?: number;
+    allowedDays?: Array<'Sun' | 'Mon' | 'Tue' | 'Wed' | 'Thu' | 'Fri' | 'Sat'>;
+    allowedHoursStart?: number;
+    allowedHoursEnd?: number;
+    timezone: string;
+    allowedCategories?: string[];
+    blockedCategories?: string[];
+    allowedMerchants?: string[];
+    blockedMerchants?: string[];
+    activeFrom?: string | null;
+    activeUntil?: string | null;
+}
+type UpdateExternalCardAssignmentInput = Partial<Omit<AssignExternalCardInput, 'cardId'>>;
+interface AgentExternalCard {
+    id: string;
+    cardId: string;
+    cardName: string;
+    last4: string;
+    brand: string | null;
+    cardType: string;
+    fundingType: string;
+    cardStatus: string;
+    accessStatus: 'ACTIVE' | 'PAUSED' | 'REVOKED';
+    spendLimitDaily: number;
+    spendLimitWeekly: number | null;
+    spendLimitMonthly: number | null;
+    spendLimitPerTx: number;
+    spentToday: number;
+    spentThisWeek: number;
+    spentThisMonth: number;
+    remainingToday: number;
+    allowedDays: string[];
+    allowedHoursStart: number;
+    allowedHoursEnd: number;
+    timezone: string;
+    allowedCategories: string[] | null;
+    blockedCategories: string[] | null;
+    allowedMerchants: string[] | null;
+    blockedMerchants: string[] | null;
+    activeFrom: string | null;
+    activeUntil: string | null;
+    isActive: boolean;
+    enforcement: AdminExternalCardOverlayEnforcement;
+    createdAt: string;
+}
+interface RevokeExternalCardAssignmentResult {
+    unassigned: true;
+    cardId: string;
+    agentId: string;
+    revokedApprovals: number;
+    executingRequests: number;
+    reconciliationRequired: boolean;
+    enforcement: AdminExternalCardOverlayEnforcement;
+}
+interface PauseExternalCardAssignmentResult {
+    accessStatus: 'PAUSED';
+    cardId: string;
+    agentId: string;
+    revokedApprovals: number;
+    executingRequests: number;
+    reconciliationRequired: boolean;
+    enforcement: AdminExternalCardOverlayEnforcement;
+}
+type ExternalCardRequestStatus = 'APPROVED' | 'EXECUTING' | 'CONFIRMING' | 'COMPLETED' | 'DENIED' | 'EXPIRED' | 'CANCELLED';
+interface ExternalCardOverlayRequest {
+    requestId: string;
+    status: ExternalCardRequestStatus;
+    decision: string;
+    amount: number;
+    currency: string;
+    merchantName: string | null;
+    merchantId: string | null;
+    merchantCategory: string | null;
+    purpose: string | null;
+    expiresAt: string | null;
+    executionClaimedAt: string | null;
+    reconciliationRequired: boolean;
+    nextAction: 'BEGIN_EXECUTION' | 'CONFIRM_OR_RECONCILE' | 'POLL' | 'NONE';
+    transactionId: string | null;
+    transaction: {
+        id: string;
+        status: string;
+        amount: number;
+        currency: string;
+        externalTxId: string | null;
+        authorizedAt: string | null;
+    } | null;
+    card: {
+        id: string;
+        name: string;
+        last4: string;
+        brand: string | null;
+    };
+    agent: {
+        id: string;
+        name: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+    enforcement: AdminExternalCardOverlayEnforcement;
+}
+interface ListExternalCardRequestsInput {
+    status?: ExternalCardRequestStatus;
+    limit?: number;
+}
+interface ListExternalCardRequestsResponse {
+    requests: ExternalCardOverlayRequest[];
+    summary: Partial<Record<ExternalCardRequestStatus, number>>;
+    enforcement: AdminExternalCardOverlayEnforcement;
+}
+interface ResolveExternalCardRequestInput {
+    resolution: 'EXECUTED' | 'NOT_EXECUTED';
+    reason: string;
+    externalTxId?: string;
+    authorizationCode?: string;
+    actualAmount?: number;
+    merchantDetails?: {
+        name?: string;
+        id?: string;
+        category?: string;
+        address?: string;
+        city?: string;
+        state?: string;
+        country?: string;
+        postalCode?: string;
+    };
+}
+interface ResolveExternalCardRequestResult {
+    resolved: true;
+    requestId?: string;
+    status: string;
+    reservationReleased?: boolean;
+    releasedAmount?: number;
+    confirmed?: true;
+    replayed?: boolean;
+    transactionId?: string;
+    amount?: number;
+    currency?: string;
+    verificationStatus?: 'SELF_REPORTED';
+    enforcement?: AdminExternalCardOverlayEnforcement;
 }
 interface OrganizationMember {
     id: string;
-    organizationId: string;
-    userId: string;
     role: 'OWNER' | 'ADMIN' | 'MANAGER' | 'VIEWER' | 'MEMBER';
     createdAt: string;
     updatedAt: string;
@@ -215,24 +438,20 @@ interface Wallet {
     chainType: ChainType;
     chainId: string;
     walletType: WalletType;
-    custodyType: CustodyType;
+    custodyMode: CustomerCustodyMode;
     usdcBalance: number;
     status: WalletStatus;
-    externalWalletId: string | null;
-    organizationId: string;
     createdAt: string;
     updatedAt: string;
+    linkedAgentCount?: number;
 }
 interface CreateWalletInput {
     name: string;
     chainType?: ChainType;
     chainId?: string;
-    custodyType?: CustodyType;
+    custodyMode?: Extract<CustomerCustodyMode, 'MANAGED' | 'EXTERNAL'>;
     walletType?: WalletType;
     address?: string;
-    externalWalletId?: string;
-    importAddress?: string;
-    isWatchOnly?: boolean;
 }
 interface UpdateWalletInput {
     name?: string;
@@ -256,7 +475,7 @@ interface ProvisionWalletResult {
         address: string;
         chainId: string;
         chainType: string;
-        custodyType: string;
+        custodyMode: CustomerCustodyMode;
         balance: number;
         currency: string;
     };
@@ -286,21 +505,32 @@ interface PolicyRule {
     value: string;
     action: RuleAction;
     createdAt: string;
+    updatedAt: string;
 }
 interface Policy {
     id: string;
     name: string;
     description: string | null;
     policyType: PolicyType;
+    scope: 'organization' | 'assigned';
     priority: number;
     isActive: boolean;
-    organizationId: string;
     rules?: PolicyRule[];
+    assignedAgents?: Array<{
+        id: string;
+        name: string;
+    }>;
+    assignedWallets?: Array<{
+        id: string;
+        name: string;
+    }>;
     createdAt: string;
     updatedAt: string;
-    _count?: {
-        agentPolicies: number;
-    };
+}
+interface AssignedPolicy {
+    policyId: string;
+    assignedAt: string;
+    policy: Policy;
 }
 interface CreatePolicyInput {
     name: string;
@@ -308,6 +538,7 @@ interface CreatePolicyInput {
     description?: string;
     priority?: number;
     isActive?: boolean;
+    scope?: 'organization' | 'assigned';
     rules?: CreatePolicyRuleInput[];
     agentIds?: string[];
 }
@@ -316,6 +547,7 @@ interface UpdatePolicyInput {
     description?: string;
     priority?: number;
     isActive?: boolean;
+    scope?: 'organization' | 'assigned';
 }
 interface ListPoliciesParams extends PaginationParams {
 }
@@ -343,13 +575,73 @@ declare class ContoAdmin {
     private timeout;
     agents: AgentsClient;
     wallets: WalletsClient;
+    cards: AdminCardsClient;
     policies: PoliciesClient;
     team: TeamClient;
     constructor(config: ContoAdminConfig);
-    private fetchWithRetry;
     /** Make an authenticated request to the Conto API */
     request<T>(method: string, path: string, body?: Record<string, unknown>): Promise<T>;
 }
+declare class AdminCardsClient {
+    private client;
+    constructor(client: ContoAdmin);
+    /** List masked external-card aliases. No card credentials are returned. */
+    list(): Promise<{
+        cards: ExternalCard[];
+        enforcement: AdminExternalCardOverlayEnforcement;
+    }>;
+    /** Register a masked alias for a customer card. Never pass PAN or CVC. */
+    register(input: RegisterExternalCardInput): Promise<{
+        card: ExternalCard;
+        enforcement: AdminExternalCardOverlayEnforcement;
+    }>;
+    /** Assign a card alias and cooperative policy controls to an agent. */
+    assignToAgent(agentId: string, input: AssignExternalCardInput): Promise<{
+        agentCard: AgentExternalCard;
+        enforcement: AdminExternalCardOverlayEnforcement;
+    }>;
+    listForAgent(agentId: string): Promise<{
+        cards: AgentExternalCard[];
+        enforcement: AdminExternalCardOverlayEnforcement;
+    }>;
+    /** Update limits, merchant rules, hours, and optional start or end dates. */
+    updateAgentAssignment(agentId: string, cardId: string, input: UpdateExternalCardAssignmentInput): Promise<{
+        agentCard: AgentExternalCard;
+        enforcement: AdminExternalCardOverlayEnforcement;
+    }>;
+    /** Pause an assignment and cancel its unused approvals. */
+    pauseForAgent(agentId: string, cardId: string): Promise<PauseExternalCardAssignmentResult>;
+    /** Resume a paused assignment when its alias and date range permit it. */
+    resumeForAgent(agentId: string, cardId: string): Promise<{
+        agentCard: AgentExternalCard;
+        enforcement: AdminExternalCardOverlayEnforcement;
+    }>;
+    /**
+     * Revoke an agent's overlay assignment. Unused grants are cancelled; claimed
+     * executions remain visible for reconciliation.
+     */
+    revokeFromAgent(agentId: string, cardId: string): Promise<RevokeExternalCardAssignmentResult>;
+    /** List overlay requests, including executions that need receipt reconciliation. */
+    listRequests(input?: ListExternalCardRequestsInput): Promise<ListExternalCardRequestsResponse>;
+    /**
+     * Resolve a claimed execution after checking the customer's processor or
+     * receipt. Resolving NOT_EXECUTED releases the reserved policy amount.
+     */
+    resolveRequest(requestId: string, input: ResolveExternalCardRequestInput): Promise<ResolveExternalCardRequestResult>;
+    /** Pause the Conto-controlled path and revoke live overlay grants. */
+    pause(cardId: string): Promise<{
+        card: Pick<ExternalCard, 'id' | 'name' | 'last4' | 'brand' | 'fundingType' | 'status' | 'isActive' | 'updatedAt'>;
+        revokedApprovals: number;
+        enforcement: AdminExternalCardOverlayEnforcement;
+    }>;
+    /** Resume the Conto-controlled path. This does not activate a card at its issuer. */
+    resume(cardId: string): Promise<{
+        card: Pick<ExternalCard, 'id' | 'name' | 'last4' | 'brand' | 'fundingType' | 'status' | 'isActive' | 'updatedAt'>;
+        revokedApprovals: number;
+        enforcement: AdminExternalCardOverlayEnforcement;
+    }>;
+    private setState;
+}
 declare class AgentsClient {
     private client;
     constructor(client: ContoAdmin);
@@ -366,9 +658,13 @@ declare class AgentsClient {
         message: string;
     }>;
     /** Freeze an agent, blocking all transactions */
-    freeze(agentId: string, input: FreezeAgentInput): Promise<Record<string, unknown>>;
+    freeze(agentId: string, input: FreezeAgentInput): Promise<{
+        frozen: boolean;
+    }>;
     /** Unfreeze an agent, restoring transaction ability */
-    unfreeze(agentId: string, input: UnfreezeAgentInput): Promise<Record<string, unknown>>;
+    unfreeze(agentId: string, input: UnfreezeAgentInput): Promise<{
+        frozen: boolean;
+    }>;
     /** List wallets linked to an agent */
     listWallets(agentId: string): Promise<{
         wallets: AgentWalletLink[];
@@ -381,10 +677,10 @@ declare class AgentsClient {
     }>;
     /** List policies assigned to an agent */
     listPolicies(agentId: string): Promise<{
-        policies: Array<Record<string, unknown>>;
+        policies: AssignedPolicy[];
     }>;
     /** Assign a policy to an agent */
-    assignPolicy(agentId: string, policyId: string, overrides?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    assignPolicy(agentId: string, policyId: string): Promise<AssignedPolicy>;
     /** Unassign a policy from an agent */
     unassignPolicy(agentId: string, policyId: string): Promise<{
         success: boolean;
@@ -403,7 +699,7 @@ declare class WalletsClient {
     constructor(client: ContoAdmin);
     /** List wallets in the organization */
     list(params?: ListWalletsParams): Promise<ListWalletsResponse>;
-    /** Create a new wallet or attach an existing provider/self-custodied wallet */
+    /** Create a managed wallet or register an external address. */
     create(input: CreateWalletInput): Promise<Wallet>;
     /** Get a single wallet by ID */
     get(walletId: string): Promise<Wallet>;
@@ -462,7 +758,6 @@ declare class TeamClient {
     constructor(client: ContoAdmin);
     /** List organization memberships for the authenticated organization */
     listMembers(): Promise<{
-        organizationId: string;
         members: OrganizationMember[];
     }>;
 }
@@ -491,10 +786,11 @@ declare class TeamClient {
  * // Execute if approved
  * if (request.status === 'APPROVED') {
  *   const result = await conto.payments.execute(request.requestId);
- *   console.log(`Payment sent: ${result.txHash}`);
+ *   console.log(result.receipt?.txHash ? `Payment sent: ${result.receipt.txHash}` : `Payment ${result.status}`);
  * }
  * ```
  */
+
 interface ContoConfig {
     /** Your agent's SDK API key (conto_agent_xxx...) */
     apiKey: string;
@@ -514,8 +810,20 @@ interface PaymentRequestInput {
     purpose?: string;
     /** Spend category for analytics */
     category?: string;
-    /** Additional context (will be stored) */
-    context?: Record<string, unknown>;
+    /** Typed invoice context associated with the payment */
+    context?: {
+        invoice?: {
+            vendorId?: string;
+            vendorAddress?: string;
+            id?: string;
+            hash?: string;
+            sourceUrl?: string;
+            payload?: unknown;
+            expectedAmount?: number | string;
+            currency?: string;
+            dueDate?: string;
+        };
+    };
     /** Specific wallet ID to use (optional) */
     walletId?: string;
     /** Payment urgency */
@@ -533,132 +841,454 @@ interface PaymentRequestResult {
     /** Unique request ID - use this to execute or check status */
     requestId: string;
     /** Current status */
-    status: 'APPROVED' | 'DENIED' | 'REQUIRES_APPROVAL' | 'EXECUTED';
-    /** True when the server returned a previously-created request for the same idempotency key */
-    idempotent?: boolean;
-    /** Wallet that will be used for payment (if approved) */
-    wallet?: {
-        id: string;
-        address: string;
-        chainId: string;
-        custodyType: string;
-        availableBalance: number;
-    };
+    status: 'APPROVED' | 'DENIED' | 'REQUIRES_APPROVAL' | 'ACTION_REQUIRED' | 'PROCESSING';
+    /** Requested amount */
+    amount: number;
+    /** Currency selected for the payment */
+    currency: string;
+    /** Recipient wallet address */
+    recipient: string;
+    /** Customer-facing custody model for the selected payment wallet */
+    custodyMode?: CustomerCustodyMode;
     /** When the approval expires (ISO timestamp) */
     expiresAt?: string;
-    /** Explanation of the decision */
+    /** Customer-facing explanation when action is required or the payment is denied */
     reasons: string[];
-    /** Policy violations (if denied) */
-    violations?: PolicyViolation[];
-    /** Currency used for the payment (e.g., 'USDC', 'USDC.e', 'pathUSD') */
-    currency?: string;
-    /** Chain information for the selected wallet */
-    chain?: {
-        chainId: string;
-        chainName: string;
-        chainType: string;
-        explorerUrl: string;
-    };
-    /** URL to execute this payment (convenience) */
-    executeUrl?: string;
-    /** Session ID for tracking (used in x402/MPP flows) */
-    sessionId?: string | null;
-    /** Explanation of why this wallet was selected */
-    walletSelectionReason?: string;
-    /** If autoExecute was true and approved, contains the execution result */
-    execution?: {
+    /** Approval workflow reference when a team decision is required */
+    approvalRequestId?: string;
+    /** Stable URL for polling and reconciliation */
+    statusUrl: string;
+    /** Next URL to follow for the returned status */
+    actionUrl?: string;
+    /** Public receipt data when execution has started */
+    receipt?: {
+        /** Stable Conto transaction ID for status checks and reconciliation */
         transactionId: string;
         txHash: string;
-        explorerUrl: string;
-        status: string;
-    };
-    /** If autoExecute failed, the payment is still approved and can be executed manually */
-    autoExecuteError?: {
-        error: string;
-        code?: string;
-    };
-    /** Human-readable recovery hint for denied requests */
-    hint?: string;
-    /** Additional structured context for recovery or debugging */
-    context?: {
-        wallets?: Array<{
-            id: string;
-            address: string;
-            chainId?: string | null;
-            custodyType?: string | null;
-            balance: number;
-        }>;
-        nextSteps?: string[];
+        /** Whether this receipt represents live settlement or a test-mode payment */
+        settlementMode: 'live' | 'test';
+        explorerUrl?: string;
     };
 }
-interface PolicyViolation {
-    type: string;
-    limit: number;
-    current: number;
-    message: string;
-}
 interface PaymentExecuteResult {
-    /** Internal transaction ID */
-    transactionId: string;
-    /** Onchain transaction hash */
-    txHash: string;
-    /** Transaction status */
-    status: 'CONFIRMING' | 'CONFIRMED' | 'FAILED';
+    /** Payment request ID */
+    requestId: string;
+    /** Customer-facing execution state */
+    status: 'processing' | 'completed';
     /** Amount sent */
     amount: number;
     /** Currency (USDC) */
     currency: string;
     /** Recipient address */
     recipient: string;
-    /** Recipient name if provided */
-    recipientName?: string;
-    /** Wallet used */
-    wallet: {
-        address: string;
+    /** Public transaction receipt */
+    receipt: {
+        /** Stable Conto transaction ID for status checks and reconciliation */
+        transactionId: string;
+        txHash: string;
+        /** Whether this receipt represents live settlement or a test-mode payment */
+        settlementMode: 'live' | 'test';
+        explorerUrl?: string;
     };
-    /** Block explorer URL */
-    explorerUrl: string;
 }
 interface PaymentStatusResult {
     requestId: string;
-    status: string;
-    policyResult: string;
+    status: 'approved' | 'declined' | 'review_required' | 'action_required' | 'reconciliation_required' | 'processing' | 'completed' | 'failed' | 'expired';
     amount: number;
     currency: string;
     recipient: string;
-    recipientName?: string;
+    recipientName: string | null;
+    purpose: string | null;
+    category: string | null;
+    expiresAt: string | null;
+    createdAt: string;
+    action: {
+        type: 'complete_verification';
+        url: string;
+    } | null;
+    transaction: {
+        /** Stable Conto transaction ID */
+        id: string;
+        txHash: string | null;
+        status: 'processing' | 'completed' | 'failed';
+        confirmedAt: string | null;
+        blockNumber: number | null;
+        chain: {
+            type: 'evm' | 'solana';
+            id: string;
+        };
+        explorerUrl: string | null;
+        detailsUrl: string;
+    } | null;
+}
+interface ExternalCardOverlayEnforcement {
+    enforcementMode: 'POLICY_OVERLAY';
+    integrationMode: 'SDK_REQUIRED';
+    canBypass: true;
+    credentialStored: false;
+    credentialReleased: false;
+    executionResponsibility: 'CUSTOMER';
+    transactionVerification: 'SELF_REPORTED';
+}
+interface ExternalCardApprovalInput {
+    /** Stable caller-generated identifier, reused for every retry of this purchase intent. */
+    idempotencyKey: string;
+    cardId: string;
+    amount: number;
+    currency?: 'USD';
+    merchantName: string;
+    merchantId?: string;
+    merchantCategory?: string;
+    merchantAddress?: string;
+    merchantCountry?: string;
     purpose?: string;
-    category?: string;
-    wallet?: {
-        address: string;
+    context?: Record<string, unknown>;
+}
+interface ExternalCardApprovalResult {
+    approved: boolean;
+    decision: 'APPROVED' | 'DENIED' | 'REQUIRES_APPROVAL' | 'EXECUTING' | 'CONFIRMING' | 'COMPLETED' | 'EXPIRED' | 'CANCELLED';
+    requestId: string;
+    approvalToken?: string;
+    expiresAt?: string;
+    reasons: string[];
+    replayed: boolean;
+    transactionId?: string | null;
+    card: {
+        last4: string;
+        brand: string | null;
+        cardholderName: string | null;
     };
+    limits?: {
+        remainingDaily: number;
+        remainingPerTransaction: number;
+    };
+    enforcement: ExternalCardOverlayEnforcement;
+}
+interface ExternalCardExecutionClaimResult {
+    requestId: string;
+    claimed: boolean;
+    replayed: boolean;
+    state: string;
+    reconciliationRequired: boolean;
+    claimedAt?: string;
+    enforcement: ExternalCardOverlayEnforcement;
+}
+interface ExternalCardRequestStatusResult {
+    requestId: string;
+    status: string;
+    decision: string;
+    amount: number;
+    currency: string;
+    merchantName: string | null;
+    merchantId: string | null;
+    merchantCategory: string | null;
+    purpose: string | null;
+    reasons: string[];
     requiresApproval: boolean;
-    approvedAt?: string;
-    deniedAt?: string;
-    denialReason?: string;
-    expiresAt?: string;
-    createdAt: string;
-    transaction?: {
+    reviewed: boolean;
+    expiresAt: string | null;
+    executionClaimedAt: string | null;
+    reconciliationRequired: boolean;
+    nextAction: 'WAIT_FOR_APPROVAL' | 'BEGIN_EXECUTION' | 'CONFIRM_OR_RECONCILE' | 'POLL' | 'NONE';
+    transactionId: string | null;
+    transaction: {
         id: string;
-        txHash: string;
         status: string;
-        confirmedAt?: string;
-        blockNumber?: number;
+        amount: number;
+        currency: string;
+        externalTxId: string | null;
+        authorizedAt: string | null;
+    } | null;
+    enforcement: ExternalCardOverlayEnforcement;
+}
+interface ExternalCardConfirmationInput {
+    approvalToken: string;
+    /** Customer receipt, processor, or authorization reference. Never send PAN or CVC. */
+    externalTxId: string;
+    authorizationCode?: string;
+    actualAmount?: number;
+    /**
+     * Verification/enrichment only. Policy-bearing merchant fields must match
+     * the approval; confirmation cannot substitute the merchant, MCC, or country.
+     */
+    merchantDetails?: {
+        name?: string;
+        id?: string;
+        category?: string;
+        address?: string;
+        city?: string;
+        state?: string;
+        country?: string;
+        postalCode?: string;
     };
 }
-interface ContoError extends Error {
-    code: string;
-    status: number;
+interface ExternalCardConfirmationResult {
+    confirmed: true;
+    replayed: boolean;
+    transactionId: string;
+    status: string;
+    amount: number;
+    currency: string;
+    verificationStatus: 'SELF_REPORTED';
+    enforcement: ExternalCardOverlayEnforcement;
+}
+/**
+ * Input delivered to the customer's credential-using executor. The callback is
+ * invoked only after Conto approves the purchase. It deliberately excludes the
+ * Conto approval token and all card credential fields.
+ */
+interface ApprovedExternalCardExecution {
+    requestId: string;
+    cardId: string;
+    amount: number;
+    currency: 'USD';
+    merchantName: string;
+    merchantId?: string;
+    merchantCategory?: string;
+    merchantAddress?: string;
+    merchantCountry?: string;
+    purpose?: string;
+    context?: Record<string, unknown>;
+}
+interface ExternalCardExecutionResult<TReceipt = unknown> {
+    externalTxId: string;
+    authorizationCode?: string;
+    actualAmount?: number;
+    merchantDetails?: ExternalCardConfirmationInput['merchantDetails'];
+    receipt: TReceipt;
+}
+type ExternalCardExecutor<TReceipt = unknown> = (approvedPurchase: ApprovedExternalCardExecution) => Promise<ExternalCardExecutionResult<TReceipt>>;
+interface ControlledExternalCardPaymentResult<TReceipt = unknown> {
+    approval: ExternalCardApprovalResult;
+    confirmation: ExternalCardConfirmationResult;
+    receipt: TReceipt;
+}
+interface ProtocolPreAuthorizeResult {
+    authorized: boolean;
+    decision: 'approved' | 'declined' | 'review_required';
+    message: string;
+}
+interface X402PreAuthorizeInput {
+    amount: number;
+    recipientAddress: string;
+    resourceUrl: string;
+    context?: {
+        department?: string;
+        project?: string;
+    };
+    /** Customer-supplied ID used to group authorization, recording, and spend reporting. */
+    sessionId?: string;
+}
+interface X402PreAuthorizeResult extends ProtocolPreAuthorizeResult {
+    x402: {
+        serviceDomain?: string;
+        amount: number;
+        sessionId?: string;
+    };
+}
+interface X402RecordInput {
+    amount: number;
+    currency?: string;
+    recipientAddress: string;
+    txHash: string;
+    resourceUrl: string;
+    /** Stable x402 payment identifier. Reuse this value to reconcile an ambiguous failure. */
+    paymentId: string;
+    /** Customer-supplied ID used to group related x402 payments. */
+    sessionId?: string;
+    context?: {
+        department?: string;
+        project?: string;
+    };
+    batchItems?: Array<{
+        amount: number;
+        resourceUrl: string;
+        paymentId: string;
+    }>;
+}
+interface X402RecordResult {
+    recorded: true;
+    confirmed: true;
+    txHash: string;
+    explorerUrl: string;
+    sessionId?: string;
+}
+interface MppPreAuthorizeInput {
+    amount: number;
+    recipientAddress: string;
+    resourceUrl: string;
+    context?: {
+        department?: string;
+        project?: string;
+    };
+    intent?: 'charge' | 'session';
+    depositAmount?: number;
+    /** Customer-supplied ID used to group authorization, recording, and spend reporting. */
+    sessionId?: string;
+}
+interface MppPreAuthorizeResult extends ProtocolPreAuthorizeResult {
+    mpp: {
+        serviceDomain?: string;
+        amount: number;
+        sessionId?: string;
+    };
+}
+interface MppRecordInput {
+    amount: number;
+    currency?: string;
+    recipientAddress: string;
+    txHash?: string;
+    resourceUrl: string;
+    /** Stable MPP credential identifier. Reuse this value to reconcile an ambiguous failure. */
+    credentialId: string;
+    /** Customer-supplied ID used to group related MPP payments. */
+    sessionId?: string;
+    context?: {
+        department?: string;
+        project?: string;
+    };
+    paymentReceipt?: string;
+    intent?: 'charge' | 'session';
+    batchItems?: Array<{
+        amount: number;
+        resourceUrl: string;
+        credentialId: string;
+    }>;
+}
+interface MppRecordResult {
+    recorded: true;
+    txHash?: string;
+    explorerUrl?: string;
+    sessionId?: string;
+}
+interface ProtocolBudgetResult {
+    spend: {
+        daily: {
+            calls: number;
+            amount: number;
+        };
+        weekly: {
+            calls: number;
+            amount: number;
+        };
+        monthly: {
+            calls: number;
+            amount: number;
+        };
+        session: {
+            sessionId: string;
+            calls: number;
+            amount: number;
+        } | null;
+    };
+    limits: {
+        daily: number | null;
+        weekly: number | null;
+        monthly: number | null;
+        perPayment: number | null;
+    };
+    trend: {
+        spendPerHour: number;
+        callsPerHour: number;
+        averageCost: number;
+        estimatedHoursRemaining: number | null;
+    };
+}
+type X402BudgetResult = ProtocolBudgetResult;
+type MppBudgetResult = ProtocolBudgetResult;
+interface ProtocolServiceSummary {
+    domain: string;
+    name: string | null;
+    totalCalls: number;
+    totalSpend: number;
+    averageCost: number;
+    lastUsedAt: string | null;
+    recent: {
+        calls: number;
+        spend: number;
+        averageCost: number;
+    };
+}
+interface ProtocolServicesResult {
+    services: ProtocolServiceSummary[];
+    summary: {
+        serviceCount: number;
+        totalCalls: number;
+        totalSpend: number;
+        averageCost: number;
+    };
+    period: '24h' | '7d' | '30d' | '90d';
+}
+declare class ContoError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly requestId?: string;
+    readonly retryAfter?: number;
+    readonly retryGuidance?: string;
+    readonly actionUrl?: string;
+    constructor(message: string, metadata: ApiErrorMetadata);
+}
+/**
+ * The customer executor returned a receipt, but Conto did not acknowledge the
+ * confirmation. Persist confirmationInput and retry cards.confirm(); never run
+ * the customer executor again for this request.
+ */
+declare class ExternalCardConfirmationPendingError<TReceipt = unknown> extends ContoError {
+    readonly confirmationInput: ExternalCardConfirmationInput;
+    readonly receipt: TReceipt;
+    constructor(requestId: string, confirmationInput: ExternalCardConfirmationInput, receipt: TReceipt);
+}
+interface ContoRequestOptions {
+    /** Set only when repeating this request cannot create an additional side effect. */
+    idempotent?: boolean;
+    /** Number of retries after the initial attempt. Defaults to 3. */
+    maxRetries?: number;
 }
 declare class Conto {
     private apiKey;
     private baseUrl;
     private timeout;
     payments: PaymentsClient;
+    cards: CardsClient;
+    x402: X402Client;
+    mpp: MppClient;
     constructor(config: ContoConfig);
-    private fetchWithRetry;
     /** Make an authenticated request to the Giro API */
-    request<T>(method: string, path: string, body?: Record<string, unknown>): Promise<T>;
+    request<T>(method: string, path: string, body?: Record<string, unknown>, options?: ContoRequestOptions): Promise<T>;
+}
+/** Agent client for the cooperative external-card policy overlay. */
+declare class CardsClient {
+    private client;
+    constructor(client: Conto);
+    approve(input: ExternalCardApprovalInput): Promise<ExternalCardApprovalResult>;
+    confirm(requestId: string, input: ExternalCardConfirmationInput): Promise<ExternalCardConfirmationResult>;
+    /**
+     * Atomically claim the approved intent before customer code accesses or uses
+     * the card credential. A request can be claimed only once.
+     */
+    begin(requestId: string, input: {
+        approvalToken: string;
+    }): Promise<ExternalCardExecutionClaimResult>;
+    /** Read execution and reconciliation state without exposing card credentials. */
+    status(requestId: string): Promise<ExternalCardRequestStatusResult>;
+    /**
+     * Create a reference payment tool whose executor callback is unreachable
+     * until Conto has returned a live approval grant.
+     *
+     * @deprecated Use the separate `@conto_finance/card-access` product package for
+     * customer-hosted card enforcement. This helper remains for compatibility.
+     */
+    controlled<TReceipt>(executor: ExternalCardExecutor<TReceipt>): ControlledExternalCardPaymentTool<TReceipt>;
+}
+/**
+ * Cooperative control for an existing customer credential store. The executor is
+ * customer-owned and remains bypassable if another code path can call it.
+ */
+declare class ControlledExternalCardPaymentTool<TReceipt = unknown> {
+    private cardsClient;
+    private executor;
+    constructor(cardsClient: CardsClient, executor: ExternalCardExecutor<TReceipt>);
+    pay(input: ExternalCardApprovalInput): Promise<ControlledExternalCardPaymentResult<TReceipt>>;
 }
 /** Client for payment operations */
 declare class PaymentsClient {
@@ -704,8 +1334,11 @@ declare class PaymentsClient {
      * @example
      * ```typescript
      * const result = await conto.payments.execute(request.requestId);
-     * console.log(`Transaction: ${result.txHash}`);
-     * console.log(`Explorer: ${result.explorerUrl}`);
+     * console.log(`Status: ${result.status}`);
+     * console.log(`Conto transaction: ${result.receipt.transactionId}`);
+     * console.log(`Settlement mode: ${result.receipt.settlementMode}`);
+     * console.log(`Transaction: ${result.receipt.txHash}`);
+     * if (result.receipt.explorerUrl) console.log(`Explorer: ${result.receipt.explorerUrl}`);
      * ```
      */
     execute(requestId: string): Promise<PaymentExecuteResult>;
@@ -717,8 +1350,8 @@ declare class PaymentsClient {
      * @example
      * ```typescript
      * const status = await conto.payments.status(requestId);
-     * if (status.transaction?.status === 'CONFIRMED') {
-     *   console.log('Payment confirmed at block', status.transaction.blockNumber);
+     * if (status.transaction?.status === 'completed') {
+     *   console.log('Payment confirmed', status.transaction.txHash);
      * }
      * ```
      */
@@ -737,7 +1370,9 @@ declare class PaymentsClient {
      *     recipientAddress: '0x...',
      *     purpose: 'Service fee'
      *   });
-     *   console.log(`Paid! TX: ${result.txHash}`);
+     *   console.log(`Payment status: ${result.status}`);
+     *   console.log(`Conto transaction: ${result.receipt.transactionId}`);
+     *   console.log(`Transaction: ${result.receipt.txHash}`);
      * } catch (error) {
      *   if (error.code === 'REQUIRES_APPROVAL') {
      *     console.log('Payment needs human approval');
@@ -749,5 +1384,31 @@ declare class PaymentsClient {
      */
     pay(input: PaymentRequestInput): Promise<PaymentExecuteResult>;
 }
+declare class X402Client {
+    private client;
+    constructor(client: Conto);
+    preAuthorize(input: X402PreAuthorizeInput): Promise<X402PreAuthorizeResult>;
+    record(input: X402RecordInput): Promise<X402RecordResult>;
+    budget(options?: {
+        sessionId?: string;
+    }): Promise<X402BudgetResult>;
+    services(options?: {
+        period?: '24h' | '7d' | '30d' | '90d';
+        limit?: number;
+    }): Promise<ProtocolServicesResult>;
+}
+declare class MppClient {
+    private client;
+    constructor(client: Conto);
+    preAuthorize(input: MppPreAuthorizeInput): Promise<MppPreAuthorizeResult>;
+    record(input: MppRecordInput): Promise<MppRecordResult>;
+    budget(options?: {
+        sessionId?: string;
+    }): Promise<MppBudgetResult>;
+    services(options?: {
+        period?: '24h' | '7d' | '30d' | '90d';
+        limit?: number;
+    }): Promise<ProtocolServicesResult>;
+}
 
-export { type Agent, type AgentStatus, type AgentType, type AgentWalletLink, type ChainType, Conto, ContoAdmin, type ContoAdminConfig, type ContoAdminError, type ContoConfig, type ContoError, type CreateAgentInput, type CreatePolicyInput, type CreatePolicyRuleInput, type CreateSdkKeyInput, type CreateSdkKeyResult, type CreateWalletInput, type CustodyType, type DelegationType, type FreezeAgentInput, Conto as Giro, type ContoConfig as GiroConfig, type ContoError as GiroError, type LinkWalletInput, type ListAgentsParams, type ListAgentsResponse, type ListPoliciesParams, type ListPoliciesResponse, type ListWalletsParams, type ListWalletsResponse, type PaginatedResponse, type PaginationParams, type PaymentExecuteResult, type PaymentRequestInput, type PaymentRequestResult, type PaymentStatusResult, type Policy, type PolicyRule, type PolicyType, type PolicyViolation, type ProvisionWalletResult, type RefreshBalanceResult, type RuleAction, type RuleOperator, type RuleType, type SdkKey, type SdkKeyType, type UnfreezeAgentInput, type UpdateAgentInput, type UpdatePolicyInput, type UpdatePolicyRuleInput, type UpdateWalletInput, type Wallet, type WalletChainBalanceSnapshot, type WalletStatus, type WalletType, Conto as default };
+export { type AdminExternalCardOverlayEnforcement, type Agent, type AgentExternalCard, type AgentStatus, type AgentType, type AgentWalletLink, type ApprovedExternalCardExecution, type AssignExternalCardInput, type AssignedPolicy, CardsClient, type ChainType, 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 DelegationType, type ExternalCard, type ExternalCardApprovalInput, type ExternalCardApprovalResult, type ExternalCardConfirmationInput, ExternalCardConfirmationPendingError, type ExternalCardConfirmationResult, type ExternalCardExecutionClaimResult, type ExternalCardExecutionResult, type ExternalCardExecutor, type ExternalCardOverlayEnforcement, type ExternalCardRequestStatusResult, type FreezeAgentInput, Conto as Giro, type ContoConfig as GiroConfig, ContoError as GiroError, type LinkWalletInput, type ListAgentsParams, type ListAgentsResponse, type ListPoliciesParams, type ListPoliciesResponse, type ListWalletsParams, type ListWalletsResponse, type MppBudgetResult, type MppPreAuthorizeInput, type MppPreAuthorizeResult, type MppRecordInput, type MppRecordResult, type OrganizationMember, type PaginatedResponse, type PaginationParams, type PauseExternalCardAssignmentResult, type PaymentExecuteResult, type PaymentRequestInput, type PaymentRequestResult, type PaymentStatusResult, type Policy, type PolicyRule, type PolicyType, type ProtocolBudgetResult, type ProtocolPreAuthorizeResult, type ProtocolServiceSummary, type ProtocolServicesResult, type ProvisionWalletResult, type RefreshBalanceResult, type RegisterExternalCardInput, type RuleAction, type RuleOperator, type RuleType, type SdkKey, type SdkKeyType, type UnfreezeAgentInput, type UpdateAgentInput, type UpdateExternalCardAssignmentInput, type UpdatePolicyInput, type UpdatePolicyRuleInput, type UpdateWalletInput, type Wallet, type WalletChainBalanceSnapshot, type WalletStatus, type WalletType, type X402BudgetResult, type X402PreAuthorizeInput, type X402PreAuthorizeResult, type X402RecordInput, type X402RecordResult, Conto as default };