benzuko

API reference

Base URL: /api. All responses are JSON. Errors share the shape { error: string, code: string, details?: unknown }.

GET /api/health

Liveness probe.

• 200 { "status": "ok", "service": "benzuko", "time": "<iso>" }

GET /api/offers

Returns P2P offers for a side.

• Query: side = buy

  sell (default buy), validated by offersQuerySchema.

• 200 { "data": Offer[], "count": number }
• 400 BAD_REQUEST — invalid side.
• 429 RATE_LIMITED — includes Retry-After header.

Offer shape: see types/index.ts.

curl "http://localhost:3000/api/offers?side=sell"

POST /api/trades

Opens an escrow-locked trade.

• Body: validated by createTradeSchema: { side, asset, amount, price, currency, counterparty, method }.
• 201 { "data": Trade } with status: "locked".
• 400 BAD_REQUEST — malformed JSON.
• 422 VALIDATION_ERROR — includes details (Zod flatten).
• 429 RATE_LIMITED.

curl -X POST http://localhost:3000/api/trades \
  -H 'Content-Type: application/json' \
  -d '{"side":"buy","asset":"USDT","amount":500,"price":119.85,"currency":"BDT","counterparty":"Rahim T.","method":"Wise"}'

Rate limiting

Fixed-window, in-memory (lib/rate-limit.ts), keyed by x-forwarded-for. Defaults: 60 requests / 60s. Swap for Redis/Upstash in production.

Error codes

| Code | HTTP | Meaning | | — | — | — | | BAD_REQUEST | 400 | Malformed input | | VALIDATION_ERROR | 422 | Zod validation failed | | RATE_LIMITED | 429 | Too many requests |

This site is open source. Improve this page.