openapi: 3.1.0
info:
  title: Ankr Advanced API
  description: |
    The Ankr Advanced API (AAPI) provides a specifically-tailored collection of JSON-RPC
    methods that optimize, index, cache, and store blockchain data across multiple
    EVM-compatible blockchains. The Advanced API exposes three logical groups:
    NFT, Token, and Query.
  version: "1.0.0"
  contact:
    name: Ankr
    url: https://www.ankr.com
    email: support@ankr.com
  license:
    name: Ankr Terms of Service
    url: https://www.ankr.com/terms/
servers:
  - url: https://rpc.ankr.com/multichain
    description: Public multichain endpoint
  - url: https://rpc.ankr.com/multichain/{API_KEY}
    description: Premium multichain endpoint
    variables:
      API_KEY:
        default: API_KEY
        description: Premium Plan project API key
security:
  - {}
  - ApiKeyAuth: []
tags:
  - name: NFT
    description: NFT methods — ownership, metadata, holders, and transfer history.
  - name: Token
    description: Token methods — balances, prices, holders, currencies, and transfers.
  - name: Query
    description: Query methods — blockchain statistics, blocks, logs, transactions, interactions.
paths:
  /:
    post:
      summary: Ankr Get NFTs By Owner
      description: Returns the full list of NFTs owned by a wallet address across supported chains.
      operationId: ankrGetNFTsByOwner
      tags:
        - NFT
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnkrGetNFTsByOwnerRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnkrGetNFTsByOwnerResponse'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
  /nft/metadata:
    post:
      summary: Ankr Get NFT Metadata
      description: Returns metadata for a specific NFT (token contract + token ID).
      operationId: ankrGetNFTMetadata
      tags:
        - NFT
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnkrGetNFTMetadataRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
  /nft/holders:
    post:
      summary: Ankr Get NFT Holders
      description: Returns the holders of a specific NFT contract.
      operationId: ankrGetNFTHolders
      tags:
        - NFT
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnkrGetNFTHoldersRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
  /nft/transfers:
    post:
      summary: Ankr Get NFT Transfers
      description: Returns the transfer history of a specific NFT contract or wallet.
      operationId: ankrGetNftTransfers
      tags:
        - NFT
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnkrGetNftTransfersRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
  /token/account-balance:
    post:
      summary: Ankr Get Account Balance
      description: Returns the native and ERC-20 balances for a wallet address across supported chains.
      operationId: ankrGetAccountBalance
      tags:
        - Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnkrGetAccountBalanceRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnkrGetAccountBalanceResponse'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
  /token/currencies:
    post:
      summary: Ankr Get Currencies
      description: Returns the catalog of currencies supported by a given blockchain.
      operationId: ankrGetCurrencies
      tags:
        - Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnkrChainScopedRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
  /token/price:
    post:
      summary: Ankr Get Token Price
      description: Returns the current USD price of a token (native or ERC-20) on a given chain.
      operationId: ankrGetTokenPrice
      tags:
        - Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnkrGetTokenPriceRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
  /token/price-history:
    post:
      summary: Ankr Get Token Price History
      description: Returns historical pricing data for a token over a specified time window.
      operationId: ankrGetTokenPriceHistory
      tags:
        - Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnkrGetTokenPriceHistoryRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
  /token/holders:
    post:
      summary: Ankr Get Token Holders
      description: Returns the list of holders for an ERC-20 token contract.
      operationId: ankrGetTokenHolders
      tags:
        - Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnkrGetTokenHoldersRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
  /token/holders-count:
    post:
      summary: Ankr Get Token Holders Count
      description: Returns the total count of holders for an ERC-20 token contract.
      operationId: ankrGetTokenHoldersCount
      tags:
        - Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnkrGetTokenHoldersRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
  /token/transfers:
    post:
      summary: Ankr Get Token Transfers
      description: Returns ERC-20 token transfer history for a wallet address or token contract.
      operationId: ankrGetTokenTransfers
      tags:
        - Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnkrGetTokenTransfersRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
  /query/blockchain-stats:
    post:
      summary: Ankr Get Blockchain Stats
      description: Returns aggregate statistics about supported blockchains.
      operationId: ankrGetBlockchainStats
      tags:
        - Query
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnkrChainScopedRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
  /query/blocks:
    post:
      summary: Ankr Get Blocks
      description: Returns full block information for a range of block heights.
      operationId: ankrGetBlocks
      tags:
        - Query
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnkrGetBlocksRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
  /query/logs:
    post:
      summary: Ankr Get Logs
      description: Returns event logs from a specified block range.
      operationId: ankrGetLogs
      tags:
        - Query
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnkrGetLogsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
  /query/transactions-by-hash:
    post:
      summary: Ankr Get Transactions By Hash
      description: Returns the full transaction details for the supplied transaction hash.
      operationId: ankrGetTransactionsByHash
      tags:
        - Query
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnkrGetTxnByHashRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
  /query/transactions-by-address:
    post:
      summary: Ankr Get Transactions By Address
      description: Returns the full transaction history for a wallet address.
      operationId: ankrGetTransactionsByAddress
      tags:
        - Query
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnkrGetTxnByAddressRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
  /query/interactions:
    post:
      summary: Ankr Get Interactions
      description: Returns the chains a wallet has interacted with (cross-chain activity index).
      operationId: ankrGetInteractions
      tags:
        - Query
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnkrGetInteractionsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: API_KEY
      description: Premium Plan API key passed as the trailing path segment.
  parameters:
    JsonRpcVersion:
      name: jsonrpc
      in: query
      description: JSON-RPC version (always "2.0").
      schema:
        type: string
        default: "2.0"
  schemas:
    AnkrBlockchain:
      type: string
      enum:
        - arbitrum
        - avalanche
        - base
        - bsc
        - eth
        - fantom
        - flare
        - gnosis
        - linea
        - optimism
        - polygon
        - scroll
        - stellar
        - story
        - syscoin
        - taiko
        - telos
        - xai
        - xlayer
    JsonRpcRequest:
      type: object
      required:
        - jsonrpc
        - method
        - id
      properties:
        jsonrpc:
          type: string
          default: "2.0"
        id:
          type: integer
          example: 1
        method:
          type: string
        params:
          type: object
    JsonRpcResponse:
      type: object
      properties:
        jsonrpc:
          type: string
        id:
          type: integer
        result:
          type: object
          additionalProperties: true
    AnkrGetNFTsByOwnerRequest:
      allOf:
        - $ref: '#/components/schemas/JsonRpcRequest'
        - type: object
          properties:
            method:
              type: string
              default: ankr_getNFTsByOwner
            params:
              type: object
              properties:
                walletAddress:
                  type: string
                blockchain:
                  oneOf:
                    - $ref: '#/components/schemas/AnkrBlockchain'
                    - type: array
                      items:
                        $ref: '#/components/schemas/AnkrBlockchain'
                pageSize:
                  type: integer
                pageToken:
                  type: string
    AnkrGetNFTsByOwnerResponse:
      type: object
      properties:
        jsonrpc:
          type: string
        id:
          type: integer
        result:
          type: object
          properties:
            owner:
              type: string
            assets:
              type: array
              items:
                type: object
                properties:
                  blockchain:
                    type: string
                  name:
                    type: string
                  tokenId:
                    type: string
                  tokenUrl:
                    type: string
                  imageUrl:
                    type: string
                  collectionName:
                    type: string
                  symbol:
                    type: string
                  contractType:
                    type: string
                  contractAddress:
                    type: string
                  traits:
                    type: array
                    items:
                      type: object
            nextPageToken:
              type: string
    AnkrGetNFTMetadataRequest:
      allOf:
        - $ref: '#/components/schemas/JsonRpcRequest'
        - type: object
          properties:
            method:
              type: string
              default: ankr_getNFTMetadata
            params:
              type: object
              properties:
                blockchain:
                  $ref: '#/components/schemas/AnkrBlockchain'
                contractAddress:
                  type: string
                tokenId:
                  type: string
    AnkrGetNFTHoldersRequest:
      allOf:
        - $ref: '#/components/schemas/JsonRpcRequest'
        - type: object
          properties:
            method:
              type: string
              default: ankr_getNFTHolders
            params:
              type: object
              properties:
                blockchain:
                  $ref: '#/components/schemas/AnkrBlockchain'
                contractAddress:
                  type: string
                pageSize:
                  type: integer
                pageToken:
                  type: string
    AnkrGetNftTransfersRequest:
      allOf:
        - $ref: '#/components/schemas/JsonRpcRequest'
        - type: object
          properties:
            method:
              type: string
              default: ankr_getNftTransfers
            params:
              type: object
              properties:
                blockchain:
                  oneOf:
                    - $ref: '#/components/schemas/AnkrBlockchain'
                    - type: array
                      items:
                        $ref: '#/components/schemas/AnkrBlockchain'
                fromBlock:
                  type: integer
                toBlock:
                  type: integer
                walletAddress:
                  type: string
                contractAddress:
                  type: string
                pageSize:
                  type: integer
                pageToken:
                  type: string
    AnkrChainScopedRequest:
      allOf:
        - $ref: '#/components/schemas/JsonRpcRequest'
        - type: object
          properties:
            params:
              type: object
              properties:
                blockchain:
                  oneOf:
                    - $ref: '#/components/schemas/AnkrBlockchain'
                    - type: array
                      items:
                        $ref: '#/components/schemas/AnkrBlockchain'
    AnkrGetAccountBalanceRequest:
      allOf:
        - $ref: '#/components/schemas/JsonRpcRequest'
        - type: object
          properties:
            method:
              type: string
              default: ankr_getAccountBalance
            params:
              type: object
              properties:
                walletAddress:
                  type: string
                blockchain:
                  oneOf:
                    - $ref: '#/components/schemas/AnkrBlockchain'
                    - type: array
                      items:
                        $ref: '#/components/schemas/AnkrBlockchain'
                onlyWhitelisted:
                  type: boolean
                  default: true
                nativeFirst:
                  type: boolean
    AnkrGetAccountBalanceResponse:
      type: object
      properties:
        jsonrpc:
          type: string
        id:
          type: integer
        result:
          type: object
          properties:
            totalBalanceUsd:
              type: string
            assets:
              type: array
              items:
                type: object
                properties:
                  blockchain:
                    type: string
                  tokenName:
                    type: string
                  tokenSymbol:
                    type: string
                  tokenDecimals:
                    type: integer
                  tokenType:
                    type: string
                  contractAddress:
                    type: string
                  holderAddress:
                    type: string
                  balance:
                    type: string
                  balanceRawInteger:
                    type: string
                  balanceUsd:
                    type: string
                  tokenPrice:
                    type: string
                  thumbnail:
                    type: string
    AnkrGetTokenPriceRequest:
      allOf:
        - $ref: '#/components/schemas/JsonRpcRequest'
        - type: object
          properties:
            method:
              type: string
              default: ankr_getTokenPrice
            params:
              type: object
              properties:
                blockchain:
                  $ref: '#/components/schemas/AnkrBlockchain'
                contractAddress:
                  type: string
    AnkrGetTokenPriceHistoryRequest:
      allOf:
        - $ref: '#/components/schemas/JsonRpcRequest'
        - type: object
          properties:
            method:
              type: string
              default: ankr_getTokenPriceHistory
            params:
              type: object
              properties:
                blockchain:
                  $ref: '#/components/schemas/AnkrBlockchain'
                contractAddress:
                  type: string
                fromTimestamp:
                  type: integer
                toTimestamp:
                  type: integer
                interval:
                  type: integer
                limit:
                  type: integer
    AnkrGetTokenHoldersRequest:
      allOf:
        - $ref: '#/components/schemas/JsonRpcRequest'
        - type: object
          properties:
            method:
              type: string
              default: ankr_getTokenHolders
            params:
              type: object
              properties:
                blockchain:
                  $ref: '#/components/schemas/AnkrBlockchain'
                contractAddress:
                  type: string
                pageSize:
                  type: integer
                pageToken:
                  type: string
    AnkrGetTokenTransfersRequest:
      allOf:
        - $ref: '#/components/schemas/JsonRpcRequest'
        - type: object
          properties:
            method:
              type: string
              default: ankr_getTokenTransfers
            params:
              type: object
              properties:
                blockchain:
                  oneOf:
                    - $ref: '#/components/schemas/AnkrBlockchain'
                    - type: array
                      items:
                        $ref: '#/components/schemas/AnkrBlockchain'
                address:
                  type: array
                  items:
                    type: string
                fromBlock:
                  type: integer
                toBlock:
                  type: integer
                fromTimestamp:
                  type: integer
                toTimestamp:
                  type: integer
                pageSize:
                  type: integer
                pageToken:
                  type: string
    AnkrGetBlocksRequest:
      allOf:
        - $ref: '#/components/schemas/JsonRpcRequest'
        - type: object
          properties:
            method:
              type: string
              default: ankr_getBlocks
            params:
              type: object
              properties:
                blockchain:
                  $ref: '#/components/schemas/AnkrBlockchain'
                fromBlock:
                  type: integer
                toBlock:
                  type: integer
                descOrder:
                  type: boolean
                includeLogs:
                  type: boolean
                includeTxs:
                  type: boolean
    AnkrGetLogsRequest:
      allOf:
        - $ref: '#/components/schemas/JsonRpcRequest'
        - type: object
          properties:
            method:
              type: string
              default: ankr_getLogs
            params:
              type: object
              properties:
                blockchain:
                  oneOf:
                    - $ref: '#/components/schemas/AnkrBlockchain'
                    - type: array
                      items:
                        $ref: '#/components/schemas/AnkrBlockchain'
                address:
                  type: array
                  items:
                    type: string
                fromBlock:
                  oneOf:
                    - type: integer
                    - type: string
                toBlock:
                  oneOf:
                    - type: integer
                    - type: string
                topics:
                  type: array
                  items:
                    type: array
                    items:
                      type: string
                pageSize:
                  type: integer
                pageToken:
                  type: string
                descOrder:
                  type: boolean
    AnkrGetTxnByHashRequest:
      allOf:
        - $ref: '#/components/schemas/JsonRpcRequest'
        - type: object
          properties:
            method:
              type: string
              default: ankr_getTransactionsByHash
            params:
              type: object
              properties:
                transactionHash:
                  type: string
                blockchain:
                  oneOf:
                    - $ref: '#/components/schemas/AnkrBlockchain'
                    - type: array
                      items:
                        $ref: '#/components/schemas/AnkrBlockchain'
                includeLogs:
                  type: boolean
                decodeLogs:
                  type: boolean
                decodeTxData:
                  type: boolean
    AnkrGetTxnByAddressRequest:
      allOf:
        - $ref: '#/components/schemas/JsonRpcRequest'
        - type: object
          properties:
            method:
              type: string
              default: ankr_getTransactionsByAddress
            params:
              type: object
              properties:
                address:
                  type: array
                  items:
                    type: string
                blockchain:
                  oneOf:
                    - $ref: '#/components/schemas/AnkrBlockchain'
                    - type: array
                      items:
                        $ref: '#/components/schemas/AnkrBlockchain'
                fromBlock:
                  oneOf:
                    - type: integer
                    - type: string
                toBlock:
                  oneOf:
                    - type: integer
                    - type: string
                fromTimestamp:
                  type: integer
                toTimestamp:
                  type: integer
                pageSize:
                  type: integer
                pageToken:
                  type: string
                includeLogs:
                  type: boolean
                descOrder:
                  type: boolean
    AnkrGetInteractionsRequest:
      allOf:
        - $ref: '#/components/schemas/JsonRpcRequest'
        - type: object
          properties:
            method:
              type: string
              default: ankr_getInteractions
            params:
              type: object
              properties:
                walletAddress:
                  type: string
    Error:
      type: object
      properties:
        jsonrpc:
          type: string
        id:
          type: integer
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
            data:
              type: object
  responses:
    ErrorResponse:
      description: Error response (JSON-RPC error envelope).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'