TaifoonTAIFOON
TaifoonTAIFOON
DOCUMENTATION · 08
REAL · THE COORDINATION LAYER · everything here is served under one namespace at taifoon.io/v1 — 73 operations. Machine-readable at /v1/openapi.json, and every endpoint with a working example is listed in the API overview.
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. The Builder key is earned, not bought: get on the bridge whitelist at taifoon.io/bridge (one delivered transfer, a verified X account, a linked wallet) and claim it there. Claiming is optional. 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,
  "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://api.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://api.taifoon.dev',
  apiKey: apiKey
});
.ENV CONFIGURATION
# .env
TAIFOON_API_KEY=tfn_live_abc123...
TAIFOON_BASE_URL=https://api.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://api.taifoon.dev/api/v5/proof/blob/8453/51383792

# Explorer tier (no key needed)
curl https://api.taifoon.dev/api/v5/proof/blob/8453/51383792
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