@venlyfinance/settlement-mcp 0.4.1 → 0.6.0

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,17 +1,19 @@
 {
   "name": "@venlyfinance/settlement-mcp",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Venly Finance MCP: SDK-backed tools, resources and prompts for building international money products safely.",
   "type": "module",
   "bin": {
     "venly-finance-mcp": "dist/index.js",
-    "venly-settlement-mcp": "dist/index.js"
+    "venly-settlement-mcp": "dist/index.js",
+    "settlement-mcp": "dist/index.js"
   },
   "main": "dist/index.js",
   "files": [
     "dist",
     "scripts",
     "skills",
+    "AGENTS.md",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -27,7 +29,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@venlyfinance/sdk": "^0.2.0",
+    "@venlyfinance/sdk": "^0.4.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^3.23.8"
   },