# 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" ``` ### 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" } } } ``` --- ## 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" } } ``` --- ## 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)" } ```