@definitive-fi/mcp 1.2.0 → 1.3.0

package/README.md

@@ -33,5 +33,5 @@ New to Definitive? Visit the [Definitive API documentation](https://ddp.definiti
 | `DEFINITIVE_API_KEY` | Yes | Your Definitive API key |
 | `DEFINITIVE_API_SECRET` | Yes | Your Definitive API secret |
 | `DEFINITIVE_API_KEY_TYPE` | Yes | Key type: `"portfolio"` or `"organization"` |
-| `DEFINITIVE_BASE_URL` | No | API base URL |
+| `DEFINITIVE_BASE_URL` | No | API base URL. Must use `https`; defaults to `https://ddp.definitive.fi`. A different host prints a warning at startup |
 | `DEFINITIVE_PORTFOLIO_ID` | No | Portfolio ID (required for organization keys when targeting a specific portfolio) |

package/dist/server.js

@@ -76,16 +76,28 @@ function createClient(baseUrl, apiKey, apiSecret) {
         };
       }
       if (!response.ok) {
+        const issues = validationIssues(response.status, json);
         return {
           error: true,
           status_code: response.status,
-          message: typeof json === "object" && json !== null && "message" in json ? String(json.message) : response.statusText
+          message: typeof json === "object" && json !== null && "message" in json ? String(json.message) : response.statusText,
+          ...issues && { details: issues }
         };
       }
       return json;
     }
   };
 }
+function validationIssues(status, json) {
+  if (status !== 400 || typeof json !== "object" || json === null) {
+    return;
+  }
+  const error = "error" in json ? json.error : undefined;
+  if (typeof error !== "object" || error === null || !("issues" in error)) {
+    return;
+  }
+  return Array.isArray(error.issues) ? error.issues : undefined;
+}
 
 
 function resolvePortfolioRoute(keyType, suffix, portfolioId, defaultPortfolioId) {
@@ -103,29 +115,16 @@ function resolvePortfolioRoute(keyType, suffix, portfolioId, defaultPortfolioId)
 import { z } from "zod";
 var zUUID = z.string().uuid();
 var portfolioIdParam = zUUID.optional().describe("Portfolio UUID (required for organization keys without a default)");
-var ChainEnum = z.enum([
-  "arbitrum",
-  "avalanche",
-  "base",
-  "blast",
-  "bsc",
-  "ethereum",
-  "optimism",
-  "polygon",
-  "solana",
-  "hyperevm",
-  "plasma",
-  "monad",
-  "robinhood",
-  "ink"
-]);
+var chainParam = (label) => z.string().min(1).describe(`${label}, lowercase (e.g. ethereum, base, arbitrum, solana)`);
 var jsonResult = (result) => ({
-  content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+  content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+  ...isErrorResult(result) && { isError: true }
 });
+var isErrorResult = (result) => typeof result === "object" && result !== null && ("error" in result) && result.error === true;
 
 
 import { z as z2 } from "zod";
-var perpsSymbolParam = z2.string().min(1).max(32).describe('Perps market symbol. Qualify with the subvenue when the base symbol is ambiguous, e.g. "native:BTC" (core exchange) — a bare symbol works only when exactly one market uses it');
+var perpsSymbolParam = z2.string().min(1).max(32).regex(/^[A-Za-z0-9:._-]+$/, "must contain only letters, digits, and : . _ -").describe('Perps market symbol. Qualify with the subvenue when the base symbol is ambiguous, e.g. "native:BTC" (core exchange) — a bare symbol works only when exactly one market uses it');
 var MIN_EPOCH_MS = 1600000000000;
 var MAX_EPOCH_MS = 4102444800000;
 var epochMsParam = () => z2.number().int().min(MIN_EPOCH_MS).max(MAX_EPOCH_MS);
@@ -232,6 +231,125 @@ function registerPerpsReadTools(server, client, keyType, defaultPortfolioId) {
     return jsonResult(result);
   });
 }
+var evmAddressParam = z2.string().regex(/^0x[a-fA-F0-9]{40}$/, "must be a 0x-prefixed 20-byte hex address");
+var hex32Param = z2.string().regex(/^0x[a-fA-F0-9]{64}$/, "must be a 0x-prefixed 32-byte hex string");
+var depositFields = {
+  source_vault_id: zUUID.describe("Trading vault that sends the funds: vaults[].vaultId from get_portfolio"),
+  destination_portfolio_id: zUUID.describe("Portfolio whose perps account receives the funds; it must already have a perps account (see perps_get_account_status)"),
+  from_asset_address: z2.string().min(1).describe("Contract address of the asset to send, on the source vault's chain"),
+  from_amount: decimalStringParam.describe('Amount of the asset to send, decimal string (e.g. "250")'),
+  portfolio_id: portfolioIdParam
+};
+function registerPerpsWriteTools(server, client, keyType, defaultPortfolioId) {
+  const resolve = (suffix, portfolioId) => resolvePortfolioRoute(keyType, `perps/${suffix}`, portfolioId, defaultPortfolioId);
+  server.tool("perps_preview_order", "Validate a proposed perps order against the live account and preview its cost, margin, and fees. Nothing is placed. Requires a WRITE-scoped key.", {
+    symbol: perpsSymbolParam,
+    side: z2.enum(["buy", "sell"]).describe("Order side"),
+    order_type: z2.enum([
+      "market",
+      "limit",
+      "stop_market",
+      "stop_limit",
+      "take_profit_market",
+      "take_profit_limit",
+      "twap"
+    ]).describe("Order type"),
+    size: decimalStringParam.describe('Order size in the base asset, decimal string (e.g. "0.5")'),
+    price: decimalStringParam.optional().describe("Limit price, for limit-priced order types"),
+    trigger_price: decimalStringParam.optional().describe("Trigger price, for stop and take-profit order types"),
+    reduce_only: z2.boolean().optional().describe("Only reduce the current position"),
+    leverage: z2.number().int().min(1).max(100).optional().describe("Leverage 1-100; defaults to the account's active leverage"),
+    take_profit: decimalStringParam.optional().describe("Attached take-profit price"),
+    stop_loss: decimalStringParam.optional().describe("Attached stop-loss price"),
+    twap_duration_minutes: z2.number().int().min(5).max(1440).optional().describe("TWAP duration in minutes, 5-1440; required for twap"),
+    portfolio_id: portfolioIdParam
+  }, async ({
+    symbol,
+    side,
+    order_type,
+    size,
+    price,
+    trigger_price,
+    reduce_only,
+    leverage,
+    take_profit,
+    stop_loss,
+    twap_duration_minutes,
+    portfolio_id
+  }) => {
+    const result = await client.request("POST", resolve("orders/preview", portfolio_id), undefined, {
+      symbol,
+      side,
+      orderType: order_type,
+      size,
+      price,
+      triggerPrice: trigger_price,
+      reduceOnly: reduce_only,
+      leverage,
+      takeProfit: take_profit,
+      stopLoss: stop_loss,
+      twapDurationMinutes: twap_duration_minutes
+    });
+    return jsonResult(result);
+  });
+  server.tool("perps_get_withdraw_payload", "Step 1 of a perps withdrawal (perps account -> the portfolio's Arbitrum trading vault, in USDC). Returns EIP-712 typedDataJson and its nonce. The payload must be signed by the perps account owner wallet (accountOwnerAddress from perps_get_account_status); this server cannot sign. Pass the signature to perps_submit_withdraw. Requires a WRITE-scoped key.", {
+    amount: decimalStringParam.describe('USDC amount to withdraw, decimal string (e.g. "250"); the venue deducts its ~$1 fee from it'),
+    destination: evmAddressParam.optional().describe("Arbitrum address to receive the USDC; must be one of the portfolio's Arbitrum trading vaults. Defaults to the portfolio's Arbitrum trading vault"),
+    portfolio_id: portfolioIdParam
+  }, async ({ amount, destination, portfolio_id }) => {
+    const result = await client.request("POST", resolve("withdraw/payload", portfolio_id), undefined, { amount, destination });
+    return jsonResult(result);
+  });
+  server.tool("perps_submit_withdraw", "Step 2 of a perps withdrawal: submit the account owner's signature over the typed data from perps_get_withdraw_payload. amount, destination, and nonce must be exactly the values that step returned. USDC arrives on Arbitrum in about five minutes. Requires a WRITE-scoped key.", {
+    amount: decimalStringParam.describe("Exactly the amount returned by perps_get_withdraw_payload"),
+    destination: evmAddressParam.describe("Exactly the destination returned by perps_get_withdraw_payload"),
+    nonce: epochMsParam().describe("Exactly the nonce returned by perps_get_withdraw_payload"),
+    signature: z2.object({
+      r: hex32Param,
+      s: hex32Param,
+      v: z2.union([z2.literal(27), z2.literal(28)])
+    }).describe("The account owner's EIP-712 signature split into r, s (0x-prefixed 32-byte hex) and v (27 or 28)"),
+    portfolio_id: portfolioIdParam
+  }, async ({ amount, destination, nonce, signature, portfolio_id }) => {
+    const result = await client.request("POST", resolve("withdraw", portfolio_id), undefined, { amount, destination, nonce, signature });
+    return jsonResult(result);
+  });
+  server.tool("perps_get_deposit_quote", "Step 1 of a perps deposit (trading vault -> perps account). Prices the transfer and returns a quoteId plus toAmount, the amount that lands after routing and gas. No wallet signature is needed. Pass the same fields and the quoteId to perps_deposit. Requires a WRITE-scoped key.", depositFields, async ({
+    source_vault_id,
+    destination_portfolio_id,
+    from_asset_address,
+    from_amount,
+    portfolio_id
+  }) => {
+    const result = await client.request("POST", resolve("deposit/vault-fund-hl/quote", portfolio_id), undefined, {
+      sourceVaultId: source_vault_id,
+      destinationPortfolioId: destination_portfolio_id,
+      fromAssetAddress: from_asset_address,
+      fromAmount: from_amount
+    });
+    return jsonResult(result);
+  });
+  server.tool("perps_deposit", "Step 2 of a perps deposit: execute a quote from perps_get_deposit_quote. Repeat the quote's four fields exactly and add its quoteId. Settles asynchronously and returns a requestId; poll perps_get_account for the new balance. Moves real funds. Requires a WRITE-scoped key.", {
+    quote_id: z2.string().min(1).describe("The quoteId returned by perps_get_deposit_quote"),
+    ...depositFields
+  }, async ({
+    quote_id,
+    source_vault_id,
+    destination_portfolio_id,
+    from_asset_address,
+    from_amount,
+    portfolio_id
+  }) => {
+    const result = await client.request("POST", resolve("deposit/vault-fund-hl", portfolio_id), undefined, {
+      quoteId: quote_id,
+      sourceVaultId: source_vault_id,
+      destinationPortfolioId: destination_portfolio_id,
+      fromAssetAddress: from_asset_address,
+      fromAmount: from_amount
+    });
+    return jsonResult(result);
+  });
+}
 
 
 import { z as z3 } from "zod";
@@ -294,7 +412,7 @@ function registerReadTools(server, client, keyType, defaultPortfolioId) {
     return jsonResult(result);
   });
   server.tool("get_deposit_address", "Get a deposit address for a specific blockchain. Creates a vault if one doesn't exist for that chain.", {
-    chain: ChainEnum.describe("Blockchain network name"),
+    chain: chainParam("Blockchain network name"),
     wallet_address: z3.string().min(1).describe("User's wallet address on this chain — ask the user if not provided"),
     portfolio_id: portfolioIdParam
   }, async ({ chain, wallet_address, portfolio_id }) => {
@@ -374,7 +492,7 @@ function registerWriteTools(server, client, keyType, defaultPortfolioId) {
   const resolve = (suffix, portfolioId) => resolvePortfolioRoute(keyType, suffix, portfolioId, defaultPortfolioId);
   server.tool("get_trade_quote", "Get a price quote for a trade order. This is the DEFAULT tool for all trades — use this unless the user explicitly asks for a QuickTrade. Supports market, limit, TWAP, stop, stop-loss, and take-profit order types. This does not execute any trade. Use the returned quote ID with submit_trade to execute.", {
     type: OrderTypeEnum.describe("Order type"),
-    chain: ChainEnum.describe("Blockchain network name"),
+    chain: chainParam("Blockchain network name"),
     target_asset: z4.string().min(1).describe("Target asset contract address"),
     contra_asset: z4.string().min(1).describe("Contra (quote) asset contract address"),
     qty: z4.string().min(1).describe("Order quantity as a decimal string"),
@@ -444,7 +562,7 @@ function registerWriteTools(server, client, keyType, defaultPortfolioId) {
   server.tool("get_quicktrade_quote", "Get a price quote for a QuickTrade market swap. Only use when the user explicitly requests a QuickTrade. This does not execute any trade. Review the quote before executing with the quicktrade tool.", {
     target_asset: z4.string().min(1).describe("Target asset contract address"),
     contra_asset: z4.string().min(1).describe("Contra (quote) asset contract address"),
-    chain: ChainEnum.describe("Blockchain network name"),
+    chain: chainParam("Blockchain network name"),
     qty: z4.string().min(1).describe("Order quantity as a decimal string"),
     order_side: OrderSideEnum.describe("Buy or sell"),
     portfolio_id: portfolioIdParam
@@ -470,9 +588,9 @@ function registerWriteTools(server, client, keyType, defaultPortfolioId) {
   });
   server.tool("bridge_quote", "Get a quote for a cross-chain bridge transfer. This does not move any funds. Review the routes and select a route_id before executing with bridge_submit.", {
     from_asset_address: z4.string().min(1).describe("Source asset contract address"),
-    from_chain: ChainEnum.describe("Source blockchain network"),
+    from_chain: chainParam("Source blockchain network"),
     to_asset_address: z4.string().min(1).describe("Destination asset contract address"),
-    to_chain: ChainEnum.describe("Destination blockchain network"),
+    to_chain: chainParam("Destination blockchain network"),
     from_amount: z4.string().min(1).describe("Amount to bridge as a decimal string"),
     portfolio_id: portfolioIdParam
   }, { readOnlyHint: true }, async ({
@@ -519,7 +637,7 @@ function registerWriteTools(server, client, keyType, defaultPortfolioId) {
   server.tool("submit_trade", "Submit a trade order using a quote from get_trade_quote. This is irreversible — all order types (market, limit, stop, TWAP) may execute immediately. Always show the user the quote details and get confirmation before calling this tool. Pass the same parameters you used for get_trade_quote plus the quote_id.", {
     quote_id: zUUID.describe("Quote UUID from get_trade_quote response (found in quote.quote.id)"),
     type: OrderTypeEnum.describe("Order type"),
-    chain: ChainEnum.describe("Blockchain network name"),
+    chain: chainParam("Blockchain network name"),
     target_asset: z4.string().min(1).describe("Target asset contract address"),
     contra_asset: z4.string().min(1).describe("Contra (quote) asset contract address"),
     qty: z4.string().min(1).describe("Order quantity as a decimal string"),
@@ -595,7 +713,7 @@ function registerWriteTools(server, client, keyType, defaultPortfolioId) {
   server.tool("quicktrade", "Execute a QuickTrade market swap immediately. Only use when the user explicitly requests a QuickTrade. This is irreversible — funds move on-chain once submitted. Call get_quicktrade_quote first and confirm details with the user before executing, unless the user requests to skip the quote step.", {
     target_asset: z4.string().min(1).describe("Target asset contract address"),
     contra_asset: z4.string().min(1).describe("Contra (quote) asset contract address"),
-    chain: ChainEnum.describe("Blockchain network name"),
+    chain: chainParam("Blockchain network name"),
     qty: z4.string().min(1).describe("Order quantity as a decimal string"),
     order_side: OrderSideEnum.describe("Buy or sell"),
     slippage_tolerance: z4.string().optional().describe("Slippage tolerance as a decimal string (e.g. '0.01' for 1%)"),
@@ -636,8 +754,8 @@ function registerWriteTools(server, client, keyType, defaultPortfolioId) {
     return jsonResult(result);
   });
   server.tool("bridge_submit", "Execute a cross-chain bridge transfer. This is irreversible — funds are sent from the source chain to the destination chain. Always call bridge_quote first and confirm the details with the user before executing.", {
-    from_chain: ChainEnum.describe("Source blockchain network"),
-    to_chain: ChainEnum.describe("Destination blockchain network"),
+    from_chain: chainParam("Source blockchain network"),
+    to_chain: chainParam("Destination blockchain network"),
     from_asset_address: z4.string().min(1).describe("Source asset contract address"),
     to_asset_address: z4.string().min(1).describe("Destination asset contract address"),
     from_amount: z4.string().min(1).describe("Amount to bridge as a decimal string"),
@@ -686,17 +804,23 @@ import { z as z5 } from "zod";
 var McpEnvSchema = z5.object({
   DEFINITIVE_API_KEY: z5.string().startsWith("dpka_"),
   DEFINITIVE_API_SECRET: z5.string().startsWith("dpks_"),
-  DEFINITIVE_BASE_URL: z5.string().url().default("https://ddp.definitive.fi"),
+  DEFINITIVE_BASE_URL: z5.string().url().refine((value) => new URL(value).protocol === "https:", {
+    message: "DEFINITIVE_BASE_URL must use https"
+  }).default("https://ddp.definitive.fi"),
   DEFINITIVE_API_KEY_TYPE: z5.enum(["portfolio", "organization"]),
   DEFINITIVE_PORTFOLIO_ID: z5.string().optional()
 });
 var env = McpEnvSchema.parse(process.env);
+if (new URL(env.DEFINITIVE_BASE_URL).host !== "ddp.definitive.fi") {
+  console.error(`Warning: DEFINITIVE_BASE_URL points at ${new URL(env.DEFINITIVE_BASE_URL).host}, not ddp.definitive.fi. Signed requests and your API key id are sent there.`);
+}
 var client = createClient(env.DEFINITIVE_BASE_URL, env.DEFINITIVE_API_KEY, env.DEFINITIVE_API_SECRET);
-var server = new McpServer({ name: "Definitive", version: "1.2.0" }, {
-  instructions: "MCP server for the Definitive on-chain trading platform. Provides unified tools for portfolio management, trading (market/limit/TWAP/stop orders), QuickTrade execution across multiple blockchains, and read-only perps (perpetual futures) market data and account state. Tools auto-route to the correct API based on the configured key type (portfolio or organization). For organization keys, pass portfolio_id to target a specific portfolio, or set DEFINITIVE_PORTFOLIO_ID as default. TRADING: Default to get_trade_quote + submit_trade for trades unless the user specifies QuickTrade."
+var server = new McpServer({ name: "Definitive", version: "1.3.0" }, {
+  instructions: "MCP server for the Definitive on-chain trading platform. Provides unified tools for portfolio management, trading (market/limit/TWAP/stop orders), QuickTrade execution across multiple blockchains, and perps (perpetual futures) market data, account state, order previews, and transfers between trading vaults and the perps account. Perps withdrawals need a signature from the perps account owner wallet, which this server cannot produce. Tools auto-route to the correct API based on the configured key type (portfolio or organization). For organization keys, pass portfolio_id to target a specific portfolio, or set DEFINITIVE_PORTFOLIO_ID as default. TRADING: Default to get_trade_quote + submit_trade for trades unless the user specifies QuickTrade."
 });
 registerReadTools(server, client, env.DEFINITIVE_API_KEY_TYPE, env.DEFINITIVE_PORTFOLIO_ID);
 registerWriteTools(server, client, env.DEFINITIVE_API_KEY_TYPE, env.DEFINITIVE_PORTFOLIO_ID);
 registerPerpsReadTools(server, client, env.DEFINITIVE_API_KEY_TYPE, env.DEFINITIVE_PORTFOLIO_ID);
+registerPerpsWriteTools(server, client, env.DEFINITIVE_API_KEY_TYPE, env.DEFINITIVE_PORTFOLIO_ID);
 var transport = new StdioServerTransport;
 await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@definitive-fi/mcp",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "MCP server for the Definitive on-chain trading platform",
   "keywords": [
     "mcp",