Skip to main content

Troubleshooting

This guide helps you resolve common issues when working with the OneSource Web3 API.

Authentication Errors​

Invalid API token or Status Code 401​

If you receive this error:

  1. Check API key format to ensure your key starts with BP- followed by 26 characters (i.e., BP-12345678912345678912345678).

  2. Verify header implementation:

    // Correct implementation
    headers: {
      "Content-Type": "application/json",
      "x-bp-token": "BP-12345678912345678912345678"  // Note the exact case of "x-bp-token"
    }

  3. Confirm your subscription status by logging in to your OneSource Dashboard to verify your API key is active and hasn't expired.

  4. Test your API key with a playground to determine if the issue is with your query or the API itself.

Query Error​

Cannot query field X on type Y​

This error occurs when your query references fields that don't exist in our schema. To resolve:

  1. Check field spelling to ensure field names match exactly what's in our schema.
  2. Review schema changes in the GraphQL Schema.
  3. Use Apollo Sandbox to help build valid queries.

Rate Limiting​

Rate limit exceeded​

If you hit rate limits:

  1. Implement caching - if you're making the same requests over and over, caching the results can cut down on requests.
  2. Optimize queries - only ask for the data you actually need with smaller, focused queries.
  3. Upgrade your plan - if you consistently hit limits, you may need to move to a higher-tier plan that offers higher limits.

Frequently Asked Questions​

What chains does OneSource support?​

OneSource supports the following chains:

  • Ethereum Mainnet - ethereum
  • Base - base
  • Optimism - optimism
  • Avalanche C-Chain - avax
  • Sepolia Testnet - sepolia
  • Shape - shape

Use the chain identifier in your endpoint URL: https://api.onesource.io/federation/{chain}/graphql

How do I paginate through large result sets?​

Use the first and after parameters with cursor-based pagination:

query {
  tokens(first: 20, where: { ... }) {
    totalCount
    pageInfo {
      hasNextPage
      endCursor
    }
    entries {
      name
      symbol
    }
  }
}
  • first — Number of items to return per page (max 100)
  • after — Pass the endCursor from pageInfo to fetch the next page
  • Check pageInfo.hasNextPage to know if more results exist
  • totalCount gives the total number of matching results across all pages

To fetch the next page, pass the endCursor from the previous response:

query {
  tokens(first: 20, after: "eyJpZCI6MTAwfQ==", where: { ... }) {
    totalCount
    pageInfo {
      hasNextPage
      endCursor
    }
    entries {
      name
      symbol
    }
  }
}

Why is my query returning null?​

A null response typically means:

  • Token/contract doesn't exist — Verify the contract address and token ID are correct.
  • Wrong chain — The asset may exist on a different chain than you're querying.
  • Address format — Ensure addresses are checksummed hex strings (e.g., 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045).
  • Data not yet indexed — Recently minted tokens may take a few minutes to appear.

What's the difference between token and nft queries?​

  • token — Fetches a single ERC-20 fungible token by its contract address. Use when you want details about a specific fungible token (e.g., USDC, WETH).
  • nft — Fetches a single NFT by contract address and token ID. Use when you know exactly which NFT you want.
  • tokens — Fetches a filtered, paginated list of ERC-20 tokens. Use for browsing or searching fungible tokens.
  • nfts — Fetches a filtered, paginated list of NFTs across contracts. Use for browsing collections, searching, or displaying galleries.

Same pattern applies to other query pairs: contract/contracts, transaction/transactions, block/blocks, address/addresses.

How do I get NFT metadata and images?​

Use the nft query with nested metadata and media fields:

query {
  nft(contract: "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D", tokenId: "1") {
    name
    metadata {
      name
      description
      image
      attributes {
        traitType
        value
      }
    }
    media {
      fileType
      mediaType
      thumbnails(preset: MEDIUM) {
        url
        preset
        format
        fileSize
      }
    }
  }
}

Use thumbnail presets (MICRO, SMALL, MEDIUM, LARGE, XLARGE, ORIGINAL) for optimized image loading.

What's the difference between ERC-20, ERC-721, and ERC-1155?​

  • ERC-20 — Fungible tokens (e.g., USDC, WETH). Each token is identical and divisible.
  • ERC-721 — Non-fungible tokens (NFTs). Each token is unique with its own token ID.
  • ERC-1155 — Multi-token standard. Supports both fungible and non-fungible tokens in one contract.

Filter by standard using the standards field on ContractFilter:

query {
  contracts(where: { standards: [ERC721] }) {
    entries {
      address
      name
    }
  }
}

How do I filter queries?​

Use the where parameter with structured filter input objects:

query {
  nfts(where: {
    contract: { address: "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D" }
    nameLike: "Ape"
  }) {
    entries {
      tokenId
      name
    }
  }
}

Common filter patterns:

  • Range filters use nested objects with gte (greater than or equal) and lte (less than or equal) fields — e.g., holdersCount: { gte: 100 }, createdAt: { gte: "2025-01-01T00:00:00Z" }
  • Text search uses the Like suffix for case-insensitive partial matching — e.g., nameLike, symbolLike
  • Exact match uses the field directly — e.g., address: "0x...", symbol: "USDC"
  • See the Inputs documentation for all available filter inputs.

Still Need Help?​

If none of the above helps, contact support at support@onesource.io with:

  • The full request you're making.
  • Any error messages you're receiving.
  • The chain endpoint you're using.