stables-mcp-server 1.4.0 → 2.0.0

package/README.md

@@ -1,6 +1,8 @@
 # Stables MCP Server
 
-An MCP (Model Context Protocol) server that exposes the Stables fiat-to-crypto API to AI agents. This allows AI assistants like Claude, ChatGPT, and others to manage customers, create quotes, execute transfers, and handle virtual accounts programmatically.
+An MCP (Model Context Protocol) server that exposes the Stables fiat-to-crypto API to AI agents. This allows AI assistants like Claude, ChatGPT, Cursor, Codex, and other MCP-compatible clients to manage customers, create USDC and USDT quotes, execute approved transfers, and handle virtual accounts programmatically.
+
+Use it to build stablecoin payment workflows for AI agents and agentic commerce: payouts, virtual account deposits, treasury movement, fiat off-ramping, and webhook reconciliation.
 
 ## What is MCP?
 
@@ -8,7 +10,7 @@ MCP (Model Context Protocol) is an open standard that provides a standardized wa
 
 ## Features
 
-This MCP server provides 25 tools across 7 categories:
+This MCP server provides 23 tools across 7 categories:
 
 ### Customer Management
 - `create_customer` - Create individual or business customers
@@ -31,10 +33,11 @@ This MCP server provides 25 tools across 7 categories:
 - `create_virtual_account` - Create virtual bank accounts for fiat deposits
 - `list_virtual_accounts` - List virtual accounts for a customer
 - `update_virtual_account` - Update virtual account settings
-- `deactivate_virtual_account` - Deactivate a virtual account
-- `reactivate_virtual_account` - Reactivate a deactivated virtual account
 - `get_virtual_account_history` - Get activity history for a virtual account
 
+### Payment Methods
+- `validate_payment_method` - Check payout details against a currency's rules before creating a quote or transfer
+
 ### API Keys
 - `create_api_key` - Create a new API key
 - `list_api_keys` - List all API keys
@@ -46,9 +49,6 @@ This MCP server provides 25 tools across 7 categories:
 - `list_webhooks` - List all webhook subscriptions
 - `delete_webhook` - Delete a webhook subscription
 
-### Notifications
-- `send_verification_sms` - Send a KYC verification link to a customer via SMS (requires Twilio)
-
 ## Installation
 
 ```bash
@@ -69,10 +69,26 @@ The server requires the following environment variables:
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `STABLES_API_KEY` | Yes | Your Stables API key |
-| `STABLES_API_URL` | No | API base URL (default: `https://api.sandbox.stables.money`). Must use HTTPS. |
-| `TWILIO_ACCOUNT_SID` | No | Twilio Account SID (required for `send_verification_sms`) |
-| `TWILIO_AUTH_TOKEN` | No | Twilio Auth Token (required for `send_verification_sms`) |
-| `TWILIO_PHONE_NUMBER` | No | Twilio phone number to send from (required for `send_verification_sms`) |
+| `STABLES_API_URL` | No | API base URL. Defaults to the environment your key belongs to (see below). Must use HTTPS. |
+
+### Which environment you're talking to
+
+Stables keys carry their environment: `sti_test_…` is a sandbox key, `sti_live_…`
+is a production key, and the API refuses a key that arrives at the wrong
+environment. So you don't have to set a URL — leave `STABLES_API_URL` unset and
+the key decides:
+
+| Your key | Where requests go |
+|----------|-------------------|
+| `sti_test_…` | `https://api.sandbox.stables.money` |
+| `sti_live_…` | `https://api.stables.money` — **real money** |
+| `sti_local_…` or anything else | production, unless you set `STABLES_API_URL` |
+
+Setting `STABLES_API_URL` always wins, which is how you reach staging, dev or a
+local deployment.
+
+**Start with a sandbox key.** An agent holding a live key can move real money on
+your behalf; see [agent safety](https://docs.stables.money/get-started/getting-started/quickstart/building-with-ai/agent-safety).
 
 ## Usage
 
@@ -97,6 +113,29 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 Then restart Claude Desktop.
 
+### With Cursor, Codex, ChatGPT, or another MCP client
+
+Use the same command and environment variables in any MCP-compatible client:
+
+```json
+{
+  "mcpServers": {
+    "stables": {
+      "command": "npx",
+      "args": ["stables-mcp-server"],
+      "env": {
+        "STABLES_API_KEY": "your-api-key",
+        "STABLES_API_URL": "https://api.sandbox.stables.money"
+      }
+    }
+  }
+}
+```
+
+## Agent safety
+
+Stables is financial infrastructure. Agents should create quotes, prepare payment objects, and reconcile webhooks, but should require explicit human approval before creating transfers or other money movement. Check customer KYC/KYB status and entitlements before transactional actions, and treat sanctions, unsupported jurisdiction, verification, or compliance failures as hard stops.
+
 ### With MCP Inspector (for testing)
 
 ```bash
@@ -118,7 +157,7 @@ STABLES_API_KEY=your-api-key node build/index.js
 
 ### Creating a customer and getting a quote
 
-**User:** "Create a customer for john@example.com and get a quote to convert 1000 USDC to EUR"
+**User:** "Create a customer for john@example.com and get a quote to convert 1000 USDT to EUR"
 
 **AI (using MCP tools):**
 1. Calls `create_customer` with email and type
@@ -179,7 +218,7 @@ stables-mcp-server/
 │       ├── virtual-accounts.ts # Virtual account tools (6)
 │       ├── api-keys.ts       # API key tools (4)
 │       ├── webhooks.ts       # Webhook tools (3)
-│       └── notifications.ts  # Notification tools (1)
+│       └── payment-methods.ts # Payment method validation (1)
 ├── package.json
 ├── tsconfig.json
 ├── vitest.config.ts
@@ -336,22 +375,6 @@ Update virtual account settings.
 | virtualAccountId | string | Yes | Virtual account ID |
 | depositHandlingMode | string | Yes | New deposit handling mode |
 
-#### deactivate_virtual_account
-Deactivate a virtual account to prevent new deposits.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| customerId | string | Yes | Customer ID |
-| virtualAccountId | string | Yes | Virtual account ID |
-
-#### reactivate_virtual_account
-Reactivate a previously deactivated virtual account.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| customerId | string | Yes | Customer ID |
-| virtualAccountId | string | Yes | Virtual account ID |
-
 #### get_virtual_account_history
 Get activity history for a virtual account.
 
@@ -429,18 +452,6 @@ Delete a webhook subscription.
 |-----------|------|----------|-------------|
 | webhookId | string | Yes | Webhook subscription ID |
 
-### Notification Tools
-
-#### send_verification_sms
-Send a KYC verification link to a customer via SMS. Requires Twilio environment variables.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| customerId | string | Yes | Customer ID to send verification to |
-| phone | string | No | Override phone number (uses customer's phone if not provided) |
-| botName | string | No | Name of the assistant sending the message |
-| verificationLinkTtlSecs | number | No | Verification link expiry in seconds (default: 1800) |
-
 ## Security
 
 - API keys are only read from environment variables

package/build/index.js

@@ -32,7 +32,7 @@ import { registerTransferTools } from "./tools/transfers.js";
 import { registerVirtualAccountTools } from "./tools/virtual-accounts.js";
 import { registerApiKeyTools } from "./tools/api-keys.js";
 import { registerWebhookTools } from "./tools/webhooks.js";
-import { registerNotificationTools } from "./tools/notifications.js";
+import { registerPaymentMethodTools } from "./tools/payment-methods.js";
 // Validate environment
 const apiKey = process.env.STABLES_API_KEY;
 if (!apiKey) {
@@ -43,7 +43,7 @@ if (!apiKey) {
 // Create the MCP server
 const server = new McpServer({
     name: "stables-mcp-server",
-    version: "1.2.0",
+    version: "2.0.0",
     description: "Stables fiat-to-crypto API for AI agents - manage customers, quotes, transfers, and virtual accounts",
 });
 // Create the Stables API client
@@ -55,7 +55,7 @@ registerTransferTools(server, stablesClient);
 registerVirtualAccountTools(server, stablesClient);
 registerApiKeyTools(server, stablesClient);
 registerWebhookTools(server, stablesClient);
-registerNotificationTools(server, stablesClient);
+registerPaymentMethodTools(server, stablesClient);
 // Start the server with STDIO transport
 async function main() {
     const transport = new StdioServerTransport();

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AAErE,uBAAuB;AACvB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;AAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;IACZ,sCAAsC;IACtC,OAAO,CAAC,KAAK,CAAC,yDAAyD,CAAC,CAAC;IACzE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,wBAAwB;AACxB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,oBAAoB;IAC1B,OAAO,EAAE,OAAO;IAChB,WAAW,EAAE,sGAAsG;CACpH,CAAC,CAAC;AAEH,gCAAgC;AAChC,MAAM,aAAa,GAAG,mBAAmB,EAAE,CAAC;AAE5C,qBAAqB;AACrB,qBAAqB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAC7C,kBAAkB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAC1C,qBAAqB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAC7C,2BAA2B,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AACnD,mBAAmB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAC3C,oBAAoB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAC5C,yBAAyB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAEjD,wCAAwC;AACxC,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,sCAAsC;IACtC,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;IAChD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AAExE,uBAAuB;AACvB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;AAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;IACZ,sCAAsC;IACtC,OAAO,CAAC,KAAK,CAAC,yDAAyD,CAAC,CAAC;IACzE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,wBAAwB;AACxB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,oBAAoB;IAC1B,OAAO,EAAE,OAAO;IAChB,WAAW,EACT,sGAAsG;CACzG,CAAC,CAAC;AAEH,gCAAgC;AAChC,MAAM,aAAa,GAAG,mBAAmB,EAAE,CAAC;AAE5C,qBAAqB;AACrB,qBAAqB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAC7C,kBAAkB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAC1C,qBAAqB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAC7C,2BAA2B,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AACnD,mBAAmB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAC3C,oBAAoB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAC5C,0BAA0B,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAElD,wCAAwC;AACxC,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,sCAAsC;IACtC,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;IAChD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/build/lib/stables-client.d.ts

@@ -8,92 +8,117 @@ export declare class StablesApiError extends Error {
     readonly errorBody?: unknown | undefined;
     constructor(message: string, statusCode: number, endpoint: string, errorBody?: unknown | undefined);
 }
-export type CustomerType = "CUSTOMER_TYPE_INDIVIDUAL" | "CUSTOMER_TYPE_BUSINESS";
-export type VerificationStatus = "VERIFICATION_IN_PROGRESS" | "VERIFICATION_APPROVED" | "VERIFICATION_REJECTED";
-export type VerificationLevel = "KYC_LEVEL_0" | "KYC_LEVEL_1" | "KYC_LEVEL_2" | "BASE_BUSINESS" | "INDIVIDUAL_BASE" | "BUSINESS_BASE" | "INDIVIDUAL_ENHANCED";
+export type CustomerType = "individual" | "business";
+export type VerificationStatus = "in_progress" | "approved" | "rejected" | "not_started";
+export type VerificationLevel = "individual_base" | "individual_enhanced" | "business_base" | "base_business";
 export interface VerificationLevelResponse {
     level: VerificationLevel;
     status: VerificationStatus;
+    sub_status?: string[];
+    details?: unknown[];
 }
+/** The five feature entitlements the API accepts. */
+export type EntitlementId = "base_payout" | "virtual_account" | "eur_virtual_account" | "usd_virtual_account" | "aed_local";
 export interface Entitlement {
     name: string;
-    status: "ENTITLEMENT_STATUS_SUBMITTED" | "ENTITLEMENT_STATUS_IN_PROGRESS" | "ENTITLEMENT_STATUS_APPROVED" | "ENTITLEMENT_STATUS_REJECTED";
+    status: "submitted" | "pending" | "in_progress" | "approved" | "rejected";
 }
 export interface CustomerAddress {
     line1: string;
     line2?: string;
     city: string;
     state?: string;
-    postalCode?: string;
+    postal_code?: string;
     country: string;
 }
 export interface Customer {
-    customerId: string;
-    externalCustomerId: string;
-    customerType: CustomerType;
+    customer_id: string;
+    external_customer_id?: string;
+    customer_type: CustomerType;
     email: string;
     phone?: string;
-    firstName?: string;
-    lastName?: string;
-    companyName?: string;
+    first_name?: string;
+    last_name?: string;
+    company_name?: string;
+    status?: string;
+    compliance_lock?: boolean;
     entitlements?: Entitlement[];
-    createdAt: string;
-    updatedAt: string;
-    verificationLevels: VerificationLevelResponse[];
+    created_at: string;
+    updated_at: string;
+    verification_levels?: VerificationLevelResponse[];
     metadata?: Record<string, string>;
 }
 export interface CreateIndividualCustomerRequest {
-    externalCustomerId: string;
-    customerType: "CUSTOMER_TYPE_INDIVIDUAL";
-    email?: string;
-    firstName?: string;
-    lastName?: string;
-    middleName?: string;
+    customer_type: "individual";
+    /** Required — the API rejects a customer without one. */
+    email: string;
+    external_customer_id?: string;
+    first_name?: string;
+    last_name?: string;
+    middle_name?: string;
     phone?: string;
     dob?: string;
     nationality?: string;
+    tax_id_number?: string;
     address?: CustomerAddress;
-    entitlements?: string[];
+    entitlements?: EntitlementId[];
     metadata?: Record<string, string>;
 }
 export interface CreateBusinessCustomerRequest {
-    externalCustomerId: string;
-    customerType: "CUSTOMER_TYPE_BUSINESS";
-    email?: string;
+    customer_type: "business";
+    email: string;
+    company_name: string;
+    external_customer_id?: string;
     phone?: string;
-    companyName: string;
     country?: string;
-    registrationNumber?: string;
-    legalAddress?: CustomerAddress;
-    incorporatedOn?: string;
+    registration_number?: string;
+    legal_address?: CustomerAddress;
+    postal_address?: CustomerAddress;
+    incorporated_on?: string;
     type?: string;
-    taxId?: string;
-    registrationLocation?: string;
+    tax_id?: string;
+    registration_location?: string;
     website?: string;
-    postalAddress?: CustomerAddress;
-    alternativeNames?: string[];
-    describeBusiness?: string;
-    conductMoneyServices?: boolean;
-    describeMoneyServices?: string;
-    describeComplianceControls?: string;
-    accountPurpose?: string;
-    accountPurposeOther?: string;
-    isYourBusinessADao?: boolean;
-    industrySelection?: string;
-    mainSourceOfFunds?: string;
-    sourceOfFunds?: string;
-    sourceOfFundsDescription?: string;
-    expectedAnnualRevenue?: string;
-    expectedMonthlyPayments?: string;
-    doesYourBusinessEngageInHighRiskActivities?: "yes" | "no";
-    highRiskActivities?: string[];
-    operateInProhibitedCountry?: boolean;
-    acceptTerms?: boolean;
-    howDidYouComeAcrossStables?: string;
-    entitlements?: string[];
+    alternative_names?: string[];
+    describe_business?: string;
+    conduct_money_services?: boolean;
+    describe_money_services?: string;
+    describe_compliance_controls?: string;
+    account_purpose?: string;
+    account_purpose_other?: string;
+    is_your_business_a_dao?: boolean;
+    industry_selection?: string;
+    main_source_of_funds?: string;
+    source_of_funds?: string;
+    source_of_funds_description?: string;
+    expected_annual_revenue?: string;
+    expected_monthly_payments?: string;
+    does_your_business_engage_in_high_risk_activities?: "yes" | "no";
+    high_risk_activities?: string[];
+    operate_in_prohibited_country?: boolean;
+    accept_terms?: boolean;
+    how_did_you_come_across_stables?: string;
+    entitlements?: EntitlementId[];
     metadata?: Record<string, string>;
 }
 export type CreateCustomerRequest = CreateIndividualCustomerRequest | CreateBusinessCustomerRequest;
+/**
+ * Every field optional, so an unknown key is not an error — it is simply
+ * dropped. Sending camelCase here parsed to an empty object and returned 200
+ * having changed nothing.
+ */
+export interface UpdateCustomerRequest {
+    email?: string;
+    phone?: string;
+    first_name?: string;
+    last_name?: string;
+    middle_name?: string;
+    dob?: string;
+    nationality?: string;
+    company_name?: string;
+    entitlements?: EntitlementId[];
+    metadata?: Record<string, string>;
+}
 export interface ListCustomersResponse {
     customers: Customer[];
 }
@@ -108,64 +133,105 @@ export interface GenerateVerificationLinkRequest {
     redirect?: VerificationRedirect;
 }
 export interface GenerateVerificationLinkResponse {
-    customerId: string;
-    kycLink: string;
-}
-export type TransferType = "TRANSFER_TYPE_OFFRAMP" | "TRANSFER_TYPE_ONRAMP";
-export type TransferStatus = "CREATED" | "COMPLIANCE_HOLD" | "AWAITING_FUNDS_COLLECTION" | "FUNDS_COLLECTED" | "PAYMENT_SUBMITTED" | "PAYMENT_PROCESSED" | "COMPLETED" | "FAILED" | "CANCELLED" | "EXPIRED";
-export interface BankCodes {
-    swiftCode?: string;
-    bicCode?: string;
-    ifscCode?: string;
-    abaCode?: string;
-    sortCode?: string;
-    branchCode?: string;
-    bsbCode?: string;
-    bankCode?: string;
-    cnaps?: string;
+    customer_id: string;
+    kyc_link: string;
 }
-export interface BankTransferDetails {
-    accountHolderName: string;
-    accountNumber?: string;
-    iban?: string;
-    bankName: string;
-    bankCountry: string;
+export type TransferType = "offramp" | "onramp";
+export type TransferStatus = "created" | "compliance_hold" | "awaiting_funds_collection" | "funds_collected" | "in_progress" | "payment_submitted" | "payment_processed" | "completed" | "failed" | "cancelled" | "expired" | "unknown";
+/** ISO 3166-1 alpha-2, lowercase, per AddressApiSchema. */
+export interface BeneficiaryAddress {
+    street: string;
+    city: string;
+    state: string;
+    postal_code: string;
+    country: string;
+}
+/**
+ * Bank payout destination. Bank codes are flat here — the nested `bankCodes`
+ * object the API used to take is gone.
+ */
+export interface BankTransferDestination {
+    type: "bank";
+    account_holder_name: string;
+    bank_name: string;
+    bank_country: string;
     currency: string;
-    accountType?: "savings" | "checking" | "payment";
-    branchName?: string;
-    bankCodes?: BankCodes;
+    /**
+     * Required for payouts in AED, CAD, EUR, GBP, MXN and USD, together with
+     * `address`, and `date_of_birth` when this is "individual".
+     */
+    recipient_type?: "individual" | "business";
+    date_of_birth?: string;
+    address?: BeneficiaryAddress;
+    account_number?: string;
+    iban?: string;
+    pay_id?: string;
+    pay_id_type?: "email" | "phone" | "abn" | "org_id";
+    account_type?: "savings" | "checking" | "payment";
+    branch_name?: string;
+    swift_code?: string;
+    bic_code?: string;
+    ifsc_code?: string;
+    aba_code?: string;
+    sort_code?: string;
+    branch_code?: string;
+    bsb_code?: string;
+    bank_code?: string;
+    cnaps?: string;
+    name_in_local_language?: string;
+    national_identification_number?: string;
+}
+export interface PaymentMethodValidationError {
+    field?: string;
+    message: string;
+    code: "UNSUPPORTED_CURRENCY" | "UNSUPPORTED_PAYMENT_METHOD" | "INVALID_FIELDS";
 }
-export interface PaymentMethod {
-    bankTransfer: BankTransferDetails;
+export interface ValidatePaymentMethodResponse {
+    valid: boolean;
+    errors?: PaymentMethodValidationError[];
 }
-export interface CollectionInstructions {
-    walletAddress: string;
+export interface CryptoTransferDestination {
+    type: "crypto";
     currency: string;
     network: string;
-    amount: string;
+    address: string;
+}
+export type TransferDestination = BankTransferDestination | CryptoTransferDestination;
+/** Where the customer sends funds for an offramp. Was `collectionInstructions`. */
+export interface SourceDepositInstructions {
+    wallet_address?: string;
+    currency?: string;
+    network?: string;
+    amount?: string;
+    [key: string]: unknown;
 }
 export interface Transfer {
     id: string;
-    tenantId: string;
-    customerId: string;
-    quoteId: string;
+    tenant_id: string;
+    customer_id: string;
+    quote_id: string;
     type: TransferType;
     status: TransferStatus;
-    createdAt: string;
-    updatedAt: string;
-    collectionInstructions?: CollectionInstructions;
+    origin?: "api" | "otc";
+    created_at: string;
+    updated_at: string;
+    source_deposit_instructions?: SourceDepositInstructions;
+    destination?: TransferDestination;
+    fees?: Record<string, unknown>;
+    exchange_rate?: string;
     metadata?: Record<string, string>;
 }
 export interface CreateTransferRequest {
-    customerId: string;
-    quoteId: string;
-    paymentMethod?: PaymentMethod;
+    customer_id: string;
+    quote_id: string;
+    destination: TransferDestination;
+    purpose_code?: string;
     metadata?: Record<string, string>;
 }
 export interface ListTransfersResponse {
     transfers: Transfer[];
     page: {
-        nextPageToken: string;
+        next_page_token: string;
         total: number;
     };
 }
@@ -235,56 +301,62 @@ export interface VirtualAccountHistoryEvent {
     deposit_id?: string;
     created_at: string;
 }
-export type QuoteStatus = "QUOTE_STATUS_ACTIVE" | "QUOTE_STATUS_EXPIRED" | "QUOTE_STATUS_USED" | "QUOTE_STATUS_CANCELLED";
-export type PaymentMethodType = "SWIFT" | "LOCAL";
-export type QuoteNetwork = "ethereum" | "polygon";
+export type QuoteStatus = "active" | "expired" | "used" | "cancelled" | "preview";
+/**
+ * Live blockchain networks. The client used to allow only ethereum and polygon,
+ * which blocked six networks the platform supports.
+ */
+export type QuoteNetwork = "arbitrum" | "avalanche" | "base" | "ethereum" | "optimism" | "polygon" | "solana" | "tron";
 export interface CurrencyAmount {
     currency: string;
     amount: string;
     network?: string;
 }
 export interface FeeBreakdown {
-    fxFee: CurrencyAmount;
-    integratorFee: CurrencyAmount;
-    platformFee: CurrencyAmount;
-    paymentMethodFee: CurrencyAmount;
-    networkFee?: CurrencyAmount;
-    totalFee: CurrencyAmount;
+    fx_fee?: CurrencyAmount;
+    integrator_fee?: CurrencyAmount;
+    platform_fee?: CurrencyAmount;
+    payment_method_fee?: CurrencyAmount;
+    network_fee?: CurrencyAmount;
+    total_fee: CurrencyAmount;
 }
 export interface Quote {
-    quoteId: string;
-    from: CurrencyAmount;
-    to: {
-        currency: string;
-        amount: string;
-        network?: string;
-        paymentMethodType: PaymentMethodType;
-    };
+    quote_id: string;
+    source: CurrencyAmount;
+    destination: CurrencyAmount;
     fees: FeeBreakdown;
-    exchangeRate: number;
-    expiresAt: string;
-    createdAt: string;
+    exchange_rate: number;
+    expires_at: string;
+    created_at: string;
     status: QuoteStatus;
     metadata?: Record<string, string>;
 }
 export interface CreateQuoteRequest {
-    customerId?: string;
-    from: {
+    source: {
         currency: string;
-        network: QuoteNetwork;
+        /** Required for offramp (crypto source); omitted for onramp (fiat source). */
+        network?: string;
         amount: string;
     };
-    to: {
+    destination: {
         currency: string;
-        country: string;
-        network?: QuoteNetwork;
-        paymentMethodType: PaymentMethodType;
+        /** Required for offramp. */
+        country?: string;
+        /** Offramp: payment network (swift/bank). Onramp: blockchain network. */
+        network?: string;
+        /** Required for onramp. */
+        address?: string;
     };
+    /** Price without persisting the quote. Returns status "preview". */
+    preview?: boolean;
     metadata?: Record<string, string>;
 }
-export interface CreateQuoteResponse {
-    quote: Quote;
-}
+/**
+ * The quote endpoints return the quote directly. They used to wrap it in
+ * `{ quote }`, and reading the wrapper gave undefined and then a TypeError on
+ * the first field access.
+ */
+export type CreateQuoteResponse = Quote;
 export interface ApiKey {
     apiKeyId: string;
     tenantId: string;
@@ -331,7 +403,7 @@ export declare class StablesApiClient {
     listCustomers(): Promise<ListCustomersResponse>;
     getCustomer(customerId: string): Promise<Customer>;
     createCustomer(data: CreateCustomerRequest): Promise<Customer>;
-    updateCustomer(customerId: string, data: Record<string, unknown>): Promise<Customer>;
+    updateCustomer(customerId: string, data: UpdateCustomerRequest): Promise<Customer>;
     updateMetadata(customerId: string, metadata: Record<string, string>): Promise<void>;
     generateVerificationLink(customerId: string, options?: GenerateVerificationLinkRequest): Promise<GenerateVerificationLinkResponse>;
     listAllVirtualAccounts(params?: {
@@ -346,8 +418,6 @@ export declare class StablesApiClient {
     updateVirtualAccount(customerId: string, virtualAccountId: string, data: {
         deposit_handling_mode?: DepositHandlingMode;
     }): Promise<VirtualAccount>;
-    deactivateVirtualAccount(customerId: string, virtualAccountId: string): Promise<VirtualAccount>;
-    reactivateVirtualAccount(customerId: string, virtualAccountId: string): Promise<VirtualAccount>;
     getVirtualAccountHistory(customerId: string, virtualAccountId: string, params?: {
         limit?: number;
         depositId?: string;
@@ -367,9 +437,7 @@ export declare class StablesApiClient {
     getTransfer(transferId: string): Promise<Transfer>;
     createTransfer(data: CreateTransferRequest): Promise<Transfer>;
     createQuote(data: CreateQuoteRequest): Promise<CreateQuoteResponse>;
-    getQuote(quoteId: string): Promise<{
-        quote: Quote;
-    }>;
+    getQuote(quoteId: string): Promise<Quote>;
     listApiKeys(params?: {
         pageSize?: number;
         pageToken?: string;
@@ -381,6 +449,12 @@ export declare class StablesApiClient {
         apiKey: ApiKey;
     }>;
     revokeApiKey(apiKeyId: string): Promise<Record<string, never>>;
+    /**
+     * Check payout details against the per-currency rules without creating
+     * anything. Always answers 200 — the outcome is in the body — so an agent can
+     * discover what a corridor demands before spending a short-lived quote.
+     */
+    validatePaymentMethod(network: string, destination: BankTransferDestination): Promise<ValidatePaymentMethodResponse>;
     listWebhooks(): Promise<{
         subscriptions: WebhookSubscription[];
     }>;
@@ -389,5 +463,19 @@ export declare class StablesApiClient {
     }>;
     deleteWebhook(subscriptionId: string): Promise<Record<string, never>>;
 }
+/**
+ * Which environment a key belongs to, read from the key itself.
+ *
+ * Stables keys are `sti_<env>_<prefix>_<secret>` with env one of local, test or
+ * live, and the api service refuses a key whose segment does not match the
+ * deployment it arrives at. So the key already decides the environment, and a
+ * default base URL is only ever a guess at something we can read.
+ *
+ * Guessing had a cost in both directions: the code defaulted to production while
+ * the README promised sandbox, so a test key with no STABLES_API_URL set failed
+ * authentication against production and read as "my key is invalid" when the key
+ * was fine.
+ */
+export declare function apiUrlForKey(apiKey: string): string | null;
 export declare function createStablesClient(): StablesApiClient;
 //# sourceMappingURL=stables-client.d.ts.map