x402 (AI agents)

Settle an agent's payment (paywall)

Pass the agent's PAYMENT-SIGNATURE header unread, with the seller's own wallet and price. The API rebuilds the requirement from those - nothing the agent sends decides what is owed or to whom - and settles it through the facilitator. A payment is reported paid ONCE: the same header again is refused with invalid_transaction_state. A settlement still being mined is waited for once; if it is still pending the answer names the transaction and the agent's next request with the same header is paid. Refusals are 200 with paid: false; every settlement carries the P2Flux fee, max(1%, 0.003 USDC). Batch payments (batch-settlement) are verified and counted without a transaction; receipt identifies the paid request and, on refusal, payment_required is the 402 header to answer with - it carries the channel state the agent resynchronises to. Usage pricing: for an upto payment send amount, what the request cost - at least 0.01 and at most price; the fee is taken on amount. An upto payment redeemed without amount is refused (unsupported_scheme). An agent's request to take back its unused prepaid balance answers paid: false, refunded: true with payment_response: answer the agent 200 with that header and no content.

post/x402/paywall/redeem

Request

  • Base URL: https://api.p2flux.com
  • URL: https://api.p2flux.com/x402/paywall/redeem
  • Auth: none required

Request body

recipientstring required

An EVM address.

pricestring required

Price in USDC as a decimal string, 0.01 or more.

paymentstring required

The agent's PAYMENT-SIGNATURE header, as received.

resourcestring

The URL the agent asked for. Informational.

amountstring

Usage pricing only: what this request cost in USDC, 0.01 or more and at most price.

Example request

{
  "recipient": "0xb4e43f3fBa5Add75395adAD366627E7d74141Fa9",
  "price": "0.05",
  "amount": "0.02"
}

Response

Paid, or why not

paidboolean required

true: serve the content. false: answer 402 again.

reasonstring

Why not paid - the x402 reason string (invalid_transaction_state = this payment was already used).

messagestring
transactionstring

The settlement transaction on Base; with settlement_pending the one still being mined.

payerstring
amountstring

USDC base units.

networkstring required
payment_responsestring

Send as the PAYMENT-RESPONSE header with the content.

scheme'exact' | 'upto' | 'batch-settlement'
receiptstring

batch-settlement: unique id of this paid request (no transaction per request).

payment_requiredstring

batch-settlement, on refusal: the PAYMENT-REQUIRED header to send with the 402.

refundedboolean

The agent took its unused prepaid balance back. Not a payment: answer 200 with payment_response and no content.

Changes

No recorded changes to this operation across all 1 revision of this API.