# x402 Ethereum Tx Tools: full reference > Pay-per-call Ethereum mainnet (chain id 1) transaction and bundle simulation. $0.002 USDC on Base per successful call, paid with x402 v1 or v2. No signup, no API key. Base URL: https://sim.0xrelay.party ## Endpoints - `GET /health` (free): `{"ok":true,"block":"0x...","paid":true,"payment_ready":true,"price_usdc":"0.002"}` - `POST /simulate` (paid, $0.002): simulate one call or a bundle. - `POST /check` (paid, $0.003): pre-sign safety check. - `POST /explain` (paid, $0.002): explain a mined tx. - `POST /execute` (paid, $0.003): broadcast a tx you already signed. - `GET /openapi.json`, `GET /.well-known/x402`, `GET /llms.txt` (free discovery files) ## Request: single call ```json {"from":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "to":"0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "data":"0xa9059cbb000000000000000000000000ef4396d9ff8107086d215a1c9f8866c54795d7c700000000000000000000000000000000000000000000000000000000000f4240", "value":"0x0", "gas":"0x5208", "block":"latest"} ``` - `from` (required), `to` (omit for contract creation), `data` hex, `value` wei (hex string or number), `gas` (max 30,000,000), `block` (number; default latest). - Unknown fields are rejected with 400. ## Request: bundle ```json {"calls":[{"from":"0x...","to":"0x...","data":"0x..."},{"from":"0x...","to":"0x...","data":"0x..."}],"block":"latest"} ``` Up to 8 calls, executed in order on shared state. Set `block` once at bundle level. ## Response (200) ```json {"block":{"number":21000000}, "success":true, "calls":[{"success":true,"revertReason":null,"gasUsed":34567,"returnData":"0x...", "logs":[{"address":"0x...","event":"Transfer","args":{"from":"0x...","to":"0x...","value":"1000000"}}], "trace":{"type":"CALL","from":"0x...","to":"0x...","calls":[]}}], "balanceChanges":[{"holder":"0x...","token":"0xa0b8...","symbol":"USDC","delta":"-1000000","formatted":"-1.0"}]} ``` Signature checks are off (validation=false), so you can simulate from any address. ## POST /check Body: the same single call or `calls` bundle as /simulate, plus optional: - `typedData`: the EIP-712 object the user is asked to sign (`domain`, `primaryType`, `message`). Can be sent alone, without a tx. - `authorizationList`: EIP-7702 authorizations `[{"address":"0x..."}]` included in the tx. Response: ```json {"verdict":"danger","summary":"Do not sign unless you fully trust this. It grants 0xef43…d7c7 an unlimited allowance on token 0xa0b8…eb48.", "flags":[{"severity":"danger","kind":"unlimited_approval","message":"grants 0xef43…d7c7 an unlimited allowance on token 0xa0b8…eb48"}], "simulation":{ ...same shape as /simulate... }} ``` Flag kinds: `unlimited_approval`, `approval`, `set_approval_for_all`, `permit2_approve`, `permit`, `permit_signature`, `permit2_signature`, `permit2_transfer`, `marketplace_order`, `order_nothing_back`, `net_outflow`, `outflow_nothing_back`, `fresh_recipient`, `proxy_upgrade`, `ownership_transfer`, `delegatecall_from_account`, `eip7702_delegation`, `eip7702_account`, `revert`, `no_expiry`, `unknown_typed_data`. Verdict is the worst severity (info → ok). ## POST /explain Body: `{"hash":"0x<64 hex>"}`. The hash is looked up for free first: unknown → 404, pending → 404, no charge. Recent blocks only (pruned node); older traces return 502, not charged. Response: `tx` (from, to, value, block, nonce, selector), `status` success|reverted, `revertReason`, `fee` (gasUsed, effectiveGasPrice, wei, eth), `balanceChanges` (net ETH + token per address, fee excluded), `tokenTransfers` (ERC20/721/1155), `internalEth`, `logs` (decoded), `callTree` (callTracer, compacted). ## POST /execute Body: `{"rawTx":"0x","via":"flashbots","allowRevert":false,"wait":false}`. Only `rawTx` is required. - Accepted: legacy with EIP-155 chainId 1, type 1 (EIP-2930), type 2 (EIP-1559). Refused: other chains, pre-EIP-155 legacy, type 3 (blob), type 4 (EIP-7702). Gas limit 21,000..30,000,000. - We never sign and hold no keys. The sender is recovered from your signature. - Checks before sending: nonce not below the account nonce and no gap, maxFeePerGas at or above the current base fee, balance covers gas limit x max fee + value, simulation succeeds (or `allowRevert:true`). - `via`: `flashbots` (default) sends to Flashbots Protect (`rpc.flashbots.net/fast`, private, shared with all builders). `public` sends through our reth node to the public mempool. There is no silent fallback from private to public. - `wait:true` polls for the receipt for up to about 10 s; otherwise `status` is `submitted` (or `pending` if the wait ran out). Track it later with /explain or any RPC. - Resending the same tx is safe: an "already known" reply returns the same hash with `alreadyKnown:true`. Response: `{"hash","status":"submitted|pending|mined|reverted","via","alreadyKnown","tx":{from,to,type,chainId,nonce,gasLimit,maxFeePerGas,maxPriorityFeePerGas,value},"simulation":{success,gasUsed,revertReason,balanceChanges},"receipt":{status,blockNumber,gasUsed,effectiveGasPrice}|null,"explorer"}`. Errors: 400 bad tx · 422 not includable or reverts (body has the reason and the simulation) · 502 relay rejected · 504 timeout. None are charged. ## Payment flow (x402) 1. POST without payment -> HTTP 402. Body: x402 v1 `accepts` (scheme `exact`, network `base`, asset USDC `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`, maxAmountRequired `2000` = $0.002 for /simulate and /explain, `3000` = $0.003 for /check and /execute). Header `PAYMENT-REQUIRED`: base64 x402 v2 requirements (network `eip155:8453`). 2. Sign an EIP-3009 transferWithAuthorization with any x402 client (@x402/fetch, x402-axios, x402 Python, x402-rs). 3. Retry with header `X-PAYMENT` (v1) or `PAYMENT-SIGNATURE` (v2). Response carries `X-PAYMENT-RESPONSE` / `PAYMENT-RESPONSE` with the settlement tx. 4. Settlement happens only after a result is produced. Errors (400, 502, 504) are never charged. ## Errors - 400 invalid input · 402 payment required/invalid · 413 body > 64 KB · 429 > 30 req/min per IP · 502 node or facilitator error · 504 timeout (15 s) ## Notes - Backed by a self-hosted reth mainnet node (recent state; historical blocks may be pruned). - Self-hosted x402 facilitator; payments go straight to the operator's Base address. - ERC-8004 identity: agent #1135857 on Base, registry eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432.