GET /v1/analytics/metrics computes, from live sessions, payments, subscriptions and catalog: checkout conversion, per-payment-link opened / paid / conversion / revenue, repeat customers, average revenue per customer, subscription churn, ARPU and an estimated lifetime value, with exact bigint money. Checkout repositories gain listCreatedSince (in-memory and Postgres). The dashboard Analytics page shows the new cards and a payment-link table. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
89 KiB
SettleKit REST API Reference
SettleKit is an open-source USDC Commerce OS: sell private repos, SaaS, APIs, AI
tools, license keys, files, and more — and auto-deliver access on payment. This
document is the complete reference for the HTTP API served by apps/api.
- Base URL (local):
http://localhost:8787 - API version prefix:
/v1 - Settlement asset: USDC (decimal major-unit strings, e.g.
"19.99") - Content type:
application/jsonfor all request and response bodies
Contents
- Conventions
- Auth (
/v1/auth) - Products & Prices (
/v1/products) - Customers (
/v1/customers) - Checkout Sessions (
/v1/checkout-sessions) - Payments (
/v1/payments) - Subscriptions (
/v1/subscriptions) - Entitlements (
/v1/entitlements) - License Keys (
/v1/license-keys) - API Keys (
/v1/api-keys) - Coupons (
/v1/coupons) - Invoices (
/v1/invoices) - Refunds (
/v1/refunds) - Dunning (
/v1/dunning) - Disputes (
/v1/disputes) - Payouts (
/v1/payouts) - Bundles (
/v1/bundles) - Agent Services (
/v1/agent-services) - Marketplace (
/v1/marketplace) - Usage & Credits (
/v1/usage) - Analytics (
/v1/analytics) - Settings (
/v1/settings) - Escrow (
/v1/escrow) - Webhooks (
/v1/webhooks) - Files (
/v1/files) - Delivery Runs & Actions (
/v1/delivery-runs,/v1/delivery-actions) - SaaS (
/v1/saas) - GitHub Integration (
/v1/integrations/github,/v1/github/access) - Discord Integration (
/v1/integrations/discord,/v1/discord/access) - x402 Paid Endpoints (
/v1/paid/*)
Conventions
Response envelope
Every successful response is wrapped in a data envelope:
{ "data": <payload> }
Mutations that create a resource return HTTP 201 Created; reads and other
mutations return HTTP 200 OK. Two endpoints return raw (non-enveloped)
payloads by design and are noted inline:
GET /v1/agent-services/:id/metadata.json— raw machine-readable metadata JSON.GET /v1/invoices/:id.html— rendered HTML (text/html).
Error envelope
Every error response uses the error envelope:
{
"error": {
"code": "not_found",
"message": "product not found",
"details": { "id": "prod_123" }
}
}
details is optional and only present when the error carries structured
context. Unhandled routes return a uniform 404:
{ "error": { "code": "not_found", "message": "No route for GET /v1/nope" } }
Error codes
The HTTP status is derived from the error code:
| Code | HTTP | Meaning |
|---|---|---|
validation_error |
400 | Request body/query failed schema validation, or domain precondition failed. details carries Zod field issues. |
unauthorized |
401 | Missing or invalid Authorization header / API key / session token. |
payment_required |
402 | An x402 paid resource requires payment (see x402). |
payment_failed |
402 | A payment could not be settled. |
insufficient_credits |
402 | Not enough prepaid credits to satisfy the request. |
forbidden |
403 | Authenticated but not allowed to perform the action. |
entitlement_expired |
403 | The entitlement backing the request has expired. |
not_found |
404 | Resource does not exist. |
conflict |
409 | State conflict (e.g. duplicate, illegal lifecycle transition). |
rate_limited |
429 | Too many requests. |
delivery_failed |
500 | A delivery action failed to execute. |
internal_error |
500 | Unexpected server error. |
integration_error |
502 | An upstream integration (GitHub, Discord, chain RPC, etc.) failed. |
Validation errors include the failing fields under details:
{
"error": {
"code": "validation_error",
"message": "Request body failed validation",
"details": {
"issues": [
{ "code": "invalid_type", "path": ["amount"], "message": "Required" }
]
}
}
}
Authentication
All /v1 resource endpoints are guarded by a Bearer API key:
Authorization: Bearer <apiKey>
Two route groups are intentionally public (no API key):
/v1/auth/*— sign-up / sign-in use a session token, not an API key./v1/paid/*— x402 paid endpoints; the USDC payment itself is the authorization. They return402 Payment Requireduntil paid.
For local development and tests a bootstrap key can be configured via the
API_BOOTSTRAP_KEY environment variable; presenting it as the Bearer token
authenticates without any key existing in the store.
The session token returned by
/v1/auth/loginis not an API key and cannot be used asAuthorization: Bearer <apiKey>on resource routes. Issue an API key viaPOST /v1/api-keysfor programmatic access.
Money & identifiers
- Money is always a decimal major-unit string in USDC:
"0.005","19.99". AMoneyobject is{ "amount": "19.99", "currency": "USDC" }. - IDs are prefixed and opaque, e.g.
prod_…,price_…,customer_…,cs_…,pay_…,sub_…,ent_…. - Timestamps are ISO-8601 strings (
2026-06-16T12:00:00.000Z).
Health check
GET /health
Unauthenticated liveness probe.
curl http://localhost:8787/health
{ "data": { "status": "ok", "service": "settlekit-api" } }
Configuration
The API reads configuration from environment variables. Persistence is
dual-backend: when DATABASE_URL is set the API uses real Postgres via
@settlekit/persistence (drizzle, document-projection); when unset it uses an
in-memory backend. On-chain USDC verification is enabled only when Arc is
configured (ARC_RPC_URL).
| Variable | Purpose |
|---|---|
PORT |
API listen port (default 8787). |
DATABASE_URL |
Postgres connection string; unset → in-memory persistence. |
API_BOOTSTRAP_KEY |
Static Bearer key that authenticates without the key store. |
AUTH_COOKIE_SECRET |
HMAC secret for the signed sk_session cookie. |
LICENSE_TOKEN_SECRET |
Signing secret for offline license validation tokens. |
WEBHOOK_SIGNING_SECRET |
Default webhook signing secret. |
ARC_RPC_URL, ARC_CHAIN_ID, ARC_USDC_ADDRESS, ARC_MIN_CONFIRMATIONS |
Arc on-chain USDC settlement/verification. |
CIRCLE_API_KEY, CIRCLE_BASE_URL |
Circle settlement rail. |
GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY, GITHUB_INSTALLATION_ID, GITHUB_WEBHOOK_SECRET |
GitHub App integration. |
DISCORD_BOT_TOKEN |
Discord bot for role delivery. |
FILE_DOWNLOAD_BASE_URL, FILE_DOWNLOAD_SECRET, FILE_DOWNLOAD_EXPIRES_SEC, FILE_DOWNLOAD_MAX_DOWNLOADS |
Signed file-download issuance. |
RESEND_API_KEY, EMAIL_FROM |
Transactional email (magic links, receipts). |
MERCHANT_NAME, MERCHANT_EMAIL, MERCHANT_WEBSITE |
Merchant identity on invoices. |
X402_PAY_TO |
Destination address advertised by /v1/paid/research. |
Apply Postgres migrations with:
pnpm --filter @settlekit/database db:migrate
# or
make db-migrate
Auth
Public routes under /v1/auth (no API key). On every successful sign-in the
opaque session token is returned in the body and written to a signed,
HTTP-only sk_session cookie. The GET /session and POST /logout endpoints
take the session token as a Bearer header.
POST /v1/auth/register
Create a password account and immediately open a session. Public.
Body:
| Field | Type | Required | Notes |
|---|---|---|---|
email |
string | yes | |
password |
string | yes | |
type |
"merchant" | "customer" |
yes | |
organizationId |
string | no | |
displayName |
string | no |
curl -X POST http://localhost:8787/v1/auth/register \
-H "Content-Type: application/json" \
-d '{"email":"owner@acme.dev","password":"s3cret-pass","type":"merchant","displayName":"Acme"}'
{
"data": {
"account": {
"id": "acct_01H...",
"type": "merchant",
"email": "owner@acme.dev",
"displayName": "Acme",
"createdAt": "2026-06-16T12:00:00.000Z"
},
"sessionToken": "sess_3f9a..."
}
}
POST /v1/auth/login
Verify credentials and open a session. Public.
curl -X POST http://localhost:8787/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"owner@acme.dev","password":"s3cret-pass"}'
{
"data": {
"account": { "id": "acct_01H...", "type": "merchant", "email": "owner@acme.dev" },
"sessionToken": "sess_3f9a..."
}
}
Invalid credentials return 401 unauthorized.
POST /v1/auth/magic-link/request
Issue a single-use sign-in token. Public. When no email transport is
configured the token is returned in the response as devToken so the flow stays
testable; otherwise it is emailed and only { "ok": true } is returned.
curl -X POST http://localhost:8787/v1/auth/magic-link/request \
-H "Content-Type: application/json" \
-d '{"email":"owner@acme.dev"}'
{ "data": { "ok": true, "devToken": "ml_8c1d..." } }
POST /v1/auth/magic-link/complete
Consume a magic-link token and open a session. Public.
curl -X POST http://localhost:8787/v1/auth/magic-link/complete \
-H "Content-Type: application/json" \
-d '{"token":"ml_8c1d..."}'
{
"data": {
"account": { "id": "acct_01H...", "type": "merchant", "email": "owner@acme.dev" },
"sessionToken": "sess_77b2..."
}
}
GET /v1/auth/session
Resolve the account for a session token. Auth: Bearer <sessionToken>.
curl http://localhost:8787/v1/auth/session \
-H "Authorization: Bearer sess_3f9a..."
{ "data": { "account": { "id": "acct_01H...", "type": "merchant", "email": "owner@acme.dev" } } }
POST /v1/auth/logout
Revoke the session token (idempotent) and clear the cookie. Auth: Bearer <sessionToken>.
curl -X POST http://localhost:8787/v1/auth/logout \
-H "Authorization: Bearer sess_3f9a..."
{ "data": { "ok": true } }
Products & Prices
/v1/products — Auth required. A product is created as a draft, then
published once it has an active price.
Product type (one of): saas_plan, github_repo_access,
github_org_team_access, api_access, paid_api_call, ai_agent_service,
digital_download, code_template, dataset, license_key,
private_package, discord_access, support_plan, course_or_content,
consulting_slot, escrow_task, bundle.
Delivery deliveryMode (one of): github_invite, github_team_add,
license_key, api_key, file_download, discord_role, saas_entitlement,
webhook, email, bundle, none.
POST /v1/products
| Field | Type | Required | Default |
|---|---|---|---|
merchantId |
string | yes | |
organizationId |
string | yes | |
name |
string | yes | |
description |
string | no | "" |
type |
product type | yes | |
deliveryMode |
delivery mode | yes | |
metadata |
object | no | {} |
curl -X POST http://localhost:8787/v1/products \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{
"merchantId":"acct_01H...","organizationId":"org_1",
"name":"Pro Repo Access","type":"github_repo_access",
"deliveryMode":"github_invite"
}'
{
"data": {
"id": "prod_5d2c...",
"merchantId": "acct_01H...",
"organizationId": "org_1",
"name": "Pro Repo Access",
"description": "",
"type": "github_repo_access",
"deliveryMode": "github_invite",
"status": "draft",
"metadata": {},
"createdAt": "2026-06-16T12:00:00.000Z"
}
}
GET /v1/products
List all products.
curl http://localhost:8787/v1/products -H "Authorization: Bearer $SK_API_KEY"
{ "data": [ { "id": "prod_5d2c...", "name": "Pro Repo Access", "status": "draft" } ] }
GET /v1/products/:id
curl http://localhost:8787/v1/products/prod_5d2c... -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "prod_5d2c...", "name": "Pro Repo Access", "status": "draft" } }
404 not_found when the product does not exist.
POST /v1/products/:id/publish
Publish a product. Requires at least one active price on the product.
curl -X POST http://localhost:8787/v1/products/prod_5d2c.../publish \
-H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "prod_5d2c...", "status": "active" } }
POST /v1/products/:id/prices
Create a price for a product.
| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
amount |
string | yes | Decimal, e.g. "19.99". |
|
currency |
"USDC" |
no | "USDC" |
|
interval |
"one_time" | "monthly" | "yearly" |
no | "one_time" |
|
usageBased |
boolean | no | false |
|
unitAmount |
string | no | Per-unit price for usage-based billing. | |
creditsGranted |
integer > 0 | no | Prepaid credits granted on purchase. |
curl -X POST http://localhost:8787/v1/products/prod_5d2c.../prices \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"amount":"19.99","interval":"monthly"}'
{
"data": {
"id": "price_a18f...",
"productId": "prod_5d2c...",
"amount": "19.99",
"currency": "USDC",
"interval": "monthly",
"usageBased": false,
"active": true,
"createdAt": "2026-06-16T12:00:00.000Z"
}
}
GET /v1/products/:id/prices
List prices for a product.
curl http://localhost:8787/v1/products/prod_5d2c.../prices -H "Authorization: Bearer $SK_API_KEY"
{ "data": [ { "id": "price_a18f...", "amount": "19.99", "interval": "monthly", "active": true } ] }
Customers
/v1/customers — Auth required. Customers carry the external identity hooks
(githubUsername, discordUserId, walletAddress) that delivery actions
consume.
POST /v1/customers
| Field | Type | Required | Default |
|---|---|---|---|
organizationId |
string | yes | |
email |
string (email) | yes | |
name |
string | no | |
walletAddress |
string | no | |
githubUsername |
string | no | |
discordUserId |
string | no | |
metadata |
object | no | {} |
curl -X POST http://localhost:8787/v1/customers \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"organizationId":"org_1","email":"buyer@dev.io","githubUsername":"octocat"}'
{
"data": {
"id": "customer_9a3b...",
"organizationId": "org_1",
"email": "buyer@dev.io",
"githubUsername": "octocat",
"metadata": {},
"createdAt": "2026-06-16T12:00:00.000Z"
}
}
GET /v1/customers
List all customers.
curl http://localhost:8787/v1/customers -H "Authorization: Bearer $SK_API_KEY"
GET /v1/customers/:id
curl http://localhost:8787/v1/customers/customer_9a3b... -H "Authorization: Bearer $SK_API_KEY"
404 not_found when missing.
Checkout Sessions
/v1/checkout-sessions — Auth required. Resolves each line item's price,
computes the total, and persists an open session. Networks: arc, base,
ethereum.
POST /v1/checkout-sessions
| Field | Type | Required | Notes |
|---|---|---|---|
organizationId |
string | yes | |
merchantId |
string | yes | |
customerId |
string | no | Required before recording a payment. |
items |
array | yes (min 1) | Each: { priceId, quantity?, productId?, bundleId? }. |
payToAddress |
string | yes | Address that must receive USDC. |
network |
arc | base | ethereum |
yes | |
successUrl |
string (url) | no | |
cancelUrl |
string (url) | no | |
collectedFields |
object<string,string> | no | Buyer delivery fields. |
ttlDays |
integer > 0 | no |
curl -X POST http://localhost:8787/v1/checkout-sessions \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{
"organizationId":"org_1","merchantId":"acct_01H...",
"customerId":"customer_9a3b...",
"items":[{"priceId":"price_a18f...","productId":"prod_5d2c...","quantity":1}],
"payToAddress":"0xMerchantWallet","network":"arc"
}'
{
"data": {
"id": "cs_2b7e...",
"organizationId": "org_1",
"merchantId": "acct_01H...",
"customerId": "customer_9a3b...",
"status": "open",
"amount": { "amount": "19.99", "currency": "USDC" },
"network": "arc",
"payToAddress": "0xMerchantWallet",
"lineItems": [ { "priceId": "price_a18f...", "productId": "prod_5d2c...", "quantity": 1 } ],
"createdAt": "2026-06-16T12:00:00.000Z"
}
}
A missing priceId returns 400 validation_error.
GET /v1/checkout-sessions/:id
curl http://localhost:8787/v1/checkout-sessions/cs_2b7e... -H "Authorization: Bearer $SK_API_KEY"
Promo codes
Add "couponCode": "LAUNCH20" to apply one of your coupons. The session amount becomes the discounted total (what the buyer pays and what onchain verification expects) and discount records the code, list subtotal and amount off. The redemption is counted once, when the payment confirms. Codes that give a free trial, cover the whole price, or belong to another seller are refused with a 400. Payment links accept the same through /l/<slug>?promo=CODE, and buyers can enter a code on the hosted checkout until a payment is recorded.
Fiat pricing
A price can be set in a fiat currency: POST /v1/products/:id/prices with { "displayCurrency": "EUR", "displayAmount": "29" } (or currency: "EUR" on POST /v1/merchant/products). Checkout converts it to USDC at the live ECB rate (frankfurter service, FX_RATES_URL), rounded to the cent, and locks the rate on the session as fxQuote (currency, fiat amount, rate, USDC amount, rate date) until the session expires, so the buyer pays exactly the quoted USDC. Items in two different fiat currencies cannot share a checkout, subscriptions stay in USD, and checkout answers 503 when no valid rate is available.
Tax
When the seller turns tax on (POST /v1/settings with tax: { enabled, label, sellerCountry, taxId, legalName, rates: { "DE": 1900 }, defaultRateBps, reverseCharge }, rates in basis points), sessions add tax on top of the net price (after any promo) and tax records the rate, jurisdiction, net and tax amounts. billingCountry (ISO alpha-2) and vatId pick the buyer's rate; without them the seller's own country rate applies. EU business buyers in another member state with a VAT ID of the right shape get 0% (reverse charge) when the seller enables it. VAT IDs are checked for shape only. Buyers can change country and VAT ID on the hosted checkout until a payment is recorded.
Receipts
GET /v1/public/receipts/:sessionId/pdf (no API key; the session id is the capability, as on the hosted checkout) returns a PDF receipt for a settled checkout with line items, discount, tax rate and jurisdiction (or reverse charge), the seller's legal name and tax ID, the buyer's country and VAT ID, and the settlement transaction. The hosted checkout serves it at /c/<sessionId>/receipt, the success page and receipt email link to it, and the customer portal lists it per purchase.
POST /v1/checkout-sessions/:id/collect-fields
Merge buyer-supplied delivery fields into an open session.
curl -X POST http://localhost:8787/v1/checkout-sessions/cs_2b7e.../collect-fields \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"fields":{"githubUsername":"octocat"}}'
{ "data": { "id": "cs_2b7e...", "collectedFields": { "githubUsername": "octocat" } } }
POST /v1/checkout-sessions/:id/cancel
curl -X POST http://localhost:8787/v1/checkout-sessions/cs_2b7e.../cancel \
-H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "cs_2b7e...", "status": "canceled" } }
POST /v1/checkout-sessions/:id/expire
curl -X POST http://localhost:8787/v1/checkout-sessions/cs_2b7e.../expire \
-H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "cs_2b7e...", "status": "expired" } }
Payments
/v1/payments — Auth required. The core money + access flow: record →
confirm (grants entitlements) → optionally refund. When Arc is configured
(ARC_RPC_URL) and the payment network is arc, confirmation verifies the USDC
transfer on-chain before completing.
POST /v1/payments
Record a pending payment against a checkout session. The session must have a
customerId.
| Field | Type | Required |
|---|---|---|
checkoutSessionId |
string | yes |
txHash |
string | no |
curl -X POST http://localhost:8787/v1/payments \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"checkoutSessionId":"cs_2b7e..."}'
{
"data": {
"id": "pay_4c9d...",
"organizationId": "org_1",
"checkoutSessionId": "cs_2b7e...",
"customerId": "customer_9a3b...",
"amount": { "amount": "19.99", "currency": "USDC" },
"network": "arc",
"status": "pending",
"createdAt": "2026-06-16T12:00:00.000Z"
}
}
A session without customerId returns 400 validation_error.
GET /v1/payments/:id
curl http://localhost:8787/v1/payments/pay_4c9d... -H "Authorization: Bearer $SK_API_KEY"
POST /v1/payments/:id/confirm
Confirm a payment with at least the minimum confirmations. Completes the
checkout session and grants one entitlement per line-item product. On Arc with
verification configured, the on-chain transfer is validated against the
session's payToAddress and amount; a mismatch returns 400 validation_error.
| Field | Type | Required |
|---|---|---|
txHash |
string | yes |
confirmations |
integer ≥ 0 | yes |
minConfirmations |
integer > 0 | no |
curl -X POST http://localhost:8787/v1/payments/pay_4c9d.../confirm \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"txHash":"0xabc123...","confirmations":12,"minConfirmations":6}'
{
"data": {
"payment": {
"id": "pay_4c9d...",
"status": "confirmed",
"txHash": "0xabc123...",
"confirmedAt": "2026-06-16T12:01:00.000Z"
},
"entitlements": [
{
"id": "ent_77aa...",
"customerId": "customer_9a3b...",
"productId": "prod_5d2c...",
"status": "active",
"grantedBy": { "type": "payment", "id": "pay_4c9d..." }
}
]
}
}
POST /v1/payments/:id/fail
Mark a pending payment failed.
curl -X POST http://localhost:8787/v1/payments/pay_4c9d.../fail \
-H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "pay_4c9d...", "status": "failed" } }
POST /v1/payments/:id/refund
Refund a confirmed payment.
curl -X POST http://localhost:8787/v1/payments/pay_4c9d.../refund \
-H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "pay_4c9d...", "status": "refunded" } }
Subscriptions
/v1/subscriptions — Auth required. Created from a recurring price; grants a
subscription entitlement on creation.
POST /v1/subscriptions
| Field | Type | Required | Notes |
|---|---|---|---|
organizationId |
string | yes | |
customerId |
string | yes | |
productId |
string | yes | |
priceId |
string | yes | Must be a recurring (monthly/yearly) price. |
cancelAtPeriodEnd |
boolean | no |
curl -X POST http://localhost:8787/v1/subscriptions \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"organizationId":"org_1","customerId":"customer_9a3b...","productId":"prod_5d2c...","priceId":"price_a18f..."}'
{
"data": {
"subscription": {
"id": "sub_6e1a...",
"customerId": "customer_9a3b...",
"productId": "prod_5d2c...",
"priceId": "price_a18f...",
"status": "active",
"currentPeriodEnd": "2026-07-16T12:00:00.000Z"
},
"entitlement": { "id": "ent_8b2c...", "status": "active", "grantedBy": { "type": "subscription", "id": "sub_6e1a..." } }
}
}
A one-time price returns 400 validation_error.
GET /v1/subscriptions/:id
curl http://localhost:8787/v1/subscriptions/sub_6e1a... -H "Authorization: Bearer $SK_API_KEY"
POST /v1/subscriptions/:id/renew
Renew for one more period (interval derived from the price).
curl -X POST http://localhost:8787/v1/subscriptions/sub_6e1a.../renew \
-H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "sub_6e1a...", "status": "active", "currentPeriodEnd": "2026-08-16T12:00:00.000Z" } }
POST /v1/subscriptions/:id/cancel
curl -X POST http://localhost:8787/v1/subscriptions/sub_6e1a.../cancel \
-H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "sub_6e1a...", "status": "canceled" } }
Entitlements
/v1/entitlements — Auth required. The universal access layer. The
hot-path verify endpoint is what SDKs call to gate access.
GET /v1/entitlements
List a customer's entitlements.
| Query param | Type | Required | Notes |
|---|---|---|---|
customerId |
string | yes | |
activeOnly |
"true" |
no | Active entitlements only. |
productId |
string | no | Filter to a product. |
curl "http://localhost:8787/v1/entitlements?customerId=customer_9a3b...&activeOnly=true" \
-H "Authorization: Bearer $SK_API_KEY"
{ "data": [ { "id": "ent_77aa...", "productId": "prod_5d2c...", "status": "active" } ] }
POST /v1/entitlements/verify
Verify access by feature flag, credits, and/or product. Body must be strict (no unknown keys).
| Field | Type | Required |
|---|---|---|
customerId |
string | yes |
productId |
string | no |
feature |
string | no |
requiredCredits |
integer > 0 | no |
curl -X POST http://localhost:8787/v1/entitlements/verify \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"customerId":"customer_9a3b...","productId":"prod_5d2c..."}'
{ "data": { "granted": true, "entitlementId": "ent_77aa...", "creditsRemaining": null } }
POST /v1/entitlements/spend-credits
Spend credits against a product entitlement.
| Field | Type | Required |
|---|---|---|
customerId |
string | yes |
productId |
string | yes |
amount |
integer > 0 | yes |
curl -X POST http://localhost:8787/v1/entitlements/spend-credits \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"customerId":"customer_9a3b...","productId":"prod_5d2c...","amount":1}'
{ "data": { "id": "ent_77aa...", "creditsRemaining": 99 } }
GET /v1/entitlements/:id
curl http://localhost:8787/v1/entitlements/ent_77aa... -H "Authorization: Bearer $SK_API_KEY"
POST /v1/entitlements/:id/revoke
| Field | Type | Required | Default |
|---|---|---|---|
reason |
string | no | "revoked via API" |
curl -X POST http://localhost:8787/v1/entitlements/ent_77aa.../revoke \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"reason":"chargeback"}'
{ "data": { "id": "ent_77aa...", "status": "revoked", "revokedReason": "chargeback" } }
License Keys
/v1/license-keys — Auth required. Machine/domain-limited keys with offline
validation tokens.
POST /v1/license-keys
Issue a license key.
| Field | Type | Required | Default |
|---|---|---|---|
organizationId |
string | yes | |
customerId |
string | yes | |
productId |
string | yes | |
entitlementId |
string | yes | |
machineLimit |
integer > 0 | no | 1 |
domainLimit |
integer > 0 | no | |
expiresAt |
datetime | no |
curl -X POST http://localhost:8787/v1/license-keys \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"organizationId":"org_1","customerId":"customer_9a3b...","productId":"prod_5d2c...","entitlementId":"ent_77aa...","machineLimit":3}'
{
"data": {
"id": "lk_2a44...",
"key": "SK-LICN-XXXX-YYYY-ZZZZ",
"productId": "prod_5d2c...",
"machineLimit": 3,
"status": "active",
"createdAt": "2026-06-16T12:00:00.000Z"
}
}
POST /v1/license-keys/verify
Verify a license key for a product + machine (activates the machine when new and within capacity).
| Field | Type | Required |
|---|---|---|
licenseKey |
string | yes |
productId |
string | yes |
machineId |
string | yes |
curl -X POST http://localhost:8787/v1/license-keys/verify \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"licenseKey":"SK-LICN-XXXX-YYYY-ZZZZ","productId":"prod_5d2c...","machineId":"machine-01"}'
{ "data": { "valid": true, "license": { "id": "lk_2a44...", "machineCount": 1, "machineLimit": 3 } } }
POST /v1/license-keys/:id/token
Mint an offline validation token for an existing license.
curl -X POST http://localhost:8787/v1/license-keys/lk_2a44.../token \
-H "Authorization: Bearer $SK_API_KEY"
{ "data": { "token": "eyJhbGci..." } }
POST /v1/license-keys/:id/revoke
curl -X POST http://localhost:8787/v1/license-keys/lk_2a44.../revoke \
-H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "lk_2a44...", "status": "revoked" } }
API Keys
/v1/api-keys — Auth required. Issues scoped keys for a customer's
entitlement. The plaintext secret is returned exactly once on issuance; only
its SHA-256 hash is stored.
POST /v1/api-keys
| Field | Type | Required | Default |
|---|---|---|---|
organizationId |
string | yes | |
customerId |
string | yes | |
productId |
string | yes | |
entitlementId |
string | yes | |
scopes |
string[] | yes (min 1) | |
env |
"live" | "test" |
no | "live" |
curl -X POST http://localhost:8787/v1/api-keys \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"organizationId":"org_1","customerId":"customer_9a3b...","productId":"prod_5d2c...","entitlementId":"ent_77aa...","scopes":["read:data"],"env":"live"}'
{
"data": {
"apiKey": { "id": "ak_5f8b...", "prefix": "sk_live_", "scopes": ["read:data"], "env": "live" },
"plaintext": "sk_live_3f9a2c8e..."
}
}
POST /v1/api-keys/verify
Verify a presented key, optionally enforcing required scopes.
| Field | Type | Required | Default |
|---|---|---|---|
key |
string | yes | |
requiredScopes |
string[] | no | [] |
curl -X POST http://localhost:8787/v1/api-keys/verify \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"key":"sk_live_3f9a2c8e...","requiredScopes":["read:data"]}'
{ "data": { "valid": true, "apiKey": { "id": "ak_5f8b...", "scopes": ["read:data"] } } }
POST /v1/api-keys/revoke
Revoke a key by its plaintext.
curl -X POST http://localhost:8787/v1/api-keys/revoke \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"key":"sk_live_3f9a2c8e..."}'
{ "data": { "id": "ak_5f8b...", "status": "revoked" } }
Coupons
/v1/coupons — Auth required. Discount engine. Discounts are one of:
{ "type": "percent", "percentOff": 1-100 },
{ "type": "amount", "amountOff": "5.00" }, or
{ "type": "free-trial-days", "days": 14 }.
POST /v1/coupons
| Field | Type | Required | Notes |
|---|---|---|---|
code |
string | yes | |
name |
string | no | |
discount |
object | yes | One of the discount shapes above. |
status |
"active" | "archived" |
no | |
startsAt |
datetime | no | |
expiresAt |
datetime | no | |
maxRedemptions |
integer ≥ 1 | no | |
perCustomerLimit |
integer ≥ 1 | no | |
minSubtotal |
string | no | |
appliesToProductIds |
string[] | no |
curl -X POST http://localhost:8787/v1/coupons \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"code":"LAUNCH20","discount":{"type":"percent","percentOff":20},"maxRedemptions":100}'
{ "data": { "code": "LAUNCH20", "discount": { "type": "percent", "percentOff": 20 }, "status": "active", "redemptionCount": 0 } }
GET /v1/coupons
curl http://localhost:8787/v1/coupons -H "Authorization: Bearer $SK_API_KEY"
GET /v1/coupons/:code
curl http://localhost:8787/v1/coupons/LAUNCH20 -H "Authorization: Bearer $SK_API_KEY"
POST /v1/coupons/:code/validate
Dry-run apply against a subtotal (does not change the redemption count).
| Field | Type | Required |
|---|---|---|
subtotal |
string | yes |
customerId |
string | no |
curl -X POST http://localhost:8787/v1/coupons/LAUNCH20/validate \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"subtotal":"100.00","customerId":"customer_9a3b..."}'
{ "data": { "valid": true, "discountAmount": { "amount": "20.00", "currency": "USDC" }, "total": { "amount": "80.00", "currency": "USDC" } } }
POST /v1/coupons/:code/redeem
Same body as validate, but increments the redemption count.
curl -X POST http://localhost:8787/v1/coupons/LAUNCH20/redeem \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"subtotal":"100.00","customerId":"customer_9a3b..."}'
{ "data": { "coupon": { "code": "LAUNCH20", "redemptionCount": 1 }, "total": { "amount": "80.00", "currency": "USDC" } } }
Access control: API key scopes and team roles
Management API keys are platform keys (issued at sign-up or with POST /v1/api-keys/platform). Access keys delivered to buyers by a product (api_key_create) can never call the management API, whatever scopes the product gives them (403).
Restricted keys: POST /v1/api-keys/platform with { "label": "Reporting job", "scopes": ["payments:read", "reports:read"] } returns the secret once. Scopes are <resource>:read or <resource>:write (write includes read) over products, checkout, payments, customers, invoices, webhooks, reports, settings, api_keys, team, agents, treasury and access (the verify endpoints); platform:admin is full access. A caller can only grant scopes it holds. A missing scope answers 403 with details.requiredScope. GET /v1/api-keys lists the organization's keys (kind: platform or customer) and POST /v1/api-keys/:id/revoke revokes one.
Team roles (dashboard sessions): owner and admin (full access; only an owner grants owner), developer (products, checkout, webhooks, API keys, invoices, agents; reads the rest), support (customers and payments; reads the rest except settings and keys), viewer (read only).
GET /v1/teamlists members and open invitations.POST /v1/team/invitationswith{ "email", "role" }emails a 7-day link to<DASHBOARD_PUBLIC_URL>/invite/<token>;POST /v1/team/invitations/:id/revokecancels it.PATCH /v1/team/members/:accountIdwith{ "role" }andDELETE /v1/team/members/:accountIdmanage members; the last owner cannot be removed or demoted.POST /v1/auth/invitations/accept(public) with{ "token", "password"? }joins the organization; new people set a password and get a session.
Growth metrics
GET /v1/analytics/metrics?days=30 (1-365) returns checkout conversion (sessions opened vs paid, invoices excluded), per-payment-link stats (opened, paid, conversion, revenue), window and all-time revenue, paying and repeat customers, average revenue per customer, and subscription churn, ARPU and an estimated lifetime value (ARPU divided by monthly churn; null while nothing has churned).
Hosted storefront
POST /v1/settings with store: { enabled, slug, title?, tagline?, logoUrl? (https), accentColor? (#rrggbb), seoDescription?, customDomain? } publishes a branded page at <checkout>/store/<slug> listing the merchant's active products; each opens its payment link. Slugs and domains are unique across merchants. Public data: GET /v1/public/stores/:slug and GET /v1/public/stores/by-domain/:domain. For a custom domain, point it at the checkout host, have the host (Railyard or Caddy) route it, and set CHECKOUT_PRIMARY_HOSTS on the checkout app so requests for / on any other host show that domain's store. Checkout still buys one product per checkout session.
Cash out to a bank
GET /v1/merchant/offramp?network=base&amount=250 returns off-ramp partner links (Transak, MoonPay, Ramp) that open the partner's sell flow with the amount, network and the merchant's own receiving wallet prefilled. SettleKit takes no custody; the merchant sends USDC from their wallet inside the partner flow. Partners appear only when their keys are configured (TRANSAK_API_KEY, MOONPAY_PUBLISHABLE_KEY + MOONPAY_SECRET_KEY, RAMP_HOST_API_KEY); MoonPay URLs are signed server-side.
Refund to payer
Refunds are sent from the merchant's own wallet; SettleKit never holds or signs funds.
POST /v1/merchant/payments/:id/refund/preparewith{ "reason", "amountUsd"?, "to"? }creates a pending refund and returns the exact transfer to sign: on EVM networks the ERC-20transfercalldata, token, chain id and an EIP-681 link; on Solana a Solana Pay transfer request with a unique reference. The destination defaults to the wallet that paid (declared payer or customer wallet); otherwise passto. The amount defaults to what is still refundable.POST /v1/merchant/refunds/:id/confirmwith{ "txHash", "revokeAccess"? }verifies the transfer onchain (destination, amount, not before the refund, Solana reference) with the payment verifiers. Only then is the refund marked succeeded, access revoked, the payment marked refunded once fully refunded, andrefund.succeededsent withsource: "wallet". A transaction can settle one refund only.POST /v1/merchant/refunds/:id/canceldrops a pending refund.
HyperCore and Zcash refunds stay record-only (POST /v1/merchant/payments/:id/refund with the transaction hash). The vendored apps/refund-protocol escrow is not wired (known arbiter issue upstream).
Accounting exports
/v1/exports — Auth required. Tenant-scoped CSV downloads. Optional ?from=YYYY-MM-DD&to=YYYY-MM-DD (to is exclusive). Every text cell is guarded against spreadsheet formula injection.
GET /v1/exports/payments.csv,refunds.csv,invoices.csv,payouts.csv: one row per record.GET /v1/exports/ledger.csv: every USDC wallet movement (payments in, succeeded refunds out) with network and transaction hash.GET /v1/exports/xero.csv: Xero bank statement import (*Dateas DD/MM/YYYY,*Amount, Payee, Description, Reference). In Xero, create a bank account named "USDC wallet", then use Import a statement.GET /v1/exports/quickbooks.csv: QuickBooks Online bank upload, three columns (Date as MM/DD/YYYY, Description, Amount). In QuickBooks, go to Banking, Upload transactions, and pick the USDC account.
The dashboard links all of them from the Payments page.
Platform fee statements
/v1/billing — Auth required. SettleKit's per-payment fee is billed once a month. When PLATFORM_BILLING_ORG_ID is set, the API issues each merchant a statement for the previous month (confirmed payments x the fee schedule) as an invoice from the platform org, paid through the hosted checkout like any invoice. Totals below PLATFORM_BILLING_MIN_USD roll into the next month. A statement left unpaid past its due date plus PLATFORM_BILLING_GRACE_DAYS limits new products to the free plan until it is paid (402 payment_required with the pay link).
GET /v1/billing/feesreturns the schedule, standing (good,due,past_due,restricted), fees accrued since the last statement and every statement with its pay link.POST /v1/billing/statements/runwith{ "period": "YYYY-MM" }(default: last month) issues statements for every merchant. Platform operator only (the platform org or the bootstrap key). The API also runs this every six hours unlessPLATFORM_BILLING_AUTORUN=0.
Invoices
/v1/invoices — Auth required. Lifecycle: draft → open → paid (or void).
POST /v1/invoices
| Field | Type | Required | Notes |
|---|---|---|---|
organizationId |
string | yes | |
customerId |
string | yes | |
lineItems |
array | no | Each: { description, quantity (≥1), unitAmount }. |
discount |
string | no | |
taxRate |
object | no | { jurisdiction, rateBps (0-10000), inclusive? }. |
dueAt |
datetime | no | |
metadata |
object<string,string> | no |
curl -X POST http://localhost:8787/v1/invoices \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{
"organizationId":"org_1","customerId":"customer_9a3b...",
"lineItems":[{"description":"Pro plan","quantity":1,"unitAmount":"19.99"}],
"taxRate":{"jurisdiction":"US-CA","rateBps":875}
}'
{
"data": {
"id": "inv_3c7d...",
"status": "draft",
"customerId": "customer_9a3b...",
"lineItems": [ { "description": "Pro plan", "quantity": 1, "unitAmount": { "amount": "19.99", "currency": "USDC" } } ],
"total": { "amount": "21.74", "currency": "USDC" }
}
}
GET /v1/invoices
| Query param | Type | Required |
|---|---|---|
customerId |
string | no |
curl "http://localhost:8787/v1/invoices?customerId=customer_9a3b..." -H "Authorization: Bearer $SK_API_KEY"
GET /v1/invoices/:id
curl http://localhost:8787/v1/invoices/inv_3c7d... -H "Authorization: Bearer $SK_API_KEY"
GET /v1/invoices/:id.html
Render the styled HTML invoice. Returns text/html (not an enveloped JSON body).
curl http://localhost:8787/v1/invoices/inv_3c7d....html -H "Authorization: Bearer $SK_API_KEY"
POST /v1/invoices/:id/finalize
draft → open.
curl -X POST http://localhost:8787/v1/invoices/inv_3c7d.../finalize -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "inv_3c7d...", "status": "open" } }
POST /v1/invoices/:id/pay
open → paid.
curl -X POST http://localhost:8787/v1/invoices/inv_3c7d.../pay -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "inv_3c7d...", "status": "paid" } }
POST /v1/invoices/:id/void
draft|open → void.
curl -X POST http://localhost:8787/v1/invoices/inv_3c7d.../void -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "inv_3c7d...", "status": "void" } }
Voiding also cancels any open checkout session of the invoice, so an old pay link can no longer be paid.
POST /v1/invoices/:id/send
Make an invoice payable onchain. Finalizes a draft, binds a public pay page (<CHECKOUT_PUBLIC_URL>/i/<token>), opens a checkout session for the invoice total on the merchant's accepted networks, and emails the link (when RESEND_API_KEY is set). Idempotent: re-sending keeps the same link. Requires a receiving wallet in payment settings.
curl -X POST http://localhost:8787/v1/invoices/inv_3c7d.../send \
-H "Authorization: Bearer $SK_API_KEY" -H "content-type: application/json" \
-d '{"payerEmail":"billing@client.com"}'
{ "data": { "invoice": { "status": "open", "metadata": { "payToken": "..." } }, "payUrl": "https://pay.example.com/i/...", "checkoutSessionId": "cs_...", "emailedTo": "billing@client.com" } }
The invoice turns paid by itself once a confirmed onchain payment exists for one of its checkout sessions (checked on every read and by the worker's invoice-settle job), and an invoice.paid webhook is queued.
POST /v1/invoices/requests
An ad-hoc payment request: one amount and memo, sent immediately. A customer is created for the payer email on first use.
curl -X POST http://localhost:8787/v1/invoices/requests \
-H "Authorization: Bearer $SK_API_KEY" -H "content-type: application/json" \
-d '{"amount":"250.00","description":"Website redesign, deposit","payerEmail":"billing@client.com"}'
GET /v1/invoices/:id.pdf
The invoice as a PDF (a receipt with the settlement transaction once paid).
Public invoice routes (no API key)
The pay token is the capability.
GET /v1/public/invoices/:tokenreturns the buyer-safe invoice view (line items, totals, status,payable).POST /v1/public/invoices/:token/sessionsreturns the open checkout session id (reused while payable, re-opened when expired).GET /v1/public/invoices/:token/pdfreturns the PDF.
Refunds
/v1/refunds — Auth required. Creation looks up the backing payment by
paymentId to validate the refundable remaining amount.
POST /v1/refunds
| Field | Type | Required | Notes |
|---|---|---|---|
paymentId |
string | yes | Must reference an existing payment. |
customerId |
string | yes | |
amount |
string | yes | |
reason |
duplicate | fraudulent | customer_request | delivery_failed |
yes | |
originalAmount |
string | no | Hint only; the backing payment is authoritative. |
curl -X POST http://localhost:8787/v1/refunds \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"paymentId":"pay_4c9d...","customerId":"customer_9a3b...","amount":"19.99","reason":"customer_request"}'
{ "data": { "id": "ref_9d2e...", "paymentId": "pay_4c9d...", "amount": { "amount": "19.99", "currency": "USDC" }, "reason": "customer_request", "status": "pending" } }
404 not_found when paymentId is unknown.
GET /v1/refunds
List by paymentId or customerId; with neither, lists all.
| Query param | Type | Required |
|---|---|---|
paymentId |
string | no |
customerId |
string | no |
curl "http://localhost:8787/v1/refunds?paymentId=pay_4c9d..." -H "Authorization: Bearer $SK_API_KEY"
POST /v1/refunds/:id/succeed
pending → succeeded.
curl -X POST http://localhost:8787/v1/refunds/ref_9d2e.../succeed -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "ref_9d2e...", "status": "succeeded" } }
POST /v1/refunds/:id/fail
pending → failed.
| Field | Type | Required |
|---|---|---|
reason |
string | no |
curl -X POST http://localhost:8787/v1/refunds/ref_9d2e.../fail \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"reason":"insufficient liquidity"}'
{ "data": { "id": "ref_9d2e...", "status": "failed" } }
Dunning
/v1/dunning — Auth required. Failed-payment recovery campaigns keyed by
subscription.
POST /v1/dunning
Start a campaign for a subscription.
| Field | Type | Required |
|---|---|---|
subscriptionId |
string | yes |
curl -X POST http://localhost:8787/v1/dunning \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"subscriptionId":"sub_6e1a..."}'
{ "data": { "subscriptionId": "sub_6e1a...", "status": "active", "attempts": 0 } }
GET /v1/dunning
List active campaigns, or only those due for retry with ?due=true (or ?due=1).
curl "http://localhost:8787/v1/dunning?due=true" -H "Authorization: Bearer $SK_API_KEY"
POST /v1/dunning/:subscriptionId/attempt
Record a retry attempt outcome. recovered closes the campaign; failed
advances or exhausts it.
| Field | Type | Required |
|---|---|---|
outcome |
"recovered" | "failed" |
yes |
failureReason |
string | no |
curl -X POST http://localhost:8787/v1/dunning/sub_6e1a.../attempt \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"outcome":"failed","failureReason":"insufficient funds"}'
{ "data": { "subscriptionId": "sub_6e1a...", "status": "active", "attempts": 1 } }
POST /v1/dunning/:subscriptionId/recover
Mark a campaign recovered.
curl -X POST http://localhost:8787/v1/dunning/sub_6e1a.../recover -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "subscriptionId": "sub_6e1a...", "status": "recovered" } }
Disputes
/v1/disputes — Auth required. Chargeback / dispute engine.
POST /v1/disputes
Open a dispute.
| Field | Type | Required |
|---|---|---|
paymentId |
string | yes |
customerId |
string | yes |
reason |
fraud | not_received | duplicate | quality | unrecognized |
yes |
curl -X POST http://localhost:8787/v1/disputes \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"paymentId":"pay_4c9d...","customerId":"customer_9a3b...","reason":"not_received"}'
{ "data": { "id": "dsp_1f4a...", "paymentId": "pay_4c9d...", "reason": "not_received", "status": "open" } }
GET /v1/disputes
List disputes. ?status=open or ?status=under_review returns open disputes;
any other status filters the full list; no status returns all.
curl "http://localhost:8787/v1/disputes?status=open" -H "Authorization: Bearer $SK_API_KEY"
GET /v1/disputes/:id
curl http://localhost:8787/v1/disputes/dsp_1f4a... -H "Authorization: Bearer $SK_API_KEY"
POST /v1/disputes/:id/evidence
Attach evidence (moves the dispute to under_review).
| Field | Type | Required |
|---|---|---|
kind |
text | receipt | shipping | communication | url | file |
yes |
description |
string | yes |
value |
string | yes |
curl -X POST http://localhost:8787/v1/disputes/dsp_1f4a.../evidence \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"kind":"text","description":"Delivery log","value":"Repo invite accepted 2026-06-16"}'
{ "data": { "id": "dsp_1f4a...", "status": "under_review", "evidence": [ { "kind": "text" } ] } }
POST /v1/disputes/:id/resolve
| Field | Type | Required |
|---|---|---|
outcome |
won | lost | refunded |
yes |
curl -X POST http://localhost:8787/v1/disputes/dsp_1f4a.../resolve \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"outcome":"won"}'
{ "data": { "id": "dsp_1f4a...", "status": "won" } }
Payouts
/v1/payouts — Auth required. Merchant settlement. Available balance is
computed from the org's confirmed payments minus prior (pending or paid)
payouts.
POST /v1/payouts
| Field | Type | Required |
|---|---|---|
organizationId |
string | yes |
walletAddress |
string | yes |
amount |
string | yes |
network |
arc | base | ethereum |
yes |
curl -X POST http://localhost:8787/v1/payouts \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"organizationId":"org_1","walletAddress":"0xMerchantWallet","amount":"500.00","network":"arc"}'
{ "data": { "id": "po_8a2c...", "organizationId": "org_1", "amount": { "amount": "500.00", "currency": "USDC" }, "network": "arc", "status": "pending" } }
GET /v1/payouts
List payouts. With ?organizationId= filters to one org; without it, lists all.
curl "http://localhost:8787/v1/payouts?organizationId=org_1" -H "Authorization: Bearer $SK_API_KEY"
GET /v1/payouts/balance
Available balance for an org.
| Query param | Type | Required |
|---|---|---|
organizationId |
string | yes |
curl "http://localhost:8787/v1/payouts/balance?organizationId=org_1" -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "available": { "amount": "1250.00", "currency": "USDC" } } }
POST /v1/payouts/:id/paid
Mark paid with an on-chain txHash.
curl -X POST http://localhost:8787/v1/payouts/po_8a2c.../paid \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"txHash":"0xpayout..."}'
{ "data": { "id": "po_8a2c...", "status": "paid", "txHash": "0xpayout..." } }
POST /v1/payouts/:id/fail
| Field | Type | Required |
|---|---|---|
reason |
string | no |
curl -X POST http://localhost:8787/v1/payouts/po_8a2c.../fail \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"reason":"address rejected"}'
{ "data": { "id": "po_8a2c...", "status": "failed" } }
Bundles
/v1/bundles — Auth required. Group multiple products into one purchasable
bundle. Validation (non-empty, no duplicates/cycles, all products exist) runs in
the service.
POST /v1/bundles
| Field | Type | Required | Notes |
|---|---|---|---|
merchantId |
string | yes | |
organizationId |
string | yes | |
name |
string | yes | |
description |
string | no | |
productIds |
string[] | yes (min 1) | |
amount |
string | no | Bundle price; when omitted, member prices default. |
interval |
one_time | monthly | yearly |
no |
curl -X POST http://localhost:8787/v1/bundles \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"merchantId":"acct_01H...","organizationId":"org_1","name":"Starter Pack","productIds":["prod_5d2c...","prod_8e1f..."],"amount":"49.00"}'
{ "data": { "id": "bndl_4f2a...", "name": "Starter Pack", "productIds": ["prod_5d2c...","prod_8e1f..."], "status": "draft" } }
GET /v1/bundles
With ?organizationId= filters to one org.
curl "http://localhost:8787/v1/bundles?organizationId=org_1" -H "Authorization: Bearer $SK_API_KEY"
GET /v1/bundles/:id
curl http://localhost:8787/v1/bundles/bndl_4f2a... -H "Authorization: Bearer $SK_API_KEY"
PATCH /v1/bundles/:id
Patch mutable fields. Setting status to archived archives the bundle.
| Field | Type | Required |
|---|---|---|
name |
string | no |
description |
string | no |
status |
draft | active | archived |
no |
curl -X PATCH http://localhost:8787/v1/bundles/bndl_4f2a... \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"name":"Starter Pack 2026"}'
{ "data": { "id": "bndl_4f2a...", "name": "Starter Pack 2026", "status": "draft" } }
POST /v1/bundles/:id/publish
curl -X POST http://localhost:8787/v1/bundles/bndl_4f2a.../publish -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "bndl_4f2a...", "status": "active" } }
Agent Services
/v1/agent-services — Auth required. Listings for AI/agent tools that other
agents can discover and pay for.
POST /v1/agent-services
| Field | Type | Required | Default |
|---|---|---|---|
organizationId |
string | yes | |
merchantId |
string | yes | |
productId |
string | yes | |
name |
string | yes | |
description |
string | yes | |
endpoint |
string (url) | yes | |
price |
string | yes | |
network |
arc | base |
no | base |
inputSchema |
object | yes | |
outputSchema |
object | no |
curl -X POST http://localhost:8787/v1/agent-services \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{
"organizationId":"org_1","merchantId":"acct_01H...","productId":"prod_ai...",
"name":"Summarizer","description":"Summarize text","endpoint":"https://api.acme.dev/sum",
"price":"0.01","inputSchema":{"text":"string"}
}'
{ "data": { "id": "agsvc_2c8d...", "name": "Summarizer", "endpoint": "https://api.acme.dev/sum", "price": "0.01", "network": "base", "status": "draft" } }
GET /v1/agent-services
Discover services. With ?organizationId= filters to one org.
curl "http://localhost:8787/v1/agent-services?organizationId=org_1" -H "Authorization: Bearer $SK_API_KEY"
GET /v1/agent-services/:id
curl http://localhost:8787/v1/agent-services/agsvc_2c8d... -H "Authorization: Bearer $SK_API_KEY"
PATCH /v1/agent-services/:id
| Field | Type | Required |
|---|---|---|
name |
string | no |
description |
string | no |
endpoint |
string (url) | no |
price |
string | no |
curl -X PATCH http://localhost:8787/v1/agent-services/agsvc_2c8d... \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"price":"0.02"}'
POST /v1/agent-services/:id/publish
curl -X POST http://localhost:8787/v1/agent-services/agsvc_2c8d.../publish -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "agsvc_2c8d...", "status": "active" } }
GET /v1/agent-services/:id/metadata.json
Machine-readable metadata document. Returned as raw JSON (not wrapped in a
data envelope) so agents can consume it directly.
curl http://localhost:8787/v1/agent-services/agsvc_2c8d.../metadata.json \
-H "Authorization: Bearer $SK_API_KEY"
{
"name": "Summarizer",
"description": "Summarize text",
"endpoint": "https://api.acme.dev/sum",
"price": { "amount": "0.02", "currency": "USDC", "network": "base" },
"inputSchema": { "text": "string" }
}
Marketplace
/v1/marketplace — Auth required. Public product listings + discovery and
seller profiles.
POST /v1/marketplace/listings
Create an (unpublished) listing.
| Field | Type | Required | Default |
|---|---|---|---|
organizationId |
string | yes | |
merchantId |
string | yes | |
productId |
string | yes | |
title |
string | yes | |
summary |
string | yes | |
tags |
string[] | no | [] |
curl -X POST http://localhost:8787/v1/marketplace/listings \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"organizationId":"org_1","merchantId":"acct_01H...","productId":"prod_5d2c...","title":"Pro Repo","summary":"Private repo access","tags":["devtools"]}'
{ "data": { "id": "lst_7d3a...", "title": "Pro Repo", "tags": ["devtools"], "status": "draft", "ratingAvg": 0, "ratingCount": 0 } }
GET /v1/marketplace/listings
Search published listings. Query params: q (text), tag, sort
(top | new | price).
curl "http://localhost:8787/v1/marketplace/listings?q=repo&tag=devtools&sort=top" \
-H "Authorization: Bearer $SK_API_KEY"
{ "data": [ { "id": "lst_7d3a...", "title": "Pro Repo", "ratingAvg": 4.5 } ] }
GET /v1/marketplace/listings/:id
curl http://localhost:8787/v1/marketplace/listings/lst_7d3a... -H "Authorization: Bearer $SK_API_KEY"
POST /v1/marketplace/listings/:id/publish
curl -X POST http://localhost:8787/v1/marketplace/listings/lst_7d3a.../publish -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "lst_7d3a...", "status": "published" } }
POST /v1/marketplace/listings/:id/unpublish
curl -X POST http://localhost:8787/v1/marketplace/listings/lst_7d3a.../unpublish -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "lst_7d3a...", "status": "draft" } }
POST /v1/marketplace/listings/:id/rate
| Field | Type | Required |
|---|---|---|
stars |
integer 1-5 | yes |
curl -X POST http://localhost:8787/v1/marketplace/listings/lst_7d3a.../rate \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"stars":5}'
{ "data": { "id": "lst_7d3a...", "ratingAvg": 4.7, "ratingCount": 11 } }
GET /v1/marketplace/sellers/:merchantId
Aggregate seller profile.
curl http://localhost:8787/v1/marketplace/sellers/acct_01H... -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "merchantId": "acct_01H...", "listings": 3, "ratingAvg": 4.6 } }
Usage & Credits
/v1/usage — Auth required. Metering + prepaid credits. A meter is
identified by { organizationId, customerId, productId, metric }. A credit
balance is identified by { organizationId, customerId, productId }. Optional
periodStart (ISO datetime) selects the metering period; it defaults to now.
POST /v1/usage/record
Record N units of a metric (creates the meter on first use).
| Field | Type | Required | Default |
|---|---|---|---|
organizationId |
string | yes | |
customerId |
string | yes | |
productId |
string | yes | |
metric |
string | yes | |
quantity |
integer ≥ 1 | no | 1 |
periodStart |
datetime | no | now |
curl -X POST http://localhost:8787/v1/usage/record \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"organizationId":"org_1","customerId":"customer_9a3b...","productId":"prod_api...","metric":"api_calls","quantity":5}'
{ "data": { "metric": "api_calls", "quantity": 5, "periodStart": "2026-06-16T00:00:00.000Z" } }
GET /v1/usage/meter
Read the current meter. Query params: organizationId, customerId,
productId, metric (all required), periodStart (optional).
curl "http://localhost:8787/v1/usage/meter?organizationId=org_1&customerId=customer_9a3b...&productId=prod_api...&metric=api_calls" \
-H "Authorization: Bearer $SK_API_KEY"
{ "data": { "metric": "api_calls", "quantity": 5 } }
POST /v1/usage/charge
Compute the charge for a meter's usage at a unit price.
| Field | Type | Required |
|---|---|---|
| (meter ref fields) | yes | |
unitAmount |
string | yes |
periodStart |
datetime | no |
curl -X POST http://localhost:8787/v1/usage/charge \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"organizationId":"org_1","customerId":"customer_9a3b...","productId":"prod_api...","metric":"api_calls","unitAmount":"0.001"}'
{ "data": { "quantity": 5, "unitAmount": { "amount": "0.001", "currency": "USDC" }, "total": { "amount": "0.005", "currency": "USDC" } } }
POST /v1/usage/limit
Evaluate usage against a hard limit.
| Field | Type | Required |
|---|---|---|
| (meter ref fields) | yes | |
limit |
integer ≥ 0 | yes |
periodStart |
datetime | no |
curl -X POST http://localhost:8787/v1/usage/limit \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"organizationId":"org_1","customerId":"customer_9a3b...","productId":"prod_api...","metric":"api_calls","limit":1000}'
{ "data": { "used": 5, "limit": 1000, "withinLimit": true } }
GET /v1/usage/credits
Read a prepaid balance. Query params: organizationId, customerId,
productId (all required).
curl "http://localhost:8787/v1/usage/credits?organizationId=org_1&customerId=customer_9a3b...&productId=prod_api..." \
-H "Authorization: Bearer $SK_API_KEY"
{ "data": { "credits": 100 } }
POST /v1/usage/credits/grant
Grant prepaid credits.
| Field | Type | Required |
|---|---|---|
organizationId |
string | yes |
customerId |
string | yes |
productId |
string | yes |
credits |
integer ≥ 1 | yes |
curl -X POST http://localhost:8787/v1/usage/credits/grant \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"organizationId":"org_1","customerId":"customer_9a3b...","productId":"prod_api...","credits":100}'
{ "data": { "credits": 100 } }
POST /v1/usage/credits/consume
Consume prepaid credits (e.g. meter a paid API call).
| Field | Type | Required | Default |
|---|---|---|---|
organizationId |
string | yes | |
customerId |
string | yes | |
productId |
string | yes | |
credits |
integer ≥ 1 | no | 1 |
curl -X POST http://localhost:8787/v1/usage/credits/consume \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"organizationId":"org_1","customerId":"customer_9a3b...","productId":"prod_api...","credits":1}'
{ "data": { "credits": 99 } }
Consuming more than the balance returns 402 insufficient_credits.
Analytics
/v1/analytics — Auth required.
GET /v1/analytics/summary
Merchant dashboard summary computed live from the stores. Query param
organizationId (defaults to the platform's default org when omitted).
Fields: revenue (sum of confirmed payments), revenueSeries (14-day daily
totals), customers (count), activeAccess (active entitlements), mrr
(normalized monthly recurring revenue), expiringSubscriptions (in grace or
ending within 7 days), failedDeliveries (failed/partially-failed runs).
curl "http://localhost:8787/v1/analytics/summary?organizationId=org_1" \
-H "Authorization: Bearer $SK_API_KEY"
{
"data": {
"revenue": { "amount": "1250.00", "currency": "USDC" },
"customers": 42,
"activeAccess": 38,
"expiringSubscriptions": 3,
"failedDeliveries": 1,
"mrr": { "amount": "640.00", "currency": "USDC" },
"revenueSeries": [ { "date": "2026-06-03", "amount": 0 }, { "date": "2026-06-16", "amount": 120 } ]
}
}
Settings
/v1/settings — Auth required. Editable organization config; unknown keys
are ignored and provided keys are merged over current.
GET /v1/settings
Query param organizationId (defaults to the platform default org).
curl "http://localhost:8787/v1/settings?organizationId=org_1" -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "organizationId": "org_1", "orgName": "Acme", "payoutCurrency": "USDC", "defaultRail": "arc" } }
POST /v1/settings
Patch settings.
| Field | Type | Required |
|---|---|---|
organizationId |
string | no |
orgName |
string | no |
supportEmail |
string | no |
payoutCurrency |
string | no |
webhookSecret |
string | no |
defaultRail |
arc | circle | x402 |
no |
curl -X POST http://localhost:8787/v1/settings \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"organizationId":"org_1","orgName":"Acme Inc","defaultRail":"arc"}'
{ "data": { "organizationId": "org_1", "orgName": "Acme Inc", "defaultRail": "arc" } }
Escrow
/v1/escrow — Auth required. Milestone escrow for agent/consulting work.
Lifecycle: create → fund → assign → submit → approve → release (or refund;
dispute also available).
POST /v1/escrow/tasks
| Field | Type | Required | Default |
|---|---|---|---|
organizationId |
string | yes | |
buyerCustomerId |
string | yes | |
title |
string | yes | |
description |
string | yes | |
amount |
string | yes | |
currency |
"USDC" |
no | "USDC" |
curl -X POST http://localhost:8787/v1/escrow/tasks \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"organizationId":"org_1","buyerCustomerId":"customer_9a3b...","title":"Build landing page","description":"Next.js marketing site","amount":"500.00"}'
{ "data": { "id": "esc_3a9c...", "title": "Build landing page", "amount": { "amount": "500.00", "currency": "USDC" }, "status": "created" } }
GET /v1/escrow/tasks
List tasks for an org. Query param organizationId is required.
curl "http://localhost:8787/v1/escrow/tasks?organizationId=org_1" -H "Authorization: Bearer $SK_API_KEY"
GET /v1/escrow/tasks/:id
curl http://localhost:8787/v1/escrow/tasks/esc_3a9c... -H "Authorization: Bearer $SK_API_KEY"
POST /v1/escrow/tasks/:id/fund
| Field | Type | Required |
|---|---|---|
fundingTxHash |
string | yes |
curl -X POST http://localhost:8787/v1/escrow/tasks/esc_3a9c.../fund \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"fundingTxHash":"0xfund..."}'
{ "data": { "id": "esc_3a9c...", "status": "funded", "fundingTxHash": "0xfund..." } }
POST /v1/escrow/tasks/:id/assign
| Field | Type | Required |
|---|---|---|
workerCustomerId |
string | yes |
curl -X POST http://localhost:8787/v1/escrow/tasks/esc_3a9c.../assign \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"workerCustomerId":"customer_worker..."}'
{ "data": { "id": "esc_3a9c...", "status": "assigned", "workerCustomerId": "customer_worker..." } }
POST /v1/escrow/tasks/:id/submit
| Field | Type | Required |
|---|---|---|
content |
string | yes |
curl -X POST http://localhost:8787/v1/escrow/tasks/esc_3a9c.../submit \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"content":"https://github.com/acme/site/pull/1"}'
{ "data": { "id": "esc_3a9c...", "status": "submitted" } }
POST /v1/escrow/tasks/:id/approve
No body.
curl -X POST http://localhost:8787/v1/escrow/tasks/esc_3a9c.../approve -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "esc_3a9c...", "status": "approved" } }
POST /v1/escrow/tasks/:id/release
| Field | Type | Required |
|---|---|---|
releaseTxHash |
string | yes |
curl -X POST http://localhost:8787/v1/escrow/tasks/esc_3a9c.../release \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"releaseTxHash":"0xrelease..."}'
{ "data": { "id": "esc_3a9c...", "status": "released", "releaseTxHash": "0xrelease..." } }
POST /v1/escrow/tasks/:id/refund
| Field | Type | Required | Default |
|---|---|---|---|
reason |
string | no | "refunded via API" |
curl -X POST http://localhost:8787/v1/escrow/tasks/esc_3a9c.../refund \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"reason":"scope canceled"}'
{ "data": { "id": "esc_3a9c...", "status": "refunded" } }
Webhooks
/v1/webhooks — Auth required. Register endpoints and emit signed events.
Event types: payment.confirmed, payment.failed, payment.refunded,
subscription.created, subscription.renewed, subscription.canceled,
entitlement.granted, entitlement.revoked, delivery.succeeded,
delivery.failed.
POST /v1/webhooks/endpoints
Register an endpoint with a freshly-minted signing secret (returned once).
| Field | Type | Required |
|---|---|---|
organizationId |
string | yes |
url |
string (url) | yes |
enabledEvents |
event-type[] | yes (min 1) |
curl -X POST http://localhost:8787/v1/webhooks/endpoints \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"organizationId":"org_1","url":"https://acme.dev/hooks","enabledEvents":["payment.confirmed","entitlement.granted"]}'
{
"data": {
"id": "whe_5b1c...",
"organizationId": "org_1",
"url": "https://acme.dev/hooks",
"signingSecret": "whsec_8f2a...",
"enabledEvents": ["payment.confirmed","entitlement.granted"],
"active": true,
"createdAt": "2026-06-16T12:00:00.000Z"
}
}
GET /v1/webhooks/endpoints
With ?organizationId= filters to one org.
curl "http://localhost:8787/v1/webhooks/endpoints?organizationId=org_1" -H "Authorization: Bearer $SK_API_KEY"
POST /v1/webhooks/events
Emit an event: persist it and return the signed payload + signature for each matching active endpoint. The signature is computed over the serialized event with a unix timestamp — exactly what a receiver verifies.
| Field | Type | Required | Default |
|---|---|---|---|
organizationId |
string | yes | |
type |
event type | yes | |
data |
object | no | {} |
curl -X POST http://localhost:8787/v1/webhooks/events \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"organizationId":"org_1","type":"payment.confirmed","data":{"paymentId":"pay_4c9d..."}}'
{
"data": {
"event": {
"id": "evt_9d4a...",
"type": "payment.confirmed",
"organizationId": "org_1",
"data": { "paymentId": "pay_4c9d..." },
"createdAt": "2026-06-16T12:00:00.000Z"
},
"deliveries": [
{ "endpointId": "whe_5b1c...", "url": "https://acme.dev/hooks", "signature": "t=1718539200,v1=ab12cd..." }
]
}
}
GET /v1/webhooks/events
With ?organizationId= filters to one org.
curl "http://localhost:8787/v1/webhooks/events?organizationId=org_1" -H "Authorization: Bearer $SK_API_KEY"
GET /v1/webhooks/events/:id
curl http://localhost:8787/v1/webhooks/events/evt_9d4a... -H "Authorization: Bearer $SK_API_KEY"
Files
/v1/files — Auth required. HMAC-signed, usage-limited download URLs.
POST /v1/files/downloads
Issue a signed download URL + grant.
| Field | Type | Required |
|---|---|---|
fileId |
string | yes |
customerId |
string | yes |
expiresInSec |
integer > 0 | no |
maxDownloads |
integer > 0 | no |
curl -X POST http://localhost:8787/v1/files/downloads \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"fileId":"file_7a2b...","customerId":"customer_9a3b...","expiresInSec":3600,"maxDownloads":3}'
{
"data": {
"url": "https://downloads.acme.dev/file_7a2b...?exp=1718542800&sig=ab12...",
"grant": { "fileId": "file_7a2b...", "customerId": "customer_9a3b...", "maxDownloads": 3, "downloadsUsed": 0 }
}
}
GET /v1/files/download
Redeem a signed download URL. The full signed URL is passed as the url query
param; the server verifies the signature/expiry and atomically consumes one
download.
| Query param | Type | Required |
|---|---|---|
url |
string | yes |
curl "http://localhost:8787/v1/files/download?url=https%3A%2F%2Fdownloads.acme.dev%2Ffile_7a2b...%3Fexp%3D1718542800%26sig%3Dab12..." \
-H "Authorization: Bearer $SK_API_KEY"
{ "data": { "fileId": "file_7a2b...", "downloadsRemaining": 2 } }
A missing url returns 400 validation_error; an invalid/expired URL is
rejected by the signed-URL verifier.
Delivery Runs & Actions
Auth required. Inspect delivery runs and test individual delivery action handlers.
GET /v1/delivery-runs
List runs. Optional query params organizationId and paymentId filter.
curl "http://localhost:8787/v1/delivery-runs?organizationId=org_1&paymentId=pay_4c9d..." \
-H "Authorization: Bearer $SK_API_KEY"
{ "data": [ { "id": "dr_4f8a...", "paymentId": "pay_4c9d...", "status": "succeeded", "actionRuns": [] } ] }
GET /v1/delivery-runs/:id
curl http://localhost:8787/v1/delivery-runs/dr_4f8a... -H "Authorization: Bearer $SK_API_KEY"
POST /v1/delivery-runs/:id/retry
Re-run the failed actions of a run by marking them pending again.
curl -X POST http://localhost:8787/v1/delivery-runs/dr_4f8a.../retry -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "dr_4f8a...", "status": "pending", "actionRuns": [ { "status": "pending", "attempts": 1 } ] } }
POST /v1/delivery-actions/test
Execute a single delivery action through the real handler registry + in-process clients, returning the handler's actual output.
Context fields (all optional, with defaults): organizationId (org_test),
customerId (cus_test), productId (prod_test), paymentId (pay_test),
entitlementId (ent_test), customerEmail, githubInstallationId,
githubUsername, discordUserId.
action is a discriminated union on type:
type |
Additional fields |
|---|---|
github_invite |
repoId, permission? (pull/push/maintain) |
github_team_add |
orgLogin, teamSlug |
license_key_create |
policyId |
api_key_create |
scopes (string[], min 1) |
file_access_grant |
fileId |
discord_role_add |
guildId, roleId |
saas_entitlement_create |
features (object<string, boolean|number|string>) |
webhook_send |
url |
email_send |
template |
curl -X POST http://localhost:8787/v1/delivery-actions/test \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{
"githubInstallationId":12345,"githubUsername":"octocat",
"action":{"type":"github_invite","repoId":"acme/private-repo","permission":"push"}
}'
{
"data": {
"action": { "type": "github_invite", "repoId": "acme/private-repo", "permission": "push" },
"status": "succeeded",
"output": { "invited": "octocat", "repo": "acme/private-repo", "permission": "push" }
}
}
An unknown action type returns 404 not_found; a handler failure surfaces the
handler's own error, otherwise 400 validation_error.
SaaS
/v1/saas — Auth required. Plans, feature-bearing tenant entitlements,
feature verification, and seat management.
POST /v1/saas/plans
| Field | Type | Required | Default |
|---|---|---|---|
productId |
string | yes | |
name |
string | yes | |
interval |
monthly | yearly |
no | monthly |
amount |
string | yes | |
features |
object<string, boolean|number> | no | {} |
seats |
integer ≥ 0 | no | 1 |
curl -X POST http://localhost:8787/v1/saas/plans \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"productId":"prod_saas...","name":"Team","amount":"99.00","features":{"sso":true,"seats":10},"seats":10}'
{ "data": { "id": "plan_2c8e...", "name": "Team", "interval": "monthly", "price": { "amount": "99.00", "currency": "USDC" }, "features": { "sso": true, "seats": 10 }, "seats": 10 } }
GET /v1/saas/plans
With ?productId= filters to one product.
curl "http://localhost:8787/v1/saas/plans?productId=prod_saas..." -H "Authorization: Bearer $SK_API_KEY"
POST /v1/saas/features
Grant a feature-bearing tenant entitlement from a plan.
| Field | Type | Required | Default |
|---|---|---|---|
organizationId |
string | yes | |
customerId |
string | yes | |
planId |
string | yes | |
grantedById |
string | yes | |
grantedByType |
payment | subscription | bundle | manual |
no | subscription |
expiresAt |
datetime | no |
curl -X POST http://localhost:8787/v1/saas/features \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"organizationId":"org_1","customerId":"customer_9a3b...","planId":"plan_2c8e...","grantedById":"sub_6e1a..."}'
{ "data": { "id": "tent_4a1c...", "planId": "plan_2c8e...", "features": { "sso": true, "seats": 10 }, "status": "active" } }
POST /v1/saas/entitlements/verify
Check a feature flag/limit on a freshly-built tenant entitlement.
| Field | Type | Required |
|---|---|---|
planId |
string | yes |
organizationId |
string | yes |
customerId |
string | yes |
grantedById |
string | yes |
feature |
string | yes |
curl -X POST http://localhost:8787/v1/saas/entitlements/verify \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"planId":"plan_2c8e...","organizationId":"org_1","customerId":"customer_9a3b...","grantedById":"sub_6e1a...","feature":"sso"}'
{ "data": { "feature": "sso", "enabled": true, "limit": null } }
POST /v1/saas/seats
Assign a seat.
| Field | Type | Required |
|---|---|---|
customerId |
string | yes |
userId |
string | yes |
planId |
string | yes |
curl -X POST http://localhost:8787/v1/saas/seats \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"customerId":"customer_9a3b...","userId":"user_42","planId":"plan_2c8e..."}'
{ "data": { "seats": [ { "userId": "user_42" } ] } }
POST /v1/saas/seats/remove
Release a seat.
| Field | Type | Required |
|---|---|---|
customerId |
string | yes |
userId |
string | yes |
curl -X POST http://localhost:8787/v1/saas/seats/remove \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"customerId":"customer_9a3b...","userId":"user_42"}'
{ "data": { "seats": [] } }
GitHub Integration
Auth required. Two mounts: /v1/integrations/github (installations /
repositories / teams) and /v1/github/access (grant / revoke / sync).
POST /v1/integrations/github/installations
Connect a GitHub App installation.
| Field | Type | Required |
|---|---|---|
organizationId |
string | yes |
installationId |
integer > 0 | yes |
accountLogin |
string | yes |
accountType |
User | Organization |
yes |
curl -X POST http://localhost:8787/v1/integrations/github/installations \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"organizationId":"org_1","installationId":12345,"accountLogin":"acme","accountType":"Organization"}'
{ "data": { "id": "ghi_2a4c...", "installationId": 12345, "accountLogin": "acme", "accountType": "Organization" } }
GET /v1/integrations/github/installations
With ?organizationId= filters to one org.
curl "http://localhost:8787/v1/integrations/github/installations?organizationId=org_1" -H "Authorization: Bearer $SK_API_KEY"
GET /v1/integrations/github/repositories
Repositories visible to installations (derived from recorded grants).
curl http://localhost:8787/v1/integrations/github/repositories -H "Authorization: Bearer $SK_API_KEY"
{ "data": [ { "owner": "acme", "name": "private-repo", "fullName": "acme/private-repo" } ] }
GET /v1/integrations/github/teams
Org teams synthesized from organization installations. With ?organizationId=
filters.
curl "http://localhost:8787/v1/integrations/github/teams?organizationId=org_1" -H "Authorization: Bearer $SK_API_KEY"
{ "data": [ { "orgLogin": "acme", "slug": "members", "name": "acme/members" } ] }
POST /v1/github/access/grant
Grant a customer access to a private repo.
| Field | Type | Required |
|---|---|---|
organizationId |
string | yes |
installationId |
integer > 0 | yes |
customerId |
string | yes |
entitlementId |
string | yes |
repoOwner |
string | yes |
repoName |
string | yes |
githubUsername |
string | yes |
permission |
pull | push | maintain |
no |
curl -X POST http://localhost:8787/v1/github/access/grant \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{
"organizationId":"org_1","installationId":12345,
"customerId":"customer_9a3b...","entitlementId":"ent_77aa...",
"repoOwner":"acme","repoName":"private-repo","githubUsername":"octocat","permission":"push"
}'
{ "data": { "id": "ghg_8b1d...", "repoOwner": "acme", "repoName": "private-repo", "githubUsername": "octocat", "permission": "push", "status": "invited" } }
POST /v1/github/access/revoke
| Field | Type | Required |
|---|---|---|
grantId |
string | yes |
curl -X POST http://localhost:8787/v1/github/access/revoke \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"grantId":"ghg_8b1d..."}'
{ "data": { "id": "ghg_8b1d...", "status": "revoked" } }
POST /v1/github/access/sync
Reconcile recorded grants: promote pending (invited) grants the GitHub client
now reports as accepted.
| Field | Type | Required |
|---|---|---|
organizationId |
string | yes |
curl -X POST http://localhost:8787/v1/github/access/sync \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"organizationId":"org_1"}'
{ "data": { "organizationId": "org_1", "outcomes": [ { "grantId": "ghg_8b1d...", "action": "activated" } ] } }
Discord Integration
Auth required. Two mounts: /v1/integrations/discord (connect / guilds /
roles) and /v1/discord/access (grant / revoke).
POST /v1/integrations/discord/connect
Connect a guild.
| Field | Type | Required |
|---|---|---|
organizationId |
string | yes |
guildId |
string | yes |
guildName |
string | yes |
botTokenRef |
string | yes |
curl -X POST http://localhost:8787/v1/integrations/discord/connect \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"organizationId":"org_1","guildId":"99887766","guildName":"Acme Community","botTokenRef":"secret://discord-bot"}'
{ "data": { "id": "dcon_3f9a...", "guildId": "99887766", "guildName": "Acme Community" } }
GET /v1/integrations/discord/guilds
List guilds the bot is in.
curl http://localhost:8787/v1/integrations/discord/guilds -H "Authorization: Bearer $SK_API_KEY"
{ "data": [ { "id": "99887766", "name": "Acme Community" } ] }
GET /v1/integrations/discord/roles
List assignable roles for a guild. Query param guildId is required.
curl "http://localhost:8787/v1/integrations/discord/roles?guildId=99887766" -H "Authorization: Bearer $SK_API_KEY"
{ "data": [ { "id": "role_paid", "name": "Supporter", "guildId": "99887766" } ] }
POST /v1/discord/access/grant
Grant a paid role.
| Field | Type | Required |
|---|---|---|
organizationId |
string | yes |
guildId |
string | yes |
roleId |
string | yes |
customerId |
string | yes |
entitlementId |
string | yes |
discordUserId |
string | yes |
curl -X POST http://localhost:8787/v1/discord/access/grant \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{
"organizationId":"org_1","guildId":"99887766","roleId":"role_paid",
"customerId":"customer_9a3b...","entitlementId":"ent_77aa...","discordUserId":"557799"
}'
{ "data": { "id": "dgr_6a2c...", "guildId": "99887766", "roleId": "role_paid", "discordUserId": "557799", "status": "active" } }
POST /v1/discord/access/revoke
| Field | Type | Required |
|---|---|---|
grantId |
string | yes |
curl -X POST http://localhost:8787/v1/discord/access/revoke \
-H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
-d '{"grantId":"dgr_6a2c..."}'
{ "data": { "id": "dgr_6a2c...", "status": "revoked" } }
x402 Paid Endpoints
/v1/paid/* — Public (no API key). The USDC payment itself is the
authorization, so both humans and AI agents pay per call. The endpoint returns
402 Payment Required with a PaymentRequirements document until a valid
X-Payment proof is presented and verified on-chain.
On-chain settlement requires Arc configured via ARC_RPC_URL. Without it, the
402 challenge is still fully functional and any presented proof is honestly
rejected (no mock acceptance). Each settled call is metered as one paid_calls
unit attributed to the payer.
GET /v1/paid/research
A demo pay-per-call endpoint priced at 0.005 USDC on the arc network.
Step 1 — request without payment → 402 challenge:
curl -i http://localhost:8787/v1/paid/research
Response (402), with the requirements echoed in both the body and the
X-Payment-Required (and Accept-Payment) headers:
HTTP/1.1 402 Payment Required
Content-Type: application/json; charset=utf-8
X-Payment-Required: {"scheme":"x402","amount":"0.005","asset":"USDC","network":"arc","payTo":"0x...","productId":"prod_x402_research","resource":"http://localhost:8787/v1/paid/research","nonce":"a1b2c3d4..."}
{
"error": "payment_required",
"accepts": [
{
"scheme": "x402",
"amount": "0.005",
"asset": "USDC",
"network": "arc",
"payTo": "0x0000000000000000000000000000000000000000",
"productId": "prod_x402_research",
"resource": "http://localhost:8787/v1/paid/research",
"nonce": "a1b2c3d4..."
}
]
}
Step 2 — pay on-chain, then retry with the X-Payment proof. The proof is
base64-encoded JSON of:
{
"txHash": "0xpaidtx...",
"from": "0xPayerWallet",
"amount": "0.005",
"network": "arc",
"nonce": "a1b2c3d4..."
}
The nonce MUST echo the one from the 402 challenge to bind the payment to this
request. Construct the header value as base64(JSON.stringify(proof)):
PROOF='{"txHash":"0xpaidtx...","from":"0xPayerWallet","amount":"0.005","network":"arc","nonce":"a1b2c3d4..."}'
XPAY=$(printf '%s' "$PROOF" | base64)
curl -i http://localhost:8787/v1/paid/research \
-H "X-Payment: $XPAY"
On successful on-chain verification (200):
{
"data": {
"answer": "Paid research result: USDC settles on Arc in seconds.",
"generatedAt": "2026-06-16T12:00:00.000Z"
}
}
If the proof is malformed, the nonce/amount/payTo do not match the challenge, or
Arc is not configured, the endpoint again responds 402 with a reason field
explaining the rejection, e.g.:
{
"error": "payment_required",
"accepts": [ { "scheme": "x402", "amount": "0.005", "asset": "USDC", "network": "arc", "payTo": "0x...", "productId": "prod_x402_research", "resource": "http://localhost:8787/v1/paid/research", "nonce": "a1b2c3d4..." } ],
"reason": "x402 settlement requires Arc (set ARC_RPC_URL)"
}