For agents

# Sponsored Code — Documentation

> Sponsored Code puts one clean, clearly-labeled ad line in the AI tools developers already run in
> the terminal — Claude Code, Codex, Gemini, and more — and splits the revenue with them 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 line in your terminal AI tools with the `scode` CLI. See
  "For developers".
- Brands — launch campaigns and pull analytics from the dashboard, 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 line across
  their terminal AI tools — 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 a small, clearly-labeled ad line in the AI tools you already run in the terminal —
Claude Code, Codex, Gemini, or any command you point it at. One command sets it up. Nothing touches
your code or keys.

### Start earning

Install and run `scode`. On a fresh machine it walks you through it: pick where the ad line shows up,
then connect a Polygon wallet (or sign in with Google). Prefer the wallet prompt up front? Pass
`--wallet`. Your wallet is stored server-side; this machine only ever holds an encrypted token.

```bash
# install, then run the guided setup
npm install -g sponsored-code
scode

# or skip the wallet prompt if you already know it
scode start --wallet 0xYourWallet

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

### Choose your tools

Works with Claude Code, Codex, Gemini, and any other terminal AI tool — you keep running them exactly
as you do now. Claude Code and Codex are built in; to add anything else, register it once:

1. Run `scode integrations`.
2. Choose "Other CLIs".
3. Enter the command name, e.g. `aider`.

Now run `aider` like usual and the ad line rides along — toggle any tool on or off from that same
screen. Just want it for a single run? Skip the setup:

```bash
scode run aider
```

### Pause or stop

Toggle earning whenever you want — `scode off` restores your tools untouched. The VS Code extension
has the same switch: a pause/resume toggle and a clearly-labeled status-bar line.

```bash
scode off   # pause — restores your tools untouched
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 dashboard
or your own code.

### Launch a campaign

Create and fund a campaign from the dashboard — sign in with your browser wallet, set your bid and
budget, and it joins the live auction right away. To drive it from your own code instead, use the
SDK & API with an API key.

### How campaigns run

- Open auction — your bid competes for each slot; you never pay more than you set.
- Verified views only — every impression is checked 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.

---

## MCP servers

Bring Sponsored Code into Claude — or any Model Context Protocol client — right inside the chat. Two
servers, two audiences: brands manage campaigns, earners read what they've made.

### For brands — manage campaigns

"How are my ads doing?", "launch a campaign for X". It runs on the SDK and signs in with an API key.

### Get an API key

Create one in the dashboard under API keys. A read key covers analytics and listing; a write key can
launch and pause campaigns. The key can't move funds or change a payout wallet.

### Install

Runs over stdio via `npx` — set SCODE_API_KEY and pick your client:

Any MCP-capable CLI (Claude Code, Codex, Gemini, …) shares the same `mcp add` — swap the binary:

```bash
claude mcp add sponsored-code \
  --env SCODE_API_KEY=scode_live_your_key \
  -- 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"],
      "env": { "SCODE_API_KEY": "scode_live_your_key" }
    }
  }
}
```

### Tools

- `whoami` — the team and scopes your key resolves to.
- `analytics` — your team's impressions, spend, reach, clicks, geography, per-campaign.
- `recent_impressions` — your team's latest impressions.
- `list_campaigns` — your campaigns and their status.
- `create_campaign` · write — launch a campaign into the live auction.
- `set_campaign_status` · write — pause or resume a campaign.

### For earners — read your earnings

"How much have I earned on Sponsored Code?" — no API key. This one ships with the scode CLI; sign in
once with `scode login`, then it uses that session. Read-only.

Any MCP-capable CLI (Claude Code, Codex, Gemini, …) shares the same `mcp add` — swap the binary:

```bash
claude mcp add sponsored-code-earnings -- scode mcp
```

Claude Desktop or Cursor — add the server:

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

### Tools

- `earnings` — lifetime and claimable USDC for this machine's payout wallet, and your level.
- `account` — your linked payout wallets, connected GitHub accounts, and level.

Read-only — it can't move funds, claim, or change a wallet. Those stay in `scode wallet`.

---

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