API Reference

Micropay exposes an OpenAI-compatible surface with x402 payment headers. Clients pay USDC on Algorand; Micropay settles via the GoPlausible facilitator, then fulfills inference through its server-side provider gateway.

Realtime

SSE — chat token streaming (stream:true) and image job progress (GET …/jobs/:id?stream=1).
WebSocket — not used; HTTP SSE covers streaming.
JSON poll — optional fallback for image jobs without stream=1.

POST

/api/v1/chat/completions

Chat completion (OpenAI-compatible, streaming supported). Anthropic-only models (e.g. Claude) are auto-routed via /v1/messages. x402 settle then Micropay runs inference. Provider keys stay server-side.

GET

/api/v1/models

List available models. Add ?raw=1 for the upstream catalog payload.

POST

/api/v1/images/generations

Image generation (requires Supabase Storage). Default waits for the job; ?async=1 returns jobId after payment (Studio then uses SSE).

GET

/api/v1/images/jobs/:jobId

Job status. JSON poll by default; ?stream=1 (or Accept: text/event-stream) for SSE progress until done. On completion persists images to Supabase (no extra payment).

POST

/api/v1/audio/transcriptions

Speech-to-text multipart transcription (50 MB max).

POST

/api/v1/storage/upload

Upload a file to Supabase Storage (multipart field: file; optional folder). Hard 50 MB limit. Server-side only.

GET

/api/v1/activities

Usage history from settled x402 requests. Optional ?wallet= & X-Wallet-Address.

GET

/api/v1/chat/sessions

List chat sessions for a wallet (?wallet=&modelId=&latest=1).

POST

/api/v1/chat/sessions

Create a session or append messages (persist chat turn).

GET

/api/v1/chat/sessions/:sessionId

Fetch a session and its messages.

DELETE

/api/v1/chat/sessions/:sessionId

Delete a session (or ?clear=1 to wipe messages only).

POST

/api/v1/puya-ts/compile

Compile Algorand TypeScript (puya-ts) to TEAL. Body: { source } or { files, entry }. Free (not x402).

# Browser clients: use @x402/fetch + Algorand wallet (auto PAYMENT-SIGNATURE).
# Agents: handle 402 → sign → retry with PAYMENT-SIGNATURE.

curl http://localhost:3000/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "PAYMENT-SIGNATURE: <signed-payload>" \
  -d '{
    "model": "glm-5.2",
    "messages": [{"role":"user","content":"Hello"}]
  }'