GET /v1/analytics/metrics computes, from live sessions, payments, subscriptions and catalog: checkout conversion, per-payment-link opened / paid / conversion / revenue, repeat customers, average revenue per customer, subscription churn, ARPU and an estimated lifetime value, with exact bigint money. Checkout repositories gain listCreatedSince (in-memory and Postgres). The dashboard Analytics page shows the new cards and a payment-link table. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2930 lines
89 KiB
Markdown
2930 lines
89 KiB
Markdown
# 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": <payload> }
|
|
```
|
|
|
|
Mutations that create a resource return HTTP `201 Created`; reads and other
|
|
mutations return HTTP `200 OK`. Two endpoints return raw (non-enveloped)
|
|
payloads by design and are noted inline:
|
|
|
|
- `GET /v1/agent-services/:id/metadata.json` — raw machine-readable metadata JSON.
|
|
- `GET /v1/invoices/:id.html` — rendered HTML (`text/html`).
|
|
|
|
### Error envelope
|
|
|
|
Every error response uses the `error` envelope:
|
|
|
|
```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 <apiKey>
|
|
```
|
|
|
|
Two route groups are intentionally **public** (no API key):
|
|
|
|
- `/v1/auth/*` — sign-up / sign-in use a **session token**, not an API key.
|
|
- `/v1/paid/*` — x402 paid endpoints; the USDC payment itself is the
|
|
authorization. They return `402 Payment Required` until paid.
|
|
|
|
For local development and tests a bootstrap key can be configured via the
|
|
`API_BOOTSTRAP_KEY` environment variable; presenting it as the Bearer token
|
|
authenticates without any key existing in the store.
|
|
|
|
> The session token returned by `/v1/auth/login` is **not** an API key and
|
|
> cannot be used as `Authorization: Bearer <apiKey>` on resource routes. Issue
|
|
> an API key via [`POST /v1/api-keys`](#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 <sessionToken>`.
|
|
|
|
```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 <sessionToken>`.
|
|
|
|
```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<string,string> | 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/<slug>?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/<sessionId>/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 `<resource>:read` or `<resource>: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 `<DASHBOARD_PUBLIC_URL>/invite/<token>`; `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 `<checkout>/store/<slug>` 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<string,string> | 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 (`<CHECKOUT_PUBLIC_URL>/i/<token>`), opens a checkout session for the invoice total on the merchant's accepted networks, and emails the link (when `RESEND_API_KEY` is set). Idempotent: re-sending keeps the same link. Requires a receiving wallet in payment settings.
|
|
|
|
```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<string, boolean\|number\|string>) |
|
|
| `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<string, boolean\|number> | 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)"
|
|
}
|
|
```
|