@venlyfinance/settlement-mcp 0.1.1 → 0.2.0

package/dist/tools/read-tools.js

@@ -3,18 +3,7 @@
  */
 import { z } from "zod";
 import { reconcileByReferenceCode } from "../reconcile.js";
-/** Serialize a result as a text-content tool response. */
-function jsonResult(data) {
-    return {
-        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
-    };
-}
-function errorResult(message) {
-    return {
-        content: [{ type: "text", text: `Error: ${message}` }],
-        isError: true,
-    };
-}
+import { errorResult, jsonResult } from "../results.js";
 const READ_ONLY = {
     readOnlyHint: true,
     destructiveHint: false,
@@ -71,6 +60,23 @@ export function registerReadTools(server, client) {
             return errorResult(e.message);
         }
     });
+    server.registerTool("list_accounts", {
+        title: "List accounts",
+        description: "List Venly Finance accounts before creating duplicates (finance GET /accounts). Read-only.",
+        inputSchema: {
+            page: z.number().int().min(1).optional(),
+            size: z.number().int().min(1).max(200).optional(),
+        },
+        annotations: READ_ONLY,
+    }, async (params) => {
+        try {
+            const result = await client.listAccounts(params);
+            return jsonResult({ count: result.length, accounts: result });
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
     server.registerTool("get_account", {
         title: "Get account",
         description: "Fetch a settlement account (finance GET /accounts/{accountId}). Read-only.",
@@ -84,6 +90,24 @@ export function registerReadTools(server, client) {
             return errorResult(e.message);
         }
     });
+    server.registerTool("list_wallets", {
+        title: "List account wallets",
+        description: "List wallets auto-provisioned for a Finance account (finance GET /accounts/{accountId}/wallets). Read-only.",
+        inputSchema: {
+            accountId: z.string().describe("Account UUID"),
+            page: z.number().int().min(1).optional(),
+            size: z.number().int().min(1).max(200).optional(),
+        },
+        annotations: READ_ONLY,
+    }, async ({ accountId, page, size }) => {
+        try {
+            const result = await client.listWallets(accountId, { page, size });
+            return jsonResult({ count: result.length, wallets: result });
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
     server.registerTool("list_virtual_bank_accounts", {
         title: "List virtual bank accounts",
         description: "List the EUR vIBANs on an account, each with its reconciliation " +
@@ -99,6 +123,22 @@ export function registerReadTools(server, client) {
             return errorResult(e.message);
         }
     });
+    server.registerTool("get_virtual_bank_account", {
+        title: "Get virtual bank account",
+        description: "Fetch receiving-account details including status, IBAN/BIC and referenceCode. Read-only.",
+        inputSchema: {
+            accountId: z.string().describe("Account UUID"),
+            virtualBankAccountId: z.string().describe("Virtual bank account UUID"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ accountId, virtualBankAccountId }) => {
+        try {
+            return jsonResult(await client.getVirtualBankAccount(accountId, virtualBankAccountId));
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
     server.registerTool("reconcile_by_reference_code", {
         title: "Reconcile by referenceCode",
         description: "Match observed incoming bank transactions on an account's EUR vIBANs to " +
@@ -132,6 +172,24 @@ export function registerReadTools(server, client) {
             return errorResult(e.message);
         }
     });
+    server.registerTool("list_transfers", {
+        title: "List transfers",
+        description: "List transfer history for an account (finance GET /accounts/{accountId}/transfers). Read-only.",
+        inputSchema: {
+            accountId: z.string().describe("Account UUID"),
+            page: z.number().int().min(1).optional(),
+            size: z.number().int().min(1).max(200).optional(),
+        },
+        annotations: READ_ONLY,
+    }, async ({ accountId, page, size }) => {
+        try {
+            const result = await client.listTransfers(accountId, { page, size });
+            return jsonResult({ count: result.length, transfers: result });
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
     server.registerTool("get_transfer", {
         title: "Get transfer",
         description: "Fetch a transfer by id (finance GET /accounts/{accountId}/transfers/{transferId}). Read-only.",
@@ -165,6 +223,19 @@ export function registerReadTools(server, client) {
             return errorResult(e.message);
         }
     });
+    server.registerTool("get_party", {
+        title: "Get party",
+        description: "Fetch an individual or organisation party, including KYC/KYB state when present. Read-only.",
+        inputSchema: { partyId: z.string().describe("Party UUID") },
+        annotations: READ_ONLY,
+    }, async ({ partyId }) => {
+        try {
+            return jsonResult(await client.getParty(partyId));
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
     server.registerTool("get_reference_data", {
         title: "Get reference data",
         description: "Fetch settlement reference data: supported chains, fiat currencies, " +

package/dist/tools/write-tools.js

@@ -8,16 +8,14 @@
  */
 import { z } from "zod";
 import { buildDryRun, evaluateWriteGate } from "../safety.js";
-function jsonResult(data) {
-    return {
-        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
-    };
-}
-function errorResult(message) {
-    return {
-        content: [{ type: "text", text: `Error: ${message}` }],
-        isError: true,
-    };
+import { errorResult, jsonResult } from "../results.js";
+import { normalizeLegacyFiatTransfer } from "../client/sdk-client.js";
+function executionResult(gate, result) {
+    return jsonResult({
+        mode: gate.environment === "mock" ? "mock" : "live",
+        environment: gate.environment,
+        result,
+    });
 }
 const WRITE_ANNOTATIONS = {
     readOnlyHint: false,
@@ -30,18 +28,215 @@ const confirmField = z
     .default(false)
     .describe("Must be true to attempt a live call. Even then, VENLY_MCP_LIVE=1 and " +
     "credentials are also required, otherwise the tool dry-runs.");
+const addressSchema = z
+    .object({
+    addressLine1: z.string().optional(),
+    addressLine2: z.string().optional(),
+    city: z.string().optional(),
+    state: z.string().optional(),
+    postalCode: z.string().optional(),
+    country: z.string().regex(/^[A-Z]{2}$/).optional(),
+})
+    .optional();
+const partySchema = z.object({
+    partyType: z.enum(["INDIVIDUAL", "ORGANISATION"]),
+    externalId: z.string().optional(),
+    firstName: z.string().optional(),
+    lastName: z.string().optional(),
+    name: z.string().optional(),
+    vatNumber: z.string().optional(),
+    address: addressSchema,
+});
+function partyValidationError(party) {
+    if (party.partyType === "INDIVIDUAL" && (!party.firstName || !party.lastName)) {
+        return "INDIVIDUAL parties require firstName and lastName";
+    }
+    if (party.partyType === "ORGANISATION" && !party.name) {
+        return "ORGANISATION parties require name";
+    }
+    return undefined;
+}
 export function registerWriteTools(server, client, env) {
+    server.registerTool("create_party", {
+        title: "Create a customer or organisation party",
+        description: "Create a Finance party. This creates the party record; it does not complete KYC/KYB. Dry-run by default outside explicit mock mode.",
+        inputSchema: {
+            partyType: z.enum(["INDIVIDUAL", "ORGANISATION"]),
+            externalId: z.string().optional(),
+            firstName: z.string().optional(),
+            lastName: z.string().optional(),
+            name: z.string().optional(),
+            vatNumber: z.string().optional(),
+            address: addressSchema,
+            confirm: confirmField,
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ confirm, ...party }) => {
+        const validationError = partyValidationError(party);
+        if (validationError)
+            return errorResult(validationError);
+        const gate = evaluateWriteGate(confirm, env);
+        if (!gate.armed) {
+            return jsonResult(buildDryRun("create_party", "POST", "finance", "/parties", party, gate));
+        }
+        try {
+            return executionResult(gate, await client.createParty(party));
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("create_account", {
+        title: "Create an account and provision its wallet",
+        description: "Create a Finance account. Venly auto-provisions its wallet on the selected chain. Supply partyId or an inline party. Dry-run by default.",
+        inputSchema: {
+            externalId: z.string().min(1),
+            name: z.string().optional(),
+            chain: z.enum(["AVALANCHE", "BASE", "POLYGON"]),
+            address: z.string().optional().describe("Required for SELF_CUSTODY tenants"),
+            partyId: z.string().optional(),
+            party: partySchema.optional(),
+            confirm: confirmField,
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ confirm, ...body }) => {
+        if (!body.partyId && !body.party) {
+            return errorResult("create_account requires partyId or an inline party");
+        }
+        if (body.party) {
+            const validationError = partyValidationError(body.party);
+            if (validationError)
+                return errorResult(validationError);
+        }
+        const gate = evaluateWriteGate(confirm, env);
+        if (!gate.armed) {
+            return jsonResult(buildDryRun("create_account", "POST", "finance", "/accounts", body, gate));
+        }
+        try {
+            return executionResult(gate, await client.createAccount(body));
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("create_virtual_bank_account", {
+        title: "Create a EUR receiving account",
+        description: "Provision a EUR SEPA virtual bank account and conversion target. Outside mock mode the Finance account must have KYC status VERIFIED. Dry-run by default.",
+        inputSchema: {
+            accountId: z.string(),
+            name: z.string().min(1),
+            inCurrency: z.literal("EUR"),
+            targetCryptocurrency: z.enum(["USDC", "EURC", "USDT", "USDS"]),
+            idempotencyKey: z.string().min(1).optional(),
+            confirm: confirmField,
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ accountId, confirm, ...input }) => {
+        const body = {
+            ...input,
+            idempotencyKey: input.idempotencyKey ?? crypto.randomUUID(),
+        };
+        const gate = evaluateWriteGate(confirm, env);
+        if (!gate.armed) {
+            const dryRun = buildDryRun("create_virtual_bank_account", "POST", "finance", `/accounts/${accountId}/virtual-bank-accounts`, body, gate);
+            dryRun.note += " The account must have KYC status VERIFIED before live provisioning.";
+            return jsonResult(dryRun);
+        }
+        try {
+            return executionResult(gate, await client.createVirtualBankAccount(accountId, body));
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("create_fiat_transfer", {
+        title: "Create a fiat-denominated internal transfer",
+        description: "Create an account-to-account transfer using the current Finance OpenAPI fields. Dry-run by default outside explicit mock mode.",
+        inputSchema: {
+            senderAccountId: z.string(),
+            receiverAccountId: z.string().optional(),
+            receiverExternalId: z.string().optional(),
+            currency: z.enum(["EUR", "GBP", "USD"]),
+            amount: z.number(),
+            description: z.string().optional(),
+            merchantReference: z.string().optional(),
+            idempotencyKey: z.string().min(1).optional(),
+            confirm: confirmField,
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ senderAccountId, confirm, ...input }) => {
+        if (!input.receiverAccountId && !input.receiverExternalId) {
+            return errorResult("A receiverAccountId or receiverExternalId is required");
+        }
+        const body = {
+            ...input,
+            idempotencyKey: input.idempotencyKey ?? crypto.randomUUID(),
+        };
+        const gate = evaluateWriteGate(confirm, env);
+        if (!gate.armed) {
+            return jsonResult(buildDryRun("create_fiat_transfer", "POST", "finance", `/accounts/${senderAccountId}/transfers/fiat`, body, gate));
+        }
+        try {
+            return executionResult(gate, await client.createCurrentFiatTransfer(senderAccountId, body));
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("create_crypto_transfer", {
+        title: "Create a crypto-denominated internal transfer",
+        description: "Create an account-to-account asset transfer using the current Finance OpenAPI fields. Dry-run by default outside explicit mock mode.",
+        inputSchema: {
+            senderAccountId: z.string(),
+            receiverAccountId: z.string().optional(),
+            receiverExternalId: z.string().optional(),
+            chain: z.enum(["AVALANCHE", "BASE", "POLYGON"]),
+            asset: z.string().min(1),
+            amount: z.number(),
+            description: z.string().optional(),
+            merchantReference: z.string().optional(),
+            idempotencyKey: z.string().min(1).optional(),
+            confirm: confirmField,
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ senderAccountId, confirm, ...input }) => {
+        if (!input.receiverAccountId && !input.receiverExternalId) {
+            return errorResult("A receiverAccountId or receiverExternalId is required");
+        }
+        const body = {
+            ...input,
+            idempotencyKey: input.idempotencyKey ?? crypto.randomUUID(),
+        };
+        const gate = evaluateWriteGate(confirm, env);
+        if (!gate.armed) {
+            return jsonResult(buildDryRun("create_crypto_transfer", "POST", "finance", `/accounts/${senderAccountId}/transfers/crypto`, body, gate));
+        }
+        try {
+            return executionResult(gate, await client.createCryptoTransfer(senderAccountId, body));
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
     server.registerTool("stage_transfer", {
         title: "Stage a fiat transfer (dry-run by default)",
         description: "Stage a fiat-to-crypto transfer (finance POST /accounts/{senderAccountId}/transfers/fiat). " +
-            "DISARMED by default: returns the exact request it would send unless " +
-            "confirm:true AND VENLY_MCP_LIVE=1 AND credentials are present.",
+            "Legacy fiatAmount/fiatCurrency inputs are normalized to the current OpenAPI fields; " +
+            "the dry-run shows the exact normalized request. DISARMED by default: returns that " +
+            "request without sending unless confirm:true AND VENLY_MCP_LIVE=1 AND credentials are present.",
         inputSchema: {
             senderAccountId: z.string().describe("Account initiating the transfer"),
             receiverAccountId: z.string(),
-            fiatAmount: z.string().describe("Decimal string, e.g. \"1000.00\""),
+            fiatAmount: z
+                .string()
+                .refine((value) => value.trim() !== "" && Number.isFinite(Number(value)), "fiatAmount must be a numeric decimal string")
+                .describe("Decimal string, e.g. \"1000.00\""),
             fiatCurrency: z.string().describe("e.g. EUR"),
-            cryptocurrency: z.string().optional(),
+            cryptocurrency: z
+                .string()
+                .optional()
+                .describe("Retired: rejected with guidance. The current contract resolves the fiat " +
+                "amount to the account's settlement asset; use create_crypto_transfer instead."),
             description: z.string().optional(),
             merchantReference: z.string().optional(),
             confirm: confirmField,
@@ -49,20 +244,31 @@ export function registerWriteTools(server, client, env) {
         annotations: WRITE_ANNOTATIONS,
     }, async ({ senderAccountId, confirm, ...rest }) => {
         const gate = evaluateWriteGate(confirm, env);
-        const body = {
+        const legacyInput = {
             receiverAccountId: rest.receiverAccountId,
             fiatAmount: rest.fiatAmount,
             fiatCurrency: rest.fiatCurrency,
             cryptocurrency: rest.cryptocurrency,
             description: rest.description,
             merchantReference: rest.merchantReference,
+            idempotencyKey: crypto.randomUUID(),
         };
+        // Normalize BEFORE the gate branch so the dry-run preview is byte-for-byte
+        // the request a live call would send (and the retired cryptocurrency field
+        // is rejected instead of silently dropped).
+        let body;
+        try {
+            body = normalizeLegacyFiatTransfer(legacyInput);
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
         if (!gate.armed) {
             return jsonResult(buildDryRun("stage_transfer", "POST", "finance", `/accounts/${senderAccountId}/transfers/fiat`, body, gate));
         }
         try {
-            const result = await client.createFiatTransfer(senderAccountId, body);
-            return jsonResult({ mode: "live", result });
+            const result = await client.createFiatTransfer(senderAccountId, legacyInput);
+            return executionResult(gate, result);
         }
         catch (e) {
             return errorResult(e.message);
@@ -91,7 +297,7 @@ export function registerWriteTools(server, client, env) {
         }
         try {
             const result = await client.approveRampRequest(id, body);
-            return jsonResult({ mode: "live", result });
+            return executionResult(gate, result);
         }
         catch (e) {
             return errorResult(e.message);
@@ -118,7 +324,7 @@ export function registerWriteTools(server, client, env) {
         }
         try {
             const result = await client.rejectRampRequest(id, body);
-            return jsonResult({ mode: "live", result });
+            return executionResult(gate, result);
         }
         catch (e) {
             return errorResult(e.message);
@@ -162,7 +368,7 @@ export function registerWriteTools(server, client, env) {
         }
         try {
             const result = await client.createPayInSession(accountId, body);
-            return jsonResult({ mode: "live", result });
+            return executionResult(gate, result);
         }
         catch (e) {
             return errorResult(e.message);

package/dist/types.d.ts

@@ -1,108 +1,37 @@
 /**
- * Domain types + the injectable VenlyClient interface.
+ * Generated API contracts + the injectable VenlyClient interface.
  *
- * These shapes are a minimal projection of the published OpenAPI specs
- * vendored in this repository under `specs/` – finance.yaml (servers:
- * https://api.venlyfinance.com/v1) and fundflow.yaml (servers:
- * https://api-fundflow.venly.io). Only the fields the tools actually read or
- * echo are modeled. Fields are intentionally loose (optional) because this is a
- * thin wrapper, not a full SDK.
- *
- * TRANSPORT NOTE: the bundled HttpVenlyClient is a deliberately minimal fetch
- * transport (see client/http-client.ts). A future release replaces it with a
- * thin adapter over `@venlyfinance/sdk` with no change to this interface;
- * until then the minimal transport is what ships. When that lands, replace
- * HttpVenlyClient with a thin adapter over it and delete the vendored transport.
+ * Finance and Fundflow resources and requests are aliases to the types exported
+ * by `@venlyfinance/sdk`. Only MCP-owned inputs and compatibility shapes are
+ * declared locally. This prevents the MCP from silently drifting away from the
+ * vendored OpenAPI specifications.
  */
-/** Ramp request status flow, per fundflow.yaml overview. */
-export type RampStatus = "AWAITING_APPROVAL" | "AWAITING_FUNDS" | "PROCESSING" | "SUCCEEDED" | "FAILED" | "BLOCKED" | "DENIED" | "REJECTED" | "CANCELLED";
-export type RampType = "ON_RAMP" | "OFF_RAMP";
-/** Simplified ramp request for list views (fundflow RampRequestListItem). */
-export interface RampRequestListItem {
-    id: string;
-    paymentReference?: string;
-    rampType?: RampType;
-    status?: RampStatus;
-    fiatAmount?: number;
-    fiatCurrency?: string;
-    cryptoAmount?: number;
-    cryptoCurrency?: string;
-    createdAt?: string;
-    createdBy?: string;
-}
-/** Full ramp request detail (fundflow RampRequestDto). `version` drives the
- * four-eyes optimistic-locking approve/reject calls. */
-export interface RampRequestDto {
-    id: string;
-    companyId?: string;
-    companyName?: string;
-    rampType?: RampType;
-    status?: RampStatus;
-    fiatAmount?: number;
-    fiatNetAmount?: number;
-    cryptoAmount?: number;
-    fiatFeeAmount?: number;
-    exchangeRate?: number;
-    feePercentage?: number;
-    paymentReference?: string;
-    paymentReceived?: boolean;
-    blockchainTransactionHash?: string;
-    createdAt?: string;
-    createdBy?: string;
-    version?: number;
-}
-/** Finance Account (finance getAccount). */
-export interface Account {
-    id: string;
-    status?: string;
-    reference?: string;
-    createdAt?: string;
-    updatedAt?: string;
-    [key: string]: unknown;
-}
-/** Finance VirtualBankAccount. `referenceCode` is the reconciliation key. */
-export interface VirtualBankAccount {
-    id: string;
-    accountId?: string;
-    bankAccountType?: string;
-    name?: string;
-    status?: string;
-    currency?: string;
-    targetCryptocurrency?: string;
-    iban?: string;
-    bic?: string;
-    bankName?: string;
-    beneficiaryName?: string;
-    referenceCode?: string;
-    createdAt?: string;
-    updatedAt?: string;
-}
-/** Finance Transfer (finance getTransfer). */
-export interface Transfer {
-    id: string;
-    status?: string;
-    fiatAmount?: string | number;
-    fiatCurrency?: string;
-    cryptocurrency?: string;
-    createdAt?: string;
-    [key: string]: unknown;
-}
-/** Finance Party (finance listParties). */
-export interface Party {
-    id: string;
-    type?: string;
-    status?: string;
-    [key: string]: unknown;
-}
-/** A fiat-to-crypto payment session (finance PaymentSession). */
-export interface PaymentSession {
-    id: string;
-    accountId?: string;
-    paymentUrl?: string;
-    externalRef?: string;
-    status?: string;
-    [key: string]: unknown;
-}
+import type { FinanceComponents, FundflowComponents } from "@venlyfinance/sdk";
+import type { VenlyEnvironment } from "./constants.js";
+type FinanceSchemas = FinanceComponents["schemas"];
+type FundflowSchemas = FundflowComponents["schemas"];
+export type AddressInput = FinanceSchemas["Address"];
+export type Party = FinanceSchemas["Party"];
+export type CreatePartyInput = FinanceSchemas["CreatePartyRequest"];
+export type Account = FinanceSchemas["Account"];
+export type CreateAccountInput = FinanceSchemas["CreateAccountRequest"];
+export type Wallet = FinanceSchemas["Wallet"];
+export type VirtualBankAccount = FinanceSchemas["VirtualBankAccount"];
+export type CreateVirtualBankAccountInput = FinanceSchemas["CreateVirtualBankAccountRequest"];
+export type PaymentSession = FinanceSchemas["PaymentSession"];
+export type CreatePayInSessionRequest = FinanceSchemas["CreatePayInSessionRequest"];
+export type Transfer = FinanceSchemas["Transfer"];
+export type CurrentCreateFiatTransferInput = FinanceSchemas["CreateFiatTransferInput"];
+export type CreateCryptoTransferInput = FinanceSchemas["CreateCryptoTransferInput"];
+export type RampRequestDto = FundflowSchemas["RampRequestDto"];
+export type RampRequestListItem = FundflowSchemas["RampRequestListItem"];
+export type OptimisticLockingBody = FundflowSchemas["UpdateWithOptimisticLockingRequest"];
+export type SupportedChains = FundflowSchemas["SupportedChainsDto"];
+export type FiatCurrency = FundflowSchemas["FiatCurrencyDto"];
+export type CryptoCurrency = FundflowSchemas["CryptoCurrencyDto"];
+export type VenlyFee = FundflowSchemas["FeeDto"];
+export type RampStatus = NonNullable<RampRequestDto["status"]>;
+export type RampType = NonNullable<RampRequestDto["rampType"]>;
 /**
  * An observed incoming bank transaction on a vIBAN. This is operator- or
  * bank-feed-supplied data (there is no list-vIBAN-transactions endpoint in the
@@ -127,54 +56,67 @@ export interface ListRampRequestsParams {
     page?: number;
     size?: number;
 }
-/** Body for the fiat transfer POST (finance CreateFiatTransferInput). */
+/** Legacy stage_transfer body, normalized to the current finance
+ * CreateFiatTransferInput before any call (see normalizeLegacyFiatTransfer). */
 export interface CreateFiatTransferInput {
     receiverAccountId: string;
     receiverExternalId?: string;
     fiatAmount: string;
     fiatCurrency: string;
+    /** Retired: the current contract has no such field. Normalization rejects it
+     * instead of silently dropping it. */
     cryptocurrency?: string;
     description?: string;
     merchantReference?: string;
-}
-/** Body for approve/reject (fundflow UpdateWithOptimisticLockingRequest). */
-export interface OptimisticLockingBody {
-    version: number;
-}
-/** Body for the payment session POST (finance CreatePayInSessionRequest). */
-export interface CreatePayInSessionRequest {
-    inAmount: string;
-    inCurrency: string;
-    outCryptocurrency: string;
-    callbackUrl: string;
-    idempotencyKey: string;
-    successRedirectUrl?: string;
-    failureRedirectUrl?: string;
-    externalRef?: string;
-    metadata?: Record<string, string>;
+    /** Preserved across the dry-run preview and the live call when supplied. */
+    idempotencyKey?: string;
 }
 /**
- * The injectable Venly transport. HttpVenlyClient is the real fetch-based
- * implementation; tests inject a mock. The MCP layer depends ONLY on this
- * interface, never on a concrete transport, which is what makes the fail-closed
- * write path testable without a network.
+ * The injectable Venly client contract. SdkVenlyClient is the production
+ * implementation; tests inject a lightweight mock. The MCP layer depends only
+ * on this interface, keeping the fail-closed write path testable without a
+ * network.
  */
 export interface VenlyClient {
+    /** The environment this client actually targets. When present, createServer
+     * refuses to start if it disagrees with the VENLY_ENV the write gate reads –
+     * the mock gate auto-arms writes, so the two must never diverge. */
+    readonly environment?: VenlyEnvironment;
     listRampRequests(params?: ListRampRequestsParams): Promise<RampRequestListItem[]>;
     getRampRequest(id: string): Promise<RampRequestDto>;
+    listAccounts(params?: {
+        page?: number;
+        size?: number;
+    }): Promise<Account[]>;
     getAccount(accountId: string): Promise<Account>;
+    listWallets(accountId: string, params?: {
+        page?: number;
+        size?: number;
+    }): Promise<Wallet[]>;
     listVirtualBankAccounts(accountId: string): Promise<VirtualBankAccount[]>;
+    getVirtualBankAccount(accountId: string, virtualBankAccountId: string): Promise<VirtualBankAccount>;
+    listTransfers(accountId: string, params?: {
+        page?: number;
+        size?: number;
+    }): Promise<Transfer[]>;
     getTransfer(accountId: string, transferId: string): Promise<Transfer>;
     listParties(params?: {
         page?: number;
         size?: number;
     }): Promise<Party[]>;
-    getSupportedChains(): Promise<unknown[]>;
-    getFiatCurrencies(): Promise<unknown[]>;
-    getCryptocurrencies(): Promise<unknown[]>;
-    getCompanyFees(): Promise<unknown>;
+    getParty(partyId: string): Promise<Party>;
+    getSupportedChains(): Promise<SupportedChains[]>;
+    getFiatCurrencies(): Promise<FiatCurrency[]>;
+    getCryptocurrencies(): Promise<CryptoCurrency[]>;
+    getCompanyFees(): Promise<VenlyFee[]>;
+    createParty(body: CreatePartyInput): Promise<Party>;
+    createAccount(body: CreateAccountInput): Promise<Account>;
+    createVirtualBankAccount(accountId: string, body: CreateVirtualBankAccountInput): Promise<VirtualBankAccount>;
     createFiatTransfer(senderAccountId: string, body: CreateFiatTransferInput): Promise<Transfer>;
+    createCurrentFiatTransfer(senderAccountId: string, body: CurrentCreateFiatTransferInput): Promise<Transfer>;
+    createCryptoTransfer(senderAccountId: string, body: CreateCryptoTransferInput): Promise<Transfer>;
     approveRampRequest(id: string, body: OptimisticLockingBody): Promise<RampRequestDto>;
     rejectRampRequest(id: string, body: OptimisticLockingBody): Promise<RampRequestDto>;
     createPayInSession(accountId: string, body: CreatePayInSessionRequest): Promise<PaymentSession>;
 }
+export {};