For agents

# Sponsored Code — Documentation

> Sponsored Code turns Claude Code's "thinking…" word into a clean, clearly-labeled ad slot and
> splits the revenue with developers in USDC on Polygon. Earnings are paid to your wallet on-chain,
> and every payout is publicly auditable.

This file is the entire Sponsored Code documentation as one plain-text document, for AI agents and
anyone pasting the docs into an assistant. Browse the rendered docs at https://sponsoredcode.com/docs
or fetch this file directly at https://sponsoredcode.com/llms.txt

Two ways in, depending on who you are:

- Developers — earn USDC for the ad slot with the `scode` CLI. See "For developers".
- Brands — launch campaigns and pull analytics from the terminal, your own code ("SDK & API"),
  or Claude ("MCP server").

## Overview

### How it works

- Developers install the CLI, point it at a Polygon wallet, and earn USDC for the ad slot — the
  client never touches your code or keys.
- Brands launch a campaign, bid in an open auction, and pay only for verified views. A click is
  worth far more than an impression.
- Payouts settle on-chain in USDC; you claim to your wallet whenever it's worth the gas — verify the
  payout contract yourself (see "Contracts").

---

## For developers

Earn USDC for Claude Code's "thinking…" word — a clean, clearly-labeled ad slot. One command
turns it on. Nothing patches your editor and nothing touches your code or keys.

### Start earning

One command installs, registers, and turns the slot on. It asks for a payout wallet the first time —
or pass `--wallet` to skip the prompt. Your wallet is stored server-side; this machine only ever
holds an encrypted token.

```bash
# install + register + turn the slot on — one command (asks for your wallet)
npx sponsored-code start

# already know it? pass it inline to skip the prompt
npx sponsored-code start --wallet 0xYourWallet

# check status (account · integrity · state) anytime
scode status
```

### Pause or stop

Toggle the slot whenever you want — pausing restores stock Claude Code instantly. The VS Code
extension has the same switch: the Sponsored Code panel has a pause/resume toggle and a
clearly-labeled status-bar line.

```bash
scode off   # pause — restores stock Claude Code
scode on    # resume earning
```

### Get paid

You earn a share of every verified view, denominated in USDC. Earnings batch up and you claim them
to your wallet on-chain whenever it's worth the gas — the payout contract is public, so you can
verify every settlement yourself (see "Contracts").

---

## For brands

Reach developers inside their AI coding tools. Launch a campaign, bid in an open auction, and pay
only for verified views — a click is worth far more than an impression. Run it from the terminal,
your own code, or Claude.

### Launch from the terminal

Sign in with your wallet and launch a campaign straight from the CLI. The private key signs the
challenge locally and is never sent — only the signature is. Prefer a browser wallet? Use the
dashboard instead.

```bash
# sign in (key signs locally; or set SCODE_WALLET_KEY)
scode brand login --key 0xYourPrivateKey

# launch a campaign — it joins the live auction immediately
scode brand campaign \
  --brand "Example" \
  --tagline "yield on idle USDC" \
  --url https://example.com \
  --bid 20 --budget 500

# track impressions · spend · clicks · geography
scode brand stats
```

#### Campaign flags

- `--brand`, `--tagline`, `--url` — required.
- `--bid` max CPM in USD (default 20), `--budget` USDC deposit (default 500).
- `--color` hex, `--team` name/slug (defaults to your Personal team).

### How campaigns run

- Open auction — your bid competes for each slot; you never pay more than you set.
- Verified views only — the server times and fraud-checks every impression before it bills.
- Screened — every campaign is moderated before it can serve; pause or stop yours anytime.

---

## 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.

```bash
export SCODE_API_KEY="scode_live_…"
```

### Install the SDK

Dependency-free and isomorphic — it runs on Node 18+ and in the browser.

```bash
npm install @sponsored-code/sdk
```

### Quickstart

```ts
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`, …).

```ts
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 }.

```bash
# 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.

---

## MCP server

The Sponsored Code MCP server gives Claude (or any Model Context Protocol client) direct tools to
read network activity and manage your campaigns — "how are my ads doing?", "launch a campaign for
X" — without leaving the chat.

### Install

Runs over stdio via `npx` — no global install, no keys, no config. Pick your client:

Claude Code — one line:

```bash
claude mcp add sponsored-code -- npx -y sponsored-code mcp
```

Claude Desktop (claude_desktop_config.json) or Cursor (~/.cursor/mcp.json) — add the server:

```json
{
  "mcpServers": {
    "sponsored-code": {
      "command": "npx",
      "args": ["-y", "sponsored-code", "mcp"]
    }
  }
}
```

### Sign in

Public tools work right away. The first time a tool needs your account (e.g. `create_campaign`),
your browser opens to connect your wallet and sign once — exactly like the dashboard. You can also
do it ahead of time:

```bash
scode login
```

The session is stored encrypted on your machine. No private key is ever typed into your terminal or
your MCP config.

### Tools

- `network_stats` — impressions, wallets earning, USDC settled, live campaigns.
- `market_overview` — the live bid market (top bid + active campaigns).
- `recent_impressions` — the latest impressions from the public ledger.
- `campaign_stats` · sign-in — your team's impressions, spend, clicks, geography.
- `list_campaigns` · sign-in — your campaigns and their status.
- `create_campaign` · sign-in — launch a campaign into the live auction.

### Automated (power users only)

For headless or CI environments where no browser is available, you can sign in non-interactively
with a brand wallet private key in `SCODE_WALLET_KEY`. It signs locally and is never sent — but
it's a raw private key, so treat it like any secret. Most people should use the browser sign-in.

```bash
claude mcp add sponsored-code \
  --env SCODE_WALLET_KEY=0xYourBrandKey \
  -- npx -y sponsored-code mcp
```

```json
{
  "mcpServers": {
    "sponsored-code": {
      "command": "npx",
      "args": ["-y", "sponsored-code", "mcp"],
      "env": { "SCODE_WALLET_KEY": "0xYourBrandKey" }
    }
  }
}
```

---

## Contracts

Every developer payout settles on-chain in USDC on Polygon, through our open, verified payout
contract. The live contract addresses are published on https://sponsoredcode.com/docs/contracts —
read the verified source yourself on Polygonscan.

Payouts are in USDC (Circle's canonical Polygon token). Earnings batch up and you claim them to your
wallet on-chain whenever it's worth the gas.