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 24 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({
    query: `
      query GetToken($contract: String!, $tokenId: String!) {
        token(contract: $contract, tokenId: $tokenId) {
          tokenId
          contract
          metadata { name description image }
        }
      }
    `,
    variables: {
      contract: "0xbd3531da5cf5857e7cfaa92426877b022e612cf8",
      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(contract: \"0xbd3531da5cf5857e7cfaa92426877b022e612cf8\", tokenId: \"1\") { tokenId metadata { name } } }"}'

Query Patterns

Single Item Queries

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

query {
  token(contract: "0x...", tokenId: "1") {
    tokenId
    metadata { name }
  }
}

List Queries with Pagination

Queries like tokens, contracts, balances return paginated lists:

query {
  tokens(first: 20, after: "cursor_string", filter: { ... }) {
    items {
      tokenId
      contract
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Pagination parameters:

• first: Number of items to return (default varies, max 100)
• after: Cursor for next page (from pageInfo.endCursor)

Filtering

Use the filter parameter with type-specific filter objects:

query {
  tokens(filter: { contractAddress: "0x...", ownerAddress: "0x..." }) {
    items { tokenId }
  }
}

Ordering

Use orderBy and orderDirection parameters:

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

Common Queries by Use Case

Use Case	Query	Key Parameters
Get NFT details	token	contract, tokenId
List NFTs by owner	tokens	filter: { ownerAddress }
Get wallet balances	balances	filter: { ownerAddress }
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 - always handle hasNextPage
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: SMALL, MEDIUM, LARGE

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