> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usespoke.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Merchants, products, and campaigns
> Merchant profiles, product records and assets, campaign drafts and publication, and policy simulation.
Merchant profiles, product records and assets, campaign drafts and publication, and policy simulation.
This reference is generated from application commit [`1c90c5e`](https://github.com/Enoch208/spoke/commit/1c90c5e408592d5b4e87944ea79b998890633249). It covers **30 client methods** in this group.
Input schemas describe the typed client call before path/query/body mapping.
Output schemas describe the envelope's `data`, not the full HTTP response.
Custom refinements, transforms, and runtime permissions are enforced by the
[shared Zod
contract](https://github.com/Enoch208/spoke/tree/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api).
Read [transport rules](/developers/http-transport) before copying a client
object into an HTTP body. Designed methods reject live calls; optional funding
still requires provider configuration.
[Download all method schemas](https://raw.githubusercontent.com/Enoch208/docs-madonna/main/schemas/client-methods.json) · [Live endpoint registry](https://api.usespoke.xyz/v1/system/endpoints)
## Methods at a glance
| Client method | HTTP route | Access | Availability |
| - | - | - | - |
| [`campaigns.list`](#campaigns-list) | `GET /v1/campaigns` | public | Core live |
| [`campaigns.get`](#campaigns-get) | `GET /v1/campaigns/:campaignId` | public | Core live |
| [`campaigns.policy`](#campaigns-policy) | `GET /v1/campaigns/:campaignId/policy` | public | Core live |
| [`campaigns.stats`](#campaigns-stats) | `GET /v1/campaigns/:campaignId/stats` | public | Core live |
| [`campaigns.activity`](#campaigns-activity) | `GET /v1/campaigns/:campaignId/activity` | public | Core live |
| [`campaigns.mine`](#campaigns-mine) | `GET /v1/merchant/campaigns` | session | Core live |
| [`campaigns.saveDraft`](#campaigns-savedraft) | `PUT /v1/merchant/campaign-drafts/:id` | session | Core live |
| [`campaigns.getDraft`](#campaigns-getdraft) | `GET /v1/merchant/campaign-drafts/:id` | session | Core live |
| [`campaigns.deleteDraft`](#campaigns-deletedraft) | `DELETE /v1/merchant/campaign-drafts/:id` | session | Core live |
| [`campaigns.prepareCreate`](#campaigns-preparecreate) | `POST /v1/merchant/campaign-drafts/:id/prepare` | session | Core live |
| [`campaigns.updateSettings`](#campaigns-updatesettings) | `PATCH /v1/merchant/campaigns/:campaignId/settings` | session | Core live |
| [`campaigns.distributors`](#campaigns-distributors) | `GET /v1/merchant/campaigns/:campaignId/distributors` | session | Core live |
| [`products.list`](#products-list) | `GET /v1/merchant/products` | session | Core live |
| [`products.get`](#products-get) | `GET /v1/products/:id` | public | Core live |
| [`products.save`](#products-save) | `PUT /v1/merchant/products/:id` | session | Core live |
| [`products.uploadAsset`](#products-uploadasset) | `POST /v1/merchant/products/:id/assets` | session | Core live |
| [`products.categories`](#products-categories) | `GET /v1/categories` | public | Core live |
| [`merchants.get`](#merchants-get) | `GET /v1/merchants/:slug` | public | Core live |
| [`merchants.record`](#merchants-record) | `GET /v1/merchants/:slug/record` | public | Core live |
| [`merchants.me`](#merchants-me) | `GET /v1/merchant` | session | Core live |
| [`merchants.setup`](#merchants-setup) | `POST /v1/merchant` | session | Core live |
| [`merchants.update`](#merchants-update) | `PATCH /v1/merchant` | session | Core live |
| [`merchants.slugAvailable`](#merchants-slugavailable) | `GET /v1/merchant-slugs/:slug` | session | Core live |
| [`merchants.uploadLogo`](#merchants-uploadlogo) | `POST /v1/merchant/logo` | session | Core live |
| [`merchants.requestVerification`](#merchants-requestverification) | `POST /v1/merchant/verification` | session | Designed — unavailable |
| [`merchants.close`](#merchants-close) | `POST /v1/merchant/close` | session | Core live |
| [`merchants.offers`](#merchants-offers) | `GET /v1/merchants/:slug/offers` | public | Core live |
| [`studio.templates`](#studio-templates) | `GET /v1/merchant/policy-templates` | session | Core live |
| [`studio.saveTemplate`](#studio-savetemplate) | `POST /v1/merchant/policy-templates` | session | Core live |
| [`studio.simulate`](#studio-simulate) | `POST /v1/policies/simulate` | public | Core live |
## campaigns.list
**GET `/v1/campaigns`** · **Core live** · Access: **public**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L208).
**Client input fields**
| Field | Type | Required | Constraints |
| - | - | - | - |
| `cursor` | string | No | See nested schema and runtime validation |
| `limit` | integer | No | Minimum: 1; Maximum: 100 |
| `q` | string | No | Max length: 200 |
| `category` | string | No | See nested schema and runtime validation |
| `rateMin` | integer | No | Minimum: 1; Maximum: 10000 |
| `rateMax` | integer | No | Minimum: 1; Maximum: 10000 |
| `levels` | integer | No | Minimum: 1; Maximum: 5 |
| `holdMax` | integer | No | Minimum: 0; Maximum: 9007199254740991 |
| `budgetLeftMin` | string | No | Max length: 78; Pattern validated; see input schema |
| `source` | "NATIVE\_ONCHAIN" · "MERCHANT\_ATTESTED" · "THIRD\_PARTY\_VERIFIED" | No | See nested schema and runtime validation |
| `invitationOnly` | boolean | No | See nested schema and runtime validation |
| `excludeJoined` | boolean | No | See nested schema and runtime validation |
| `status` | "active" · "not\_live" · "paused" · "ended" · "expired" | No | See nested schema and runtime validation |
| `merchant` | string | No | See nested schema and runtime validation |
| `sort` | "balanced" · "newest" · "reward" · "budget" · "hold" | No | See nested schema and runtime validation |
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"cursor": {
"type": "string"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"q": {
"type": "string",
"maxLength": 200
},
"category": {
"type": "string"
},
"rateMin": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"rateMax": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"levels": {
"type": "integer",
"minimum": 1,
"maximum": 5
},
"holdMax": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"budgetLeftMin": {
"type": "string",
"maxLength": 78,
"pattern": "^(0|[1-9]\\d*)$"
},
"source": {
"type": "string",
"enum": ["NATIVE_ONCHAIN", "MERCHANT_ATTESTED", "THIRD_PARTY_VERIFIED"]
},
"invitationOnly": {
"type": "boolean"
},
"excludeJoined": {
"type": "boolean"
},
"status": {
"type": "string",
"enum": ["active", "not_live", "paused", "ended", "expired"]
},
"merchant": {
"type": "string"
},
"sort": {
"type": "string",
"enum": ["balanced", "newest", "reward", "budget", "hold"]
}
}
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"campaignId": {
"anyOf": [
{
"$ref": "#/$defs/__schema0"
},
{
"type": "string",
"pattern": "^demo-[\\w-]+$"
}
]
},
"chainId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"contractAddress": {
"$ref": "#/$defs/__schema1"
},
"state": {
"type": "string",
"enum": [
"DRAFT_OFFCHAIN",
"CREATED_UNFUNDED",
"FUNDED_ACTIVE",
"PAUSED",
"ENDED",
"EXPIRED"
]
},
"merchant": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"address": {
"$ref": "#/$defs/__schema1"
}
},
"required": ["name", "slug", "address"],
"additionalProperties": false
},
"product": {
"type": "object",
"properties": {
"id": {
"$ref": "#/$defs/__schema2"
},
"title": {
"type": "string"
},
"summary": {
"type": "string"
},
"media": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"$ref": "#/$defs/__schema2"
},
"kind": {
"type": "string",
"enum": ["image", "download"]
},
"size": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"sha256": {
"type": "string",
"pattern": "^[\\da-f]{64}$"
},
"url": {
"type": "string",
"format": "uri"
},
"width": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"height": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": ["id", "kind", "size", "sha256"],
"additionalProperties": false
}
},
"category": {
"type": "string"
}
},
"required": ["id", "title", "summary", "media", "category"],
"additionalProperties": false
},
"token": {
"type": "object",
"properties": {
"address": {
"$ref": "#/$defs/__schema1"
},
"symbol": {
"type": "string"
},
"decimals": {
"type": "integer",
"minimum": 0,
"maximum": 36
},
"name": {
"type": "string"
},
"testnet": {
"type": "boolean"
}
},
"required": ["address", "symbol", "decimals"],
"additionalProperties": false
},
"price": {
"$ref": "#/$defs/__schema0"
},
"policy": {
"type": "object",
"properties": {
"rewardToken": {
"$ref": "#/$defs/__schema1"
},
"commissionBps": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"perSaleCap": {
"$ref": "#/$defs/__schema0"
},
"campaignLiabilityCap": {
"$ref": "#/$defs/__schema0"
},
"maxRewardedAncestors": {
"type": "integer",
"minimum": 1,
"maximum": 5
},
"weightsBps": {
"minItems": 1,
"maxItems": 5,
"type": "array",
"items": {
"$ref": "#/$defs/__schema3"
}
},
"shortPathMode": {
"default": "RENORMALIZE_EXISTING",
"type": "string",
"enum": ["RENORMALIZE_EXISTING", "RETURN_UNUSED"]
},
"holdSeconds": {
"type": "integer",
"minimum": 60,
"maximum": 7776000
},
"expiry": {
"$ref": "#/$defs/__schema0"
},
"eligibilityHash": {
"$ref": "#/$defs/__schema4"
},
"policyHash": {
"$ref": "#/$defs/__schema4"
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"effectiveAt": {
"$ref": "#/$defs/__schema5"
},
"regions": {
"type": "array",
"items": {
"type": "string"
}
},
"sharingRules": {
"type": "array",
"items": {
"type": "string"
}
},
"registrationTx": {
"anyOf": [
{
"type": "object",
"properties": {
"hash": {
"$ref": "#/$defs/__schema4"
},
"blockNumber": {
"$ref": "#/$defs/__schema0"
},
"explorerUrl": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"at": {
"$ref": "#/$defs/__schema5"
}
},
"required": ["hash", "blockNumber", "explorerUrl"],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"salesCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"rewardToken",
"commissionBps",
"perSaleCap",
"campaignLiabilityCap",
"maxRewardedAncestors",
"weightsBps",
"shortPathMode",
"holdSeconds",
"expiry",
"eligibilityHash",
"policyHash",
"version",
"effectiveAt",
"regions",
"sharingRules"
],
"additionalProperties": false
},
"rewardAvailable": {
"$ref": "#/$defs/__schema0"
},
"rewardTotal": {
"$ref": "#/$defs/__schema0"
},
"settledSales": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"onchainUrl": {
"type": "string",
"format": "uri"
},
"rankReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"inviteOnly": {
"type": "boolean"
},
"endsAt": {
"$ref": "#/$defs/__schema5"
}
},
"required": [
"campaignId",
"chainId",
"contractAddress",
"state",
"merchant",
"product",
"token",
"price",
"policy",
"rewardAvailable",
"rewardTotal",
"settledSales",
"onchainUrl",
"rankReasons"
],
"additionalProperties": false
}
},
"nextCursor": {
"type": ["string", "null"]
},
"total": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": ["items", "nextCursor", "total"],
"additionalProperties": false,
"$defs": {
"__schema0": {
"type": "string"
},
"__schema1": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"__schema2": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9_-]+$"
},
"__schema3": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema4": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{64}$"
},
"__schema5": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
}
}
}
```
## campaigns.get
**GET `/v1/campaigns/:campaignId`** · **Core live** · Access: **public**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L212).
**Client input fields**
| Field | Type | Required | Constraints |
| - | - | - | - |
| `campaignId` | string | Yes | See nested schema and runtime validation |
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"campaignId": {
"anyOf": [
{
"type": "string",
"maxLength": 78,
"pattern": "^(0|[1-9]\\d*)$"
},
{
"type": "string",
"pattern": "^demo-[\\w-]+$"
}
]
}
},
"required": ["campaignId"]
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"campaignId": {
"$ref": "#/$defs/__schema0"
},
"chainId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"contractAddress": {
"$ref": "#/$defs/__schema2"
},
"state": {
"type": "string",
"enum": [
"DRAFT_OFFCHAIN",
"CREATED_UNFUNDED",
"FUNDED_ACTIVE",
"PAUSED",
"ENDED",
"EXPIRED"
]
},
"merchant": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"address": {
"$ref": "#/$defs/__schema2"
}
},
"required": ["name", "slug", "address"],
"additionalProperties": false
},
"product": {
"type": "object",
"properties": {
"id": {
"$ref": "#/$defs/__schema3"
},
"merchantId": {
"$ref": "#/$defs/__schema3"
},
"title": {
"type": "string"
},
"summary": {
"type": "string"
},
"outcome": {
"type": "string"
},
"description": {
"type": "string"
},
"media": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"$ref": "#/$defs/__schema3"
},
"kind": {
"type": "string",
"enum": ["image", "download"]
},
"size": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"sha256": {
"type": "string",
"pattern": "^[\\da-f]{64}$"
},
"url": {
"type": "string",
"format": "uri"
},
"width": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"height": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": ["id", "kind", "size", "sha256"],
"additionalProperties": false
}
},
"priceBaseUnits": {
"$ref": "#/$defs/__schema1"
},
"token": {
"$ref": "#/$defs/__schema4"
},
"category": {
"type": "string"
},
"fulfillmentMode": {
"type": "string",
"enum": ["download", "external", "manual"]
},
"deliverable": {
"type": "string",
"minLength": 1,
"maxLength": 2048
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"skuHash": {
"$ref": "#/$defs/__schema5"
},
"refundPolicy": {
"type": "string"
},
"variants": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"$ref": "#/$defs/__schema3"
},
"name": {
"type": "string"
},
"priceBaseUnits": {
"$ref": "#/$defs/__schema1"
}
},
"required": ["id", "name", "priceBaseUnits"],
"additionalProperties": false
}
},
"billingPeriod": {
"anyOf": [
{
"type": "string",
"enum": ["monthly", "yearly"]
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": ["draft", "ready", "archived"]
},
"missing": {
"type": "array",
"items": {
"type": "string",
"enum": [
"title",
"outcome",
"description",
"category",
"cover",
"coverAlt",
"price",
"deliverable"
]
}
},
"coverUrl": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"coverAlt": {
"type": ["string", "null"]
},
"accessTiming": {
"type": "string",
"enum": ["afterPurchase", "afterHold"]
},
"liveCampaignCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"usedBy": {
"type": "array",
"items": {
"type": "object",
"properties": {
"campaignId": {
"$ref": "#/$defs/__schema0"
},
"name": {
"type": "string"
},
"state": {
"type": "string",
"enum": [
"DRAFT_OFFCHAIN",
"CREATED_UNFUNDED",
"FUNDED_ACTIVE",
"PAUSED",
"ENDED",
"EXPIRED"
]
},
"productVersion": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": ["campaignId", "name", "state", "productVersion"],
"additionalProperties": false
}
},
"updatedAt": {
"$ref": "#/$defs/__schema6"
}
},
"required": [
"id",
"merchantId",
"title",
"summary",
"outcome",
"description",
"media",
"priceBaseUnits",
"token",
"category",
"fulfillmentMode",
"version",
"skuHash",
"refundPolicy",
"variants",
"billingPeriod"
],
"additionalProperties": false
},
"token": {
"$ref": "#/$defs/__schema4"
},
"price": {
"$ref": "#/$defs/__schema1"
},
"policy": {
"type": "object",
"properties": {
"rewardToken": {
"$ref": "#/$defs/__schema2"
},
"commissionBps": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"perSaleCap": {
"$ref": "#/$defs/__schema1"
},
"campaignLiabilityCap": {
"$ref": "#/$defs/__schema1"
},
"maxRewardedAncestors": {
"type": "integer",
"minimum": 1,
"maximum": 5
},
"weightsBps": {
"minItems": 1,
"maxItems": 5,
"type": "array",
"items": {
"$ref": "#/$defs/__schema7"
}
},
"shortPathMode": {
"default": "RENORMALIZE_EXISTING",
"type": "string",
"enum": ["RENORMALIZE_EXISTING", "RETURN_UNUSED"]
},
"holdSeconds": {
"type": "integer",
"minimum": 60,
"maximum": 7776000
},
"expiry": {
"$ref": "#/$defs/__schema1"
},
"eligibilityHash": {
"$ref": "#/$defs/__schema5"
},
"policyHash": {
"$ref": "#/$defs/__schema5"
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"effectiveAt": {
"$ref": "#/$defs/__schema6"
},
"regions": {
"type": "array",
"items": {
"type": "string"
}
},
"sharingRules": {
"type": "array",
"items": {
"type": "string"
}
},
"registrationTx": {
"anyOf": [
{
"$ref": "#/$defs/__schema8"
},
{
"type": "null"
}
]
},
"salesCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"rewardToken",
"commissionBps",
"perSaleCap",
"campaignLiabilityCap",
"maxRewardedAncestors",
"weightsBps",
"shortPathMode",
"holdSeconds",
"expiry",
"eligibilityHash",
"policyHash",
"version",
"effectiveAt",
"regions",
"sharingRules"
],
"additionalProperties": false
},
"rewardAvailable": {
"$ref": "#/$defs/__schema1"
},
"rewardTotal": {
"$ref": "#/$defs/__schema1"
},
"settledSales": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"onchainUrl": {
"type": "string",
"format": "uri"
},
"rankReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"inviteOnly": {
"type": "boolean"
},
"endsAt": {
"$ref": "#/$defs/__schema6"
},
"rewardLedger": {
"type": "object",
"properties": {
"netDeposited": {
"$ref": "#/$defs/__schema1"
},
"available": {
"$ref": "#/$defs/__schema1"
},
"pendingReserved": {
"$ref": "#/$defs/__schema1"
},
"vestedUnclaimed": {
"$ref": "#/$defs/__schema1"
},
"rewardsClaimed": {
"$ref": "#/$defs/__schema1"
},
"surplusWithdrawn": {
"$ref": "#/$defs/__schema1"
}
},
"required": [
"netDeposited",
"available",
"pendingReserved",
"vestedUnclaimed",
"rewardsClaimed",
"surplusWithdrawn"
],
"additionalProperties": false
},
"proceedsLedger": {
"type": "object",
"properties": {
"proceedsPending": {
"$ref": "#/$defs/__schema1"
},
"proceedsClaimable": {
"$ref": "#/$defs/__schema1"
},
"proceedsClaimed": {
"$ref": "#/$defs/__schema1"
},
"buyerRefunded": {
"$ref": "#/$defs/__schema1"
}
},
"required": [
"proceedsPending",
"proceedsClaimable",
"proceedsClaimed",
"buyerRefunded"
],
"additionalProperties": false
},
"startsAt": {
"$ref": "#/$defs/__schema6"
},
"counts": {
"type": "object",
"properties": {
"pending": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"finalized": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"refunded": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": ["pending", "finalized", "refunded"],
"additionalProperties": false
},
"nodeCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"moderation": {
"type": "object",
"properties": {
"hidden": {
"type": "boolean"
},
"reason": {
"type": ["string", "null"]
}
},
"required": ["hidden", "reason"],
"additionalProperties": false
},
"capacity": {
"type": "object",
"properties": {
"nodes": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"sales": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": ["nodes", "sales"],
"additionalProperties": false
},
"trustMode": {
"type": "string",
"enum": ["NATIVE_ONCHAIN", "MERCHANT_ATTESTED", "THIRD_PARTY_VERIFIED"]
},
"creationTx": {
"$ref": "#/$defs/__schema8"
},
"fundingTxs": {
"type": "array",
"items": {
"$ref": "#/$defs/__schema8"
}
},
"indexedAt": {
"anyOf": [
{
"$ref": "#/$defs/__schema6"
},
{
"type": "null"
}
]
},
"metadataHash": {
"$ref": "#/$defs/__schema5"
}
},
"required": [
"campaignId",
"chainId",
"contractAddress",
"state",
"merchant",
"product",
"token",
"price",
"policy",
"rewardAvailable",
"rewardTotal",
"settledSales",
"onchainUrl",
"rankReasons",
"inviteOnly",
"endsAt",
"rewardLedger",
"proceedsLedger",
"startsAt",
"counts",
"nodeCount",
"moderation",
"capacity",
"trustMode",
"creationTx",
"fundingTxs",
"indexedAt"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"anyOf": [
{
"$ref": "#/$defs/__schema1"
},
{
"type": "string",
"pattern": "^demo-[\\w-]+$"
}
]
},
"__schema1": {
"type": "string"
},
"__schema2": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"__schema3": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9_-]+$"
},
"__schema4": {
"type": "object",
"properties": {
"address": {
"$ref": "#/$defs/__schema2"
},
"symbol": {
"type": "string"
},
"decimals": {
"type": "integer",
"minimum": 0,
"maximum": 36
},
"name": {
"type": "string"
},
"testnet": {
"type": "boolean"
}
},
"required": ["address", "symbol", "decimals"],
"additionalProperties": false
},
"__schema5": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{64}$"
},
"__schema6": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
"__schema7": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema8": {
"type": "object",
"properties": {
"hash": {
"$ref": "#/$defs/__schema5"
},
"blockNumber": {
"$ref": "#/$defs/__schema1"
},
"explorerUrl": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"at": {
"$ref": "#/$defs/__schema6"
}
},
"required": ["hash", "blockNumber", "explorerUrl"],
"additionalProperties": false
}
}
}
```
## campaigns.policy
**GET `/v1/campaigns/:campaignId/policy`** · **Core live** · Access: **public**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L213).
**Client input fields**
| Field | Type | Required | Constraints |
| - | - | - | - |
| `campaignId` | string | Yes | See nested schema and runtime validation |
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"campaignId": {
"anyOf": [
{
"type": "string",
"maxLength": 78,
"pattern": "^(0|[1-9]\\d*)$"
},
{
"type": "string",
"pattern": "^demo-[\\w-]+$"
}
]
}
},
"required": ["campaignId"]
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"current": {
"$ref": "#/$defs/__schema0"
},
"scheduled": {
"anyOf": [
{
"$ref": "#/$defs/__schema0"
},
{
"type": "null"
}
]
},
"history": {
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
}
},
"required": ["current", "scheduled", "history"],
"additionalProperties": false,
"$defs": {
"__schema0": {
"type": "object",
"properties": {
"rewardToken": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"commissionBps": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"perSaleCap": {
"$ref": "#/$defs/__schema1"
},
"campaignLiabilityCap": {
"$ref": "#/$defs/__schema1"
},
"maxRewardedAncestors": {
"type": "integer",
"minimum": 1,
"maximum": 5
},
"weightsBps": {
"minItems": 1,
"maxItems": 5,
"type": "array",
"items": {
"$ref": "#/$defs/__schema2"
}
},
"shortPathMode": {
"default": "RENORMALIZE_EXISTING",
"type": "string",
"enum": ["RENORMALIZE_EXISTING", "RETURN_UNUSED"]
},
"holdSeconds": {
"type": "integer",
"minimum": 60,
"maximum": 7776000
},
"expiry": {
"$ref": "#/$defs/__schema1"
},
"eligibilityHash": {
"$ref": "#/$defs/__schema3"
},
"policyHash": {
"$ref": "#/$defs/__schema3"
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"effectiveAt": {
"$ref": "#/$defs/__schema4"
},
"regions": {
"type": "array",
"items": {
"type": "string"
}
},
"sharingRules": {
"type": "array",
"items": {
"type": "string"
}
},
"registrationTx": {
"anyOf": [
{
"type": "object",
"properties": {
"hash": {
"$ref": "#/$defs/__schema3"
},
"blockNumber": {
"$ref": "#/$defs/__schema1"
},
"explorerUrl": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"at": {
"$ref": "#/$defs/__schema4"
}
},
"required": ["hash", "blockNumber", "explorerUrl"],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"salesCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"rewardToken",
"commissionBps",
"perSaleCap",
"campaignLiabilityCap",
"maxRewardedAncestors",
"weightsBps",
"shortPathMode",
"holdSeconds",
"expiry",
"eligibilityHash",
"policyHash",
"version",
"effectiveAt",
"regions",
"sharingRules"
],
"additionalProperties": false
},
"__schema1": {
"type": "string"
},
"__schema2": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema3": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{64}$"
},
"__schema4": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
}
}
}
```
## campaigns.stats
**GET `/v1/campaigns/:campaignId/stats`** · **Core live** · Access: **public**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L214).
**Client input fields**
| Field | Type | Required | Constraints |
| - | - | - | - |
| `campaignId` | string | Yes | See nested schema and runtime validation |
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"campaignId": {
"anyOf": [
{
"type": "string",
"maxLength": 78,
"pattern": "^(0|[1-9]\\d*)$"
},
{
"type": "string",
"pattern": "^demo-[\\w-]+$"
}
]
}
},
"required": ["campaignId"]
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"links": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"branches": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"deepestLevel": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"sales": {
"type": "object",
"properties": {
"pending": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"finalized": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"refunded": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": ["pending", "finalized", "refunded"],
"additionalProperties": false
},
"settledValue": {
"$ref": "#/$defs/__schema0"
},
"reservedRewards": {
"$ref": "#/$defs/__schema0"
},
"depthMix": {
"type": "array",
"items": {
"type": "object",
"properties": {
"level": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"sales": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": ["level", "sales"],
"additionalProperties": false
}
}
},
"required": [
"links",
"branches",
"deepestLevel",
"sales",
"settledValue",
"reservedRewards",
"depthMix"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"type": "string"
}
}
}
```
## campaigns.activity
**GET `/v1/campaigns/:campaignId/activity`** · **Core live** · Access: **public**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L215).
**Client input fields**
| Field | Type | Required | Constraints |
| - | - | - | - |
| `campaignId` | string | Yes | See nested schema and runtime validation |
| `cursor` | string | No | See nested schema and runtime validation |
| `limit` | integer | No | Minimum: 1; Maximum: 100 |
| `kinds` | string\[] | No | See nested schema and runtime validation |
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"campaignId": {
"anyOf": [
{
"type": "string",
"maxLength": 78,
"pattern": "^(0|[1-9]\\d*)$"
},
{
"type": "string",
"pattern": "^demo-[\\w-]+$"
}
]
},
"cursor": {
"type": "string"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"kinds": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": ["campaignId"]
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"salePending",
"saleSettled",
"saleRefunded",
"saleFinalized",
"linkCreated",
"claimed",
"funded",
"paused",
"resumed",
"ended",
"termsPublished"
]
},
"actor": {
"type": "object",
"properties": {
"address": {
"anyOf": [
{
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
{
"type": "null"
}
]
},
"handle": {
"type": ["string", "null"]
},
"displayName": {
"type": ["string", "null"]
},
"visibility": {
"type": "string",
"enum": ["public", "pseudonymous", "private"]
}
},
"required": ["address", "handle", "displayName", "visibility"],
"additionalProperties": false
},
"amount": {
"anyOf": [
{
"$ref": "#/$defs/__schema0"
},
{
"type": "null"
}
]
},
"tx": {
"type": "object",
"properties": {
"hash": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{64}$"
},
"blockNumber": {
"$ref": "#/$defs/__schema0"
},
"explorerUrl": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"at": {
"$ref": "#/$defs/__schema1"
}
},
"required": ["hash", "blockNumber", "explorerUrl"],
"additionalProperties": false
},
"at": {
"$ref": "#/$defs/__schema1"
},
"saleId": {
"anyOf": [
{
"$ref": "#/$defs/__schema0"
},
{
"type": "string",
"pattern": "^demo-[\\w-]+$"
}
]
}
},
"required": ["kind", "actor", "amount", "tx", "at"],
"additionalProperties": false
}
},
"nextCursor": {
"type": ["string", "null"]
}
},
"required": ["items", "nextCursor"],
"additionalProperties": false,
"$defs": {
"__schema0": {
"type": "string"
},
"__schema1": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
}
}
}
```
## campaigns.mine
**GET `/v1/merchant/campaigns`** · **Core live** · Access: **session**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L216).
An authenticated session is necessary; ownership, merchant/operator scope, and any fresh-confirmation requirements are checked separately by the service.
**Client input fields**
| Field | Type | Required | Constraints |
| - | - | - | - |
| `cursor` | string | No | See nested schema and runtime validation |
| `limit` | integer | No | Minimum: 1; Maximum: 100 |
| `q` | string | No | Max length: 200 |
| `category` | string | No | See nested schema and runtime validation |
| `rateMin` | integer | No | Minimum: 1; Maximum: 10000 |
| `rateMax` | integer | No | Minimum: 1; Maximum: 10000 |
| `levels` | integer | No | Minimum: 1; Maximum: 5 |
| `holdMax` | integer | No | Minimum: 0; Maximum: 9007199254740991 |
| `budgetLeftMin` | string | No | Max length: 78; Pattern validated; see input schema |
| `source` | "NATIVE\_ONCHAIN" · "MERCHANT\_ATTESTED" · "THIRD\_PARTY\_VERIFIED" | No | See nested schema and runtime validation |
| `invitationOnly` | boolean | No | See nested schema and runtime validation |
| `excludeJoined` | boolean | No | See nested schema and runtime validation |
| `status` | "active" · "not\_live" · "paused" · "ended" · "expired" · "draft" | No | See nested schema and runtime validation |
| `merchant` | string | No | See nested schema and runtime validation |
| `sort` | "balanced" · "newest" · "reward" · "budget" · "hold" | No | See nested schema and runtime validation |
| `eligibility` | string | No | See nested schema and runtime validation |
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"cursor": {
"type": "string"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"q": {
"type": "string",
"maxLength": 200
},
"category": {
"type": "string"
},
"rateMin": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"rateMax": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"levels": {
"type": "integer",
"minimum": 1,
"maximum": 5
},
"holdMax": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"budgetLeftMin": {
"type": "string",
"maxLength": 78,
"pattern": "^(0|[1-9]\\d*)$"
},
"source": {
"type": "string",
"enum": ["NATIVE_ONCHAIN", "MERCHANT_ATTESTED", "THIRD_PARTY_VERIFIED"]
},
"invitationOnly": {
"type": "boolean"
},
"excludeJoined": {
"type": "boolean"
},
"status": {
"type": "string",
"enum": ["active", "not_live", "paused", "ended", "expired", "draft"]
},
"merchant": {
"type": "string"
},
"sort": {
"type": "string",
"enum": ["balanced", "newest", "reward", "budget", "hold"]
},
"eligibility": {
"type": "string"
}
}
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"campaignId": {
"anyOf": [
{
"anyOf": [
{
"$ref": "#/$defs/__schema0"
},
{
"type": "string",
"pattern": "^demo-[\\w-]+$"
}
]
},
{
"type": "null"
}
]
},
"draftId": {
"anyOf": [
{
"$ref": "#/$defs/__schema1"
},
{
"type": "null"
}
]
},
"state": {
"type": "string"
},
"productTitle": {
"type": "string"
},
"rewardPerSale": {
"$ref": "#/$defs/__schema0"
},
"policy": {
"type": "object",
"properties": {
"rewardToken": {
"$ref": "#/$defs/__schema2"
},
"commissionBps": {
"$ref": "#/$defs/__schema3"
},
"perSaleCap": {
"$ref": "#/$defs/__schema0"
},
"campaignLiabilityCap": {
"$ref": "#/$defs/__schema0"
},
"maxRewardedAncestors": {
"$ref": "#/$defs/__schema4"
},
"weightsBps": {
"$ref": "#/$defs/__schema5"
},
"shortPathMode": {
"$ref": "#/$defs/__schema7"
},
"holdSeconds": {
"$ref": "#/$defs/__schema8"
},
"expiry": {
"$ref": "#/$defs/__schema0"
},
"eligibilityHash": {
"$ref": "#/$defs/__schema9"
}
},
"required": [
"rewardToken",
"commissionBps",
"perSaleCap",
"campaignLiabilityCap",
"maxRewardedAncestors",
"weightsBps",
"shortPathMode",
"holdSeconds",
"expiry",
"eligibilityHash"
],
"additionalProperties": false
},
"source": {
"type": "string"
},
"trustMode": {
"type": "string"
},
"eligibility": {
"type": "string"
},
"availableRewards": {
"$ref": "#/$defs/__schema0"
},
"pendingSales": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"proceedsClaimable": {
"$ref": "#/$defs/__schema0"
},
"sales": {
"type": "object",
"properties": {
"pending": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"finalized": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"refunded": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": ["pending", "finalized", "refunded"],
"additionalProperties": false
},
"links": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"budgetAlertSales": {
"type": "integer",
"minimum": 1,
"maximum": 50
},
"endsAt": {
"$ref": "#/$defs/__schema10"
},
"scheduledPolicyHash": {
"anyOf": [
{
"$ref": "#/$defs/__schema9"
},
{
"type": "null"
}
]
},
"productId": {
"$ref": "#/$defs/__schema1"
},
"name": {
"type": "string"
},
"savedAt": {
"$ref": "#/$defs/__schema10"
},
"stepReached": {
"type": "integer",
"minimum": 0,
"maximum": 5
},
"settledValue": {
"$ref": "#/$defs/__schema0"
},
"updatedAt": {
"$ref": "#/$defs/__schema10"
}
},
"required": [
"campaignId",
"draftId",
"state",
"productTitle",
"rewardPerSale",
"policy",
"source",
"trustMode",
"eligibility",
"availableRewards",
"pendingSales",
"proceedsClaimable",
"sales",
"links",
"budgetAlertSales",
"endsAt",
"scheduledPolicyHash"
],
"additionalProperties": false
}
},
"nextCursor": {
"type": ["string", "null"]
},
"countsByState": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
}
},
"required": ["items", "nextCursor", "countsByState"],
"additionalProperties": false,
"$defs": {
"__schema0": {
"type": "string"
},
"__schema1": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9_-]+$"
},
"__schema2": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"__schema3": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema4": {
"type": "integer",
"minimum": 1,
"maximum": 5
},
"__schema5": {
"minItems": 1,
"maxItems": 5,
"type": "array",
"items": {
"$ref": "#/$defs/__schema6"
}
},
"__schema6": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema7": {
"default": "RENORMALIZE_EXISTING",
"type": "string",
"enum": ["RENORMALIZE_EXISTING", "RETURN_UNUSED"]
},
"__schema8": {
"type": "integer",
"minimum": 60,
"maximum": 7776000
},
"__schema9": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{64}$"
},
"__schema10": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
}
}
}
```
## campaigns.saveDraft
**PUT `/v1/merchant/campaign-drafts/:id`** · **Core live** · Access: **session**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L222).
An authenticated session is necessary; ownership, merchant/operator scope, and any fresh-confirmation requirements are checked separately by the service.
HTTP body mapping: send the `draft` property itself after removing path fields, rather than the complete client input wrapper.
**Client input fields**
| Field | Type | Required | Constraints |
| - | - | - | - |
| `id` | string | Yes | Min length: 1; Max length: 100; Pattern validated; see input schema |
| `draft` | object | Yes | See nested schema and runtime validation |
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"$ref": "#/$defs/__schema0"
},
"draft": {
"type": "object",
"properties": {
"productId": {
"$ref": "#/$defs/__schema1"
},
"productVersion": {
"$ref": "#/$defs/__schema2"
},
"policy": {
"$ref": "#/$defs/__schema3"
},
"endsAt": {
"$ref": "#/$defs/__schema13"
},
"inviteOnly": {
"$ref": "#/$defs/__schema14"
},
"stepReached": {
"$ref": "#/$defs/__schema15"
},
"version": {
"$ref": "#/$defs/__schema16"
},
"mode": {
"$ref": "#/$defs/__schema17"
},
"campaignId": {
"$ref": "#/$defs/__schema18"
},
"effectiveAt": {
"$ref": "#/$defs/__schema19"
},
"name": {
"$ref": "#/$defs/__schema20"
},
"deposit": {
"$ref": "#/$defs/__schema21"
},
"budgetAlertSales": {
"$ref": "#/$defs/__schema22"
},
"endPreset": {
"$ref": "#/$defs/__schema23"
},
"refundTerms": {
"$ref": "#/$defs/__schema24"
},
"regions": {
"$ref": "#/$defs/__schema25"
},
"disclosure": {
"$ref": "#/$defs/__schema27"
},
"cohort": {
"$ref": "#/$defs/__schema28"
},
"templateId": {
"$ref": "#/$defs/__schema29"
}
},
"required": ["policy", "endsAt", "stepReached", "version", "mode"],
"additionalProperties": false
}
},
"required": ["id", "draft"],
"$defs": {
"__schema0": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9_-]+$"
},
"__schema1": {
"$ref": "#/$defs/__schema0"
},
"__schema2": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"__schema3": {
"type": "object",
"properties": {
"rewardToken": {
"$ref": "#/$defs/__schema4"
},
"commissionBps": {
"$ref": "#/$defs/__schema5"
},
"perSaleCap": {
"$ref": "#/$defs/__schema6"
},
"campaignLiabilityCap": {
"$ref": "#/$defs/__schema6"
},
"maxRewardedAncestors": {
"$ref": "#/$defs/__schema7"
},
"weightsBps": {
"$ref": "#/$defs/__schema8"
},
"shortPathMode": {
"$ref": "#/$defs/__schema10"
},
"holdSeconds": {
"$ref": "#/$defs/__schema11"
},
"expiry": {
"$ref": "#/$defs/__schema6"
},
"eligibilityHash": {
"$ref": "#/$defs/__schema12"
}
},
"required": [
"rewardToken",
"commissionBps",
"perSaleCap",
"campaignLiabilityCap",
"maxRewardedAncestors",
"weightsBps",
"holdSeconds",
"expiry",
"eligibilityHash"
],
"additionalProperties": false
},
"__schema4": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"__schema5": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema6": {
"type": "string",
"maxLength": 78,
"pattern": "^(0|[1-9]\\d*)$"
},
"__schema7": {
"type": "integer",
"minimum": 1,
"maximum": 5
},
"__schema8": {
"minItems": 1,
"maxItems": 5,
"type": "array",
"items": {
"$ref": "#/$defs/__schema9"
}
},
"__schema9": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema10": {
"default": "RENORMALIZE_EXISTING",
"type": "string",
"enum": ["RENORMALIZE_EXISTING", "RETURN_UNUSED"]
},
"__schema11": {
"type": "integer",
"minimum": 60,
"maximum": 7776000
},
"__schema12": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{64}$"
},
"__schema13": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
"__schema14": {
"default": false,
"type": "boolean"
},
"__schema15": {
"type": "integer",
"minimum": 0,
"maximum": 5
},
"__schema16": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"__schema17": {
"type": "string",
"enum": ["create", "newVersion"]
},
"__schema18": {
"anyOf": [
{
"$ref": "#/$defs/__schema6"
},
{
"type": "string",
"pattern": "^demo-[\\w-]+$"
}
]
},
"__schema19": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
"__schema20": {
"type": "string",
"maxLength": 80
},
"__schema21": {
"$ref": "#/$defs/__schema6"
},
"__schema22": {
"type": "integer",
"minimum": 1,
"maximum": 50
},
"__schema23": {
"type": "string",
"enum": ["30d", "90d", "180d", "365d", "custom"]
},
"__schema24": {
"type": "string",
"maxLength": 500
},
"__schema25": {
"maxItems": 250,
"type": "array",
"items": {
"$ref": "#/$defs/__schema26"
}
},
"__schema26": {
"type": "string",
"pattern": "^[A-Z]{2}$"
},
"__schema27": {
"type": "string",
"maxLength": 280
},
"__schema28": {
"maxItems": 200,
"type": "array",
"items": {
"$ref": "#/$defs/__schema4"
}
},
"__schema29": {
"$ref": "#/$defs/__schema0"
}
}
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"draftId": {
"$ref": "#/$defs/__schema0"
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"savedAt": {
"$ref": "#/$defs/__schema1"
},
"stepReached": {
"type": "integer",
"minimum": 0,
"maximum": 5
},
"mode": {
"type": "string",
"enum": ["create", "newVersion"]
},
"campaignId": {
"anyOf": [
{
"$ref": "#/$defs/__schema2"
},
{
"type": "string",
"pattern": "^demo-[\\w-]+$"
}
]
},
"productId": {
"$ref": "#/$defs/__schema0"
},
"productVersion": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"policy": {
"type": "object",
"properties": {
"rewardToken": {
"$ref": "#/$defs/__schema3"
},
"commissionBps": {
"$ref": "#/$defs/__schema4"
},
"perSaleCap": {
"$ref": "#/$defs/__schema2"
},
"campaignLiabilityCap": {
"$ref": "#/$defs/__schema2"
},
"maxRewardedAncestors": {
"$ref": "#/$defs/__schema5"
},
"weightsBps": {
"$ref": "#/$defs/__schema6"
},
"shortPathMode": {
"$ref": "#/$defs/__schema8"
},
"holdSeconds": {
"$ref": "#/$defs/__schema9"
},
"expiry": {
"$ref": "#/$defs/__schema2"
},
"eligibilityHash": {
"$ref": "#/$defs/__schema10"
}
},
"required": [
"rewardToken",
"commissionBps",
"perSaleCap",
"campaignLiabilityCap",
"maxRewardedAncestors",
"weightsBps",
"shortPathMode",
"holdSeconds",
"expiry",
"eligibilityHash"
],
"additionalProperties": false
},
"endsAt": {
"$ref": "#/$defs/__schema1"
},
"effectiveAt": {
"$ref": "#/$defs/__schema1"
},
"inviteOnly": {
"type": "boolean"
},
"name": {
"type": "string"
},
"deposit": {
"$ref": "#/$defs/__schema2"
},
"budgetAlertSales": {
"type": "integer",
"minimum": 1,
"maximum": 50
},
"endPreset": {
"type": "string",
"enum": ["30d", "90d", "180d", "365d", "custom"]
},
"refundTerms": {
"type": "string"
},
"regions": {
"type": "array",
"items": {
"type": "string"
}
},
"disclosure": {
"type": "string"
},
"cohort": {
"type": "array",
"items": {
"$ref": "#/$defs/__schema3"
}
},
"templateId": {
"$ref": "#/$defs/__schema0"
}
},
"required": [
"draftId",
"version",
"savedAt",
"stepReached",
"mode",
"productId",
"productVersion",
"policy",
"endsAt",
"inviteOnly"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9_-]+$"
},
"__schema1": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
"__schema2": {
"type": "string"
},
"__schema3": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"__schema4": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema5": {
"type": "integer",
"minimum": 1,
"maximum": 5
},
"__schema6": {
"minItems": 1,
"maxItems": 5,
"type": "array",
"items": {
"$ref": "#/$defs/__schema7"
}
},
"__schema7": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema8": {
"default": "RENORMALIZE_EXISTING",
"type": "string",
"enum": ["RENORMALIZE_EXISTING", "RETURN_UNUSED"]
},
"__schema9": {
"type": "integer",
"minimum": 60,
"maximum": 7776000
},
"__schema10": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{64}$"
}
}
}
```
## campaigns.getDraft
**GET `/v1/merchant/campaign-drafts/:id`** · **Core live** · Access: **session**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L223).
An authenticated session is necessary; ownership, merchant/operator scope, and any fresh-confirmation requirements are checked separately by the service.
**Client input fields**
| Field | Type | Required | Constraints |
| - | - | - | - |
| `id` | string | Yes | Min length: 1; Max length: 100; Pattern validated; see input schema |
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9_-]+$"
}
},
"required": ["id"]
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"draftId": {
"$ref": "#/$defs/__schema0"
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"savedAt": {
"$ref": "#/$defs/__schema1"
},
"stepReached": {
"type": "integer",
"minimum": 0,
"maximum": 5
},
"mode": {
"type": "string",
"enum": ["create", "newVersion"]
},
"campaignId": {
"anyOf": [
{
"$ref": "#/$defs/__schema2"
},
{
"type": "string",
"pattern": "^demo-[\\w-]+$"
}
]
},
"productId": {
"$ref": "#/$defs/__schema0"
},
"productVersion": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"policy": {
"type": "object",
"properties": {
"rewardToken": {
"$ref": "#/$defs/__schema3"
},
"commissionBps": {
"$ref": "#/$defs/__schema4"
},
"perSaleCap": {
"$ref": "#/$defs/__schema2"
},
"campaignLiabilityCap": {
"$ref": "#/$defs/__schema2"
},
"maxRewardedAncestors": {
"$ref": "#/$defs/__schema5"
},
"weightsBps": {
"$ref": "#/$defs/__schema6"
},
"shortPathMode": {
"$ref": "#/$defs/__schema8"
},
"holdSeconds": {
"$ref": "#/$defs/__schema9"
},
"expiry": {
"$ref": "#/$defs/__schema2"
},
"eligibilityHash": {
"$ref": "#/$defs/__schema10"
}
},
"required": [
"rewardToken",
"commissionBps",
"perSaleCap",
"campaignLiabilityCap",
"maxRewardedAncestors",
"weightsBps",
"shortPathMode",
"holdSeconds",
"expiry",
"eligibilityHash"
],
"additionalProperties": false
},
"endsAt": {
"$ref": "#/$defs/__schema1"
},
"effectiveAt": {
"$ref": "#/$defs/__schema1"
},
"inviteOnly": {
"type": "boolean"
},
"name": {
"type": "string"
},
"deposit": {
"$ref": "#/$defs/__schema2"
},
"budgetAlertSales": {
"type": "integer",
"minimum": 1,
"maximum": 50
},
"endPreset": {
"type": "string",
"enum": ["30d", "90d", "180d", "365d", "custom"]
},
"refundTerms": {
"type": "string"
},
"regions": {
"type": "array",
"items": {
"type": "string"
}
},
"disclosure": {
"type": "string"
},
"cohort": {
"type": "array",
"items": {
"$ref": "#/$defs/__schema3"
}
},
"templateId": {
"$ref": "#/$defs/__schema0"
}
},
"required": [
"draftId",
"version",
"savedAt",
"stepReached",
"mode",
"productId",
"productVersion",
"policy",
"endsAt",
"inviteOnly"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9_-]+$"
},
"__schema1": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
"__schema2": {
"type": "string"
},
"__schema3": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"__schema4": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema5": {
"type": "integer",
"minimum": 1,
"maximum": 5
},
"__schema6": {
"minItems": 1,
"maxItems": 5,
"type": "array",
"items": {
"$ref": "#/$defs/__schema7"
}
},
"__schema7": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema8": {
"default": "RENORMALIZE_EXISTING",
"type": "string",
"enum": ["RENORMALIZE_EXISTING", "RETURN_UNUSED"]
},
"__schema9": {
"type": "integer",
"minimum": 60,
"maximum": 7776000
},
"__schema10": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{64}$"
}
}
}
```
## campaigns.deleteDraft
**DELETE `/v1/merchant/campaign-drafts/:id`** · **Core live** · Access: **session**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L224).
An authenticated session is necessary; ownership, merchant/operator scope, and any fresh-confirmation requirements are checked separately by the service.
**Client input fields**
| Field | Type | Required | Constraints |
| - | - | - | - |
| `id` | string | Yes | Min length: 1; Max length: 100; Pattern validated; see input schema |
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9_-]+$"
}
},
"required": ["id"]
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"deleted": {
"type": "boolean",
"const": true
}
},
"required": ["deleted"],
"additionalProperties": false
}
```
## campaigns.prepareCreate
**POST `/v1/merchant/campaign-drafts/:id/prepare`** · **Core live** · Access: **session**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L225).
An authenticated session is necessary; ownership, merchant/operator scope, and any fresh-confirmation requirements are checked separately by the service.
**Client input fields**
| Field | Type | Required | Constraints |
| - | - | - | - |
| `id` | string | Yes | Min length: 1; Max length: 100; Pattern validated; see input schema |
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9_-]+$"
}
},
"required": ["id"]
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"metadataHash": {
"$ref": "#/$defs/__schema0"
},
"policy": {
"type": "object",
"properties": {
"rewardToken": {
"$ref": "#/$defs/__schema1"
},
"commissionBps": {
"$ref": "#/$defs/__schema2"
},
"perSaleCap": {
"$ref": "#/$defs/__schema3"
},
"campaignLiabilityCap": {
"$ref": "#/$defs/__schema3"
},
"maxRewardedAncestors": {
"$ref": "#/$defs/__schema4"
},
"weightsBps": {
"$ref": "#/$defs/__schema5"
},
"shortPathMode": {
"$ref": "#/$defs/__schema7"
},
"holdSeconds": {
"$ref": "#/$defs/__schema8"
},
"expiry": {
"$ref": "#/$defs/__schema3"
},
"eligibilityHash": {
"$ref": "#/$defs/__schema0"
}
},
"required": [
"rewardToken",
"commissionBps",
"perSaleCap",
"campaignLiabilityCap",
"maxRewardedAncestors",
"weightsBps",
"shortPathMode",
"holdSeconds",
"expiry",
"eligibilityHash"
],
"additionalProperties": false
},
"policyHash": {
"$ref": "#/$defs/__schema0"
},
"eligibilityHash": {
"$ref": "#/$defs/__schema0"
},
"productVersion": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"gasEstimate": {
"anyOf": [
{
"$ref": "#/$defs/__schema3"
},
{
"type": "null"
}
]
},
"expectedEvents": {
"type": "array",
"items": {
"type": "string"
}
},
"cohortEnforcement": {
"type": "string",
"enum": ["onchain", "offchain"]
},
"mode": {
"type": "string",
"enum": ["create", "newVersion"]
},
"config": {
"type": "object",
"properties": {
"skuHash": {
"$ref": "#/$defs/__schema0"
},
"skuPrice": {
"$ref": "#/$defs/__schema3"
}
},
"required": ["skuHash", "skuPrice"],
"additionalProperties": false
},
"earliestEffectiveAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
"diff": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string"
},
"before": {
"$ref": "#/$defs/__schema9"
},
"after": {
"$ref": "#/$defs/__schema10"
}
},
"required": ["field", "before", "after"],
"additionalProperties": false
}
}
},
"required": [
"metadataHash",
"policy",
"policyHash",
"eligibilityHash",
"productVersion",
"gasEstimate",
"expectedEvents",
"cohortEnforcement",
"mode"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{64}$"
},
"__schema1": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"__schema2": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema3": {
"type": "string"
},
"__schema4": {
"type": "integer",
"minimum": 1,
"maximum": 5
},
"__schema5": {
"minItems": 1,
"maxItems": 5,
"type": "array",
"items": {
"$ref": "#/$defs/__schema6"
}
},
"__schema6": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema7": {
"default": "RENORMALIZE_EXISTING",
"type": "string",
"enum": ["RENORMALIZE_EXISTING", "RETURN_UNUSED"]
},
"__schema8": {
"type": "integer",
"minimum": 60,
"maximum": 7776000
},
"__schema9": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema9"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema9"
}
}
]
},
"__schema10": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema10"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema10"
}
}
]
}
}
}
```
## campaigns.updateSettings
**PATCH `/v1/merchant/campaigns/:campaignId/settings`** · **Core live** · Access: **session**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L226).
An authenticated session is necessary; ownership, merchant/operator scope, and any fresh-confirmation requirements are checked separately by the service.
**Client input fields**
| Field | Type | Required | Constraints |
| - | - | - | - |
| `campaignId` | string | Yes | See nested schema and runtime validation |
| `budgetAlertSales` | integer | Yes | Minimum: 1; Maximum: 50 |
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"campaignId": {
"anyOf": [
{
"type": "string",
"maxLength": 78,
"pattern": "^(0|[1-9]\\d*)$"
},
{
"type": "string",
"pattern": "^demo-[\\w-]+$"
}
]
},
"budgetAlertSales": {
"type": "integer",
"minimum": 1,
"maximum": 50
}
},
"required": ["campaignId", "budgetAlertSales"]
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"budgetAlertSales": {
"type": "integer",
"minimum": 1,
"maximum": 50
}
},
"required": ["budgetAlertSales"],
"additionalProperties": false
}
```
## campaigns.distributors
**GET `/v1/merchant/campaigns/:campaignId/distributors`** · **Core live** · Access: **session**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L230).
An authenticated session is necessary; ownership, merchant/operator scope, and any fresh-confirmation requirements are checked separately by the service.
**Client input fields**
| Field | Type | Required | Constraints |
| - | - | - | - |
| `campaignId` | string | Yes | See nested schema and runtime validation |
| `cursor` | string | No | See nested schema and runtime validation |
| `limit` | integer | No | Minimum: 1; Maximum: 100 |
| `sort` | string | No | See nested schema and runtime validation |
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"campaignId": {
"anyOf": [
{
"type": "string",
"maxLength": 78,
"pattern": "^(0|[1-9]\\d*)$"
},
{
"type": "string",
"pattern": "^demo-[\\w-]+$"
}
]
},
"cursor": {
"type": "string"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"sort": {
"type": "string"
}
},
"required": ["campaignId"]
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"address": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"handle": {
"type": ["string", "null"]
},
"parentNodeId": {
"$ref": "#/$defs/__schema0"
},
"nodeId": {
"$ref": "#/$defs/__schema0"
},
"linkCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"descendants": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"directSales": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"paidSales": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"rewards": {
"type": "object",
"properties": {
"atRisk": {
"$ref": "#/$defs/__schema1"
},
"readyToFinalize": {
"$ref": "#/$defs/__schema1"
},
"claimable": {
"$ref": "#/$defs/__schema1"
},
"claimed": {
"$ref": "#/$defs/__schema1"
},
"refunded": {
"$ref": "#/$defs/__schema1"
},
"reversed": {
"$ref": "#/$defs/__schema1"
}
},
"required": [
"atRisk",
"readyToFinalize",
"claimable",
"claimed",
"refunded",
"reversed"
],
"additionalProperties": false
},
"lastActivityAt": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
{
"type": "null"
}
]
},
"invitationStatus": {
"type": ["string", "null"]
}
},
"required": [
"address",
"handle",
"parentNodeId",
"nodeId",
"linkCount",
"descendants",
"directSales",
"paidSales",
"rewards",
"lastActivityAt",
"invitationStatus"
],
"additionalProperties": false
}
},
"nextCursor": {
"type": ["string", "null"]
}
},
"required": ["items", "nextCursor"],
"additionalProperties": false,
"$defs": {
"__schema0": {
"anyOf": [
{
"$ref": "#/$defs/__schema1"
},
{
"type": "string",
"pattern": "^demo-[\\w-]+$"
}
]
},
"__schema1": {
"type": "string"
}
}
}
```
## products.list
**GET `/v1/merchant/products`** · **Core live** · Access: **session**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L234).
An authenticated session is necessary; ownership, merchant/operator scope, and any fresh-confirmation requirements are checked separately by the service.
**Client input fields**
| Field | Type | Required | Constraints |
| - | - | - | - |
| `cursor` | string | No | See nested schema and runtime validation |
| `limit` | integer | No | Minimum: 1; Maximum: 100 |
| `billing` | "oneTime" · "subscription" | No | See nested schema and runtime validation |
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"cursor": {
"type": "string"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"billing": {
"type": "string",
"enum": ["oneTime", "subscription"]
}
}
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"$ref": "#/$defs/__schema0"
},
"merchantId": {
"$ref": "#/$defs/__schema0"
},
"title": {
"type": "string"
},
"summary": {
"type": "string"
},
"outcome": {
"type": "string"
},
"description": {
"type": "string"
},
"media": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"$ref": "#/$defs/__schema0"
},
"kind": {
"type": "string",
"enum": ["image", "download"]
},
"size": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"sha256": {
"type": "string",
"pattern": "^[\\da-f]{64}$"
},
"url": {
"type": "string",
"format": "uri"
},
"width": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"height": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": ["id", "kind", "size", "sha256"],
"additionalProperties": false
}
},
"priceBaseUnits": {
"$ref": "#/$defs/__schema1"
},
"token": {
"type": "object",
"properties": {
"address": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"symbol": {
"type": "string"
},
"decimals": {
"type": "integer",
"minimum": 0,
"maximum": 36
},
"name": {
"type": "string"
},
"testnet": {
"type": "boolean"
}
},
"required": ["address", "symbol", "decimals"],
"additionalProperties": false
},
"category": {
"type": "string"
},
"fulfillmentMode": {
"type": "string",
"enum": ["download", "external", "manual"]
},
"deliverable": {
"type": "string",
"minLength": 1,
"maxLength": 2048
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"skuHash": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{64}$"
},
"refundPolicy": {
"type": "string"
},
"variants": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"$ref": "#/$defs/__schema0"
},
"name": {
"type": "string"
},
"priceBaseUnits": {
"$ref": "#/$defs/__schema1"
}
},
"required": ["id", "name", "priceBaseUnits"],
"additionalProperties": false
}
},
"billingPeriod": {
"anyOf": [
{
"type": "string",
"enum": ["monthly", "yearly"]
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": ["draft", "ready", "archived"]
},
"missing": {
"type": "array",
"items": {
"type": "string",
"enum": [
"title",
"outcome",
"description",
"category",
"cover",
"coverAlt",
"price",
"deliverable"
]
}
},
"coverUrl": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"coverAlt": {
"type": ["string", "null"]
},
"accessTiming": {
"type": "string",
"enum": ["afterPurchase", "afterHold"]
},
"liveCampaignCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"usedBy": {
"type": "array",
"items": {
"type": "object",
"properties": {
"campaignId": {
"anyOf": [
{
"$ref": "#/$defs/__schema1"
},
{
"type": "string",
"pattern": "^demo-[\\w-]+$"
}
]
},
"name": {
"type": "string"
},
"state": {
"type": "string",
"enum": [
"DRAFT_OFFCHAIN",
"CREATED_UNFUNDED",
"FUNDED_ACTIVE",
"PAUSED",
"ENDED",
"EXPIRED"
]
},
"productVersion": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": ["campaignId", "name", "state", "productVersion"],
"additionalProperties": false
}
},
"updatedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
}
},
"required": [
"id",
"merchantId",
"title",
"summary",
"outcome",
"description",
"media",
"priceBaseUnits",
"token",
"category",
"fulfillmentMode",
"version",
"skuHash",
"refundPolicy",
"variants",
"billingPeriod"
],
"additionalProperties": false
}
},
"nextCursor": {
"type": ["string", "null"]
}
},
"required": ["items", "nextCursor"],
"additionalProperties": false,
"$defs": {
"__schema0": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9_-]+$"
},
"__schema1": {
"type": "string"
}
}
}
```
## products.get
**GET `/v1/products/:id`** · **Core live** · Access: **public**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L238).
**Client input fields**
| Field | Type | Required | Constraints |
| - | - | - | - |
| `id` | string | Yes | Min length: 1; Max length: 100; Pattern validated; see input schema |
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9_-]+$"
}
},
"required": ["id"]
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"$ref": "#/$defs/__schema0"
},
"merchantId": {
"$ref": "#/$defs/__schema0"
},
"title": {
"type": "string"
},
"summary": {
"type": "string"
},
"outcome": {
"type": "string"
},
"description": {
"type": "string"
},
"media": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"$ref": "#/$defs/__schema0"
},
"kind": {
"type": "string",
"enum": ["image", "download"]
},
"size": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"sha256": {
"type": "string",
"pattern": "^[\\da-f]{64}$"
},
"url": {
"type": "string",
"format": "uri"
},
"width": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"height": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": ["id", "kind", "size", "sha256"],
"additionalProperties": false
}
},
"priceBaseUnits": {
"$ref": "#/$defs/__schema1"
},
"token": {
"type": "object",
"properties": {
"address": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"symbol": {
"type": "string"
},
"decimals": {
"type": "integer",
"minimum": 0,
"maximum": 36
},
"name": {
"type": "string"
},
"testnet": {
"type": "boolean"
}
},
"required": ["address", "symbol", "decimals"],
"additionalProperties": false
},
"category": {
"type": "string"
},
"fulfillmentMode": {
"type": "string",
"enum": ["download", "external", "manual"]
},
"deliverable": {
"type": "string",
"minLength": 1,
"maxLength": 2048
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"skuHash": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{64}$"
},
"refundPolicy": {
"type": "string"
},
"variants": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"$ref": "#/$defs/__schema0"
},
"name": {
"type": "string"
},
"priceBaseUnits": {
"$ref": "#/$defs/__schema1"
}
},
"required": ["id", "name", "priceBaseUnits"],
"additionalProperties": false
}
},
"billingPeriod": {
"anyOf": [
{
"type": "string",
"enum": ["monthly", "yearly"]
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": ["draft", "ready", "archived"]
},
"missing": {
"type": "array",
"items": {
"type": "string",
"enum": [
"title",
"outcome",
"description",
"category",
"cover",
"coverAlt",
"price",
"deliverable"
]
}
},
"coverUrl": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"coverAlt": {
"type": ["string", "null"]
},
"accessTiming": {
"type": "string",
"enum": ["afterPurchase", "afterHold"]
},
"liveCampaignCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"usedBy": {
"type": "array",
"items": {
"type": "object",
"properties": {
"campaignId": {
"anyOf": [
{
"$ref": "#/$defs/__schema1"
},
{
"type": "string",
"pattern": "^demo-[\\w-]+$"
}
]
},
"name": {
"type": "string"
},
"state": {
"type": "string",
"enum": [
"DRAFT_OFFCHAIN",
"CREATED_UNFUNDED",
"FUNDED_ACTIVE",
"PAUSED",
"ENDED",
"EXPIRED"
]
},
"productVersion": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": ["campaignId", "name", "state", "productVersion"],
"additionalProperties": false
}
},
"updatedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
}
},
"required": [
"id",
"merchantId",
"title",
"summary",
"outcome",
"description",
"media",
"priceBaseUnits",
"token",
"category",
"fulfillmentMode",
"version",
"skuHash",
"refundPolicy",
"variants",
"billingPeriod"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9_-]+$"
},
"__schema1": {
"type": "string"
}
}
}
```
## products.save
**PUT `/v1/merchant/products/:id`** · **Core live** · Access: **session**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L239).
An authenticated session is necessary; ownership, merchant/operator scope, and any fresh-confirmation requirements are checked separately by the service.
HTTP body mapping: send the `product` property itself after removing path fields, rather than the complete client input wrapper.
**Client input fields**
| Field | Type | Required | Constraints |
| - | - | - | - |
| `id` | string | Yes | Min length: 1; Max length: 100; Pattern validated; see input schema |
| `product` | object | Yes | See nested schema and runtime validation |
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"$ref": "#/$defs/__schema0"
},
"product": {
"type": "object",
"properties": {
"merchantId": {
"$ref": "#/$defs/__schema0"
},
"title": {
"type": "string",
"minLength": 2,
"maxLength": 150
},
"summary": {
"type": "string",
"maxLength": 300
},
"outcome": {
"default": "",
"type": "string",
"maxLength": 500
},
"description": {
"type": "string",
"maxLength": 15000
},
"category": {
"type": "string",
"enum": ["digital", "education", "software", "design", "other"]
},
"priceBaseUnits": {
"$ref": "#/$defs/__schema1"
},
"token": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"images": {
"default": [],
"maxItems": 8,
"type": "array",
"items": {
"$ref": "#/$defs/__schema2"
}
},
"fulfillmentMode": {
"type": "string",
"enum": ["download", "external", "manual"]
},
"deliverable": {
"type": "string",
"minLength": 1,
"maxLength": 2048
},
"refundPolicy": {
"type": "string",
"minLength": 10,
"maxLength": 3000
},
"coverAlt": {
"type": "string",
"maxLength": 140
},
"accessTiming": {
"type": "string",
"enum": ["afterPurchase", "afterHold"]
},
"status": {
"type": "string",
"enum": ["draft", "ready", "archived"]
}
},
"required": [
"title",
"summary",
"description",
"category",
"priceBaseUnits",
"token",
"fulfillmentMode",
"deliverable",
"refundPolicy"
],
"additionalProperties": false
}
},
"required": ["id", "product"],
"$defs": {
"__schema0": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9_-]+$"
},
"__schema1": {
"type": "string",
"maxLength": 78,
"pattern": "^(0|[1-9]\\d*)$"
},
"__schema2": {
"type": "string",
"format": "uri"
}
}
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"$ref": "#/$defs/__schema0"
},
"merchantId": {
"$ref": "#/$defs/__schema0"
},
"title": {
"type": "string"
},
"summary": {
"type": "string"
},
"outcome": {
"type": "string"
},
"description": {
"type": "string"
},
"media": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"$ref": "#/$defs/__schema0"
},
"kind": {
"type": "string",
"enum": ["image", "download"]
},
"size": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"sha256": {
"type": "string",
"pattern": "^[\\da-f]{64}$"
},
"url": {
"type": "string",
"format": "uri"
},
"width": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"height": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": ["id", "kind", "size", "sha256"],
"additionalProperties": false
}
},
"priceBaseUnits": {
"$ref": "#/$defs/__schema1"
},
"token": {
"type": "object",
"properties": {
"address": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"symbol": {
"type": "string"
},
"decimals": {
"type": "integer",
"minimum": 0,
"maximum": 36
},
"name": {
"type": "string"
},
"testnet": {
"type": "boolean"
}
},
"required": ["address", "symbol", "decimals"],
"additionalProperties": false
},
"category": {
"type": "string"
},
"fulfillmentMode": {
"type": "string",
"enum": ["download", "external", "manual"]
},
"deliverable": {
"type": "string",
"minLength": 1,
"maxLength": 2048
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"skuHash": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{64}$"
},
"refundPolicy": {
"type": "string"
},
"variants": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"$ref": "#/$defs/__schema0"
},
"name": {
"type": "string"
},
"priceBaseUnits": {
"$ref": "#/$defs/__schema1"
}
},
"required": ["id", "name", "priceBaseUnits"],
"additionalProperties": false
}
},
"billingPeriod": {
"anyOf": [
{
"type": "string",
"enum": ["monthly", "yearly"]
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": ["draft", "ready", "archived"]
},
"missing": {
"type": "array",
"items": {
"type": "string",
"enum": [
"title",
"outcome",
"description",
"category",
"cover",
"coverAlt",
"price",
"deliverable"
]
}
},
"coverUrl": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"coverAlt": {
"type": ["string", "null"]
},
"accessTiming": {
"type": "string",
"enum": ["afterPurchase", "afterHold"]
},
"liveCampaignCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"usedBy": {
"type": "array",
"items": {
"type": "object",
"properties": {
"campaignId": {
"anyOf": [
{
"$ref": "#/$defs/__schema1"
},
{
"type": "string",
"pattern": "^demo-[\\w-]+$"
}
]
},
"name": {
"type": "string"
},
"state": {
"type": "string",
"enum": [
"DRAFT_OFFCHAIN",
"CREATED_UNFUNDED",
"FUNDED_ACTIVE",
"PAUSED",
"ENDED",
"EXPIRED"
]
},
"productVersion": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": ["campaignId", "name", "state", "productVersion"],
"additionalProperties": false
}
},
"updatedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
}
},
"required": [
"id",
"merchantId",
"title",
"summary",
"outcome",
"description",
"media",
"priceBaseUnits",
"token",
"category",
"fulfillmentMode",
"version",
"skuHash",
"refundPolicy",
"variants",
"billingPeriod"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9_-]+$"
},
"__schema1": {
"type": "string"
}
}
}
```
## products.uploadAsset
**POST `/v1/merchant/products/:id/assets`** · **Core live** · Access: **session**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L240).
An authenticated session is necessary; ownership, merchant/operator scope, and any fresh-confirmation requirements are checked separately by the service.
Transport: multipart form data. File/blob inputs require the original runtime schema; JSON Schema cannot represent browser Blob validation.
**Client input fields**
| Field | Type | Required | Constraints |
| - | - | - | - |
| `id` | string | Yes | Min length: 1; Max length: 100; Pattern validated; see input schema |
| `file` | string | Yes | Max length: 25000000; Format: binary |
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9_-]+$"
},
"file": {
"type": "string",
"format": "binary",
"contentEncoding": "binary",
"maxLength": 25000000
}
},
"required": ["id", "file"]
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9_-]+$"
},
"kind": {
"type": "string",
"enum": ["image", "download"]
},
"size": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"sha256": {
"type": "string",
"pattern": "^[\\da-f]{64}$"
},
"url": {
"type": "string",
"format": "uri"
},
"width": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"height": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": ["id", "kind", "size", "sha256"],
"additionalProperties": false
}
```
## products.categories
**GET `/v1/categories`** · **Core live** · Access: **public**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L241).
**Client input fields**
No fields. Use an empty object for the client method input.
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": ["id", "name"],
"additionalProperties": false
}
}
```
## merchants.get
**GET `/v1/merchants/:slug`** · **Core live** · Access: **public**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L242).
**Client input fields**
| Field | Type | Required | Constraints |
| - | - | - | - |
| `slug` | string | Yes | See nested schema and runtime validation |
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"slug": {
"type": "string"
}
},
"required": ["slug"]
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9_-]+$"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"address": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"description": {
"type": "string"
},
"logo": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"website": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"verificationTier": {
"type": "string",
"enum": ["unverified", "domain", "business"]
},
"joinedAt": {
"$ref": "#/$defs/__schema0"
},
"offersCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"closedAt": {
"anyOf": [
{
"$ref": "#/$defs/__schema0"
},
{
"type": "null"
}
]
},
"category": {
"type": ["string", "null"]
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"supportEmail": {
"type": "string",
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
},
"moderation": {
"type": "object",
"properties": {
"state": {
"type": "string",
"enum": ["visible", "hidden"]
},
"actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"at": {
"$ref": "#/$defs/__schema0"
},
"action": {
"type": "string"
},
"reasonCategory": {
"type": "string"
}
},
"required": ["at", "action", "reasonCategory"],
"additionalProperties": false
}
}
},
"required": ["state", "actions"],
"additionalProperties": false
}
},
"required": [
"id",
"name",
"slug",
"address",
"description",
"logo",
"website",
"verificationTier",
"joinedAt",
"offersCount",
"closedAt"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
}
}
}
```
## merchants.record
**GET `/v1/merchants/:slug/record`** · **Core live** · Access: **public**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L243).
**Client input fields**
| Field | Type | Required | Constraints |
| - | - | - | - |
| `slug` | string | Yes | See nested schema and runtime validation |
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"slug": {
"type": "string"
}
},
"required": ["slug"]
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"sales": {
"type": "object",
"properties": {
"pending": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"finalized": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"refunded": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": ["pending", "finalized", "refunded"],
"additionalProperties": false
},
"refundRateBps": {
"type": "integer",
"minimum": 0,
"maximum": 10000
},
"medianRefundSeconds": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"rewardsDeposited": {
"$ref": "#/$defs/__schema0"
},
"rewardsEarned": {
"$ref": "#/$defs/__schema0"
},
"rewardsWithdrawn": {
"$ref": "#/$defs/__schema0"
},
"indexedBlock": {
"anyOf": [
{
"$ref": "#/$defs/__schema0"
},
{
"type": "null"
}
]
}
},
"required": [
"sales",
"refundRateBps",
"medianRefundSeconds",
"rewardsDeposited",
"rewardsEarned",
"rewardsWithdrawn",
"indexedBlock"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"type": "string"
}
}
}
```
## merchants.me
**GET `/v1/merchant`** · **Core live** · Access: **session**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L244).
An authenticated session is necessary; ownership, merchant/operator scope, and any fresh-confirmation requirements are checked separately by the service.
**Client input fields**
No fields. Use an empty object for the client method input.
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9_-]+$"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"address": {
"$ref": "#/$defs/__schema0"
},
"description": {
"type": "string"
},
"logo": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"website": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"verificationTier": {
"type": "string",
"enum": ["unverified", "domain", "business"]
},
"joinedAt": {
"$ref": "#/$defs/__schema1"
},
"offersCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"closedAt": {
"anyOf": [
{
"$ref": "#/$defs/__schema1"
},
{
"type": "null"
}
]
},
"category": {
"type": ["string", "null"]
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"supportEmail": {
"type": "string",
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
},
"moderation": {
"type": "object",
"properties": {
"state": {
"type": "string",
"enum": ["visible", "hidden"]
},
"actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"at": {
"$ref": "#/$defs/__schema1"
},
"action": {
"type": "string"
},
"reasonCategory": {
"type": "string"
}
},
"required": ["at", "action", "reasonCategory"],
"additionalProperties": false
}
}
},
"required": ["state", "actions"],
"additionalProperties": false
},
"region": {
"type": "string"
},
"defaults": {
"anyOf": [
{
"type": "object",
"properties": {
"rewardToken": {
"$ref": "#/$defs/__schema0"
},
"commissionBps": {
"$ref": "#/$defs/__schema2"
},
"perSaleCap": {
"$ref": "#/$defs/__schema3"
},
"campaignLiabilityCap": {
"$ref": "#/$defs/__schema3"
},
"maxRewardedAncestors": {
"$ref": "#/$defs/__schema4"
},
"weightsBps": {
"$ref": "#/$defs/__schema5"
},
"shortPathMode": {
"$ref": "#/$defs/__schema7"
},
"holdSeconds": {
"$ref": "#/$defs/__schema8"
},
"expiry": {
"$ref": "#/$defs/__schema3"
},
"eligibilityHash": {
"$ref": "#/$defs/__schema9"
}
},
"required": [
"rewardToken",
"commissionBps",
"perSaleCap",
"campaignLiabilityCap",
"maxRewardedAncestors",
"weightsBps",
"shortPathMode",
"holdSeconds",
"expiry",
"eligibilityHash"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"budgetAlertSales": {
"type": "integer",
"minimum": 1,
"maximum": 50
},
"agreement": {
"type": "object",
"properties": {
"version": {
"type": "string"
},
"publishedAt": {
"$ref": "#/$defs/__schema1"
},
"url": {
"type": "string",
"format": "uri"
},
"acceptedAt": {
"$ref": "#/$defs/__schema1"
}
},
"required": ["version", "publishedAt", "url", "acceptedAt"],
"additionalProperties": false
},
"businessWallet": {
"$ref": "#/$defs/__schema0"
},
"showSupportEmail": {
"type": "boolean"
}
},
"required": [
"id",
"name",
"slug",
"address",
"description",
"logo",
"website",
"verificationTier",
"joinedAt",
"offersCount",
"closedAt",
"supportEmail",
"region",
"defaults",
"budgetAlertSales",
"agreement",
"businessWallet"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"__schema1": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
"__schema2": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema3": {
"type": "string"
},
"__schema4": {
"type": "integer",
"minimum": 1,
"maximum": 5
},
"__schema5": {
"minItems": 1,
"maxItems": 5,
"type": "array",
"items": {
"$ref": "#/$defs/__schema6"
}
},
"__schema6": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema7": {
"default": "RENORMALIZE_EXISTING",
"type": "string",
"enum": ["RENORMALIZE_EXISTING", "RETURN_UNUSED"]
},
"__schema8": {
"type": "integer",
"minimum": 60,
"maximum": 7776000
},
"__schema9": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{64}$"
}
}
}
```
## merchants.setup
**POST `/v1/merchant`** · **Core live** · Access: **session**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L245).
An authenticated session is necessary; ownership, merchant/operator scope, and any fresh-confirmation requirements are checked separately by the service.
**Client input fields**
| Field | Type | Required | Constraints |
| - | - | - | - |
| `name` | string | Yes | Min length: 2; Max length: 100 |
| `slug` | string | Yes | Min length: 3; Max length: 30; Pattern validated; see input schema |
| `description` | string | No | Max length: 2000; Default: `""` |
| `website` | string or null | No | Default: `null` |
| `supportEmail` | string | Yes | Max length: 200; Format: email; Pattern validated; see input schema |
| `region` | string | Yes | Min length: 2; Max length: 80 |
| `agreementVersion` | "1.0" | Yes | See nested schema and runtime validation |
| `budgetAlertSales` | integer | No | Minimum: 1; Maximum: 50; Default: `5` |
| `logo` | string or null | No | See nested schema and runtime validation |
| `category` | "digital" · "education" · "software" · "design" · "other" | No | See nested schema and runtime validation |
| `showSupportEmail` | boolean | No | See nested schema and runtime validation |
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 2,
"maxLength": 100
},
"slug": {
"type": "string",
"minLength": 3,
"maxLength": 30,
"pattern": "^[a-z][a-z0-9_]+$"
},
"description": {
"default": "",
"type": "string",
"maxLength": 2000
},
"website": {
"default": null,
"anyOf": [
{
"$ref": "#/$defs/__schema0"
},
{
"type": "null"
}
]
},
"supportEmail": {
"type": "string",
"maxLength": 200,
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
},
"region": {
"type": "string",
"minLength": 2,
"maxLength": 80
},
"agreementVersion": {
"type": "string",
"const": "1.0"
},
"budgetAlertSales": {
"default": 5,
"type": "integer",
"minimum": 1,
"maximum": 50
},
"logo": {
"anyOf": [
{
"$ref": "#/$defs/__schema0"
},
{
"type": "null"
}
]
},
"category": {
"type": "string",
"enum": ["digital", "education", "software", "design", "other"]
},
"showSupportEmail": {
"type": "boolean"
}
},
"required": ["name", "slug", "supportEmail", "region", "agreementVersion"],
"additionalProperties": false,
"$defs": {
"__schema0": {
"type": "string",
"format": "uri"
}
}
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9_-]+$"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"address": {
"$ref": "#/$defs/__schema0"
},
"description": {
"type": "string"
},
"logo": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"website": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"verificationTier": {
"type": "string",
"enum": ["unverified", "domain", "business"]
},
"joinedAt": {
"$ref": "#/$defs/__schema1"
},
"offersCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"closedAt": {
"anyOf": [
{
"$ref": "#/$defs/__schema1"
},
{
"type": "null"
}
]
},
"category": {
"type": ["string", "null"]
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"supportEmail": {
"type": "string",
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
},
"moderation": {
"type": "object",
"properties": {
"state": {
"type": "string",
"enum": ["visible", "hidden"]
},
"actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"at": {
"$ref": "#/$defs/__schema1"
},
"action": {
"type": "string"
},
"reasonCategory": {
"type": "string"
}
},
"required": ["at", "action", "reasonCategory"],
"additionalProperties": false
}
}
},
"required": ["state", "actions"],
"additionalProperties": false
},
"region": {
"type": "string"
},
"defaults": {
"anyOf": [
{
"type": "object",
"properties": {
"rewardToken": {
"$ref": "#/$defs/__schema0"
},
"commissionBps": {
"$ref": "#/$defs/__schema2"
},
"perSaleCap": {
"$ref": "#/$defs/__schema3"
},
"campaignLiabilityCap": {
"$ref": "#/$defs/__schema3"
},
"maxRewardedAncestors": {
"$ref": "#/$defs/__schema4"
},
"weightsBps": {
"$ref": "#/$defs/__schema5"
},
"shortPathMode": {
"$ref": "#/$defs/__schema7"
},
"holdSeconds": {
"$ref": "#/$defs/__schema8"
},
"expiry": {
"$ref": "#/$defs/__schema3"
},
"eligibilityHash": {
"$ref": "#/$defs/__schema9"
}
},
"required": [
"rewardToken",
"commissionBps",
"perSaleCap",
"campaignLiabilityCap",
"maxRewardedAncestors",
"weightsBps",
"shortPathMode",
"holdSeconds",
"expiry",
"eligibilityHash"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"budgetAlertSales": {
"type": "integer",
"minimum": 1,
"maximum": 50
},
"agreement": {
"type": "object",
"properties": {
"version": {
"type": "string"
},
"publishedAt": {
"$ref": "#/$defs/__schema1"
},
"url": {
"type": "string",
"format": "uri"
},
"acceptedAt": {
"$ref": "#/$defs/__schema1"
}
},
"required": ["version", "publishedAt", "url", "acceptedAt"],
"additionalProperties": false
},
"businessWallet": {
"$ref": "#/$defs/__schema0"
},
"showSupportEmail": {
"type": "boolean"
}
},
"required": [
"id",
"name",
"slug",
"address",
"description",
"logo",
"website",
"verificationTier",
"joinedAt",
"offersCount",
"closedAt",
"supportEmail",
"region",
"defaults",
"budgetAlertSales",
"agreement",
"businessWallet"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"__schema1": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
"__schema2": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema3": {
"type": "string"
},
"__schema4": {
"type": "integer",
"minimum": 1,
"maximum": 5
},
"__schema5": {
"minItems": 1,
"maxItems": 5,
"type": "array",
"items": {
"$ref": "#/$defs/__schema6"
}
},
"__schema6": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema7": {
"default": "RENORMALIZE_EXISTING",
"type": "string",
"enum": ["RENORMALIZE_EXISTING", "RETURN_UNUSED"]
},
"__schema8": {
"type": "integer",
"minimum": 60,
"maximum": 7776000
},
"__schema9": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{64}$"
}
}
}
```
## merchants.update
**PATCH `/v1/merchant`** · **Core live** · Access: **session**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L246).
An authenticated session is necessary; ownership, merchant/operator scope, and any fresh-confirmation requirements are checked separately by the service.
**Client input fields**
| Field | Type | Required | Constraints |
| - | - | - | - |
| `name` | string | No | Min length: 2; Max length: 100 |
| `slug` | string | No | Min length: 3; Max length: 30; Pattern validated; see input schema |
| `description` | string | No | Max length: 2000; Default: `""` |
| `website` | string or null | No | Default: `null` |
| `supportEmail` | string | No | Max length: 200; Format: email; Pattern validated; see input schema |
| `region` | string | No | Min length: 2; Max length: 80 |
| `budgetAlertSales` | integer | No | Minimum: 1; Maximum: 50; Default: `5` |
| `logo` | string or null | No | See nested schema and runtime validation |
| `category` | "digital" · "education" · "software" · "design" · "other" | No | See nested schema and runtime validation |
| `showSupportEmail` | boolean | No | See nested schema and runtime validation |
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 2,
"maxLength": 100
},
"slug": {
"type": "string",
"minLength": 3,
"maxLength": 30,
"pattern": "^[a-z][a-z0-9_]+$"
},
"description": {
"default": "",
"type": "string",
"maxLength": 2000
},
"website": {
"default": null,
"anyOf": [
{
"$ref": "#/$defs/__schema0"
},
{
"type": "null"
}
]
},
"supportEmail": {
"type": "string",
"maxLength": 200,
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
},
"region": {
"type": "string",
"minLength": 2,
"maxLength": 80
},
"budgetAlertSales": {
"default": 5,
"type": "integer",
"minimum": 1,
"maximum": 50
},
"logo": {
"anyOf": [
{
"$ref": "#/$defs/__schema0"
},
{
"type": "null"
}
]
},
"category": {
"type": "string",
"enum": ["digital", "education", "software", "design", "other"]
},
"showSupportEmail": {
"type": "boolean"
}
},
"additionalProperties": false,
"$defs": {
"__schema0": {
"type": "string",
"format": "uri"
}
}
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9_-]+$"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"address": {
"$ref": "#/$defs/__schema0"
},
"description": {
"type": "string"
},
"logo": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"website": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"verificationTier": {
"type": "string",
"enum": ["unverified", "domain", "business"]
},
"joinedAt": {
"$ref": "#/$defs/__schema1"
},
"offersCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"closedAt": {
"anyOf": [
{
"$ref": "#/$defs/__schema1"
},
{
"type": "null"
}
]
},
"category": {
"type": ["string", "null"]
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"supportEmail": {
"type": "string",
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
},
"moderation": {
"type": "object",
"properties": {
"state": {
"type": "string",
"enum": ["visible", "hidden"]
},
"actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"at": {
"$ref": "#/$defs/__schema1"
},
"action": {
"type": "string"
},
"reasonCategory": {
"type": "string"
}
},
"required": ["at", "action", "reasonCategory"],
"additionalProperties": false
}
}
},
"required": ["state", "actions"],
"additionalProperties": false
},
"region": {
"type": "string"
},
"defaults": {
"anyOf": [
{
"type": "object",
"properties": {
"rewardToken": {
"$ref": "#/$defs/__schema0"
},
"commissionBps": {
"$ref": "#/$defs/__schema2"
},
"perSaleCap": {
"$ref": "#/$defs/__schema3"
},
"campaignLiabilityCap": {
"$ref": "#/$defs/__schema3"
},
"maxRewardedAncestors": {
"$ref": "#/$defs/__schema4"
},
"weightsBps": {
"$ref": "#/$defs/__schema5"
},
"shortPathMode": {
"$ref": "#/$defs/__schema7"
},
"holdSeconds": {
"$ref": "#/$defs/__schema8"
},
"expiry": {
"$ref": "#/$defs/__schema3"
},
"eligibilityHash": {
"$ref": "#/$defs/__schema9"
}
},
"required": [
"rewardToken",
"commissionBps",
"perSaleCap",
"campaignLiabilityCap",
"maxRewardedAncestors",
"weightsBps",
"shortPathMode",
"holdSeconds",
"expiry",
"eligibilityHash"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"budgetAlertSales": {
"type": "integer",
"minimum": 1,
"maximum": 50
},
"agreement": {
"type": "object",
"properties": {
"version": {
"type": "string"
},
"publishedAt": {
"$ref": "#/$defs/__schema1"
},
"url": {
"type": "string",
"format": "uri"
},
"acceptedAt": {
"$ref": "#/$defs/__schema1"
}
},
"required": ["version", "publishedAt", "url", "acceptedAt"],
"additionalProperties": false
},
"businessWallet": {
"$ref": "#/$defs/__schema0"
},
"showSupportEmail": {
"type": "boolean"
}
},
"required": [
"id",
"name",
"slug",
"address",
"description",
"logo",
"website",
"verificationTier",
"joinedAt",
"offersCount",
"closedAt",
"supportEmail",
"region",
"defaults",
"budgetAlertSales",
"agreement",
"businessWallet"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"__schema1": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
"__schema2": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema3": {
"type": "string"
},
"__schema4": {
"type": "integer",
"minimum": 1,
"maximum": 5
},
"__schema5": {
"minItems": 1,
"maxItems": 5,
"type": "array",
"items": {
"$ref": "#/$defs/__schema6"
}
},
"__schema6": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema7": {
"default": "RENORMALIZE_EXISTING",
"type": "string",
"enum": ["RENORMALIZE_EXISTING", "RETURN_UNUSED"]
},
"__schema8": {
"type": "integer",
"minimum": 60,
"maximum": 7776000
},
"__schema9": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{64}$"
}
}
}
```
## merchants.slugAvailable
**GET `/v1/merchant-slugs/:slug`** · **Core live** · Access: **session**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L247).
An authenticated session is necessary; ownership, merchant/operator scope, and any fresh-confirmation requirements are checked separately by the service.
**Client input fields**
| Field | Type | Required | Constraints |
| - | - | - | - |
| `slug` | string | Yes | See nested schema and runtime validation |
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"slug": {
"type": "string"
}
},
"required": ["slug"]
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"available": {
"type": "boolean"
},
"reason": {
"anyOf": [
{
"type": "string",
"enum": ["taken", "reserved", "invalid"]
},
{
"type": "null"
}
]
},
"suggestion": {
"type": ["string", "null"]
}
},
"required": ["available", "reason", "suggestion"],
"additionalProperties": false
}
```
## merchants.uploadLogo
**POST `/v1/merchant/logo`** · **Core live** · Access: **session**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L255).
An authenticated session is necessary; ownership, merchant/operator scope, and any fresh-confirmation requirements are checked separately by the service.
Transport: multipart form data. File/blob inputs require the original runtime schema; JSON Schema cannot represent browser Blob validation.
**Client input fields**
| Field | Type | Required | Constraints |
| - | - | - | - |
| `file` | See JSON schema | Yes | Max length: 2000000; Format: binary |
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary",
"contentEncoding": "binary",
"maxLength": 2000000,
"anyOf": [
{
"contentMediaType": "image/png"
},
{
"contentMediaType": "image/jpeg"
},
{
"contentMediaType": "image/webp"
}
]
}
},
"required": ["file"]
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"width": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"height": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"sha256": {
"type": "string",
"pattern": "^[\\da-f]{64}$"
}
},
"required": ["sha256"],
"additionalProperties": false
}
```
## merchants.requestVerification
**POST `/v1/merchant/verification`** · **Designed — unavailable** · Access: **session**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L259).
An authenticated session is necessary; ownership, merchant/operator scope, and any fresh-confirmation requirements are checked separately by the service.
**Client input fields**
| Field | Type | Required | Constraints |
| - | - | - | - |
| `tier` | "domain" | Yes | See nested schema and runtime validation |
| `domain` | string | Yes | See nested schema and runtime validation |
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"tier": {
"type": "string",
"const": "domain"
},
"domain": {
"type": "string"
}
},
"required": ["tier", "domain"]
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": ["pending", "verified", "failed"]
},
"record": {
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "TXT"
},
"name": {
"type": "string"
},
"value": {
"type": "string"
}
},
"required": ["type", "name", "value"],
"additionalProperties": false
}
},
"required": ["status", "record"],
"additionalProperties": false
}
```
## merchants.close
**POST `/v1/merchant/close`** · **Core live** · Access: **session**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L266).
An authenticated session is necessary; ownership, merchant/operator scope, and any fresh-confirmation requirements are checked separately by the service.
**Client input fields**
| Field | Type | Required | Constraints |
| - | - | - | - |
| `confirmationToken` | string | Yes | Min length: 32; Max length: 128 |
| `confirmation` | string | Yes | See nested schema and runtime validation |
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"confirmationToken": {
"type": "string",
"minLength": 32,
"maxLength": 128
},
"confirmation": {
"type": "string"
}
},
"required": ["confirmationToken", "confirmation"]
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"ok": {
"type": "boolean",
"const": true
}
},
"required": ["ok"],
"additionalProperties": false
}
```
## merchants.offers
**GET `/v1/merchants/:slug/offers`** · **Core live** · Access: **public**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L267).
**Client input fields**
| Field | Type | Required | Constraints |
| - | - | - | - |
| `slug` | string | Yes | See nested schema and runtime validation |
| `cursor` | string | No | See nested schema and runtime validation |
| `limit` | integer | No | Minimum: 1; Maximum: 100 |
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"slug": {
"type": "string"
},
"cursor": {
"type": "string"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"required": ["slug"]
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"campaignId": {
"anyOf": [
{
"$ref": "#/$defs/__schema0"
},
{
"type": "string",
"pattern": "^demo-[\\w-]+$"
}
]
},
"chainId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"contractAddress": {
"$ref": "#/$defs/__schema1"
},
"state": {
"type": "string",
"enum": [
"DRAFT_OFFCHAIN",
"CREATED_UNFUNDED",
"FUNDED_ACTIVE",
"PAUSED",
"ENDED",
"EXPIRED"
]
},
"merchant": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"address": {
"$ref": "#/$defs/__schema1"
}
},
"required": ["name", "slug", "address"],
"additionalProperties": false
},
"product": {
"type": "object",
"properties": {
"id": {
"$ref": "#/$defs/__schema2"
},
"title": {
"type": "string"
},
"summary": {
"type": "string"
},
"media": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"$ref": "#/$defs/__schema2"
},
"kind": {
"type": "string",
"enum": ["image", "download"]
},
"size": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"sha256": {
"type": "string",
"pattern": "^[\\da-f]{64}$"
},
"url": {
"type": "string",
"format": "uri"
},
"width": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"height": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": ["id", "kind", "size", "sha256"],
"additionalProperties": false
}
},
"category": {
"type": "string"
}
},
"required": ["id", "title", "summary", "media", "category"],
"additionalProperties": false
},
"token": {
"type": "object",
"properties": {
"address": {
"$ref": "#/$defs/__schema1"
},
"symbol": {
"type": "string"
},
"decimals": {
"type": "integer",
"minimum": 0,
"maximum": 36
},
"name": {
"type": "string"
},
"testnet": {
"type": "boolean"
}
},
"required": ["address", "symbol", "decimals"],
"additionalProperties": false
},
"price": {
"$ref": "#/$defs/__schema0"
},
"policy": {
"type": "object",
"properties": {
"rewardToken": {
"$ref": "#/$defs/__schema1"
},
"commissionBps": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"perSaleCap": {
"$ref": "#/$defs/__schema0"
},
"campaignLiabilityCap": {
"$ref": "#/$defs/__schema0"
},
"maxRewardedAncestors": {
"type": "integer",
"minimum": 1,
"maximum": 5
},
"weightsBps": {
"minItems": 1,
"maxItems": 5,
"type": "array",
"items": {
"$ref": "#/$defs/__schema3"
}
},
"shortPathMode": {
"default": "RENORMALIZE_EXISTING",
"type": "string",
"enum": ["RENORMALIZE_EXISTING", "RETURN_UNUSED"]
},
"holdSeconds": {
"type": "integer",
"minimum": 60,
"maximum": 7776000
},
"expiry": {
"$ref": "#/$defs/__schema0"
},
"eligibilityHash": {
"$ref": "#/$defs/__schema4"
},
"policyHash": {
"$ref": "#/$defs/__schema4"
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"effectiveAt": {
"$ref": "#/$defs/__schema5"
},
"regions": {
"type": "array",
"items": {
"type": "string"
}
},
"sharingRules": {
"type": "array",
"items": {
"type": "string"
}
},
"registrationTx": {
"anyOf": [
{
"type": "object",
"properties": {
"hash": {
"$ref": "#/$defs/__schema4"
},
"blockNumber": {
"$ref": "#/$defs/__schema0"
},
"explorerUrl": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"at": {
"$ref": "#/$defs/__schema5"
}
},
"required": ["hash", "blockNumber", "explorerUrl"],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"salesCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"rewardToken",
"commissionBps",
"perSaleCap",
"campaignLiabilityCap",
"maxRewardedAncestors",
"weightsBps",
"shortPathMode",
"holdSeconds",
"expiry",
"eligibilityHash",
"policyHash",
"version",
"effectiveAt",
"regions",
"sharingRules"
],
"additionalProperties": false
},
"rewardAvailable": {
"$ref": "#/$defs/__schema0"
},
"rewardTotal": {
"$ref": "#/$defs/__schema0"
},
"settledSales": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"onchainUrl": {
"type": "string",
"format": "uri"
},
"rankReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"inviteOnly": {
"type": "boolean"
},
"endsAt": {
"$ref": "#/$defs/__schema5"
}
},
"required": [
"campaignId",
"chainId",
"contractAddress",
"state",
"merchant",
"product",
"token",
"price",
"policy",
"rewardAvailable",
"rewardTotal",
"settledSales",
"onchainUrl",
"rankReasons"
],
"additionalProperties": false
}
},
"nextCursor": {
"type": ["string", "null"]
}
},
"required": ["items", "nextCursor"],
"additionalProperties": false,
"$defs": {
"__schema0": {
"type": "string"
},
"__schema1": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"__schema2": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9_-]+$"
},
"__schema3": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema4": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{64}$"
},
"__schema5": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
}
}
}
```
## studio.templates
**GET `/v1/merchant/policy-templates`** · **Core live** · Access: **session**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L418).
An authenticated session is necessary; ownership, merchant/operator scope, and any fresh-confirmation requirements are checked separately by the service.
**Client input fields**
No fields. Use an empty object for the client method input.
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9_-]+$"
},
"name": {
"type": "string"
},
"policy": {
"$ref": "#/$defs/__schema0"
},
"status": {
"type": "string",
"enum": ["active", "archived"]
},
"createdAt": {
"$ref": "#/$defs/__schema10"
},
"category": {
"type": ["string", "null"]
},
"description": {
"type": "string"
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"updatedAt": {
"$ref": "#/$defs/__schema10"
},
"history": {
"type": "array",
"items": {
"type": "object",
"properties": {
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"policy": {
"$ref": "#/$defs/__schema0"
},
"savedAt": {
"$ref": "#/$defs/__schema10"
}
},
"required": ["version", "policy", "savedAt"],
"additionalProperties": false
}
},
"usedBy": {
"type": "array",
"items": {
"type": "object",
"properties": {
"campaignId": {
"anyOf": [
{
"$ref": "#/$defs/__schema3"
},
{
"type": "string",
"pattern": "^demo-[\\w-]+$"
}
]
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": ["campaignId", "version"],
"additionalProperties": false
}
}
},
"required": ["id", "name", "policy", "status", "createdAt"],
"additionalProperties": false
},
"$defs": {
"__schema0": {
"type": "object",
"properties": {
"rewardToken": {
"$ref": "#/$defs/__schema1"
},
"commissionBps": {
"$ref": "#/$defs/__schema2"
},
"perSaleCap": {
"$ref": "#/$defs/__schema3"
},
"campaignLiabilityCap": {
"$ref": "#/$defs/__schema3"
},
"maxRewardedAncestors": {
"$ref": "#/$defs/__schema4"
},
"weightsBps": {
"$ref": "#/$defs/__schema5"
},
"shortPathMode": {
"$ref": "#/$defs/__schema7"
},
"holdSeconds": {
"$ref": "#/$defs/__schema8"
},
"expiry": {
"$ref": "#/$defs/__schema3"
},
"eligibilityHash": {
"$ref": "#/$defs/__schema9"
}
},
"required": [
"rewardToken",
"commissionBps",
"perSaleCap",
"campaignLiabilityCap",
"maxRewardedAncestors",
"weightsBps",
"shortPathMode",
"holdSeconds",
"expiry",
"eligibilityHash"
],
"additionalProperties": false
},
"__schema1": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"__schema2": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema3": {
"type": "string"
},
"__schema4": {
"type": "integer",
"minimum": 1,
"maximum": 5
},
"__schema5": {
"minItems": 1,
"maxItems": 5,
"type": "array",
"items": {
"$ref": "#/$defs/__schema6"
}
},
"__schema6": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema7": {
"default": "RENORMALIZE_EXISTING",
"type": "string",
"enum": ["RENORMALIZE_EXISTING", "RETURN_UNUSED"]
},
"__schema8": {
"type": "integer",
"minimum": 60,
"maximum": 7776000
},
"__schema9": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{64}$"
},
"__schema10": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
}
}
}
```
## studio.saveTemplate
**POST `/v1/merchant/policy-templates`** · **Core live** · Access: **session**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L419).
An authenticated session is necessary; ownership, merchant/operator scope, and any fresh-confirmation requirements are checked separately by the service.
**Client input fields**
| Field | Type | Required | Constraints |
| - | - | - | - |
| `name` | string | Yes | Min length: 2; Max length: 100 |
| `policy` | object | Yes | See nested schema and runtime validation |
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 2,
"maxLength": 100
},
"policy": {
"type": "object",
"properties": {
"rewardToken": {
"$ref": "#/$defs/__schema0"
},
"commissionBps": {
"$ref": "#/$defs/__schema1"
},
"perSaleCap": {
"$ref": "#/$defs/__schema2"
},
"campaignLiabilityCap": {
"$ref": "#/$defs/__schema2"
},
"maxRewardedAncestors": {
"$ref": "#/$defs/__schema3"
},
"weightsBps": {
"$ref": "#/$defs/__schema4"
},
"shortPathMode": {
"$ref": "#/$defs/__schema6"
},
"holdSeconds": {
"$ref": "#/$defs/__schema7"
},
"expiry": {
"$ref": "#/$defs/__schema2"
},
"eligibilityHash": {
"$ref": "#/$defs/__schema8"
}
},
"required": [
"rewardToken",
"commissionBps",
"perSaleCap",
"campaignLiabilityCap",
"maxRewardedAncestors",
"weightsBps",
"holdSeconds",
"expiry",
"eligibilityHash"
],
"additionalProperties": false
}
},
"required": ["name", "policy"],
"$defs": {
"__schema0": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"__schema1": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema2": {
"type": "string",
"maxLength": 78,
"pattern": "^(0|[1-9]\\d*)$"
},
"__schema3": {
"type": "integer",
"minimum": 1,
"maximum": 5
},
"__schema4": {
"minItems": 1,
"maxItems": 5,
"type": "array",
"items": {
"$ref": "#/$defs/__schema5"
}
},
"__schema5": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema6": {
"default": "RENORMALIZE_EXISTING",
"type": "string",
"enum": ["RENORMALIZE_EXISTING", "RETURN_UNUSED"]
},
"__schema7": {
"type": "integer",
"minimum": 60,
"maximum": 7776000
},
"__schema8": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{64}$"
}
}
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9_-]+$"
},
"name": {
"type": "string"
},
"policy": {
"$ref": "#/$defs/__schema0"
},
"status": {
"type": "string",
"enum": ["active", "archived"]
},
"createdAt": {
"$ref": "#/$defs/__schema10"
},
"category": {
"type": ["string", "null"]
},
"description": {
"type": "string"
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"updatedAt": {
"$ref": "#/$defs/__schema10"
},
"history": {
"type": "array",
"items": {
"type": "object",
"properties": {
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"policy": {
"$ref": "#/$defs/__schema0"
},
"savedAt": {
"$ref": "#/$defs/__schema10"
}
},
"required": ["version", "policy", "savedAt"],
"additionalProperties": false
}
},
"usedBy": {
"type": "array",
"items": {
"type": "object",
"properties": {
"campaignId": {
"anyOf": [
{
"$ref": "#/$defs/__schema3"
},
{
"type": "string",
"pattern": "^demo-[\\w-]+$"
}
]
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": ["campaignId", "version"],
"additionalProperties": false
}
}
},
"required": ["id", "name", "policy", "status", "createdAt"],
"additionalProperties": false,
"$defs": {
"__schema0": {
"type": "object",
"properties": {
"rewardToken": {
"$ref": "#/$defs/__schema1"
},
"commissionBps": {
"$ref": "#/$defs/__schema2"
},
"perSaleCap": {
"$ref": "#/$defs/__schema3"
},
"campaignLiabilityCap": {
"$ref": "#/$defs/__schema3"
},
"maxRewardedAncestors": {
"$ref": "#/$defs/__schema4"
},
"weightsBps": {
"$ref": "#/$defs/__schema5"
},
"shortPathMode": {
"$ref": "#/$defs/__schema7"
},
"holdSeconds": {
"$ref": "#/$defs/__schema8"
},
"expiry": {
"$ref": "#/$defs/__schema3"
},
"eligibilityHash": {
"$ref": "#/$defs/__schema9"
}
},
"required": [
"rewardToken",
"commissionBps",
"perSaleCap",
"campaignLiabilityCap",
"maxRewardedAncestors",
"weightsBps",
"shortPathMode",
"holdSeconds",
"expiry",
"eligibilityHash"
],
"additionalProperties": false
},
"__schema1": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"__schema2": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema3": {
"type": "string"
},
"__schema4": {
"type": "integer",
"minimum": 1,
"maximum": 5
},
"__schema5": {
"minItems": 1,
"maxItems": 5,
"type": "array",
"items": {
"$ref": "#/$defs/__schema6"
}
},
"__schema6": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema7": {
"default": "RENORMALIZE_EXISTING",
"type": "string",
"enum": ["RENORMALIZE_EXISTING", "RETURN_UNUSED"]
},
"__schema8": {
"type": "integer",
"minimum": 60,
"maximum": 7776000
},
"__schema9": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{64}$"
},
"__schema10": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
}
}
}
```
## studio.simulate
**POST `/v1/policies/simulate`** · **Core live** · Access: **public**. [Source definition](https://github.com/Enoch208/spoke/blob/1c90c5e408592d5b4e87944ea79b998890633249/packages/protocol/src/api/methods.ts#L423).
**Client input fields**
| Field | Type | Required | Constraints |
| - | - | - | - |
| `price` | string | Yes | Max length: 78; Pattern validated; see input schema |
| `policy` | object | Yes | See nested schema and runtime validation |
| `pathLengths` | integer\[] | Yes | Min items: 1; Max items: 20 |
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"price": {
"$ref": "#/$defs/__schema0"
},
"policy": {
"type": "object",
"properties": {
"rewardToken": {
"$ref": "#/$defs/__schema1"
},
"commissionBps": {
"$ref": "#/$defs/__schema2"
},
"perSaleCap": {
"$ref": "#/$defs/__schema0"
},
"campaignLiabilityCap": {
"$ref": "#/$defs/__schema0"
},
"maxRewardedAncestors": {
"$ref": "#/$defs/__schema3"
},
"weightsBps": {
"$ref": "#/$defs/__schema4"
},
"shortPathMode": {
"$ref": "#/$defs/__schema6"
},
"holdSeconds": {
"$ref": "#/$defs/__schema7"
},
"expiry": {
"$ref": "#/$defs/__schema0"
},
"eligibilityHash": {
"$ref": "#/$defs/__schema8"
}
},
"required": [
"rewardToken",
"commissionBps",
"perSaleCap",
"campaignLiabilityCap",
"maxRewardedAncestors",
"weightsBps",
"holdSeconds",
"expiry",
"eligibilityHash"
],
"additionalProperties": false
},
"pathLengths": {
"minItems": 1,
"maxItems": 20,
"type": "array",
"items": {
"$ref": "#/$defs/__schema9"
}
}
},
"required": ["price", "policy", "pathLengths"],
"$defs": {
"__schema0": {
"type": "string",
"maxLength": 78,
"pattern": "^(0|[1-9]\\d*)$"
},
"__schema1": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"__schema2": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema3": {
"type": "integer",
"minimum": 1,
"maximum": 5
},
"__schema4": {
"minItems": 1,
"maxItems": 5,
"type": "array",
"items": {
"$ref": "#/$defs/__schema5"
}
},
"__schema5": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"__schema6": {
"default": "RENORMALIZE_EXISTING",
"type": "string",
"enum": ["RENORMALIZE_EXISTING", "RETURN_UNUSED"]
},
"__schema7": {
"type": "integer",
"minimum": 60,
"maximum": 7776000
},
"__schema8": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{64}$"
},
"__schema9": {
"type": "integer",
"minimum": 0,
"maximum": 256
}
}
}
```
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"policyHash": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{64}$"
},
"simulations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"pathLength": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"weightsBps": {
"type": "array",
"items": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"amounts": {
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
"reserved": {
"$ref": "#/$defs/__schema0"
},
"unallocated": {
"$ref": "#/$defs/__schema0"
}
},
"required": [
"pathLength",
"weightsBps",
"amounts",
"reserved",
"unallocated"
],
"additionalProperties": false
}
},
"contractChecks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"nodeId": {
"anyOf": [
{
"$ref": "#/$defs/__schema0"
},
{
"type": "string",
"pattern": "^demo-[\\w-]+$"
}
]
},
"pathLength": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"amounts": {
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
"rewardTotal": {
"$ref": "#/$defs/__schema0"
},
"matches": {
"type": "boolean"
},
"blockNumber": {
"$ref": "#/$defs/__schema0"
}
},
"required": [
"nodeId",
"pathLength",
"amounts",
"rewardTotal",
"matches",
"blockNumber"
],
"additionalProperties": false
}
}
},
"required": ["policyHash", "simulations"],
"additionalProperties": false,
"$defs": {
"__schema0": {
"type": "string"
}
}
}
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.