@venlyfinance/settlement-mcp 0.4.1 → 0.5.0

package/dist/client/sdk-client.d.ts

@@ -1,6 +1,6 @@
 import { FundflowClient, VenlyFinanceClient, type MockCall } from "@venlyfinance/sdk";
 import { type VenlyEnvironment } from "../constants.js";
-import type { Account, CryptoCurrency, CreateAccountInput, CreateCryptoTransferInput, CreateFiatTransferInput, CreatePartyInput, CreatePayInSessionRequest, CreateVirtualBankAccountInput, CurrentCreateFiatTransferInput, FiatCurrency, ListRampRequestsParams, OptimisticLockingBody, Party, PaymentSession, RampRequestDto, RampRequestListItem, SupportedChains, Transfer, VenlyClient, VirtualBankAccount, VenlyFee, Wallet } from "../types.js";
+import type { Account, CryptoCurrency, CreateAccountInput, CreateCryptoTransferInput, CreateFiatTransferInput, CreatePartyInput, CreatePayInSessionRequest, CreateVirtualBankAccountInput, CurrentCreateFiatTransferInput, FiatCurrency, ListRampRequestsParams, OptimisticLockingBody, Party, PaymentSession, Payout, PayoutBankAccount, PayoutRoute, CreatePayoutInput, CreatePayoutRouteInput, RegisterPayoutBankAccountInput, PayoutOwnershipProof, CompleteOwnershipProofInput, RampRequestDto, RampRequestListItem, SupportedChains, Transfer, VenlyClient, VirtualBankAccount, VenlyFee, Wallet } from "../types.js";
 /**
  * Normalize the legacy stage_transfer input to the current Finance
  * CreateFiatTransferInput wire shape. Exported so the write tool can show the
@@ -64,4 +64,17 @@ export declare class SdkVenlyClient implements VenlyClient {
     approveRampRequest(id: string, body: OptimisticLockingBody): Promise<RampRequestDto>;
     rejectRampRequest(id: string, body: OptimisticLockingBody): Promise<RampRequestDto>;
     createPayInSession(accountId: string, body: CreatePayInSessionRequest): Promise<PaymentSession>;
+    listPayouts(accountId: string, params?: {
+        page?: number;
+        size?: number;
+        status?: string;
+    }): Promise<Payout[]>;
+    getPayout(accountId: string, payoutId: string): Promise<Payout>;
+    requestPayout(accountId: string, body: CreatePayoutInput): Promise<Payout>;
+    listPayoutRoutes(accountId: string): Promise<PayoutRoute[]>;
+    createPayoutRoute(accountId: string, body: CreatePayoutRouteInput): Promise<PayoutRoute>;
+    preparePayoutOwnershipProof(accountId: string, routeId: string): Promise<PayoutOwnershipProof>;
+    completePayoutOwnershipProof(accountId: string, routeId: string, body: CompleteOwnershipProofInput): Promise<PayoutRoute>;
+    listPayoutBankAccounts(partyId: string): Promise<PayoutBankAccount[]>;
+    registerPayoutBankAccount(partyId: string, body: RegisterPayoutBankAccountInput): Promise<PayoutBankAccount>;
 }

package/dist/client/sdk-client.js

@@ -180,4 +180,43 @@ export class SdkVenlyClient {
         this.assertReady();
         return this.finance.paymentSessions.create(accountId, body);
     }
+    // ----- Payout surface (contract 1.3.0) -----
+    async listPayouts(accountId, params) {
+        this.assertReady();
+        const page = await this.finance.payouts.list(accountId, params);
+        return page.items;
+    }
+    async getPayout(accountId, payoutId) {
+        this.assertReady();
+        return this.finance.payouts.get(accountId, payoutId);
+    }
+    async requestPayout(accountId, body) {
+        this.assertReady();
+        return this.finance.payouts.request(accountId, body);
+    }
+    async listPayoutRoutes(accountId) {
+        this.assertReady();
+        return this.finance.payoutRoutes.list(accountId);
+    }
+    async createPayoutRoute(accountId, body) {
+        this.assertReady();
+        return this.finance.payoutRoutes.create(accountId, body);
+    }
+    async preparePayoutOwnershipProof(accountId, routeId) {
+        this.assertReady();
+        return this.finance.payoutRoutes.prepareOwnershipProof(accountId, routeId);
+    }
+    async completePayoutOwnershipProof(accountId, routeId, body) {
+        this.assertReady();
+        return this.finance.payoutRoutes.completeOwnershipProof(accountId, routeId, body);
+    }
+    async listPayoutBankAccounts(partyId) {
+        this.assertReady();
+        const page = await this.finance.payoutBankAccounts.list(partyId);
+        return page.items;
+    }
+    async registerPayoutBankAccount(partyId, body) {
+        this.assertReady();
+        return this.finance.payoutBankAccounts.register(partyId, body);
+    }
 }

package/dist/constants.d.ts

@@ -1,9 +1,9 @@
 /** Shared constants. The default environment is MOCK so an unconfigured run
  * never touches real infrastructure; staging/production are explicit. */
 export declare const SERVER_NAME = "venly-finance-mcp-server";
-export declare const SERVER_VERSION = "0.4.1";
+export declare const SERVER_VERSION = "0.5.0";
 export declare const ENVIRONMENT_FLAG = "VENLY_ENV";
-export type VenlyEnvironment = "mock" | "staging" | "production";
+export type VenlyEnvironment = "mock" | "qa" | "staging" | "production";
 export declare function resolveVenlyEnvironment(env: Record<string, string | undefined>): VenlyEnvironment;
 /** The env flag that must equal "1" for any write tool to execute live. */
 export declare const LIVE_FLAG = "VENLY_MCP_LIVE";

package/dist/constants.js

@@ -1,17 +1,17 @@
 /** Shared constants. The default environment is MOCK so an unconfigured run
  * never touches real infrastructure; staging/production are explicit. */
 export const SERVER_NAME = "venly-finance-mcp-server";
-export const SERVER_VERSION = "0.4.1";
+export const SERVER_VERSION = "0.5.0";
 export const ENVIRONMENT_FLAG = "VENLY_ENV";
 export function resolveVenlyEnvironment(env) {
     // Default is MOCK (since 0.3.0): the mock-first product must not point at
     // real infrastructure when unconfigured. Set VENLY_ENV explicitly for
     // staging or production.
     const value = env[ENVIRONMENT_FLAG] ?? "mock";
-    if (value === "mock" || value === "staging" || value === "production") {
+    if (value === "mock" || value === "qa" || value === "staging" || value === "production") {
         return value;
     }
-    throw new Error(`${ENVIRONMENT_FLAG} must be one of mock, staging, production; received ${JSON.stringify(value)}`);
+    throw new Error(`${ENVIRONMENT_FLAG} must be one of mock, qa, staging, production; received ${JSON.stringify(value)}`);
 }
 /** The env flag that must equal "1" for any write tool to execute live. */
 export const LIVE_FLAG = "VENLY_MCP_LIVE";

package/dist/frontend.js

@@ -1,12 +1,35 @@
 import { z } from "zod";
 export const REGISTRY_URL_TEMPLATE = "https://raw.githubusercontent.com/Venly/venly-settlement-sdk/main/ui/r/{name}.json";
 const JOURNEYS = {
+    auth: `# Auth (sign-in, 2FA, sign-up)
+Shell: outside the app shell - a centred card column.
+Registry items: venly-tokens; block: auth (SignInForm, TwoFactorForm, SignUpForm).
+Binding: an AuthAdapter YOU implement - the Venly APIs authenticate machines
+(client credentials), never people, so end-user auth is your identity layer
+(OAuth/OIDC, Better Auth, Auth0, Clerk, Keycloak). createMockAuthAdapter ships
+for demos: deterministic 2FA code 000000, expireSession() driver.
+States that must exist: signed out, bad credentials (ONE combined message -
+no user enumeration), 2FA challenge with wrong-code path, session expired
+(session() returns null - redirect, no other signal), duplicate sign-up email.
+Rules that must hold: credential errors never confirm which half was wrong;
+the code field is six slots with paste distribution and full keyboard support;
+the mock never claims an email was sent.`,
+    team: `# Team
+Shell: in-shell content column.
+Registry items: venly-tokens, data-table, status-pill; block: team (TeamTable, InviteDialog).
+Binding: a TeamAdapter over your auth provider (createMockTeamAdapter for demos).
+States that must exist: ACTIVE/INVITED/DISABLED members on first paint, invite
+created (display-only link in mock - never a fake sent-email claim), role
+change persisting, self-actions blocked with the reason.
+Rules that must hold: member status is word + glyph; role controls live in the
+row; you cannot change your own role or disable yourself - the control is
+disabled AND explains why.`,
     "home-balances": `# Home / balances
 Shell: left nav rail + thin top bar; full-width content.
-Registry items: venly-tokens, balance-card, data-table, status-pill.
-Hooks: useAccounts, useVirtualBankAccounts; balances rendered per account/currency.
-States that must exist: loading, zero accounts (first-run guidance), balances with reserved buckets.
-Rules that must hold: available is the emphasised figure and the only one above the rule; reserved is demoted by position and scale, never colour; unspendable buckets carry the padlock; never assume stablecoin parity - render the quoted rate.`,
+Registry items: venly-tokens, balance-card, data-table, status-pill; block: balances (BalancesBlock, BalanceMiniature).
+Hooks: useAccounts, useWallets; balances rendered per asset across the account's wallets.
+States that must exist: loading, zero balances (first-run guidance), reserved buckets, entirely reserved (available 0 rendered honestly - the acct-escrow seed exercises it), balance load error degrading locally with a retry.
+Rules that must hold: available is the emphasised figure and the only one above the rule; reserved is demoted by position and scale, never colour, and carries the still-yours qualifier; unspendable buckets carry the padlock; masking covers every figure including the chrome miniature; arithmetic mismatches are surfaced, never corrected; never assume stablecoin parity - render the quoted rate.`,
     receive: `# Receive
 Shell: content column - a warning callout, the field card, an advisory below.
 Registry items: venly-tokens, field-list; block: receive.
@@ -27,10 +50,16 @@ States that must exist: loading, empty ledger, rows with pending/failed pills, o
 Rules that must hold: a row click opens the panel, never navigates; no scrim - the source row stays tinted; settled rows stay quiet (colour is a budget; pills only where action or failure lives); the panel's hero is the amount; the failure reason rides the terminal timeline node.`,
     "onboarding-status": `# Onboarding / verification status
 Shell: full page, form clamped ~600px; a status home once submitted.
-Registry items: venly-tokens, timeline, status-pill, field-list.
-Hooks: useParties, useCreateParty; verification status from the party/account records.
-States that must exist: collecting (per-section progress), submitted/waiting (say who acts next, on which channel, what still works meanwhile), approved, declined (humane copy + what to do next), re-verification on a live account.
-Rules that must hold: never render a fake progress percentage - use real per-item status; a waiting state answers how long / who acts / what still works; a decline explains and offers a next step, not a dead end; creating a party is NOT completed verification - show the honest state.`,
+Registry items: venly-tokens, timeline, status-pill, field-list; block: onboarding (CompanyForm, VerificationStatusHome, RestrictedBanner).
+Hooks: useCreateParty, useCreateAccount, useParty, useAccount; verification status from the party/account records verbatim.
+States that must exist: collecting (review before submit), submitted/waiting (say who acts next, on which channel, what still works meanwhile), approved, declined (humane copy, review-request as the primary action), re-verification on a live account (banner naming what pauses and what keeps working).
+Rules that must hold: never render a fake progress percentage - use real status; a waiting state answers how long / who acts / what still works, and where no review window is published the copy says so instead of inventing one; a decline explains and offers a next step, not a dead end; creating a party is NOT completed verification - show the honest state.`,
+    "withdraw-bank-accounts": `# Withdraw + bank accounts (off-ramp)
+Shell: settings page for the whitelist; full page for the flow, form clamped ~600px.
+Registry items: venly-tokens, data-table, status-pill, timeline, field-list, arithmetic-ladder; blocks: bank-accounts (BankAccountsBlock, AddBankAccountForm), withdraw (WithdrawFlow, WithdrawalsTable, ConnectedWithdrawDetail).
+Hooks: useCompanyBankAccounts, useBankAccountConfig, useCreateCompanyBankAccount, useRampRequests, useRampRequest, useCreateRampRequest, useFeeQuote, useRampPairs, useReferenceData, useFourEyesApproval, useInitiateRamp, describeRampStatus.
+States that must exist: empty whitelist (one CTA), account in review / verified / declined, no-verified-destination block, amount over balance (two-place signal), fee quote with its unit, awaiting approval (creator sees why they can't approve), stale decision (409 - refetch and re-decide, never auto-retry), awaiting funds (deposit instructions + mandatory reference + tx-hash report), processing, paid out, failed, rejected, cancelled, on hold.
+Rules that must hold: destinations are the company's OWN verified accounts - unverified rows are disabled with the reason, never hidden; the pre-create review renders only known figures (no invented rate, no bank-receives placeholder - the created record carries the fiat arithmetic and the detail opens on it); a refusal never reads as a wait; the event timeline renders actor, role and absolute timestamps.`,
     reconciliation: `# Reconciliation
 Shell: split pane (roughly one-third list, two-thirds evidence) - not a drawer.
 Registry items: venly-tokens, data-table, side-panel, status-pill, field-list.
@@ -104,7 +133,7 @@ registry install. On a fresh Vite/React app that means, in order:
    works - it never imports base-library components itself).
 3. Add the registry once to components.json -
   { "registries": { "@venlyfinance": "${REGISTRY_URL_TEMPLATE}" } }
-4. \`npx shadcn@latest add @venlyfinance/receive @venlyfinance/send @venlyfinance/activity -y -o\`.
+4. \`npx shadcn@latest add @venlyfinance/balances @venlyfinance/activity @venlyfinance/receive @venlyfinance/send @venlyfinance/auth @venlyfinance/team @venlyfinance/onboarding -y -o\`.
    Each block auto-installs its components, the venly-tokens file AND its
    npm dependencies (@venlyfinance/react, @venlyfinance/sdk, TanStack
    Query) - no separate npm install step is needed.

package/dist/resources.js

@@ -15,14 +15,16 @@ Venly Finance provides financial infrastructure through several regulated partne
 - fiat-to-crypto payment sessions;
 - account-to-account fiat-denominated and crypto-denominated transfers;
 - payment-request authorization, settlement and reversal primitives;
+- third-party payouts (contract 1.3.0): beneficiary bank accounts registered per party (SEPA and US ACH, masked details), payout routes activated by wallet-ownership proof, and payouts with a full lifecycle (REQUESTED through COMPLETED, REJECTED, FAILED or RETURNED, failures carrying a reason);
 - Fundflow on/off-ramp workflows with four-eyes approval.
 
 Current boundaries:
 
-- EUR is the currently documented virtual-bank-account currency. Do not infer global bank-account coverage.
+- EUR SEPA and USD ACH are the documented virtual-bank-account types. Do not infer global bank-account coverage.
 - Creating a party does not complete KYC/KYB. Live virtual-bank-account provisioning requires a VERIFIED account.
+- The payout surface is on the QA contract (Finance API 1.3.0); production may trail it. Verify against the environment you target.
 - Card issuing is not exposed by the current Finance OpenAPI contract.
-- A bank charter, deposit insurance and external-bank payout coverage are not supplied or implied by this MCP.
+- A bank charter and deposit insurance are not supplied or implied by this MCP.
 - Production x402 settlement is not implemented; the x402 tool is a quote-only stub.
 `,
     },
@@ -33,7 +35,7 @@ Current boundaries:
         description: "Environment, write, compliance and secret-handling rules.",
         text: `# Venly Finance MCP safety
 
-- Set VENLY_ENV explicitly to mock, staging or production. An absent value defaults to mock (since 0.3.0), so an unconfigured server never points at real infrastructure.
+- Set VENLY_ENV explicitly to mock, qa, staging or production. An absent value defaults to mock (since 0.3.0), so an unconfigured server never points at real infrastructure.
 - Mock mode uses synthetic SDK fixtures, no credentials and no network. Every mutation result is labelled mode=mock.
 - Staging writes require confirm=true, VENLY_MCP_LIVE=1 and VENLY_CLIENT_ID/VENLY_CLIENT_SECRET.
 - Production requires every staging gate plus VENLY_MCP_PRODUCTION=1.

package/dist/staging-smoke.d.ts

@@ -1,4 +1,4 @@
-export declare const EXPECTED_TOOLS: readonly ["list_ramp_requests", "get_ramp_request", "list_accounts", "get_account", "list_wallets", "list_virtual_bank_accounts", "get_virtual_bank_account", "reconcile_by_reference_code", "list_transfers", "get_transfer", "list_parties", "get_party", "get_reference_data", "create_party", "create_account", "create_virtual_bank_account", "create_fiat_transfer", "create_crypto_transfer", "approve_ramp_request", "reject_ramp_request", "create_payment_session", "quote_x402_payment", "get_journey_blueprint", "review_screen"];
+export declare const EXPECTED_TOOLS: readonly ["list_ramp_requests", "get_ramp_request", "list_accounts", "get_account", "list_wallets", "list_virtual_bank_accounts", "get_virtual_bank_account", "reconcile_by_reference_code", "list_transfers", "get_transfer", "list_parties", "get_party", "get_reference_data", "create_party", "create_account", "create_virtual_bank_account", "create_fiat_transfer", "create_crypto_transfer", "approve_ramp_request", "reject_ramp_request", "create_payment_session", "list_payouts", "get_payout", "list_payout_routes", "list_payout_bank_accounts", "register_payout_bank_account", "create_payout_route", "prepare_payout_ownership_proof", "complete_payout_ownership_proof", "request_payout", "quote_x402_payment", "get_journey_blueprint", "review_screen"];
 export declare const EXPECTED_RESOURCE_URIS: readonly ["venly://capabilities", "venly://safety", "venly://workflows/international-account", "venly://workflows/mock-to-staging", "venly://frontend/agents"];
 export declare const EXPECTED_PROMPTS: readonly ["build_international_account"];
 export interface DiscoveryNames {

package/dist/staging-smoke.js

@@ -25,6 +25,15 @@ export const EXPECTED_TOOLS = [
     "approve_ramp_request",
     "reject_ramp_request",
     "create_payment_session",
+    "list_payouts",
+    "get_payout",
+    "list_payout_routes",
+    "list_payout_bank_accounts",
+    "register_payout_bank_account",
+    "create_payout_route",
+    "prepare_payout_ownership_proof",
+    "complete_payout_ownership_proof",
+    "request_payout",
     "quote_x402_payment",
     "get_journey_blueprint",
     "review_screen",

package/dist/tools/read-tools.js

@@ -270,4 +270,83 @@ export function registerReadTools(server, client) {
             return errorResult(e.message);
         }
     });
+    server.registerTool("list_payouts", {
+        title: "List payouts",
+        description: "List third-party payouts for an account (finance GET /v1/accounts/{accountId}/payouts). " +
+            "A payout moves crypto out of the account and settles fiat to a registered beneficiary " +
+            "bank account. Statuses: REQUESTED, SENDING, PROVIDER_PROCESSING, COMPLETED, REJECTED, " +
+            "FAILED, RETURNED. Read-only.",
+        inputSchema: {
+            accountId: z.string(),
+            status: z
+                .enum([
+                "REQUESTED",
+                "SENDING",
+                "PROVIDER_PROCESSING",
+                "COMPLETED",
+                "REJECTED",
+                "FAILED",
+                "RETURNED",
+            ])
+                .optional(),
+            page: z.number().int().min(1).optional(),
+            size: z.number().int().min(1).max(200).optional(),
+        },
+        annotations: READ_ONLY,
+    }, async ({ accountId, ...params }) => {
+        try {
+            const result = await client.listPayouts(accountId, params);
+            return jsonResult({ count: result.length, payouts: result });
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("get_payout", {
+        title: "Get one payout",
+        description: "Fetch one payout by id (finance GET /v1/accounts/{accountId}/payouts/{payoutId}). " +
+            "COMPLETED payouts carry settledFiatAmount and completedAt; REJECTED/FAILED/RETURNED " +
+            "carry a failureReason. Read-only.",
+        inputSchema: { accountId: z.string(), payoutId: z.string() },
+        annotations: READ_ONLY,
+    }, async ({ accountId, payoutId }) => {
+        try {
+            return jsonResult(await client.getPayout(accountId, payoutId));
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("list_payout_routes", {
+        title: "List payout routes",
+        description: "List an account's payout routes (finance GET /v1/accounts/{accountId}/payout-routes). " +
+            "A route binds a beneficiary bank account to this account and a deposit asset; only an " +
+            "ACTIVE route (ownership proof completed) can carry payouts. Read-only.",
+        inputSchema: { accountId: z.string() },
+        annotations: READ_ONLY,
+    }, async ({ accountId }) => {
+        try {
+            const result = await client.listPayoutRoutes(accountId);
+            return jsonResult({ count: result.length, payoutRoutes: result });
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("list_payout_bank_accounts", {
+        title: "List beneficiary bank accounts",
+        description: "List the payout (beneficiary) bank accounts registered on a party " +
+            "(finance GET /v1/parties/{partyId}/payout-bank-accounts). Rail details come back " +
+            "masked. Only ACTIVE accounts can back a payout route. Read-only.",
+        inputSchema: { partyId: z.string() },
+        annotations: READ_ONLY,
+    }, async ({ partyId }) => {
+        try {
+            const result = await client.listPayoutBankAccounts(partyId);
+            return jsonResult({ count: result.length, payoutBankAccounts: result });
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
 }

package/dist/tools/write-tools.js

@@ -332,4 +332,151 @@ export function registerWriteTools(server, client, env) {
             return errorResult(e.message);
         }
     });
+    server.registerTool("register_payout_bank_account", {
+        title: "Register a beneficiary bank account",
+        description: "Register a payout (beneficiary) bank account on a party (finance POST " +
+            "/v1/parties/{partyId}/payout-bank-accounts). The account starts PENDING; an operator " +
+            "activates it before it can back a payout route. Rail details come back masked. " +
+            "Dry-run by default.",
+        inputSchema: {
+            partyId: z.string(),
+            rail: z.enum(["SEPA", "US_ACH"]),
+            fiatCurrency: z.string().min(3).max(3),
+            label: z.string().optional(),
+            accountHolderName: z.string().min(1),
+            iban: z.string().optional().describe("SEPA rail"),
+            bic: z.string().optional().describe("SEPA rail"),
+            accountNumber: z.string().optional().describe("US_ACH rail"),
+            abaRoutingNumber: z.string().optional().describe("US_ACH rail"),
+            accountType: z.enum(["CHECKING", "SAVINGS"]).optional().describe("US_ACH rail"),
+            bankName: z.string().optional(),
+            confirm: confirmField,
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ partyId, confirm, iban, bic, accountNumber, abaRoutingNumber, accountType, ...rest }) => {
+        const body = {
+            ...rest,
+            railDetails: { iban, bic, accountNumber, abaRoutingNumber, accountType },
+        };
+        const gate = evaluateWriteGate(confirm, env);
+        if (!gate.armed) {
+            return jsonResult(buildDryRun("register_payout_bank_account", "POST", "finance", `/parties/${partyId}/payout-bank-accounts`, body, gate));
+        }
+        try {
+            return executionResult(gate, await client.registerPayoutBankAccount(partyId, body));
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("create_payout_route", {
+        title: "Create a payout route",
+        description: "Bind an ACTIVE beneficiary bank account to an account and a deposit asset (finance " +
+            "POST /v1/accounts/{accountId}/payout-routes). The route starts AWAITING_OWNERSHIP_PROOF; " +
+            "complete_payout_ownership_proof activates it. Dry-run by default.",
+        inputSchema: {
+            accountId: z.string(),
+            payoutBankAccountId: z.string(),
+            chain: z.enum(["AVALANCHE", "BASE", "ETHEREUM", "POLYGON", "SOLANA"]),
+            asset: z.string().min(1).describe("Deposit asset name, e.g. USDC"),
+            confirm: confirmField,
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ accountId, payoutBankAccountId, chain, asset, confirm }) => {
+        const body = { payoutBankAccountId, depositAsset: { chain, name: asset } };
+        const gate = evaluateWriteGate(confirm, env);
+        if (!gate.armed) {
+            return jsonResult(buildDryRun("create_payout_route", "POST", "finance", `/accounts/${accountId}/payout-routes`, body, gate));
+        }
+        try {
+            return executionResult(gate, await client.createPayoutRoute(accountId, body));
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("prepare_payout_ownership_proof", {
+        title: "Prepare route ownership proof",
+        description: "Get the message the route's funding wallet must sign (finance POST " +
+            "/v1/accounts/{accountId}/payout-routes/{routeId}/ownership-proof/prepare). Takes no " +
+            "body: the server derives the wallet and chain from the route. The signature itself " +
+            "is produced by the wallet owner, never by this server. Dry-run by default.",
+        inputSchema: {
+            accountId: z.string(),
+            routeId: z.string(),
+            confirm: confirmField,
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ accountId, routeId, confirm }) => {
+        const gate = evaluateWriteGate(confirm, env);
+        if (!gate.armed) {
+            return jsonResult(buildDryRun("prepare_payout_ownership_proof", "POST", "finance", `/accounts/${accountId}/payout-routes/${routeId}/ownership-proof/prepare`, {}, gate));
+        }
+        try {
+            return executionResult(gate, await client.preparePayoutOwnershipProof(accountId, routeId));
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("complete_payout_ownership_proof", {
+        title: "Complete route ownership proof",
+        description: "Submit the signed ownership-proof message; on success the route becomes ACTIVE " +
+            "(finance POST /v1/accounts/{accountId}/payout-routes/{routeId}/ownership-proof/complete). " +
+            "Dry-run by default.",
+        inputSchema: {
+            accountId: z.string(),
+            routeId: z.string(),
+            message: z.string().min(1),
+            signature: z.string().min(1),
+            confirm: confirmField,
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ accountId, routeId, confirm, ...body }) => {
+        const gate = evaluateWriteGate(confirm, env);
+        if (!gate.armed) {
+            return jsonResult(buildDryRun("complete_payout_ownership_proof", "POST", "finance", `/accounts/${accountId}/payout-routes/${routeId}/ownership-proof/complete`, body, gate));
+        }
+        try {
+            return executionResult(gate, await client.completePayoutOwnershipProof(accountId, routeId, body));
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("request_payout", {
+        title: "Request a payout",
+        description: "Move crypto out of the account and settle fiat to the route's beneficiary bank " +
+            "account (finance POST /v1/accounts/{accountId}/payouts). Requires an ACTIVE payout " +
+            "route. This is money leaving the platform. Dry-run by default.",
+        inputSchema: {
+            accountId: z.string(),
+            payoutRouteId: z.string(),
+            cryptoAmount: z.number().positive(),
+            idempotencyKey: z
+                .string()
+                .optional()
+                .describe("UUID; generated when omitted"),
+            confirm: confirmField,
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ accountId, confirm, ...rest }) => {
+        const body = {
+            payoutRouteId: rest.payoutRouteId,
+            cryptoAmount: rest.cryptoAmount,
+            idempotencyKey: rest.idempotencyKey ?? crypto.randomUUID(),
+        };
+        const gate = evaluateWriteGate(confirm, env);
+        if (!gate.armed) {
+            const dryRun = buildDryRun("request_payout", "POST", "finance", `/accounts/${accountId}/payouts`, body, gate);
+            dryRun.note += " Payouts are outbound money movement; the route must be ACTIVE.";
+            return jsonResult(dryRun);
+        }
+        try {
+            return executionResult(gate, await client.requestPayout(accountId, body));
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
 }

package/dist/types.d.ts

@@ -10,19 +10,27 @@ 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 AddressInput = FinanceSchemas["AddressDto"];
+export type Party = FinanceSchemas["PartyDto"];
 export type CreatePartyInput = FinanceSchemas["CreatePartyRequest"];
-export type Account = FinanceSchemas["Account"];
+export type Account = FinanceSchemas["AccountListItemDto"];
 export type CreateAccountInput = FinanceSchemas["CreateAccountRequest"];
-export type Wallet = FinanceSchemas["Wallet"];
-export type VirtualBankAccount = FinanceSchemas["VirtualBankAccount"];
+export type Wallet = FinanceSchemas["WalletBalanceDto"];
+export type VirtualBankAccount = FinanceSchemas["VirtualBankAccountResponse"];
 export type CreateVirtualBankAccountInput = FinanceSchemas["CreateVirtualBankAccountRequest"];
-export type PaymentSession = FinanceSchemas["PaymentSession"];
-export type CreatePayInSessionRequest = FinanceSchemas["CreatePayInSessionRequest"];
-export type Transfer = FinanceSchemas["Transfer"];
+export type PaymentSession = FinanceSchemas["PayInSessionDto"];
+export type CreatePayInSessionRequest = FinanceSchemas["CreatePayInSessionInput"];
+export type Transfer = FinanceSchemas["TransferRequestDto"];
 export type CurrentCreateFiatTransferInput = FinanceSchemas["CreateFiatTransferInput"];
 export type CreateCryptoTransferInput = FinanceSchemas["CreateCryptoTransferInput"];
+export type Payout = FinanceSchemas["PayoutDto"];
+export type CreatePayoutInput = FinanceSchemas["CreatePayoutRequest"];
+export type PayoutRoute = FinanceSchemas["PayoutRouteDto"];
+export type CreatePayoutRouteInput = FinanceSchemas["CreatePayoutRouteRequest"];
+export type PayoutBankAccount = FinanceSchemas["PayoutBankAccountDto"];
+export type RegisterPayoutBankAccountInput = FinanceSchemas["RegisterPayoutBankAccountRequest"];
+export type PayoutOwnershipProof = FinanceSchemas["PayoutOwnershipProofDto"];
+export type CompleteOwnershipProofInput = FinanceSchemas["CompletePayoutOwnershipProofRequest"];
 export type RampRequestDto = FundflowSchemas["RampRequestDto"];
 export type RampRequestListItem = FundflowSchemas["RampRequestListItem"];
 export type OptimisticLockingBody = FundflowSchemas["UpdateWithOptimisticLockingRequest"];
@@ -118,5 +126,18 @@ export interface VenlyClient {
     approveRampRequest(id: string, body: OptimisticLockingBody): Promise<RampRequestDto>;
     rejectRampRequest(id: string, body: OptimisticLockingBody): Promise<RampRequestDto>;
     createPayInSession(accountId: string, body: CreatePayInSessionRequest): Promise<PaymentSession>;
+    listPayouts(accountId: string, params?: {
+        page?: number;
+        size?: number;
+        status?: string;
+    }): Promise<Payout[]>;
+    getPayout(accountId: string, payoutId: string): Promise<Payout>;
+    requestPayout(accountId: string, body: CreatePayoutInput): Promise<Payout>;
+    listPayoutRoutes(accountId: string): Promise<PayoutRoute[]>;
+    createPayoutRoute(accountId: string, body: CreatePayoutRouteInput): Promise<PayoutRoute>;
+    preparePayoutOwnershipProof(accountId: string, routeId: string): Promise<PayoutOwnershipProof>;
+    completePayoutOwnershipProof(accountId: string, routeId: string, body: CompleteOwnershipProofInput): Promise<PayoutRoute>;
+    listPayoutBankAccounts(partyId: string): Promise<PayoutBankAccount[]>;
+    registerPayoutBankAccount(partyId: string, body: RegisterPayoutBankAccountInput): Promise<PayoutBankAccount>;
 }
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venlyfinance/settlement-mcp",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Venly Finance MCP: SDK-backed tools, resources and prompts for building international money products safely.",
   "type": "module",
   "bin": {
@@ -27,7 +27,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@venlyfinance/sdk": "^0.2.0",
+    "@venlyfinance/sdk": "^0.4.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^3.23.8"
   },
@@ -60,4 +60,4 @@
     "eur",
     "viban"
   ]
-}
+}