> ## Documentation Index
> Fetch the complete documentation index at: https://www.velora.xyz/docs/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 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.

### 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`.

<Note>
  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. A native ETH source uses neither — submit with `signature: "0x"` and have the user send `depositNativeAndPreSign(orderHash)` with `value = srcAmount` instead; see [Native ETH (dETH)](/docs/delta/native-eth). See [Token approvals for agents](/docs/for-agents/token-approvals) for the spender and Permit decision rules.
</Note>

### 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), Robinhood Chain (4663), 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

<CardGroup cols={2}>
  <Card title="Examples" icon="list-check" href="/docs/for-agents/mcp-server/examples">
    These tools composed into end-to-end Delta and Market workflows.
  </Card>

  <Card title="Decision tables" icon="route" href="/docs/for-agents/decision-tables">
    The full intent-to-action mapping the guidance tools implement.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.