Server-Side API - Onchain Suite Docs

The server-side API is HTTP from your backend, authenticated with a secret (sk_…) key. Use it to register wallets as contacts, ingest form submissions, send pushes, and launch campaigns, everything that reads or writes data.

In plain terms. This is the toolkit your backend uses to talk to Onchain Suite directly, no dashboard, no browser. A developer keeps one secret key on the server and calls these to register wallets, pull in consented emails, send a push, or kick off a campaign. If all you want is notifications inside your dApp, you don’t need this, use the in-app SDK instead.

Secret keys are server-only. They grant full server-to-server access to your workspace, so never ship one to a browser, a mobile app, a repo, or any client. Client code uses a publishable (pk_…) key, which can only run the wallet auth handshake. If a secret key is ever exposed, roll it with zero grace immediately.

Authentication

Every call carries your secret key in a header. Two forms are accepted, use whichever your HTTP client makes easy:

Authorization: Bearer sk_live_…

x-secret-key: sk_live_…

The organization is derived from the key, you never pass an org id. Base path:

https://api.onchainsuite.com/api/v1

A sk_test_… key runs against your workspace in test mode, which is the safe way to integrate before going live, custom events sent with a test key are dry-run, for example. Read-only keys reject writes with 403. See API keys for scopes, rolling, and revocation.

Quickstart: ingest a capture

The highest-value first call for most backends: hand a consented email (and optional wallet) to a capture form from your server. If the form uses double opt-in, this kicks off the confirmation email; on confirmation the contact joins the bound list and can fire an automation.

curl -X POST https://api.onchainsuite.com/api/v1/forms/{token}/ingest \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "walletAddress": "0xabc...",
    "consent": true,
    "consentText": "I agree to receive product updates.",
    "fields": { "referral": "partner-app" }
  }'

const res = await fetch(
  `https://api.onchainsuite.com/api/v1/forms/${token}/ingest`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.ONCHAIN_SECRET_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      email: "alice@example.com",
      walletAddress: "0xabc...",
      consent: true,
      consentText: "I agree to receive product updates.",
      fields: { referral: "partner-app" },
    }),
  },
);

const data = await res.json(); // { ok: true, ... }

import os, requests

res = requests.post(
    f"https://api.onchainsuite.com/api/v1/forms/{token}/ingest",
    headers={"Authorization": f"Bearer {os.environ['ONCHAIN_SECRET_KEY']}"},
    json={
        "email": "alice@example.com",
        "walletAddress": "0xabc...",
        "consent": True,
        "consentText": "I agree to receive product updates.",
        "fields": {"referral": "partner-app"},
    },
)
res.raise_for_status()
data = res.json()  # { "ok": True, ... }

The key’s organization must own the form ({token} is the form’s token), or the request 404s. See capture forms for the body fields and the confirmation flow.

The server-to-server surface

A secret key unlocks a small, deliberate set of endpoints. Reads never expose the email address itself.

Endpoint	Purpose
`POST /identify`	Register a wallet as a contact. Wallet addresses only, PII is rejected.
`POST /forms/{token}/ingest`	Ingest a consented capture (email/wallet) into a bound list.
`POST /events`	Send a custom product event (signup, deposit, upgrade).
`POST /inapp/push`	Send a wallet-addressed in-app push.
`GET /contacts`	List contacts with reachability flags and tags. Never returns the email.
`GET /messages/pending?wallet=`	Fetch queued in-app pushes for one wallet.
`POST /campaigns/{id}/send`	Launch a campaign you’ve prepared in the dashboard.

Email can’t be set through POST /identify, by design. The only consent-first path for an address is a capture form, embedded or ingested server-side with the endpoint above.

A few semantics worth knowing before you wire these up:

POST /identify is idempotent on the wallet, lower-cases the address, and rejects any personal identifier (email, phone, name) with 400 PERSONAL_IDENTIFIER_REJECTED. To attach traits, send a custom event instead.
POST /campaigns/{id}/send takes a prepared campaign id, not the campaignRunId returned by /inapp/push. It can’t compose or retarget; it launches what’s already in the dashboard.
GET /contacts returns a per-contact emailReachable and pushReachable (and tags), never the email itself. emailReachable is true only for a real, sendable email, a wallet-only contact’s synthetic placeholder address doesn’t count, so an email-first audience can key a send off it. pushReachable is true for a connected wallet (an in-app push target). Narrow the list with ?tag= and ?hasWallet=true|false.
GET /events/catalog is a dashboard (session) route, not a secret-key one, so a sk_ key gets 401 there.
Lists and tags are populated server-side with tags / listIds / addToList on POST /events (see custom events). Finding a list’s ID, adding contacts already in your audience, and renaming or deleting a list are dashboard (session) actions under /audience/…, not secret-key routes — see Tags, lists & segments.

Wrap it once

Keep the secret key in one server-only module and expose your own thin routes, so the key never reaches the browser.

// lib/onchain.server.ts (SERVER ONLY). Never import into a "use client" file.
const OCS = "https://api.onchainsuite.com/api/v1";
const SK = process.env.ONCHAIN_SECRET_KEY!; // sk_live_… (server env, not NEXT_PUBLIC)

async function ocs(path: string, body?: unknown, method = "POST") {
  const res = await fetch(OCS + path, {
    method,
    headers: { Authorization: `Bearer ${SK}`, "Content-Type": "application/json" },
    body: body ? JSON.stringify(body) : undefined,
    cache: "no-store",
  });
  const json = await res.json().catch(() => ({}));
  if (!res.ok) throw new Error(`OCS ${res.status} ${JSON.stringify(json)}`);
  return json;
}

// event: ^[a-z0-9_.:-]{1,64}$ ; contact needs >= 1 of walletAddress / email / externalId
export const identify = (walletAddress: string) => ocs("/identify", { walletAddress });
export const track = (event: string, walletAddress: string, payload?: object) =>
  ocs("/events", { event, contact: { walletAddress }, payload });
export const pushInApp = (walletAddress: string, title: string, body: string) =>
  ocs("/inapp/push", { walletAddress, title, body });

Call it from your own endpoint so the browser only ever talks to your server:

// app/api/track/route.ts
import { NextRequest, NextResponse } from "next/server";
import { track } from "@/lib/onchain.server";

export const runtime = "nodejs";

export async function POST(req: NextRequest) {
  const { event, walletAddress, payload } = await req.json();
  try {
    return NextResponse.json(await track(event, walletAddress, payload));
  } catch (e) {
    return NextResponse.json({ error: String(e) }, { status: 502 });
  }
}

The shape of a backend integration

Register wallets as contacts, collect email through a form, with consent, then send product events and let campaigns and automations operate on the result. To hear about what happens next, delivered, viewed, unsubscribed, register a webhook.

Errors

Responses use the standard envelope. Common statuses:

Status	Meaning
`401`	Missing, invalid, or revoked secret key. Send it as `Authorization: Bearer` or `x-secret-key`.
`403`	The key is read-only and the route writes. Use a read/write key.
`404`	The resource isn’t in the key’s organization (e.g. a form token owned by another workspace).
`429`	Rate limited, back off and retry.

​Authentication

​Quickstart: ingest a capture

​The server-to-server surface

​Wrap it once

​The shape of a backend integration

​Errors

Authentication

Quickstart: ingest a capture

The server-to-server surface

Wrap it once

The shape of a backend integration

Errors