78 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"
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" } } }
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" } }
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)"
}