Cortex API Usage Guide for LLMs

Overview

The Cortex API is a blockchain data API that provides comprehensive token information, wallet data, and market analytics across multiple blockchain networks. The API uses a pay-per-request model with USDC payments processed on the Base network.

Base URL

API Base URL: https://api.cortex402.xyz

Authentication & Payment

Payment Method: USDC on Base network (Chain ID: 8453)
Price: $0.0004 USDC per request
Protocol: x402 (HTTP 402 Payment Required)
Payment Processing: Automatic via x402 client libraries
Required: Crypto wallet with USDC and x402 client library

Prerequisites

Before using the API, you need:

Crypto Wallet: Any EVM-compatible wallet with USDC
x402 Client Library: Install one of the following:
- Node.js: npm install x402-fetch or npm install x402-axios
- Python: pip install x402
- MCP: npm install x402-mcp (for AI agents)
Private Key: Your wallet's private key for signing transactions

How x402 Works

The x402 protocol automatically handles payments by:

Making an initial request to the API
Receiving a 402 Payment Required response with payment details
Creating and signing a payment transaction
Retrying the request with payment headers
Receiving the actual API response

This process is completely transparent when using the x402 client libraries.

Supported Networks

The API supports 100+ blockchain networks. Here are the most commonly used ones:

Major Networks

Ethereum: Network ID 1 (networkShortName: eth)
Solana: Network ID 1399811149 (networkShortName: sol)
Tron: Network ID 728126428 (networkShortName: tron)
BNB Chain: Network ID 56 (networkShortName: bsc)
Polygon: Network ID 137 (networkShortName: matic)
Arbitrum: Network ID 42161 (networkShortName: arb)
Optimism: Network ID 10 (networkShortName: opti)
Base: Network ID 8453 (networkShortName: base)
Avalanche: Network ID 43114 (networkShortName: avax)
Fantom: Network ID 250 (networkShortName: ftm)
Cronos: Network ID 25 (networkShortName: cro)
Aurora: Network ID 1313161554 (networkShortName: aur)

Layer 2 & Scaling Solutions

zkSync: Network ID 324 (networkShortName: zksync)
Scroll: Network ID 534352 (networkShortName: scroll)
Polygon zkEVM: Network ID 1101 (networkShortName: polygonzkevm)
Linea: Network ID 59144 (networkShortName: linea)
Mode: Network ID 34443 (networkShortName: mode)
Blast: Network ID 81457 (networkShortName: blast)

Testnets

Ethereum Sepolia: Network ID 11155111 (networkShortName: sepolia)
Base Sepolia: Network ID 84532 (networkShortName: base-sepolia)
Polygon Mumbai: Network ID 80001 (networkShortName: mumbai)
Goerli: Network ID 5 (networkShortName: goerli)

Other Notable Networks

Sui: Network ID 101 (networkShortName: sui)
Aptos: Network ID 49705 (networkShortName: aptos)
Starknet: Network ID 57420037 (networkShortName: starknet)
Celo: Network ID 42220 (networkShortName: celo)
Harmony: Network ID 1666600000 (networkShortName: one)
Moonbeam: Network ID 1284 (networkShortName: glmr)
Moonriver: Network ID 1285 (networkShortName: movr)
Klaytn: Network ID 8217 (networkShortName: klay)
Mantle: Network ID 5000 (networkShortName: mantle)
Zora: Network ID 7777777 (networkShortName: zora)
Degen Chain: Network ID 666666666 (networkShortName: degen)

Note: Use the /networks endpoint to get the complete list of all 100+ supported networks with their IDs and short names.

API Endpoints

1. Token Information

Get detailed token information including metadata, social links, and market data

GET /token/{address}/{networkId}

Parameters:

address (string, required): Token contract address
networkId (integer, required): Network ID (1, 56, 137, etc.)

Example:

curl -X GET "https://api.cortex402.xyz/token/0xA0b86a33E6441b8C4C8C0E4b8b8C4C8C0E4b8b8C4/1"

Response includes:

Basic info: address, symbol, name, decimals, totalSupply
Network info: networkId, networkName
Metadata: logoUrl, description, website, social links
Market data: marketCap, volume24h, priceChange24h
Timestamps: lastUpdated

2. Token Price

Get current price information for a specific token

GET /token/{address}/{networkId}/price

Parameters:

address (string, required): Token contract address
networkId (integer, required): Network ID

Example:

curl -X GET "https://api.cortex402.xyz/token/0xA0b86a33E6441b8C4C8C0E4b8b8C4C8C0E4b8b8C4/1/price"

Response includes:

address, price, priceUsd
networkId, networkName
lastUpdated timestamp

3. Wallet Balances

Get token balances for a wallet address across multiple networks

POST /balances

Request Body:

{
  "walletAddress": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  "networks": [1, 56, 137]
}

Parameters:

walletAddress (string, required): Wallet address to query
networks (array, required): Array of network IDs to query

Example:

curl -X POST "https://api.cortex402.xyz/balances" \
  -H "Content-Type: application/json" \
  -d '{"walletAddress": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6", "networks": [1, 56, 137]}'

4. Supported Networks

Get list of all supported blockchain networks

GET /networks

Example:

curl -X GET "https://api.cortex402.xyz/networks"

Response includes:

Array of network objects with id, name, symbol, chainId, isActive
Total count and lastUpdated timestamp

5. Top 10 Token Holders

Get the top 10 holders of a specific token

GET /token/{tokenId}/top10holders

Parameters:

tokenId (string, required): Token ID in format "network:address" (e.g., "ethereum:0x...")

Example:

curl -X GET "https://api.cortex402.xyz/token/ethereum:0xA0b86a33E6441b8C4C8C0E4b8b8C4C8C0E4b8b8C4/top10holders"

Response includes:

Array of top 10 holders with address, balance, percentage, rank
Total holders count and lastUpdated timestamp

6. Search Tokens

Search for tokens by name, symbol, or address

GET /tokens/search?q={query}&limit={limit}

Query Parameters:

q (string, required): Search query (token name, symbol, or address)
limit (integer, optional): Maximum results (1-100, default: 20)

Example:

curl -X GET "https://api.cortex402.xyz/tokens/search?q=bitcoin&limit=10"

Response includes:

Array of matching tokens with full metadata
Total count, original query, and lastUpdated timestamp

7. Price Bars (OHLCV Data)

Get historical price bars for charting

GET /bars?symbol={symbol}&from={from}&to={to}&resolution={resolution}&removeLeadingNullValues={boolean}

Query Parameters:

symbol (string, required): Token symbol (e.g., "BTC", "ETH")
from (integer, required): Start timestamp (Unix seconds)
to (integer, required): End timestamp (Unix seconds)
resolution (string, required): Bar resolution ("1", "5", "15", "30", "60", "240", "1D", "1W", "1M")
removeLeadingNullValues (boolean, optional): Remove leading null values (default: false)

Example:

curl -X GET "https://api.cortex402.xyz/bars?symbol=BTC&from=1640995200&to=1641081600&resolution=1D"

Response includes:

Array of bar data with timestamp (t), close (c), high (h), low (l), open (o), volume
Symbol, resolution, time range, and lastUpdated timestamp

8. Health Check

Check API server health and status

GET /health

Example:

curl -X GET "https://api.cortex402.xyz/health"

Response includes:

status: "healthy" or "unhealthy"
uptime, memory usage, version
timestamp

Common Use Cases

1. Token Research

# Get token info
GET https://api.cortex402.xyz/token/0x.../1

# Get current price
GET https://api.cortex402.xyz/token/0x.../1/price

# Search for similar tokens
GET https://api.cortex402.xyz/tokens/search?q=USDC&limit=10

2. Portfolio Analysis

# Get wallet balances across networks
POST https://api.cortex402.xyz/balances
{
  "walletAddress": "0x...",
  "networks": [1, 56, 137]
}

# Get top holders of a token
GET https://api.cortex402.xyz/token/ethereum:0x.../top10holders

3. Market Analysis

# Get price history
GET https://api.cortex402.xyz/bars?symbol=BTC&from=1640995200&to=1641081600&resolution=1D

# Get all supported networks
GET https://api.cortex402.xyz/networks

Error Handling

Common HTTP Status Codes

200: Success
400: Bad Request (invalid parameters)
402: Payment required
429: Rate Limit Exceeded
500: Internal Server Error

Rate Limiting

Rate limits are applied per endpoint
When rate limited, wait for retryAfter seconds before retrying
Rate limit headers may be included in responses

Best Practices

Always check the success field in responses
Handle rate limiting gracefully with exponential backoff
Use appropriate network IDs for your target blockchain
Validate input parameters before making requests
Cache responses when appropriate to reduce costs

Cost Optimization

Each request costs $0.0004 USDC
Cache responses when possible
Use batch operations when available
Monitor usage through health endpoints
Consider using search with appropriate limits

This API provides comprehensive blockchain data access with a simple, RESTful interface and built-in payment processing for seamless integration into applications.

Overview​

Base URL​

Authentication & Payment​

Prerequisites​

How x402 Works​

Supported Networks​

Major Networks​

Layer 2 & Scaling Solutions​

Testnets​

Other Notable Networks​

API Endpoints​

1. Token Information​

2. Token Price​

3. Wallet Balances​

4. Supported Networks​

5. Top 10 Token Holders​

6. Search Tokens​

7. Price Bars (OHLCV Data)​

8. Health Check​

Common Use Cases​

1. Token Research​

2. Portfolio Analysis​

3. Market Analysis​

Error Handling​

Common HTTP Status Codes​

Rate Limiting​

Best Practices​

Cost Optimization​

Overview

Base URL

Authentication & Payment

Prerequisites

How x402 Works

Supported Networks

Major Networks

Layer 2 & Scaling Solutions

Testnets

Other Notable Networks

API Endpoints

1. Token Information

2. Token Price

3. Wallet Balances

4. Supported Networks

5. Top 10 Token Holders

6. Search Tokens

7. Price Bars (OHLCV Data)

8. Health Check

Common Use Cases

1. Token Research

2. Portfolio Analysis

3. Market Analysis

Error Handling

Common HTTP Status Codes

Rate Limiting

Best Practices

Cost Optimization