# Token Bank - AI Agent Integration Guide

## Overview
Token Bank is a next-generation financial infrastructure platform for Token sharing.
AI Agents can borrow shared Tokens, use them for LLM inference, and return them later
with a small premium via blockchain-backed agreements.

## Domains
- Primary: https://wordsworth.dpdns.org
- Secondary: https://token-bank.cloud

## Quick Start (3 Steps)

### Step 1: Register Your Agent
```bash
curl -X POST https://wordsworth.dpdns.org/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-ai-agent",
    "email": "agent@example.com",
    "wallet_address": "0xYourWalletAddress"
  }'
```
Response includes: `user_id`, `api_key` (save it!), `tenant_id`.

### Step 2: Use the API (OpenAI Compatible)
```bash
curl https://wordsworth.dpdns.org/v1/chat/completions \
  -H "Authorization: Bearer sk-agent-xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'
```

### Step 3: Return Tokens
After the contract period (default 180 days), return tokens according to the token policy.
Formula: `actual_usage x (1 + return_coefficient) x model_coefficient`

## API Endpoints

### Public (No Auth Required)
- `GET /api/v1/token-policy/public` - Token return policy, model coefficients, example
- `GET /health` - Health check (returns status, model_count, uptime_secs, components)
- `GET /api/v1/settings/public` - Platform public settings

### Agent Registration
- `POST /api/v1/agents/register` - One-click register (returns API key)
- `PUT /api/v1/agents/{user_id}/wallet` - Bind wallet address
- `POST /api/v1/agents/{user_id}/wallet/verify` - Verify wallet ownership
- `GET /api/v1/agents/{user_id}/credit` - Query on-chain credit status

### OpenAI-Compatible API (Requires Bearer Token)
- `POST /v1/chat/completions` - Chat completions
- `GET /v1/models` - List available models
- `GET /v1/models/{model}` - Retrieve model details

### User and Billing
- `GET /api/v1/me` - Current user info
- `GET /api/v1/usage` - Usage records
- `GET /api/v1/usage/stats` - Usage statistics
- `POST /api/v1/keys` - Create API key
- `GET /api/v1/keys` - List API keys
- `DELETE /api/v1/keys/{id}` - Delete API key

### Authentication
- `POST /api/v1/auth/login` - Login (returns access token)
- `POST /api/v1/auth/refresh-token` - Refresh access token

## Token Return Policy
- Formula: `actual_usage x (1 + return_coefficient) x model_coefficient`
- Default return period: 180 days
- Default return coefficient: 0.03%
- Model coefficients vary by model (see /api/v1/token-policy/public)
- Agreement recorded on-chain via LLMSharedTokenPool contract

## Supported Models
- OpenAI: GPT-4o, GPT-4o-mini, GPT-5
- Anthropic: Claude Sonnet 4, Claude Haiku 3.5
- Google: Gemini 2.5 Pro
- DeepSeek: DeepSeek Chat
- Ollama: Local models (node: prefix)

## Authentication
All API requests (except public endpoints) require:
  Authorization: Bearer <api_key_or_access_token>

## Rate Limiting

### Defaults
| Dimension           | Default Limit | Window         |
|---------------------|---------------|----------------|
| RPM (Requests/Min)  | 60            | 60s sliding    |
| TPM (Tokens/Min)    | 100,000       | 60s sliding    |

### Scope
- Rate limits are enforced per (tenant_id, user_id, api_key_id) triple.
- API Key-authenticated requests use your key's limits.
- Agent registration uses a separate per-IP limit to prevent abuse.

### Tenant Overrides
Tenants may have custom RPM/TPM limits configured in the platform.
The server loads tenant-specific limits from the database on every request.
If no tenant config is found, the defaults above apply.

### Handling 429 (Too Many Requests)
When a request is rejected, the response body contains:
{
  "error": {
    "message": "Rate limit exceeded. Please try again later.",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded"
  }
}
Respect the Retry-After response header and back off before retrying.
Implement exponential backoff (e.g., 1s, 2s, 4s) to avoid thundering-herd retries.

### Recommended Agent Behavior
- Check your usage before sending large batches.
- If you receive a 429, wait for the value in Retry-After and retry.
- Cache the token-policy response (GET /api/v1/token-policy/public) to avoid repeated calls.

## Audit Logging
Every request is logged server-side with structured fields:
- request_id  -- unique per-request identifier (from X-Request-ID header or generated)
- method      -- HTTP method (GET, POST, etc.)
- uri         -- full request URI
- status      -- HTTP response status code
- duration_ms -- request processing time in milliseconds

Agents can correlate logs by sending a consistent X-Request-ID header on related requests.