TaifoonTAIFOON
TaifoonTAIFOON
DOCUMENTATION · 08
08API KEYS

API Keys
Registration & Authentication

TL;DR
Register with a wallet address to get an API key. Explorer tier is free and rate-limited at 100 req/min. Builder and Protocol tiers unlock higher limits and streaming endpoints. Payment accepted in USDC or ETH on Base. All usage tracked per-request.
08.1REGISTRATION

Registration
Get Your Key

One API call to register. Returns a key immediately. Explorer tier requires no payment.
REGISTER
POST /api/v1/register
Content-Type: application/json

{
  "wallet_address": "0xYourWalletAddress",
  "tier": "explorer"
}

// Response
{
  "api_key": "tfn_live_abc123...",
  "tier": "explorer",
  "rate_limit": 100,
  "user_id": "uuid-here",
  "key_prefix": "tfn_live_abc"
}
KEY SECURITY
Store your key securely. The raw key is only shown once at registration. We store a SHA-256 hash — if you lose the key, you need to generate a new one. Keys are prefixed with tfn_live_ for production and tfn_test_ for devnet.
08.2SDK INTEGRATION

SDK Integration
TypeScript + Rust

TYPESCRIPT
import { RegistryClient } from '@taifoon/sdk/registry';

// Register programmatically
const registry = new RegistryClient({
  baseUrl: 'https://scanner.taifoon.dev'
});

const { apiKey } = await registry.register(
  '0xYourWallet'
);

// Use the key with any client
import { ProofClient } from '@taifoon/sdk/proof';

const client = new ProofClient({
  baseUrl: 'https://scanner.taifoon.dev',
  apiKey: apiKey
});
.ENV CONFIGURATION
# .env
TAIFOON_API_KEY=tfn_live_abc123...
TAIFOON_BASE_URL=https://scanner.taifoon.dev

# Use in code:
const client = new ProofClient({
  baseUrl: process.env.TAIFOON_BASE_URL,
  apiKey: process.env.TAIFOON_API_KEY
});
08.3AUTHENTICATION

Authentication
Headers & Rate Limits

Include the API key in the X-API-Key header. Explorer tier can also access basic endpoints without a key (rate-limited by IP).
# Authenticated request (Builder+ tiers)
curl -H "X-API-Key: tfn_live_abc123..." \
  https://scanner.taifoon.dev/api/v5/proof/blob/1/19876543

# Explorer tier (no key needed)
curl https://scanner.taifoon.dev/api/v5/proof/blob/1/19876543
RATE LIMITS
Rate limit headers on every response:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 1711468860

When exceeded: HTTP 429 with Retry-After header.
08.4ACCESS TIERS

Access Tiers
Pricing & Limits

TIERRATEPRICEPAYMENTENDPOINTS
Explorer100/minFreeNoneProof, Gas (REST), Status
Builder1,000/min50 USDC/moUSDC or ETH on BaseAll REST + SSE
Protocol10,000/min500 USDC/moUSDC or ETH on BaseAll REST + SSE + gRPC
EnterpriseCustomCustomCustomAll + dedicated + SLA
08.5PAYMENT

Payment
USDC & ETH on Base

Paid tiers are activated on-chain via the ApiRegistry contract on Base (chain ID 8453). Payment is in USDC or native ETH. 30-day rolling subscription.
PAY WITH USDC
// 1. Approve USDC spend
IERC20(USDC).approve(registry, amount);

// 2. Activate subscription
registry.activateWithUsdc();

USDC on Base: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

PAY WITH ETH
// Send ETH directly — excess refunded
registry.activateWithEth({ value: ethAmount });

ETH price set by admin, updated periodically. Excess automatically refunded.

08.6USAGE TRACKING

Usage Tracking
Monitor Your Consumption

CHECK USAGE
GET /api/v1/usage
X-API-Key: tfn_live_abc123...

// Response
{
  "tier": "builder",
  "requests_today": 4521,
  "requests_this_month": 89432,
  "rate_limit_rpm": 1000,
  "top_endpoints": [
    { "endpoint": "/api/v5/proof/blob", "count": 3200 },
    { "endpoint": "/search-api/v5/gas", "count": 1321 }
  ],
  "subscription": {
    "status": "active",
    "expires_at": "2026-04-26T00:00:00Z",
    "amount_paid_usdc": 50.00
  }
}

All tiers — including Explorer (free) — are metered per-request. Usage data is stored in Supabase with hourly rollups. On-chain usage checkpoints are written periodically to the ApiRegistry contract for audit trail purposes.

08.7KEY MANAGEMENT

Key Management
Rotation & Revocation

Generate multiple keys per account. Revoke compromised keys instantly. Keys can be scoped to specific chains.
# Verify a key is valid
GET /api/v1/verify
X-API-Key: tfn_live_abc123...

// Response
{
  "valid": true,
  "tier": "builder",
  "rate_limit_rpm": 1000,
  "expires_at": "2026-04-26T00:00:00Z",
  "subscription_status": "active"
}
08.8NEXT STEPS

Next Steps