address

API Context

Endpoint: https://api.onesource.io/federation/{chain}/graphql Auth Header: x-bp-token: BP-{YOUR_API_KEY} Method: POST | Content-Type: application/json

Look up any address (EOA or contract) by its address string. Returns null if the address has never been seen on-chain.

Schema Definition

address(
  address: AddressString!
): Address

Arguments

Argument	Type	Description
address	AddressString! non-null scalar	The address to look up (0x-prefixed, 42 characters).

Return Type

Type	Description
Address interface	Base interface for any address on chain, whether an externally owned account (EOA) or a smart contract. Provides common fields for address identification, activity tracking, and asset balances.

Common Use Cases

• Build wallet profile pages by looking up any address to display its activity, balances, and transaction history.
• Determine whether an address is an EOA or a smart contract to customize UI rendering and available actions.
• Display a wallet's ERC-20 portfolio by traversing the tokenBalances field on the returned Address.
• Show NFT holdings for a specific address using the nftBalances field for gallery or portfolio views.
• Retrieve recent transactions for an address via the transactions field to build activity feeds.
• Check address activity status using lastActiveAt and nonce for wallet health or risk assessment tools.

Example

Query

Look Up a Wallet Address with Balances and Recent Activity

query WalletProfile($address: AddressString!) {
  address(address: $address) {
    address
    nonce
    lastActiveAt
    transactionCount
    tokenBalances(first: 5, orderDirection: DESC) {
      totalCount
      entries {
        token {
          name
          symbol
          decimals
        }
        balance {
          formatted
        }
      }
    }
    nftBalances(first: 5) {
      totalCount
      entries {
        contract {
          name
          symbol
        }
        nftCount
      }
    }
    transactions(first: 3, orderBy: TIMESTAMP, orderDirection: DESC) {
      entries {
        hash
        blockNumber
        timestamp
        from {
          address
        }
        to {
          address
        }
        value {
          formatted
        }
        status
      }
    }
  }
}

Variables

{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
}

Response

{
  "data": {
    "address": {
      "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
      "nonce": 1247,
      "lastActiveAt": "2025-06-10T14:22:08Z",
      "transactionCount": 1893,
      "tokenBalances": {
        "totalCount": 42,
        "entries": [
          {
            "token": {
              "name": "USD Coin",
              "symbol": "USDC",
              "decimals": 6
            },
            "balance": {
              "formatted": "15000.000000"
            }
          },
          {
            "token": {
              "name": "Wrapped Ether",
              "symbol": "WETH",
              "decimals": 18
            },
            "balance": {
              "formatted": "12.450000000000000000"
            }
          }
        ]
      },
      "nftBalances": {
        "totalCount": 8,
        "entries": [
          {
            "contract": {
              "name": "Art Blocks",
              "symbol": "BLOCKS"
            },
            "nftCount": 3
          },
          {
            "contract": {
              "name": "Nouns",
              "symbol": "NOUN"
            },
            "nftCount": 1
          }
        ]
      },
      "transactions": {
        "entries": [
          {
            "hash": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890",
            "blockNumber": 19876543,
            "timestamp": "2025-06-10T14:22:08Z",
            "from": {
              "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
            },
            "to": {
              "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
            },
            "value": {
              "formatted": "0.000000000000000000"
            },
            "status": "SUCCESS"
          }
        ]
      }
    }
  }
}

Implementation Notes

note

• The address query returns null if the address has never been seen on-chain. Always handle the null case in your application.
• The return type is the Address interface, which is implemented by EOA and contract types (Token, NFTContract, Contract). Use GraphQL inline fragments (... on EOA, ... on Token) to access type-specific fields.
• The tokenBalances, nftBalances, and transactions fields are paginated sub-queries with their own first, after, where, orderBy, and orderDirection parameters.
• To look up only smart contracts, use the contract query instead, which returns the appropriate contract type directly.
• To search and filter across multiple addresses, use the addresses query with pagination and filtering support.
• The nonce field reflects the number of transactions sent from the address. For EOAs, this is the standard account nonce.
• The transactionCount field includes all transactions involving the address (both sent and received).