API Reference

The full OpenAPI 3.1 spec is served by the API at /openapi.json, with an interactive Scalar UI at /docs on the API host itself.

For static reference, the resources are:

Authentication

Every request requires a Bearer token:

• Dashboard auth: a Privy access token (POST /v1/auth/sync first).
• SDK auth: a merchant secret API key (prefix sk_test_… or sk_live_…).

Authorization: Bearer sk_test_xxx

Resources

Payment sessions

• POST /v1/payment-sessions , create a one-shot checkout session
• GET /v1/payment-sessions/:id , fetch
• GET /v1/payment-sessions , list

Subscriptions

• GET /v1/subscriptions/:id
• GET /v1/subscriptions (filterable by status, planId)
• POST /v1/subscriptions/:id/cancel , marks DB cancelled, enqueues on-chain cancel

Refunds

• POST /v1/refunds , returns wallet-signing instructions
• POST /v1/refunds/:id/signature , record the on-chain tx hash
• GET /v1/refunds, GET /v1/refunds/:id

Webhooks

• POST /v1/webhook-endpoints , register an endpoint, returns the signing secret once
• POST /v1/webhook-endpoints/:id/{enable,disable,rotate-secret}
• GET /v1/webhook-deliveries , every attempt, every response code

Invoices

• POST /v1/invoices , create with line items, returns a backing payment session
• POST /v1/invoices/:id/{send,void}

Storefronts

• POST /v1/storefront , create or update your storefront
• POST /v1/storefront/products , add a product
• GET /store/:slug , public read

Agents

• GET /v1/agents/config, PATCH /v1/agents/config
• GET /v1/agents/activity , chronological feed
• POST /v1/agents/jobs , create an ERC-8183 escrow job

Analytics

• GET /v1/stats/{conversion,churn,mrr,ltv,forecast}

Tokens (public, no auth)

• GET /v1/tokens/:address. Token metadata and the Strimz capability bitmap (EIP-3009, EIP-2612).
• GET /v1/tokens/:address/permit-nonce?owner=0x…. Current EIP-2612 permit nonce for an owner.

Checkout (public, no auth)

• GET /v1/checkout/sessions/:id. Loads a payment session for the hosted checkout page.
• GET /v1/checkout/plans/:id. Loads a subscription plan for the hosted enrolment page.

Relay (relay_write and relay_read scopes)

• POST /v1/relay/payments. Submits a payer-signed EIP-3009 authorization.
• POST /v1/relay/subscriptions. Submits a payer-signed EIP-2612 permit plus enrolment.
• GET /v1/relay/submissions/:idempotencyKey. Looks up a submission's on-chain status.

The tokens and checkout namespaces sit outside the auth boundary on purpose. Both serve data that is either chain-derived or already shown to the payer, so there is nothing confidential to protect. The hosted checkout pages and the browser SDK call them directly. From your own server, use the merchant-scoped equivalents on StrimzClient (paymentSessions.retrieve, subscriptionPlans.retrieve).

The relay namespace does need a secret key. The hosted checkout reaches it through a same-origin BFF route (/api/checkout/sessions/:id/submit) that proxies the call with a server-only Strimz key. The secret never leaves the server; the browser only ever talks to the BFF.