From c079650947472ed09165208446e33dba4c0eead8 Mon Sep 17 00:00:00 2001 From: andriy-shymkiv Date: Fri, 26 Jun 2026 08:21:36 +0300 Subject: [PATCH] docs: delta order lifecycle for MCP --- for-agents/mcp-server/available-tools.mdx | 126 +++++++++++++++++++++- for-agents/mcp-server/installation.mdx | 4 +- for-agents/mcp-server/overview.mdx | 1 + 3 files changed, 126 insertions(+), 5 deletions(-) diff --git a/for-agents/mcp-server/available-tools.mdx b/for-agents/mcp-server/available-tools.mdx index 20f17b1..672db7f 100644 --- a/for-agents/mcp-server/available-tools.mdx +++ b/for-agents/mcp-server/available-tools.mdx @@ -1,11 +1,11 @@ --- title: "Velora MCP server tools" sidebarTitle: "Available tools" -description: "Reference for all 9 Velora MCP server tools and 5 resources — parameters, return shapes, and the agent rules each tool enforces." -keywords: ["Velora MCP server", "MCP tools", "velora_get_quote", "velora_build_transaction", "MCP resources", "DEX quote tool", "Model Context Protocol"] +description: "Reference for all 18 Velora MCP server tools and 5 resources — parameters, return shapes, and the agent rules each tool enforces." +keywords: ["Velora MCP server", "MCP tools", "velora_get_quote", "velora_build_transaction", "velora_build_delta_order", "MCP resources", "DEX quote tool", "Model Context Protocol"] --- -The Velora MCP server exposes 9 tools and 5 read-only resources. Tool and parameter names below are verbatim from the server's public contract; the contract is stable, so agents can hardcode against it. +The Velora MCP server exposes 18 tools and 5 read-only resources. Tool and parameter names below are verbatim from the server's public contract; the contract is stable, so agents can hardcode against it. ## Response envelope @@ -76,6 +76,126 @@ Agent rules: - The transaction is never signed here. Every response carries the warning "Review and sign externally with the user's wallet." - Delta-shaped input (anything containing `delta`, `orderType`, or `alternatives` keys) is rejected with an error pointing to the Delta build → sign → submit path. +## Delta order lifecycle + +A Delta quote completes through these tools, not through `velora_build_transaction`. The path is always build → sign externally → submit: a build tool returns **unsigned** EIP-712 typed data, you sign it with the user's wallet, and a submit tool forwards your signature. The server never signs and never holds a key. Pass every `route` and `order` payload verbatim — never normalize, reconstruct, or mutate it (including any `hmac`). + +### velora_build_delta_order + +Build a Delta order from a Delta quote's route, returning unsigned EIP-712 typed data. Get a Delta quote first (`velora_get_quote` with `mode=DELTA`). + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `chainId` | number | Yes | | +| `route` | object | Yes | `result.raw.delta.route` (or one of its `alternatives`) from the Delta quote, copied **verbatim**. | +| `side` | `"SELL"` \| `"BUY"` | Yes | | +| `owner` | string | Yes | The order owner's address. | +| `beneficiary` | string | No | Defaults to `owner`. | +| `deadline` | number | No | Unix seconds. | +| `nonce` | string | No | | +| `permit` | string | No | | +| `slippage` | number | No | Basis points. | +| `limitAmount` | string | No | For a target-price (Limit Order) constraint. | +| `metadata` | string | No | | +| `partiallyFillable` | boolean | No | | +| `partner` | string | No | Your partner key. | +| `partnerAddress` | string | No | | +| `partnerFeeBps` | number | No | | +| `partnerTakesSurplus` | boolean | No | | +| `capSurplus` | boolean | No | | + +Returns `result.raw` with `{ toSign, orderHash }`, where `toSign` is the unsigned EIP-712 typed data. Sign it externally, then call `velora_submit_delta_order`. + +### velora_build_twap_delta_order + +Build a TWAP Delta order — one scheduled order executed slice-by-slice, not repeated swaps — returning unsigned EIP-712 typed data. The order family is selected by `onChainOrderType`. + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `chainId` | number | Yes | | +| `route` | object | Yes | Copied **verbatim** from the Delta quote. | +| `owner` | string | Yes | | +| `interval` | number | Yes | Seconds between slices, minimum 60. | +| `numSlices` | number | Yes | Minimum 2. | +| `onChainOrderType` | `"TWAPOrder"` \| `"TWAPBuyOrder"` | Yes | `TWAPOrder` = sell, `TWAPBuyOrder` = buy. | +| `totalSrcAmount` | string | Conditional | Required when `onChainOrderType=TWAPOrder` (sell). Fixes the total source amount. | +| `totalDestAmount` | string | Conditional | Required when `onChainOrderType=TWAPBuyOrder` (buy). Fixes the total destination amount. | +| `maxSrcAmount` | string | Conditional | Required when `onChainOrderType=TWAPBuyOrder` (buy). Caps source spend. | + +Also accepts the optional fields shared with `velora_build_delta_order` (`beneficiary`, `deadline`, `nonce`, `permit`, `slippage`, `metadata`, `partiallyFillable`, and the `partner*` fields). Returns the same `{ toSign, orderHash }` shape. Sign externally, then call `velora_submit_twap_order`. + +### velora_submit_delta_order + +Submit a signed single Delta order (the family built by `velora_build_delta_order`). The server forwards your signature; it never signs. + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `chainId` | number | Yes | | +| `order` | object | Yes | The `toSign.value` struct, passed **verbatim**. | +| `signature` | string | Yes | Produced externally. EOA signatures in ERC-2098 compact form. | +| `partner` | string | No | | +| `referrerAddress` | string | No | | +| `partiallyFillable` | boolean | No | | +| `type` | `"MARKET"` \| `"LIMIT"` | No | | + +Returns `result.raw` with the created Delta auction (status, transactions). For TWAP orders use `velora_submit_twap_order` instead. + +### velora_submit_twap_order + +Submit a signed TWAP Delta order (the order built by `velora_build_twap_delta_order`). Same parameters as `velora_submit_delta_order`, except `order` is the TWAP struct (`TWAPOrder` or `TWAPBuyOrder`) from the build step, passed **verbatim**. Returns the created Delta auction. + +### velora_get_delta_orders + +List a user's Delta orders, paginated. Read-only. + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `userAddress` | string | Yes | The order owner. | +| `page` | number | No | | +| `limit` | number | No | | +| `chainId` | number[] | No | Array; omit for all chains. | +| `status` | string[] | No | Any of `PENDING`, `AWAITING_SIGNATURE`, `ACTIVE`, `SUSPENDED`, `CANCELLING`, `BRIDGING`, `COMPLETED`, `FAILED`, `EXPIRED`, `CANCELLED`, `REFUNDED`, `REFUNDING`. | +| `type` | `"MARKET"` \| `"LIMIT"` | No | | +| `onChainOrderType` | string | No | One of `Order`, `FillableOrder`, `ExternalOrder`, `TWAPOrder`, `TWAPBuyOrder`, `ProductiveOrder`. | + +### velora_get_delta_order + +Fetch a single Delta order by id or hash. Poll it until a terminal status (`COMPLETED`, `FAILED`, `EXPIRED`, `CANCELLED`, `REFUNDED`). Read-only. + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `orderId` | string | Conditional | A UUID. Pass exactly one of `orderId` or `orderHash`. | +| `orderHash` | string | Conditional | Pass exactly one of `orderId` or `orderHash`. | + +### velora_build_cancel_delta_order + +Build the unsigned EIP-712 typed data to cancel one or more Delta orders. + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `chainId` | number | Yes | | +| `orderIds` | string[] | Yes | UUIDs, at least one. | + +Returns `{ toSign }` — the `OrderCancellations` typed data, with the resolved VeloraDelta contract as `verifyingContract`. Sign it externally with the order owner's wallet, then call `velora_submit_cancel_delta_order`. + +### velora_submit_cancel_delta_order + +Submit a signed cancellation. The server forwards your signature; it never signs. + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `orderIds` | string[] | Yes | UUIDs, at least one. | +| `signature` | string | Yes | Produced externally from `velora_build_cancel_delta_order`. | + +### velora_get_bridge_routes + +List Velora's supported Crosschain bridge routes — source→destination chain pairs and the destination-chain output tokens each supports. Use it to confirm a Crosschain pair is bridgeable before quoting or building a Delta order. Read-only. + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `allowBridgeAndSwap` | boolean | No | Include tokens swappable on the destination chain after bridging. Default `true`. | +| `bridges` | string[] | No | Restrict to specific bridge protocols. | + ## Agent guidance These three tools are deterministic, rule-based logic. They make no network calls and involve no model, so the same input always produces the same answer. diff --git a/for-agents/mcp-server/installation.mdx b/for-agents/mcp-server/installation.mdx index 93ae27c..0f37629 100644 --- a/for-agents/mcp-server/installation.mdx +++ b/for-agents/mcp-server/installation.mdx @@ -85,9 +85,9 @@ The endpoint speaks Streamable HTTP, the current MCP transport. Clients that onl ## Verify the connection -A correctly connected client lists **9 tools** (all prefixed `velora_`) and **5 resources** (all prefixed `velora://docs/`). +A correctly connected client lists **18 tools** (all prefixed `velora_`) and **5 resources** (all prefixed `velora://docs/`). -1. List the server's tools (`tools/list`, or your client's MCP panel). Expect 9 tools, from `velora_search_docs` to `velora_validate_agent_plan`. +1. List the server's tools (`tools/list`, or your client's MCP panel). Expect 18 tools, from `velora_search_docs` to `velora_get_bridge_routes`. 2. Call `velora_get_supported_chains` with no arguments. Expect a chain list that includes Ethereum (1), Base (8453), and Arbitrum (42161). You can also smoke-test from the command line without any MCP client: diff --git a/for-agents/mcp-server/overview.mdx b/for-agents/mcp-server/overview.mdx index 3c86e18..406dd46 100644 --- a/for-agents/mcp-server/overview.mdx +++ b/for-agents/mcp-server/overview.mdx @@ -48,6 +48,7 @@ Every tool response also carries `agentHints` (the next safe step) and `docs` (l | Category | Tools | |---|---| | Quoting and building | `velora_get_quote` (Delta, Market, or ALL), `velora_build_transaction` (unsigned, Market only) | +| Delta order lifecycle | `velora_build_delta_order`, `velora_build_twap_delta_order`, `velora_submit_delta_order`, `velora_submit_twap_order`, `velora_get_delta_orders`, `velora_get_delta_order`, `velora_build_cancel_delta_order`, `velora_submit_cancel_delta_order`, `velora_get_bridge_routes` (all unsigned build → sign externally → submit) | | Agent guidance | `velora_decide_execution_route`, `velora_explain_quote`, `velora_validate_agent_plan` | | Market data | `velora_get_supported_chains`, `velora_get_tokens` | | Documentation | `velora_search_docs`, `velora_get_docs_page` |