{"id":"idempotency-fingerprint","title":"Derive a stable idempotency fingerprint from declared identity fields and flag volatile fields","description":"Hashes the fields you declare as the identity of an operation (JSON Pointers into each request) with RFC 8785 canonical JSON and SHA-256, so retries of the same operation get the same fingerprint regardless of key order, and flags the ways that breaks: an identity field missing, an identity field also declared volatile, identity values that look like timestamps, epoch times or UUIDs (heuristic), and undeclared fields that differ between attempts. For an agent that must choose an Idempotency-Key for a retried write. Does not know any provider's key rules, length limits or scope, and does not send anything.","roi":"A key built from the wrong fields either double-charges (key changes per retry) or silently drops a different request (key collides).","audience":"agent-infra","package":"execution-safety-kit","channels":["x402","mcp"],"endpoint":{"method":"POST","url":"https://agents.writerslogic.com/api/v1/idempotency-fingerprint","path":"/api/v1/idempotency-fingerprint","contentType":"application/json"},"price":{"amount":"0.005","currency":"USDC","network":"base","perCall":true,"failedCallsCharged":false},"inputSchema":{"type":"object","additionalProperties":false,"required":["requests","identity"],"properties":{"requests":{"type":"array","minItems":1,"maxItems":20,"items":{"description":"A request (body, or {method,url,body}) as JSON; several attempts of the same intended operation."}},"identity":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","maxLength":300},"description":"JSON Pointers whose values define the operation's identity."},"volatile":{"type":"array","maxItems":50,"items":{"type":"string","maxLength":300},"description":"JSON Pointers declared to change per attempt (timestamps, nonces, request ids)."},"scope":{"type":"string","maxLength":200,"description":"Mixed into the hash (for example operation name and tenant) so equal bodies in different scopes get different fingerprints."}}},"resultSchema":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"fingerprints":{"type":"array","items":{"type":"string","description":"Hex SHA-256."}},"stable":{"type":"boolean","description":"All requests produce the same fingerprint."},"undeclaredDifferences":{"type":"array","items":{"type":"string"},"description":"Pointers of leaf values that differ across requests and are neither identity nor volatile."},"derivation":{"type":"string"},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"outputSchema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"fingerprints":{"type":"array","items":{"type":"string","description":"Hex SHA-256."}},"stable":{"type":"boolean","description":"All requests produce the same fingerprint."},"undeclaredDifferences":{"type":"array","items":{"type":"string"},"description":"Pointers of leaf values that differ across requests and are neither identity nor volatile."},"derivation":{"type":"string"},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"_provenance":{"type":"object","description":"C2PA-aligned manifest and W3C VC 2.0 (eddsa-jcs-2022) issued by the hub DID; verify at POST /api/v1/verify-provenance"}},"required":["data","_provenance"]},"example":{"requests":[{"amount":500,"currency":"USD","customer":"c_1","sentAt":"2026-11-04T10:00:00Z"},{"amount":500,"currency":"USD","customer":"c_1","sentAt":"2026-11-04T10:00:07Z"}],"identity":["/amount","/currency","/customer"],"volatile":["/sentAt"],"scope":"charge:acct_9"},"openapiOperation":{"operationId":"idempotency_fingerprint","summary":"Derive a stable idempotency fingerprint from declared identity fields and flag volatile fields","description":"Hashes the fields you declare as the identity of an operation (JSON Pointers into each request) with RFC 8785 canonical JSON and SHA-256, so retries of the same operation get the same fingerprint regardless of key order, and flags the ways that breaks: an identity field missing, an identity field also declared volatile, identity values that look like timestamps, epoch times or UUIDs (heuristic), and undeclared fields that differ between attempts. For an agent that must choose an Idempotency-Key for a retried write. Does not know any provider's key rules, length limits or scope, and does not send anything.\n\nPrice: 0.005 USDC on Base (x402).","x-x402-price-usdc":"0.005","x-x402-amount":"5000","x-payment-info":{"protocols":["x402"],"price":{"mode":"fixed","currency":"USD","amount":"0.005"}},"x-audience":"agent-infra","x-sample-url":"https://agents.writerslogic.com/api/v1/samples/idempotency-fingerprint","security":[{"x402":[]},{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["requests","identity"],"properties":{"requests":{"type":"array","minItems":1,"maxItems":20,"items":{"description":"A request (body, or {method,url,body}) as JSON; several attempts of the same intended operation."}},"identity":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","maxLength":300},"description":"JSON Pointers whose values define the operation's identity."},"volatile":{"type":"array","maxItems":50,"items":{"type":"string","maxLength":300},"description":"JSON Pointers declared to change per attempt (timestamps, nonces, request ids)."},"scope":{"type":"string","maxLength":200,"description":"Mixed into the hash (for example operation name and tenant) so equal bodies in different scopes get different fingerprints."}}},"example":{"requests":[{"amount":500,"currency":"USD","customer":"c_1","sentAt":"2026-11-04T10:00:00Z"},{"amount":500,"currency":"USD","customer":"c_1","sentAt":"2026-11-04T10:00:07Z"}],"identity":["/amount","/currency","/customer"],"volatile":["/sentAt"],"scope":"charge:acct_9"}}}},"responses":{"200":{"description":"Paid result with provenance","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"fingerprints":{"type":"array","items":{"type":"string","description":"Hex SHA-256."}},"stable":{"type":"boolean","description":"All requests produce the same fingerprint."},"undeclaredDifferences":{"type":"array","items":{"type":"string"},"description":"Pointers of leaf values that differ across requests and are neither identity nor volatile."},"derivation":{"type":"string"},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"_provenance":{"type":"object","description":"C2PA-aligned manifest and W3C VC 2.0 (eddsa-jcs-2022) issued by the hub DID; verify at POST /api/v1/verify-provenance"}},"required":["data","_provenance"]}}}},"400":{"description":"Invalid request (no payment consumed)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"401":{"description":"Invalid X-API-KEY","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"402":{"description":"Payment required or invalid","content":{"application/json":{"schema":{"type":"object","description":"x402 v2 PaymentRequired (also base64 in the PAYMENT-REQUIRED header)","properties":{"x402Version":{"type":"integer"},"error":{"type":"string"},"code":{"type":"string"},"resource":{"type":"object"},"accepts":{"type":"array","items":{"type":"object"}},"extensions":{"type":"object"}}}}}},"502":{"description":"Upstream failure; the payment is released or not settled","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}},"links":{"docs":"https://agents.writerslogic.com/docs/idempotency-fingerprint/","docsJson":"https://agents.writerslogic.com/docs/idempotency-fingerprint.json","sample":"https://agents.writerslogic.com/api/v1/samples/idempotency-fingerprint","openapi":"https://agents.writerslogic.com/openapi.json","catalog":"https://agents.writerslogic.com/api/v1/catalog","verifyProvenance":"https://agents.writerslogic.com/api/v1/verify-provenance","index":"https://agents.writerslogic.com/docs/index.json"}}