SDK & API

Drive campaigns and pull impression analytics from your own code with an API key — no wallet, no browser. Use the official @sponsored-code/sdk for TypeScript/JavaScript, or call the REST endpoints directly from any language.

Create an API key

In the dashboard, open API keys and click New key. You’ll see the secret (scode_live_…) once — we store only a hash, so copy it into a secret manager or your environment now. A key is scoped to a single team and to one of:

• Read only — analytics, impressions, list campaigns.
• Read & write — everything above, plus create, pause, and resume campaigns.

Keys are revocable at any time from the same screen; a revoked key stops working immediately.

export SCODE_API_KEY="scode_live_…"

Install the SDK

Dependency-free, and runs anywhere modern fetch exists — Node 18+, Deno, Bun, and edge/serverless runtimes. Your API key is a secret: use the SDK server-side, not in a public browser app.

npm install @sponsored-code/sdk

Quickstart

import { SponsoredCode } from "@sponsored-code/sdk";

const scode = new SponsoredCode({ apiKey: process.env.SCODE_API_KEY });

// Pull aggregate analytics for your team
const { totals, geo } = await scode.analytics();
console.log(`${totals.impressions} impressions · $${totals.spendUsd} spent`);

// Launch a campaign into the live auction (needs the "write" scope)
const campaign = await scode.campaigns.create({
  brand: "Example",
  tagline: "yield on idle USDC",
  url: "https://example.com",
  bidUsdCpm: 20,
  budgetUsd: 500,
});

// Pause / resume it later
await scode.campaigns.pause(campaign.id);

The constructor reads SCODE_API_KEY from the environment if you don’t pass apiKey.

Methods

• whoami() · read — the team + scopes the key grants.
• analytics() · read — impressions, spend, reach, clicks, geography, per-campaign rows.
• impressions({ limit }) · read — the team’s most recent attested impressions.
• campaigns.list() · read — every campaign in the team.
• campaigns.create(input) · write — launch a campaign into the auction.
• campaigns.pause(id) / resume(id) · write — toggle a campaign.

Analytics and impressions are aggregate— counts, spend, and geography for your campaigns. The API never exposes an individual developer’s wallet or IP.

Errors

Every failure throws a SponsoredCodeError with a numeric .status and a stable .code (unauthorized, insufficient_scope, no_campaign, …).

import { SponsoredCode, SponsoredCodeError } from "@sponsored-code/sdk";

try {
  await scode.campaigns.create({ brand: "Example", tagline: "…", url: "https://example.com" });
} catch (err) {
  if (err instanceof SponsoredCodeError && err.code === "insufficient_scope") {
    console.error("This key is read-only — create a read+write key.");
  }
}

REST API

No SDK required — every key authenticates a plain HTTPS request with an Authorization: Bearer header.

• GET /v1/api/me — the key’s team + scopes.
• GET /v1/api/analytics — aggregate team analytics.
• GET /v1/api/impressions?limit=20 — recent impressions (max 100).
• GET /v1/api/campaigns — list campaigns.
• POST /v1/api/campaigns · write — create a campaign.
• POST /v1/api/campaigns/status · write — { campaignId, status }.

# Read analytics
curl https://api.sponsoredcode.com/v1/api/analytics \
  -H "Authorization: Bearer $SCODE_API_KEY"

# Create a campaign (needs a read+write key)
curl -X POST https://api.sponsoredcode.com/v1/api/campaigns \
  -H "Authorization: Bearer $SCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brand":"Example","tagline":"yield on idle USDC","url":"https://example.com","bidUsdCpm":20,"budgetUsd":500}'

Keep keys safe

• A key is a secret. Store it in a secret manager or an environment variable — never commit it.
• Scope down: if a job only reads, give it a read-only key.
• Rotate by creating a new key and revoking the old one. Revocation is instant.
• Prefer this over the MCP server’s SCODE_WALLET_KEY (a raw wallet private key) for automation — an API key can’t move funds or change your payout wallet.

Next steps