Billing API

Manage API keys, check usage, and upgrade plans via Stripe.

Create API Key

POST /api/v1/billing/api-keys

Requires JWT (Authorization: Bearer <token>).

{
  "organizationName": "Acme DeFi",
  "contactEmail": "dev@acme.com",
  "tier": "Free"
}

Validation

Field	Rules
organizationName	Required, 2–200 characters
contactEmail	Required, valid email, max 320 characters
tier	Free, Starter, Growth, or Enterprise (defaults to Free)

Response

{
  "id": "a1b2c3d4-...",
  "tier": "Free",
  "rateLimit": 10,
  "monthlyQueryLimit": 100,
  "createdAt": "2026-02-27T12:00:00Z",
  "note": "API key created. Use X-API-Key header to authenticate requests."
}

---

Get Usage

GET /api/v1/billing/usage

Requires API key (X-API-Key header).

Response

{
  "queriesThisMonth": 47,
  "monthlyLimit": 100,
  "remaining": 53
}

For Enterprise tier, monthlyLimit and remaining are null (unlimited).

---

Create Checkout Session

POST /api/v1/billing/checkout

Creates a Stripe Checkout session for upgrading to a paid plan.

{
  "planId": "starter",
  "walletAddress": "0x1234...",
  "successUrl": "https://your-app.com/billing/success",
  "cancelUrl": "https://your-app.com/billing/cancel"
}

Validation

Field	Rules
planId	Required, starter or growth
walletAddress	Optional, valid Ethereum address
successUrl	Optional, valid URL, max 2,000 chars
cancelUrl	Optional, valid URL, max 2,000 chars

Response

{
  "sessionId": "cs_live_abc123...",
  "url": "https://checkout.stripe.com/c/pay/cs_live_abc123..."
}

Redirect the user to url to complete payment.

---

Pricing Tiers

Tier	Rate Limit	Monthly Queries	Webhooks	Price
Free	10 req/s	100	—	$0
Starter	100 req/s	10,000	3	$49/mo
Growth	500 req/s	100,000	10	$199/mo
Enterprise	2,000 req/s	Unlimited	50	Contact us

---

Subscription Lifecycle

Stripe webhooks automatically manage tier upgrades and downgrades:

Stripe Event	Action
checkout.session.completed	Upgrade API key to purchased tier
customer.subscription.updated	Log subscription change
customer.subscription.deleted	Downgrade API key to Free tier