[P1] Implement Token API (Balances, Transfers, Metadata, Prices)

[BlocksScanIO]

Feature Request: Token API Suite

Background

Competitor Analysis Reference: Alchemy Token API, Covalent

Comprehensive token data APIs are essential for wallets, DeFi dashboards, and portfolio trackers. XDC Gateway needs robust token endpoints.

Requirements

Core API Endpoints

1. Token Balances

GET /api/v1/tokens/balances/:address
GET /api/v1/tokens/balances/:address?contractAddresses=0x...,0x...

{
  "address": "0x...",
  "balances": [
    {
      "contractAddress": "0x...",
      "name": "XDC Stable",
      "symbol": "XUSDT",
      "decimals": 18,
      "balance": "1000000000000000000",
      "balanceFormatted": "1.0",
      "price": {
        "usd": "1.00",
        "change24h": "0.01"
      },
      "valueUsd": "1.00"
    }
  ],
  "totalValueUsd": "1500.50"
}

2. Token Transfers

GET /api/v1/tokens/transfers?fromAddress=0x...
GET /api/v1/tokens/transfers?toAddress=0x...
GET /api/v1/tokens/transfers?contractAddress=0x...

{
  "transfers": [
    {
      "transactionHash": "0x...",
      "blockNumber": "12345678",
      "contractAddress": "0x...",
      "from": "0x...",
      "to": "0x...",
      "value": "1000000000000000000",
      "valueFormatted": "1.0",
      "tokenName": "XDC Stable",
      "tokenSymbol": "XUSDT",
      "decimals": 18,
      "timestamp": "2026-02-26T20:33:00Z"
    }
  ]
}

3. Token Metadata

GET /api/v1/tokens/:contractAddress/metadata

{
  "contractAddress": "0x...",
  "name": "XDC Stable",
  "symbol": "XUSDT",
  "decimals": 18,
  "totalSupply": "1000000000000000000000000",
  "type": "XRC20",
  "holders": 15000,
  "transfers": 500000,
  "verified": true,
  "logo": "https://...",
  "website": "https://...",
  "social": {
    "twitter": "...",
    "telegram": "..."
  }
}

4. Token Allowances

GET /api/v1/tokens/:contractAddress/allowances?owner=0x...

{
  "allowances": [
    {
      "spender": "0x...",
      "allowance": "1000000000000000000",
      "allowanceFormatted": "1.0",
      "spenderName": "Uniswap V3"
    }
  ]
}

5. Token Prices

GET /api/v1/tokens/:contractAddress/price
GET /api/v1/tokens/prices?contractAddresses=0x...,0x...

{
  "contractAddress": "0x...",
  "symbol": "XUSDT",
  "priceUsd": "1.00",
  "priceXdc": "25.0",
  "change24h": "0.01",
  "change7d": "0.05",
  "volume24h": "1000000",
  "marketCap": "100000000",
  "lastUpdated": "2026-02-26T20:33:00Z"
}

Technical Implementation

Database Schema

-- Token Contracts
CREATE TABLE tokens (
    address VARCHAR(42) PRIMARY KEY,
    name VARCHAR(255),
    symbol VARCHAR(50),
    decimals INTEGER,
    total_supply NUMERIC,
    type VARCHAR(20) DEFAULT 'XRC20',
    holders INTEGER DEFAULT 0,
    transfers INTEGER DEFAULT 0,
    verified BOOLEAN DEFAULT FALSE,
    logo_url TEXT,
    website TEXT,
    created_at TIMESTAMP,
    updated_at TIMESTAMP
);

-- Token Balances (materialized view or cache)
CREATE TABLE token_balances (
    address VARCHAR(42),
    token_address VARCHAR(42) REFERENCES tokens(address),
    balance NUMERIC DEFAULT 0,
    updated_at TIMESTAMP,
    PRIMARY KEY (address, token_address)
);

-- Token Transfers
CREATE TABLE token_transfers (
    id SERIAL PRIMARY KEY,
    token_address VARCHAR(42) REFERENCES tokens(address),
    from_address VARCHAR(42),
    to_address VARCHAR(42),
    value NUMERIC,
    transaction_hash VARCHAR(66),
    block_number BIGINT,
    log_index INTEGER,
    timestamp TIMESTAMP
);

-- Token Prices
CREATE TABLE token_prices (
    token_address VARCHAR(42) REFERENCES tokens(address),
    price_usd NUMERIC,
    price_xdc NUMERIC,
    change_24h NUMERIC,
    volume_24h NUMERIC,
    market_cap NUMERIC,
    updated_at TIMESTAMP DEFAULT NOW(),
    PRIMARY KEY (token_address)
);

-- Indexes
CREATE INDEX idx_token_transfers_token ON token_transfers(token_address);
CREATE INDEX idx_token_transfers_from ON token_transfers(from_address);
CREATE INDEX idx_token_transfers_to ON token_transfers(to_address);
CREATE INDEX idx_token_balances_address ON token_balances(address);
CREATE INDEX idx_token_balances_token ON token_balances(token_address);

Balance Indexer

package tokens

type BalanceIndexer struct {
    db     *pgx.Pool
    cache  *redis.Client
}

func (i *BalanceIndexer) ProcessTransfer(event *types.Log) error {
    // Parse Transfer event
    // Update sender balance
    // Update receiver balance
    // Cache invalidation
}

func (i *BalanceIndexer) GetBalance(address, token string) (*big.Int, error) {
    // Check cache first
    // Query database if cache miss
    // Update cache
}

Price Oracle Integration

type PriceOracle struct {
    sources []PriceSource // DEXes, CEXes, aggregators
}

func (o *PriceOracle) GetPrice(token string) (*Price, error) {
    // Aggregate prices from multiple sources
    // Calculate volume-weighted average
    // Handle stale data
}

Advanced Features

1. Historical Balances

GET /api/v1/tokens/balances/:address/historical?blockNumber=12345678

2. Token Analytics

GET /api/v1/tokens/:contractAddress/analytics
{
  "holders": {
    "total": 15000,
    "growth24h": 50,
    "distribution": {
      "whales": 100,
      "large": 500,
      "medium": 2000,
      "small": 12400
    }
  },
  "transfers": {
    "24h": 1500,
    "7d": 10000,
    "volume24h": "500000"
  }
}

3. Token Discovery

GET /api/v1/tokens/trending
GET /api/v1/tokens/new
GET /api/v1/tokens/top?by=volume|marketCap|holders

Batch Operations

POST /api/v1/tokens/batch/balances
{
  "addresses": ["0x...", "0x..."],
  "contractAddresses": ["0x..."]
}

WebSocket Events

{
  "event": "token.transfer",
  "data": {
    "contractAddress": "0x...",
    "from": "0x...",
    "to": "0x...",
    "value": "1000000000000000000",
    "transactionHash": "0x..."
  }
}

Acceptance Criteria

• All core endpoints functional
• Real-time balance updates
• Price data from multiple sources
• Historical balance queries
• Batch operations (up to 100 addresses)
• WebSocket events
• <50ms response for cached balances

Competitor Comparison

Feature	Alchemy	Covalent	XDC Gateway (Target)
Token Balances	✅	✅	🔄 Planned
Token Transfers	✅	✅	✅
Token Prices	✅	✅	✅
Historical	✅	✅	✅
Batch	✅	✅	✅

References

• Alchemy Token API
• Covalent Token API

Priority: P1 - Important for DeFi ecosystem
Estimated Effort: 6 weeks
Labels: enhancement, api, P1, tokens