docs(for-agents): remove non-existent hmac from Delta V2 agent flow#22
Open
dxnght wants to merge 1 commit into
Open
docs(for-agents): remove non-existent hmac from Delta V2 agent flow#22dxnght wants to merge 1 commit into
hmac from Delta V2 agent flow#22dxnght wants to merge 1 commit into
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
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-agentspages 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:
Files changed (6 files, 12 single-line edits)
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.mdxPass 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.mdxPass every route and order payload verbatim … (including any hmac). → Pass every route and order payload verbatim ….
prompt-library/parallel-aggregators.mdxreturn 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.