← All docs

Sanction Quickstart — first call in under 5 minutes

Create a wallet, issue an agent key, route an LLM call through the gateway so it's metered, and authorize a spend before it happens. Base URL: https://getsanction.com/api/v1. Full API: OpenAPI spec.

0. Hosted or local?

Every step below runs against the hosted API — nothing to install. Cloned the repo and want it local instead? The API routes need Postgres:

cp .env.example .env.local           # fill DATABASE_URL (any Postgres), the two secrets
npx prisma migrate deploy            # create the schema
npm run dev                          # then use http://localhost:3000/api/v1 below

npm run check (tests, typecheck, lint) needs no database — only the running API does. Two shortcuts worth knowing either way:

  • bash examples/setup.sh does steps 1–3 in one command — wallet, agent, a demo policy tuned so $8 approves / $45 escalates — and prints the exports. Point it locally with SANCTION_API_URL=http://localhost:3000/api/v1.
  • Add ?simulate=true to any /authorize call for a full dry run: the real engine decides, nothing persists, no budget moves.

1. Create a wallet

A wallet is your master account. You get back a management key (sk_…) — save it, it's shown once.

curl -s -X POST https://getsanction.com/api/v1/wallets \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-org",
    "owner_email": "you@example.com"
  }' | jq .

Response (abbreviated):

{ "id": "wal_abc123", "management_key": "sk_...", "warning": "Store this key now." }

Before connecting long-lived clients: for a wallet created here, the first verified owner-email claim (email magic link or verified social sign-in) revokes pre-claim agent keys and deactivates those agents. The original management key also stops working. Claim the wallet through sign-in first, then use the new management key shown by the magic link, or reset it in Team after social sign-in.

If you already issued agent keys, create new agents or rotate their keys and reactivate them in Agents, then update your clients. Later magic links for the verified owner rotate only the management key; they preserve agent keys.

2. Register an agent & get a key

Use your sk_ management key to provision an agent. You get back an agent key (pxy_…) — also shown once.

curl -s -X POST https://getsanction.com/api/v1/agents \
  -H "Content-Type: application/json" \
  -H "x-mgmt-key: sk_YOUR_MGMT_KEY" \
  -d '{
    "wallet_id": "wal_abc123",
    "name": "my-first-agent"
  }' | jq .

Response:

{ "id": "agt_xyz", "api_key": "pxy_...", "warning": "Store this key now." }

3. Route an LLM call through the gateway

Swap your provider's base URL for the Sanction gateway. Pass your agent key in x-sanction-key; your own provider key still rides along and is forwarded upstream.

# Claude via Sanction gateway
curl -s -X POST https://getsanction.com/api/gateway/anthropic/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-sanction-key: pxy_YOUR_AGENT_KEY" \
  -H "x-api-key: YOUR_ANTHROPIC_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 256,
    "messages": [{"role":"user","content":"Say hello"}]
  }'

The gateway meters tokens and cost automatically — they show up in your dashboard. When a daily token budget is exhausted, the gateway returns 402 before the call reaches the provider.

4. Authorize a spend action

Before any financial action, ask Sanction for permission.

curl -s -X POST https://getsanction.com/api/v1/authorize \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxy_YOUR_AGENT_KEY" \
  -d '{
    "action": "purchase",
    "amount_usd": 29.99,
    "merchant": "GitHub",
    "category": "software",
    "description": "Copilot subscription"
  }' | jq .

Response:

{
  "authorized": true,
  "status": "approved",
  "request_id": "req_...",
  "agent": "agt_xyz",
  "amount_usd": 29.99,
  "merchant": "GitHub"
}

Handle every status: approved (proceed), denied (stop), escalated (wait for a human).

5. Log token usage (optional — the gateway does this automatically)

If you call an LLM directly instead of through the gateway, log usage manually:

curl -s -X POST https://getsanction.com/api/v1/tokens \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxy_YOUR_AGENT_KEY" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "tokens_in": 150,
    "tokens_out": 42,
    "cost_usd": 0.0012,
    "task": "greeting"
  }'

Next steps

  • Set a spend policy: PATCH /wallets/policy — daily budgets, auto-approve thresholds, escalation rules.
  • Carry the wallet over MCP: paste https://getsanction.com/mcp with x-api-key, or npx sanction-mcp. Discovery: /.well-known/wallet-card.json. Guide: The agent wallet.
  • Mandate: POST /exec mints a 15-minute JWT; a counterparty checks it at POST /mandate/verify (no API key); POST /credentials/inject uses it.
  • Dashboard: GET /wallets/stats?wallet_id=<id> or visit getsanction.com.
  • Framework guides: Vercel AI SDK · LangChain · CrewAI
Start free →