Skip to content

docs(for-agents): remove non-existent hmac from Delta V2 agent flow#22

Open
dxnght wants to merge 1 commit into
VeloraDEX:mainfrom
dxnght:fix/for-agents-remove-delta-v2-hmac
Open

docs(for-agents): remove non-existent hmac from Delta V2 agent flow#22
dxnght wants to merge 1 commit into
VeloraDEX:mainfrom
dxnght:fix/for-agents-remove-delta-v2-hmac

Conversation

@dxnght

@dxnght dxnght commented Jul 11, 2026

Copy link
Copy Markdown

Problem

The /for-agents docs repeatedly instruct agents to read, preserve, and thread an hmac field through the Delta flow. But Delta V2 has no hmac — this is stated explicitly by the canonical sources in this same repo:

  • OpenAPI api-reference/specs/delta-v2.json, /v2/quote description: the delta block has the same shape as GET /v2/delta/prices — there is no hmac in V2.
  • resources/migrations/delta-v1-to-v2.mdx: the hmac is gone in V2; existing code that re-attaches hmac to the build payload will fail validation.
  • api-reference/delta/quote.mdx: a Delta V2 price is route + alternatives, no hmac.

Because the /for-agents pages are consumed by LLM coding agents (Claude, Cursor, Codex) to generate integrations, the phantom hmac leads agents to read/forward a field that does not exist, or to add validation logic that can break the POST /v2/delta/orders/build step.

Fix

Remove hmac references from the Delta path only, across the /for-agents section. For Delta V2 the payload to preserve verbatim is the delta object / route — the wording is updated accordingly. Error-handling rows that mentioned "HMAC invalid" now read "quote validation error", which stays accurate for V2.

Why this isn't "V1 support"

Delta V1 (/delta/) remains fully supported (per the migration guide) and its hmac is real — nothing V1-related is touched here. But the /for-agents section teaches V2 exclusively: every Delta endpoint it references is /v2/ (GET /v2/quote, POST /v2/delta/orders/build, POST /v2/delta/orders, …), and the top-level delta block these pages attach the hmac to only exists in the V2 GET /v2/quote response — V1 has no /quote endpoint and no delta block at all. In V1 the hmac lives inside the price object from GET /delta/prices, so the current wording doesn't describe V1 mechanics either. Per the migration guide, threading an hmac into the V2 build payload fails validation, so this is an active footgun for agents, not harmless legacy text.

Scope (intentionally untouched)
hmac remains valid and is not changed where it genuinely exists:

  • Market API /prices → priceRoute.hmac (integrity tag) — api-reference/market/*, api-reference/specs/market.json.
  • Market-maker RFQ API HMAC-SHA256 auth — resources/market-makers/*.
  • The migration guide's own historical mentions of the V1 hmac.

Files changed (6 files, 12 single-line edits)

  • for-agents/decision-tables.mdx (5)
  • for-agents/five-call-recipe.mdx (1)
  • for-agents/mcp-server/overview.mdx (1)
  • for-agents/mcp-server/examples.mdx (1)
  • for-agents/mcp-server/available-tools.mdx (2)
  • for-agents/prompt-library/parallel-aggregators.mdx (2)

Documentation only, no behavioral/code changes. Verified there are no remaining hmac references on the Delta path in /for-agents after this change.

Example before → after

decision-tables.mdx
Pass the delta object and matching hmac from the same quote response. → Pass the delta object from the quote response verbatim.
Quote expired, HMAC invalid, or build rejected → Quote expired or build rejected
Keep the delta block and its hmac together. Treat them as an opaque pair. → Keep the delta block intact and pass it verbatim. Treat it as an opaque object.

mcp-server/available-tools.mdx
Pass every route and order payload verbatim … (including any hmac). → Pass every route and order payload verbatim ….

prompt-library/parallel-aggregators.mdx
return both the delta block and hmac to the caller so they can sign and submit. → return the delta block to the caller so they can build, sign, and submit.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant