Uniblock Tokens API

openapi: 3.2.0
info:
  title: Uniblock Unified Tokens API
  description: The Uniblock Unified API provides a single standardized interface for interacting with multiple blockchain networks and data providers.
  version: '1.0'
  contact:
    name: Uniblock Support
    url: https://docs.uniblock.dev
  termsOfService: https://uniblock.dev/terms
servers:
- url: https://api.uniblock.dev/uni/v1
  description: Uniblock Production Server
security:
- apiKeyHeader: []
tags:
- name: Tokens
  description: Endpoints for retrieving fungible token data including metadata, balances, prices, transfers, and allowances across multiple blockchain networks.
paths:
  /token/metadata:
    get:
      operationId: getTokenMetadata
      summary: Get Token Metadata
      description: Retrieves metadata about a specific fungible token including name, symbol, decimals, and contract details. Supports multiple blockchain networks through automatic provider routing.
      tags:
      - Tokens
      parameters:
      - $ref: '#/components/parameters/chainParam'
      - $ref: '#/components/parameters/contractAddressParam'
      responses:
        '200':
          description: Successful response with token metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenMetadataResponse'
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Token not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /token/balance:
    get:
      operationId: getTokenBalance
      summary: Get Token Balances
      description: Retrieves the native and fungible token balances associated with a specific wallet address. Returns balances across tokens held by the address on the specified blockchain network.
      tags:
      - Tokens
      parameters:
      - $ref: '#/components/parameters/chainParam'
      - $ref: '#/components/parameters/walletAddressParam'
      responses:
        '200':
          description: Successful response with token balances
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenBalanceResponse'
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /token/balance/historical:
    get:
      operationId: getTokenBalanceHistorical
      summary: Get Historical Token Balances
      description: Retrieves historical token balances for a specific wallet address at a given point in time, enabling tracking of balance changes over time.
      tags:
      - Tokens
      parameters:
      - $ref: '#/components/parameters/chainParam'
      - $ref: '#/components/parameters/walletAddressParam'
      - name: blockNumber
        in: query
        description: The block number at which to retrieve the historical balance.
        schema:
          type: integer
      responses:
        '200':
          description: Successful response with historical token balances
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenBalanceResponse'
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /token/transfers:
    get:
      operationId: getTokenTransfers
      summary: Get Token Transfers
      description: Retrieves a list of token transfers for a specific wallet address, including both incoming and outgoing transfers of fungible tokens. Useful for tracking token swaps and transfer history.
      tags:
      - Tokens
      parameters:
      - $ref: '#/components/parameters/chainParam'
      - $ref: '#/components/parameters/walletAddressParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/cursorParam'
      responses:
        '200':
          description: Successful response with token transfers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenTransfersResponse'
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /token/allowances:
    get:
      operationId: getTokenAllowances
      summary: Get Token Allowances
      description: Retrieves token allowances granted by a specific wallet address to spender contracts. Useful for inspecting which contracts have approval to spend tokens on behalf of the wallet owner.
      tags:
      - Tokens
      parameters:
      - $ref: '#/components/parameters/chainParam'
      - $ref: '#/components/parameters/walletAddressParam'
      responses:
        '200':
          description: Successful response with token allowances
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenAllowancesResponse'
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /token/price:
    get:
      operationId: getTokenPrice
      summary: Get Token Price
      description: Retrieves the current USD price for a specific token by its contract address and chain. Aggregates pricing data from multiple exchange and data provider sources.
      tags:
      - Tokens
      parameters:
      - $ref: '#/components/parameters/chainParam'
      - $ref: '#/components/parameters/contractAddressParam'
      responses:
        '200':
          description: Successful response with token price
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenPriceResponse'
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /token/price/historical:
    get:
      operationId: getTokenPriceHistorical
      summary: Get Historical Token Price
      description: Retrieves the historical price, volume, and market cap of a token at a given date, enabling analysis of price movements over time.
      tags:
      - Tokens
      parameters:
      - $ref: '#/components/parameters/chainParam'
      - $ref: '#/components/parameters/contractAddressParam'
      - name: date
        in: query
        description: The date for which to retrieve historical price data in ISO 8601 format.
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Successful response with historical token price
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenPriceHistoricalResponse'
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      description: Standard error response returned when a request fails.
      properties:
        success:
          type: boolean
          description: Indicates whether the request was successful.
          example: false
        error:
          type: object
          description: Error details object.
          properties:
            code:
              type: string
              description: Machine-readable error code.
            message:
              type: string
              description: Human-readable error message describing what went wrong.
    TokenTransfer:
      type: object
      description: A single token transfer event between two addresses.
      properties:
        transactionHash:
          type: string
          description: The hash of the transaction containing this transfer.
        from:
          type: string
          description: The sender address.
        to:
          type: string
          description: The recipient address.
        value:
          type: string
          description: The amount transferred in the token's smallest unit.
        contractAddress:
          type: string
          description: The smart contract address of the transferred token.
        tokenName:
          type: string
          description: The name of the transferred token.
        tokenSymbol:
          type: string
          description: The symbol of the transferred token.
        blockNumber:
          type: integer
          description: The block number in which the transfer occurred.
        blockTimestamp:
          type: string
          format: date-time
          description: The timestamp of the block in which the transfer occurred.
    TokenBalance:
      type: object
      description: Balance of a specific token held by a wallet address.
      properties:
        contractAddress:
          type: string
          description: The smart contract address of the token.
        name:
          type: string
          description: The display name of the token.
        symbol:
          type: string
          description: The ticker symbol of the token.
        decimals:
          type: integer
          description: The number of decimal places the token uses.
        balance:
          type: string
          description: The token balance in its smallest unit.
        balanceFormatted:
          type: string
          description: The token balance formatted with proper decimal places.
    TokenBalanceResponse:
      type: object
      description: Response containing token balances for a wallet address.
      properties:
        success:
          type: boolean
          description: Indicates whether the request was successful.
        data:
          type: array
          description: List of token balances held by the address.
          items:
            $ref: '#/components/schemas/TokenBalance'
    TokenAllowance:
      type: object
      description: A token allowance granted to a spender contract.
      properties:
        contractAddress:
          type: string
          description: The smart contract address of the token.
        spender:
          type: string
          description: The address of the approved spender.
        allowance:
          type: string
          description: The approved allowance amount.
        tokenName:
          type: string
          description: The name of the token.
        tokenSymbol:
          type: string
          description: The symbol of the token.
    TokenTransfersResponse:
      type: object
      description: Response containing a paginated list of token transfers.
      properties:
        success:
          type: boolean
          description: Indicates whether the request was successful.
        data:
          type: array
          description: List of token transfer events.
          items:
            $ref: '#/components/schemas/TokenTransfer'
        cursor:
          type: string
          description: Pagination cursor for the next page of results.
    TokenMetadataResponse:
      type: object
      description: Response containing metadata about a fungible token.
      properties:
        success:
          type: boolean
          description: Indicates whether the request was successful.
        data:
          $ref: '#/components/schemas/TokenMetadata'
    TokenPriceHistoricalResponse:
      type: object
      description: Response containing historical price data for a token.
      properties:
        success:
          type: boolean
          description: Indicates whether the request was successful.
        data:
          type: object
          description: Historical token price data.
          properties:
            usdPrice:
              type: number
              format: double
              description: The historical price of the token in USD.
            date:
              type: string
              format: date
              description: The date of the historical price.
            volume:
              type: number
              format: double
              description: The trading volume on the specified date.
            marketCap:
              type: number
              format: double
              description: The market capitalization on the specified date.
    TokenPriceResponse:
      type: object
      description: Response containing the current price of a token.
      properties:
        success:
          type: boolean
          description: Indicates whether the request was successful.
        data:
          type: object
          description: Token price data.
          properties:
            usdPrice:
              type: number
              format: double
              description: The current price of the token in USD.
            chain:
              type: string
              description: The blockchain network.
            contractAddress:
              type: string
              description: The contract address of the token.
    TokenAllowancesResponse:
      type: object
      description: Response containing token allowances granted by a wallet address.
      properties:
        success:
          type: boolean
          description: Indicates whether the request was successful.
        data:
          type: array
          description: List of token allowances.
          items:
            $ref: '#/components/schemas/TokenAllowance'
    TokenMetadata:
      type: object
      description: Metadata for a fungible token including identifiers and contract details.
      properties:
        name:
          type: string
          description: The display name of the token.
        symbol:
          type: string
          description: The ticker symbol of the token.
        decimals:
          type: integer
          description: The number of decimal places the token uses.
        contractAddress:
          type: string
          description: The smart contract address of the token.
        chain:
          type: string
          description: The blockchain network the token exists on.
        logo:
          type: string
          format: uri
          description: URL to the token logo image.
        totalSupply:
          type: string
          description: The total supply of the token in its smallest unit.
  parameters:
    limitParam:
      name: limit
      in: query
      description: Maximum number of results to return per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
    chainParam:
      name: chain
      in: query
      required: true
      description: The blockchain network identifier (e.g., ethereum, polygon, solana, bsc, arbitrum, optimism, avalanche, base).
      schema:
        type: string
        examples:
        - ethereum
        - polygon
        - solana
    cursorParam:
      name: cursor
      in: query
      description: Pagination cursor for retrieving the next page of results.
      schema:
        type: string
    walletAddressParam:
      name: address
      in: query
      required: true
      description: The wallet address to query data for.
      schema:
        type: string
    contractAddressParam:
      name: contractAddress
      in: query
      required: true
      description: The smart contract address of the token.
      schema:
        type: string
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: Uniblock project API key passed as a header. Obtain your API key by creating a project on the Uniblock dashboard at app.uniblock.dev.
externalDocs:
  description: Uniblock Unified API Documentation
  url: https://docs.uniblock.dev/docs/unified-api-overview