@paysponge/sdk 0.1.75 → 0.1.88

package/dist/tools/definitions.js

@@ -46,8 +46,13 @@ export const TOOL_DEFINITIONS = [
                     enum: [
                         "ethereum",
                         "base",
+                        "arbitrum-one",
+                        "monad",
+                        "polygon",
                         "sepolia",
                         "base-sepolia",
+                        "arbitrum-sepolia",
+                        "polygon-amoy",
                         "tempo-testnet",
                         "tempo",
                         "solana",
@@ -76,13 +81,13 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: "evm_transfer",
-        description: "Transfer native tokens or USDC on Ethereum, Base, Polygon, or their testnets. Supports native (ETH/POL) and USDC transfers.",
+        description: "Transfer native tokens or USDC on Ethereum, Base, Arbitrum, Polygon, Monad, or their testnets. Supports native (ETH/MON/POL) and USDC transfers.",
         input_schema: {
             type: "object",
             properties: {
                 chain: {
                     type: "string",
-                    enum: ["ethereum", "base", "polygon", "sepolia", "base-sepolia", "polygon-amoy"],
+                    enum: ["ethereum", "base", "arbitrum-one", "monad", "polygon", "sepolia", "base-sepolia", "arbitrum-sepolia", "polygon-amoy", "monad-testnet"],
                     description: "The chain to transfer on",
                 },
                 to: {
@@ -95,8 +100,8 @@ export const TOOL_DEFINITIONS = [
                 },
                 currency: {
                     type: "string",
-                    enum: ["ETH", "POL", "USDC"],
-                    description: "The currency to transfer (ETH for Ethereum/Base, POL for Polygon, or USDC)",
+                    enum: ["ETH", "MON", "POL", "USDC"],
+                    description: "The currency to transfer (ETH for Ethereum/Base/Arbitrum, MON for Monad, POL for Polygon, or USDC)",
                 },
             },
             required: ["chain", "to", "amount", "currency"],
@@ -321,18 +326,18 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: "bridge",
-        description: "Bridge tokens between different blockchains using deBridge. Supports Ethereum, Base, and Solana.",
+        description: "Bridge tokens between different blockchains using deBridge. Supports Ethereum, Base, Arbitrum, Polygon, Monad, Tempo, Solana, and Hyperliquid where routes are available.",
         input_schema: {
             type: "object",
             properties: {
                 sourceChain: {
                     type: "string",
-                    enum: ["ethereum", "base", "sepolia", "base-sepolia", "solana", "solana-devnet"],
+                    enum: ["ethereum", "base", "arbitrum-one", "polygon", "monad", "tempo", "sepolia", "base-sepolia", "arbitrum-sepolia", "polygon-amoy", "monad-testnet", "solana", "solana-devnet"],
                     description: "The source chain to bridge FROM",
                 },
                 destinationChain: {
                     type: "string",
-                    enum: ["ethereum", "base", "sepolia", "base-sepolia", "solana", "solana-devnet"],
+                    enum: ["ethereum", "base", "arbitrum-one", "polygon", "monad", "tempo", "hyperliquid", "polymarket", "sepolia", "base-sepolia", "arbitrum-sepolia", "polygon-amoy", "monad-testnet", "solana", "solana-devnet"],
                     description: "The destination chain to bridge TO",
                 },
                 token: {
@@ -525,8 +530,8 @@ export const TOOL_DEFINITIONS = [
     {
         name: "paid_fetch",
         description: "Make an HTTP request with automatic paid API handling. " +
-            "This is the main one-shot paid fetch tool. It selects the best wallet route, automatically handles x402 or MPP challenges, " +
-            "and falls back when the requested chain is unsupported by the endpoint.",
+            "This is the main one-shot paid fetch tool. It detects x402 or MPP from the endpoint's 402 challenge, " +
+            "handles the matching payment flow, and if both are advertised chooses the route with the highest available stablecoin balance.",
         input_schema: {
             type: "object",
             properties: {
@@ -552,6 +557,11 @@ export const TOOL_DEFINITIONS = [
                     enum: ["base", "solana", "tempo", "ethereum"],
                     description: "Preferred wallet chain to spend from. This is a hint, not a hard requirement.",
                 },
+                protocol: {
+                    type: "string",
+                    enum: ["x402", "mpp"],
+                    description: "Explicit protocol override/debug option. Omit to route from the endpoint's 402 response and balance tie-breaker.",
+                },
             },
             required: ["url"],
         },
@@ -854,6 +864,211 @@ export const TOOL_DEFINITIONS = [
             { key: "created_at", label: "Created" },
         ], "Key stored"),
     },
+    {
+        name: "bank_onboard",
+        description: "Start or resume banking onboarding. Returns a KYC verification link until internal KYC is approved, then a Bridge terms URL unless the customer is already active.",
+        input_schema: {
+            type: "object",
+            properties: {
+                wallet_id: {
+                    type: "string",
+                    description: "Optional wallet ID to associate with the onboarding request.",
+                },
+                redirect_uri: {
+                    type: "string",
+                    description: "URL to redirect to after KYC completion.",
+                },
+                customer_type: {
+                    type: "string",
+                    enum: ["individual", "business"],
+                    description: "Customer type. KYC-backed bank onboarding currently supports individual customers only.",
+                },
+                signed_agreement_id: {
+                    type: "string",
+                    description: "Bridge signed agreement ID from the terms redirect, used to finish KYC-backed customer creation.",
+                },
+            },
+            required: [],
+        },
+        cli_output: fieldsOutput([
+            { key: "kyc_url", label: "Verification URL" },
+            { key: ["customer", "kycStatus"], label: "KYC status" },
+            { key: ["customer", "tosStatus"], label: "TOS status" },
+            { key: "message", label: "Message" },
+        ], "Bank onboarding"),
+    },
+    {
+        name: "bank_status",
+        description: "Check Bridge banking onboarding, KYC, terms, and capability status.",
+        input_schema: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+        cli_output: fieldsOutput([
+            { key: "onboarded", label: "Onboarded" },
+            { key: ["customer", "status"], label: "Status" },
+            { key: ["customer", "kycStatus"], label: "KYC status" },
+            { key: ["customer", "tosStatus"], label: "TOS status" },
+            { key: ["customer", "hostedLinkUrl"], label: "Hosted link" },
+            { key: "message", label: "Message" },
+        ], "Bank status"),
+    },
+    {
+        name: "bank_create_virtual_account",
+        description: "Create or retrieve a virtual bank account for a wallet to receive USD deposits as USDC.",
+        input_schema: {
+            type: "object",
+            properties: {
+                wallet_id: {
+                    type: "string",
+                    description: "Wallet ID to create a virtual account for.",
+                },
+            },
+            required: ["wallet_id"],
+        },
+        cli_output: fieldsOutput([
+            { key: ["virtual_account", "id"], label: "ID" },
+            { key: ["virtual_account", "status"], label: "Status" },
+            { key: ["virtual_account", "walletId"], label: "Wallet" },
+            { key: ["virtual_account", "destinationPaymentRail"], label: "Rail" },
+            { key: ["virtual_account", "destinationAddress"], label: "Destination" },
+            { key: ["virtual_account", "depositInstructions"], label: "Deposit instructions" },
+            { key: "message", label: "Message" },
+        ], "Virtual bank account"),
+    },
+    {
+        name: "bank_get_virtual_account",
+        description: "Get virtual bank account deposit instructions for one wallet, or list all virtual bank accounts.",
+        input_schema: {
+            type: "object",
+            properties: {
+                wallet_id: {
+                    type: "string",
+                    description: "Wallet ID to get. Omit to list all virtual accounts.",
+                },
+            },
+            required: [],
+        },
+        cli_output: fieldsOutput([
+            { key: "found", label: "Found" },
+            { key: "count", label: "Count" },
+            { key: "accounts", label: "Accounts" },
+            { key: ["virtual_account", "id"], label: "ID" },
+            { key: ["virtual_account", "status"], label: "Status" },
+            { key: ["virtual_account", "depositInstructions"], label: "Deposit instructions" },
+            { key: "message", label: "Message" },
+        ], "Virtual bank account"),
+    },
+    {
+        name: "bank_list_external_accounts",
+        description: "List linked external US bank accounts for ACH or wire payouts.",
+        input_schema: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+        cli_output: tableOutput([
+            { key: "id", label: "ID" },
+            { key: "bankName", label: "Bank" },
+            { key: "last4", label: "Last 4" },
+            { key: "accountType", label: "Type" },
+            { key: "active", label: "Active" },
+        ], "External bank accounts", "accounts", "No linked bank accounts found."),
+    },
+    {
+        name: "bank_add_external_account",
+        description: "Link an external US bank account for receiving USD ACH or wire payouts.",
+        input_schema: {
+            type: "object",
+            properties: {
+                bank_name: { type: "string", description: "Bank name." },
+                account_owner_name: { type: "string", description: "Full name of the account holder." },
+                routing_number: { type: "string", description: "9-digit ABA routing number." },
+                account_number: { type: "string", description: "Bank account number." },
+                checking_or_savings: {
+                    type: "string",
+                    enum: ["checking", "savings"],
+                    description: "Bank account type.",
+                },
+                street_line_1: { type: "string", description: "Account holder street address line 1." },
+                street_line_2: { type: "string", description: "Street address line 2." },
+                city: { type: "string", description: "City." },
+                state: { type: "string", description: "US state, e.g. CA." },
+                postal_code: { type: "string", description: "ZIP code." },
+            },
+            required: [
+                "bank_name",
+                "account_owner_name",
+                "routing_number",
+                "account_number",
+                "checking_or_savings",
+                "street_line_1",
+                "city",
+                "state",
+                "postal_code",
+            ],
+        },
+        cli_output: fieldsOutput([
+            { key: ["account", "id"], label: "ID" },
+            { key: ["account", "bankName"], label: "Bank" },
+            { key: ["account", "last4"], label: "Last 4" },
+            { key: ["account", "accountType"], label: "Type" },
+            { key: "message", label: "Message" },
+        ], "External bank account"),
+    },
+    {
+        name: "bank_send",
+        description: "Send USD from a crypto wallet to a linked external bank account by funding a Bridge payout with USDC.",
+        input_schema: {
+            type: "object",
+            properties: {
+                wallet_id: { type: "string", description: "Wallet ID to send USDC from." },
+                external_account_id: {
+                    type: "string",
+                    description: "External bank account ID from bank_list_external_accounts.",
+                },
+                amount: { type: "string", description: "USD amount, e.g. '100.00'." },
+                payment_rail: {
+                    type: "string",
+                    enum: ["ach", "wire"],
+                    description: "Payout rail. Defaults to ach.",
+                },
+            },
+            required: ["wallet_id", "external_account_id", "amount"],
+        },
+        cli_output: fieldsOutput([
+            { key: ["transfer", "id"], label: "ID" },
+            { key: ["transfer", "status"], label: "Status" },
+            { key: ["transfer", "amount"], label: "Amount" },
+            { key: ["transfer", "destinationPaymentRail"], label: "Rail" },
+            { key: ["transfer", "fundingTxHash"], label: "Funding tx" },
+            { key: ["transfer", "fundingExplorerUrl"], label: "Explorer" },
+            { key: "message", label: "Message" },
+        ], "Bank transfer"),
+    },
+    {
+        name: "bank_list_transfers",
+        description: "List bank transfer history, optionally filtered by transfer ID.",
+        input_schema: {
+            type: "object",
+            properties: {
+                transfer_id: {
+                    type: "string",
+                    description: "Optional transfer ID to filter by.",
+                },
+            },
+            required: [],
+        },
+        cli_output: tableOutput([
+            { key: "id", label: "ID" },
+            { key: "status", label: "Status" },
+            { key: "amount", label: "Amount" },
+            { key: "destinationPaymentRail", label: "Rail" },
+            { key: "fundingTxHash", label: "Funding tx" },
+            { key: "createdAt", label: "Created" },
+        ], "Bank transfers", "transfers", "No bank transfers found."),
+    },
     {
         name: "store_credit_card",
         description: "Store credit card details in encrypted secret storage for this agent. " +
@@ -1036,11 +1251,233 @@ export const TOOL_DEFINITIONS = [
             required: [],
         },
     },
+    {
+        name: "report_card_usage",
+        description: "Report the outcome of a purchase attempt that used a stored or vaulted card. " +
+            "Use this after checkout to log success/failure and update spending usage.",
+        input_schema: {
+            type: "object",
+            properties: {
+                payment_method_id: { type: "string", description: "Payment method ID used for the purchase." },
+                merchant_name: { type: "string", description: "Merchant name." },
+                merchant_domain: { type: "string", description: "Merchant domain." },
+                amount: { type: "string", description: "Amount charged or attempted." },
+                currency: { type: "string", description: "Currency for the amount, e.g. USD." },
+                status: {
+                    type: "string",
+                    enum: ["success", "failed", "cancelled"],
+                    description: "Outcome of the purchase attempt.",
+                },
+                failure_reason: { type: "string", description: "Failure reason when status is failed." },
+            },
+            required: ["payment_method_id", "status"],
+        },
+        cli_output: fieldsOutput([
+            { key: "status", label: "Status" },
+            { key: "message", label: "Message" },
+            { key: "payment_method_id", label: "Payment method" },
+        ], "Card usage"),
+    },
+    {
+        name: "get_sponge_card_status",
+        description: "Get the user's Sponge Card onboarding, consent, card, and balance status. " +
+            "Use this before onboarding, terms acceptance, card creation, funding, withdrawal, or card-detail retrieval. " +
+            "Card balance amounts include explicit cent fields and formatted USD display fields, e.g. spending_power_cents=250 means spending_power_display='$2.50'.",
+        input_schema: {
+            type: "object",
+            properties: {
+                refresh: {
+                    type: "boolean",
+                    description: "Force-refresh issuer application status before returning. Defaults to true.",
+                },
+            },
+            required: [],
+        },
+        cli_output: fieldsOutput([
+            { key: "onboarded", label: "Onboarded" },
+            { key: "environment", label: "Environment" },
+            { key: "ready_for_card_creation", label: "Ready for card creation" },
+            { key: ["customer", "application_status"], label: "Application status" },
+            { key: ["balances", "spending_power_display"], label: "Spending power" },
+            { key: ["balances", "credit_limit_display"], label: "Credit limit" },
+            { key: ["balances", "pending_charges_display"], label: "Pending charges" },
+            { key: ["balances", "posted_charges_display"], label: "Posted charges" },
+            { key: ["balances", "balance_due_display"], label: "Balance due" },
+            { key: "completion_link_url", label: "Completion link" },
+            { key: "message", label: "Message" },
+        ], "Sponge Card status"),
+    },
+    {
+        name: "onboard_sponge_card",
+        description: "Start Sponge Card onboarding for the authenticated user, returning a KYC verification link first when internal KYC is missing, and record Sponge consent acknowledgements. " +
+            "The issuer environment is determined by API key mode. Call get_sponge_card_status afterwards to check approval.",
+        input_schema: {
+            type: "object",
+            properties: {
+                redirect_uri: {
+                    type: "string",
+                    description: "URL to redirect to after KYC completion.",
+                },
+                occupation: { type: "string", description: "Occupation or SOC code." },
+                e_sign_consent: { type: "boolean", description: "Must be true: user accepts the E-Sign Consent." },
+                account_opening_privacy_notice: {
+                    type: "boolean",
+                    description: "Required for US KYC: user accepts the Account Opening Privacy Notice.",
+                },
+                sponge_card_terms: {
+                    type: "boolean",
+                    description: "Must be true: user accepts Sponge Card terms and issuer privacy policy.",
+                },
+                information_certification: {
+                    type: "boolean",
+                    description: "Must be true: user certifies KYC information is accurate.",
+                },
+                unauthorized_solicitation_acknowledgement: {
+                    type: "boolean",
+                    description: "Must be true: user acknowledges applying is not unauthorized solicitation.",
+                },
+            },
+            required: [],
+        },
+        cli_output: fieldsOutput([
+            { key: "submitted_application", label: "Submitted application" },
+            { key: "environment", label: "Environment" },
+            { key: "ready_for_card_creation", label: "Ready for card creation" },
+            { key: "kyc_url", label: "KYC URL" },
+            { key: "message", label: "Message" },
+        ], "Sponge Card onboarding"),
+    },
+    {
+        name: "accept_sponge_card_terms",
+        description: "Record Sponge Card consent acknowledgements for an existing application. " +
+            "Use this when get_sponge_card_status says the application is approved but Sponge consent is missing.",
+        input_schema: {
+            type: "object",
+            properties: {
+                e_sign_consent: { type: "boolean", description: "Must be true: user accepts the E-Sign Consent." },
+                account_opening_privacy_notice: {
+                    type: "boolean",
+                    description: "Required for US KYC: user accepts the Account Opening Privacy Notice.",
+                },
+                sponge_card_terms: {
+                    type: "boolean",
+                    description: "Must be true: user accepts Sponge Card terms and issuer privacy policy.",
+                },
+                information_certification: {
+                    type: "boolean",
+                    description: "Must be true: user certifies KYC information is accurate.",
+                },
+                unauthorized_solicitation_acknowledgement: {
+                    type: "boolean",
+                    description: "Must be true: user acknowledges applying is not unauthorized solicitation.",
+                },
+            },
+            required: [
+                "e_sign_consent",
+                "sponge_card_terms",
+                "information_certification",
+                "unauthorized_solicitation_acknowledgement",
+            ],
+        },
+        cli_output: fieldsOutput([
+            { key: "environment", label: "Environment" },
+            { key: "ready_for_card_creation", label: "Ready for card creation" },
+            { key: "message", label: "Message" },
+        ], "Sponge Card terms"),
+    },
+    {
+        name: "create_sponge_card",
+        description: "Create the user's Sponge Card after issuer approval and Sponge consent. " +
+            "If a card already exists for the environment, the API returns the existing card instead of issuing a duplicate.",
+        input_schema: {
+            type: "object",
+            properties: {
+                billing: {
+                    type: "object",
+                    description: "Billing address: line1, optional line2, city, region, postal_code, country_code.",
+                },
+                email: { type: "string", description: "Contact email to store with the card." },
+                phone: { type: "string", description: "Contact phone to store with the card." },
+                shipping: {
+                    type: "object",
+                    description: "Optional shipping address. Same address fields as billing, plus optional first_name and last_name.",
+                },
+            },
+            required: ["billing", "email", "phone"],
+        },
+        cli_output: fieldsOutput([
+            { key: "created", label: "Created" },
+            { key: "environment", label: "Environment" },
+            { key: ["card", "id"], label: "Card ID" },
+            { key: ["card", "status"], label: "Status" },
+            { key: ["card", "last4"], label: "Last 4" },
+            { key: "message", label: "Message" },
+        ], "Sponge Card"),
+    },
+    {
+        name: "get_sponge_card_details",
+        description: "Fetch encrypted PAN/CVC for the user's Sponge Card plus a per-call secret_key for local AES-128-GCM decryption and current spending power. " +
+            "Use spending_power_display for user-facing output; spending_power_cents is an integer in cents, so 250 means $2.50. " +
+            "Treat the response and decrypted values as highly sensitive; do not log or persist them.",
+        input_schema: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+        cli_output: fieldsOutput([
+            { key: "last4", label: "Last 4" },
+            { key: "expiration_month", label: "Expiry month" },
+            { key: "expiration_year", label: "Expiry year" },
+            { key: "status", label: "Status" },
+            { key: "spending_power_display", label: "Spending power" },
+            { key: "spending_power_cents", label: "Spending power cents" },
+            { key: "secret_key", label: "Secret key" },
+        ], "Sponge Card details"),
+    },
+    {
+        name: "fund_sponge_card",
+        description: "Top up the user's Sponge Card collateral by sending USDC from the wallet to the card collateral contract deposit address.",
+        input_schema: {
+            type: "object",
+            properties: {
+                amount: { type: "string", description: "USDC amount in human-readable units, e.g. '100.50'." },
+                chain: { type: "string", description: "Optional collateral chain, e.g. base or solana." },
+            },
+            required: ["amount"],
+        },
+        cli_output: fieldsOutput([
+            { key: "tx_hash", label: "Transaction" },
+            { key: "transaction_id", label: "Transaction ID" },
+            { key: "chain_id", label: "Chain ID" },
+            { key: "to_address", label: "To" },
+            { key: "token_address", label: "Token" },
+            { key: "amount", label: "Amount" },
+        ], "Sponge Card funding"),
+    },
+    {
+        name: "withdraw_sponge_card",
+        description: "Withdraw USDC from Sponge Card collateral back to the user's wallet, reducing card spending power.",
+        input_schema: {
+            type: "object",
+            properties: {
+                amount: { type: "string", description: "USDC amount in human-readable units, max 2 decimal places." },
+                chain: { type: "string", description: "Optional collateral chain, e.g. base or solana." },
+            },
+            required: ["amount"],
+        },
+        cli_output: fieldsOutput([
+            { key: "tx_hash", label: "Transaction" },
+            { key: "chain_id", label: "Chain ID" },
+            { key: "amount", label: "Amount" },
+            { key: "recipient_address", label: "Recipient" },
+        ], "Sponge Card withdrawal"),
+    },
     {
         name: "get_card",
         description: "Fetch the user's card details. Routes to the right card source automatically:\n\n" +
             "- **Sponge Card (Rain)** — credit card backed by on-chain collateral. Returns encrypted PAN/CVC plus a per-call symmetric key for client-side AES-128-GCM decryption.\n" +
             "- **Basis Theory vaulted card** — a card the user vaulted via the dashboard. Returns a short-lived BT session (`session_key` + `retrieve_url`) that you must immediately fetch over HTTP.\n\n" +
+            "For the Sponge Card branch, use `spending_power_display` for user-facing output; `spending_power_cents` is an integer in cents, so 250 means $2.50.\n\n" +
             "If the user has only one source enrolled, returns that card directly. If both sources are enrolled and `card_type` is omitted, returns `{ status: \"selection_required\", available_cards: [...] }` so you can ask the user which to use, then re-call with `card_type` set.\n\n" +
             "For per-transaction virtual cards (issued on demand for a specific merchant + amount), use `issue_virtual_card` instead.",
         input_schema: {
@@ -1070,7 +1507,8 @@ export const TOOL_DEFINITIONS = [
             { key: "card_type", label: "Card type" },
             { key: "card_last4", label: "Card last 4" },
             { key: "last4", label: "Sponge Card last 4" },
-            { key: "spending_power_cents", label: "Spending power (cents)" },
+            { key: "spending_power_display", label: "Spending power" },
+            { key: "spending_power_cents", label: "Spending power cents" },
             { key: "email", label: "Email" },
             { key: "phone", label: "Phone" },
             { key: "retrieve_url", label: "Retrieve URL" },
@@ -1095,6 +1533,8 @@ export const TOOL_DEFINITIONS = [
                 merchant_url: { type: "string", description: "Merchant URL" },
                 merchant_country_code: { type: "string", description: "Merchant country code (default: US)" },
                 description: { type: "string", description: "Description of the purchase" },
+                products: { type: "array", description: "Optional products being purchased." },
+                shipping_address: { type: "object", description: "Optional shipping address for the purchase." },
                 enrollment_id: { type: "string", description: "Specific enrollment ID (uses default if omitted)" },
             },
             required: ["amount", "merchant_name", "merchant_url"],