# 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](#conventions) - [Response envelope](#response-envelope) - [Error envelope](#error-envelope) - [Error codes](#error-codes) - [Authentication](#authentication) - [Money & identifiers](#money--identifiers) - [Health check](#health-check) - [Configuration](#configuration) - [Auth](#auth) (`/v1/auth`) - [Products & Prices](#products--prices) (`/v1/products`) - [Customers](#customers) (`/v1/customers`) - [Checkout Sessions](#checkout-sessions) (`/v1/checkout-sessions`) - [Payments](#payments) (`/v1/payments`) - [Subscriptions](#subscriptions) (`/v1/subscriptions`) - [Entitlements](#entitlements) (`/v1/entitlements`) - [License Keys](#license-keys) (`/v1/license-keys`) - [API Keys](#api-keys) (`/v1/api-keys`) - [Coupons](#coupons) (`/v1/coupons`) - [Invoices](#invoices) (`/v1/invoices`) - [Refunds](#refunds) (`/v1/refunds`) - [Dunning](#dunning) (`/v1/dunning`) - [Disputes](#disputes) (`/v1/disputes`) - [Payouts](#payouts) (`/v1/payouts`) - [Bundles](#bundles) (`/v1/bundles`) - [Agent Services](#agent-services) (`/v1/agent-services`) - [Marketplace](#marketplace) (`/v1/marketplace`) - [Usage & Credits](#usage--credits) (`/v1/usage`) - [Analytics](#analytics) (`/v1/analytics`) - [Settings](#settings) (`/v1/settings`) - [Escrow](#escrow) (`/v1/escrow`) - [Webhooks](#webhooks) (`/v1/webhooks`) - [Files](#files) (`/v1/files`) - [Delivery Runs & Actions](#delivery-runs--actions) (`/v1/delivery-runs`, `/v1/delivery-actions`) - [SaaS](#saas) (`/v1/saas`) - [GitHub Integration](#github-integration) (`/v1/integrations/github`, `/v1/github/access`) - [Discord Integration](#discord-integration) (`/v1/integrations/discord`, `/v1/discord/access`) - [x402 Paid Endpoints](#x402-paid-endpoints) (`/v1/paid/*`) --- ## Conventions ### Response envelope Every successful response is wrapped in a `data` envelope: ```json { "data": } ``` 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: ```json { "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`: ```json { "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](#x402-paid-endpoints)). | | `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`: ```json { "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 ``` 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 ` on resource routes. Issue > an API key via [`POST /v1/api-keys`](#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. ```bash curl http://localhost:8787/health ``` ```json { "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: ```bash 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 | | ```bash 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"}' ``` ```json { "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.** ```bash curl -X POST http://localhost:8787/v1/auth/login \ -H "Content-Type: application/json" \ -d '{"email":"owner@acme.dev","password":"s3cret-pass"}' ``` ```json { "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. ```bash curl -X POST http://localhost:8787/v1/auth/magic-link/request \ -H "Content-Type: application/json" \ -d '{"email":"owner@acme.dev"}' ``` ```json { "data": { "ok": true, "devToken": "ml_8c1d..." } } ``` ### POST /v1/auth/magic-link/complete Consume a magic-link token and open a session. **Public.** ```bash curl -X POST http://localhost:8787/v1/auth/magic-link/complete \ -H "Content-Type: application/json" \ -d '{"token":"ml_8c1d..."}' ``` ```json { "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 `. ```bash curl http://localhost:8787/v1/auth/session \ -H "Authorization: Bearer sess_3f9a..." ``` ```json { "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 `. ```bash curl -X POST http://localhost:8787/v1/auth/logout \ -H "Authorization: Bearer sess_3f9a..." ``` ```json { "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 | `{}` | ```bash 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" }' ``` ```json { "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. ```bash curl http://localhost:8787/v1/products -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "data": [ { "id": "prod_5d2c...", "name": "Pro Repo Access", "status": "draft" } ] } ``` ### GET /v1/products/:id ```bash curl http://localhost:8787/v1/products/prod_5d2c... -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "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. ```bash curl -X POST http://localhost:8787/v1/products/prod_5d2c.../publish \ -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "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. | ```bash 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"}' ``` ```json { "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. ```bash curl http://localhost:8787/v1/products/prod_5d2c.../prices -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "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 | `{}` | ```bash 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"}' ``` ```json { "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. ```bash curl http://localhost:8787/v1/customers -H "Authorization: Bearer $SK_API_KEY" ``` ### GET /v1/customers/:id ```bash 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 | no | Buyer delivery fields. | | `ttlDays` | integer > 0 | no | | ```bash 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" }' ``` ```json { "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 ```bash 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/?promo=CODE`, and buyers can enter a code on the hosted checkout until a payment is recorded. #### Fiat pricing A price can be set in a fiat currency: `POST /v1/products/:id/prices` with `{ "displayCurrency": "EUR", "displayAmount": "29" }` (or `currency: "EUR"` on `POST /v1/merchant/products`). Checkout converts it to USDC at the live ECB rate (frankfurter service, `FX_RATES_URL`), rounded to the cent, and locks the rate on the session as `fxQuote` (currency, fiat amount, rate, USDC amount, rate date) until the session expires, so the buyer pays exactly the quoted USDC. Items in two different fiat currencies cannot share a checkout, subscriptions stay in USD, and checkout answers 503 when no valid rate is available. #### Tax When the seller turns tax on (`POST /v1/settings` with `tax: { enabled, label, sellerCountry, taxId, legalName, rates: { "DE": 1900 }, defaultRateBps, reverseCharge }`, rates in basis points), sessions add tax on top of the net price (after any promo) and `tax` records the rate, jurisdiction, net and tax amounts. `billingCountry` (ISO alpha-2) and `vatId` pick the buyer's rate; without them the seller's own country rate applies. EU business buyers in another member state with a VAT ID of the right shape get 0% (reverse charge) when the seller enables it. VAT IDs are checked for shape only. Buyers can change country and VAT ID on the hosted checkout until a payment is recorded. #### Receipts `GET /v1/public/receipts/:sessionId/pdf` (no API key; the session id is the capability, as on the hosted checkout) returns a PDF receipt for a settled checkout with line items, discount, tax rate and jurisdiction (or reverse charge), the seller's legal name and tax ID, the buyer's country and VAT ID, and the settlement transaction. The hosted checkout serves it at `/c//receipt`, the success page and receipt email link to it, and the customer portal lists it per purchase. ### POST /v1/checkout-sessions/:id/collect-fields Merge buyer-supplied delivery fields into an open session. ```bash 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"}}' ``` ```json { "data": { "id": "cs_2b7e...", "collectedFields": { "githubUsername": "octocat" } } } ``` ### POST /v1/checkout-sessions/:id/cancel ```bash curl -X POST http://localhost:8787/v1/checkout-sessions/cs_2b7e.../cancel \ -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "data": { "id": "cs_2b7e...", "status": "canceled" } } ``` ### POST /v1/checkout-sessions/:id/expire ```bash curl -X POST http://localhost:8787/v1/checkout-sessions/cs_2b7e.../expire \ -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "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 | ```bash curl -X POST http://localhost:8787/v1/payments \ -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \ -d '{"checkoutSessionId":"cs_2b7e..."}' ``` ```json { "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 ```bash 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 | ```bash 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}' ``` ```json { "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. ```bash curl -X POST http://localhost:8787/v1/payments/pay_4c9d.../fail \ -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "data": { "id": "pay_4c9d...", "status": "failed" } } ``` ### POST /v1/payments/:id/refund Refund a confirmed payment. ```bash curl -X POST http://localhost:8787/v1/payments/pay_4c9d.../refund \ -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "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 | | ```bash 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..."}' ``` ```json { "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 ```bash 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). ```bash curl -X POST http://localhost:8787/v1/subscriptions/sub_6e1a.../renew \ -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "data": { "id": "sub_6e1a...", "status": "active", "currentPeriodEnd": "2026-08-16T12:00:00.000Z" } } ``` ### POST /v1/subscriptions/:id/cancel ```bash curl -X POST http://localhost:8787/v1/subscriptions/sub_6e1a.../cancel \ -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "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. | ```bash curl "http://localhost:8787/v1/entitlements?customerId=customer_9a3b...&activeOnly=true" \ -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "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 | ```bash 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..."}' ``` ```json { "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 | ```bash 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}' ``` ```json { "data": { "id": "ent_77aa...", "creditsRemaining": 99 } } ``` ### GET /v1/entitlements/:id ```bash 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"` | ```bash 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"}' ``` ```json { "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 | | ```bash 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}' ``` ```json { "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 | ```bash 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"}' ``` ```json { "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. ```bash curl -X POST http://localhost:8787/v1/license-keys/lk_2a44.../token \ -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "data": { "token": "eyJhbGci..." } } ``` ### POST /v1/license-keys/:id/revoke ```bash curl -X POST http://localhost:8787/v1/license-keys/lk_2a44.../revoke \ -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "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"` | ```bash 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"}' ``` ```json { "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 | `[]` | ```bash 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"]}' ``` ```json { "data": { "valid": true, "apiKey": { "id": "ak_5f8b...", "scopes": ["read:data"] } } } ``` ### POST /v1/api-keys/revoke Revoke a key by its plaintext. ```bash 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..."}' ``` ```json { "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 | | ```bash 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}' ``` ```json { "data": { "code": "LAUNCH20", "discount": { "type": "percent", "percentOff": 20 }, "status": "active", "redemptionCount": 0 } } ``` ### GET /v1/coupons ```bash curl http://localhost:8787/v1/coupons -H "Authorization: Bearer $SK_API_KEY" ``` ### GET /v1/coupons/:code ```bash 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 | ```bash 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..."}' ``` ```json { "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. ```bash 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..."}' ``` ```json { "data": { "coupon": { "code": "LAUNCH20", "redemptionCount": 1 }, "total": { "amount": "80.00", "currency": "USDC" } } } ``` --- ## Access control: API key scopes and team roles Management API keys are platform keys (issued at sign-up or with `POST /v1/api-keys/platform`). Access keys delivered to buyers by a product (`api_key_create`) can never call the management API, whatever scopes the product gives them (403). Restricted keys: `POST /v1/api-keys/platform` with `{ "label": "Reporting job", "scopes": ["payments:read", "reports:read"] }` returns the secret once. Scopes are `:read` or `:write` (write includes read) over `products`, `checkout`, `payments`, `customers`, `invoices`, `webhooks`, `reports`, `settings`, `api_keys`, `team`, `agents`, `treasury` and `access` (the verify endpoints); `platform:admin` is full access. A caller can only grant scopes it holds. A missing scope answers 403 with `details.requiredScope`. `GET /v1/api-keys` lists the organization's keys (`kind`: platform or customer) and `POST /v1/api-keys/:id/revoke` revokes one. Team roles (dashboard sessions): owner and admin (full access; only an owner grants owner), developer (products, checkout, webhooks, API keys, invoices, agents; reads the rest), support (customers and payments; reads the rest except settings and keys), viewer (read only). - `GET /v1/team` lists members and open invitations. - `POST /v1/team/invitations` with `{ "email", "role" }` emails a 7-day link to `/invite/`; `POST /v1/team/invitations/:id/revoke` cancels it. - `PATCH /v1/team/members/:accountId` with `{ "role" }` and `DELETE /v1/team/members/:accountId` manage members; the last owner cannot be removed or demoted. - `POST /v1/auth/invitations/accept` (public) with `{ "token", "password"? }` joins the organization; new people set a password and get a session. ## Growth metrics `GET /v1/analytics/metrics?days=30` (1-365) returns checkout conversion (sessions opened vs paid, invoices excluded), per-payment-link stats (opened, paid, conversion, revenue), window and all-time revenue, paying and repeat customers, average revenue per customer, and subscription churn, ARPU and an estimated lifetime value (ARPU divided by monthly churn; null while nothing has churned). ## Hosted storefront `POST /v1/settings` with `store: { enabled, slug, title?, tagline?, logoUrl? (https), accentColor? (#rrggbb), seoDescription?, customDomain? }` publishes a branded page at `/store/` listing the merchant's active products; each opens its payment link. Slugs and domains are unique across merchants. Public data: `GET /v1/public/stores/:slug` and `GET /v1/public/stores/by-domain/:domain`. For a custom domain, point it at the checkout host, have the host (Railyard or Caddy) route it, and set `CHECKOUT_PRIMARY_HOSTS` on the checkout app so requests for `/` on any other host show that domain's store. Checkout still buys one product per checkout session. ## Cash out to a bank `GET /v1/merchant/offramp?network=base&amount=250` returns off-ramp partner links (Transak, MoonPay, Ramp) that open the partner's sell flow with the amount, network and the merchant's own receiving wallet prefilled. SettleKit takes no custody; the merchant sends USDC from their wallet inside the partner flow. Partners appear only when their keys are configured (`TRANSAK_API_KEY`, `MOONPAY_PUBLISHABLE_KEY` + `MOONPAY_SECRET_KEY`, `RAMP_HOST_API_KEY`); MoonPay URLs are signed server-side. ## Refund to payer Refunds are sent from the merchant's own wallet; SettleKit never holds or signs funds. - `POST /v1/merchant/payments/:id/refund/prepare` with `{ "reason", "amountUsd"?, "to"? }` creates a pending refund and returns the exact transfer to sign: on EVM networks the ERC-20 `transfer` calldata, token, chain id and an EIP-681 link; on Solana a Solana Pay transfer request with a unique reference. The destination defaults to the wallet that paid (declared payer or customer wallet); otherwise pass `to`. The amount defaults to what is still refundable. - `POST /v1/merchant/refunds/:id/confirm` with `{ "txHash", "revokeAccess"? }` verifies the transfer onchain (destination, amount, not before the refund, Solana reference) with the payment verifiers. Only then is the refund marked succeeded, access revoked, the payment marked refunded once fully refunded, and `refund.succeeded` sent with `source: "wallet"`. A transaction can settle one refund only. - `POST /v1/merchant/refunds/:id/cancel` drops a pending refund. HyperCore and Zcash refunds stay record-only (`POST /v1/merchant/payments/:id/refund` with the transaction hash). The vendored `apps/refund-protocol` escrow is not wired (known arbiter issue upstream). ## Accounting exports `/v1/exports` — **Auth required.** Tenant-scoped CSV downloads. Optional `?from=YYYY-MM-DD&to=YYYY-MM-DD` (to is exclusive). Every text cell is guarded against spreadsheet formula injection. - `GET /v1/exports/payments.csv`, `refunds.csv`, `invoices.csv`, `payouts.csv`: one row per record. - `GET /v1/exports/ledger.csv`: every USDC wallet movement (payments in, succeeded refunds out) with network and transaction hash. - `GET /v1/exports/xero.csv`: Xero bank statement import (`*Date` as DD/MM/YYYY, `*Amount`, Payee, Description, Reference). In Xero, create a bank account named "USDC wallet", then use Import a statement. - `GET /v1/exports/quickbooks.csv`: QuickBooks Online bank upload, three columns (Date as MM/DD/YYYY, Description, Amount). In QuickBooks, go to Banking, Upload transactions, and pick the USDC account. The dashboard links all of them from the Payments page. ## Platform fee statements `/v1/billing` — **Auth required.** SettleKit's per-payment fee is billed once a month. When `PLATFORM_BILLING_ORG_ID` is set, the API issues each merchant a statement for the previous month (confirmed payments x the fee schedule) as an invoice from the platform org, paid through the hosted checkout like any invoice. Totals below `PLATFORM_BILLING_MIN_USD` roll into the next month. A statement left unpaid past its due date plus `PLATFORM_BILLING_GRACE_DAYS` limits new products to the free plan until it is paid (`402 payment_required` with the pay link). - `GET /v1/billing/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 | no | | ```bash 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} }' ``` ```json { "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 | ```bash curl "http://localhost:8787/v1/invoices?customerId=customer_9a3b..." -H "Authorization: Bearer $SK_API_KEY" ``` ### GET /v1/invoices/:id ```bash 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). ```bash curl http://localhost:8787/v1/invoices/inv_3c7d....html -H "Authorization: Bearer $SK_API_KEY" ``` ### POST /v1/invoices/:id/finalize `draft → open`. ```bash curl -X POST http://localhost:8787/v1/invoices/inv_3c7d.../finalize -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "data": { "id": "inv_3c7d...", "status": "open" } } ``` ### POST /v1/invoices/:id/pay `open → paid`. ```bash curl -X POST http://localhost:8787/v1/invoices/inv_3c7d.../pay -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "data": { "id": "inv_3c7d...", "status": "paid" } } ``` ### POST /v1/invoices/:id/void `draft|open → void`. ```bash curl -X POST http://localhost:8787/v1/invoices/inv_3c7d.../void -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "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 (`/i/`), 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. ```bash 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"}' ``` ```json { "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. ```bash 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. | ```bash 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"}' ``` ```json { "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 | ```bash curl "http://localhost:8787/v1/refunds?paymentId=pay_4c9d..." -H "Authorization: Bearer $SK_API_KEY" ``` ### POST /v1/refunds/:id/succeed `pending → succeeded`. ```bash curl -X POST http://localhost:8787/v1/refunds/ref_9d2e.../succeed -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "data": { "id": "ref_9d2e...", "status": "succeeded" } } ``` ### POST /v1/refunds/:id/fail `pending → failed`. | Field | Type | Required | |-------|------|----------| | `reason` | string | no | ```bash 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"}' ``` ```json { "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 | ```bash curl -X POST http://localhost:8787/v1/dunning \ -H "Authorization: Bearer $SK_API_KEY" -H "Content-Type: application/json" \ -d '{"subscriptionId":"sub_6e1a..."}' ``` ```json { "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`). ```bash 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 | ```bash 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"}' ``` ```json { "data": { "subscriptionId": "sub_6e1a...", "status": "active", "attempts": 1 } } ``` ### POST /v1/dunning/:subscriptionId/recover Mark a campaign recovered. ```bash curl -X POST http://localhost:8787/v1/dunning/sub_6e1a.../recover -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "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 | ```bash 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"}' ``` ```json { "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. ```bash curl "http://localhost:8787/v1/disputes?status=open" -H "Authorization: Bearer $SK_API_KEY" ``` ### GET /v1/disputes/:id ```bash 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 | ```bash 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"}' ``` ```json { "data": { "id": "dsp_1f4a...", "status": "under_review", "evidence": [ { "kind": "text" } ] } } ``` ### POST /v1/disputes/:id/resolve | Field | Type | Required | |-------|------|----------| | `outcome` | `won` \| `lost` \| `refunded` | yes | ```bash 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"}' ``` ```json { "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 | ```bash 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"}' ``` ```json { "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. ```bash 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 | ```bash curl "http://localhost:8787/v1/payouts/balance?organizationId=org_1" -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "data": { "available": { "amount": "1250.00", "currency": "USDC" } } } ``` ### POST /v1/payouts/:id/paid Mark paid with an on-chain `txHash`. ```bash 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..."}' ``` ```json { "data": { "id": "po_8a2c...", "status": "paid", "txHash": "0xpayout..." } } ``` ### POST /v1/payouts/:id/fail | Field | Type | Required | |-------|------|----------| | `reason` | string | no | ```bash 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"}' ``` ```json { "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 | | ```bash 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"}' ``` ```json { "data": { "id": "bndl_4f2a...", "name": "Starter Pack", "productIds": ["prod_5d2c...","prod_8e1f..."], "status": "draft" } } ``` ### GET /v1/bundles With `?organizationId=` filters to one org. ```bash curl "http://localhost:8787/v1/bundles?organizationId=org_1" -H "Authorization: Bearer $SK_API_KEY" ``` ### GET /v1/bundles/:id ```bash 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 | ```bash 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"}' ``` ```json { "data": { "id": "bndl_4f2a...", "name": "Starter Pack 2026", "status": "draft" } } ``` ### POST /v1/bundles/:id/publish ```bash curl -X POST http://localhost:8787/v1/bundles/bndl_4f2a.../publish -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "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 | | ```bash 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"} }' ``` ```json { "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. ```bash curl "http://localhost:8787/v1/agent-services?organizationId=org_1" -H "Authorization: Bearer $SK_API_KEY" ``` ### GET /v1/agent-services/:id ```bash 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 | ```bash 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 ```bash curl -X POST http://localhost:8787/v1/agent-services/agsvc_2c8d.../publish -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "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. ```bash curl http://localhost:8787/v1/agent-services/agsvc_2c8d.../metadata.json \ -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "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 | `[]` | ```bash 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"]}' ``` ```json { "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`). ```bash curl "http://localhost:8787/v1/marketplace/listings?q=repo&tag=devtools&sort=top" \ -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "data": [ { "id": "lst_7d3a...", "title": "Pro Repo", "ratingAvg": 4.5 } ] } ``` ### GET /v1/marketplace/listings/:id ```bash curl http://localhost:8787/v1/marketplace/listings/lst_7d3a... -H "Authorization: Bearer $SK_API_KEY" ``` ### POST /v1/marketplace/listings/:id/publish ```bash curl -X POST http://localhost:8787/v1/marketplace/listings/lst_7d3a.../publish -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "data": { "id": "lst_7d3a...", "status": "published" } } ``` ### POST /v1/marketplace/listings/:id/unpublish ```bash curl -X POST http://localhost:8787/v1/marketplace/listings/lst_7d3a.../unpublish -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "data": { "id": "lst_7d3a...", "status": "draft" } } ``` ### POST /v1/marketplace/listings/:id/rate | Field | Type | Required | |-------|------|----------| | `stars` | integer 1-5 | yes | ```bash 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}' ``` ```json { "data": { "id": "lst_7d3a...", "ratingAvg": 4.7, "ratingCount": 11 } } ``` ### GET /v1/marketplace/sellers/:merchantId Aggregate seller profile. ```bash curl http://localhost:8787/v1/marketplace/sellers/acct_01H... -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "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 | ```bash 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}' ``` ```json { "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). ```bash 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" ``` ```json { "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 | ```bash 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"}' ``` ```json { "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 | ```bash 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}' ``` ```json { "data": { "used": 5, "limit": 1000, "withinLimit": true } } ``` ### GET /v1/usage/credits Read a prepaid balance. Query params: `organizationId`, `customerId`, `productId` (all required). ```bash curl "http://localhost:8787/v1/usage/credits?organizationId=org_1&customerId=customer_9a3b...&productId=prod_api..." \ -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "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 | ```bash 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}' ``` ```json { "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` | ```bash 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}' ``` ```json { "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). ```bash curl "http://localhost:8787/v1/analytics/summary?organizationId=org_1" \ -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "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). ```bash curl "http://localhost:8787/v1/settings?organizationId=org_1" -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "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 | ```bash 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"}' ``` ```json { "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"` | ```bash 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"}' ``` ```json { "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**. ```bash curl "http://localhost:8787/v1/escrow/tasks?organizationId=org_1" -H "Authorization: Bearer $SK_API_KEY" ``` ### GET /v1/escrow/tasks/:id ```bash 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 | ```bash 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..."}' ``` ```json { "data": { "id": "esc_3a9c...", "status": "funded", "fundingTxHash": "0xfund..." } } ``` ### POST /v1/escrow/tasks/:id/assign | Field | Type | Required | |-------|------|----------| | `workerCustomerId` | string | yes | ```bash 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..."}' ``` ```json { "data": { "id": "esc_3a9c...", "status": "assigned", "workerCustomerId": "customer_worker..." } } ``` ### POST /v1/escrow/tasks/:id/submit | Field | Type | Required | |-------|------|----------| | `content` | string | yes | ```bash 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"}' ``` ```json { "data": { "id": "esc_3a9c...", "status": "submitted" } } ``` ### POST /v1/escrow/tasks/:id/approve No body. ```bash curl -X POST http://localhost:8787/v1/escrow/tasks/esc_3a9c.../approve -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "data": { "id": "esc_3a9c...", "status": "approved" } } ``` ### POST /v1/escrow/tasks/:id/release | Field | Type | Required | |-------|------|----------| | `releaseTxHash` | string | yes | ```bash 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..."}' ``` ```json { "data": { "id": "esc_3a9c...", "status": "released", "releaseTxHash": "0xrelease..." } } ``` ### POST /v1/escrow/tasks/:id/refund | Field | Type | Required | Default | |-------|------|----------|---------| | `reason` | string | no | `"refunded via API"` | ```bash 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"}' ``` ```json { "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) | ```bash 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"]}' ``` ```json { "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. ```bash 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 | `{}` | ```bash 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..."}}' ``` ```json { "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. ```bash curl "http://localhost:8787/v1/webhooks/events?organizationId=org_1" -H "Authorization: Bearer $SK_API_KEY" ``` ### GET /v1/webhooks/events/:id ```bash 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 | ```bash 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}' ``` ```json { "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 | ```bash 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" ``` ```json { "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. ```bash curl "http://localhost:8787/v1/delivery-runs?organizationId=org_1&paymentId=pay_4c9d..." \ -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "data": [ { "id": "dr_4f8a...", "paymentId": "pay_4c9d...", "status": "succeeded", "actionRuns": [] } ] } ``` ### GET /v1/delivery-runs/:id ```bash 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. ```bash curl -X POST http://localhost:8787/v1/delivery-runs/dr_4f8a.../retry -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "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) | | `webhook_send` | `url` | | `email_send` | `template` | ```bash 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"} }' ``` ```json { "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 | no | `{}` | | `seats` | integer ≥ 0 | no | `1` | ```bash 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}' ``` ```json { "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. ```bash 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 | | ```bash 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..."}' ``` ```json { "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 | ```bash 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"}' ``` ```json { "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 | ```bash 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..."}' ``` ```json { "data": { "seats": [ { "userId": "user_42" } ] } } ``` ### POST /v1/saas/seats/remove Release a seat. | Field | Type | Required | |-------|------|----------| | `customerId` | string | yes | | `userId` | string | yes | ```bash 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"}' ``` ```json { "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 | ```bash 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"}' ``` ```json { "data": { "id": "ghi_2a4c...", "installationId": 12345, "accountLogin": "acme", "accountType": "Organization" } } ``` ### GET /v1/integrations/github/installations With `?organizationId=` filters to one org. ```bash 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). ```bash curl http://localhost:8787/v1/integrations/github/repositories -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "data": [ { "owner": "acme", "name": "private-repo", "fullName": "acme/private-repo" } ] } ``` ### GET /v1/integrations/github/teams Org teams synthesized from organization installations. With `?organizationId=` filters. ```bash curl "http://localhost:8787/v1/integrations/github/teams?organizationId=org_1" -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "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 | ```bash 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" }' ``` ```json { "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 | ```bash 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..."}' ``` ```json { "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 | ```bash 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"}' ``` ```json { "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 | ```bash 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"}' ``` ```json { "data": { "id": "dcon_3f9a...", "guildId": "99887766", "guildName": "Acme Community" } } ``` ### GET /v1/integrations/discord/guilds List guilds the bot is in. ```bash curl http://localhost:8787/v1/integrations/discord/guilds -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "data": [ { "id": "99887766", "name": "Acme Community" } ] } ``` ### GET /v1/integrations/discord/roles List assignable roles for a guild. Query param `guildId` is **required**. ```bash curl "http://localhost:8787/v1/integrations/discord/roles?guildId=99887766" -H "Authorization: Bearer $SK_API_KEY" ``` ```json { "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 | ```bash 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" }' ``` ```json { "data": { "id": "dgr_6a2c...", "guildId": "99887766", "roleId": "role_paid", "discordUserId": "557799", "status": "active" } } ``` ### POST /v1/discord/access/revoke | Field | Type | Required | |-------|------|----------| | `grantId` | string | yes | ```bash 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..."}' ``` ```json { "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:** ```bash 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..."} ``` ```json { "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: ```json { "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))`: ```bash 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`): ```json { "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.: ```json { "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)" } ```