@definitive-fi/mcp 1.2.1 → 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

@@ -124,7 +124,7 @@ var isErrorResult = (result) => typeof result === "object" && result !== null &&
 
 
 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);
@@ -231,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";
@@ -685,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.1" }, {
-  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.1",
+  "version": "1.3.0",
   "description": "MCP server for the Definitive on-chain trading platform",
   "keywords": [
     "mcp",