settlekit/docs/API.md
caelum0x 4e97fcc409 feat: promo codes at checkout (G3)
Coupons now reach checkout. POST /v1/checkout-sessions takes an optional
couponCode, payment links accept ?promo=CODE (a refused code falls back to
full price with a notice), and the hosted checkout gets a promo field
while the session is open and unpaid. The discounted total becomes the
session amount before network bindings, so onchain verification expects
the discounted amount and a locked Zcash quote is re-priced. Codes are
tenant-scoped, product-scoped codes discount only their products, and
free-trial or 100% codes are refused. The redemption is counted once
after the payment confirms (API confirm and hosted checkout).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 04:09:54 +03:00

82 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"

Promo codes

Add "couponCode": "LAUNCH20" to apply one of your coupons. The session amount becomes the discounted total (what the buyer pays and what onchain verification expects) and discount records the code, list subtotal and amount off. The redemption is counted once, when the payment confirms. Codes that give a free trial, cover the whole price, or belong to another seller are refused with a 400. Payment links accept the same through /l/<slug>?promo=CODE, and buyers can enter a code on the hosted checkout until a payment is recorded.

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

Platform fee statements

/v1/billing — Auth required. SettleKit's per-payment fee is billed once a month. When PLATFORM_BILLING_ORG_ID is set, the API issues each merchant a statement for the previous month (confirmed payments x the fee schedule) as an invoice from the platform org, paid through the hosted checkout like any invoice. Totals below PLATFORM_BILLING_MIN_USD roll into the next month. A statement left unpaid past its due date plus PLATFORM_BILLING_GRACE_DAYS limits new products to the free plan until it is paid (402 payment_required with the pay link).

  • GET /v1/billing/fees returns the schedule, standing (good, due, past_due, restricted), fees accrued since the last statement and every statement with its pay link.
  • POST /v1/billing/statements/run with { "period": "YYYY-MM" } (default: last month) issues statements for every merchant. Platform operator only (the platform org or the bootstrap key). The API also runs this every six hours unless PLATFORM_BILLING_AUTORUN=0.

Invoices

/v1/invoices — Auth required. Lifecycle: draft → open → paid (or void).

POST /v1/invoices

Field Type Required Notes
organizationId string yes
customerId string yes
lineItems array no Each: { description, quantity (≥1), unitAmount }.
discount string no
taxRate object no { jurisdiction, rateBps (0-10000), inclusive? }.
dueAt datetime no
metadata object<string,string> no
curl -X POST http://localhost:8787/v1/invoices \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "organizationId":"org_1","customerId":"customer_9a3b...",
    "lineItems":[{"description":"Pro plan","quantity":1,"unitAmount":"19.99"}],
    "taxRate":{"jurisdiction":"US-CA","rateBps":875}
  }'
{
  "data": {
    "id": "inv_3c7d...",
    "status": "draft",
    "customerId": "customer_9a3b...",
    "lineItems": [ { "description": "Pro plan", "quantity": 1, "unitAmount": { "amount": "19.99", "currency": "USDC" } } ],
    "total": { "amount": "21.74", "currency": "USDC" }
  }
}

GET /v1/invoices

Query param Type Required
customerId string no
curl "http://localhost:8787/v1/invoices?customerId=customer_9a3b..." -H "Authorization: Bearer $SK_API_KEY"

GET /v1/invoices/:id

curl http://localhost:8787/v1/invoices/inv_3c7d... -H "Authorization: Bearer $SK_API_KEY"

GET /v1/invoices/:id.html

Render the styled HTML invoice. Returns text/html (not an enveloped JSON body).

curl http://localhost:8787/v1/invoices/inv_3c7d....html -H "Authorization: Bearer $SK_API_KEY"

POST /v1/invoices/:id/finalize

draft → open.

curl -X POST http://localhost:8787/v1/invoices/inv_3c7d.../finalize -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "inv_3c7d...", "status": "open" } }

POST /v1/invoices/:id/pay

open → paid.

curl -X POST http://localhost:8787/v1/invoices/inv_3c7d.../pay -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "inv_3c7d...", "status": "paid" } }

POST /v1/invoices/:id/void

draft|open → void.

curl -X POST http://localhost:8787/v1/invoices/inv_3c7d.../void -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "inv_3c7d...", "status": "void" } }

Voiding also cancels any open checkout session of the invoice, so an old pay link can no longer be paid.

POST /v1/invoices/:id/send

Make an invoice payable onchain. Finalizes a draft, binds a public pay page (<CHECKOUT_PUBLIC_URL>/i/<token>), opens a checkout session for the invoice total on the merchant's accepted networks, and emails the link (when RESEND_API_KEY is set). Idempotent: re-sending keeps the same link. Requires a receiving wallet in payment settings.

curl -X POST http://localhost:8787/v1/invoices/inv_3c7d.../send \
  -H "Authorization: Bearer $SK_API_KEY" -H "content-type: application/json" \
  -d '{"payerEmail":"billing@client.com"}'
{ "data": { "invoice": { "status": "open", "metadata": { "payToken": "..." } }, "payUrl": "https://pay.example.com/i/...", "checkoutSessionId": "cs_...", "emailedTo": "billing@client.com" } }

The invoice turns paid by itself once a confirmed onchain payment exists for one of its checkout sessions (checked on every read and by the worker's invoice-settle job), and an invoice.paid webhook is queued.

POST /v1/invoices/requests

An ad-hoc payment request: one amount and memo, sent immediately. A customer is created for the payer email on first use.

curl -X POST http://localhost:8787/v1/invoices/requests \
  -H "Authorization: Bearer $SK_API_KEY" -H "content-type: application/json" \
  -d '{"amount":"250.00","description":"Website redesign, deposit","payerEmail":"billing@client.com"}'

GET /v1/invoices/:id.pdf

The invoice as a PDF (a receipt with the settlement transaction once paid).

Public invoice routes (no API key)

The pay token is the capability.

  • GET /v1/public/invoices/:token returns the buyer-safe invoice view (line items, totals, status, payable).
  • POST /v1/public/invoices/:token/sessions returns the open checkout session id (reused while payable, re-opened when expired).
  • GET /v1/public/invoices/:token/pdf returns the PDF.

Refunds

/v1/refunds — Auth required. Creation looks up the backing payment by paymentId to validate the refundable remaining amount.

POST /v1/refunds

Field Type Required Notes
paymentId string yes Must reference an existing payment.
customerId string yes
amount string yes
reason duplicate | fraudulent | customer_request | delivery_failed yes
originalAmount string no Hint only; the backing payment is authoritative.
curl -X POST http://localhost:8787/v1/refunds \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"paymentId":"pay_4c9d...","customerId":"customer_9a3b...","amount":"19.99","reason":"customer_request"}'
{ "data": { "id": "ref_9d2e...", "paymentId": "pay_4c9d...", "amount": { "amount": "19.99", "currency": "USDC" }, "reason": "customer_request", "status": "pending" } }

404 not_found when paymentId is unknown.

GET /v1/refunds

List by paymentId or customerId; with neither, lists all.

Query param Type Required
paymentId string no
customerId string no
curl "http://localhost:8787/v1/refunds?paymentId=pay_4c9d..." -H "Authorization: Bearer $SK_API_KEY"

POST /v1/refunds/:id/succeed

pending → succeeded.

curl -X POST http://localhost:8787/v1/refunds/ref_9d2e.../succeed -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "ref_9d2e...", "status": "succeeded" } }

POST /v1/refunds/:id/fail

pending → failed.

Field Type Required
reason string no
curl -X POST http://localhost:8787/v1/refunds/ref_9d2e.../fail \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"reason":"insufficient liquidity"}'
{ "data": { "id": "ref_9d2e...", "status": "failed" } }

Dunning

/v1/dunning — Auth required. Failed-payment recovery campaigns keyed by subscription.

POST /v1/dunning

Start a campaign for a subscription.

Field Type Required
subscriptionId string yes
curl -X POST http://localhost:8787/v1/dunning \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"subscriptionId":"sub_6e1a..."}'
{ "data": { "subscriptionId": "sub_6e1a...", "status": "active", "attempts": 0 } }

GET /v1/dunning

List active campaigns, or only those due for retry with ?due=true (or ?due=1).

curl "http://localhost:8787/v1/dunning?due=true" -H "Authorization: Bearer $SK_API_KEY"

POST /v1/dunning/:subscriptionId/attempt

Record a retry attempt outcome. recovered closes the campaign; failed advances or exhausts it.

Field Type Required
outcome "recovered" | "failed" yes
failureReason string no
curl -X POST http://localhost:8787/v1/dunning/sub_6e1a.../attempt \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"outcome":"failed","failureReason":"insufficient funds"}'
{ "data": { "subscriptionId": "sub_6e1a...", "status": "active", "attempts": 1 } }

POST /v1/dunning/:subscriptionId/recover

Mark a campaign recovered.

curl -X POST http://localhost:8787/v1/dunning/sub_6e1a.../recover -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "subscriptionId": "sub_6e1a...", "status": "recovered" } }

Disputes

/v1/disputes — Auth required. Chargeback / dispute engine.

POST /v1/disputes

Open a dispute.

Field Type Required
paymentId string yes
customerId string yes
reason fraud | not_received | duplicate | quality | unrecognized yes
curl -X POST http://localhost:8787/v1/disputes \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"paymentId":"pay_4c9d...","customerId":"customer_9a3b...","reason":"not_received"}'
{ "data": { "id": "dsp_1f4a...", "paymentId": "pay_4c9d...", "reason": "not_received", "status": "open" } }

GET /v1/disputes

List disputes. ?status=open or ?status=under_review returns open disputes; any other status filters the full list; no status returns all.

curl "http://localhost:8787/v1/disputes?status=open" -H "Authorization: Bearer $SK_API_KEY"

GET /v1/disputes/:id

curl http://localhost:8787/v1/disputes/dsp_1f4a... -H "Authorization: Bearer $SK_API_KEY"

POST /v1/disputes/:id/evidence

Attach evidence (moves the dispute to under_review).

Field Type Required
kind text | receipt | shipping | communication | url | file yes
description string yes
value string yes
curl -X POST http://localhost:8787/v1/disputes/dsp_1f4a.../evidence \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"kind":"text","description":"Delivery log","value":"Repo invite accepted 2026-06-16"}'
{ "data": { "id": "dsp_1f4a...", "status": "under_review", "evidence": [ { "kind": "text" } ] } }

POST /v1/disputes/:id/resolve

Field Type Required
outcome won | lost | refunded yes
curl -X POST http://localhost:8787/v1/disputes/dsp_1f4a.../resolve \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"outcome":"won"}'
{ "data": { "id": "dsp_1f4a...", "status": "won" } }

Payouts

/v1/payouts — Auth required. Merchant settlement. Available balance is computed from the org's confirmed payments minus prior (pending or paid) payouts.

POST /v1/payouts

Field Type Required
organizationId string yes
walletAddress string yes
amount string yes
network arc | base | ethereum yes
curl -X POST http://localhost:8787/v1/payouts \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"organizationId":"org_1","walletAddress":"0xMerchantWallet","amount":"500.00","network":"arc"}'
{ "data": { "id": "po_8a2c...", "organizationId": "org_1", "amount": { "amount": "500.00", "currency": "USDC" }, "network": "arc", "status": "pending" } }

GET /v1/payouts

List payouts. With ?organizationId= filters to one org; without it, lists all.

curl "http://localhost:8787/v1/payouts?organizationId=org_1" -H "Authorization: Bearer $SK_API_KEY"

GET /v1/payouts/balance

Available balance for an org.

Query param Type Required
organizationId string yes
curl "http://localhost:8787/v1/payouts/balance?organizationId=org_1" -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "available": { "amount": "1250.00", "currency": "USDC" } } }

POST /v1/payouts/:id/paid

Mark paid with an on-chain txHash.

curl -X POST http://localhost:8787/v1/payouts/po_8a2c.../paid \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"txHash":"0xpayout..."}'
{ "data": { "id": "po_8a2c...", "status": "paid", "txHash": "0xpayout..." } }

POST /v1/payouts/:id/fail

Field Type Required
reason string no
curl -X POST http://localhost:8787/v1/payouts/po_8a2c.../fail \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"reason":"address rejected"}'
{ "data": { "id": "po_8a2c...", "status": "failed" } }

Bundles

/v1/bundles — Auth required. Group multiple products into one purchasable bundle. Validation (non-empty, no duplicates/cycles, all products exist) runs in the service.

POST /v1/bundles

Field Type Required Notes
merchantId string yes
organizationId string yes
name string yes
description string no
productIds string[] yes (min 1)
amount string no Bundle price; when omitted, member prices default.
interval one_time | monthly | yearly no
curl -X POST http://localhost:8787/v1/bundles \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"merchantId":"acct_01H...","organizationId":"org_1","name":"Starter Pack","productIds":["prod_5d2c...","prod_8e1f..."],"amount":"49.00"}'
{ "data": { "id": "bndl_4f2a...", "name": "Starter Pack", "productIds": ["prod_5d2c...","prod_8e1f..."], "status": "draft" } }

GET /v1/bundles

With ?organizationId= filters to one org.

curl "http://localhost:8787/v1/bundles?organizationId=org_1" -H "Authorization: Bearer $SK_API_KEY"

GET /v1/bundles/:id

curl http://localhost:8787/v1/bundles/bndl_4f2a... -H "Authorization: Bearer $SK_API_KEY"

PATCH /v1/bundles/:id

Patch mutable fields. Setting status to archived archives the bundle.

Field Type Required
name string no
description string no
status draft | active | archived no
curl -X PATCH http://localhost:8787/v1/bundles/bndl_4f2a... \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Starter Pack 2026"}'
{ "data": { "id": "bndl_4f2a...", "name": "Starter Pack 2026", "status": "draft" } }

POST /v1/bundles/:id/publish

curl -X POST http://localhost:8787/v1/bundles/bndl_4f2a.../publish -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "bndl_4f2a...", "status": "active" } }

Agent Services

/v1/agent-services — Auth required. Listings for AI/agent tools that other agents can discover and pay for.

POST /v1/agent-services

Field Type Required Default
organizationId string yes
merchantId string yes
productId string yes
name string yes
description string yes
endpoint string (url) yes
price string yes
network arc | base no base
inputSchema object yes
outputSchema object no
curl -X POST http://localhost:8787/v1/agent-services \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "organizationId":"org_1","merchantId":"acct_01H...","productId":"prod_ai...",
    "name":"Summarizer","description":"Summarize text","endpoint":"https://api.acme.dev/sum",
    "price":"0.01","inputSchema":{"text":"string"}
  }'
{ "data": { "id": "agsvc_2c8d...", "name": "Summarizer", "endpoint": "https://api.acme.dev/sum", "price": "0.01", "network": "base", "status": "draft" } }

GET /v1/agent-services

Discover services. With ?organizationId= filters to one org.

curl "http://localhost:8787/v1/agent-services?organizationId=org_1" -H "Authorization: Bearer $SK_API_KEY"

GET /v1/agent-services/:id

curl http://localhost:8787/v1/agent-services/agsvc_2c8d... -H "Authorization: Bearer $SK_API_KEY"

PATCH /v1/agent-services/:id

Field Type Required
name string no
description string no
endpoint string (url) no
price string no
curl -X PATCH http://localhost:8787/v1/agent-services/agsvc_2c8d... \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"price":"0.02"}'

POST /v1/agent-services/:id/publish

curl -X POST http://localhost:8787/v1/agent-services/agsvc_2c8d.../publish -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "agsvc_2c8d...", "status": "active" } }

GET /v1/agent-services/:id/metadata.json

Machine-readable metadata document. Returned as raw JSON (not wrapped in a data envelope) so agents can consume it directly.

curl http://localhost:8787/v1/agent-services/agsvc_2c8d.../metadata.json \
  -H "Authorization: Bearer $SK_API_KEY"
{
  "name": "Summarizer",
  "description": "Summarize text",
  "endpoint": "https://api.acme.dev/sum",
  "price": { "amount": "0.02", "currency": "USDC", "network": "base" },
  "inputSchema": { "text": "string" }
}

Marketplace

/v1/marketplace — Auth required. Public product listings + discovery and seller profiles.

POST /v1/marketplace/listings

Create an (unpublished) listing.

Field Type Required Default
organizationId string yes
merchantId string yes
productId string yes
title string yes
summary string yes
tags string[] no []
curl -X POST http://localhost:8787/v1/marketplace/listings \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"organizationId":"org_1","merchantId":"acct_01H...","productId":"prod_5d2c...","title":"Pro Repo","summary":"Private repo access","tags":["devtools"]}'
{ "data": { "id": "lst_7d3a...", "title": "Pro Repo", "tags": ["devtools"], "status": "draft", "ratingAvg": 0, "ratingCount": 0 } }

GET /v1/marketplace/listings

Search published listings. Query params: q (text), tag, sort (top | new | price).

curl "http://localhost:8787/v1/marketplace/listings?q=repo&tag=devtools&sort=top" \
  -H "Authorization: Bearer $SK_API_KEY"
{ "data": [ { "id": "lst_7d3a...", "title": "Pro Repo", "ratingAvg": 4.5 } ] }

GET /v1/marketplace/listings/:id

curl http://localhost:8787/v1/marketplace/listings/lst_7d3a... -H "Authorization: Bearer $SK_API_KEY"

POST /v1/marketplace/listings/:id/publish

curl -X POST http://localhost:8787/v1/marketplace/listings/lst_7d3a.../publish -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "lst_7d3a...", "status": "published" } }

POST /v1/marketplace/listings/:id/unpublish

curl -X POST http://localhost:8787/v1/marketplace/listings/lst_7d3a.../unpublish -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "lst_7d3a...", "status": "draft" } }

POST /v1/marketplace/listings/:id/rate

Field Type Required
stars integer 1-5 yes
curl -X POST http://localhost:8787/v1/marketplace/listings/lst_7d3a.../rate \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"stars":5}'
{ "data": { "id": "lst_7d3a...", "ratingAvg": 4.7, "ratingCount": 11 } }

GET /v1/marketplace/sellers/:merchantId

Aggregate seller profile.

curl http://localhost:8787/v1/marketplace/sellers/acct_01H... -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "merchantId": "acct_01H...", "listings": 3, "ratingAvg": 4.6 } }

Usage & Credits

/v1/usage — Auth required. Metering + prepaid credits. A meter is identified by { organizationId, customerId, productId, metric }. A credit balance is identified by { organizationId, customerId, productId }. Optional periodStart (ISO datetime) selects the metering period; it defaults to now.

POST /v1/usage/record

Record N units of a metric (creates the meter on first use).

Field Type Required Default
organizationId string yes
customerId string yes
productId string yes
metric string yes
quantity integer ≥ 1 no 1
periodStart datetime no now
curl -X POST http://localhost:8787/v1/usage/record \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"organizationId":"org_1","customerId":"customer_9a3b...","productId":"prod_api...","metric":"api_calls","quantity":5}'
{ "data": { "metric": "api_calls", "quantity": 5, "periodStart": "2026-06-16T00:00:00.000Z" } }

GET /v1/usage/meter

Read the current meter. Query params: organizationId, customerId, productId, metric (all required), periodStart (optional).

curl "http://localhost:8787/v1/usage/meter?organizationId=org_1&customerId=customer_9a3b...&productId=prod_api...&metric=api_calls" \
  -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "metric": "api_calls", "quantity": 5 } }

POST /v1/usage/charge

Compute the charge for a meter's usage at a unit price.

Field Type Required
(meter ref fields) yes
unitAmount string yes
periodStart datetime no
curl -X POST http://localhost:8787/v1/usage/charge \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"organizationId":"org_1","customerId":"customer_9a3b...","productId":"prod_api...","metric":"api_calls","unitAmount":"0.001"}'
{ "data": { "quantity": 5, "unitAmount": { "amount": "0.001", "currency": "USDC" }, "total": { "amount": "0.005", "currency": "USDC" } } }

POST /v1/usage/limit

Evaluate usage against a hard limit.

Field Type Required
(meter ref fields) yes
limit integer ≥ 0 yes
periodStart datetime no
curl -X POST http://localhost:8787/v1/usage/limit \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"organizationId":"org_1","customerId":"customer_9a3b...","productId":"prod_api...","metric":"api_calls","limit":1000}'
{ "data": { "used": 5, "limit": 1000, "withinLimit": true } }

GET /v1/usage/credits

Read a prepaid balance. Query params: organizationId, customerId, productId (all required).

curl "http://localhost:8787/v1/usage/credits?organizationId=org_1&customerId=customer_9a3b...&productId=prod_api..." \
  -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "credits": 100 } }

POST /v1/usage/credits/grant

Grant prepaid credits.

Field Type Required
organizationId string yes
customerId string yes
productId string yes
credits integer ≥ 1 yes
curl -X POST http://localhost:8787/v1/usage/credits/grant \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"organizationId":"org_1","customerId":"customer_9a3b...","productId":"prod_api...","credits":100}'
{ "data": { "credits": 100 } }

POST /v1/usage/credits/consume

Consume prepaid credits (e.g. meter a paid API call).

Field Type Required Default
organizationId string yes
customerId string yes
productId string yes
credits integer ≥ 1 no 1
curl -X POST http://localhost:8787/v1/usage/credits/consume \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"organizationId":"org_1","customerId":"customer_9a3b...","productId":"prod_api...","credits":1}'
{ "data": { "credits": 99 } }

Consuming more than the balance returns 402 insufficient_credits.


Analytics

/v1/analytics — Auth required.

GET /v1/analytics/summary

Merchant dashboard summary computed live from the stores. Query param organizationId (defaults to the platform's default org when omitted).

Fields: revenue (sum of confirmed payments), revenueSeries (14-day daily totals), customers (count), activeAccess (active entitlements), mrr (normalized monthly recurring revenue), expiringSubscriptions (in grace or ending within 7 days), failedDeliveries (failed/partially-failed runs).

curl "http://localhost:8787/v1/analytics/summary?organizationId=org_1" \
  -H "Authorization: Bearer $SK_API_KEY"
{
  "data": {
    "revenue": { "amount": "1250.00", "currency": "USDC" },
    "customers": 42,
    "activeAccess": 38,
    "expiringSubscriptions": 3,
    "failedDeliveries": 1,
    "mrr": { "amount": "640.00", "currency": "USDC" },
    "revenueSeries": [ { "date": "2026-06-03", "amount": 0 }, { "date": "2026-06-16", "amount": 120 } ]
  }
}

Settings

/v1/settings — Auth required. Editable organization config; unknown keys are ignored and provided keys are merged over current.

GET /v1/settings

Query param organizationId (defaults to the platform default org).

curl "http://localhost:8787/v1/settings?organizationId=org_1" -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "organizationId": "org_1", "orgName": "Acme", "payoutCurrency": "USDC", "defaultRail": "arc" } }

POST /v1/settings

Patch settings.

Field Type Required
organizationId string no
orgName string no
supportEmail string no
payoutCurrency string no
webhookSecret string no
defaultRail arc | circle | x402 no
curl -X POST http://localhost:8787/v1/settings \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"organizationId":"org_1","orgName":"Acme Inc","defaultRail":"arc"}'
{ "data": { "organizationId": "org_1", "orgName": "Acme Inc", "defaultRail": "arc" } }

Escrow

/v1/escrow — Auth required. Milestone escrow for agent/consulting work. Lifecycle: create → fund → assign → submit → approve → release (or refund; dispute also available).

POST /v1/escrow/tasks

Field Type Required Default
organizationId string yes
buyerCustomerId string yes
title string yes
description string yes
amount string yes
currency "USDC" no "USDC"
curl -X POST http://localhost:8787/v1/escrow/tasks \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"organizationId":"org_1","buyerCustomerId":"customer_9a3b...","title":"Build landing page","description":"Next.js marketing site","amount":"500.00"}'
{ "data": { "id": "esc_3a9c...", "title": "Build landing page", "amount": { "amount": "500.00", "currency": "USDC" }, "status": "created" } }

GET /v1/escrow/tasks

List tasks for an org. Query param organizationId is required.

curl "http://localhost:8787/v1/escrow/tasks?organizationId=org_1" -H "Authorization: Bearer $SK_API_KEY"

GET /v1/escrow/tasks/:id

curl http://localhost:8787/v1/escrow/tasks/esc_3a9c... -H "Authorization: Bearer $SK_API_KEY"

POST /v1/escrow/tasks/:id/fund

Field Type Required
fundingTxHash string yes
curl -X POST http://localhost:8787/v1/escrow/tasks/esc_3a9c.../fund \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"fundingTxHash":"0xfund..."}'
{ "data": { "id": "esc_3a9c...", "status": "funded", "fundingTxHash": "0xfund..." } }

POST /v1/escrow/tasks/:id/assign

Field Type Required
workerCustomerId string yes
curl -X POST http://localhost:8787/v1/escrow/tasks/esc_3a9c.../assign \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"workerCustomerId":"customer_worker..."}'
{ "data": { "id": "esc_3a9c...", "status": "assigned", "workerCustomerId": "customer_worker..." } }

POST /v1/escrow/tasks/:id/submit

Field Type Required
content string yes
curl -X POST http://localhost:8787/v1/escrow/tasks/esc_3a9c.../submit \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"content":"https://github.com/acme/site/pull/1"}'
{ "data": { "id": "esc_3a9c...", "status": "submitted" } }

POST /v1/escrow/tasks/:id/approve

No body.

curl -X POST http://localhost:8787/v1/escrow/tasks/esc_3a9c.../approve -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "esc_3a9c...", "status": "approved" } }

POST /v1/escrow/tasks/:id/release

Field Type Required
releaseTxHash string yes
curl -X POST http://localhost:8787/v1/escrow/tasks/esc_3a9c.../release \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"releaseTxHash":"0xrelease..."}'
{ "data": { "id": "esc_3a9c...", "status": "released", "releaseTxHash": "0xrelease..." } }

POST /v1/escrow/tasks/:id/refund

Field Type Required Default
reason string no "refunded via API"
curl -X POST http://localhost:8787/v1/escrow/tasks/esc_3a9c.../refund \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"reason":"scope canceled"}'
{ "data": { "id": "esc_3a9c...", "status": "refunded" } }

Webhooks

/v1/webhooks — Auth required. Register endpoints and emit signed events.

Event types: payment.confirmed, payment.failed, payment.refunded, subscription.created, subscription.renewed, subscription.canceled, entitlement.granted, entitlement.revoked, delivery.succeeded, delivery.failed.

POST /v1/webhooks/endpoints

Register an endpoint with a freshly-minted signing secret (returned once).

Field Type Required
organizationId string yes
url string (url) yes
enabledEvents event-type[] yes (min 1)
curl -X POST http://localhost:8787/v1/webhooks/endpoints \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"organizationId":"org_1","url":"https://acme.dev/hooks","enabledEvents":["payment.confirmed","entitlement.granted"]}'
{
  "data": {
    "id": "whe_5b1c...",
    "organizationId": "org_1",
    "url": "https://acme.dev/hooks",
    "signingSecret": "whsec_8f2a...",
    "enabledEvents": ["payment.confirmed","entitlement.granted"],
    "active": true,
    "createdAt": "2026-06-16T12:00:00.000Z"
  }
}

GET /v1/webhooks/endpoints

With ?organizationId= filters to one org.

curl "http://localhost:8787/v1/webhooks/endpoints?organizationId=org_1" -H "Authorization: Bearer $SK_API_KEY"

POST /v1/webhooks/events

Emit an event: persist it and return the signed payload + signature for each matching active endpoint. The signature is computed over the serialized event with a unix timestamp — exactly what a receiver verifies.

Field Type Required Default
organizationId string yes
type event type yes
data object no {}
curl -X POST http://localhost:8787/v1/webhooks/events \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"organizationId":"org_1","type":"payment.confirmed","data":{"paymentId":"pay_4c9d..."}}'
{
  "data": {
    "event": {
      "id": "evt_9d4a...",
      "type": "payment.confirmed",
      "organizationId": "org_1",
      "data": { "paymentId": "pay_4c9d..." },
      "createdAt": "2026-06-16T12:00:00.000Z"
    },
    "deliveries": [
      { "endpointId": "whe_5b1c...", "url": "https://acme.dev/hooks", "signature": "t=1718539200,v1=ab12cd..." }
    ]
  }
}

GET /v1/webhooks/events

With ?organizationId= filters to one org.

curl "http://localhost:8787/v1/webhooks/events?organizationId=org_1" -H "Authorization: Bearer $SK_API_KEY"

GET /v1/webhooks/events/:id

curl http://localhost:8787/v1/webhooks/events/evt_9d4a... -H "Authorization: Bearer $SK_API_KEY"

Files

/v1/files — Auth required. HMAC-signed, usage-limited download URLs.

POST /v1/files/downloads

Issue a signed download URL + grant.

Field Type Required
fileId string yes
customerId string yes
expiresInSec integer > 0 no
maxDownloads integer > 0 no
curl -X POST http://localhost:8787/v1/files/downloads \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"fileId":"file_7a2b...","customerId":"customer_9a3b...","expiresInSec":3600,"maxDownloads":3}'
{
  "data": {
    "url": "https://downloads.acme.dev/file_7a2b...?exp=1718542800&sig=ab12...",
    "grant": { "fileId": "file_7a2b...", "customerId": "customer_9a3b...", "maxDownloads": 3, "downloadsUsed": 0 }
  }
}

GET /v1/files/download

Redeem a signed download URL. The full signed URL is passed as the url query param; the server verifies the signature/expiry and atomically consumes one download.

Query param Type Required
url string yes
curl "http://localhost:8787/v1/files/download?url=https%3A%2F%2Fdownloads.acme.dev%2Ffile_7a2b...%3Fexp%3D1718542800%26sig%3Dab12..." \
  -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "fileId": "file_7a2b...", "downloadsRemaining": 2 } }

A missing url returns 400 validation_error; an invalid/expired URL is rejected by the signed-URL verifier.


Delivery Runs & Actions

Auth required. Inspect delivery runs and test individual delivery action handlers.

GET /v1/delivery-runs

List runs. Optional query params organizationId and paymentId filter.

curl "http://localhost:8787/v1/delivery-runs?organizationId=org_1&paymentId=pay_4c9d..." \
  -H "Authorization: Bearer $SK_API_KEY"
{ "data": [ { "id": "dr_4f8a...", "paymentId": "pay_4c9d...", "status": "succeeded", "actionRuns": [] } ] }

GET /v1/delivery-runs/:id

curl http://localhost:8787/v1/delivery-runs/dr_4f8a... -H "Authorization: Bearer $SK_API_KEY"

POST /v1/delivery-runs/:id/retry

Re-run the failed actions of a run by marking them pending again.

curl -X POST http://localhost:8787/v1/delivery-runs/dr_4f8a.../retry -H "Authorization: Bearer $SK_API_KEY"
{ "data": { "id": "dr_4f8a...", "status": "pending", "actionRuns": [ { "status": "pending", "attempts": 1 } ] } }

POST /v1/delivery-actions/test

Execute a single delivery action through the real handler registry + in-process clients, returning the handler's actual output.

Context fields (all optional, with defaults): organizationId (org_test), customerId (cus_test), productId (prod_test), paymentId (pay_test), entitlementId (ent_test), customerEmail, githubInstallationId, githubUsername, discordUserId.

action is a discriminated union on type:

type Additional fields
github_invite repoId, permission? (pull/push/maintain)
github_team_add orgLogin, teamSlug
license_key_create policyId
api_key_create scopes (string[], min 1)
file_access_grant fileId
discord_role_add guildId, roleId
saas_entitlement_create features (object<string, boolean|number|string>)
webhook_send url
email_send template
curl -X POST http://localhost:8787/v1/delivery-actions/test \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "githubInstallationId":12345,"githubUsername":"octocat",
    "action":{"type":"github_invite","repoId":"acme/private-repo","permission":"push"}
  }'
{
  "data": {
    "action": { "type": "github_invite", "repoId": "acme/private-repo", "permission": "push" },
    "status": "succeeded",
    "output": { "invited": "octocat", "repo": "acme/private-repo", "permission": "push" }
  }
}

An unknown action type returns 404 not_found; a handler failure surfaces the handler's own error, otherwise 400 validation_error.


SaaS

/v1/saas — Auth required. Plans, feature-bearing tenant entitlements, feature verification, and seat management.

POST /v1/saas/plans

Field Type Required Default
productId string yes
name string yes
interval monthly | yearly no monthly
amount string yes
features object<string, boolean|number> no {}
seats integer ≥ 0 no 1
curl -X POST http://localhost:8787/v1/saas/plans \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"productId":"prod_saas...","name":"Team","amount":"99.00","features":{"sso":true,"seats":10},"seats":10}'
{ "data": { "id": "plan_2c8e...", "name": "Team", "interval": "monthly", "price": { "amount": "99.00", "currency": "USDC" }, "features": { "sso": true, "seats": 10 }, "seats": 10 } }

GET /v1/saas/plans

With ?productId= filters to one product.

curl "http://localhost:8787/v1/saas/plans?productId=prod_saas..." -H "Authorization: Bearer $SK_API_KEY"

POST /v1/saas/features

Grant a feature-bearing tenant entitlement from a plan.

Field Type Required Default
organizationId string yes
customerId string yes
planId string yes
grantedById string yes
grantedByType payment | subscription | bundle | manual no subscription
expiresAt datetime no
curl -X POST http://localhost:8787/v1/saas/features \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"organizationId":"org_1","customerId":"customer_9a3b...","planId":"plan_2c8e...","grantedById":"sub_6e1a..."}'
{ "data": { "id": "tent_4a1c...", "planId": "plan_2c8e...", "features": { "sso": true, "seats": 10 }, "status": "active" } }

POST /v1/saas/entitlements/verify

Check a feature flag/limit on a freshly-built tenant entitlement.

Field Type Required
planId string yes
organizationId string yes
customerId string yes
grantedById string yes
feature string yes
curl -X POST http://localhost:8787/v1/saas/entitlements/verify \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"planId":"plan_2c8e...","organizationId":"org_1","customerId":"customer_9a3b...","grantedById":"sub_6e1a...","feature":"sso"}'
{ "data": { "feature": "sso", "enabled": true, "limit": null } }

POST /v1/saas/seats

Assign a seat.

Field Type Required
customerId string yes
userId string yes
planId string yes
curl -X POST http://localhost:8787/v1/saas/seats \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"customerId":"customer_9a3b...","userId":"user_42","planId":"plan_2c8e..."}'
{ "data": { "seats": [ { "userId": "user_42" } ] } }

POST /v1/saas/seats/remove

Release a seat.

Field Type Required
customerId string yes
userId string yes
curl -X POST http://localhost:8787/v1/saas/seats/remove \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"customerId":"customer_9a3b...","userId":"user_42"}'
{ "data": { "seats": [] } }

GitHub Integration

Auth required. Two mounts: /v1/integrations/github (installations / repositories / teams) and /v1/github/access (grant / revoke / sync).

POST /v1/integrations/github/installations

Connect a GitHub App installation.

Field Type Required
organizationId string yes
installationId integer > 0 yes
accountLogin string yes
accountType User | Organization yes
curl -X POST http://localhost:8787/v1/integrations/github/installations \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"organizationId":"org_1","installationId":12345,"accountLogin":"acme","accountType":"Organization"}'
{ "data": { "id": "ghi_2a4c...", "installationId": 12345, "accountLogin": "acme", "accountType": "Organization" } }

GET /v1/integrations/github/installations

With ?organizationId= filters to one org.

curl "http://localhost:8787/v1/integrations/github/installations?organizationId=org_1" -H "Authorization: Bearer $SK_API_KEY"

GET /v1/integrations/github/repositories

Repositories visible to installations (derived from recorded grants).

curl http://localhost:8787/v1/integrations/github/repositories -H "Authorization: Bearer $SK_API_KEY"
{ "data": [ { "owner": "acme", "name": "private-repo", "fullName": "acme/private-repo" } ] }

GET /v1/integrations/github/teams

Org teams synthesized from organization installations. With ?organizationId= filters.

curl "http://localhost:8787/v1/integrations/github/teams?organizationId=org_1" -H "Authorization: Bearer $SK_API_KEY"
{ "data": [ { "orgLogin": "acme", "slug": "members", "name": "acme/members" } ] }

POST /v1/github/access/grant

Grant a customer access to a private repo.

Field Type Required
organizationId string yes
installationId integer > 0 yes
customerId string yes
entitlementId string yes
repoOwner string yes
repoName string yes
githubUsername string yes
permission pull | push | maintain no
curl -X POST http://localhost:8787/v1/github/access/grant \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "organizationId":"org_1","installationId":12345,
    "customerId":"customer_9a3b...","entitlementId":"ent_77aa...",
    "repoOwner":"acme","repoName":"private-repo","githubUsername":"octocat","permission":"push"
  }'
{ "data": { "id": "ghg_8b1d...", "repoOwner": "acme", "repoName": "private-repo", "githubUsername": "octocat", "permission": "push", "status": "invited" } }

POST /v1/github/access/revoke

Field Type Required
grantId string yes
curl -X POST http://localhost:8787/v1/github/access/revoke \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"grantId":"ghg_8b1d..."}'
{ "data": { "id": "ghg_8b1d...", "status": "revoked" } }

POST /v1/github/access/sync

Reconcile recorded grants: promote pending (invited) grants the GitHub client now reports as accepted.

Field Type Required
organizationId string yes
curl -X POST http://localhost:8787/v1/github/access/sync \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"organizationId":"org_1"}'
{ "data": { "organizationId": "org_1", "outcomes": [ { "grantId": "ghg_8b1d...", "action": "activated" } ] } }

Discord Integration

Auth required. Two mounts: /v1/integrations/discord (connect / guilds / roles) and /v1/discord/access (grant / revoke).

POST /v1/integrations/discord/connect

Connect a guild.

Field Type Required
organizationId string yes
guildId string yes
guildName string yes
botTokenRef string yes
curl -X POST http://localhost:8787/v1/integrations/discord/connect \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"organizationId":"org_1","guildId":"99887766","guildName":"Acme Community","botTokenRef":"secret://discord-bot"}'
{ "data": { "id": "dcon_3f9a...", "guildId": "99887766", "guildName": "Acme Community" } }

GET /v1/integrations/discord/guilds

List guilds the bot is in.

curl http://localhost:8787/v1/integrations/discord/guilds -H "Authorization: Bearer $SK_API_KEY"
{ "data": [ { "id": "99887766", "name": "Acme Community" } ] }

GET /v1/integrations/discord/roles

List assignable roles for a guild. Query param guildId is required.

curl "http://localhost:8787/v1/integrations/discord/roles?guildId=99887766" -H "Authorization: Bearer $SK_API_KEY"
{ "data": [ { "id": "role_paid", "name": "Supporter", "guildId": "99887766" } ] }

POST /v1/discord/access/grant

Grant a paid role.

Field Type Required
organizationId string yes
guildId string yes
roleId string yes
customerId string yes
entitlementId string yes
discordUserId string yes
curl -X POST http://localhost:8787/v1/discord/access/grant \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "organizationId":"org_1","guildId":"99887766","roleId":"role_paid",
    "customerId":"customer_9a3b...","entitlementId":"ent_77aa...","discordUserId":"557799"
  }'
{ "data": { "id": "dgr_6a2c...", "guildId": "99887766", "roleId": "role_paid", "discordUserId": "557799", "status": "active" } }

POST /v1/discord/access/revoke

Field Type Required
grantId string yes
curl -X POST http://localhost:8787/v1/discord/access/revoke \
  -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \
  -d '{"grantId":"dgr_6a2c..."}'
{ "data": { "id": "dgr_6a2c...", "status": "revoked" } }

x402 Paid Endpoints

/v1/paid/* — Public (no API key). The USDC payment itself is the authorization, so both humans and AI agents pay per call. The endpoint returns 402 Payment Required with a PaymentRequirements document until a valid X-Payment proof is presented and verified on-chain.

On-chain settlement requires Arc configured via ARC_RPC_URL. Without it, the 402 challenge is still fully functional and any presented proof is honestly rejected (no mock acceptance). Each settled call is metered as one paid_calls unit attributed to the payer.

GET /v1/paid/research

A demo pay-per-call endpoint priced at 0.005 USDC on the arc network.

Step 1 — request without payment → 402 challenge:

curl -i http://localhost:8787/v1/paid/research

Response (402), with the requirements echoed in both the body and the X-Payment-Required (and Accept-Payment) headers:

HTTP/1.1 402 Payment Required
Content-Type: application/json; charset=utf-8
X-Payment-Required: {"scheme":"x402","amount":"0.005","asset":"USDC","network":"arc","payTo":"0x...","productId":"prod_x402_research","resource":"http://localhost:8787/v1/paid/research","nonce":"a1b2c3d4..."}
{
  "error": "payment_required",
  "accepts": [
    {
      "scheme": "x402",
      "amount": "0.005",
      "asset": "USDC",
      "network": "arc",
      "payTo": "0x0000000000000000000000000000000000000000",
      "productId": "prod_x402_research",
      "resource": "http://localhost:8787/v1/paid/research",
      "nonce": "a1b2c3d4..."
    }
  ]
}

Step 2 — pay on-chain, then retry with the X-Payment proof. The proof is base64-encoded JSON of:

{
  "txHash": "0xpaidtx...",
  "from": "0xPayerWallet",
  "amount": "0.005",
  "network": "arc",
  "nonce": "a1b2c3d4..."
}

The nonce MUST echo the one from the 402 challenge to bind the payment to this request. Construct the header value as base64(JSON.stringify(proof)):

PROOF='{"txHash":"0xpaidtx...","from":"0xPayerWallet","amount":"0.005","network":"arc","nonce":"a1b2c3d4..."}'
XPAY=$(printf '%s' "$PROOF" | base64)

curl -i http://localhost:8787/v1/paid/research \
  -H "X-Payment: $XPAY"

On successful on-chain verification (200):

{
  "data": {
    "answer": "Paid research result: USDC settles on Arc in seconds.",
    "generatedAt": "2026-06-16T12:00:00.000Z"
  }
}

If the proof is malformed, the nonce/amount/payTo do not match the challenge, or Arc is not configured, the endpoint again responds 402 with a reason field explaining the rejection, e.g.:

{
  "error": "payment_required",
  "accepts": [ { "scheme": "x402", "amount": "0.005", "asset": "USDC", "network": "arc", "payTo": "0x...", "productId": "prod_x402_research", "resource": "http://localhost:8787/v1/paid/research", "nonce": "a1b2c3d4..." } ],
  "reason": "x402 settlement requires Arc (set ARC_RPC_URL)"
}