X402 Payment Proof Verification for Paid APIs

X402 payment proof verification is the step that turns a payment-required API request into protected work the seller is willing to run. It is where the gateway checks that an AI agent has satisfied the payment requirement for the current endpoint, amount, token, network, and request context.

That step deserves its own design, not just a boolean called `paid`. Agent payments are automated, frequent, and often small. If verification is too loose, unpaid or mismatched requests can reach valuable endpoints. If verification is too vague, finance and support lose the records needed to explain what happened.

Apiosk focuses on this seller-side operating layer: get paid by AI, use x402-style flows for machine-readable payment requirements, accept crypto in and move toward euros out, preserve non-custodial seller controls, bundle micropayments, and maintain reconciliation context for each paid request.

Verification is more than seeing a payment

The first mistake is treating payment proof as proof of any payment, anywhere. A paid API needs narrower checks. The payment must satisfy this seller's requirement for this operation at this time.

For a fixed-price endpoint, verification should confirm that the paid amount matches the quoted amount or the seller's accepted rule. For a usage-priced endpoint, it should confirm the pre-agreed unit, quote, or authorization policy. For both models, it should confirm the accepted token, network, recipient, quote expiry, and request binding.

The goal is not to make the agent wait through a checkout page. The goal is to make the payment step deterministic enough that software can complete it and the seller can trust it before running the expensive or valuable work behind the endpoint.

Match proof to the payment requirement

An x402-style flow usually begins with an unpaid request. The API or gateway responds with `HTTP 402 Payment Required` and a machine-readable payment requirement. The agent then retries with payment proof.

Verification should compare the retry against the requirement that was issued. Useful fields include:

• Endpoint or tool identifier.
• Quoted amount and currency.
• Accepted token, such as USDC.
• Accepted network, such as Base.
• Seller receiving address or payment destination.
• Quote expiry or validity window.
• Request identifier, nonce, or challenge reference.
• Idempotency key where duplicate protection is required.

This matching prevents a broad class of mistakes. A proof for another endpoint should not unlock a more expensive endpoint. A payment to a stale wallet should not be treated as current. An expired quote should not silently execute unless the seller has an explicit grace policy.

Bind verification to the request being paid for

Paid APIs need a clear relationship between payment and work. If the agent pays for one company enrichment, that proof should not become an open-ended pass for unrelated enrichments.

The binding can be implemented through a challenge id, request hash, idempotency key, or gateway-managed reference. The exact mechanism depends on the stack, but the operational question is the same: can the seller explain which paid action this proof authorized?

This matters when requests are retried. Good binding lets the agent retry safely without creating a second paid action or letting the same proof run unrelated work.

Prevent replay without blocking legitimate retries

Replay protection is a core verification concern. Once payment proof has been accepted, the system should know whether that proof can be used again.

There are three common outcomes:

• The proof is single-use and cannot run the protected action again.
• The proof can be reused only with the same idempotency key and same request body.
• The proof creates a time-limited access grant for a defined scope.

For per-call API monetization, the second model is often practical. It allows reliable retries for the same paid action while blocking reuse for a different action. The seller can return the original result, rerun safely when policy allows, or point the client to a request status record.

The important part is to make the rule explicit. Agents should not have to infer whether a retry will cost again or whether a previous payment proof remains valid.

Verify before protected work runs

The protected operation should normally run only after verification succeeds. That sequence keeps payment close to the API action being purchased while the gateway handles payment challenge, proof checks, and commercial records.

A clean sequence looks like this:

• The agent calls a protected endpoint without proof.
• The gateway returns an x402-style payment requirement.
• The agent pays according to the requirement.
• The agent retries with payment proof and the same request context.
• The gateway verifies proof, request binding, token, network, amount, destination, and expiry.
• The protected API work runs.
• The seller records execution status and settlement eligibility.

Execution status is important. A verified payment followed by a successful response is different from a verified payment followed by an upstream timeout. Both need records, but they may not have the same settlement outcome.

Keep verification narrow and auditable

Verification should answer operational questions, not become a hidden policy engine. Sellers should be able to inspect why a request passed or failed.

A useful verification record includes the request id, endpoint, timestamp, agent context where available, quoted amount, accepted token, network, destination, proof reference, verification result, failure reason, idempotency key, and execution status. For Apiosk-style operations, it should also connect to bundle id, settlement state, payout reference, and euro reconciliation export where relevant.

That audit trail helps engineering, support, and finance speak from the same record. Engineering can debug failed proofs, support can answer whether an agent paid for a specific request, and finance can connect verified usage to bundled settlement.

Handle failures with machine-readable responses

Payment proof can fail for ordinary reasons: it may be missing, expired, for the wrong amount, sent on the wrong network, already used, linked to a different request, or temporarily unverifiable.

The response should help the agent decide what to do next. A missing proof can receive a fresh payment requirement. An expired quote can ask the agent to request a new quote. A mismatched amount can explain that the current price differs. A duplicate proof can return the existing request status when an idempotency key matches.

Avoid vague failures such as "payment invalid" when a narrower reason is available. Machine-readable failure codes reduce unnecessary retries.

Example: verifying a paid research endpoint

Imagine a seller exposes a research endpoint that returns one structured company profile. The seller charges per successful profile, accepts USDC on Base, and wants verified payments bundled before euro settlement records are prepared.

An agent requests `/v1/company/profile` for one domain. The gateway returns a payment requirement with the amount, token, network, destination, quote expiry, request reference, and retry instructions. The agent pays and retries with proof.

The verification layer checks that the proof matches the issued requirement, the amount is correct, the payment is on the accepted network, the destination matches seller policy, the quote is still valid, and the proof has not already been used elsewhere. Only then does the endpoint run.

If the endpoint succeeds, the verified request becomes eligible for a settlement bundle. If it times out after verification, the record can move into an exception or refund review workflow instead of disappearing into logs.

Where Apiosk fits

Apiosk gives API sellers a way to make paid agent access operational instead of improvised. The buyer side can be software-native: an agent sees a payment requirement, pays with USDC on Base through an x402-style flow, and retries with proof. The seller side can stay controlled: verify proof before protected work, keep non-custodial seller settings, bundle micropayments, prepare settlement records, and reconcile revenue where needed.

The practical starting point is one paid endpoint with one clear unit of value. Define the payment requirement, bind proof to the request, decide retry and replay behavior, record verification outcomes, and connect successful paid calls to settlement. That foundation helps agents know when they are allowed to call and helps sellers know why each protected request was executed.