openapi: 3.1.0
info:
  title: Monad JSON-RPC API
  version: "2026-05"
  description: |
    Ethereum-compatible JSON-RPC API for the Monad blockchain. Mainnet (chain
    ID 143, native token MON) is reachable at `https://rpc.monad.xyz`; the
    public testnet is reachable at `https://testnet-rpc.monad.xyz`. WebSocket
    variants of each endpoint are available via the `wss://` scheme.

    All JSON-RPC requests are made by `POST`ing a JSON body to the RPC URL.
    Public endpoints are unauthenticated and rate limited (mainnet default is
    25 requests per second on `rpc.monad.xyz`).
  contact:
    name: Monad
    url: https://docs.monad.xyz
servers:
  - url: https://rpc.monad.xyz
    description: Monad mainnet (QuickNode public RPC, 25 rps)
  - url: https://rpc1.monad.xyz
    description: Monad mainnet (Alchemy public RPC, 15 rps; debug_*/trace_* disabled)
  - url: https://rpc2.monad.xyz
    description: Monad mainnet (Goldsky Edge, 300 per 10s)
  - url: https://rpc3.monad.xyz
    description: Monad mainnet (Ankr, 300 per 10s; debug_* disabled)
  - url: https://testnet-rpc.monad.xyz
    description: Monad public testnet
paths:
  /:
    post:
      operationId: jsonRpcCall
      summary: JSON-RPC call
      description: |
        Invoke a JSON-RPC method against the Monad node. Supported methods
        include Ethereum-standard `eth_*`, `net_*`, `web3_*`, plus
        Monad-specific extensions and `debug_*`/`trace_*` methods (subject to
        endpoint-specific availability — Alchemy disables `debug_`/`trace_`,
        Ankr disables `debug_`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/JsonRpcRequest"
            examples:
              eth_blockNumber:
                summary: Latest block number
                value:
                  jsonrpc: "2.0"
                  id: 1
                  method: eth_blockNumber
                  params: []
              eth_chainId:
                summary: Chain ID
                value:
                  jsonrpc: "2.0"
                  id: 1
                  method: eth_chainId
                  params: []
              eth_getBalance:
                summary: Account balance at latest block
                value:
                  jsonrpc: "2.0"
                  id: 1
                  method: eth_getBalance
                  params:
                    - "0x0000000000000000000000000000000000000000"
                    - "latest"
              eth_call:
                summary: Read-only contract call
                value:
                  jsonrpc: "2.0"
                  id: 1
                  method: eth_call
                  params:
                    - to: "0x0000000000000000000000000000000000000000"
                      data: "0x"
                    - "latest"
              eth_getLogs:
                summary: Query event logs
                value:
                  jsonrpc: "2.0"
                  id: 1
                  method: eth_getLogs
                  params:
                    - fromBlock: "latest"
                      toBlock: "latest"
                      address: "0x0000000000000000000000000000000000000000"
              eth_sendRawTransaction:
                summary: Submit a signed transaction
                value:
                  jsonrpc: "2.0"
                  id: 1
                  method: eth_sendRawTransaction
                  params:
                    - "0x..."
              eth_getTransactionByHash:
                summary: Fetch a transaction by hash
                value:
                  jsonrpc: "2.0"
                  id: 1
                  method: eth_getTransactionByHash
                  params:
                    - "0x0000000000000000000000000000000000000000000000000000000000000000"
              eth_getBlockByNumber:
                summary: Fetch a block by number
                value:
                  jsonrpc: "2.0"
                  id: 1
                  method: eth_getBlockByNumber
                  params:
                    - "latest"
                    - false
              eth_estimateGas:
                summary: Estimate gas for a call
                value:
                  jsonrpc: "2.0"
                  id: 1
                  method: eth_estimateGas
                  params:
                    - to: "0x0000000000000000000000000000000000000000"
                      data: "0x"
              eth_feeHistory:
                summary: Recent fee history
                value:
                  jsonrpc: "2.0"
                  id: 1
                  method: eth_feeHistory
                  params:
                    - 4
                    - "latest"
                    - [25, 50, 75]
              net_version:
                summary: Network ID
                value:
                  jsonrpc: "2.0"
                  id: 1
                  method: net_version
                  params: []
              web3_clientVersion:
                summary: Client version string
                value:
                  jsonrpc: "2.0"
                  id: 1
                  method: web3_clientVersion
                  params: []
              debug_traceTransaction:
                summary: Trace a transaction (where supported)
                value:
                  jsonrpc: "2.0"
                  id: 1
                  method: debug_traceTransaction
                  params:
                    - "0x0000000000000000000000000000000000000000000000000000000000000000"
                    - tracer: "callTracer"
      responses:
        "200":
          description: JSON-RPC response (success or JSON-RPC error)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonRpcResponse"
        "429":
          description: Rate limit exceeded
components:
  schemas:
    JsonRpcRequest:
      type: object
      required: [jsonrpc, method, id]
      properties:
        jsonrpc:
          type: string
          const: "2.0"
        method:
          type: string
          description: |
            Supported methods include `eth_blockNumber`, `eth_chainId`,
            `eth_getBalance`, `eth_getCode`, `eth_getStorageAt`,
            `eth_getTransactionCount`, `eth_call`, `eth_estimateGas`,
            `eth_gasPrice`, `eth_maxPriorityFeePerGas`, `eth_feeHistory`,
            `eth_getBlockByHash`, `eth_getBlockByNumber`,
            `eth_getBlockReceipts`, `eth_getTransactionByHash`,
            `eth_getTransactionReceipt`, `eth_getLogs`,
            `eth_sendRawTransaction`, `eth_sendRawTransactionSync`,
            `eth_createAccessList`, `net_version`, `web3_clientVersion`,
            `debug_traceTransaction`, `debug_traceCall`,
            `debug_traceBlockByHash`, `txpool_statusByAddress`,
            `txpool_statusByHash`, and `admin_ethCallStatistics`.
        params:
          type: array
          items: {}
        id:
          oneOf:
            - type: integer
            - type: string
    JsonRpcResponse:
      type: object
      required: [jsonrpc, id]
      properties:
        jsonrpc:
          type: string
          const: "2.0"
        id:
          oneOf:
            - type: integer
            - type: string
            - type: "null"
        result: {}
        error:
          type: object
          properties:
            code: { type: integer }
            message: { type: string }
            data: {}