Amberdata On-Chain API

openapi: 3.1.0
info:
  title: blockchain-api
  version: '2'
servers:
  - url: https://api.amberdata.com/blockchains
security:
  - sec0: []
paths:
  /addresses/{hash}/token-balances/historical:
    get:
      summary: Token Balances Historical
      description: >-
        Retrieves the historical (time series) token balances for the specified
        address.
      operationId: get-token-balances
      parameters:
        - name: hash
          in: path
          description: The address to retrieve tokens for
          schema:
            type: string
            default: '0x19bf56fca395a600c20f732b05757f30ad24a719'
          required: true
        - name: amount
          in: query
          description: Filters by token balances which value is equal to this amount
          schema:
            type: integer
            format: int32
        - name: amountGt
          in: query
          description: Filter by token balances which value is greater than this amount
          schema:
            type: integer
            format: int32
        - name: amountGte
          in: query
          description: >-
            Filter by token balances which value is greater than or equal to
            this amount
          schema:
            type: integer
            format: int32
        - name: amountLt
          in: query
          description: Filter by token balances which value is less than this amount
          schema:
            type: integer
            format: int32
        - name: amountLte
          in: query
          description: >-
            Filter by token balances which value is less than or equal to this
            amount
          schema:
            type: integer
            format: int32
        - name: blockNumber
          in: query
          description: Filter by blockNumber
          schema:
            type: integer
            format: int32
        - name: startDate
          in: query
          description: Get balance after a start date (Requires endDate)
          schema:
            type: string
            format: date-time
        - name: endDate
          in: query
          description: Get balances before the specified date (Requires startDate)
          schema:
            type: string
            format: date-time
        - name: tokenAddress
          in: query
          description: Filter by the specified token address.
          schema:
            type: string
        - name: page
          in: query
          description: The page number to return.
          schema:
            type: integer
            format: int32
            default: 0
        - name: size
          in: query
          description: Number of records per page
          schema:
            type: integer
            format: int32
            default: 50
        - name: x-amberdata-blockchain-id
          in: header
          description: The id of the blockchain
          schema:
            type: string
            enum:
              - ethereum-mainnet
              - polygon-mainnet
            default: ethereum-mainnet
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                    default: 0
                  title:
                    type: string
                    example: OK
                  description:
                    type: string
                    example: Successful request
                  payload:
                    type: object
                    properties:
                      totalRecords:
                        type: integer
                        example: 804219
                        default: 0
                      records:
                        type: array
                        items:
                          type: object
                          properties:
                            blockchainId:
                              type: string
                              example: 1c9c969065fcd1cf
                            amount:
                              type: string
                              example: '1341'
                            address:
                              type: string
                              example: '0x06012c8cf97bead5deae237070f9587f8e7a266d'
                            holder:
                              type: string
                              example: '0xbae25a69a6eb7341ee834be7635e247e22a1e57a'
                            decimals:
                              type: string
                              example: '0'
                            name:
                              type: string
                              example: CryptoKitties
                            symbol:
                              type: string
                              example: CK
                            isERC20:
                              type: boolean
                              example: false
                              default: true
                            isERC721:
                              type: boolean
                              example: true
                              default: true
                            isERC777:
                              type: boolean
                              example: false
                              default: true
                            isERC884:
                              type: boolean
                              example: false
                              default: true
                            isERC998:
                              type: boolean
                              example: false
                              default: true
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                type: object
                properties: {}
      deprecated: false
      security:
        - ApiKeyAuth: []
  /addresses/{hash}/token-balances/latest:
    get:
      summary: Token Balances Latest
      description: Retrieves the tokens this address is holding.
      operationId: get-address-tokens
      parameters:
        - name: hash
          in: path
          description: address to retrieve tokens for
          schema:
            type: string
            default: '0x19bf56fca395a600c20f732b05757f30ad24a719'
          required: true
        - name: direction
          in: query
          description: The direction by which to sort the tokens (ascending or descending).
          schema:
            type: string
        - name: includePrice
          in: query
          description: >-
            Indicates whether or not to include price data with the results.
            Options: true, false. <a
            href="https://docs.amberdata.io/reference#query-params">More
            Details.</a>
          schema:
            type: string
        - name: currency
          in: query
          description: >-
            The currency of the price information (usd or eth.) - only used in
            conjunction with includePrice. <a
            href="https://docs.amberdata.io/reference#query-params">More
            Details.</a>
          schema:
            type: string
        - name: sortType
          in: query
          description: The metric by which to rank the tokens (amount, name, symbol).
          schema:
            type: string
        - name: page
          in: query
          description: The page number to return.
          schema:
            type: string
            default: '0'
        - name: size
          in: query
          description: The number of records per page.
          schema:
            type: string
            default: '50'
        - name: x-amberdata-blockchain-id
          in: header
          description: The id of the blockchain
          schema:
            type: string
            enum:
              - ethereum-mainnet
              - polygon-mainnet
              - solana-mainnet
            default: ethereum-mainnet
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                    default: 0
                  title:
                    type: string
                    example: OK
                  description:
                    type: string
                    example: Successful request
                  totalRecords:
                    type: integer
                    example: 84
                  payload:
                    type: object
                    properties:
                      totalRecords:
                        type: integer
                        example: 804219
                        default: 0
                      records:
                        type: array
                        items:
                          type: object
                          properties:
                            blockchainId:
                              type: string
                              example: 1c9c969065fcd1cf
                            amount:
                              type: string
                              example: '100000100000000000000000000'
                            address:
                              type: string
                              example: '0xfa6f7881e52fdf912c4a285d78a3141b089ce859'
                            holder:
                              type: string
                              example: '0xbae25a69a6eb7341ee834be7635e247e22a1e57a'
                            decimals:
                              type: string
                              example: '18'
                            name:
                              type: string
                              example: Avocado
                            symbol:
                              type: string
                              example: CK
                            isERC20:
                              type: boolean
                              example: false
                              default: true
                            isERC721:
                              type: boolean
                              example: true
                              default: true
                            isERC777:
                              type: boolean
                              example: false
                              default: true
                            isERC884:
                              type: boolean
                              example: false
                              default: true
                            isERC998:
                              type: boolean
                              example: false
                              default: true
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                type: object
                properties: {}
      deprecated: false
      security:
        - ApiKeyAuth: []
  /addresses/balances:
    get:
      summary: Account & Token Balances Latest Batch - Multiple Wallets
      description: >-
        Retrieves the latest account and token balances for the specified
        addresses.

        This is useful if you want to get an entire portfolio's summary in a
        single call. Get totals for ETH & all token amounts with market prices.
      operationId: address-balances-batch
      parameters:
        - name: addresses
          in: query
          description: >-
            A comma separated list of addresses. NOTE: Max 200 addresses per
            request!
          required: true
          schema:
            type: string
            default: >-
              0x3f5CE5FBFe3E9af3971dD833D26bA9b5C936f0bE,0xF02e86D9E0eFd57aD034FaF52201B79917fE0713
        - name: blockNumber
          in: query
          description: >-
            Get balances for addresses at a specific block height. (NOTE: does
            not support token holdings for Ethereum at this time.)
          schema:
            type: string
        - name: includePrice
          in: query
          description: >-
            Indicates whether or not to include price data with the results.
            Options: true, false.
          schema:
            type: boolean
            default: false
        - name: currency
          in: query
          description: >-
            The currency of the price information (usd or btc.) - only used in
            conjunction with includePrice.
          schema:
            type: string
        - name: timeFormat
          in: query
          description: >-
            **[Optional]** Time format of the timestamps in the return
            payload.<BR/>**[Defaults]** `milliseconds | ms* | iso | iso8601 | hr
            | human_readable`
          schema:
            type: string
        - name: x-amberdata-blockchain-id
          in: header
          description: The id of the blockchain
          schema:
            type: string
            enum:
              - bitcoin-mainnet
              - bitcoin-abc-mainnet
              - ethereum-mainnet
              - litecoin-mainnet
              - polygon-mainnet
            default: ethereum-mainnet
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                  title:
                    type: string
                    description: Status title
                  description:
                    type: string
                    description: Status description
                  payload:
                    type: object
                    description: >-
                      Map of blockchain addresses to their balance and token
                      information
                    additionalProperties:
                      type: object
                      properties:
                        balance:
                          type: string
                          description: Current balance in wei/base units as a string
                        balanceIn:
                          type: string
                          description: Total balance inflow in wei/base units as a string
                        balanceOut:
                          type: string
                          description: Total balance outflow in wei/base units as a string
                        price:
                          type: object
                          required:
                            - balance
                          properties:
                            balance:
                              type: object
                              description: Contains price details for the main balance.
                              required:
                                - currency
                                - quote
                                - total
                              properties:
                                currency:
                                  type: string
                                  description: >-
                                    The currency of the price information (e.g.,
                                    'usd').
                                quote:
                                  type: string
                                  description: >-
                                    The price per unit of the native blockchain
                                    currency.
                                total:
                                  type: string
                                  description: >-
                                    The total value of the main balance in the
                                    specified currency.
                        tokens:
                          type: array
                          description: Array of token holdings for this address
                          items:
                            type: object
                            properties:
                              decimals:
                                type: integer
                                description: >-
                                  Number of decimal places for the token (can be
                                  -1 for invalid/unknown tokens)
                              name:
                                type: string
                                description: Human-readable name of the token
                              symbol:
                                type: string
                                description: Token symbol or ticker
                              amount:
                                type: string
                                description: Token amount held in base units as a string
                              timestamp:
                                type: string
                                format: date-time
                                description: ISO 8601 timestamp of the last balance update
                              address:
                                type: string
                                description: Ethereum contract address of the token
                            required:
                              - decimals
                              - name
                              - symbol
                              - amount
                              - timestamp
                              - address
                      required:
                        - balance
                        - balanceIn
                        - balanceOut
                        - tokens
                required:
                  - status
                  - title
                  - description
                  - payload
              example:
                status: 200
                title: OK
                description: Successful request
                payload:
                  '0x3f7bb687ab9f04b055f4d326977f17471270499c':
                    balance: '492231474000'
                    balanceIn: '3182796362466409764'
                    balanceOut: '3182795870234935764'
                    price:
                      balance:
                        currency: usd
                        quote: '3045.10978468'
                        total: '0.00149890'
                    tokens:
                      - decimals: 18
                        name: Sign
                        symbol: SIGN
                        amount: '21000000000000000000'
                        timestamp: '2025-06-17T13:39:11.000Z'
                        address: '0x868fced65edbf0056c4163515dd840e9f287a4c3'
                      - decimals: 0
                        name: Seeing Signs
                        symbol: $IGN
                        amount: '0'
                        timestamp: '2025-12-04T20:03:35.000Z'
                        address: '0xbc37ee54f066e79c23389c55925f877f79f3cb84'
                      - decimals: 18
                        name: Wrapped Ether
                        symbol: WETH
                        amount: '0'
                        timestamp: '2025-12-04T20:12:23.000Z'
                        address: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2'
                  '0x3b0684dcfb5c0d50e75d512b4562b440c96a1b8d':
                    balance: '197722156918921153'
                    balanceIn: '200000003000000006'
                    balanceOut: '2277846081078853'
                    tokens:
                      - decimals: 18
                        name: Gemini3
                        symbol: Gemini3
                        amount: '10000000000000000000'
                        timestamp: '2025-11-27T10:10:59.000Z'
                        address: '0xa62c5ef5dc67b6b38b3d14c79efca2c27eca8518'
                      - decimals: 18
                        name: ePEPE
                        symbol: ePEPE
                        amount: '20000000000000000000'
                        timestamp: '2025-11-27T10:10:59.000Z'
                        address: '0xdc5cb57711ac6ea18bc9e07404a3fa2a9b4913e9'
                      - decimals: 18
                        name: SPX
                        symbol: SPX
                        amount: '10000000000000000000'
                        timestamp: '2025-11-27T09:08:23.000Z'
                        address: '0xdd0d0781fd0045ccb8c4f56ab4229a37f8e86e42'
        '401':
          description: '401'
          content:
            text/plain:
              examples:
                Result:
                  value: Unauthorized
        '404':
          description: '404'
          content:
            text/plain:
              examples:
                Address Not Found:
                  value: Unknown address or address is not a contract
      deprecated: false
      security:
        - ApiKeyAuth: []
  /addresses/{hash}/balances:
    get:
      summary: Account and Token Balance Latest
      description: >-
        Retrieves the latest account and token balances for the specified
        address.
      operationId: address-balances
      parameters:
        - name: includePrice
          in: query
          description: >-
            Indicates whether or not to include price data with the results.
            Options: true, false.
          schema:
            type: boolean
        - name: currency
          in: query
          description: >-
            The currency of the price information (usd or btc.) - only used in
            conjunction with includePrice.
          schema:
            type: string
        - name: x-amberdata-blockchain-id
          in: header
          description: The id of the blockchain
          schema:
            type: string
            enum:
              - ethereum-mainnet
              - solana-mainnet
            default: ethereum-mainnet
        - name: timeFormat
          in: query
          description: >-
            **[Optional]** Time format of the timestamps in the return
            payload.<BR/>**[Defaults]** `milliseconds | ms* | iso | iso8601 | hr
            | human_readable`
          schema:
            type: string
        - name: hash
          in: path
          description: The address for which to retrieve balances.
          schema:
            type: string
            default: '0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be'
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                    default: 0
                  title:
                    type: string
                    example: OK
                  description:
                    type: string
                    example: Successful request
                  payload:
                    type: object
                    properties:
                      balance:
                        type: string
                        example: '5.4777658867801856271744e+22'
                      balanceIn:
                        type: string
                        example: '5.5265160095722306803399618e+25'
                      balanceOut:
                        type: string
                        example: '5.5210382436854504947127874e+25'
                      tokens:
                        type: array
                        items:
                          type: object
                          properties:
                            address:
                              type: string
                              example: '0x9f8f72aa9304c8b593d555f12ef6589cc3a579a2'
                            decimals:
                              type: integer
                              example: 18
                            milliseconds:
                              type: integer
                              format: int64
                              example: 1559665587000
                            name:
                              type: string
                              example: Maker
                            symbol:
                              type: string
                              example: MKR
                            amount:
                              type: string
                              example: '187720361680000000000'
                            timestamp:
                              type: integer
                              format: int64
                              example: 1559665587000
                            price:
                              type: object
                              properties:
                                amount:
                                  type: object
                                  properties:
                                    currency:
                                      type: string
                                      example: usd
                                    quote:
                                      type: string
                                      example: '680.815866247'
                                    total:
                                      type: string
                                      example: '127803.0006493693442149600000000'
        '401':
          description: '401'
          content:
            text/plain:
              examples:
                Result:
                  value: Unauthorized
        '404':
          description: '404'
          content:
            text/plain:
              examples:
                Address Not Found:
                  value: Unknown address or address is not a contract
      deprecated: false
      security:
        - ApiKeyAuth: []
  /addresses/{hash}/account-balances/historical:
    get:
      summary: Account Balance Historical
      description: >-
        Retrieves the historical (time series) account balances for the
        specified address.
      operationId: get-historical-account-balances
      parameters:
        - name: hash
          in: path
          description: The address to retrieve the account balances for
          schema:
            type: string
            default: '0x06012c8cf97bead5deae237070f9587f8e7a266d'
          required: true
        - name: blockNumber
          in: query
          description: FIlter by account balances at block number
          schema:
            type: integer
            format: int32
        - name: startDate
          in: query
          description: FIlter by account balances which happened after this date
          schema:
            type: string
            format: date-time
        - name: endDate
          in: query
          description: FIlter by account balances which happened before this date
          schema:
            type: string
            format: date-time
        - name: value
          in: query
          description: FIlter by account balances where the balance is equal to this value
          schema:
            type: integer
            format: int32
        - name: valueGt
          in: query
          description: >-
            FIlter by account balances where the balance is greater than this
            value
          schema:
            type: integer
            format: int32
        - name: valueGte
          in: query
          description: >-
            FIlter by account balances where the balance is greater than or
            equal to this value
          schema:
            type: integer
            format: int32
        - name: valueLt
          in: query
          description: FIlter by account balances where the balance is less than this value
          schema:
            type: integer
            format: int32
        - name: valueLte
          in: query
          description: >-
            FIlter by account balances where the balance is less than or equal
            to this value
          schema:
            type: integer
            format: int32
        - name: includePrice
          in: query
          description: >-
            Indicates whether or not to include price data with the results.
            Options: true, false.
          schema:
            type: boolean
        - name: currency
          in: query
          description: >-
            The currency of the price information (usd or btc.) - only used in
            conjunction with includePrice.
          schema:
            type: string
        - name: page
          in: query
          description: The page number to return.
          schema:
            type: integer
            format: int32
            default: 0
        - name: size
          in: query
          description: Number of records per page
          schema:
            type: integer
            format: int32
            default: 50
        - name: timeFormat
          in: query
          description: >-
            **[Optional]** Time format of the timestamps in the return
            payload.<BR/>**[Defaults]** `milliseconds | ms* | iso | iso8601 | hr
            | human_readable`
          schema:
            type: string
        - name: x-amberdata-blockchain-id
          in: header
          description: The id of the blockchain
          schema:
            type: string
            enum:
              - bitcoin-mainnet
              - bitcoin-abc-mainnet
              - ethereum-mainnet
              - litecoin-mainnet
              - polygon-mainnet
            default: ethereum-mainnet
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                    default: 0
                  title:
                    type: string
                    example: OK
                  description:
                    type: string
                    example: Successful request
                  payload:
                    type: object
                    properties:
                      data:
                        type: array
                        description: >-
                          Array of rows, each row is an array of values in the
                          same order as metadata.columns
                        items:
                          type: array
                          minItems: 5
                          maxItems: 5
                          items:
                            oneOf:
                              - type: string
                              - type: integer
                          example:
                            - '0x06012c8cf97bead5deae237070f9587f8e7a266d'
                            - '7446815'
                            - 1553638828000
                            - 0
                            - '65183168478133965282'
                      metadata:
                        type: object
                        properties:
                          columns:
                            type: array
                            items:
                              type: string
                            example:
                              - address
                              - blockNumber
                              - timestamp
                              - timestampNanoseconds
                              - value
                          totalRecords:
                            type: integer
                            example: 1118325
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                type: object
                properties: {}
      deprecated: false
      security:
        - ApiKeyAuth: []
  /addresses/{hash}/account-balances/latest:
    get:
      summary: Account Balance Latest
      description: Retrieves the current account balance for the specified address.
      operationId: get-current-account-balance
      parameters:
  

# --- truncated at 32 KB (138 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/amberdata/refs/heads/main/openapi/amberdata-blockchain-openapi.yaml