openapi: 3.1.0
info:
  title: Uniblock Direct Direct Pass-Through Tokens API
  description: The Uniblock Direct API gives developers pass-through access to provider-specific endpoints exactly as offered by upstream blockchain data providers. Requests follow the pattern of specifying the provider and optional prefix in the URL path, while still benefiting from Uniblock's routing, retry, and failover infrastructure. Results are returned exactly as they would be if the first-party provider endpoint was called directly. This is intended for use cases where a specific method is not yet abstracted into the Unified API.
  version: '1.0'
  contact:
    name: Uniblock Support
    url: https://docs.uniblock.dev
  termsOfService: https://uniblock.dev/terms
servers:
- url: https://api.uniblock.dev/direct/v1
  description: Uniblock Direct API 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:
    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.
    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.
    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.
    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.
    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'
    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'
    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.
    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.
    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.
  parameters:
    walletAddressParam:
      name: address
      in: query
      required: true
      description: The wallet address to query data for.
      schema:
        type: string
    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
    limitParam:
      name: limit
      in: query
      description: Maximum number of results to return per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
    cursorParam:
      name: cursor
      in: query
      description: Pagination cursor for retrieving the next page of results.
      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. If no provider-specific authentication is passed in the request, Uniblock will use the credentials stored in the project associated with this API key.
externalDocs:
  description: Uniblock Direct API Documentation
  url: https://docs.uniblock.dev/docs/direct-api-overview