Architecture
What happens on every call.
A single request flows through ten gateway stages — auth to billing — in under 15ms of added latency. Here is the whole lifecycle.
Customer
X-API-Key
Gateway
auth · limit · resolve
Wallet HOLD
Redis Lua
Router
cheapest healthy
Adapter
req → vendor
Vendor
upstream API
Normalize
canonical schema
CAPTURE / RELEASE
success → debit · fail → refund
Ledgers
wallet + cost
Usage stream
ClickHouse
Response
call_id + result
Authenticate
Your X-API-Key is verified against a Redis cache (Postgres fallback). We attach your tenant, scopes and rate limits.
Rate limit
A Redis sliding window enforces per-key RPS and RPM. Bursts beyond your plan get a 429 with Retry-After.
Resolve product
The slug maps to a product contract; your request body is validated against its JSON Schema before any vendor is touched.
Idempotency check
If you send an Idempotency-Key, a 24-hour replay returns the original response byte-for-byte.
Wallet hold
We resolve your sale price and atomically reserve it from your wallet via a Redis Lua script. Insufficient balance → 402.
Pick cheapest healthy vendor
The router sorts active mappings by cost, filters by health, and prefers healthy over degraded — with circuit breakers on failures.
Adapter → vendor call
A per-mapping JSON adapter transforms your request into the vendor format and calls it with per-vendor timeouts.
Normalize response
The response adapter maps the vendor payload back into our canonical schema and decides success vs error.
Capture or release
On success we capture the hold and write both wallet and cost ledgers. On failure we release the hold — you are not charged.
Emit & return
A usage event streams to analytics; the normalized response (with call_id) returns to you. Margins are visible per call.
Double-sided ledger
Every successful call writes two entries: a wallet debit at your sale price (revenue) and a cost-ledger credit at the vendor cost (payable). Gross margin is captured per call and rolled up per product, vendor, tenant and day.
wallet_ledger
DEBIT the customer at the sale price — revenue side.
cost_ledger
CREDIT the vendor at the cost price — payable side.
See it on your own keys
Sandbox mode runs the whole flow without touching a vendor.