> ## Documentation Index
> Fetch the complete documentation index at: https://digraphsas-docs-pricing.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Velora MCP server tools
> Reference for all 18 Velora MCP server tools and 5 resources — parameters, return shapes, and the agent rules each tool enforces.
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
Every tool returns the same envelope:
```json theme={null}
{
"result": {},
"agentHints": [],
"docs": [{ "title": "...", "url": "https://velora.xyz/docs/...", "uri": "velora://docs/..." }],
"warnings": []
}
```
* `result` — the tool-specific payload. Raw API responses appear unmodified under `result.raw`.
* `agentHints` — the next safe step, as plain strings. Follow them.
* `docs` — links into this documentation relevant to the result.
* `warnings` — user-facing caveats (for example, the sign-externally reminder on every built transaction).
Errors use the same envelope with `isError: true` and `result.error.{type, message}`. Validation failures and documented upstream errors surface their `errorType` and `details`; unexpected failures stay generic.
## Quoting and building
### velora\_get\_quote
Get a Velora quote. Delta, Market, or both modes via the unified quote endpoint.
| Parameter | Type | Required | Notes |
| -------------- | ---------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `chainId` | number | Yes | Always `chainId`, never `network`. |
| `destChainId` | number | No | Set for Crosschain quotes. Crosschain is Delta-only; `mode=MARKET` with a different `destChainId` is rejected before any API call. |
| `srcToken` | string | Yes | Token address. Native token placeholder: `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`. |
| `destToken` | string | Yes | Token address, same format. |
| `amount` | string | Yes | Raw units (wei-style), digits only. |
| `srcDecimals` | number | Yes | Source token decimals. |
| `destDecimals` | number | Yes | Destination token decimals. |
| `side` | `"SELL"` \| `"BUY"` | Yes | |
| `userAddress` | string | No | The wallet that will execute. |
| `mode` | `"DELTA"` \| `"MARKET"` \| `"ALL"` | No | Default `ALL`. Use `DELTA` for MEV protection, Limit Orders, TWAP, and Crosschain. |
| `partner` | string | No | Your partner key; `my-app-name` is the placeholder to replace. |
Returns `{ modeRequested, responseType, raw }` where `responseType` is `"delta"`, `"market"`, or `"unknown"` and `raw` is the upstream payload, preserved unchanged.
Agent rules:
* Branch on `responseType`, never on what you requested. `mode=ALL` returns either a Delta or a Market response, never both.
* A Delta quote is completed through the Delta path (`POST /v2/delta/orders/build`, sign externally, `POST /v2/delta/orders`) — not through `velora_build_transaction`. The quote's `agentHints` repeat these steps.
* Preserve the `delta` payload and its `hmac` exactly. Never normalize, reconstruct, or mutate it.
* Under `mode=ALL`, a Delta pricing failure falls back to Market and surfaces a structured `fallbackReason` in `warnings`.
### velora\_build\_transaction
Build an **unsigned** Market swap transaction from a quote's `priceRoute`. Market only.
| Parameter | Type | Required | Notes |
| ------------- | ------ | -------- | --------------------------------------------------------- |
| `chainId` | number | Yes | |
| `srcToken` | string | Yes | Token address. |
| `destToken` | string | Yes | Token address. |
| `srcAmount` | string | Yes | Raw units. |
| `destAmount` | string | Yes | Raw units. |
| `userAddress` | string | Yes | The wallet that will sign and send. |
| `priceRoute` | object | Yes | Copied **verbatim** from the Market quote's `priceRoute`. |
| `partner` | string | No | Your partner key. |
Returns `result.raw` with the unsigned transaction fields: `from`, `to` (the Augustus v6.2 router), `value`, `data`, gas pricing, and `chainId`.
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`.
Before the order can settle, the source token must be authorized to the Delta contract: either grant an on-chain ERC-20 `approve` to it, or pass a Permit/Permit2 signature in the `permit` field of this build call. See [Token approvals for agents](/for-agents/token-approvals) for the spender and Permit decision rules.
### 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.
### velora\_decide\_execution\_route
Decide whether a trading intent should use Delta, Market, ALL, or none of the quote modes. Call it before `velora_get_quote` when the mode is unclear.
| Parameter | Type | Required | Notes |
| ------------- | ------------------- | -------- | ------------------------------------------------------------- |
| `userIntent` | string | Yes | The user's request, free-form. |
| `chainId` | number | No | |
| `destChainId` | number | No | A different `destChainId` forces the Crosschain (Delta) rule. |
| `srcToken` | string | No | |
| `destToken` | string | No | |
| `amount` | string | No | |
| `side` | `"SELL"` \| `"BUY"` | No | |
Returns `{ recommendedMode, reasoning }` where `recommendedMode` is `"DELTA"`, `"MARKET"`, `"ALL"`, or `"NONE"`.
Rule precedence (first match wins): OTC intent → `NONE` (it's the AugustusRFQ maker/taker flow, not a quote mode) · MEV protection → `DELTA` · Crosschain → `DELTA` · Limit Orders → `DELTA` · TWAP or DCA → `DELTA` · explicit Market → `MARKET` · explicit Delta → `DELTA` · best-execution language → `ALL` · default → `ALL`.
### velora\_explain\_quote
Classify a raw quote response and return the safe completion path. Never mutates the payload.
| Parameter | Type | Required | Notes |
| --------------- | ------ | -------- | ----------------------------------------- |
| `raw` | object | Yes | The `result.raw` from `velora_get_quote`. |
| `modeRequested` | string | Yes | The mode you passed to the quote call. |
Returns `{ responseType, summary, fallbackReason }`. A top-level `delta` key classifies as `"delta"`, a top-level `market` key as `"market"`, anything else as `"unknown"`. `fallbackReason` (`{ errorType, details }`) appears when Delta pricing was skipped under `mode=ALL`.
### velora\_validate\_agent\_plan
Check a free-form plan against the mistakes agents actually make with Velora, before any of them execute.
| Parameter | Type | Required | Notes |
| --------- | ------ | -------- | ------------------------------------- |
| `plan` | object | Yes | Your plan as a free-form JSON object. |
Returns `{ issues }`, each issue carrying `severity` (`"info"`, `"warning"`, or `"critical"`), `message`, and `fix`.
Checks include: a `network` key anywhere in the plan (must be `chainId`), MEV intent with a non-Delta mode, Crosschain with `mode=MARKET`, Limit Orders or TWAP treated as RFQ, and any signing, private-key, or Delta-payload-mutation step (critical — the server never signs).
## Market data
### velora\_get\_supported\_chains
List the EVM chains Velora supports. No parameters.
Returns `result.raw.chains` as `{ chainId, name }` pairs with `source: "server-known"`: Ethereum (1), Optimism (10), BNB Chain (56), Gnosis (100), Unichain (130), Polygon (137), Sonic (146), Base (8453), Arbitrum (42161), Avalanche (43114).
This is a server-known list, not a live API response, and may lag actual support. Confirm a specific chain with `velora_get_tokens`; do not assume every EVM chain is supported.
### velora\_get\_tokens
List the tokens Velora can route on a chain. Use it to resolve token addresses and decimals before quoting instead of inventing them.
| Parameter | Type | Required | Notes |
| --------- | ------ | -------- | ---------------------------------- |
| `chainId` | number | Yes | Always `chainId`, never `network`. |
Returns `result.raw.tokens` as `{ symbol, address, decimals, img, network }` entries.
## Documentation
### velora\_search\_docs
Search Velora's canonical documentation. Use it before guessing Velora behavior.
| Parameter | Type | Required | Notes |
| --------- | ------ | -------- | ---------------- |
| `query` | string | Yes | |
| `limit` | number | No | 1–20, default 5. |
Returns search results as `{ title, url, resourceUri, snippet }`.
### velora\_get\_docs\_page
Fetch a single docs page as markdown by its slug.
| Parameter | Type | Required | Notes |
| --------- | ------ | -------- | --------------------------------------------------------------------------------------------- |
| `slug` | string | Yes | A docs slug such as `integrate/trading-modes`. Absolute URLs and path traversal are rejected. |
Returns `{ slug, content }`.
## Resources
Five read-only documents an MCP client can pull straight into context:
| Resource URI | What it is | When to read it |
| -------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------- |
| `velora://docs/llms` | The docs index (`llms.txt`), a compact map of the documentation. | First. Orient before fetching pages. |
| `velora://docs/llms-full` | The full documentation concatenated. | When you need authoritative detail and have the context budget. |
| `velora://docs/openapi/delta-v2` | OpenAPI spec for the Delta v2 intent API. | Generating or checking Delta integration code. |
| `velora://docs/openapi/market` | OpenAPI spec for the Market aggregator API. | Generating or checking Market integration code. |
| `velora://docs/openapi/rfq` | OpenAPI spec for AugustusRFQ (OTC maker/taker). | OTC flows. RFQ is not a quote mode. |
## Next steps
These tools composed into end-to-end Delta and Market workflows.
The full intent-to-action mapping the guidance tools implement.