OneSource Web3 API - AI Instructions

This page provides structured guidance for AI assistants and coding agents working with the OneSource Web3 API.

Quick Reference

Property	Value
API Type	GraphQL
Base URL	https://api.onesource.io/federation/{chain}/graphql
Auth Header	x-bp-token: BP-{YOUR_API_KEY}
Supported Chains	ethereum, base, optimism, avax, sepolia, shape

Authentication

All requests require an API key passed as an HTTP header:

x-bp-token: BP-{YOUR_API_KEY}

Key format: BP- prefix followed by 26 alphanumeric characters (e.g., BP-12345678912345678912345678)

Common auth errors:

• 401 Unauthorized = Missing or invalid API key
• Ensure header name is exactly x-bp-token (not Authorization: Bearer)

Making Requests

Endpoint Pattern

Replace {chain} with the target blockchain:

https://api.onesource.io/federation/ethereum/graphql
https://api.onesource.io/federation/base/graphql
https://api.onesource.io/federation/optimism/graphql
https://api.onesource.io/federation/avax/graphql
https://api.onesource.io/federation/sepolia/graphql
https://api.onesource.io/federation/shape/graphql

Example Request (JavaScript)

const response = await fetch('https://api.onesource.io/federation/ethereum/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-bp-token': 'BP-YOUR_API_KEY'
  },
  body: JSON.stringify({
    // ERC-20 token lookup
    query: `
      query GetToken($address: AddressString!) {
        token(address: $address) {
          name
          symbol
          decimals
          totalSupply { formatted }
        }
      }
    `,
    variables: {
      address: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
    }
  })
});

const data = await response.json();

NFT lookup example:

const response = await fetch('https://api.onesource.io/federation/ethereum/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-bp-token': 'BP-YOUR_API_KEY'
  },
  body: JSON.stringify({
    query: `
      query GetNFT($contract: AddressString!, $tokenId: TokenId!) {
        nft(contract: $contract, tokenId: $tokenId) {
          tokenId
          name
          metadata { name description }
          media { thumbnails(preset: MEDIUM) { url } }
        }
      }
    `,
    variables: {
      contract: "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d",
      tokenId: "1"
    }
  })
});

const data = await response.json();

Example Request (curl)

curl -X POST "https://api.onesource.io/federation/ethereum/graphql" \
  -H "Content-Type: application/json" \
  -H "x-bp-token: BP-YOUR_API_KEY" \
  -d '{"query": "{ token(address: \"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\") { name symbol decimals } }"}'

Query Patterns

Single Item Queries

Queries like token, nft, contract, block, transaction return a single object:

# ERC-20 token
query {
  token(address: "0x...") {
    name
    symbol
    decimals
  }
}

# NFT
query {
  nft(contract: "0x...", tokenId: "1") {
    tokenId
    name
    metadata { name description }
  }
}

List Queries with Pagination

Queries like tokens, contracts, balances return paginated lists:

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

Pagination parameters:

• first: Number of items to return (default 10, max 100)
• after: Cursor for the next page (use pageInfo.endCursor from previous response)

Filtering

Use the where parameter with type-specific filter objects:

query {
  tokens(where: { contract: { address: "0x..." } }) {
    entries { tokenId }
  }
}

Ordering

Use orderBy and orderDirection parameters:

query {
  blocks(orderBy: NUMBER, orderDirection: DESC, first: 10) {
    entries { number timestamp }
  }
}

Common Queries by Use Case

Use Case	Query	Key Parameters
Get ERC-20 token	token	address
Get NFT details	nft	contract, tokenId
List NFTs by contract	tokens	where: { contract: { address: "0x..." } }
Get wallet balances	balances	where: { account: "0x..." }
Get contract info	contract	address
Get transaction	transaction	hash
List recent blocks	blocks	orderBy: NUMBER, orderDirection: DESC

Error Handling

Status	Meaning	Solution
401	Invalid/missing API key	Check x-bp-token header format
429	Rate limit exceeded	Reduce request frequency
400	Invalid GraphQL query	Check query syntax and field names

GraphQL errors appear in the response body:

{
  "errors": [
    {
      "message": "Cannot query field 'foo' on type 'Token'",
      "path": ["token", "foo"]
    }
  ]
}

Important Notes for AI Assistants

1. Always use lowercase for Ethereum addresses (e.g., 0xabcd... not 0xABCD...)
2. Contract addresses are strings, not checksummed
3. TokenIds are strings, even if numeric (e.g., "123" not 123)
4. Pagination is required for large result sets - check pageInfo.hasNextPage to detect the last page and use pageInfo.endCursor as the after value for the next request
5. Chain selection matters - ensure you're querying the correct chain endpoint
6. Timestamps are ISO 8601 format (e.g., "2024-01-15T12:00:00Z")

Available Query Types

Data Queries:

• token / tokens - NFT and token data
• contract / contracts - Smart contract information
• balance / balances - Wallet token holdings
• transaction / transactions - Transaction history
• block / blocks - Block data
• metadata / metadataList - NFT metadata
• media / mediaList - NFT media files

Aggregate Queries:

• holdersCount - Number of token holders
• blockCount - Number of blocks matching filter
• transactionCount - Number of transactions matching filter

GraphQL Schema Types

Scalars: String, Int, Boolean, JSON, Time, UInt64, UInt256

Key Enums:

• AssetType: ERC20, ERC721, ERC1155
• Ordering: ASC, DESC
• ThumbnailPreset: MICRO, SMALL, MEDIUM, LARGE, XLARGE, ORIGINAL

Filter Inputs: TokenFilter, BalanceFilter, ContractFilter, TransactionFilter, BlockFilter, MediaFilter, MetadataFilter