API Documentation(RESEARCH)

Complete reference for integrating TimeBank.Living into your applications. Track computational work, manage tokens, and access real-time intelligence-backed currency data.

Introduction

The TimeBank.Living API allows you to programmatically interact with the TimeBank ecosystem. All API requests are made to:

Base URL 
https://api.timebank.living/v1

All requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

API Version

The current API version is v1. We recommend explicitly specifying the API version in your requests.

Authentication

TimeBank.Living uses API keys to authenticate requests. You can view and manage your API keys in the Dashboard.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, etc.

Shell 
curl https://api.timebank.living/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"
Security Warning

All API requests must be made over HTTPS. Requests made over plain HTTP will fail. API requests without authentication will return a 401 error.

Rate Limits

The TimeBank.Living API implements rate limiting to ensure fair usage and system stability:

  • Free Tier: 100 requests per hour
  • Pro Tier: 1,000 requests per hour
  • Enterprise: Custom limits

Rate limit information is included in the response headers:

Headers 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1640995200

Account

GET /account

Retrieve your account information including balance, tier, and settings.

Response

JSON 
{
  "id": "acc_1a2b3c4d5e6f",
  "email": "user@example.com",
  "balance": {
    "tb_tokens": 12847,
    "usd_value": 1541.64
  },
  "tier": "pro",
  "multiplier_avg_7d": 2.1,
  "created_at": "2025-01-15T08:30:00Z"
}
PUT /account/settings

Update your account settings and preferences.

Parameters

Parameter Type Required Description
webhook_url string No URL to receive webhook events
auto_convert_threshold integer No Auto-convert TB to USD when balance exceeds this value
biometric_privacy boolean No Enable enhanced biometric data privacy mode

Tokens

GET /tokens/balance

Get your current TB token balance and USD equivalent.

JSON Response 
{
  "tb_tokens": 12847,
  "usd_value": 1541.64,
  "exchange_rate": 0.12,
  "last_updated": "2025-01-15T14:23:45Z"
}
GET /tokens/history

Retrieve your token generation history with optional filtering.

Query Parameters

Parameter Type Required Description
start_date string No ISO 8601 date (e.g., 2025-01-01T00:00:00Z)
end_date string No ISO 8601 date
limit integer No Number of records to return (default: 50, max: 500)
model string No Filter by AI model (gpt-5, claude-opus-sonnet, etc.)
POST /tokens/convert

Convert TB tokens to USD or other supported currencies.

Request Body

JSON 
{
  "amount": 1000,
  "from": "TB",
  "to": "USD",
  "destination": "bank_account_id"
}

Response

200 OK 
{
  "transaction_id": "txn_9z8y7x6w5v4u",
  "amount_converted": 1000,
  "from_currency": "TB",
  "to_currency": "USD",
  "exchange_rate": 0.12,
  "total_received": 120.00,
  "status": "completed",
  "completed_at": "2025-01-15T14:30:00Z"
}

Compute Tracking

Requires API Key
POST /compute/track

Submit computational work for token generation. This endpoint automatically calculates weighted token value based on the model and task complexity.

Request Body

Parameter Type Required Description
model string Yes AI model used (gpt-5, claude-opus, claude-sonnet, gpt-3.5, local)
tokens_used integer Yes Number of tokens consumed
task_type string Yes Type of task (code, analysis, creative, simple, complex)
duration_seconds integer No Time taken for computation
coherence_score float No Biometric coherence score (0.5 - 3.0)

Example Request

cURL 
curl -X POST https://api.timebank.living/v1/compute/track \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus",
    "tokens_used": 8450,
    "task_type": "code",
    "duration_seconds": 45,
    "coherence_score": 2.8
  }'

Response

201 Created 
{
  "compute_id": "cmp_abcd1234",
  "tb_tokens_generated": 27.1,
  "model_weight": 3.2,
  "coherence_multiplier": 2.8,
  "base_tokens": 8450,
  "timestamp": "2025-01-15T14:35:22Z"
}
GET /compute/stats

Get aggregated statistics about your computational activity.

{
  "total_tb_generated": 12847,
  "total_compute_sessions": 1453,
  "models_used": {
    "claude-opus": 154,
    "gpt-5": 120,
    "claude-sonnet": 51,
    "local": 17
  },
  "avg_coherence_7d": 2.1,
  "most_productive_hour": 14,
  "tokens_per_day_avg": 342
}

Biometric Data

Requires API Key
Privacy First

Only coherence scores are transmitted. Raw biometric data never leaves your device.

POST /biometric/coherence

Submit coherence score data from biometric devices.

Request Body

{
  "coherence_score": 0.87,
  "device_type": "apple_watch",
  "hrv_coherence": 0.85,
  "timestamp": "2025-01-15T14:40:00Z"
}
GET /biometric/multiplier

Get your current coherence-based multiplier.

{
  "current_multiplier": 2.8,
  "coherence_score": 0.87,
  "status": "high_coherence",
  "last_updated": "2025-01-15T14:40:00Z"
}

Transactions

GET /transactions

List all transactions including token generations and conversions.

Query Parameters

Parameter Type Description
type string Filter by type (generation, conversion, transfer)
limit integer Number of records (default: 50)

Webhooks

TimeBank.Living can send webhook events to notify your application when certain events occur.

Supported Events

  • token.generated - New tokens created from compute work
  • token.converted - Tokens converted to fiat currency
  • balance.threshold - Balance crosses configured threshold
  • coherence.high - Coherence score exceeds 0.85
  • coherence.low - Coherence score drops below 0.60

Webhook Payload Example

{
  "event": "token.generated",
  "timestamp": "2025-01-15T14:45:00Z",
  "data": {
    "compute_id": "cmp_xyz123",
    "tb_tokens": 27.1,
    "model": "claude-opus",
    "coherence_multiplier": 2.8
  }
}

Error Codes

TimeBank.Living uses conventional HTTP response codes to indicate success or failure.

Code Description
200 OK - Request succeeded
201 Created - Resource created successfully
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid API key
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Something went wrong

Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "The 'model' parameter is required",
    "param": "model"
  }
}

SDKs & Libraries

Official SDKs for popular programming languages:

Python

pip install timebank

Node.js

npm install timebank

Ruby

gem install timebank

Quick Start - Python

Python 
import timebank

# Initialize client
tb = timebank.Client(api_key='YOUR_API_KEY')

# Track compute work
result = tb.compute.track(
    model='claude-opus',
    tokens_used=8450,
    task_type='code',
    coherence_score=2.8
)

print(f"Generated {result.tb_tokens} TB tokens")

# Check balance
balance = tb.tokens.balance()
print(f"Balance: {balance.tb_tokens} TB (${balance.usd_value})")