openapi: 3.0.3
info:
  title: PolygonScan API API
  version: '2.0'
  description: REST API for querying Polygon PoS blockchain data including account balances, transactions, token transfers, smart contract source code and ABI, event logs, gas prices, and network statistics via Etherscan V2 unified endpoint with chainid 137.
  termsOfService: https://polygonscan.com/apiterms
  contact:
    name: PolygonScan Support
    email: apisupport@etherscan.io
    url: https://polygonscan.com/contactus
servers:
- url: https://api.etherscan.io/v2/api
  description: Etherscan V2 unified endpoint (use chainid=137 for Polygon PoS)
- url: https://api.polygonscan.com/api
  description: PolygonScan legacy endpoint
security:
- ApiKeyAuth: []
tags:
- name: API
paths:
  /:
    get:
      summary: PolygonScan API
      description: All PolygonScan API calls use this single endpoint. The specific action is determined by the module and action query parameters.
      operationId: apiCall
      tags:
      - API
      parameters:
      - name: module
        in: query
        required: true
        schema:
          type: string
          enum:
          - account
          - contract
          - transaction
          - block
          - logs
          - gastracker
          - stats
          - token
        description: API module to call.
      - name: action
        in: query
        required: true
        schema:
          type: string
        description: Action to perform within the selected module.
      - $ref: '#/components/parameters/chainid'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
components:
  schemas:
    ApiResponse:
      type: object
      properties:
        status:
          type: string
          description: 1 for success, 0 for error.
          example: '1'
        message:
          type: string
          description: OK on success, NOTOK on error.
          example: OK
        result:
          description: Result data - type varies by endpoint.
  parameters:
    chainid:
      name: chainid
      in: query
      required: false
      schema:
        type: string
        default: '137'
      description: Chain ID. Use 137 for Polygon PoS mainnet, 80002 for Amoy testnet.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: apikey
      description: API key obtained from https://polygonscan.com/myapikey
externalDocs:
  description: Etherscan V2 API Documentation
  url: https://docs.etherscan.io/etherscan-v2
x-polygonscan-modules:
  account:
    description: Account and balance related actions
    actions:
      balance:
        description: Get native MATIC balance for a single address
        parameters:
          required:
          - module
          - action
          - address
          - apikey
          optional:
          - chainid
          - tag
          address: Polygon address to query
          tag: 'latest or block number in hex (default: latest)'
        response: Native token balance in wei as a string
      balancemulti:
        description: Get native MATIC balances for multiple addresses (max 20)
        parameters:
          required:
          - module
          - action
          - address
          - apikey
          optional:
          - chainid
          - tag
          address: Comma-separated list of addresses (max 20)
        response: Array of {account, balance} objects
      txlist:
        description: Get normal transactions by address
        parameters:
          required:
          - module
          - action
          - address
          - apikey
          optional:
          - chainid
          - startblock
          - endblock
          - page
          - offset
          - sort
        response: Array of transaction objects
      txlistinternal:
        description: Get internal transactions by address
        parameters:
          required:
          - module
          - action
          - address
          - apikey
          optional:
          - chainid
          - startblock
          - endblock
          - page
          - offset
          - sort
        response: Array of internal transaction objects
      tokentx:
        description: Get ERC-20 token transfer events by address
        parameters:
          required:
          - module
          - action
          - address
          - apikey
          optional:
          - chainid
          - contractaddress
          - startblock
          - endblock
          - page
          - offset
          - sort
        response: Array of ERC-20 token transfer objects
      tokennfttx:
        description: Get ERC-721 NFT transfer events by address
        parameters:
          required:
          - module
          - action
          - address
          - apikey
          optional:
          - chainid
          - contractaddress
          - startblock
          - endblock
          - page
          - offset
          - sort
        response: Array of ERC-721 transfer objects
      token1155tx:
        description: Get ERC-1155 token transfer events by address
        parameters:
          required:
          - module
          - action
          - address
          - apikey
          optional:
          - chainid
          - contractaddress
          - startblock
          - endblock
          - page
          - offset
          - sort
        response: Array of ERC-1155 transfer objects
      addresstokenbalance:
        description: Get ERC-20 token holdings for an address
        parameters:
          required:
          - module
          - action
          - address
          - apikey
          optional:
          - chainid
          - page
          - offset
        response: Array of token balance objects
      addresstokennftbalance:
        description: Get ERC-721 NFT holdings for an address
        parameters:
          required:
          - module
          - action
          - address
          - apikey
          optional:
          - chainid
          - page
          - offset
        response: Array of NFT balance objects
      addresstokennftinventory:
        description: Get ERC-721 NFT inventory (token IDs) for an address
        parameters:
          required:
          - module
          - action
          - address
          - contractaddress
          - apikey
          optional:
          - chainid
          - page
          - offset
        response: Array of NFT inventory objects with token IDs
      tokenbalance:
        description: Get ERC-20 token account balance for a specific contract
        parameters:
          required:
          - module
          - action
          - contractaddress
          - address
          - apikey
          optional:
          - chainid
          - tag
        response: Token balance as a string
      getminedblocks:
        description: Get list of blocks validated by an address
        parameters:
          required:
          - module
          - action
          - address
          - apikey
          optional:
          - chainid
          - blocktype
          - page
          - offset
        response: Array of mined block objects
  contract:
    description: Smart contract related actions
    actions:
      getabi:
        description: Get ABI for a verified smart contract
        parameters:
          required:
          - module
          - action
          - address
          - apikey
          optional:
          - chainid
        response: Contract ABI as a JSON-encoded string
      getsourcecode:
        description: Get source code for a verified smart contract
        parameters:
          required:
          - module
          - action
          - address
          - apikey
          optional:
          - chainid
        response: Array of contract source objects with SourceCode, ABI, ContractName, CompilerVersion, etc.
      getcontractcreation:
        description: Get contract creator address and creation transaction hash
        parameters:
          required:
          - module
          - action
          - contractaddresses
          - apikey
          optional:
          - chainid
        response: Array of contract creation objects
      verifysourcecode:
        description: Submit Solidity source code for verification
        parameters:
          required:
          - module
          - action
          - contractaddress
          - sourceCode
          - codeformat
          - contractname
          - compilerversion
          - apikey
          optional:
          - chainid
          - optimizationUsed
          - runs
          - constructorArguements
          - evmversion
          - licenseType
        response: GUID for checking verification status
      checkverifystatus:
        description: Check contract verification submission status
        parameters:
          required:
          - module
          - action
          - guid
          - apikey
          optional:
          - chainid
        response: Verification status string
  transaction:
    description: Transaction status actions
    actions:
      getstatus:
        description: Check contract execution status (if there were errors during execution)
        parameters:
          required:
          - module
          - action
          - txhash
          - apikey
          optional:
          - chainid
        response: Object with isError and errDescription fields
      gettxreceiptstatus:
        description: Check transaction receipt status (only for post-Byzantium fork transactions)
        parameters:
          required:
          - module
          - action
          - txhash
          - apikey
          optional:
          - chainid
        response: Object with status field (1 for success, 0 for failed)
  block:
    description: Block data actions
    actions:
      getblockreward:
        description: Get block and uncle rewards by block number
        parameters:
          required:
          - module
          - action
          - blockno
          - apikey
          optional:
          - chainid
        response: Block reward object with blockNumber, timeStamp, blockMiner, blockReward, uncles, uncleInclusionReward
      getblockcountdown:
        description: Get estimated time remaining until a block is validated
        parameters:
          required:
          - module
          - action
          - blockno
          - apikey
          optional:
          - chainid
        response: Object with CurrentBlock, CountdownBlock, RemainingBlock, EstimateTimeInSec
      getblocknobytime:
        description: Get block number closest to a provided Unix timestamp
        parameters:
          required:
          - module
          - action
          - timestamp
          - closest
          - apikey
          optional:
          - chainid
          timestamp: Unix timestamp in seconds
          closest: before or after
        response: Block number as a string
  logs:
    description: Event log actions
    actions:
      getLogs:
        description: Get event logs by address and/or block range
        parameters:
          required:
          - module
          - action
          - apikey
          at_least_one:
          - address
          - topic0
          optional:
          - chainid
          - address
          - fromBlock
          - toBlock
          - topic0
          - topic1
          - topic2
          - topic3
          - topic0_1_opr
          - topic1_2_opr
          - topic2_3_opr
          - topic0_2_opr
          - page
          - offset
        response: Array of event log objects
  gastracker:
    description: Gas price estimation actions
    actions:
      gasoracle:
        description: Get gas price oracle with safe/proposed/fast gas prices
        parameters:
          required:
          - module
          - action
          - apikey
          optional:
          - chainid
        response: Object with LastBlock, SafeGasPrice, ProposeGasPrice, FastGasPrice, suggestBaseFee, gasUsedRatio
      gasestimate:
        description: Get estimated confirmation time for a given gas price
        parameters:
          required:
          - module
          - action
          - gasprice
          - apikey
          optional:
          - chainid
          gasprice: Gas price in wei
        response: Estimated wait time in seconds
  stats:
    description: Network statistics actions
    actions:
      maticprice:
        description: Get latest MATIC price in BTC and USD
        parameters:
          required:
          - module
          - action
          - apikey
          optional:
          - chainid
        response: Object with maticbtc, maticusd, maticbtc_timestamp, maticusd_timestamp
      tokensupply:
        description: Get total supply of an ERC-20 token
        parameters:
          required:
          - module
          - action
          - contractaddress
          - apikey
          optional:
          - chainid
        response: Token total supply as a string
      tokeninfo:
        description: Get token information including name, symbol, decimals
        parameters:
          required:
          - module
          - action
          - contractaddress
          - apikey
          optional:
          - chainid
        response: Array of token info objects
      nodecount:
        description: Get total number of nodes in Polygon network
        parameters:
          required:
          - module
          - action
          - apikey
          optional:
          - chainid
        response: Object with UTCDate and TotalNodeCount
      dailytx:
        description: Get daily transaction count (PRO endpoint)
        parameters:
          required:
          - module
          - action
          - startdate
          - enddate
          - sort
          - apikey
          optional:
          - chainid
        response: Array of daily transaction count objects