stables-mcp-server 2.0.0 → 2.2.0

package/README.md

@@ -10,7 +10,7 @@ MCP (Model Context Protocol) is an open standard that provides a standardized wa
 
 ## Features
 
-This MCP server provides 23 tools across 7 categories:
+This MCP server provides 26 tools across 7 categories:
 
 ### Customer Management
 - `create_customer` - Create individual or business customers
@@ -33,10 +33,12 @@ This MCP server provides 23 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
-- `get_virtual_account_history` - Get activity history for a virtual account
+- `get_virtual_account_history` - Get deposits and their payouts for a payment route
+- `update_route_destination` - Change the payout wallet on an existing route
 
-### Payment Methods
-- `validate_payment_method` - Check payout details against a currency's rules before creating a quote or transfer
+### Sandbox
+- `simulate_route_deposit` - Simulate a fiat deposit into a payment route (sandbox only)
+- `simulate_transfer_deposit` - Simulate the inbound crypto an off-ramp transfer awaits (sandbox only)
 
 ### API Keys
 - `create_api_key` - Create a new API key
@@ -48,8 +50,56 @@ This MCP server provides 23 tools across 7 categories:
 - `create_webhook` - Subscribe to events via webhook
 - `list_webhooks` - List all webhook subscriptions
 - `delete_webhook` - Delete a webhook subscription
+- `list_webhook_deliveries` - Recent delivery attempts, status codes and retry state
 
-## Installation
+## Hosted server (recommended)
+
+The server runs as a hosted service, so there is nothing to install. Point your MCP client at:
+
+```
+https://mcp.stables.money/mcp
+```
+
+and send your Stables API key as a bearer token. The key you get during onboarding is all you need: a `sti_test_…` key reaches sandbox, a `sti_live_…` key reaches production and moves real money. The hosted server keeps no credentials of its own; every request carries yours.
+
+### Claude Code
+
+```bash
+claude mcp add --transport http stables https://mcp.stables.money/mcp --header "Authorization: Bearer ${STABLES_API_KEY}"
+```
+
+### Cursor, VS Code, Windsurf and other clients with a `url` field
+
+```json
+{
+  "mcpServers": {
+    "stables": {
+      "url": "https://mcp.stables.money/mcp",
+      "headers": {
+        "Authorization": "Bearer sti_test_..."
+      }
+    }
+  }
+}
+```
+
+### Codex
+
+```toml
+[mcp_servers.stables]
+url = "https://mcp.stables.money/mcp"
+bearer_token_env_var = "STABLES_API_KEY"
+```
+
+### Claude.ai and ChatGPT
+
+Claude.ai custom connectors and ChatGPT connectors sign in with OAuth rather than a fixed key. OAuth sign-in for the hosted server is in progress; until it ships, use one of the clients above, or run the server locally as described below.
+
+## Running locally
+
+The same server also runs as a local process over stdio, which is what `npx stables-mcp-server` does. Use this for a `sti_local_…` key against your own deployment, or when your client cannot reach the internet.
+
+### Installation
 
 ```bash
 # Install from npm
@@ -62,7 +112,7 @@ npm install
 npm run build
 ```
 
-## Configuration
+### Configuration
 
 The server requires the following environment variables:
 
@@ -90,9 +140,9 @@ 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
+### Usage
 
-### With Claude Desktop
+#### With Claude Desktop
 
 Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
@@ -113,7 +163,7 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 Then restart Claude Desktop.
 
-### With Cursor, Codex, ChatGPT, or another MCP client
+#### With Cursor, Codex, ChatGPT, or another MCP client
 
 Use the same command and environment variables in any MCP-compatible client:
 
@@ -161,7 +211,7 @@ STABLES_API_KEY=your-api-key node build/index.js
 
 **AI (using MCP tools):**
 1. Calls `create_customer` with email and type
-2. Calls `create_quote` with USDC, amount, EUR destination, network, country, and payment method
+2. Calls `create_quote` with source USDT + network, destination EUR + country, and `destinationNetwork` (`swift` or `bank`)
 3. Returns customer details and quote information
 
 ### Checking transfer status
@@ -169,16 +219,24 @@ STABLES_API_KEY=your-api-key node build/index.js
 **User:** "What's the status of all my pending transfers?"
 
 **AI (using MCP tools):**
-1. Calls `list_transfers` with `status=PENDING`
-2. Returns formatted list of pending transfers
+1. Calls `list_transfers` with `status=created` or `status=in_progress` (statuses are lowercase)
+2. Returns a formatted list of in-flight transfers
 
 ### Setting up auto-payout
 
-**User:** "Create a virtual USD account for customer abc123 that auto-pays to my Polygon USDC wallet 0x..."
+**User:** "Create a payment route for customer abc123 that pays AUD deposits out to my Polygon USDT wallet 0x..."
+
+**AI (using MCP tools):**
+1. Calls `create_virtual_account` with the customer ID, AUD source currency, and the Polygon destination (the payout address is mandatory)
+2. Returns the deposit instructions to share with the customer
+
+### Paying out to a European beneficiary
+
+**User:** "Pay 500 EUR to this German bank account"
 
 **AI (using MCP tools):**
-1. Calls `create_virtual_account` with customer ID, USD currency, and Polygon destination
-2. Returns virtual account details with deposit instructions
+1. Collects the extra beneficiary details EUR requires — `recipientType`, a full address, and `dateOfBirth` for individuals — before doing anything else
+2. Calls `create_quote`, then `create_transfer` once a human approves
 
 ## Development
 
@@ -218,7 +276,7 @@ stables-mcp-server/
 │       ├── virtual-accounts.ts # Virtual account tools (6)
 │       ├── api-keys.ts       # API key tools (4)
 │       ├── webhooks.ts       # Webhook tools (3)
-│       └── payment-methods.ts # Payment method validation (1)
+│       └── sandbox.ts        # Sandbox deposit simulation (2)
 ├── package.json
 ├── tsconfig.json
 ├── vitest.config.ts

package/build/http/auth.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Per-request authentication for the hosted server.
+ *
+ * The hosted service holds no credentials of its own. Each request carries the
+ * caller's Stables API key, and the key alone decides which environment the
+ * request reaches: `sti_test_…` goes to sandbox, `sti_live_…` to production.
+ * That is the same rule the stdio server applies to STABLES_API_KEY, so a key
+ * issued during onboarding works here with no further setup.
+ */
+import { StablesApiClient } from "../lib/stables-client.js";
+export declare const BEARER_CHALLENGE: string;
+export type AuthResult = {
+    ok: true;
+    client: StablesApiClient;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Read the API key off a request. The Authorization header is the standard
+ * place; X-Api-Key is accepted because the Stables API itself accepts it and
+ * some MCP clients only let users set that header.
+ */
+export declare function extractApiKey(headers: Headers): string | null;
+export declare function authenticate(headers: Headers): AuthResult;
+//# sourceMappingURL=auth.d.ts.map

package/build/http/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/http/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,gBAAgB,EAAgB,MAAM,0BAA0B,CAAC;AAE1E,eAAO,MAAM,gBAAgB,QAEiH,CAAC;AAE/I,MAAM,MAAM,UAAU,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhG;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAS7D;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,UAAU,CAiBzD"}

package/build/http/auth.js

@@ -0,0 +1,47 @@
+/**
+ * Per-request authentication for the hosted server.
+ *
+ * The hosted service holds no credentials of its own. Each request carries the
+ * caller's Stables API key, and the key alone decides which environment the
+ * request reaches: `sti_test_…` goes to sandbox, `sti_live_…` to production.
+ * That is the same rule the stdio server applies to STABLES_API_KEY, so a key
+ * issued during onboarding works here with no further setup.
+ */
+import { StablesApiClient, apiUrlForKey } from "../lib/stables-client.js";
+export const BEARER_CHALLENGE = 'Bearer realm="stables", error="invalid_token", ' +
+    'error_description="Send your Stables API key as a bearer token: Authorization: Bearer sti_test_... (sandbox) or sti_live_... (production)"';
+/**
+ * Read the API key off a request. The Authorization header is the standard
+ * place; X-Api-Key is accepted because the Stables API itself accepts it and
+ * some MCP clients only let users set that header.
+ */
+export function extractApiKey(headers) {
+    const authorization = headers.get("authorization");
+    if (authorization) {
+        const match = authorization.match(/^Bearer\s+(.+)$/i);
+        if (match)
+            return match[1].trim();
+    }
+    const apiKeyHeader = headers.get("x-api-key");
+    if (apiKeyHeader)
+        return apiKeyHeader.trim();
+    return null;
+}
+export function authenticate(headers) {
+    const apiKey = extractApiKey(headers);
+    if (!apiKey) {
+        return { ok: false, reason: "Missing API key" };
+    }
+    const baseUrl = apiUrlForKey(apiKey);
+    if (!baseUrl) {
+        // A `sti_local_…` key or an unrecognised shape has no environment we can
+        // route to. The stdio server lets STABLES_API_URL resolve that; the hosted
+        // one has no such channel, and guessing production would be wrong.
+        return {
+            ok: false,
+            reason: "Unrecognised API key. The hosted server accepts sti_test_… (sandbox) and sti_live_… (production) keys; for a local deployment run the server locally with STABLES_API_URL",
+        };
+    }
+    return { ok: true, client: new StablesApiClient(apiKey, baseUrl) };
+}
+//# sourceMappingURL=auth.js.map

package/build/http/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/http/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE1E,MAAM,CAAC,MAAM,gBAAgB,GAC3B,iDAAiD;IACjD,4IAA4I,CAAC;AAI/I;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACnD,IAAI,aAAa,EAAE,CAAC;QAClB,MAAM,KAAK,GAAG,aAAa,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;QACtD,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACpC,CAAC;IACD,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC9C,IAAI,YAAY;QAAE,OAAO,YAAY,CAAC,IAAI,EAAE,CAAC;IAC7C,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAgB;IAC3C,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACtC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAClD,CAAC;IACD,MAAM,OAAO,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACrC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,yEAAyE;QACzE,2EAA2E;QAC3E,mEAAmE;QACnE,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EACJ,2KAA2K;SAC9K,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;AACrE,CAAC"}

package/build/http/handler.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Web-standard HTTP handler for the hosted Stables MCP server.
+ *
+ * Works anywhere a `fetch`-style `Request` → `Response` function runs: a
+ * Cloudflare Worker, a Node process (see serve.ts), or any other runtime with
+ * the web platform APIs. The server is stateless: each request authenticates
+ * from its own headers and gets a fresh MCP server bound to that key, so
+ * nothing about one caller survives to the next and no session store is
+ * needed.
+ */
+export declare const MCP_PATH = "/mcp";
+export declare function handleRequest(request: Request): Promise<Response>;
+//# sourceMappingURL=handler.d.ts.map

package/build/http/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/http/handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,eAAO,MAAM,QAAQ,SAAS,CAAC;AAgF/B,wBAAsB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAyBvE"}

package/build/http/handler.js

@@ -0,0 +1,102 @@
+/**
+ * Web-standard HTTP handler for the hosted Stables MCP server.
+ *
+ * Works anywhere a `fetch`-style `Request` → `Response` function runs: a
+ * Cloudflare Worker, a Node process (see serve.ts), or any other runtime with
+ * the web platform APIs. The server is stateless: each request authenticates
+ * from its own headers and gets a fresh MCP server bound to that key, so
+ * nothing about one caller survives to the next and no session store is
+ * needed.
+ */
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { SERVER_NAME, SERVER_VERSION, createStablesMcpServer } from "../server.js";
+import { BEARER_CHALLENGE, authenticate } from "./auth.js";
+export const MCP_PATH = "/mcp";
+const CORS_HEADERS = {
+    "access-control-allow-origin": "*",
+    "access-control-allow-methods": "GET, POST, DELETE, OPTIONS",
+    "access-control-allow-headers": "authorization, x-api-key, content-type, accept, mcp-session-id, mcp-protocol-version, last-event-id",
+    "access-control-expose-headers": "mcp-session-id, mcp-protocol-version",
+    "access-control-max-age": "86400",
+};
+function withCors(response) {
+    const headers = new Headers(response.headers);
+    for (const [name, value] of Object.entries(CORS_HEADERS))
+        headers.set(name, value);
+    return new Response(response.body, { status: response.status, headers });
+}
+function json(body, status = 200, extraHeaders = {}) {
+    return new Response(JSON.stringify(body, null, 2), {
+        status,
+        headers: { "content-type": "application/json", ...extraHeaders },
+    });
+}
+function unauthorized(reason) {
+    return json({
+        error: "unauthorized",
+        message: reason,
+        hint: "Authorization: Bearer <your Stables API key>. A sti_test_ key reaches sandbox, a sti_live_ key reaches production and moves real money.",
+        docs: "https://docs.stables.money/get-started/getting-started/quickstart/building-with-ai",
+    }, 401, { "www-authenticate": BEARER_CHALLENGE });
+}
+function describe(origin) {
+    return json({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+        description: "Hosted MCP server for the Stables fiat-to-crypto API. Connect any MCP client to the endpoint below with your Stables API key as a bearer token.",
+        endpoint: `${origin}${MCP_PATH}`,
+        transport: "streamable-http",
+        authentication: {
+            type: "bearer",
+            header: "Authorization: Bearer <api key>",
+            environments: {
+                "sti_test_…": "sandbox (https://api.sandbox.stables.money)",
+                "sti_live_…": "production (https://api.stables.money)",
+            },
+        },
+        docs: "https://docs.stables.money/get-started/getting-started/quickstart/building-with-ai",
+        source: "https://github.com/stables-money/mcp-server",
+    });
+}
+async function handleMcp(request) {
+    const auth = authenticate(request.headers);
+    if (!auth.ok)
+        return unauthorized(auth.reason);
+    const server = createStablesMcpServer(auth.client);
+    const transport = new WebStandardStreamableHTTPServerTransport({
+        // Stateless: no session ids, so any instance (or any edge location) can
+        // answer any request, and a client never has to re-initialise after a
+        // deploy. Each tool call is one round trip to the Stables API anyway.
+        sessionIdGenerator: undefined,
+        // Plain JSON bodies rather than SSE frames: nothing here streams partial
+        // results, and JSON is the easier contract for clients and for debugging.
+        enableJsonResponse: true,
+    });
+    await server.connect(transport);
+    try {
+        return await transport.handleRequest(request);
+    }
+    finally {
+        await transport.close();
+    }
+}
+export async function handleRequest(request) {
+    const url = new URL(request.url);
+    if (request.method === "OPTIONS") {
+        return withCors(new Response(null, { status: 204 }));
+    }
+    if (url.pathname === "/" || url.pathname === "") {
+        return withCors(describe(url.origin));
+    }
+    if (url.pathname === "/health") {
+        return withCors(json({ status: "ok", version: SERVER_VERSION }));
+    }
+    if (url.pathname === MCP_PATH || url.pathname === `${MCP_PATH}/`) {
+        return withCors(await handleMcp(request));
+    }
+    return withCors(json({
+        error: "not_found",
+        message: `Nothing at ${url.pathname}. The MCP endpoint is ${MCP_PATH}.`,
+    }, 404));
+}
+//# sourceMappingURL=handler.js.map

package/build/http/handler.js.map

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

package/build/index.d.ts

@@ -1,27 +1,14 @@
 #!/usr/bin/env node
 /**
- * Stables MCP Server
+ * Stables MCP Server — stdio entry point.
  *
- * This server exposes the Stables fiat-to-crypto API to AI agents via the
- * Model Context Protocol (MCP). It enables AI assistants to manage customers,
- * create quotes, execute transfers, and handle virtual accounts.
+ * This is what `npx stables-mcp-server` runs: a local process that speaks MCP
+ * over stdin/stdout and authenticates to the Stables API with the key in
+ * STABLES_API_KEY. The hosted service at https://mcp.stables.money/mcp exposes
+ * the same tools over HTTP without installing anything; see README.md.
  *
  * Usage:
  *   STABLES_API_KEY=your-key node build/index.js
- *
- * For Claude Desktop, add to ~/Library/Application Support/Claude/claude_desktop_config.json:
- *   {
- *     "mcpServers": {
- *       "stables": {
- *         "command": "node",
- *         "args": ["/path/to/stables-mcp-server/build/index.js"],
- *         "env": {
- *           "STABLES_API_KEY": "your-api-key",
- *           "STABLES_API_URL": "https://api.stables.money"
- *         }
- *       }
- *     }
- *   }
  */
 export {};
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;GAuBG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;GAUG"}

package/build/index.js

@@ -1,38 +1,18 @@
 #!/usr/bin/env node
 /**
- * Stables MCP Server
+ * Stables MCP Server — stdio entry point.
  *
- * This server exposes the Stables fiat-to-crypto API to AI agents via the
- * Model Context Protocol (MCP). It enables AI assistants to manage customers,
- * create quotes, execute transfers, and handle virtual accounts.
+ * This is what `npx stables-mcp-server` runs: a local process that speaks MCP
+ * over stdin/stdout and authenticates to the Stables API with the key in
+ * STABLES_API_KEY. The hosted service at https://mcp.stables.money/mcp exposes
+ * the same tools over HTTP without installing anything; see README.md.
  *
  * Usage:
  *   STABLES_API_KEY=your-key node build/index.js
- *
- * For Claude Desktop, add to ~/Library/Application Support/Claude/claude_desktop_config.json:
- *   {
- *     "mcpServers": {
- *       "stables": {
- *         "command": "node",
- *         "args": ["/path/to/stables-mcp-server/build/index.js"],
- *         "env": {
- *           "STABLES_API_KEY": "your-api-key",
- *           "STABLES_API_URL": "https://api.stables.money"
- *         }
- *       }
- *     }
- *   }
  */
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createStablesClient } from "./lib/stables-client.js";
-import { registerCustomerTools } from "./tools/customers.js";
-import { registerQuoteTools } from "./tools/quotes.js";
-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 { registerPaymentMethodTools } from "./tools/payment-methods.js";
+import { createStablesMcpServer } from "./server.js";
 // Validate environment
 const apiKey = process.env.STABLES_API_KEY;
 if (!apiKey) {
@@ -40,24 +20,8 @@ if (!apiKey) {
     console.error("Error: STABLES_API_KEY environment variable is required");
     process.exit(1);
 }
-// Create the MCP server
-const server = new McpServer({
-    name: "stables-mcp-server",
-    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
-const stablesClient = createStablesClient();
-// Register all tools
-registerCustomerTools(server, stablesClient);
-registerQuoteTools(server, stablesClient);
-registerTransferTools(server, stablesClient);
-registerVirtualAccountTools(server, stablesClient);
-registerApiKeyTools(server, stablesClient);
-registerWebhookTools(server, stablesClient);
-registerPaymentMethodTools(server, stablesClient);
-// Start the server with STDIO transport
 async function main() {
+    const server = createStablesMcpServer(createStablesClient());
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

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,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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAErD,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,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,sBAAsB,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAC7D,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

@@ -279,27 +279,94 @@ export interface VirtualAccount {
         last_deposit_at: string | null;
     };
 }
+/**
+ * `deposit_handling_mode` is deliberately absent — it is not part of the create
+ * schema (the server sets it, defaulting to auto_payout) and was being silently
+ * ignored. Change it afterwards with updateVirtualAccount.
+ */
 export interface CreateVirtualAccountRequest {
     source: {
         currency: string;
     };
-    deposit_handling_mode?: DepositHandlingMode;
+    /** Required for fiat_to_crypto, which is the default. */
     destination?: VirtualAccountDestination;
+    workflow_type?: "fiat_to_crypto" | "fiat_to_fiat";
+    developer_fee_percent?: string;
     metadata?: Record<string, string>;
 }
 export interface ListVirtualAccountsResponse {
     count: number;
     data: VirtualAccount[];
 }
+/**
+ * One deposit and its payout. The client previously described these as
+ * `{type, amount, currency}`, none of which exist, so every row rendered as
+ * "undefined: undefined undefined".
+ */
 export interface VirtualAccountHistoryEvent {
     id: string;
-    type: string;
-    customer_id: string;
     virtual_account_id: string;
-    amount: string;
-    currency: string;
+    deposit_amount?: string;
+    deposit_currency?: string;
     deposit_id?: string;
+    sender_name?: string;
+    sender_reference?: string;
+    handling_mode?: string;
+    payout_status?: string;
+    payout_amount?: string;
+    payout_currency?: string;
+    payout_network?: string;
+    payout_address?: string;
+    payout_transaction_hash?: string;
+    payout_completed_at?: string;
+    platform_fee_amount?: string;
+    platform_fee_currency?: string;
+    deposited_at?: string;
+    created_at?: string;
+}
+/** The envelope is `{data, has_more}` — there is no `count`. */
+export interface VirtualAccountHistoryResponse {
+    data: VirtualAccountHistoryEvent[];
+    has_more?: boolean;
+}
+/**
+ * A request for information: what a customer must supply before a held
+ * verification or payout can proceed. Compliance can raise one at any time, so
+ * an integration that never reads them will stall without knowing why.
+ */
+export interface Rfi {
+    rfi_id: string;
+    type: string;
+    status: string;
+    customer_id: string;
+    kyc_level?: string;
+    reasons?: unknown[];
+    requirements?: unknown[];
     created_at: string;
+    expires_at?: string;
+    resolved_at?: string;
+}
+export interface WebhookDelivery {
+    deliveryId: string;
+    subscriptionId?: string | null;
+    subscriptionName?: string | null;
+    subscriptionUrl?: string | null;
+    eventType: string;
+    status: "PENDING" | "SUCCESS" | "FAILED" | "RETRYING";
+    attemptCount: number;
+    lastAttemptAt?: string | null;
+    nextRetryAt?: string | null;
+    responseCode?: number | null;
+    createdAt?: string | null;
+}
+export interface SandboxDepositRequest {
+    amount: string;
+    scenario?: "create_only" | "completed" | "failed";
+    external_deposit_id?: string;
+    sender_name?: string;
+    sender_reference?: string;
+    failure_code?: string;
+    failure_message?: string;
 }
 export type QuoteStatus = "active" | "expired" | "used" | "cancelled" | "preview";
 /**
@@ -423,10 +490,7 @@ export declare class StablesApiClient {
         depositId?: string;
         startingAfter?: string;
         endingBefore?: string;
-    }): Promise<{
-        count: number;
-        data: VirtualAccountHistoryEvent[];
-    }>;
+    }): Promise<VirtualAccountHistoryResponse>;
     listTransfers(params?: {
         status?: string;
         type?: string;
@@ -455,6 +519,31 @@ export declare class StablesApiClient {
      * discover what a corridor demands before spending a short-lived quote.
      */
     validatePaymentMethod(network: string, destination: BankTransferDestination): Promise<ValidatePaymentMethodResponse>;
+    /** Replace the payout wallet on an existing payment route. */
+    updateVirtualAccountDestination(customerId: string, virtualAccountId: string, destination: VirtualAccountDestination): Promise<VirtualAccount>;
+    /** Compliance requests for information against a customer. */
+    listCustomerRfis(customerId: string): Promise<{
+        rfis: Rfi[];
+    }>;
+    getRfi(rfiId: string): Promise<Rfi>;
+    /** What verification the customer still owes. */
+    getKycCapabilities(customerId: string): Promise<Record<string, unknown>>;
+    listAvailableEntitlements(customerId: string): Promise<Record<string, unknown>>;
+    /**
+     * Sandbox only. Drives a deposit through the route or transfer so an agent can
+     * reach a terminal state in test, which is otherwise impossible without a real
+     * bank payment.
+     */
+    simulateVirtualAccountDeposit(customerId: string, virtualAccountId: string, data: SandboxDepositRequest): Promise<Record<string, unknown>>;
+    simulateTransferDeposit(transferId: string, data?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Recent webhook delivery attempts — the first place to look when events go missing. */
+    listWebhookDeliveries(params?: {
+        pageSize?: number;
+        status?: string;
+        eventType?: string;
+    }): Promise<{
+        deliveries: WebhookDelivery[];
+    }>;
     listWebhooks(): Promise<{
         subscriptions: WebhookSubscription[];
     }>;