API reference

Conventions

All requests/responses are JSON. Send Content-Type: application/json.
Auth: Authorization: Bearer sk_live_… (or session cookie for dashboard contexts).
Idempotency: every POST / PUT / DELETE must carry Idempotency-Key: <uuid>.
Times are ISO-8601 UTC strings.
Money amounts are decimal strings ("100.00") unless specifically noted as base units.

Authentication

POST /api/auth/sign-up/email     { name, email, password }
POST /api/auth/sign-in/email     { email, password }
POST /api/auth/sign-out
GET  /api/auth/get-session

These come from better-auth; see their docs for the full surface.

Identity

GET  /v1/me

{ "user_id": "...", "platform_id": "...", "auth_kind": "session", "onboarded": true }

Platform onboarding

POST /v1/onboarding/self     (session, no platform yet)

// Request
{
  "name": "Acme Events",
  "platform_wallet": "0xabc…",
  "chain_id": 84532,
  "platform_fee_bps": 1000,
  "default_reserve_bps": 500
}
// Response 201
{
  "platform_id": "...",
  "name": "Acme Events",
  "secret_key": "sk_live_...",
  "publishable_key": "pk_live_...",
  "platform_wallet": "0xabc…",
  "chain_id": 84532,
  "platform_fee_bps": 1000
}

Sub-merchants

Direct creation

POST /v1/onboarding/merchants    (bearer)

Invitation links

POST /v1/merchants/invitations                 (bearer)
GET  /v1/merchants/invitations                 (bearer)
GET  /v1/merchants/invitations/:token          (public)
POST /v1/merchants/invitations/:token/complete (public, signed)

Listing / detail

GET /v1/merchants
GET /v1/merchants/:id

Orders

POST /v1/orders                  (bearer)
GET  /v1/orders                  (bearer)
GET  /v1/orders/summary          (bearer)
GET  /v1/orders/:id              (bearer)

Refunds

POST /v1/refunds                 (bearer)
GET  /v1/refunds                 (bearer)

Hosted Checkout

POST /v1/checkout/sessions               (bearer)
GET  /v1/checkout/sessions/:token        (public)

Webhooks

POST   /v1/webhooks/endpoints            (bearer)
GET    /v1/webhooks/endpoints            (bearer)
DELETE /v1/webhooks/endpoints/:id        (bearer)

Developers (API keys)

GET  /v1/developers/keys                 (session or bearer)
POST /v1/developers/keys/:id/revoke      (session or bearer)

Health

GET /health

{
  "ok": true,
  "env": "production",
  "time_ms": 18,
  "db": { "ok": true, "latency_ms": 5, "error": null }
}

Operations (admin-only)

POST /_/indexer/start                    (admin)
POST /_/indexer/stop                     (admin)
GET  /_/indexer/status                   (admin)

These trigger the Base chain indexer Durable Object that polls for OrderPaid / Refunded / BatchSettled events. You will not need them as an integrator.

API reference

On this page