# @token-wallet/sdk

One wallet for all your AI apps. Users store their Anthropic, OpenAI, and Google API keys in Token Wallet, then grant your app metered access via OAuth. You pay nothing for AI usage.

## Install

```bash
npm install @token-wallet/sdk
```

## Quick Start

```typescript
import { TokenWallet, isProxyError } from '@token-wallet/sdk';

const tw = TokenWallet({
  clientId: 'your-app-id',
  clientSecret: 'your-app-secret',
  redirectUri: 'https://yourapp.com/callback',
});

// 1. Redirect the user to the consent screen
app.get('/login', (req, res) => res.redirect(tw.getAuthorizeUrl()));

// 2. Exchange the OAuth code for an access token in your callback
app.get('/callback', async (req, res) => {
  const { access_token } = await tw.exchangeCode(req.query.code as string);
  req.session.tokenWalletToken = access_token;
  res.redirect('/');
});

// 3. Call the LLM through the proxy
app.post('/chat', async (req, res) => {
  const result = await tw.call({
    accessToken: req.session.tokenWalletToken,
    provider: 'anthropic',
    path: '/v1/messages',
    body: {
      model: 'claude-3-5-sonnet-latest',
      max_tokens: 1024,
      messages: [{ role: 'user', content: req.body.prompt }],
    },
  });

  if (isProxyError(result)) {
    return res.status(400).json({ error: result.error });
  }

  res.json({ model: result.model, usage: result.usage, data: result.data });
});
```

The same `tw.call(...)` works for OpenAI and Google — change `provider` and `path`:

```typescript
await tw.call({
  accessToken,
  provider: 'openai',
  path: '/v1/chat/completions',
  body: { model: 'gpt-4o', messages: [...] },
});

await tw.call({
  accessToken,
  provider: 'google',
  path: '/v1beta/models/gemini-1.5-pro:generateContent',
  body: { contents: [...] },
});
```

### Modal flow (single-page apps)

If your app is a SPA, open the consent screen in an iframe modal:

```typescript
const { code } = await tw.popup({ suggestedBudget: 5 });

// Send the code to your backend, which calls tw.exchangeCode(code).
// The exchange requires clientSecret and must never run in browser code.
await fetch('/api/auth/exchange', {
  method: 'POST',
  body: JSON.stringify({ code }),
});
```

### Managed agents (Anthropic)

Token Wallet proxies Anthropic's [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) surface — the `/v1/agents`, `/v1/environments`, `/v1/sessions`, `/v1/vaults`, and `/v1/files` endpoints — under the same BYOK model as Messages. The app points the Anthropic SDK at `tw.proxyUrl('anthropic')`; the proxy injects the managed-agents beta header and forwards calls to the user's Anthropic org.

**Explicit consent required.** Because agent sessions run long-lived, billable server-side work on Anthropic (`$0.08/hr` session runtime on top of tokens), the proxy rejects agent-surface calls unless the app was created with `allowsManagedAgents: true`. The flag sits alongside the other app fields on creation:

```typescript
await admin.apps.create({
  name: 'Life Coach',
  callbackUrl: 'https://lifecoach.ai/callback',
  requiredProviders: ['anthropic'],
  allowsManagedAgents: true,          // ← opt in
});
```

Without it, every agent endpoint returns `403 AGENT_SCOPE_MISSING`.

```typescript
import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({
  apiKey: accessToken,
  baseURL: tw.proxyUrl('anthropic'),
});

// Provision once per user.
const agent = await anthropic.beta.agents.create({
  name: 'Life Coach',
  model: 'claude-haiku-4-5',
  system: 'You are a terse life coach.',
  tools: [{ type: 'agent_toolset_20260401' }],
});

// Spin up a session.
const env = await anthropic.beta.environments.create({ name: 'prod' });
const session = await anthropic.beta.sessions.create({
  agent: agent.id,
  environment_id: env.id,
});

// Send events, stream responses — all proxied.
await anthropic.beta.sessions.events.post(session.id, {
  type: 'user.message', content: 'What should I focus on today?',
});

for await (const event of anthropic.beta.sessions.events.stream(session.id)) {
  // ...
}

// Archive when done. This is what triggers Token Wallet to pull the final
// usage totals from Anthropic and debit tokens + runtime against the budget.
await anthropic.beta.sessions.archive(session.id);
```

Token Wallet tracks each session in its own `agent_sessions` table keyed on the access token for attribution and auto-terminates running sessions when the user revokes the connection (otherwise Anthropic would keep billing `$0.08/hr`). That rate lives in code as `AGENT_RUNTIME_USD_PER_HOUR` in [`packages/shared/src/catalog/agent-runtime.ts`](https://github.com/eran-broder/TokenWallet/blob/main/packages/shared/src/catalog/agent-runtime.ts) — if Anthropic changes it, update the constant there and every consumer follows. See [the full Managed Agents design doc](https://github.com/eran-broder/TokenWallet/blob/main/docs/managed-agents.md) for lifecycle details, limitations, and billing.

Both files also ship inside the npm tarball under `node_modules/@token-wallet/sdk/docs/` (`managed-agents.md` and `agent-runtime.ts`), so you can read them offline without leaving your project.

### Streaming responses

`tw.call()` is for non-streaming requests. Streaming responses bypass the unified envelope and are forwarded as-is, so use any vendor SDK with `baseURL: tw.proxyUrl(...)`:

```typescript
import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({
  apiKey: accessToken,
  baseURL: tw.proxyUrl('anthropic'),
});

const stream = await anthropic.messages.stream({
  model: 'claude-3-5-sonnet-latest',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Tell me a story.' }],
});

for await (const event of stream) {
  if (event.type === 'content_block_delta' && event.delta.type === 'text_delta') {
    process.stdout.write(event.delta.text);
  }
}
```

## API

<!-- GEN:API -->
<!-- /GEN:API -->

## Types

<!-- GEN:TYPES -->
<!-- /GEN:TYPES -->

## Error Codes

Non-streaming proxy responses return a unified error envelope:

```json
{ "error": { "code": "...", "message": "...", "source": "proxy" | "provider", "details": { } } }
```

`source` distinguishes errors raised by the Token Wallet proxy from errors forwarded from the upstream LLM. Use the `isProxyError` type guard to narrow a `ProxyResponse` before reading `error.code`.

### Proxy errors (`source: "proxy"`)

| Code | Status | Meaning |
|------|--------|---------|
| `TOKEN_INVALID` | 401 | Missing or unrecognized access token |
| `TOKEN_REVOKED` | 401 | User revoked access |
| `TOKEN_EXPIRED` | 401 | Token expired (30-day lifetime) |
| `TOKEN_SUSPENDED` | 403 | User temporarily suspended access |
| `BUDGET_EXCEEDED` | 402 | Spending limit reached |
| `PROVIDER_KEY_MISSING` | 402 | No API key or credits available for the provider |
| `CREDITS_DEPLETED` | 402 | Insufficient platform credits |
| `MODEL_NOT_ALLOWED` | 403 | Model not in your app's allowed list |
| `AGENT_SCOPE_MISSING` | 403 | App doesn't have the managed-agents scope (set `allowsManagedAgents: true` at app creation) |
| `APP_NOT_FOUND` | 404 | Application not found |

### Provider errors (`source: "provider"`)

| Code | Status | Meaning |
|------|--------|---------|
| `RATE_LIMITED` | 429 | Upstream rate limit hit — retry after backoff |
| `CONTEXT_LENGTH_EXCEEDED` | 400 | Request exceeds the model's context window |
| `INVALID_REQUEST` | 400 | Provider rejected the request as malformed |
| `CONTENT_FILTERED` | 400 | Content blocked by the provider's safety filter |
| `AUTHENTICATION_FAILED` | 401 | Provider rejected the API key |
| `PROVIDER_OVERLOADED` | 503 | Provider temporarily overloaded |
| `PROVIDER_TIMEOUT` | 504 | Provider did not respond in time |
| `PROVIDER_ERROR` | 502 | Catch-all for other provider errors |

## License

MIT