@venlyfinance/settlement-mcp 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Domain types + the injectable VenlyClient interface.
+ *
+ * These shapes are a minimal projection of the vendored OpenAPI specs at
+ * projects/venly-docs-rebuild/api-reference/finance.yaml (servers:
+ * https://api.venlyfinance.com/api/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.
+ */
+/** 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 payment link (finance PaymentLink). */
+export interface PaymentLink {
+    id: string;
+    accountId?: string;
+    paymentUrl?: string;
+    externalRef?: string;
+    status?: string;
+    [key: string]: unknown;
+}
+/**
+ * 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
+ * Release 1 specs), matched against a vIBAN referenceCode during reconciliation.
+ */
+export interface ObservedBankTransaction {
+    /** The reference code carried in the payment (payment reference / remittance). */
+    referenceCode: string;
+    amount: number;
+    currency: string;
+    remitterName?: string;
+    valueDate?: string;
+    bankTransactionId?: string;
+}
+/** Query params for listing ramp requests (fundflow getAll). */
+export interface ListRampRequestsParams {
+    rampType?: RampType;
+    status?: RampStatus;
+    fromDate?: string;
+    toDate?: string;
+    paymentReference?: string;
+    page?: number;
+    size?: number;
+}
+/** Body for the fiat transfer POST (finance CreateFiatTransferInput). */
+export interface CreateFiatTransferInput {
+    receiverAccountId: string;
+    receiverExternalId?: string;
+    fiatAmount: string;
+    fiatCurrency: string;
+    cryptocurrency?: string;
+    description?: string;
+    merchantReference?: string;
+}
+/** Body for approve/reject (fundflow UpdateWithOptimisticLockingRequest). */
+export interface OptimisticLockingBody {
+    version: number;
+}
+/** Body for the payment link POST (finance CreatePaymentLinkRequest). */
+export interface CreatePaymentLinkRequest {
+    inAmount: string;
+    inCurrency: string;
+    outCryptocurrency?: string;
+    redirectUrl?: string;
+    externalRef?: string;
+    metadata?: Record<string, 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.
+ */
+export interface VenlyClient {
+    listRampRequests(params?: ListRampRequestsParams): Promise<RampRequestListItem[]>;
+    getRampRequest(id: string): Promise<RampRequestDto>;
+    getAccount(accountId: string): Promise<Account>;
+    listVirtualBankAccounts(accountId: string): Promise<VirtualBankAccount[]>;
+    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>;
+    createFiatTransfer(senderAccountId: string, body: CreateFiatTransferInput): Promise<Transfer>;
+    approveRampRequest(id: string, body: OptimisticLockingBody): Promise<RampRequestDto>;
+    rejectRampRequest(id: string, body: OptimisticLockingBody): Promise<RampRequestDto>;
+    createPaymentLink(accountId: string, body: CreatePaymentLinkRequest): Promise<PaymentLink>;
+}

package/dist/types.js

@@ -0,0 +1,17 @@
+/**
+ * Domain types + the injectable VenlyClient interface.
+ *
+ * These shapes are a minimal projection of the vendored OpenAPI specs at
+ * projects/venly-docs-rebuild/api-reference/finance.yaml (servers:
+ * https://api.venlyfinance.com/api/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.
+ */
+export {};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@venlyfinance/settlement-mcp",
+  "version": "0.1.0",
+  "description": "Venly Settlement MCP server. Human-gated operator surface over the Venly Finance and Fundflow APIs, plus an x402 machine-to-machine quote stub. Read-only by default, write tools fail closed.",
+  "type": "module",
+  "bin": {
+    "venly-settlement-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "skills",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "test": "node --import tsx --test test/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/timdierckxsens/venly-sdk.git",
+    "directory": "settlement-mcp"
+  },
+  "homepage": "https://github.com/timdierckxsens/venly-sdk/tree/main/settlement-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/timdierckxsens/venly-sdk/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "stablecoin",
+    "settlement",
+    "payments",
+    "x402",
+    "venly",
+    "fintech",
+    "eur",
+    "viban"
+  ]
+}

package/skills/four-eyes-approval.md

@@ -0,0 +1,39 @@
+# Skill: Walk a ramp through four-eyes approval
+
+Move a ramp request from `AWAITING_APPROVAL` to `AWAITING_FUNDS` (approve) or to
+`REJECTED` (reject), preserving four-eyes control.
+
+## When to use
+
+A Company Manager created a ramp request. A Company Admin (a different identity)
+must review and approve or reject it.
+
+## Tools
+
+- `list_ramp_requests` (read)
+- `get_ramp_request` (read)
+- `approve_ramp_request` (write, disarmed by default)
+- `reject_ramp_request` (write, disarmed by default)
+
+## Steps
+
+1. `list_ramp_requests` with `status: "AWAITING_APPROVAL"` to find pending
+   requests. Note `id` and `createdBy`.
+2. `get_ramp_request` for the chosen `id`. Read the amounts, the `paymentReference`,
+   and the `version`. The `version` is required for the optimistic-locking write.
+3. Decide. Four-eyes: the approving identity must differ from `createdBy`. The
+   Fundflow API enforces this; the tool surfaces the state, it does not bypass it.
+4. Call `approve_ramp_request` (or `reject_ramp_request`) with `id` and the
+   `version` from step 2.
+   - By default the tool returns a dry-run object showing the exact POST it would
+     send. Review it.
+   - To execute live, all three must hold: `confirm: true`, `VENLY_MCP_LIVE=1`,
+     and credentials present. Arming is a deliberate human decision.
+5. On a version conflict (HTTP 409) in live mode, re-fetch with `get_ramp_request`
+   to get the new `version` and retry.
+
+## Notes
+
+- Approve transitions `AWAITING_APPROVAL` to `AWAITING_FUNDS`. Reject transitions
+  to `REJECTED`.
+- The dry-run is the safe default. Read the request body before arming.

package/skills/payment-link-lifecycle.md

@@ -0,0 +1,44 @@
+# Skill: Create and track a payment link
+
+Stand up a fiat-to-crypto payment link for an account, hand the URL to a payer,
+and follow the payment through to settlement.
+
+## When to use
+
+An operator wants to collect a fiat payment that settles as stablecoin into an
+account's wallet, without building a checkout: invoicing, one-off B2B
+collections, top-ups.
+
+## Tools
+
+- `get_account` (read)
+- `list_virtual_bank_accounts` (read)
+- `create_payment_link` (write, disarmed by default)
+- `get_transfer` (read)
+
+## Steps
+
+1. `get_account` for the collecting account. Confirm `status: "ACTIVE"` - an
+   unverified or suspended account cannot collect.
+2. Optional context: `list_virtual_bank_accounts` shows the account's existing
+   collection surfaces (IBAN + referenceCode); a payment link is the hosted
+   alternative for payers who won't do a bank transfer.
+3. `create_payment_link` with the `accountId` and an `externalRef` your own
+   system can reconcile on later.
+   - By default the tool returns a dry-run object with the exact POST it would
+     send. Review it.
+   - Live execution needs all three: `confirm: true`, `VENLY_MCP_LIVE=1`, and
+     credentials present.
+4. Share the returned `paymentUrl` with the payer. Status starts at `CREATED` /
+   `PENDING_PAYMENT`.
+5. After payment, the received fiat converts and lands on-chain. Track the
+   resulting movement with `get_transfer` and reconcile on your `externalRef`.
+
+## Notes
+
+- Payment links expire (`expiresAt`); a link that was never paid ends at
+  `EXPIRED`, not `FAILED`.
+- Statuses walk `CREATED → PENDING_PAYMENT → PAYMENT_RECEIVED → CONVERTING →
+  MINTING → COMPLETED`, with `FAILED`, `CANCELLED`, `REFUNDING`, `REFUNDED` as
+  exits. Only treat `COMPLETED` as settled.
+- The dry-run is the safe default. Read the request body before arming.

package/skills/reconcile-by-reference-code.md

@@ -0,0 +1,40 @@
+# Skill: Reconcile a EUR payment by referenceCode
+
+Match an incoming EUR bank payment on a virtual IBAN (vIBAN) to the vIBAN that
+issued its reference code, using only read tools. No mutation.
+
+## When to use
+
+An operator sees an incoming EUR transfer (from a bank feed, statement, or
+notification) and needs to know which account and vIBAN it belongs to, and
+whether the expected funds have arrived.
+
+## Tools
+
+- `list_virtual_bank_accounts` (read)
+- `reconcile_by_reference_code` (read, composite)
+
+## Steps
+
+1. Identify the settlement `accountId` in question.
+2. Collect the observed incoming transactions. Each needs at least a
+   `referenceCode`, `amount`, and `currency` (add `remitterName`, `valueDate`,
+   `bankTransactionId` when available).
+3. Call `reconcile_by_reference_code` with `accountId`, the target
+   `referenceCode`, and the `transactions` array. The tool fetches the account's
+   vIBANs and matches.
+4. Read the result:
+   - `matched: true` plus a `virtualBankAccount` and `matchedTransactions`: the
+     payment is reconciled. `totalAmount` is the summed value.
+   - `matched: false` with a `virtualBankAccount` but no transactions: the vIBAN
+     exists, funds have not arrived. Awaiting funds.
+   - `matched: false` with `virtualBankAccount: null` but transactions present:
+     the payment references a code no vIBAN on this account carries. Possible
+     misdirected payment, investigate.
+
+## Notes
+
+- There is no list-vIBAN-transactions endpoint in Release 1, so the transactions
+  are supplied by the operator or an upstream bank feed. The tool does the
+  matching, not the fetching of bank transactions.
+- Read-only. This skill never approves, transfers, or mutates anything.

package/skills/stage-and-confirm-transfer.md

@@ -0,0 +1,39 @@
+# Skill: Stage and confirm a transfer
+
+Prepare a fiat-to-crypto transfer, review the exact request, then execute it only
+behind the explicit confirm and arming gate.
+
+## When to use
+
+An operator needs to move funds from a sender account to a receiver, converting
+fiat to crypto.
+
+## Tools
+
+- `get_account` (read)
+- `stage_transfer` (write, disarmed by default)
+- `get_transfer` (read)
+
+## Steps
+
+1. `get_account` for the `senderAccountId` to confirm it is active.
+2. Stage the transfer: call `stage_transfer` with `senderAccountId`,
+   `receiverAccountId`, `fiatAmount` (decimal string), `fiatCurrency`, and
+   optionally `cryptocurrency`, `description`, `merchantReference`. Omit
+   `confirm` (or set it false).
+3. The tool returns a dry-run object: the exact `POST /accounts/{senderAccountId}/transfers/fiat`
+   body it would send, plus the gate decision. Review the amount, currency, and
+   receiver.
+4. To execute live, re-call with `confirm: true` AND the server armed with
+   `VENLY_MCP_LIVE=1` AND credentials present. If any leg is missing, the tool
+   dry-runs again and does not touch the API.
+5. After a live execution, use `get_transfer` with the returned account and
+   transfer id to confirm status.
+
+## Notes
+
+- Dry-run first is the default and the safe path. Confirm and arming are separate,
+  deliberate steps.
+- Idempotency keys are handled by the transport on live POSTs.
+- The fiat transfer endpoint is documented in the rebuild specs but marked a stub
+  pending live annotation. Cross-check the live schema before a production run.

package/skills/x402-quote-walkthrough.md

@@ -0,0 +1,39 @@
+# Skill: Read an x402 settlement quote
+
+Get an HTTP-402-shaped quote for a settlement action and understand what each
+field commits to, without moving any funds.
+
+## When to use
+
+An agent (or an operator evaluating agent payments) wants to know what a
+machine-to-machine settlement over the x402 rail would cost and where it would
+pay, before any decision to execute anything.
+
+## Tools
+
+- `quote_x402_payment` (stub - never executes, never calls a facilitator)
+- `get_reference_data` (read; chains and currencies for context)
+
+## Steps
+
+1. Call `quote_x402_payment` with the settlement action you are pricing.
+2. Read the returned `PaymentRequirements`-shaped quote:
+   - `price`: the amount the counterparty would require.
+   - `asset`: the settlement asset (typically USDC).
+   - `payTo`: the receiving address.
+   - `chain`: where settlement would occur (CAIP-2 style network reference).
+3. Cross-check `chain` and `asset` against `get_reference_data` - a quote on an
+   unsupported chain/currency pair is a configuration error, not an offer.
+4. Stop. This tool states Venly's position on the x402 rail; it does not settle.
+
+## Notes
+
+- Position of record: the MCP is the human-gated operator surface; x402 is the
+  machine-to-machine rail. This server ships the quote shape so integrators can
+  build against it today.
+- Live x402 settlement requires a facilitator decision (who submits the signed
+  payment on-chain, under whose licence) that deliberately sits outside this
+  server. No `confirm` flag, no env var, and no credential arms this tool into
+  executing - it has no execution path.
+- The x402 pattern: a server answers `402 Payment Required` with these fields;
+  the payer signs (EIP-3009/Permit2 style) and a facilitator submits on-chain.