agentwallet-sdk 5.0.5 → 5.1.0

package/README.md

@@ -1,8 +1,5 @@
 # AgentWallet SDK
 
-> **📦 CANONICAL PACKAGE:** This is the actively maintained source for the `agentwallet-sdk` npm package (v5+). The old `agentwallet-sdk` GitHub repo is deprecated — use this repo.
-
-
 Non-custodial AI agent wallet with ERC-8004 on-chain identity, ERC-6551 token-bound accounts, x402 payments, mutual stake escrow, and programmable spending guardrails.
 
 Agent Wallet gives AI agents autonomous spending power with hard on-chain limits. No more choosing between "agent can drain everything" and "every transaction needs manual approval."
@@ -207,24 +204,45 @@ await escrow.verify(escrowId);
 
 Premium access: [github.com/up2itnow/AgentNexus2](https://github.com/up2itnow/AgentNexus2)
 
-## Atomic Settlement — Verified On-Chain
+## x402 Protocol: Supported Chains and Payment Rails
 
-Live x402 settlement endpoint on Base Sepolia with on-chain attestation verification:
+x402 (HTTP 402 Payment Required) is the native payment protocol for agent-to-service transactions. The agent encounters a 402 response, signs a payment proof, and re-sends the request. One round trip. No accounts, no API keys, no invoices.
 
-```
-https://dexter-settlement-test-production.up.railway.app
-```
+As of March 2026, x402 is live on 3 chains/rails:
 
-| Proof | Transaction |
-|---|---|
-| USDC Payment | [`0xbba6c34a...`](https://sepolia.basescan.org/tx/0xbba6c34ad6b11cc4e511317ca38553df903dcbe989ee47e45b5c48f3af7e4334) |
-| Fee Routing (0.77%) | [`0x9a5e450c...`](https://sepolia.basescan.org/tx/0x9a5e450c1080a2478ea22792b6ab034974d8f99072808f83354c98451441733a) |
+| Chain / Rail | Status | Settlement Token | Gas Cost | Notes |
+|---|---|---|---|---|
+| **Base** (Coinbase L2) | Live | USDC | Sub-cent | Primary x402 chain. 15M+ transactions in Jan 2026. |
+| **Etherlink** (Tezos L2) | Live (Mar 2026) | USDC | Sub-cent | EVM-compatible. Same x402 integration, different RPC + chain ID. |
+| **Stripe** (Fiat offramp) | Live (Feb 2026) | USDC -> USD | N/A | Vendors receive USD in Stripe dashboard. Agents pay USDC. |
 
-See [`examples/settlement-test/`](examples/settlement-test/) for the full settlement server, self-test script, and integration guide.
+### x402 + Etherlink Quick Start
+
+```typescript
+import { createWallet, agentExecute } from 'agentwallet-sdk';
+
+const wallet = createWallet({
+  accountAddress: '0xYourAgent',
+  chain: 'etherlink',  // new: Tezos L2 support
+  walletClient,
+});
+
+// x402 payment flow is identical across chains
+const response = await fetch('https://api.vendor.com/data');
+if (response.status === 402) {
+  const details = await response.json();
+  const proof = await wallet.createX402Proof(details);
+  const paid = await fetch('https://api.vendor.com/data', {
+    headers: { 'X-Payment': proof }
+  });
+}
+```
+
+The SDK handles chain-specific RPC endpoints, gas estimation, and USDC contract addresses automatically. Swap `chain: 'base'` to `chain: 'etherlink'` and the x402 flow works identically.
 
 ## Supported Chains
 
-Mainnet: Ethereum, Base, Arbitrum, Polygon, Optimism, Avalanche, BSC, Celo, Gnosis, Linea, Mantle, Scroll, and more.
+Mainnet: Ethereum, Base, Arbitrum, Polygon, Optimism, Avalanche, BSC, Celo, Gnosis, Linea, Mantle, Scroll, Etherlink, and more.
 
 Testnet: Base Sepolia, Arbitrum Sepolia, and corresponding testnets.
 
@@ -234,22 +252,6 @@ Testnet: Base Sepolia, Arbitrum Sepolia, and corresponding testnets.
 - [GitHub](https://github.com/agentnexus/agent-wallet-sdk)
 - [npm](https://www.npmjs.com/package/agentwallet-sdk)
 
-
-## Why agent-wallet-sdk vs. Polygon Agent CLI
-
-| Feature | agent-wallet-sdk | Polygon Agent CLI |
-|---|---|---|
-| Wallet model | Non-custodial, agent holds keys | CLI-based, operator-managed |
-| x402 support | Native, automatic negotiation | Not supported |
-| Spend limits | Programmable (daily, per-tx, per-agent) | Manual configuration |
-| Multi-chain | Ethereum, Base, Etherlink, Polygon, 10+ chains | Polygon-only |
-| Integration | npm package, works in any JS/TS runtime | CLI tool, requires shell access |
-| Agent frameworks | Any (LangChain, CrewAI, Cursor, NemoClaw) | Polygon ecosystem only |
-| Audit trail | Built-in transaction logging | External tooling required |
-| Use case | Autonomous agent payments at scale | Polygon-specific agent ops |
-
-agent-wallet-sdk is chain-agnostic, framework-agnostic, and built for autonomous agents that need to pay for things without human approval. Polygon Agent CLI is a solid tool if you are all-in on Polygon infrastructure - but if your agents need to operate across chains or use x402 payment headers, agent-wallet-sdk is the better fit.
-
 ## License
 
 MIT

package/dist/ap2/index.d.ts

@@ -0,0 +1,185 @@
+/**
+ * AP2Client — ISO 20022 / AP2 European Payment Module for agentwallet-sdk
+ *
+ * Non-custodial AI agent bridge for AP2 payments:
+ *   - Parse ISO 20022 pacs.008 XML → bridge quote
+ *   - Sign x402 payment header locally (private key never leaves agent)
+ *   - Execute USDC → EUR settlement via CCTP V2 (Base → EUR off-ramp)
+ *
+ * AP2 context:
+ *   Nexi + Google Cloud MoU (2026): AP2 processes ~2.9T EUR/year across Europe.
+ *   ISO 20022 is the wire standard. This module makes AI agents first-class
+ *   European payment participants — non-custodially.
+ *
+ * @module ap2
+ */
+/** Parameters for building a pacs.008 XML message from simple inputs. */
+export interface AP2PaymentParams {
+    /** Unique message ID (e.g. "MSG-2026-0001") */
+    messageId: string;
+    /** ISO 8601 creation datetime (defaults to now) */
+    creationDateTime?: string;
+    /** Payment amount in EUR (or specified currency) */
+    amount: number;
+    /** Currency code (default: "EUR") */
+    currency?: string;
+    /** Debtor full name */
+    debtorName: string;
+    /** Debtor IBAN */
+    debtorIban: string;
+    /** Debtor BIC */
+    debtorBic: string;
+    /** Creditor full name */
+    creditorName: string;
+    /** Creditor IBAN */
+    creditorIban: string;
+    /** Creditor BIC */
+    creditorBic: string;
+    /** Optional end-to-end reference */
+    endToEndId?: string;
+    /** Optional purpose code (e.g. "SUPP") */
+    purposeCode?: string;
+    /** Optional unstructured remittance info */
+    remittanceInfo?: string;
+}
+/** Bridge quote returned by the AP2 facilitator. */
+export interface AP2Quote {
+    /** ISO 20022 message ID */
+    messageId: string;
+    /** Creditor IBAN for SEPA settlement */
+    creditorIban: string;
+    /** EUR payment amount */
+    amountEur: number;
+    /** USDC required (6 decimal precision, as bigint μUSDC) */
+    usdcRequired: bigint;
+    /** Bridge fee in USDC (μUSDC) */
+    bridgeFeeUsdc: bigint;
+    /** Estimated settlement time in seconds */
+    estimatedSettlementSeconds: number;
+    /** x402 payment header string */
+    x402PaymentHeader: string;
+    /** Raw calldata for agentwallet-sdk */
+    agentWalletCalldata: Record<string, unknown>;
+    /** Quote expiry ISO timestamp */
+    expiresAt: string;
+}
+/** Execution receipt after AP2 payment is submitted. */
+export interface AP2Receipt {
+    /** ISO 20022 message ID */
+    messageId: string;
+    /** On-chain transaction hash */
+    txHash: string;
+    /** USDC bridged (μUSDC as bigint) */
+    usdcBridged: bigint;
+    /** SEPA creditor reference */
+    sepaReference: string;
+    /** Payment status */
+    status: 'pending' | 'confirmed' | 'failed' | 'dry_run';
+    /** True if this was a dry run simulation */
+    dryRun: boolean;
+    /** x402 payment header signature */
+    x402Signature: string;
+    /** Agent Ethereum address */
+    agentAddress: string;
+    /** CCTP bridge nonce */
+    nonce: number;
+    /** ISO timestamp of execution */
+    executedAt: string;
+    /** Creditor IBAN */
+    creditorIban: string;
+    /** Bridge fee in USDC (μUSDC) */
+    bridgeFeeUsdc: bigint;
+}
+/** AP2Client configuration */
+export interface AP2ClientConfig {
+    /**
+     * URL of the AP2 facilitator (FastAPI handler).
+     * Defaults to http://localhost:8420
+     */
+    facilitatorUrl?: string;
+}
+/**
+ * Build a valid ISO 20022 pacs.008 (FIToFICstmrCdtTrf) XML string
+ * from simple agent-friendly parameters.
+ *
+ * @param params - Payment parameters
+ * @returns ISO 20022 pacs.008 XML string
+ */
+declare function buildPacs008(params: AP2PaymentParams): string;
+/**
+ * AP2Client — Non-custodial ISO 20022 / AP2 payment client for AI agents.
+ *
+ * Connects to the AP2 facilitator (ap2_handler.py FastAPI service) to
+ * get bridge quotes and execute payments via CCTP V2 / x402.
+ *
+ * @example
+ * ```typescript
+ * const client = new AP2Client({ facilitatorUrl: 'http://localhost:8420' });
+ *
+ * const xml = AP2Client.buildPacs008({
+ *   messageId: 'MSG-2026-0001',
+ *   amount: 1000,
+ *   debtorName: 'Agent Zero',
+ *   debtorIban: 'DE89370400440532013000',
+ *   debtorBic: 'COBADEFFXXX',
+ *   creditorName: 'Acme GmbH',
+ *   creditorIban: 'FR7630006000011234567890189',
+ *   creditorBic: 'BNPAFRPPXXX',
+ * });
+ *
+ * const quote = await client.quote(xml);
+ * const receipt = await client.pay(xml);
+ * ```
+ */
+export declare class AP2Client {
+    private readonly facilitatorUrl;
+    constructor(config?: AP2ClientConfig);
+    /**
+     * Parse ISO 20022 pacs.008 XML and get a bridge quote from the facilitator.
+     *
+     * @param iso20022Xml - Raw pacs.008 XML string
+     * @returns AP2Quote with USDC amounts and x402 calldata
+     * @throws Error if the facilitator returns an error or the XML is invalid
+     */
+    quote(iso20022Xml: string): Promise<AP2Quote>;
+    /**
+     * Execute the full AP2 payment: sign x402 header + bridge USDC + settle.
+     *
+     * Calls the /ap2/execute endpoint on the facilitator, which:
+     *   1. Parses the XML
+     *   2. Signs x402 header with agent's private key (server-side in this flow)
+     *   3. Submits USDC to CCTP V2 bridge
+     *   4. Returns receipt
+     *
+     * @param iso20022Xml - Raw pacs.008 XML string
+     * @returns AP2Receipt with txHash and SEPA reference
+     * @throws AP2Error on execution failure
+     */
+    pay(iso20022Xml: string): Promise<AP2Receipt>;
+    /**
+     * Generate a valid ISO 20022 pacs.008 XML string from simple parameters.
+     *
+     * Handles XML escaping, IBAN normalization, and timestamp formatting.
+     * Makes AP2 payments agent-friendly — no ISO 20022 expertise required.
+     *
+     * @param params - Simple payment parameters
+     * @returns Valid pacs.008 XML string
+     */
+    static buildPacs008(params: AP2PaymentParams): string;
+    /**
+     * Estimate USDC required for a given EUR amount.
+     *
+     * Uses the default EUR/USDC rate. For accurate quotes, call quote() instead.
+     *
+     * @param amountEur - Amount in EUR
+     * @returns Estimated USDC amount as bigint (μUSDC, 6 decimals)
+     */
+    static estimateUsdc(amountEur: number): bigint;
+}
+/** AP2-specific error with structured context. */
+export declare class AP2Error extends Error {
+    readonly context?: Record<string, unknown> | undefined;
+    constructor(message: string, context?: Record<string, unknown> | undefined);
+}
+export { buildPacs008 };
+//# sourceMappingURL=index.d.ts.map

package/dist/ap2/index.d.ts.map

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

package/dist/ap2/index.js

@@ -0,0 +1,255 @@
+/**
+ * AP2Client — ISO 20022 / AP2 European Payment Module for agentwallet-sdk
+ *
+ * Non-custodial AI agent bridge for AP2 payments:
+ *   - Parse ISO 20022 pacs.008 XML → bridge quote
+ *   - Sign x402 payment header locally (private key never leaves agent)
+ *   - Execute USDC → EUR settlement via CCTP V2 (Base → EUR off-ramp)
+ *
+ * AP2 context:
+ *   Nexi + Google Cloud MoU (2026): AP2 processes ~2.9T EUR/year across Europe.
+ *   ISO 20022 is the wire standard. This module makes AI agents first-class
+ *   European payment participants — non-custodially.
+ *
+ * @module ap2
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** USDC decimals (6) */
+const USDC_DECIMALS = 6n;
+const USDC_MULTIPLIER = 10n ** USDC_DECIMALS;
+/** EUR → USDC rate (fallback; production uses Chainlink oracle) */
+const EUR_TO_USDC_RATE = 1.08;
+/** Default facilitator URL */
+const DEFAULT_FACILITATOR_URL = 'http://localhost:8420';
+/** Estimated CCTP V2 settlement time (~20 min) */
+const ESTIMATED_SETTLEMENT_SECONDS = 1200;
+// ---------------------------------------------------------------------------
+// ISO 20022 pacs.008 XML Builder
+// ---------------------------------------------------------------------------
+/**
+ * Build a valid ISO 20022 pacs.008 (FIToFICstmrCdtTrf) XML string
+ * from simple agent-friendly parameters.
+ *
+ * @param params - Payment parameters
+ * @returns ISO 20022 pacs.008 XML string
+ */
+function buildPacs008(params) {
+    const now = params.creationDateTime ?? new Date().toISOString().replace(/\.\d+Z$/, '+00:00');
+    const currency = params.currency ?? 'EUR';
+    const e2eId = params.endToEndId ?? params.messageId;
+    const amount = params.amount.toFixed(2);
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08">
+  <FIToFICstmrCdtTrf>
+    <GrpHdr>
+      <MsgId>${escapeXml(params.messageId)}</MsgId>
+      <CreDtTm>${escapeXml(now)}</CreDtTm>
+      <NbOfTxs>1</NbOfTxs>
+      <SttlmInf>
+        <SttlmMtd>CLRG</SttlmMtd>
+      </SttlmInf>
+    </GrpHdr>
+    <CdtTrfTxInf>
+      <PmtId>
+        <EndToEndId>${escapeXml(e2eId)}</EndToEndId>
+      </PmtId>
+      <IntrBkSttlmAmt Ccy="${escapeXml(currency)}">${amount}</IntrBkSttlmAmt>
+      <ChrgBr>SHAR</ChrgBr>
+      <Dbtr>
+        <Nm>${escapeXml(params.debtorName)}</Nm>
+      </Dbtr>
+      <DbtrAcct>
+        <Id>
+          <IBAN>${escapeXml(params.debtorIban.replace(/\s/g, '').toUpperCase())}</IBAN>
+        </Id>
+      </DbtrAcct>
+      <DbtrAgt>
+        <FinInstnId>
+          <BICFI>${escapeXml(params.debtorBic.toUpperCase())}</BICFI>
+        </FinInstnId>
+      </DbtrAgt>
+      <Cdtr>
+        <Nm>${escapeXml(params.creditorName)}</Nm>
+      </Cdtr>
+      <CdtrAcct>
+        <Id>
+          <IBAN>${escapeXml(params.creditorIban.replace(/\s/g, '').toUpperCase())}</IBAN>
+        </Id>
+      </CdtrAcct>
+      <CdtrAgt>
+        <FinInstnId>
+          <BICFI>${escapeXml(params.creditorBic.toUpperCase())}</BICFI>
+        </FinInstnId>
+      </CdtrAgt>${params.purposeCode ? `
+      <Purp>
+        <Cd>${escapeXml(params.purposeCode)}</Cd>
+      </Purp>` : ''}${params.remittanceInfo ? `
+      <RmtInf>
+        <Ustrd>${escapeXml(params.remittanceInfo)}</Ustrd>
+      </RmtInf>` : ''}
+    </CdtTrfTxInf>
+  </FIToFICstmrCdtTrf>
+</Document>`;
+}
+/** Escape XML special characters. */
+function escapeXml(str) {
+    return str
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+/** Convert a decimal USDC string to bigint μUSDC. */
+function usdcToBigInt(usdcStr) {
+    const [whole, frac = ''] = usdcStr.split('.');
+    const fracPadded = frac.padEnd(Number(USDC_DECIMALS), '0').slice(0, Number(USDC_DECIMALS));
+    return BigInt(whole) * USDC_MULTIPLIER + BigInt(fracPadded);
+}
+// ---------------------------------------------------------------------------
+// AP2Client
+// ---------------------------------------------------------------------------
+/**
+ * AP2Client — Non-custodial ISO 20022 / AP2 payment client for AI agents.
+ *
+ * Connects to the AP2 facilitator (ap2_handler.py FastAPI service) to
+ * get bridge quotes and execute payments via CCTP V2 / x402.
+ *
+ * @example
+ * ```typescript
+ * const client = new AP2Client({ facilitatorUrl: 'http://localhost:8420' });
+ *
+ * const xml = AP2Client.buildPacs008({
+ *   messageId: 'MSG-2026-0001',
+ *   amount: 1000,
+ *   debtorName: 'Agent Zero',
+ *   debtorIban: 'DE89370400440532013000',
+ *   debtorBic: 'COBADEFFXXX',
+ *   creditorName: 'Acme GmbH',
+ *   creditorIban: 'FR7630006000011234567890189',
+ *   creditorBic: 'BNPAFRPPXXX',
+ * });
+ *
+ * const quote = await client.quote(xml);
+ * const receipt = await client.pay(xml);
+ * ```
+ */
+export class AP2Client {
+    constructor(config = {}) {
+        this.facilitatorUrl = (config.facilitatorUrl ?? DEFAULT_FACILITATOR_URL).replace(/\/$/, '');
+    }
+    /**
+     * Parse ISO 20022 pacs.008 XML and get a bridge quote from the facilitator.
+     *
+     * @param iso20022Xml - Raw pacs.008 XML string
+     * @returns AP2Quote with USDC amounts and x402 calldata
+     * @throws Error if the facilitator returns an error or the XML is invalid
+     */
+    async quote(iso20022Xml) {
+        const response = await fetch(`${this.facilitatorUrl}/ap2/payment`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/xml' },
+            body: iso20022Xml,
+        });
+        if (!response.ok) {
+            const body = await response.text();
+            throw new AP2Error(`Quote failed (${response.status}): ${body}`);
+        }
+        const json = (await response.json());
+        const bq = json.bridge_quote;
+        const payment = json.payment;
+        return {
+            messageId: payment.message_id,
+            creditorIban: payment.creditor.iban,
+            amountEur: parseFloat(payment.amount),
+            usdcRequired: usdcToBigInt(bq.usdc_amount),
+            bridgeFeeUsdc: usdcToBigInt(bq.bridge_fee_usdc),
+            estimatedSettlementSeconds: ESTIMATED_SETTLEMENT_SECONDS,
+            x402PaymentHeader: bq.x402_payment_header,
+            agentWalletCalldata: bq.agent_wallet_calldata,
+            expiresAt: bq.expires_at,
+        };
+    }
+    /**
+     * Execute the full AP2 payment: sign x402 header + bridge USDC + settle.
+     *
+     * Calls the /ap2/execute endpoint on the facilitator, which:
+     *   1. Parses the XML
+     *   2. Signs x402 header with agent's private key (server-side in this flow)
+     *   3. Submits USDC to CCTP V2 bridge
+     *   4. Returns receipt
+     *
+     * @param iso20022Xml - Raw pacs.008 XML string
+     * @returns AP2Receipt with txHash and SEPA reference
+     * @throws AP2Error on execution failure
+     */
+    async pay(iso20022Xml) {
+        const response = await fetch(`${this.facilitatorUrl}/ap2/execute`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/xml' },
+            body: iso20022Xml,
+        });
+        if (!response.ok) {
+            const body = await response.text();
+            throw new AP2Error(`Execution failed (${response.status}): ${body}`);
+        }
+        const json = (await response.json());
+        const r = json.receipt;
+        return {
+            messageId: r.message_id,
+            txHash: r.tx_hash,
+            usdcBridged: usdcToBigInt(r.usdc_bridged),
+            sepaReference: r.sepa_reference,
+            status: r.status,
+            dryRun: r.dry_run,
+            x402Signature: r.x402_signature,
+            agentAddress: r.agent_address,
+            nonce: r.nonce,
+            executedAt: r.executed_at,
+            creditorIban: r.creditor_iban,
+            bridgeFeeUsdc: usdcToBigInt(r.bridge_fee_usdc),
+        };
+    }
+    /**
+     * Generate a valid ISO 20022 pacs.008 XML string from simple parameters.
+     *
+     * Handles XML escaping, IBAN normalization, and timestamp formatting.
+     * Makes AP2 payments agent-friendly — no ISO 20022 expertise required.
+     *
+     * @param params - Simple payment parameters
+     * @returns Valid pacs.008 XML string
+     */
+    static buildPacs008(params) {
+        return buildPacs008(params);
+    }
+    /**
+     * Estimate USDC required for a given EUR amount.
+     *
+     * Uses the default EUR/USDC rate. For accurate quotes, call quote() instead.
+     *
+     * @param amountEur - Amount in EUR
+     * @returns Estimated USDC amount as bigint (μUSDC, 6 decimals)
+     */
+    static estimateUsdc(amountEur) {
+        const usdc = amountEur * EUR_TO_USDC_RATE;
+        return BigInt(Math.round(usdc * Number(USDC_MULTIPLIER)));
+    }
+}
+// ---------------------------------------------------------------------------
+// Error class
+// ---------------------------------------------------------------------------
+/** AP2-specific error with structured context. */
+export class AP2Error extends Error {
+    constructor(message, context) {
+        super(message);
+        this.context = context;
+        this.name = 'AP2Error';
+    }
+}
+// ---------------------------------------------------------------------------
+// Re-export builder as standalone function
+// ---------------------------------------------------------------------------
+export { buildPacs008 };
+//# sourceMappingURL=index.js.map

package/dist/ap2/index.js.map

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

package/dist/bridge/unified.d.ts

@@ -0,0 +1,101 @@
+import type { WalletClient } from 'viem';
+import type { Keypair } from '@solana/web3.js';
+import { BridgeError } from './client.js';
+import type { BridgeChain, BridgeResult } from './types.js';
+import { type CCTPSupportedChain, type BridgeQuote, CCTP_DOMAIN_IDS, BRIDGE_CHAIN_IDS, BRIDGE_RPC_URLS, calcBridgeFee } from './types.js';
+import { SolanaBridgeError } from '../solana/bridge.js';
+export interface UnifiedBridgeConfig {
+    /** EVM wallet client (required for any EVM source chain) */
+    evmSigner?: WalletClient;
+    /** Solana keypair (required when Solana is source) */
+    solanaWallet?: Keypair;
+    /** Solana RPC URL (default: mainnet-beta public) */
+    solanaRpcUrl?: string;
+    /** Override EVM RPC URLs per chain */
+    evmRpcOverrides?: Partial<Record<BridgeChain, string>>;
+    /** Circle attestation API override */
+    attestationApiUrl?: string;
+    /** Platform fee wallet address (future: fee collection) */
+    feeWallet?: string;
+}
+export interface UnifiedBridgeParams {
+    /** USDC amount in base units (6 decimals). 1 USDC = 1_000_000 */
+    amount: bigint;
+    /** Source chain */
+    sourceChain: CCTPSupportedChain;
+    /** Destination chain */
+    destinationChain: CCTPSupportedChain;
+    /** Recipient address (hex for EVM, base58 for Solana destination) */
+    destinationAddress: string;
+    /** Finality: 0 = fast (~20s), 1000 = finalized (~15min) */
+    minFinalityThreshold?: number;
+    /** Apply 0.1% platform fee (default: true) */
+    applyPlatformFee?: boolean;
+    /** Override destination RPC URL */
+    destinationRpcUrl?: string;
+}
+export type { BridgeResult, BridgeQuote, CCTPSupportedChain };
+/**
+ * UnifiedBridge — Cross-chain USDC bridge across all 17 CCTP V2 supported chains.
+ *
+ * Routing:
+ *   - EVM → EVM:     BridgeModule (approve → burn → attest → mint)
+ *   - EVM → Solana:  BridgeModule burn + SolanaCCTPBridge receive
+ *   - Solana → EVM:  SolanaCCTPBridge burn + EVM receiveMessage
+ *   - Solana → Solana: throws (use native Solana transfer instead)
+ *
+ * @example
+ * ```ts
+ * import { UnifiedBridge } from 'agentwallet-sdk';
+ * import { createWalletClient } from 'viem';
+ *
+ * const bridge = new UnifiedBridge({ evmSigner });
+ *
+ * // Bridge 1 USDC from Base to Polygon
+ * const result = await bridge.bridge({
+ *   amount: 1_000_000n,
+ *   sourceChain: 'base',
+ *   destinationChain: 'polygon',
+ *   destinationAddress: '0x...',
+ * });
+ * console.log(bridge.getSupportedChains()); // 17 chains!
+ * ```
+ */
+export declare class UnifiedBridge {
+    private readonly config;
+    private readonly solanaConnection;
+    constructor(config?: UnifiedBridgeConfig);
+    /**
+     * Bridge USDC between any two CCTP V2 supported chains.
+     * Routes automatically based on source/destination chain types.
+     */
+    bridge(params: UnifiedBridgeParams): Promise<BridgeResult>;
+    /**
+     * Get all supported chains (16 EVM + Solana = 17 total).
+     */
+    getSupportedChains(): CCTPSupportedChain[];
+    /**
+     * Get a bridge quote: fee breakdown + estimated time.
+     */
+    getQuote(params: {
+        amount: bigint;
+        sourceChain: CCTPSupportedChain;
+        destinationChain: CCTPSupportedChain;
+    }): BridgeQuote;
+    /**
+     * Check if a route is supported.
+     */
+    isRouteSupported(source: CCTPSupportedChain, destination: CCTPSupportedChain): boolean;
+    private bridgeEvmToEvm;
+    private bridgeSolanaToEvm;
+    private bridgeEvmToSolana;
+    private validateParams;
+    /**
+     * Convert a Solana base58 address to a 32-byte hex string for EVM mintRecipient.
+     * Per Circle docs: hex-encoded USDC token account address.
+     */
+    private solanaAddressToHex;
+}
+export { BridgeError, SolanaBridgeError };
+export { CCTP_DOMAIN_IDS, BRIDGE_CHAIN_IDS, BRIDGE_RPC_URLS, calcBridgeFee, };
+//# sourceMappingURL=unified.d.ts.map

package/dist/bridge/unified.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unified.d.ts","sourceRoot":"","sources":["../../src/bridge/unified.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AACzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE/C,OAAO,EAAgB,WAAW,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,eAAe,EACf,gBAAgB,EAChB,eAAe,EAEf,aAAa,EAGd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAoB,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAI1E,MAAM,WAAW,mBAAmB;IAClC,4DAA4D;IAC5D,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB,sDAAsD;IACtD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,eAAe,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;IACvD,sCAAsC;IACtC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB;IACnB,WAAW,EAAE,kBAAkB,CAAC;IAChC,wBAAwB;IACxB,gBAAgB,EAAE,kBAAkB,CAAC;IACrC,qEAAqE;IACrE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,2DAA2D;IAC3D,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,8CAA8C;IAC9C,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,mCAAmC;IACnC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;AAI9D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAa;gBAElC,MAAM,GAAE,mBAAwB;IAU5C;;;OAGG;IACG,MAAM,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,YAAY,CAAC;IA4DhE;;OAEG;IACH,kBAAkB,IAAI,kBAAkB,EAAE;IAI1C;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE;QACf,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,kBAAkB,CAAC;QAChC,gBAAgB,EAAE,kBAAkB,CAAC;KACtC,GAAG,WAAW;IAuBf;;OAEG;IACH,gBAAgB,CAAC,MAAM,EAAE,kBAAkB,EAAE,WAAW,EAAE,kBAAkB,GAAG,OAAO;YAQxE,cAAc;YAmCd,iBAAiB;YA4EjB,iBAAiB;IAoF/B,OAAO,CAAC,cAAc;IAsCtB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;CAkB3B;AAID,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,CAAC;AAC1C,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,aAAa,GACd,CAAC"}