Uniblock Unified API

openapi: 3.1.0
info:
  title: Uniblock Unified API
  description: >-
    The Uniblock Unified API provides a single standardized interface for
    interacting with multiple blockchain networks and data providers. It offers
    higher-level endpoints for common data needs including token metadata and
    balances, NFT collections and assets, transaction lookups, scan data, and
    market data for pricing and analytics. The API abstracts away the
    differences between upstream providers like Alchemy, Moralis, and Covalent,
    automatically routing requests to the best provider based on reliability,
    cost, and performance across 300+ blockchains and 55+ providers.
  version: '1.0'
  contact:
    name: Uniblock Support
    url: https://docs.uniblock.dev
  termsOfService: https://uniblock.dev/terms
externalDocs:
  description: Uniblock Unified API Documentation
  url: https://docs.uniblock.dev/docs/unified-api-overview
servers:
  - url: https://api.uniblock.dev/uni/v1
    description: Uniblock Production Server
tags:
  - name: Market Data
    description: >-
      Endpoints for real-time and historical market data including token
      prices, market capitalization, trading volume, trending tokens, and
      charting data from multiple exchanges.
  - name: NFTs
    description: >-
      Endpoints for retrieving non-fungible token data including balances,
      metadata, transfers, and collection information.
  - name: Scan
    description: >-
      Endpoints for scanning blockchain networks for transactions, transfers,
      native supply, and block-level data similar to block explorers.
  - name: Tokens
    description: >-
      Endpoints for retrieving fungible token data including metadata, balances,
      prices, transfers, and allowances across multiple blockchain networks.
  - name: Transactions
    description: >-
      Endpoints for looking up transaction data by address or transaction hash,
      including detailed transaction information.
security:
  - apiKeyHeader: []
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'
  /nft/balance:
    get:
      operationId: getNftBalance
      summary: Get NFT Balances
      description: >-
        Retrieves the NFT balances held by a specific wallet address, returning
        a list of NFTs owned including collection and token identifiers.
      tags:
        - NFTs
      parameters:
        - $ref: '#/components/parameters/chainParam'
        - $ref: '#/components/parameters/walletAddressParam'
        - $ref: '#/components/parameters/limitParam'
        - $ref: '#/components/parameters/cursorParam'
      responses:
        '200':
          description: Successful response with NFT balances
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NftBalanceResponse'
        '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'
  /nft/metadata:
    get:
      operationId: getNftMetadata
      summary: Get NFT Metadata
      description: >-
        Retrieves detailed metadata for a specific NFT including name,
        description, image URL, attributes, and trait information.
      tags:
        - NFTs
      parameters:
        - $ref: '#/components/parameters/chainParam'
        - $ref: '#/components/parameters/contractAddressParam'
        - name: tokenId
          in: query
          required: true
          description: >-
            The token ID of the specific NFT within the collection.
          schema:
            type: string
      responses:
        '200':
          description: Successful response with NFT metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NftMetadataResponse'
        '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: NFT not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /nft/collection-metadata:
    get:
      operationId: getNftCollectionMetadata
      summary: Get NFT Collection Metadata
      description: >-
        Retrieves metadata about an NFT collection including name, description,
        total supply, floor price, and other collection-level attributes.
      tags:
        - NFTs
      parameters:
        - $ref: '#/components/parameters/chainParam'
        - $ref: '#/components/parameters/contractAddressParam'
      responses:
        '200':
          description: Successful response with collection metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NftCollectionMetadataResponse'
        '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'
  /nft/transfers:
    get:
      operationId: getNftTransfers
      summary: Get NFT Transfers
      description: >-
        Retrieves a list of NFT transfer events for a specific wallet address
        or contract, including mints, sales, and transfers between addresses.
      tags:
        - NFTs
      parameters:
        - $ref: '#/components/parameters/chainParam'
        - $ref: '#/components/parameters/walletAddressParam'
        - $ref: '#/components/parameters/limitParam'
        - $ref: '#/components/parameters/cursorParam'
      responses:
        '200':
          description: Successful response with NFT transfers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NftTransfersResponse'
        '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'
  /transactions:
    get:
      operationId: getTransactions
      summary: Get Transactions
      description: >-
        Retrieves a list of transactions associated with a specific wallet
        address, including both incoming and outgoing transactions across the
        specified blockchain network.
      tags:
        - Transactions
      parameters:
        - $ref: '#/components/parameters/chainParam'
        - $ref: '#/components/parameters/walletAddressParam'
        - $ref: '#/components/parameters/limitParam'
        - $ref: '#/components/parameters/cursorParam'
      responses:
        '200':
          description: Successful response with transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionsResponse'
        '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'
  /transactions/{transactionHash}:
    get:
      operationId: getTransactionByHash
      summary: Get Transaction by Hash
      description: >-
        Retrieves detailed information about a specific transaction by its
        transaction hash, including status, gas used, block number, and
        input data.
      tags:
        - Transactions
      parameters:
        - $ref: '#/components/parameters/chainParam'
        - name: transactionHash
          in: path
          required: true
          description: >-
            The hash of the transaction to retrieve.
          schema:
            type: string
            pattern: '^0x[a-fA-F0-9]{64}$'
      responses:
        '200':
          description: Successful response with transaction details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionDetailResponse'
        '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: Transaction not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /scan/transactions:
    get:
      operationId: getScanTransactions
      summary: Get Scanned Transactions
      description: >-
        Retrieves transactions for a specific address using blockchain
        explorer-style scanning, useful for auditing transaction histories
        and monitoring network activity.
      tags:
        - Scan
      parameters:
        - $ref: '#/components/parameters/chainParam'
        - $ref: '#/components/parameters/walletAddressParam'
        - $ref: '#/components/parameters/limitParam'
        - $ref: '#/components/parameters/cursorParam'
      responses:
        '200':
          description: Successful response with scanned transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanTransactionsResponse'
        '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'
  /scan/transfers:
    get:
      operationId: getScanTransfers
      summary: Get Scanned Transfers
      description: >-
        Retrieves token transfer events for a specific address using
        blockchain explorer-style scanning, including ERC-20 and ERC-721
        transfers.
      tags:
        - Scan
      parameters:
        - $ref: '#/components/parameters/chainParam'
        - $ref: '#/components/parameters/walletAddressParam'
        - $ref: '#/components/parameters/limitParam'
        - $ref: '#/components/parameters/cursorParam'
      responses:
        '200':
          description: Successful response with scanned transfers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanTransfersResponse'
        '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'
  /scan/native-supply:
    get:
      operationId: getScanNativeSupply
      summary: Get Native Token Supply
      description: >-
        Returns the current amount of the native token in circulation for the
        specified blockchain network, similar to block explorer supply queries.
      tags:
        - Scan
      parameters:
        - $ref: '#/components/parameters/chainParam'
      responses:
        '200':
          description: Successful response with native token supply
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NativeSupplyResponse'
        '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'
  /market-data/price:
    get:
      operationId: getMarketDataPrice
      summary: Get Market Data Price
      description: >-
        Retrieves the current price of a token from aggregated market data
        sources, providing real-time pricing from multiple exchanges.
      tags:
        - Market Data
      parameters:
        - $ref: '#/components/parameters/chainParam'
        - $ref: '#/components/parameters/contractAddressParam'
      responses:
        '200':
          description: Successful response with market price
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketDataPriceResponse'
        '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'
  /market-data/market-cap:
    get:
      operationId: getMarketDataMarketCap
      summary: Get Market Capitalization
      description: >-
        Retrieves the current market capitalization for a specific token,
        calculated from circulating supply and current price data.
      tags:
        - Market Data
      parameters:
        - $ref: '#/components/parameters/chainParam'
        - $ref: '#/components/parameters/contractAddressParam'
      responses:
        '200':
          description: Successful response with market cap
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketDataMarketCapResponse'
        '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'
  /market-data/volume:
    get:
      operationId: getMarketDataVolume
      summary: Get Trading Volume
      description: >-
        Retrieves the 24-hour trading volume for a specific token across
        aggregated exchange data sources.
      tags:
        - Market Data
      parameters:
        - $ref: '#/components/parameters/chainParam'
        - $ref: '#/components/parameters/contractAddressParam'
      responses:
        '200':
          description: Successful response with trading volume
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketDataVolumeResponse'
        '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'
  /market-data/trending:
    get:
      operationId: getMarketDataTrending
      summary: Get Trending Tokens
      description: >-
        Retrieves a list of currently trending tokens based on trading
        activity, volume, and market interest across aggregated data sources.
      tags:
        - Market Data
      parameters:
        - $ref: '#/components/parameters/chainParam'
        - $ref: '#/components/parameters/limitParam'
      responses:
        '200':
          description: Successful response with trending tokens
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketDataTrendingResponse'
        '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'
  /market-data/chart:
    get:
      operationId: getMarketDataChart
      summary: Get Charting Data
      description: >-
        Retrieves price, volume, and market cap data for a token at a given
        date range and predefined granularity, suitable for rendering charts
        and performing time-series analysis.
      tags:
        - Market Data
      parameters:
        - $ref: '#/components/parameters/chainParam'
        - $ref: '#/components/parameters/contractAddressParam'
        - name: from
          in: query
          description: >-
            Start date for the charting period in ISO 8601 format.
          schema:
            type: string
            format: date
        - name: to
          in: query
          description: >-
            End date for the charting period in ISO 8601 format.
          schema:
            type: string
            format: date
        - name: granularity
          in: query
          description: >-
            Time interval granularity for data points.
          schema:
            type: string
            enum:
              - 1h
              - 4h
              - 1d
              - 1w
      responses:
        '200':
          description: Successful response with charting data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketDataChartResponse'
        '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'
  /market-data/history:
    get:
      operationId: getMarketDataHistory
      summary: Get Historical Market Data
      description: >-
        Retrieves historical price, volume, and market cap of a token at a
        specific date, enabling point-in-time market analysis.
      tags:
        - Market Data
      parameters:
        - $ref: '#/components/parameters/chainParam'
        - $ref: '#/components/parameters/contractAddressParam'
        - name: date
          in: query
          description: >-
            The specific date for historical data retrieval in ISO 8601 format.
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Successful response with historical market data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketDataHistoryResponse'
        '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:
  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.
  parameters:
    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
    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
    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
  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.
    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'
    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.
    TokenBalanceResponse:
      type: object
      description: >-
        Response containing token balances for a wallet address.
      properties:
        success:

# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/uniblock/refs/heads/main/openapi/uniblock-unified-api-openapi.yml