> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asksurf.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallet Detail



## OpenAPI

````yaml openapi.json GET /gateway/v1/wallet/detail
openapi: 3.1.0
info:
  title: Hermod
  version: 0.0.1
servers:
  - url: https://api.asksurf.ai
security: []
paths:
  /gateway/v1/wallet/detail:
    get:
      tags:
        - Wallet
      summary: Aggregated Wallet Detail
      description: >-
        Returns multiple wallet sub-resources in a single request.


        **Available fields** (via `fields`): `balance`, `tokens`, `labels`,
        `nft`.


        **Lookup:** by `address`. Partial failures return available fields with
        per-field error info. Returns 422 if `fields` is invalid.
      operationId: wallet-detail
      parameters:
        - description: Wallet address (0x hex for EVM, base58 for Solana)
          explode: false
          in: query
          name: address
          required: true
          schema:
            description: Wallet address (0x hex for EVM, base58 for Solana)
            examples:
              - '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
            type: string
        - description: >-
            Chain filter for `tokens`, `nft`, and `approvals`. When omitted,
            inferred from address format: 0x addresses query all EVM chains,
            base58 addresses query Solana.
          explode: false
          in: query
          name: chain
          schema:
            description: >-
              Chain filter for `tokens`, `nft`, and `approvals`. When omitted,
              inferred from address format: 0x addresses query all EVM chains,
              base58 addresses query Solana.
            enum:
              - ethereum
              - polygon
              - bsc
              - avalanche
              - arbitrum
              - optimism
              - fantom
              - base
              - solana
            examples:
              - ethereum
            type: string
        - description: >-
            Comma-separated sub-resources to include. Valid: `balance`,
            `tokens`, `labels`, `nft`, `approvals`. The `active_chains` field is
            always returned. `approvals` is opt-in (not in default) as it
            triggers additional upstream calls.
          explode: false
          in: query
          name: fields
          schema:
            default: balance,tokens,labels,nft
            description: >-
              Comma-separated sub-resources to include. Valid: `balance`,
              `tokens`, `labels`, `nft`, `approvals`. The `active_chains` field
              is always returned. `approvals` is opt-in (not in default) as it
              triggers additional upstream calls.
            examples:
              - balance,labels,approvals
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataObjectResponseWalletDetailBody'
          description: OK
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAPIError'
          description: Error
      security:
        - AccessToken: []
components:
  schemas:
    DataObjectResponseWalletDetailBody:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
            - >-
              https://example.com/schemas/DataObjectResponseWalletDetailBody.json
          format: uri
          readOnly: true
          type: string
        data:
          $ref: '#/components/schemas/WalletDetailBody'
        meta:
          $ref: '#/components/schemas/ObjectResponseMeta'
      required:
        - data
        - meta
      type: object
    DataAPIError:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
            - https://example.com/schemas/DataAPIError.json
          format: uri
          readOnly: true
          type: string
        error:
          $ref: '#/components/schemas/DataAPIErrorDetail'
      required:
        - error
      type: object
    WalletDetailBody:
      additionalProperties: false
      properties:
        active_chains:
          description: >-
            Chains the wallet has non-zero balances on. Always present (not
            controlled by fields param). For Solana addresses, returns a single
            entry.
          items:
            $ref: '#/components/schemas/WalletChainItem'
          type:
            - array
            - 'null'
        approvals:
          description: >-
            Token approvals (EVM-only, up to 50). Only present when `approvals`
            is included in the `fields` param.
          items:
            $ref: '#/components/schemas/WalletApprovalItem'
          type:
            - array
            - 'null'
        errors:
          description: Per-field errors for any fields that failed to load
          items:
            $ref: '#/components/schemas/WalletDetailError'
          type:
            - array
            - 'null'
        evm_balance:
          $ref: '#/components/schemas/EvmBalanceItem'
          description: EVM wallet balance. Populated for EVM chains only.
        evm_tokens:
          description: EVM token holdings (up to 50). Populated for EVM chains only.
          items:
            $ref: '#/components/schemas/EvmTokenItem'
          type:
            - array
            - 'null'
        labels:
          $ref: '#/components/schemas/WalletLabelItem'
          description: Address labels and entity attribution
        nft:
          description: NFT holdings (EVM-only, top 200 by value)
          items:
            $ref: '#/components/schemas/WalletNFTItem'
          type:
            - array
            - 'null'
        sol_balance:
          $ref: '#/components/schemas/SolBalanceItem'
          description: Solana wallet balance from Solscan. Populated for Solana chain only.
        sol_tokens:
          description: >-
            Solana SPL token holdings from Solscan (up to 50). Populated for
            Solana chain only.
          items:
            $ref: '#/components/schemas/SolTokenItem'
          type:
            - array
            - 'null'
      type: object
    ObjectResponseMeta:
      additionalProperties: false
      properties:
        cached:
          description: Whether this response was served from cache
          type: boolean
        credits_used:
          description: Credits deducted for this request
          format: int64
          type: integer
      required:
        - credits_used
        - cached
      type: object
    DataAPIErrorDetail:
      additionalProperties: false
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message
      type: object
    WalletChainItem:
      additionalProperties: false
      properties:
        chain:
          description: Canonical chain name like `ethereum` or `polygon`
          type: string
        chain_id:
          description: EVM chain ID like `1` for Ethereum or `137` for Polygon
          format: int64
          type: integer
        usd_value:
          description: Total USD value of assets on this chain
          format: double
          type: number
      required:
        - chain
        - usd_value
      type: object
    WalletApprovalItem:
      additionalProperties: false
      properties:
        balance:
          description: Current token balance
          format: double
          type: number
        chain:
          description: Canonical chain name
          type: string
        name:
          description: Full token name
          type: string
        spenders:
          description: List of approved spender contracts
          items:
            $ref: '#/components/schemas/WalletApprovalSpender'
          type:
            - array
            - 'null'
        symbol:
          description: Token ticker symbol
          type: string
        token_address:
          description: Token contract address
          type: string
      required:
        - token_address
        - symbol
        - chain
        - balance
        - spenders
      type: object
    WalletDetailError:
      additionalProperties: false
      properties:
        field:
          description: >-
            Field name that failed to load like `evm_balance`, `sol_balance`,
            `evm_tokens`, `sol_tokens`, `labels`, `nft`, `active_chains`, or
            `approvals`
          type: string
        message:
          description: Error message describing why the field could not be loaded
          type: string
      required:
        - field
        - message
      type: object
    EvmBalanceItem:
      additionalProperties: false
      properties:
        address:
          description: Wallet address
          type: string
        chain_balances:
          description: Per-chain balance breakdown, sorted by value descending (EVM only)
          items:
            $ref: '#/components/schemas/WalletChainItem'
          type:
            - array
            - 'null'
        total_usd:
          description: Total portfolio value in USD (EVM only)
          format: double
          type: number
      required:
        - address
        - total_usd
      type: object
    EvmTokenItem:
      additionalProperties: false
      properties:
        balance:
          description: Decimal-adjusted token balance as a string
          type: string
        chain:
          description: Chain name like ethereum, polygon (EVM only)
          type: string
        is_verified:
          description: Whether the token is verified (EVM only)
          type: boolean
        logo_url:
          description: Token logo image URL
          type: string
        name:
          description: Full token name
          type: string
        price:
          description: Current USD price per token (EVM only)
          format: double
          type: number
        symbol:
          description: Token ticker symbol
          type: string
        token_address:
          description: Token contract address (EVM only)
          type: string
        usd_value:
          description: Total USD value (balance * price) (EVM only)
          format: double
          type: number
      required:
        - token_address
        - symbol
        - balance
        - price
        - usd_value
        - is_verified
      type: object
    WalletLabelItem:
      additionalProperties: false
      properties:
        address:
          description: Wallet address
          type: string
        entity_name:
          description: Name of the associated entity like `Binance` or `Aave`
          type: string
        entity_type:
          description: Type of entity like `exchange`, `fund`, or `whale`
          type: string
        labels:
          description: List of labels assigned to this address
          items:
            $ref: '#/components/schemas/WalletLabelInfo'
          type:
            - array
            - 'null'
      required:
        - address
        - labels
      type: object
    WalletNFTItem:
      additionalProperties: false
      properties:
        chain:
          description: Canonical chain name like `ethereum` or `polygon`
          type: string
        collection_name:
          description: NFT collection name
          type: string
        contract_address:
          description: NFT contract address
          type: string
        image_url:
          description: NFT image or thumbnail URL
          type: string
        name:
          description: NFT item name or title
          type: string
        token_id:
          description: NFT token ID within the collection
          type: string
        usd_price:
          description: Latest trading price in USD
          format: double
          type: number
      required:
        - contract_address
        - token_id
      type: object
    SolBalanceItem:
      additionalProperties: false
      properties:
        address:
          description: Wallet address
          type: string
        sol_balance:
          description: Decimal-adjusted native SOL balance as a string (Solana only)
          type: string
      required:
        - address
        - sol_balance
      type: object
    SolTokenItem:
      additionalProperties: false
      properties:
        balance:
          description: Decimal-adjusted token balance as a string
          type: string
        decimals:
          description: Token decimal places (Solana only)
          format: int64
          type: integer
        name:
          description: Full token name
          type: string
        symbol:
          description: Token ticker symbol
          type: string
        token_address:
          description: SPL token mint address (Solana only)
          type: string
      required:
        - token_address
        - symbol
        - balance
        - decimals
      type: object
    WalletApprovalSpender:
      additionalProperties: false
      properties:
        allowance:
          description: Approved token amount (use -1 for unlimited)
          format: double
          type: number
        spender_address:
          description: Address of the approved spender contract
          type: string
        spender_name:
          description: >-
            Human-readable name of the spender, absent for unrecognized
            contracts
          type: string
      required:
        - spender_address
        - allowance
      type: object
    WalletLabelInfo:
      additionalProperties: false
      properties:
        confidence:
          description: Confidence score 0.0-1.0
          format: double
          type: number
        label:
          description: Human-readable label for this address like `Binance Hot Wallet`
          type: string
      required:
        - label
      type: object

````