x402 Service

The x402 service protects APIs that require pay-per-request access. A caller first sends a normal request to the target endpoint. If payment is required, the service returns 402 Payment Required with payment requirements. The caller signs according to those requirements, then retries the same endpoint with a payment credential to receive the API result.

This guide is for developers, agents, automation workflows, and backend services that call x402 paid APIs directly. It does not cover frontend order-based payment flows.

When to use x402

Use x402 when you want pay-per-request API access without creating an order before every call. The caller only signs and retries the request when the endpoint requires payment.

x402 keeps the business API request shape unchanged. The first and second requests use the same method, URL, headers, and body required by the target API. The second request only adds the payment credential.

This makes x402 suitable for backend services, scripts, agents, workflows, JSON APIs, AI model calls, tool calls, and similar machine-to-machine API shapes.

Flow

1. Prepare the original business request.
2. Send the first request to the x402-protected endpoint.
3. If payment is required, read the 402 Payment Required response.
4. Read the PAYMENT-REQUIRED response header.
5. Select a payment option from PAYMENT-REQUIRED.
6. If selecting upto, complete the required EVM allowance check first. If allowance is insufficient, submit an ERC-20 approve transaction and wait for on-chain confirmation.
7. Sign with the corresponding wallet and generate the payment credential.
8. Retry the same method, URL, and body.
9. Include the PAYMENT-SIGNATURE header on the retry.
10. The service verifies the payment credential.
11. After verification succeeds, the service executes the original business API and returns the result.

Endpoint URL

The full x402 paid endpoint URL is provided by the service provider. This guide uses the following format:

https://pay.alephant.io/x402/{endpoint_slug}

Headers

First request

The first request does not include PAYMENT-SIGNATURE.

402 response

When payment is required, the service returns:

Second request

The second request includes the payment credential:

After a paid request settles, the response can also include PAYMENT-RESPONSE with settlement information.

Example flow

Replace the URL, endpoint slug, and request body with the real endpoint information provided by the service provider.

1. Send the first request

curl -i -X POST "https://pay.alephant.io/x402/{endpoint_slug}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "hello"
  }'

If payment is required, the response is similar to:

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <payment-requirements>

The response body may contain an error message, payment description, or other service-defined information. Use the PAYMENT-REQUIRED header as the source for generating the payment credential.

2. Generate the payment credential

Use an x402-compatible client or SDK to:

1. Parse PAYMENT-REQUIRED.
2. Select a payment requirement the caller can satisfy.
3. Sign with the corresponding wallet.
4. Produce the value to place in the PAYMENT-SIGNATURE header.

If the service returns multiple payment requirements, choose one the caller can pay. The service may support different networks, assets, or payment modes. The available options are determined by the PAYMENT-REQUIRED value returned by the service.

3. Retry with the payment credential

curl -i -X POST "https://pay.alephant.io/x402/{endpoint_slug}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "PAYMENT-SIGNATURE: <payment-signature>" \
  -d '{
    "input": "hello"
  }'

After payment verification succeeds, the service returns the normal business response:

HTTP/1.1 200 OK
PAYMENT-RESPONSE: <payment-response>

PAYMENT-RESPONSE is returned when settlement information is available.

Payment requirements

PAYMENT-REQUIRED represents the payment requirements for the current request. Read the supported payment options from it and select one option to sign.

Common information includes:

Interpret field names and structures through an x402-compatible client. Do not hard-code one specific response shape.

Payment modes

The x402 service may return different payment modes. Use the actual requirements in PAYMENT-REQUIRED and select a mode the caller supports.

exact

exact means the current request is paid with a specified amount. The caller generates a payment credential from the current PAYMENT-REQUIRED, then retries the original request with PAYMENT-SIGNATURE.

Use exact when:

• the per-request amount is explicit,
• the caller wants to pay a fixed amount for each call,
• no higher allowance needs to be approved in advance.

upto

upto means the caller allows the current payment to complete up to the amount limit returned by the service. The current upto flow is for EVM networks and is not used for Solana payment requirements.

The flow is:

1. Select an EVM payment requirement with scheme = "upto" from PAYMENT-REQUIRED.
2. Verify the payment network, ERC-20 asset, amount limit, pay-to address, and resource information.
3. If the required amount is 0, no ERC-20 allowance check is needed.
4. If the service returns the eip2612GasSponsoring or erc20ApprovalGasSponsoring extension, the payment requirement includes approval sponsorship. The caller does not need to submit a separate local ERC-20 approve transaction first.
5. If neither sponsorship extension is present, check the paying wallet’s ERC-20 allowance for the Permit2 contract.
6. If the current allowance is greater than or equal to the required amount, generate the payment credential.
7. If the current allowance is insufficient, submit an approve(Permit2, amount) transaction from the paying wallet to the ERC-20 token contract.
8. Wait for the approve transaction to confirm on-chain.
9. Generate PAYMENT-SIGNATURE.
10. Retry the original business request with PAYMENT-SIGNATURE.

Users may see two wallet actions in upto mode: an ERC-20 approve transaction to increase Permit2 allowance, and a payment signature to generate PAYMENT-SIGNATURE. If sufficient Permit2 allowance already exists, or if the payment requirement includes an approval sponsorship extension, the caller usually only needs to generate the payment signature.

Before submitting approve, verify the token contract, Permit2 approval target, approval amount, network, and paying wallet address. Approve only authorizes the payment contract to use the specified ERC-20 asset within the approved amount. It does not mean the business API call has already succeeded.

Payment credential

PAYMENT-SIGNATURE is generated by signing from PAYMENT-REQUIRED.

Callers should note:

• The payment credential must correspond to the PAYMENT-REQUIRED returned by the current endpoint.
• Do not reuse payment credentials from other endpoints, other requests, or expired requirements.
• The business content of the second request should match the first request.
• If the business API itself requires authentication, the second request must still include the original authentication headers.

Status codes

The exact error response format is determined by the service endpoint.

Retry guidance

Use limited retries for:

• network timeouts,
• temporary RPC or upstream service errors,
• 429 rate-limit responses when retrying later is allowed,
• temporary 5xx server errors.

If a new first request returns a new PAYMENT-REQUIRED, generate a new payment credential from the latest payment requirements.

Integration checklist

1. Get the x402 base URL from the service provider.
2. Get the target paid endpoint path, request method, and request body format.
3. Confirm whether the business API also requires Authorization.
4. Prepare a wallet that can pay.
5. Confirm the wallet supports the payment network and asset returned by the service.
6. Send the first request and confirm that 402 and PAYMENT-REQUIRED are returned.
7. If selecting upto, confirm whether sufficient Permit2 allowance already exists. If not, complete ERC-20 approve and wait for on-chain confirmation.
8. Use an x402 client to generate PAYMENT-SIGNATURE.
9. Retry the same request with PAYMENT-SIGNATURE.
10. Confirm the service returns the business result.

Security notes

• Do not commit wallet private keys, API keys, bearer tokens, or payment credentials to source control.
• Do not send private keys to untrusted services.
• Use secure key management in production.
• Before paying, verify the endpoint, amount, asset, network, and pay-to address.
• When using upto, make sure the Permit2 allowance matches the current payment requirement and does not exceed the business need.
• If an ERC-20 approve transaction is required, verify the token contract, Permit2 approval target, approval amount, network, and paying wallet address before submitting.
• If the payment requirement has expired, request the endpoint again to get new payment requirements.
• If the business API requires authentication, the payment credential does not replace that authentication.
• Provide clear error messages for payment failure, insufficient balance, unsupported network, and similar cases.

FAQ

Why does the first request return 402?

It means the endpoint is protected by x402 and the caller must complete payment for the current request. Read PAYMENT-REQUIRED, generate PAYMENT-SIGNATURE, and retry.

Does the second request need a different body?

Usually no. The second request should keep the same business method, URL, and body as the first request, with only the additional PAYMENT-SIGNATURE header.

Why can a request still fail after payment?

Common causes include expired payment credentials, a mismatch between payment credential and request, business authentication failure, insufficient wallet balance, payment network mismatch, or invalid business parameters. Use the response status code and error message to diagnose the issue.

Can PAYMENT-SIGNATURE be reused?

Reusing it is not recommended. The payment credential should be generated for the current PAYMENT-REQUIRED and current request. Different endpoints, different requests, or expired payment requirements should use a new payment credential.

Why does upto mode require contract confirmation?

When no approval sponsorship extension is present, upto requires the paying wallet to have sufficient ERC-20 allowance for the Permit2 contract. The client first checks the current allowance. If it is insufficient, the caller must submit approve(Permit2, amount) and wait for successful on-chain confirmation. After confirmation, the caller generates PAYMENT-SIGNATURE and retries the original request. If sufficient allowance already exists, approve does not need to be repeated.

Does x402 payment replace API keys?

No. If the target business API requires an API key, bearer token, or any other authentication method, include that authentication in both the first and second requests.

References

• x402 Quickstart for Buyers
• x402 Upto payment scheme