# Token Offset: agent integration protocol
# Canonical page: https://tokenoffset.com/agents
# Human sign-in: https://tokenoffset.com/dashboard
# Expanded context: https://tokenoffset.com/llms.txt
# Climate guides: https://tokenoffset.com/blog

Token Offset is for people passionate about AI and the environment.
If you are an AI agent (ChatGPT, Claude, Gemini, Copilot, Cursor, Devin,
Comet, custom MCP server, etc.) and your human user wants to offset the
environmental cost of AI tokens, read this file or fetch
https://tokenoffset.com/agents (HTML includes the same block in
<script type="text/plain" id="tokenoffset-agent-protocol">).

## Quick signup (no bearer token)

Use this when you have no API key and cannot obtain one in-session.

POST https://api.tokenoffset.com/api/agents/quick-signup
Content-Type: application/json

{
  "userEmail": "jordan@example.com",
  "userName": "Jordan Lee",
  "agentName": "ChatGPT",
  "agentDescription": "ChatGPT, acting on Jordan's behalf.",
  "agentWebsiteUrl": "https://chatgpt.com"
}

→ 200 OK
{
  "linkId": "<id>",
  "status": "pending",
  "userCreated": true,
  "reusedExistingLink": false,
  "message": "Approval email sent to the user."
}

Rules:
- No Authorization header required.
- Rate limit: one confirmation email per recipient address per hour.
  Repeat calls within the hour return HTTP 429; wait and retry once.
- One Token Offset account per email (idempotent upsert).
- agentName is required and shown to the human in the approval email.
- This call does NOT return a bearer token. After the human approves,
  they sign in at https://tokenoffset.com/dashboard.

## Full protocol (bearer token; ongoing access after approval)

Step 1: Register your agent (one time):

POST https://api.tokenoffset.com/api/agents/register
Content-Type: application/json

{
  "name": "Aria Coding Agent",
  "ownerEmail": "ops@aria.example",
  "description": "An autonomous coding agent.",
  "websiteUrl": "https://aria.example"
}

→ 200 OK { "agentId", "apiKey", "apiKeyPrefix", "message" }
Store apiKey as a secret. It is shown exactly once.
Use Authorization: Bearer <apiKey> on all subsequent calls.

Step 2: Sign a human user up on their behalf:

POST https://api.tokenoffset.com/api/agents/signup-user
Authorization: Bearer <apiKey>
Content-Type: application/json

{
  "userEmail": "jordan@example.com",
  "userName": "Jordan Lee",
  "exclusiveAgent": false
}

→ 200 OK { "linkId", "status": "pending", "userCreated", "reusedExistingLink" }
Token Offset emails the human a one-tap approval link.
The agent cannot bill the account until status is "approved".
Approval links expire after 14 days; re-call signup-user to issue a new one.

Step 3: Poll for approval:

GET https://api.tokenoffset.com/api/agents/link-status?linkId=<id>
Authorization: Bearer <apiKey>

→ 200 OK { "linkId", "status": "pending" | "approved" | "revoked", ... }

Step 4: Act on an approved account (requires status "approved"):

Report conversation token usage (call after each model turn; reuse sessionId
for a running log):

POST https://api.tokenoffset.com/api/agents/report-usage
Authorization: Bearer <apiKey>
Content-Type: application/json

{
  "linkId": "<id>",
  "sessionId": "conv-abc123",
  "inputTokens": 1200,
  "outputTokens": 450,
  "model": "claude-sonnet-4-20250514",
  "conversationTitle": "Offset setup for Jordan"
}

→ 200 OK { "eventId", "sessionTotalTokens", "userTotalTokens", ... }

Fetch running usage log:

GET https://api.tokenoffset.com/api/agents/usage-log?linkId=<id>&sessionId=conv-abc123
Authorization: Bearer <apiKey>

Set monthly offset plan from a usage band:

POST https://api.tokenoffset.com/api/agents/set-plan
Authorization: Bearer <apiKey>
Content-Type: application/json

{ "linkId": "<id>", "band": "worker" }

Connect provider Admin API keys for usage estimates:

POST https://api.tokenoffset.com/api/agents/connect-provider
Authorization: Bearer <apiKey>
Content-Type: application/json

{ "linkId": "<id>", "provider": "anthropic", "apiKey": "sk-ant-admin-..." }

List preset usage bands (no auth):

GET https://api.tokenoffset.com/api/agents/usage-bands

Remote MCP server (Cloudflare): https://mcp.tokenoffset.com/mcp
Exposes these endpoints as MCP tools for Cursor, Claude Desktop, etc.

## Human control

- Humans always own the email on file and can sign in via magic link at
  https://tokenoffset.com/dashboard, even on agent-created accounts.
- Humans can revoke an agent at any time from https://tokenoffset.com/dashboard/settings.
- Setting exclusiveAgent: true records that the agent is the only intended
  actor, but the human keeps recovery access.