openapi: 3.1.0
info:
  title: EVM Tx Toolkit
  version: 0.1.0
  description: 'Three premium x402 endpoints across 5 EVM chains (Base, Ethereum, Arbitrum, Optimism, Polygon): tx/explain ($0.10), tx/simulate ($0.20),
    token/risk_scan ($0.50). The OATP playbook for EVM.'
  contact:
    email: hello@
servers:
- url: https://evm-tx-toolkit.mtree.workers.dev
x-pricing:
  - path: /v1/tx/explain
    method: POST
    price: $0.1
    amount: "0.1"
    asset: USDC
    network: base
  - path: /v1/tx/simulate
    method: POST
    price: $0.2
    amount: "0.2"
    asset: USDC
    network: base
  - path: /v1/token/risk_scan
    method: POST
    price: $0.5
    amount: "0.5"
    asset: USDC
    network: base
  - path: /tools/tx_explainer
    method: POST
    price: $0.1
    amount: "0.1"
    asset: USDC
    network: base
  - path: /tools/tx_simulator
    method: POST
    price: $0.2
    amount: "0.2"
    asset: USDC
    network: base
  - path: /tools/token_risk_scan
    method: POST
    price: $0.5
    amount: "0.5"
    asset: USDC
    network: base
paths:
  /v1/tx/explain:
    post:
      summary: Decoded transaction summary
      description: 'Decode a confirmed transaction on Base, Ethereum, Arbitrum, Optimism, or Polygon into a structured

        human-readable summary: sender, recipient, contract calls decoded,

        ERC-20 / ERC-721 / ERC-1155 transfers, swap legs (UniV2/UniV3/Aerodrome),

        gas, status, revert reason if reverted, all token symbols/decimals

        labeled. $0.10 per call via x402 USDC on Base.

        '
      operationId: txExplain
      x-x402-price-usd: 0.1
      x-x402-chains:
      - base
      - ethereum
      - arbitrum
      - optimism
      - polygon
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  chain:
                    type: string
                  tx_hash:
                    type: string
                  block_number:
                    type: integer
                  from:
                    type: string
                  to:
                    type: string
                  status:
                    type: string
                    enum:
                    - success
                    - reverted
                  revert_reason:
                    type: string
                  gas_used:
                    type: integer
                  gas_price_gwei:
                    type: number
                  value_eth:
                    type: number
                  transfers:
                    type: array
                    items:
                      type: object
                      properties:
                        kind:
                          type: string
                          enum:
                          - erc20
                          - erc721
                          - erc1155
                          - native
                        token_address:
                          type: string
                        symbol:
                          type: string
                        decimals:
                          type: integer
                        from:
                          type: string
                        to:
                          type: string
                        amount:
                          type: string
                  swap_legs:
                    type: array
                    items:
                      type: object
                      properties:
                        dex:
                          type: string
                        token_in:
                          type: string
                        token_out:
                          type: string
                        amount_in:
                          type: string
                        amount_out:
                          type: string
        '402':
          description: Payment Required (x402 challenge)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - chain
              - tx_hash
              properties:
                chain:
                  type: string
                  enum:
                  - base
                  - ethereum
                  - arbitrum
                  - optimism
                  - polygon
                tx_hash:
                  type: string
                  pattern: ^0x[0-9a-fA-F]{64}$
                  description: 0x-prefixed 32-byte transaction hash
  /v1/tx/simulate:
    post:
      summary: Pre-flight transaction simulation
      description: 'Simulate an unsent transaction on Base, Ethereum, Arbitrum, Optimism, or Polygon via eth_call (with

        debug_traceCall fallback when the upstream RPC supports it). Returns

        success / revert + decoded revert reason + gas estimate. Degrades

        gracefully when the public RPC lacks tracing. $0.20 per call.

        '
      operationId: txSimulate
      x-x402-price-usd: 0.2
      x-x402-chains:
      - base
      - ethereum
      - arbitrum
      - optimism
      - polygon
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - success
                    - reverted
                  revert_reason:
                    type: string
                  gas_estimate:
                    type: integer
                  return_data:
                    type: string
                  block_number:
                    type: integer
        '402':
          description: Payment Required (x402 challenge)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - chain
              - from
              - to
              properties:
                chain:
                  type: string
                  enum:
                  - base
                  - ethereum
                  - arbitrum
                  - optimism
                  - polygon
                from:
                  type: string
                  description: 0x-address of the sender
                to:
                  type: string
                  description: 0x-address of the target contract
                data:
                  type: string
                  description: 0x-prefixed calldata, optional
                value:
                  type: string
                  description: Wei amount as decimal string, optional
                block:
                  oneOf:
                  - type: string
                    enum:
                    - latest
                    - pending
                  - type: integer
  /v1/token/risk_scan:
    post:
      summary: ERC-20 risk scoring
      description: "Risk-score an ERC-20 on Base, Ethereum, Arbitrum, Optimism, or Polygon. Combines on-chain reads via\nviem (name/symbol/decimals/owner,\
        \ EIP-1967 proxy slots) with GoPlus\nToken Security API enrichment (honeypot, blacklist, fee-on-transfer,\n\
        mintable, top-10 holder concentration). Returns a composite 0\u2013100\nrisk_score and a categorical\
        \ verdict. $0.50 per call.\n"
      operationId: tokenRiskScan
      x-x402-price-usd: 0.5
      x-x402-chains:
      - base
      - ethereum
      - arbitrum
      - optimism
      - polygon
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  identity:
                    type: object
                    properties:
                      name:
                        type: string
                      symbol:
                        type: string
                      decimals:
                        type: integer
                      total_supply:
                        type: string
                      owner:
                        type: string
                      is_proxy:
                        type: boolean
                      implementation:
                        type: string
                  security:
                    type: object
                    properties:
                      honeypot:
                        type: boolean
                      blacklist:
                        type: boolean
                      mintable:
                        type: boolean
                      fee_on_transfer:
                        type: boolean
                      buy_tax:
                        type: number
                      sell_tax:
                        type: number
                  holders:
                    type: object
                    properties:
                      top_10_concentration_pct:
                        type: number
                      holder_count:
                        type: integer
                  risk_score_0_100:
                    type: integer
                    minimum: 0
                    maximum: 100
                  verdict:
                    type: string
                    enum:
                    - safe
                    - caution
                    - likely_rug
                    - insufficient_data
        '402':
          description: Payment Required (x402 challenge)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - chain
              - token_address
              properties:
                chain:
                  type: string
                  enum:
                  - base
                  - ethereum
                  - arbitrum
                  - optimism
                  - polygon
                token_address:
                  type: string
                  pattern: ^0x[0-9a-fA-F]{40}$
x-x402:
  facilitator: x402.org
  chains:
  - base
  - ethereum
  - arbitrum
  - optimism
  - polygon
  /tools/tx_explainer:
    post:
      summary: tx_explainer — transaction explainer alias
      description: EVM transaction explainer alias using winner vocabulary. Fetch a confirmed transaction by hash and return a human-readable explanation with contracts invoked, token balance changes, approvals, fees, gas used, transfers, and one-line summary. Alias for /v1/tx/explain. $0.10 per call via x402 USDC on Base.
      operationId: toolsTxExplainer
      x-x402-price-usd: 0.1
      x-alias-for: /v1/tx/explain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [chain, tx_hash]
              properties:
                chain:
                  type: string
                  enum: [base, ethereum, arbitrum, optimism, polygon]
                tx_hash:
                  type: string
                  pattern: ^0x[0-9a-fA-F]{64}$
      responses:
        '200':
          description: Transaction explanation JSON
        '402':
          description: Payment Required (x402 challenge)
  /tools/tx_simulator:
    post:
      summary: tx_simulator — transaction simulation alias
      description: EVM transaction simulation alias for pre-signing safety. Simulate a call before broadcasting and return success/revert status, decoded revert reason, gas estimate, return data, approval risk hints, and likely balance-change posture. Alias for /v1/tx/simulate. $0.20 per call via x402 USDC on Base.
      operationId: toolsTxSimulator
      x-x402-price-usd: 0.2
      x-alias-for: /v1/tx/simulate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [chain, from, to]
              properties:
                chain:
                  type: string
                  enum: [base, ethereum, arbitrum, optimism, polygon]
                from:
                  type: string
                to:
                  type: string
                data:
                  type: string
                value:
                  type: string
                block:
                  oneOf:
                    - type: string
                    - type: integer
      responses:
        '200':
          description: Transaction simulation JSON
        '402':
          description: Payment Required (x402 challenge)
  /tools/token_risk_scan:
    post:
      summary: token_risk_scan — rug risk / token risk scan alias
      description: Base/EVM token risk scan alias for autonomous trading agents before swaps, buys, DCA, and memecoin entries. Detect rug risk, honeypot/tax flags, proxy/owner control, approval risk, holder/liquidity danger signals, and return a composite 0-100 risk score with verdict. Alias for /v1/token/risk_scan. $0.50 per call via x402 USDC on Base.
      operationId: toolsTokenRiskScan
      x-x402-price-usd: 0.5
      x-alias-for: /v1/token/risk_scan
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [chain, token_address]
              properties:
                chain:
                  type: string
                  enum: [base, ethereum, arbitrum, optimism, polygon]
                token_address:
                  type: string
                  pattern: ^0x[0-9a-fA-F]{40}$
      responses:
        '200':
          description: Token risk scan JSON
        '402':
          description: Payment Required (x402 challenge)

x-money-tree-buyer-readiness:
  quote_before_signing: "Read the unpaid 402 quote before signing or before paying; compare payTo, amount, network, asset, and resource."
  rail_readiness:
    network: "eip155:8453"
    asset: "USDC on Base"
  payment_proof_policy:
    require_payment_response: true
    receipt_fields: [transaction, network, asset, amount, payer, payTo]
  funding_handoff: "If the buyer lacks Base USDC or the settlement asset, stop before signing and hand off to funding; retry only with the same request after funding."
  revenue_metric_policy: "External paid calls are settled revenue; self-funded/internal-credit calls are protocol proof only."
  decision_json_shape:
    required_keys: [verdict, recommendation, warnings, confidence, metadata, evidence, action, stop_conditions, fallbacks, attribution]
