API overview
The complete six-operation HTTP surface for the partner payout integration.
The partner API is a versioned, server-to-server JSON API. It accepts exact reward instructions and exposes their durable records and approved campaign configuration.
Base URL and version#
Use the environment-specific service origin supplied for your integration, then append the /v1 path. Local examples use http://localhost:3000. Remote environments require HTTPS.
There is no public production hostname implied by these docs or by the marketing website. Do not send server credentials to an origin guessed from a brand or package name.
The OpenAPI 3.1 contract is the route and schema authority for this documentation set.
Operations#
| Method | Path | Description |
|---|---|---|
POST | /v1/rewards | Accept an exact reward instruction. |
GET | /v1/rewards | List and filter rewards. |
GET | /v1/rewards/{rewardId} | Read a reward. |
POST | /v1/rewards/{rewardId}/cancel | Cancel a reward before its approval. |
GET | /v1/campaigns | List approved campaigns. |
GET | /v1/campaigns/{campaignId} | Read a campaign. |
There is no public campaign-creation, asset-list, bulk-issuance, approval, sending, refund, wallet-provisioning, or webhook-registration endpoint in this contract. The dashboard's internal console API is not part of the partner API.
Headers#
| Header | Direction | Use |
|---|---|---|
Authorization: Bearer ... | Request | Required for every operation. |
Content-Type: application/json | Request | Use on requests with JSON bodies. |
Idempotency-Key | Request | Required on issuance and cancellation. |
X-Request-Id | Response | Server-generated correlation ID. |
Idempotency-Replayed: true | Issuance replay response | An identical accepted instruction was replayed without new economic effects. |
Retry-After | Throttling response | Delay before retrying after rate limiting. |
Credentials remain valid only within their configured project, environment, campaign, and operation access. Financial idempotency never bypasses authorization.
Response envelopes#
Resource responses use {data: resource}. List responses use {data: resource[], nextCursor: string | null}. Error responses use {error: {code, message, requestId, existingRewardId?}}.
A first issuance returns 201. An identical accepted issuance replay returns 200 with the resource's current state, not a frozen copy of its original response. Cancellation and reads return 200 when successful.
The TypeScript SDK unwraps single resources but preserves list envelopes. See TypeScript SDK.
Amounts, identifiers, and time#
All token quantities are integer base-unit strings. Never deserialize them into JavaScript numbers for calculations. Chain IDs and token decimals are JSON integers; block numbers in delivery evidence are strings.
Resource IDs are opaque strings of 1–96 letters, digits, underscores, or hyphens. Do not infer authorization or behavior from an example prefix.
API timestamps use ISO 8601 date-time strings. Examples use UTC. Keep event identifiers case-sensitive and free of personal information.
Strict inputs#
Request bodies reject unknown fields. Extra metadata, verified, email, fiat amounts, or chain/token overrides are not ignored. idempotencyKey belongs in the HTTP header, although the SDK accepts it as a client method input.
Filters are documented per list endpoint. There is no generic arbitrary-field query language or undocumented sort parameter.
Privacy and failure behavior#
Private responses are non-cacheable at the shared HTTP layer. The partner API is not a browser payout endpoint and does not rely on permissive cross-origin access.
Handle structured errors by error.code, and include requestId in support reports. An unavailable RPC is not represented as delivery or as successful zero rewards: a stored resource keeps its last verified status, and deliveryEvidence.checkedAt says how old it is.
The /v1 prefix identifies this contract. No historical API compatibility or deprecation period is implied for illustrative examples previously shown on the site.
Related: Authentication, Errors, and Rate limits and retries.