envoy-pay 0.1.0

package/dist/types/adapters/evm.d.ts

@@ -0,0 +1,93 @@
+import { PaymentAdapter } from './types';
+import { Logger } from '../logger';
+/** All EVM chains supported by envoy-pay. Celo is the first-class default. */
+export type EvmChainName = 'celo' | 'celo-alfajores' | 'base' | 'base-sepolia' | 'arbitrum' | 'arbitrum-sepolia' | 'optimism' | 'optimism-sepolia' | 'ethereum' | 'ethereum-sepolia' | 'polygon' | 'polygon-amoy' | 'xlayer' | 'xlayer-testnet';
+/** ERC-20 stablecoin descriptor (address + decimals). */
+export interface StablecoinInfo {
+    address: `0x${string}`;
+    decimals: number;
+}
+export interface EvmAdapterOptions {
+    /**
+     * Chain to settle on.
+     * @example 'base', 'arbitrum', 'optimism', 'ethereum', 'polygon'
+     * @example 'base-sepolia', 'arbitrum-sepolia' (testnets)
+     */
+    chain: EvmChainName;
+    /**
+     * Asset to settle with.
+     * - 'native' — chain's native token (ETH on L1/L2, MATIC on Polygon, CELO on Celo)
+     * - 'USDC' — Circle's native USDC (ERC-20)
+     * - 'cUSD' / 'cEUR' / 'cREAL' — Mento stablecoins (Celo only)
+     * - any string symbol present in the chain's `stablecoins` map
+     * @default 'native'
+     */
+    asset?: 'native' | 'USDC' | 'cUSD' | 'cEUR' | 'cREAL' | 'USDT' | string;
+    /** Hex private key (0x-prefixed). If omitted, a random key is generated. */
+    privateKey?: `0x${string}`;
+    /** Optional custom RPC URL. Uses viem's default public RPCs if omitted. */
+    rpcUrl?: string;
+    /** Optional logger. SDK is silent by default. */
+    logger?: Logger;
+}
+/**
+ * EvmPaymentAdapter — Universal EVM on-chain settlement.
+ *
+ * One adapter for ALL EVM chains supported by x402:
+ * Base, Arbitrum, Optimism, Ethereum, Polygon — mainnet & testnet.
+ *
+ * Supports native token (ETH/MATIC) and USDC (Circle ERC-20) transfers.
+ *
+ * @example
+ * ```ts
+ * // Arbitrum USDC settlement
+ * const adapter = new EvmPaymentAdapter({
+ *   chain: 'arbitrum',
+ *   asset: 'USDC',
+ *   privateKey: '0x...',
+ * });
+ *
+ * // Base ETH settlement (testnet)
+ * const adapter = new EvmPaymentAdapter({
+ *   chain: 'base-sepolia',
+ *   asset: 'native',
+ * });
+ * ```
+ *
+ * @see https://x402.org — x402 payment protocol
+ * @see https://envoy.dev — envoy production infrastructure
+ */
+export declare class EvmPaymentAdapter implements PaymentAdapter {
+    readonly chainName: string;
+    readonly caip2Id: string;
+    private wallet;
+    private publicClient;
+    private account;
+    private chainConfig;
+    private asset;
+    private log;
+    constructor(options: EvmAdapterOptions);
+    getAddress(): string;
+    /** Get native token balance (ETH, MATIC, etc.). */
+    getNativeBalance(): Promise<string>;
+    /** Get USDC balance (6 decimals). Returns '0.00' if USDC not supported. */
+    getUsdcBalance(): Promise<string>;
+    /** Get balance for any stablecoin symbol present on this chain. Returns '0.00' if not supported. */
+    getStablecoinBalance(symbol: string): Promise<string>;
+    /** List stablecoin symbols available on this chain. */
+    listStablecoins(): string[];
+    pay(destination: string, amount: string, network: string): Promise<string | null>;
+    private payNative;
+    private payStablecoin;
+    private shortAddr;
+}
+/** Returns metadata for all supported EVM chains. */
+export declare function listEvmChains(): Array<{
+    name: EvmChainName;
+    displayName: string;
+    chainId: number;
+    caip2Id: string;
+    hasUsdc: boolean;
+    stablecoins: string[];
+}>;
+//# sourceMappingURL=evm.d.ts.map

package/dist/types/adapters/evm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evm.d.ts","sourceRoot":"","sources":["../../../src/adapters/evm.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,MAAM,EAAc,MAAM,WAAW,CAAC;AAI/C,8EAA8E;AAC9E,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,gBAAgB,GAChB,MAAM,GACN,cAAc,GACd,UAAU,GACV,kBAAkB,GAClB,UAAU,GACV,kBAAkB,GAClB,UAAU,GACV,kBAAkB,GAClB,SAAS,GACT,cAAc,GACd,QAAQ,GACR,gBAAgB,CAAC;AAErB,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,KAAK,MAAM,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;CAClB;AA0KD,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,KAAK,EAAE,YAAY,CAAC;IACpB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IACxE,4EAA4E;IAC5E,UAAU,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;IAC3B,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,iBAAkB,YAAW,cAAc;IACtD,SAAgB,SAAS,EAAE,MAAM,CAAC;IAClC,SAAgB,OAAO,EAAE,MAAM,CAAC;IAEhC,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,OAAO,CAAyC;IACxD,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,GAAG,CAAS;gBAER,OAAO,EAAE,iBAAiB;IAwCtC,UAAU,IAAI,MAAM;IAIpB,mDAAmD;IAC7C,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;IAOzC,2EAA2E;IACrE,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAIvC,oGAAoG;IAC9F,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAc3D,uDAAuD;IACvD,eAAe,IAAI,MAAM,EAAE;IAIrB,GAAG,CACP,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;YASX,SAAS;YAqCT,aAAa;IA2C3B,OAAO,CAAC,SAAS;CAGlB;AAID,qDAAqD;AACrD,wBAAgB,aAAa,IAAI,KAAK,CAAC;IACrC,IAAI,EAAE,YAAY,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB,CAAC,CASD"}

package/dist/types/adapters/index.d.ts

@@ -0,0 +1,7 @@
+export { PaymentAdapter } from './types';
+export { EvmPaymentAdapter, EvmAdapterOptions, EvmChainName, listEvmChains } from './evm';
+export { StripePaymentAdapter, StripeAdapterOptions } from './stripe';
+export { BasePaymentAdapter, BaseAdapterOptions } from './base';
+export { StellarPaymentAdapter, StellarPaymentAdapterOptions } from './stellar';
+export { SolanaPaymentAdapter, SolanaAdapterOptions } from './solana';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAC1F,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAChE,OAAO,EAAE,qBAAqB,EAAE,4BAA4B,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC"}

package/dist/types/adapters/ows.d.ts

@@ -0,0 +1,123 @@
+/**
+ * OWS Adapter — Bridge between Open Wallet Standard and envoy.
+ *
+ * Uses `@open-wallet-standard/core` for local key management,
+ * policy-gated signing, and multi-chain address derivation.
+ * envoy handles the payment protocol layer (x402, MPP).
+ *
+ * Architecture:
+ * ```
+ * Agent → EnvoyClient → OWSAdapter → @open-wallet-standard/core
+ *                                     ├── createWallet()
+ *                                     ├── signTransaction()
+ *                                     ├── signMessage()
+ *                                     └── Policy Engine (spending limits)
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { createOwsAdapter } from 'envoy-pay';
+ *
+ * // Create adapter backed by OWS local wallet
+ * const adapter = createOwsAdapter({
+ *   walletName: 'agent-treasury',
+ *   chain: 'evm',
+ *   chainId: 'eip155:8453',
+ *   rpcUrl: 'https://mainnet.base.org',
+ * });
+ *
+ * // Use with envoy client
+ * const client = new EnvoyClient({ adapter });
+ * await client.handle402(response);
+ * ```
+ *
+ * @see https://github.com/open-wallet-standard/core
+ * @see OWS Specification: docs/00-specification.md
+ */
+import type { PaymentAdapter } from './types';
+export interface OwsAdapterOptions {
+    /** Name of the OWS wallet (created if it doesn't exist). */
+    walletName: string;
+    /** Chain family for signing ('evm', 'solana', 'stellar', etc.). */
+    chain: 'evm' | 'solana' | 'xrpl' | 'sui' | 'bitcoin' | 'cosmos' | 'tron' | 'filecoin';
+    /** CAIP-2 chain identifier (e.g. 'eip155:8453'). */
+    chainId: string;
+    /** Custom RPC URL for signAndSend. If omitted, OWS uses built-in defaults. */
+    rpcUrl?: string;
+    /** OWS vault path. Defaults to ~/.ows */
+    vaultPath?: string;
+    /** Passphrase for encrypted wallets, or an OWS API key token (ows_key_...). */
+    passphrase?: string;
+    /** Account index for HD derivation. Defaults to 0. */
+    accountIndex?: number;
+    /** Human-readable chain name for display. */
+    chainName?: string;
+    /** Logger function. */
+    logger?: (msg: string) => void;
+}
+/**
+ * Create a PaymentAdapter backed by an OWS local wallet.
+ *
+ * The adapter automatically creates the wallet if it doesn't exist,
+ * and derives the address for the specified chain.
+ */
+export declare function createOwsAdapter(options: OwsAdapterOptions): PaymentAdapter;
+/**
+ * Create an OWS policy for agent spending limits.
+ *
+ * @example
+ * ```ts
+ * createOwsPolicy({
+ *   id: 'agent-budget',
+ *   name: 'Agent daily budget',
+ *   allowedChains: ['eip155:8453'],
+ *   expiresAt: '2026-12-31T23:59:59Z',
+ * });
+ * ```
+ */
+export declare function createOwsPolicy(options: {
+    id: string;
+    name: string;
+    allowedChains?: string[];
+    expiresAt?: string;
+    vaultPath?: string;
+}): void;
+/**
+ * Create a scoped OWS API key for agent access.
+ * The agent uses this token as the passphrase — it NEVER sees the private key.
+ *
+ * @returns The API key token (shown once — caller must save it)
+ */
+export declare function createOwsAgentKey(options: {
+    name: string;
+    walletName: string;
+    policyIds: string[];
+    passphrase: string;
+    expiresAt?: string;
+    vaultPath?: string;
+}): {
+    token: string;
+    id: string;
+    name: string;
+};
+/**
+ * Import an existing wallet into OWS from a mnemonic.
+ */
+export declare function importOwsWallet(name: string, mnemonic: string, passphrase?: string, vaultPath?: string): import("@open-wallet-standard/core").WalletInfo;
+/**
+ * Import an existing wallet from a private key.
+ */
+export declare function importOwsWalletFromKey(name: string, privateKeyHex: string, chain?: 'evm' | 'solana', passphrase?: string, vaultPath?: string): import("@open-wallet-standard/core").WalletInfo;
+/**
+ * Export the mnemonic from an OWS wallet.
+ */
+export declare function exportOwsWallet(nameOrId: string, passphrase?: string, vaultPath?: string): string;
+/**
+ * List all OWS wallets.
+ */
+export declare function listOwsWallets(vaultPath?: string): import("@open-wallet-standard/core").WalletInfo[];
+/**
+ * Delete an OWS wallet.
+ */
+export declare function deleteOwsWallet(nameOrId: string, vaultPath?: string): void;
+//# sourceMappingURL=ows.d.ts.map

package/dist/types/adapters/ows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ows.d.ts","sourceRoot":"","sources":["../../../src/adapters/ows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAiBH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAI9C,MAAM,WAAW,iBAAiB;IAChC,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IAEnB,mEAAmE;IACnE,KAAK,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;IAEtF,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAEhB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,uBAAuB;IACvB,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAID;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,CA6F3E;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,IAAI,CA2BP;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAS9C;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,mDAGnB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,EACrB,KAAK,GAAE,KAAK,GAAG,QAAgB,EAC/B,UAAU,CAAC,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,mDAGnB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAER;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,qDAEhD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,QAEnE"}

package/dist/types/adapters/solana.d.ts

@@ -0,0 +1,77 @@
+import { PaymentAdapter } from './types';
+import { Logger } from '../logger';
+export interface SolanaAdapterOptions {
+    /**
+     * Solana secret key as a Uint8Array (64 bytes) or base58 string.
+     * If omitted, a random keypair is generated (useful for receiving-only agents).
+     */
+    secretKey?: Uint8Array | number[];
+    /**
+     * Network: 'mainnet-beta' | 'devnet' | 'testnet'
+     * @default 'devnet'
+     */
+    network?: 'mainnet-beta' | 'devnet' | 'testnet';
+    /**
+     * Asset to settle with.
+     * - 'SOL' — native SOL (default)
+     * - 'USDC' — Circle's native USDC (SPL token)
+     * @default 'SOL'
+     */
+    asset?: 'SOL' | 'USDC';
+    /** Optional custom RPC URL. Uses Solana public RPC if omitted. */
+    rpcUrl?: string;
+    /** Optional logger. SDK is silent by default. */
+    logger?: Logger;
+}
+/**
+ * SolanaPaymentAdapter — On-chain settlement on Solana.
+ *
+ * Supports:
+ * - Native SOL transfers (System Program)
+ * - USDC (SPL Token) transfers with automatic ATA creation
+ *
+ * @example
+ * ```ts
+ * // SOL on devnet
+ * const adapter = new SolanaPaymentAdapter({
+ *   secretKey: myKeypair.secretKey,
+ *   network: 'devnet',
+ *   asset: 'SOL',
+ *   logger: console.log,
+ * });
+ *
+ * // USDC on mainnet
+ * const adapter = new SolanaPaymentAdapter({
+ *   secretKey: myKeypair.secretKey,
+ *   network: 'mainnet-beta',
+ *   asset: 'USDC',
+ * });
+ * ```
+ *
+ * @see https://spl.solana.com/token — SPL Token program
+ * @see https://envoy.dev — envoy production infrastructure
+ */
+export declare class SolanaPaymentAdapter implements PaymentAdapter {
+    readonly chainName: string;
+    readonly caip2Id: string;
+    private connection;
+    private keypair;
+    private asset;
+    private usdcMint;
+    private network;
+    private log;
+    constructor(options: SolanaAdapterOptions);
+    getAddress(): string;
+    /** Get SOL balance in SOL (not lamports). */
+    getSolBalance(): Promise<string>;
+    /** Get USDC balance (6 decimals). */
+    getUsdcBalance(): Promise<string>;
+    pay(destination: string, amount: string, network: string): Promise<string | null>;
+    private paySol;
+    private payUsdc;
+    /** Find the Associated Token Account for USDC. Returns null if none. */
+    private findAta;
+    /** Request SOL airdrop from devnet/testnet faucet (for testing). */
+    requestAirdrop(amountSol?: number): Promise<string | null>;
+}
+//# sourceMappingURL=solana.d.ts.map

package/dist/types/adapters/solana.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"solana.d.ts","sourceRoot":"","sources":["../../../src/adapters/solana.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,MAAM,EAAc,MAAM,WAAW,CAAC;AAY/C,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,SAAS,CAAC,EAAE,UAAU,GAAG,MAAM,EAAE,CAAC;IAClC;;;OAGG;IACH,OAAO,CAAC,EAAE,cAAc,GAAG,QAAQ,GAAG,SAAS,CAAC;IAChD;;;;;OAKG;IACH,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,oBAAqB,YAAW,cAAc;IACzD,SAAgB,SAAS,EAAE,MAAM,CAAC;IAClC,SAAgB,OAAO,EAAE,MAAM,CAAC;IAEhC,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,KAAK,CAAiB;IAC9B,OAAO,CAAC,QAAQ,CAAY;IAC5B,OAAO,CAAC,OAAO,CAAwC;IACvD,OAAO,CAAC,GAAG,CAAS;gBAER,OAAO,EAAE,oBAAoB;IA4BzC,UAAU,IAAI,MAAM;IAIpB,6CAA6C;IACvC,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAKtC,qCAAqC;IAC/B,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAWjC,GAAG,CACP,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;YASX,MAAM;YAwCN,OAAO;IA2DrB,wEAAwE;YAC1D,OAAO;IAoBrB,oEAAoE;IAC9D,cAAc,CAAC,SAAS,GAAE,MAAU,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAiBpE"}

package/dist/types/adapters/stellar.d.ts

@@ -0,0 +1,67 @@
+import { PaymentAdapter } from './types';
+import { Logger } from '../logger';
+export interface StellarPaymentAdapterOptions {
+    /** Stellar secret key for the agent's wallet. */
+    secretKey: string;
+    /**
+     * Asset to settle with:
+     * - 'XLM' — native lumens (default for testnet)
+     * - 'USDC' — Circle's native USDC on Stellar (recommended for production)
+     */
+    asset?: 'XLM' | 'USDC';
+    /**
+     * Network: 'mainnet' | 'testnet' (default: 'testnet').
+     * Determines Horizon URL, network passphrase, and CAIP-2 ID.
+     */
+    network?: 'mainnet' | 'testnet';
+    /** Override the Horizon URL. */
+    horizonUrl?: string;
+    /** Optional logger. */
+    logger?: Logger;
+}
+/**
+ * StellarPaymentAdapter — On-chain settlement on the Stellar network.
+ *
+ * Supports:
+ * - Native XLM payments (testnet default)
+ * - Circle USDC payments (production recommended)
+ *
+ * The production envoy stack settles USDC on Stellar mainnet.
+ * @see https://envoy.dev
+ * @see https://stellar.org/usdc
+ */
+export declare class StellarPaymentAdapter implements PaymentAdapter {
+    readonly chainName = "Stellar";
+    readonly caip2Id: string;
+    private keypair;
+    private server;
+    private networkPassphrase;
+    private assetType;
+    private log;
+    constructor(options: StellarPaymentAdapterOptions);
+    getAddress(): string;
+    /**
+     * Get the Stellar asset object based on configuration.
+     * - XLM: native asset (no trustline needed)
+     * - USDC: Circle's issued USDC (trustline required)
+     */
+    private getAsset;
+    /**
+     * Convert atomic units to human-readable amount.
+     * Stellar uses 7 decimal places (stroops) for all assets.
+     */
+    private formatAmount;
+    pay(destination: string, amount: string, network: string): Promise<string | null>;
+    /**
+     * Check if the account has a USDC trustline.
+     * Returns false if using XLM or if the trustline exists.
+     * Returns true if USDC is selected but trustline is missing.
+     */
+    needsTrustline(): Promise<boolean>;
+    /**
+     * Establish a USDC trustline (required before receiving USDC).
+     * Only needed once per account.
+     */
+    createUsdcTrustline(): Promise<string | null>;
+}
+//# sourceMappingURL=stellar.d.ts.map

package/dist/types/adapters/stellar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stellar.d.ts","sourceRoot":"","sources":["../../../src/adapters/stellar.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,MAAM,EAAc,MAAM,WAAW,CAAC;AAK/C,MAAM,WAAW,4BAA4B;IAC3C,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB;;;OAGG;IACH,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAChC,gCAAgC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,qBAAsB,YAAW,cAAc;IAC1D,SAAgB,SAAS,aAAa;IACtC,SAAgB,OAAO,EAAE,MAAM,CAAC;IAEhC,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,SAAS,CAAiB;IAClC,OAAO,CAAC,GAAG,CAAS;gBAER,OAAO,EAAE,4BAA4B;IAqBjD,UAAU,IAAI,MAAM;IAIpB;;;;OAIG;IACH,OAAO,CAAC,QAAQ;IAOhB;;;OAGG;IACH,OAAO,CAAC,YAAY;IAIP,GAAG,CACd,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA0CzB;;;;OAIG;IACU,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC;IAiB/C;;;OAGG;IACU,mBAAmB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CA6B3D"}

package/dist/types/adapters/stripe.d.ts

@@ -0,0 +1,206 @@
+import { PaymentAdapter } from './types';
+import { Logger } from '../logger';
+import { MppChallenge } from '../mpp';
+/**
+ * Configuration for the Stripe MPP adapter.
+ *
+ * @example
+ * ```ts
+ * const adapter = new StripePaymentAdapter({
+ *   stripeSecretKey: process.env.STRIPE_SECRET_KEY!,
+ *   networkId: 'my-business-network',
+ * });
+ * ```
+ */
+export interface StripeAdapterOptions {
+    /**
+     * Stripe secret key (sk_test_... or sk_live_...).
+     * Used to create SPTs and PaymentIntents.
+     */
+    stripeSecretKey: string;
+    /**
+     * Stripe Business Network ID.
+     * Found in Dashboard → Settings → Business profile.
+     */
+    networkId?: string;
+    /**
+     * Accepted payment method types.
+     * @default ['card']
+     */
+    paymentMethodTypes?: string[];
+    /**
+     * Default payment method ID for autonomous agents.
+     * e.g. 'pm_card_visa' for test mode.
+     * If set, the adapter can create SPTs autonomously.
+     */
+    paymentMethodId?: string;
+    /**
+     * Default currency for payments.
+     * @default 'usd'
+     */
+    currency?: string;
+    /**
+     * SPT expiration window in seconds.
+     * @default 300 (5 minutes)
+     */
+    sptExpirySeconds?: number;
+    /**
+     * Stripe API base URL.
+     * @default 'https://api.stripe.com'
+     */
+    stripeApiBase?: string;
+    /** Optional logger. SDK is silent by default. */
+    logger?: Logger;
+}
+/**
+ * Result of creating a Shared Payment Token.
+ */
+interface SptResult {
+    id: string;
+    object: string;
+    expires_at?: number;
+}
+/**
+ * Result of creating/confirming a PaymentIntent.
+ */
+interface PaymentIntentResult {
+    id: string;
+    status: string;
+    amount: number;
+    currency: string;
+    next_action?: {
+        crypto_display_details?: {
+            deposit_addresses?: Record<string, {
+                address: string;
+                supported_tokens?: Array<{
+                    token_currency: string;
+                    token_contract_address: string;
+                }>;
+            }>;
+        };
+    };
+}
+/**
+ * StripePaymentAdapter — Machine Payments Protocol (MPP) settlement.
+ *
+ * Implements the full MPP flow for Stripe:
+ * 1. Receives 402 + `WWW-Authenticate: Payment` challenge
+ * 2. Creates a Shared Payment Token (SPT) via Stripe API
+ * 3. Builds MPP Credential with SPT
+ * 4. Returns credential for `Authorization: Payment` header
+ *
+ * Works in two modes:
+ * - **Autonomous** (with paymentMethodId): Creates SPTs automatically
+ * - **Delegated** (without): Requires external SPT provisioning via `setSptToken()`
+ *
+ * @example
+ * ```ts
+ * // Autonomous mode — agent has a payment method on file
+ * const adapter = new StripePaymentAdapter({
+ *   stripeSecretKey: 'sk_test_...',
+ *   networkId: 'my-network',
+ *   paymentMethodId: 'pm_card_visa', // test card
+ * });
+ *
+ * // Delegated mode — external system provides SPTs
+ * const adapter = new StripePaymentAdapter({
+ *   stripeSecretKey: 'sk_test_...',
+ * });
+ * adapter.setSptToken('spt_...');
+ * ```
+ *
+ * @see https://mpp.dev/payment-methods/stripe — MPP Stripe method spec
+ * @see https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens
+ */
+export declare class StripePaymentAdapter implements PaymentAdapter {
+    readonly chainName = "Stripe MPP";
+    readonly caip2Id: string;
+    private secretKey;
+    private networkId;
+    private paymentMethodTypes;
+    private paymentMethodId;
+    private currency;
+    private sptExpirySeconds;
+    private stripeApiBase;
+    private log;
+    /** Externally-provided SPT for delegated mode */
+    private externalSpt;
+    /** Last MPP challenge processed (for credential building) */
+    private lastChallenge;
+    constructor(options: StripeAdapterOptions);
+    /**
+     * Set or update an externally-provided SPT token.
+     * Used in delegated mode when an external system provides the SPT.
+     */
+    setSptToken(token: string): void;
+    /**
+     * Store a parsed MPP challenge for credential building.
+     * Called by EnvoyClient when a 402 with `WWW-Authenticate: Payment method="stripe"` is received.
+     */
+    setMppChallenge(challenge: MppChallenge): void;
+    /**
+     * Get the last built MPP credential (base64url-encoded).
+     * Used by EnvoyClient to populate the `Authorization: Payment` header.
+     */
+    getLastCredential(): string | null;
+    private _lastCredential;
+    getAddress(): string;
+    /**
+     * Execute a Stripe MPP payment.
+     *
+     * This method handles the full SPT lifecycle:
+     * 1. If an external SPT is set → use it directly
+     * 2. If paymentMethodId is set → create SPT autonomously via Stripe API
+     * 3. Build MPP Credential with the SPT
+     * 4. Return credential string (used as "tx hash" equivalent)
+     *
+     * @param destination - Recipient (Stripe account or payment endpoint)
+     * @param amount - Amount in smallest currency unit (e.g. cents)
+     * @param network - Network identifier (ignored for Stripe, kept for interface compat)
+     * @returns Base64url-encoded MPP credential string, or null on failure
+     */
+    pay(destination: string, amount: string, network: string): Promise<string | null>;
+    /**
+     * Create a Shared Payment Token (SPT) via Stripe API.
+     *
+     * Test mode: POST /v1/test_helpers/shared_payment/granted_tokens
+     * Live mode: POST /v1/shared_payment/issued_tokens (TBD by Stripe)
+     */
+    createSpt(amount: number, currency: string): Promise<SptResult | null>;
+    /**
+     * Create and confirm a PaymentIntent using an SPT.
+     * Used in fallback mode (no MPP challenge, direct Stripe API).
+     */
+    createPaymentIntent(sptId: string, amount: number, currency: string): Promise<PaymentIntentResult | null>;
+    /**
+     * Create a crypto deposit-mode PaymentIntent.
+     * This is the verified-working flow for MPP on Stripe.
+     * Uses Tempo network + USDC stablecoins.
+     *
+     * @param amount - Amount in cents (e.g. 100 = $1.00)
+     * @param currency - Currency code (default: 'usd')
+     * @returns PaymentIntentResult with deposit address, or null on failure
+     *
+     * @example
+     * ```ts
+     * const pi = await adapter.createCryptoPaymentIntent(100, 'usd');
+     * // pi.next_action.crypto_display_details.deposit_addresses.tempo.address
+     * ```
+     */
+    createCryptoPaymentIntent(amount: number, currency?: string): Promise<PaymentIntentResult | null>;
+    /**
+     * Build and return a fully-formed MPP Challenge for server-side use.
+     * Useful if you want to GATE your own API with MPP 402.
+     *
+     * @param amount - Amount to charge (in smallest unit)
+     * @param options - Challenge options
+     * @returns WWW-Authenticate header value
+     */
+    buildServerChallenge(amount: string, options?: {
+        currency?: string;
+        description?: string;
+        expiresInSeconds?: number;
+    }): string;
+}
+export {};
+//# sourceMappingURL=stripe.d.ts.map

package/dist/types/adapters/stripe.d.ts.map

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