API Reference

CreativMoney is a P2P crypto trading platform for African markets. The HTTP API mirrors everything the web and mobile apps do — list wallets, send funds, open trades, approve settlements, reconcile ledgers. Most endpoints live behind the same session cookie the browser uses; a few use HMAC-signed webhooks or a shared cron secret.

Three minutes end-to-end:

• Sign up for an account at /register (or POST /api/auth/register).
• Verify your email with the 6-digit OTP sent to you.
• Log in via the web app or POST the credentials to the NextAuth endpoint. The response sets an authjs.session-token cookie — every subsequent authenticated request sends it automatically if you stay on the same origin.
• Call GET /api/wallets to list your wallets. That's a canonical first authenticated request.

curl https://www.creativmoney.com/api/wallets \
  -H "Cookie: authjs.session-token=COOKIE"

Everything under /api/* that isn't in the public allowlist returns 401 for anonymous callers. The error body is always `{ "message": "Unauthorized" }`.

Every endpoint lists its auth class in the badge column (Public, User, Admin, HMAC, Cron). The reference below shows how to satisfy each one.

Public

Anyone can call. No credentials. Useful for the landing page feeds and this documentation itself.

User

Any authenticated user. Send the session cookie from login.

Admin

Same cookie — but the caller's user row must have role ADMIN or SUPER_ADMIN. Otherwise 403.

HMAC

Webhook bodies signed with HMAC-SHA256. The signature goes in an x-*-signature header; the secret is shared out-of-band.

Cron

Internal invocations authenticated via Authorization: Bearer ${CRON_SECRET}. Do not expose this secret.

curl https://www.creativmoney.com/api/user/activities?limit=20 \
  -H "Cookie: authjs.session-token=eyJhbGciOi..."

BODY='{"event":"payment.received","hash":"..."}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$IBEX_WEBHOOK_SECRET" -r | cut -d' ' -f1)

curl https://www.creativmoney.com/api/webhooks/ibex \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-ibex-signature: $SIG" \
  -d "$BODY"

curl https://www.creativmoney.com/api/cron/expire-pending-txs \
  -H "Authorization: Bearer $CRON_SECRET"

Endpoints that move money require a 4-digit PIN in the request body on top of the session cookie. The PIN is the second factor — a stolen cookie alone cannot drain a wallet. Five wrong PIN attempts lock the account for 15 minutes (bcrypt + lockout via lib/pin.ts).

PIN-gated endpoints are marked with a 🔒 PIN badge in the reference below. Currently:

• POST /api/wallets/send
• POST /api/wallets/[id]/send
• POST /api/mobile-money/withdraw
• POST /api/njangi/[id]/contribute
• POST /api/settlements

curl https://www.creativmoney.com/api/wallets/send \
  -X POST \
  -H "Cookie: authjs.session-token=..." \
  -H "Content-Type: application/json" \
  -d '{
    "asset": "BTC",
    "amount": 0.001,
    "toAddress": "bc1qsp0kgwneue6y5r2trfvgn80y3y7jna2gmma0na",
    "pin": "1234"
  }'

The PIN travels in the request body — always over HTTPS, never reuse a logged request. The server hashes + constant-time-compares against the bcrypt'd PIN; plaintext is never persisted.

Four webhook endpoints (/api/webhooks/ibex, alchemy, shuftipro, crypto) accept signed POST bodies from external providers. Every one uses the same discipline:

• Read the raw request body as a string (before JSON.parse).
• Compute HMAC-SHA256(body, secret).
• Constant-time-compare against the provider's signature header.
• Return 401 on any mismatch or missing secret — never 500 with a descriptive error (information disclosure).
• Write a row to webhook_locks before mutating state. Concurrent retries lose gracefully; only one delivery completes.

import crypto from "node:crypto";

export async function receiveWebhook(req) {
  const body = await req.text();
  const expected = crypto.createHmac("sha256", process.env.WEBHOOK_SECRET)
    .update(body).digest("hex");
  const sig = req.headers.get("x-webhook-signature") ?? "";
  if (expected.length !== sig.length ||
      !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig))) {
    return new Response("Unauthorized", { status: 401 });
  }
  const event = JSON.parse(body);
  // ... handle event.type ...
  return new Response("ok");
}

Three things to know before shipping a client against this API:

Error shape

Most routes return { "message": string } with the right HTTP status; a few return { "error": string }. Successful responses wrap the payload in { "data": ... }.

Rate limits

32 endpoints are rate-limited (⚡ Rate badge). Limits vary; when exceeded you get HTTP 429 with a retryAfterSec field in the body and a Retry-After header.

Idempotency

Money-moving endpoints persist a unique `reference` on the ledger row. A retry with the same reference trips the DB uniqueness constraint and rolls the write back safely.

Common HTTP codes:

200 / 201

Success. Body is { data: ... } or the raw resource.

207 Multi-Status

Cron sweeper ran, some sub-steps failed. Body has per-bucket counts.

400

Validation error. Body tells you which field is wrong.

401

Missing / invalid auth. Also used for webhooks on signature mismatch OR unconfigured secret (deliberate — can't distinguish from outside).

403

Authenticated but not authorized (e.g., non-admin hitting /api/admin/*).

404

Resource not found. The admin-gated API doc returns 404 when the master toggle is off.

409

State conflict — trade already resolved by another admin, OTP already used, etc.

429

Rate limit. Retry-After header tells you how long to wait.

500

Server bug. Please report with the request-time timestamp.

List endpoints (transactions, notifications, trades, audit-logs, etc.) accept `?page=N&limit=M` query parameters. Defaults are sensible (page=1, limit=20-100 per endpoint), caps prevent unbounded reads. The response includes `total`, `page`, `limit`, and `hasMore`.

async function* fetchAllActivities() {
  let page = 1;
  while (true) {
    const r = await fetch(`/api/user/activities?limit=50&page=${page}`);
    const { data, hasMore } = await r.json();
    yield* data;
    if (!hasMore) return;
    page++;
  }
}