diff --git a/for-agents/decision-tables.mdx b/for-agents/decision-tables.mdx index 749b0e9..96626c1 100644 --- a/for-agents/decision-tables.mdx +++ b/for-agents/decision-tables.mdx @@ -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 @@ -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. | @@ -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. diff --git a/for-agents/five-call-recipe.mdx b/for-agents/five-call-recipe.mdx index efa09a8..56526d5 100644 --- a/for-agents/five-call-recipe.mdx +++ b/for-agents/five-call-recipe.mdx @@ -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. | diff --git a/for-agents/mcp-server/available-tools.mdx b/for-agents/mcp-server/available-tools.mdx index 7a1f713..15d4aa1 100644 --- a/for-agents/mcp-server/available-tools.mdx +++ b/for-agents/mcp-server/available-tools.mdx @@ -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 @@ -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 diff --git a/for-agents/mcp-server/examples.mdx b/for-agents/mcp-server/examples.mdx index 2002043..c94b1e8 100644 --- a/for-agents/mcp-server/examples.mdx +++ b/for-agents/mcp-server/examples.mdx @@ -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 diff --git a/for-agents/mcp-server/overview.mdx b/for-agents/mcp-server/overview.mdx index 406dd46..3734375 100644 --- a/for-agents/mcp-server/overview.mdx +++ b/for-agents/mcp-server/overview.mdx @@ -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. diff --git a/for-agents/prompt-library/parallel-aggregators.mdx b/for-agents/prompt-library/parallel-aggregators.mdx index 5f2e093..242669f 100644 --- a/for-agents/prompt-library/parallel-aggregators.mdx +++ b/for-agents/prompt-library/parallel-aggregators.mdx @@ -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 @@ -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.