Optimism Etherscan Accounts API

openapi: 3.2.0
info:
  title: Optimism Etherscan Accounts API
  description: The Optimism Etherscan API provides developer access to OP Mainnet (chain ID 10) blockchain data via REST endpoints.
  version: '2.0'
  contact:
    name: Optimism Etherscan Support
    url: https://docs.optimism.etherscan.io/
  termsOfService: https://etherscan.io/apiterms
  license:
    name: Etherscan API Terms
    url: https://etherscan.io/apiterms
servers:
- url: https://api-optimistic.etherscan.io/api
  description: Optimism Etherscan legacy endpoint (OP Mainnet, chain ID 10)
- url: https://api.etherscan.io/v2/api
  description: Etherscan unified V2 endpoint — add chainid=10 for OP Mainnet
security:
- apiKeyAuth: []
tags:
- name: Accounts
  description: Address balances, transaction lists, and token holdings on OP Mainnet
paths:
  /:
    get:
      summary: Call an API module action
      description: All Optimism Etherscan API calls are issued against this endpoint. The `module` and `action` query parameters select the operation; additional parameters depend on the module/action pair. For V2 unified access, also pass `chainid=10`.
      operationId: callApi
      tags:
      - Accounts
      parameters:
      - name: module
        in: query
        required: true
        description: 'API module name. One of: account, contract, transaction, block, logs, token, stats, proxy.'
        schema:
          type: string
          enum:
          - account
          - contract
          - transaction
          - block
          - logs
          - token
          - stats
          - proxy
          example: account
      - name: action
        in: query
        required: true
        description: 'Action to perform within the selected module. Examples: balance, txlist, tokentx, getabi, getsourcecode, getstatus, getblockreward, tokensupply, ethsupply, gasoracle, eth_blockNumber.'
        schema:
          type: string
          example: balance
      - name: chainid
        in: query
        required: false
        description: Chain ID for Etherscan V2 unified endpoint. Use 10 for OP Mainnet. Not needed when using the legacy api-optimistic.etherscan.io endpoint.
        schema:
          type: integer
          example: 10
      - name: address
        in: query
        required: false
        description: OP Mainnet address for account or token operations (0x-prefixed).
        schema:
          type: string
          example: '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
      - name: contractaddress
        in: query
        required: false
        description: Smart contract address for token or contract operations (0x-prefixed).
        schema:
          type: string
          example: '0x4200000000000000000000000000000000000042'
      - name: txhash
        in: query
        required: false
        description: Transaction hash for transaction-level queries.
        schema:
          type: string
          example: '0x15f8e5ea1079d9a0bb04a4c58ae5fe7654b5b2b4f82b7fb7b1b59b0f9e9f35e'
      - name: blockno
        in: query
        required: false
        description: Block number for block-level queries.
        schema:
          type: integer
          example: 12345678
      - name: startblock
        in: query
        required: false
        description: Start block for range queries (inclusive).
        schema:
          type: integer
          example: 0
      - name: endblock
        in: query
        required: false
        description: End block for range queries (inclusive). Use 99999999 for latest.
        schema:
          type: integer
          example: 99999999
      - name: page
        in: query
        required: false
        description: Page number for paginated results (default 1).
        schema:
          type: integer
          example: 1
      - name: offset
        in: query
        required: false
        description: Number of results per page (max 10000).
        schema:
          type: integer
          example: 25
      - name: sort
        in: query
        required: false
        description: Sort direction for list results.
        schema:
          type: string
          enum:
          - asc
          - desc
          example: asc
      - name: tag
        in: query
        required: false
        description: 'Block tag for proxy/stats calls. One of: latest, earliest, pending, or a hex block number.'
        schema:
          type: string
          example: latest
      - name: boolean
        in: query
        required: false
        description: Used with module=account&action=balance for multi-address balance queries. Set to true to enable.
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      - name: apikey
        in: query
        required: false
        description: Etherscan API key. Required for most endpoints; obtain at https://optimistic.etherscan.io/myapikey. Can also be passed via the apiKeyAuth security scheme.
        schema:
          type: string
      responses:
        '200':
          description: Successful API response. The `result` field type varies by module/action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              examples:
                accountBalance:
                  summary: Account balance response
                  value:
                    status: '1'
                    message: OK
                    result: '9999823230622199960'
                txList:
                  summary: Transaction list response
                  value:
                    status: '1'
                    message: OK
                    result:
                    - blockNumber: '12345678'
                      timeStamp: '1640000000'
                      hash: 0xabc123...
                      from: '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
                      to: '0x4200000000000000000000000000000000000042'
                      value: '1000000000000000000'
                      gas: '21000'
                      gasPrice: '1000000'
                      isError: '0'
                      confirmations: '100'
                error:
                  summary: Error response
                  value:
                    status: '0'
                    message: NOTOK
                    result: Error! Invalid address format
        '400':
          description: Bad request — invalid parameters.
        '401':
          description: Unauthorized — missing or invalid API key.
        '429':
          description: Rate limit exceeded. Free tier allows 3 calls/second and 100,000 calls/day.
        '500':
          description: Internal server error.
components:
  schemas:
    ApiResponse:
      type: object
      description: Standard Optimism Etherscan API envelope returned by all module actions.
      properties:
        status:
          type: string
          description: '"1" indicates success; "0" indicates an error.'
          enum:
          - '0'
          - '1'
          example: '1'
        message:
          type: string
          description: Human-readable status message. "OK" on success, "NOTOK" or error detail on failure.
          example: OK
        result:
          description: Module-specific response payload. May be a string (e.g. balance), an object, or an array of objects (e.g. transaction list).
          oneOf:
          - type: string
          - type: object
          - type: array
            items: {}
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: query
      name: apikey
      description: Etherscan API key obtained from https://optimistic.etherscan.io/myapikey. The free tier supports select chains with 3 req/s and 100k req/day. Paid plans start at $49/month for full multichain access.