---
name: oracle-x402
description: Inspect x402 payment requirements and prepare a capped, wallet-signable payment. Never signs, never pays.
---

# x402

x402 is an HTTP payment negotiation. A resource answers `402 Payment Required`
with a base64 `PAYMENT-REQUIRED` header, the client signs an authorization, and
a facilitator settles it. Oracle does the negotiation and the preparation. The
signature comes from the user's wallet, always.

Oracle supports x402 version 2, scheme `exact`, on `eip155:` networks, using the
`eip3009` asset transfer method.

## Prepare a payment

```text
oracle x402 prepare <url> --payer 0x<your-address>
```

This does a GET. If the resource answers 200 it says so and stops: nothing is
owed, nothing is signed. If it answers 402, Oracle parses the requirements and
prints the EIP-3009 `transferWithAuthorization` typed data your wallet must
sign. Add `--json` for the full EIP-712 payload.

The same prepare is available to the agent as the native tool `x402_prepare`
with `{ url, payer }`.

## Submit a signed payment

```text
oracle x402 submit <url> --payer 0x<your-address> --signature 0x<65-byte-sig>
```

Sign the typed data in your own wallet, then pass the signature here. Oracle
re-issues the request with the `PAYMENT-SIGNATURE` header built from YOUR
signature. This is the only network write in the flow, and it moves no funds by
itself: the resource server hands the payload to a facilitator, and the
facilitator calls `transferWithAuthorization`. One attempt, no retry loop.

## The cap

`ORACLE_X402_MAX_USD` bounds a single payment. Default `1.00`. A requirement
above the cap is refused at prepare time, before any typed data exists. A
malformed, zero, or negative cap value falls back to the default rather than
opening the gate. Raise it deliberately if a spend is intended.

## What Oracle will not do

Oracle does not sign, does not create a `PAYMENT-SIGNATURE` on its own, does not
hold a key, does not contact a facilitator directly, and does not retry a 402
with a signature of its own making. The prepared artifact carries
`requiresWalletSignature: true` and `backendSigner: false`.

## Inspecting a header you already have

If you already hold a `PAYMENT-REQUIRED` header and only want to decode it, the
read-only data provider still exists:

```text
oracle_cli data call x402 inspect paymentRequired=<base64-header>
```

Re-inspect every new 402 response: requirements can change between requests.

Do not treat any public x402 facilitator as a production mainnet dependency.
Verify the facilitator and the scheme independently before any wallet
integration.

Sources: x402 v2 HTTP transport (`specs/transports/transport_http.md`) and the
exact/EVM scheme (`specs/schemes/exact/scheme_exact_evm.md`) in
x402-foundation/x402, plus https://docs.x402.org/core-concepts/facilitator