Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions for-agents/decision-tables.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -31,10 +31,10 @@ Use these tables when an agent needs to choose the next Velora action. Prefer ex

| API result | Next action | Preserve | Do not |
|---|---|---|---|
| Top-level response field is `delta` | Continue the Delta order flow with [`POST /v2/delta/orders/build`](/api-reference/delta/orders-build). | Pass the `delta` object and matching `hmac` from the same quote response. | Do not normalize, sort, round, or reconstruct the `delta` object. |
| Top-level response field is `delta` | Continue the Delta order flow with [`POST /v2/delta/orders/build`](/api-reference/delta/orders-build). | Pass the `delta` object from the quote response verbatim. | Do not normalize, sort, round, or reconstruct the `delta` object. |
| Top-level response field is `market` | Continue the Market transaction flow with [`POST /transactions/:chainId`](/api-reference/market/transactions). | Pass the returned `market` object into the transaction build step. | Do not try to submit it as a Delta order. |
| Response has neither `delta` nor `market` | Stop the flow and surface the no-route result. | Keep the user's original tokens, chain, amount, and mode for retry suggestions. | Do not fabricate a quote, route, gas estimate, or output amount. |
| Quote expired, HMAC invalid, or build rejected | Requote, then rebuild from the fresh response. | Use the newest `delta`, `hmac`, or `market` object. | Do not reuse stale quote payloads. |
| Quote expired or build rejected | Requote, then rebuild from the fresh response. | Use the newest `delta` or `market` object. | Do not reuse stale quote payloads. |
| Chain or token unsupported | Ask the user to choose a supported chain/token pair. | Link to [chains and contracts](/resources/chains-and-contracts) when useful. | Do not guess a token address from symbol alone. |

## Wallet state → approval or signature
Expand Down Expand Up @@ -96,7 +96,7 @@ Use these tables when an agent needs to choose the next Velora action. Prefer ex
|---|---|---|
| `400` for missing slippage | Quote request is incomplete. | Add slippage in basis points and retry. |
| Pricing error or no route | No route for the requested pair, size, chain, or mode. | Retry with `mode=ALL`, reduce size, change token, or ask the user for another route. |
| HMAC or quote validation error | The quote payload is stale or mismatched. | Requote and rebuild from the same fresh response. |
| Quote validation error | The quote payload is stale or mismatched. | Requote and rebuild from the same fresh response. |
| Approval transaction succeeds but swap still fails allowance check | Approval went to the wrong spender or wrong chain. | Check the spender for the selected mode and ask for a new approval if needed. |
| User rejects transaction or signature | User declined the action. | Stop. Do not retry automatically. |
| Delta order remains pending | The auction or protocol settlement is still in progress, or the order may expire. | Poll status with backoff and show the latest order state. Do not resubmit blindly. |
Expand All @@ -107,8 +107,8 @@ Use these tables when an agent needs to choose the next Velora action. Prefer ex
- Never invent token addresses, chain IDs, quotes, transaction hashes, or order IDs.
- Always set `partner` to the integrator's app or project partner key. Treat `my-app-name` as a placeholder, not a literal value.
- Branch on the response shape: `delta` means Delta order flow; `market` means Market transaction flow.
- Keep the `delta` block and its `hmac` together. Treat them as an opaque pair.
- Requote after expiration, HMAC errors, material balance changes, or route failures.
- Keep the `delta` block intact and pass it verbatim. Treat it as an opaque object.
- Requote after expiration, validation errors, material balance changes, or route failures.
- Ask before changing execution mode, recipient, chain, or spend direction.
- Ask for user confirmation before submitting a signed order or sending an on-chain transaction.

Expand Down
2 changes: 1 addition & 1 deletion for-agents/five-call-recipe.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ Agent rules:
| Missing required field | Ask the user for the missing field. |
| No route | Ask for a different amount, token, chain, or execution mode. |
| Quote expired | Requote and rebuild. |
| HMAC or quote validation error | Requote and keep the new response object paired with its new validation data. |
| Quote validation error | Requote and rebuild from the fresh response object. |
| User rejects signature or transaction | Stop. Do not retry automatically. |
| Transaction reverts | Surface the revert and suggest requoting. |
| Delta order remains pending | Poll with backoff and show the latest order status. |
Expand Down
4 changes: 2 additions & 2 deletions for-agents/mcp-server/available-tools.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ Returns `{ modeRequested, responseType, raw }` where `responseType` is `"delta"`
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.
- 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
Expand All @@ -78,7 +78,7 @@ Agent rules:

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

Expand Down
2 changes: 1 addition & 1 deletion for-agents/mcp-server/examples.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ The response has `responseType: "delta"` and the raw quote under `result.raw`, w
- Have the user's wallet sign that typed data. The MCP server never signs.
- Submit the signed order via [`POST /v2/delta/orders`](/api-reference/delta/orders-submit) and track it by order ID.

Preserve the `delta` payload and its `hmac` exactly between steps. Any mutation invalidates the order.
Preserve the `delta` payload exactly between steps. Any mutation invalidates the order.

## Market swap with an unsigned transaction

Expand Down
2 changes: 1 addition & 1 deletion for-agents/mcp-server/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ This is the property that makes the server safe to wire into an autonomous agent

- `velora_build_transaction` returns an **unsigned** Market transaction. Your client signs it with the user's wallet.
- Delta quotes hand back the documented build → sign → submit path. The EIP-712 typed data is signed externally, never by the server.
- Raw quote payloads, including the `delta` object and its `hmac`, are preserved byte-for-byte. The server never mutates what the API returned.
- Raw quote payloads, including the `delta` object, are preserved byte-for-byte. The server never mutates what the API returned.

An agent connected to this server can research, quote, and prepare trades. It cannot move funds.

Expand Down
4 changes: 2 additions & 2 deletions for-agents/prompt-library/parallel-aggregators.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Requirements:
- Compare on `destUSD` (or `destAmount` normalized to a common token) net of `gasCostUSD` and `partnerFee`.
- Fan out in parallel; respect a hard 800ms budget per quote source; fall back gracefully if one source times out.
- For the Velora native-ETH placeholder use `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` (mixed case).
- If Velora wins via Delta, return both the `delta` block and `hmac` to the caller so they can sign and submit. If via Market, return the `market` block (same shape as `/prices`'s `priceRoute`).
- If Velora wins via Delta, return the `delta` block to the caller so they can build, sign, and submit. If via Market, return the `market` block (same shape as `/prices`'s `priceRoute`).

Reference these docs and follow them exactly:
- https://velora.xyz/docs/overview/why-velora
Expand All @@ -45,4 +45,4 @@ Do NOT race-update shared state across the two aggregators' callbacks. Do NOT fa
## End-state check

- A side-by-side comparison log shows both aggregators quoting the same trade within the 800ms budget.
- When Velora's Delta path wins on a large trade, the response carries the `delta` block + `hmac` ready to sign.
- When Velora's Delta path wins on a large trade, the response carries the `delta` block ready to build and sign.