@venlyfinance/settlement-mcp 0.1.0 → 0.1.1

package/README.md

@@ -9,16 +9,18 @@ x402, the machine-to-machine agent-payments rail.
 The differentiator: the MCP is the human-gated operator surface; x402 is the
 machine-to-machine rail. Read-only by default, write tools fail closed.
 
-Status: v0.1.0. Read tools work against staging out of the box once credentials
-are set; write tools are shipped disarmed and fail closed (see the safety model).
-The x402 tool is a stub that states a position, it moves no funds.
+Status: v0.1.1 (realigned to the live published OpenAPI specs: staging base URL
+and auth host corrected, `create_payment_link` became `create_payment_session`
+to match the live API). Read tools work against staging out of the box once
+credentials are set; write tools are shipped disarmed and fail closed (see the
+safety model). The x402 tool is a stub that states a position, it moves no funds.
 
 ## What it is
 
 - Built on the official MCP TypeScript SDK (`@modelcontextprotocol/sdk`), Node
   >= 18, stdio transport.
 - A thin layer over the Venly Finance API (`finance.yaml`, servers
-  `https://api.venlyfinance.com/api/v1`) and the Fundflow API (`fundflow.yaml`,
+  `https://api.venlyfinance.com/v1`) and the Fundflow API (`fundflow.yaml`,
   servers `https://api-fundflow.venly.io`). Endpoint truth is the published API
   reference at [docs.venlyfinance.com](https://docs.venlyfinance.com/api-reference).
 - Transport is injected through the `VenlyClient` interface (`src/types.ts`).
@@ -57,7 +59,7 @@ matched vIBAN, the matched transactions, and the total amount.
 ### 2. Write tools (present, DISARMED by default)
 
 `stage_transfer`, `approve_ramp_request`, `reject_ramp_request`,
-`create_payment_link`.
+`create_payment_session`.
 
 Each is dry-run by default and returns the exact request it would send. See the
 safety model below.
@@ -134,7 +136,7 @@ MCP client config example:
       "command": "node",
       "args": ["/absolute/path/to/settlement-mcp/dist/index.js"],
       "env": {
-        "VENLY_FINANCE_BASE_URL": "https://api-staging.venlyfinance.com/api/v1",
+        "VENLY_FINANCE_BASE_URL": "https://api-staging.venlyfinance.com/v1",
         "VENLY_FUNDFLOW_BASE_URL": "https://api-fundflow-staging.venly.io"
       }
     }
@@ -149,9 +151,9 @@ Override via env:
 
 | Env var | Default (staging) |
 |---|---|
-| `VENLY_FINANCE_BASE_URL` | `https://api-staging.venlyfinance.com/api/v1` |
+| `VENLY_FINANCE_BASE_URL` | `https://api-staging.venlyfinance.com/v1` |
 | `VENLY_FUNDFLOW_BASE_URL` | `https://api-fundflow-staging.venly.io` |
-| `VENLY_TOKEN_URL` | `https://login.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token` |
+| `VENLY_TOKEN_URL` | `https://login-staging.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token` (staging; use `login.venly.io` for production) |
 | `VENLY_CLIENT_ID` | unset (read-only until set) |
 | `VENLY_CLIENT_SECRET` | unset |
 | `VENLY_MCP_LIVE` | unset (writes disarmed) |
@@ -186,7 +188,7 @@ MCP-consumable workflow docs under `skills/`:
 - `reconcile-by-reference-code.md`
 - `four-eyes-approval.md`
 - `stage-and-confirm-transfer.md`
-- `payment-link-lifecycle.md`
+- `payment-session-lifecycle.md`
 - `x402-quote-walkthrough.md`
 
 ## Layout
@@ -213,7 +215,7 @@ settlement-mcp/
     reconcile-by-reference-code.md
     four-eyes-approval.md
     stage-and-confirm-transfer.md
-    payment-link-lifecycle.md
+    payment-session-lifecycle.md
     x402-quote-walkthrough.md
     four-eyes-approval.md
     stage-and-confirm-transfer.md

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

@@ -15,7 +15,7 @@
  *    when a write method is invoked, and write methods are invoked only after
  *    the gate in safety.ts is armed. Read-only by default is enforced upstream.
  */
-import type { Account, CreateFiatTransferInput, CreatePaymentLinkRequest, ListRampRequestsParams, OptimisticLockingBody, Party, PaymentLink, RampRequestDto, RampRequestListItem, Transfer, VenlyClient, VirtualBankAccount } from "../types.js";
+import type { Account, CreateFiatTransferInput, CreatePayInSessionRequest, ListRampRequestsParams, OptimisticLockingBody, Party, PaymentSession, RampRequestDto, RampRequestListItem, Transfer, VenlyClient, VirtualBankAccount } from "../types.js";
 export interface HttpVenlyClientConfig {
     financeBaseUrl?: string;
     fundflowBaseUrl?: string;
@@ -54,5 +54,5 @@ export declare class HttpVenlyClient implements VenlyClient {
     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>;
+    createPayInSession(accountId: string, body: CreatePayInSessionRequest): Promise<PaymentSession>;
 }

package/dist/client/http-client.js

@@ -157,7 +157,7 @@ export class HttpVenlyClient {
             body,
         });
     }
-    createPaymentLink(accountId, body) {
-        return this.request(this.financeBaseUrl, "POST", `/accounts/${accountId}/fiat-to-crypto/payment-links`, { body });
+    createPayInSession(accountId, body) {
+        return this.request(this.financeBaseUrl, "POST", `/accounts/${accountId}/fiat-to-crypto/payment-sessions`, { body });
     }
 }

package/dist/constants.d.ts

@@ -1,13 +1,13 @@
 /** Shared constants. Defaults point at STAGING so an accidental run never
  * touches production. Override via env for a real sandbox test. */
 export declare const SERVER_NAME = "venly-settlement-mcp-server";
-export declare const SERVER_VERSION = "0.1.0";
+export declare const SERVER_VERSION = "0.1.1";
 /** The env flag that must equal "1" for any write tool to execute live. */
 export declare const LIVE_FLAG = "VENLY_MCP_LIVE";
 /** Default base URLs (STAGING). Production values live in the vendored specs:
- * finance https://api.venlyfinance.com/api/v1, fundflow https://api-fundflow.venly.io */
-export declare const DEFAULT_FINANCE_BASE_URL = "https://api-staging.venlyfinance.com/api/v1";
+ * finance https://api.venlyfinance.com/v1, fundflow https://api-fundflow.venly.io */
+export declare const DEFAULT_FINANCE_BASE_URL = "https://api-staging.venlyfinance.com/v1";
 export declare const DEFAULT_FUNDFLOW_BASE_URL = "https://api-fundflow-staging.venly.io";
-export declare const DEFAULT_TOKEN_URL = "https://login.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token";
+export declare const DEFAULT_TOKEN_URL = "https://login-staging.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token";
 /** Cap on serialized tool output length to keep responses readable. */
 export declare const CHARACTER_LIMIT = 30000;

package/dist/constants.js

@@ -1,13 +1,13 @@
 /** Shared constants. Defaults point at STAGING so an accidental run never
  * touches production. Override via env for a real sandbox test. */
 export const SERVER_NAME = "venly-settlement-mcp-server";
-export const SERVER_VERSION = "0.1.0";
+export const SERVER_VERSION = "0.1.1";
 /** The env flag that must equal "1" for any write tool to execute live. */
 export const LIVE_FLAG = "VENLY_MCP_LIVE";
 /** Default base URLs (STAGING). Production values live in the vendored specs:
- * finance https://api.venlyfinance.com/api/v1, fundflow https://api-fundflow.venly.io */
-export const DEFAULT_FINANCE_BASE_URL = "https://api-staging.venlyfinance.com/api/v1";
+ * finance https://api.venlyfinance.com/v1, fundflow https://api-fundflow.venly.io */
+export const DEFAULT_FINANCE_BASE_URL = "https://api-staging.venlyfinance.com/v1";
 export const DEFAULT_FUNDFLOW_BASE_URL = "https://api-fundflow-staging.venly.io";
-export const DEFAULT_TOKEN_URL = "https://login.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token";
+export const DEFAULT_TOKEN_URL = "https://login-staging.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token";
 /** Cap on serialized tool output length to keep responses readable. */
 export const CHARACTER_LIMIT = 30_000;

package/dist/tools/write-tools.js

@@ -124,17 +124,24 @@ export function registerWriteTools(server, client, env) {
             return errorResult(e.message);
         }
     });
-    server.registerTool("create_payment_link", {
-        title: "Create a fiat-to-crypto payment link (dry-run by default)",
-        description: "Create a pay-in link (finance POST /accounts/{accountId}/fiat-to-crypto/payment-links). " +
-            "DISARMED by default.",
+    server.registerTool("create_payment_session", {
+        title: "Create a fiat-to-crypto payment session (dry-run by default)",
+        description: "Create a hosted pay-in session (finance POST " +
+            "/accounts/{accountId}/fiat-to-crypto/payment-sessions); redirect the " +
+            "payer to the returned paymentUrl. DISARMED by default.",
         inputSchema: {
             accountId: z.string(),
             inAmount: z.string().describe("Decimal string, e.g. \"250.00\""),
             inCurrency: z.string().describe("e.g. EUR"),
-            outCryptocurrency: z.string().optional().describe("e.g. USDC"),
-            redirectUrl: z.string().optional(),
+            outCryptocurrency: z.string().describe("e.g. USDC"),
+            callbackUrl: z.string().describe("Webhook URL notified on completion"),
+            successRedirectUrl: z.string().optional(),
+            failureRedirectUrl: z.string().optional(),
             externalRef: z.string().optional(),
+            idempotencyKey: z
+                .string()
+                .optional()
+                .describe("UUID; generated when omitted"),
             confirm: confirmField,
         },
         annotations: WRITE_ANNOTATIONS,
@@ -144,14 +151,17 @@ export function registerWriteTools(server, client, env) {
             inAmount: rest.inAmount,
             inCurrency: rest.inCurrency,
             outCryptocurrency: rest.outCryptocurrency,
-            redirectUrl: rest.redirectUrl,
+            callbackUrl: rest.callbackUrl,
+            successRedirectUrl: rest.successRedirectUrl,
+            failureRedirectUrl: rest.failureRedirectUrl,
             externalRef: rest.externalRef,
+            idempotencyKey: rest.idempotencyKey ?? crypto.randomUUID(),
         };
         if (!gate.armed) {
-            return jsonResult(buildDryRun("create_payment_link", "POST", "finance", `/accounts/${accountId}/fiat-to-crypto/payment-links`, body, gate));
+            return jsonResult(buildDryRun("create_payment_session", "POST", "finance", `/accounts/${accountId}/fiat-to-crypto/payment-sessions`, body, gate));
         }
         try {
-            const result = await client.createPaymentLink(accountId, body);
+            const result = await client.createPayInSession(accountId, body);
             return jsonResult({ mode: "live", result });
         }
         catch (e) {

package/dist/types.d.ts

@@ -1,9 +1,9 @@
 /**
  * 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:
+ * 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.
@@ -94,8 +94,8 @@ export interface Party {
     status?: string;
     [key: string]: unknown;
 }
-/** A payment link (finance PaymentLink). */
-export interface PaymentLink {
+/** A fiat-to-crypto payment session (finance PaymentSession). */
+export interface PaymentSession {
     id: string;
     accountId?: string;
     paymentUrl?: string;
@@ -141,12 +141,15 @@ export interface CreateFiatTransferInput {
 export interface OptimisticLockingBody {
     version: number;
 }
-/** Body for the payment link POST (finance CreatePaymentLinkRequest). */
-export interface CreatePaymentLinkRequest {
+/** Body for the payment session POST (finance CreatePayInSessionRequest). */
+export interface CreatePayInSessionRequest {
     inAmount: string;
     inCurrency: string;
-    outCryptocurrency?: string;
-    redirectUrl?: string;
+    outCryptocurrency: string;
+    callbackUrl: string;
+    idempotencyKey: string;
+    successRedirectUrl?: string;
+    failureRedirectUrl?: string;
     externalRef?: string;
     metadata?: Record<string, string>;
 }
@@ -173,5 +176,5 @@ export interface VenlyClient {
     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>;
+    createPayInSession(accountId: string, body: CreatePayInSessionRequest): Promise<PaymentSession>;
 }

package/dist/types.js

@@ -1,9 +1,9 @@
 /**
  * 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:
+ * 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venlyfinance/settlement-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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": {

package/skills/{payment-link-lifecycle.md → payment-session-lifecycle.md}

@@ -1,6 +1,6 @@
-# Skill: Create and track a payment link
+# Skill: Create and track a fiat-to-crypto payment session
 
-Stand up a fiat-to-crypto payment link for an account, hand the URL to a payer,
+Stand up a hosted pay-in session for an account, hand the URL to a payer,
 and follow the payment through to settlement.
 
 ## When to use
@@ -13,7 +13,7 @@ collections, top-ups.
 
 - `get_account` (read)
 - `list_virtual_bank_accounts` (read)
-- `create_payment_link` (write, disarmed by default)
+- `create_payment_session` (write, disarmed by default)
 - `get_transfer` (read)
 
 ## Steps
@@ -21,10 +21,11 @@ collections, top-ups.
 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
+   collection surfaces (IBAN + referenceCode); a payment session 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.
+3. `create_payment_session` with the `accountId`, a `callbackUrl` your system
+   will receive the completion webhook on, and an `externalRef` you can
+   reconcile on later. An `idempotencyKey` is generated when you don't pass one.
    - 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
@@ -36,7 +37,7 @@ collections, top-ups.
 
 ## Notes
 
-- Payment links expire (`expiresAt`); a link that was never paid ends at
+- Payment sessions expire (`expiresAt`); a session 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