txdecode

Documentation

txdecode turns a confirmed Base transaction into a human-readable action plus normalized asset movements. It is pay-per-call over x402: no account, no API key — you pay $0.005 in USDC on Base per successful call.

Quickstart — the x402 flow

Every paid endpoint follows the same x402 (v2) exchange. An x402 client library runs all four steps for you; the manual flow is:

  1. 1

    Request. Send the request normally, e.g. GET /api/v1/decode/{txHash}.

  2. 2

    402 Payment Required. If unpaid, the server replies 402 with the accepted payment requirements (price, network, asset, payTo) in the PAYMENT-REQUIRED header.

  3. 3

    Pay. The client signs an EIP-3009 USDC authorization for that amount and attaches it as the PAYMENT-SIGNATURE header.

  4. 4

    Retry. The request is replayed with the signature. On success you get 200 with the decoded JSON, and the settlement transaction hash in the PAYMENT-RESPONSE header.

See the playground to watch the flow run live, and the decode endpoint reference for runnable curl, JavaScript and Python examples.

Endpoints

One endpoint, priced flat. Follow the link for the full reference.

  • GET /api/v1/decode/{txHash} $0.005

    Decode a confirmed Base transaction into a human-readable action plus normalized asset movements (token, amount, USD value). Add ?verbose=true for the full log/event breakdown.

Errors and billing

Every error uses one uniform JSON envelope with a stable code. The full table — HTTP status, retryability and meaning — lives in the error reference.

No-settle guarantee. Non-200 responses are never settled — errors never cost $0.005. The x402 payment settles only on a 200, so a failed call costs nothing.

Known limitations

The decoder is logs-only and priced best-effort. These are the documented edges of v1; each decode reports its coverage in the completeness block.

  • internal-eth-possible Internal native-ETH transfers are invisible — the engine is logs-only. Flagged when tx.to is a contract and tx.value > 0.
  • v4-native-leg-invisible Uniswap v4 native legs emit no log; reported best-effort from tx.value and the signed swap amounts.
  • v4-pool-tokens-unresolved A v4 PoolId with no pairable ERC-20 Transfers leaves swap legs with an `unknown` asset (amounts preserved).
  • Pre-migration Slipstream pools (legacy CLFactory) are reported as `unknown-v3-style`.
  • `tx-pending` (422) is best-effort: free-RPC mempool visibility is not guaranteed; the documented fallback is 404 with a false-negative note.
  • NFTs are `not-priced` by design in v1 (distinct from `unpriced`).

More