settlekit/docs/API.md
2026-06-17 02:09:36 +03:00

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/json for all request and response bodies

Contents


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 return 402 Payment Required until 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/login is not an API key and cannot be used as Authorization: Bearer <apiKey> on resource routes. Issue an API key via POST /v1/api-keys for programmatic access.

Money & identifiers

  • Money is always a decimal major-unit string in USDC: "0.005", "19.99". A Money object 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)"
}