Fix #113 support idempotency keys for duplicate x402 retries

[Jo-anny]

Support Idempotency Keys to Prevent Duplicate Charges on Retries

Summary

Adds idempotency-key support to prevent duplicate x402 settlements when the same logical search request is retried due to lost responses, runtime retries, or network issues.

Clients can provide an idempotency key that is bound to the request parameters and payer. Repeated requests using the same key return the original outcome instead of triggering a second settlement.

Context

Browser, proxy, and agent retries can cause the same logical search request to be submitted multiple times when a response is lost or a request is otherwise retried.

For paid routes, this can result in duplicate payment settlement unless the request is handled idempotently.

Relevant Files

• server/index.ts
• src/hooks/useSearch.ts

What Changed

• Added support for client-provided idempotency keys.
• Bound idempotency keys to the relevant request parameters and payer.
• Repeated in-flight requests reuse the original request outcome.
• Repeated completed requests return the original outcome without performing another settlement.
• Preserved verified x402 settlement semantics for paid routes.
• Added automated coverage for idempotency behavior.
• Updated documentation to describe the new request behavior.
• Kept behavior aligned across Express, Vercel, browser, and MCP runtime boundaries where applicable.

Acceptance Criteria

• Clients can send an idempotency key bound to request parameters and payer.
• Repeated in-flight requests with the same key return the original outcome without a second settlement.
• Repeated completed requests with the same key return the original outcome without a second settlement.
• The same idempotency key cannot be reused with different request parameters or payer information.
• Automated coverage is updated for the new behavior.
• Documentation is updated where behavior changes.
• Verified x402 settlement semantics are preserved for paid routes.
• Express, Vercel, browser, and MCP behavior remains aligned where applicable.

Delivery Notes

The implementation is designed to make retries safe without weakening payment verification or settlement guarantees.

Idempotency applies to the logical request, ensuring that a retry does not result in an additional charge when the original request has already been processed or is still in flight.

Testing

Coverage should verify, at minimum:

• A first request with an idempotency key is processed normally.
• A concurrent retry with the same key does not trigger a second settlement.
• A completed retry with the same key returns the original outcome.
• The same idempotency key cannot be reused with different request parameters or payer information.
• Paid routes continue to enforce the existing x402 verification and settlement semantics.
• Behavior remains consistent across the supported runtime boundaries.

Related Issue

Closes #113

[vercel]

@Jo-anny is attempting to deploy a commit to the Emmanuel's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@Jo-anny Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits