addresses

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

Search and filter addresses with pagination.

Schema Definition

addresses(
  first: Int = 10
  after: Cursor
  where: AddressFilter
  orderBy: AddressOrderBy
  orderDirection: OrderDirection
): AddressList!

Arguments

Argument	Type	Description
first	Int scalar	Maximum number of results to return (default: 10, max: 100).
after	Cursor scalar	Cursor for pagination. Pass the endCursor from a previous query to get the next page.
where	AddressFilter input	Filter criteria for addresses.
orderBy	AddressOrderBy enum	Field to sort results by.
orderDirection	OrderDirection enum	Sort direction (ascending or descending).

Return Type

Type	Description
AddressList! object	Paginated list of addresses.

Common Use Cases

• Build address explorer pages by listing and paginating through on-chain addresses with sorting and filtering.
• Identify highly active wallets by ordering with orderBy: TRANSACTION_COUNT or orderBy: NONCE to surface power users.
• Monitor recently active addresses by filtering with lastActiveAt: { gte: "..." } for real-time activity dashboards.
• Find dormant wallets by filtering with lastActiveAt: { lte: "..." } for analytics on inactive addresses.
• Look up a specific address within a filtered result set using the address filter on AddressFilter.
• Filter addresses by transaction activity using nonce: { gte, lte } ranges to segment wallets by engagement level.

Example

Query

Find Most Active Addresses Recently

query ActiveAddresses(
  $where: AddressFilter
  $first: Int
  $orderBy: AddressOrderBy
  $orderDirection: OrderDirection
) {
  addresses(
    where: $where
    first: $first
    orderBy: $orderBy
    orderDirection: $orderDirection
  ) {
    totalCount
    pageInfo {
      hasNextPage
      endCursor
    }
    entries {
      address
      nonce
      lastActiveAt
      transactionCount
    }
  }
}

Variables

{
  "where": {
    "lastActiveAt": { "gte": "2025-06-01T00:00:00Z" },
    "nonce": { "gte": 100 }
  },
  "first": 20,
  "orderBy": "TRANSACTION_COUNT",
  "orderDirection": "DESC"
}

Response

{
  "data": {
    "addresses": {
      "totalCount": 5842,
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "eyJpZCI6MjB9"
      },
      "entries": [
        {
          "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
          "nonce": 1247,
          "lastActiveAt": "2025-06-10T14:22:08Z",
          "transactionCount": 1893
        },
        {
          "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb2",
          "nonce": 983,
          "lastActiveAt": "2025-06-09T21:15:44Z",
          "transactionCount": 1456
        },
        {
          "address": "0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984",
          "nonce": 714,
          "lastActiveAt": "2025-06-10T09:03:17Z",
          "transactionCount": 1102
        }
      ]
    }
  }
}

Implementation Notes

note

• The addresses query returns both EOAs and contract addresses. Use the contracts query if you need to filter specifically by contract type or token standard.
• The default first value is 10. OneSource enforces a maximum first value of 100. Adjust based on your needs.
• Use cursor-based pagination with after and pageInfo.endCursor to page through results. Check pageInfo.hasNextPage to determine if more pages exist.
• Range filters use structured input objects with gte (greater than or equal) and lte (less than or equal) fields — e.g., nonce: { gte: 100 }, lastActiveAt: { gte: "2025-01-01T00:00:00Z" }.
• Use orderBy and orderDirection to ensure consistent ordering when paginating through large result sets.
• Available orderBy values are ADDRESS, NONCE, LAST_ACTIVE, and TRANSACTION_COUNT.
• The entries in the result implement the Address interface. Use inline fragments (... on EOA, ... on Token, ... on NFTContract) to access type-specific fields.
• To look up a single address directly, use the address query instead.