TTokeo

Tokeo API Docs

One Tokeo key for stablecoin-funded AI access. Use OpenAI-compatible chat requests while Tokeo keeps provider keys private, reserves balance, settles usage, and exposes model readiness.

01

Create account

Use email, MetaMask, OKX, Binance Wallet, or Bitget Wallet from the console.

02

Fund balance

USDC / USDT only. 10% platform fee. Example: 11 USDT becomes $10.00 balance after verification.

03

Create key

Generate a `tokeo_` key. Store it once; Tokeo never exposes upstream provider keys to users.

04

Call models

Call `/v1/chat/completions`; check `/api/balance` and `/api/usage` for billing state.

Quickstart

curl /v1/chat/completions \
  -H "Authorization: Bearer tokeo_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-haiku-4-5",
    "messages": [{"role": "user", "content": "Reply exactly: OK"}],
    "max_tokens": 64
  }'

Billing Rule

No credit before provider verification. Tokeo creates a reservation before model calls, releases it on upstream failure, and writes a ledger debit only after usage settles. If balance is low, expect `insufficient_balance` with the required reservation amount plus `X-Tokeo-*` monitor headers.

Request limits/api/setup request_limits
Max output tokens4096 default
Max prompt chars120000 default

Oversized `/v1/chat/completions`, `/v1/messages`, and x402 requests fail with `request_limit_exceeded` before reserve, payment challenge, or upstream execution.

Endpoints

GET
/v1/models
List model ids and `provider_ready` flags.
POST
/v1/chat/completions
OpenAI-compatible chat request with Tokeo billing.
POST
/v1/messages
Claude-style request shape with the same Tokeo balance monitor headers.
GET
/api/balance
Requires `Authorization: Bearer tokeo_...`.
GET
/api/usage
Recent usage events, token counts, cost, and status.
GET
/api/x402/supported
Supported x402 catalog and payment requirements.

Monitor Headers

Header
X-Tokeo-Cost-USD
Actual settled request cost after a successful model call.
Header
X-Tokeo-Balance-After-USD
Derived balance after the request or failed reservation check.
Header
X-Tokeo-Low-Balance
`true` when the account is at or below the configured threshold.
Header
X-Tokeo-Recommended-Action
`create_deposit` when the caller should top up with USDC/USDT.

Errors

400
request_limit_exceeded / invalid_max_tokens
Reduce `max_tokens` or prompt size before retrying.
401
missing_api_key / invalid_api_key
Send a Tokeo key, not an upstream provider key.
402
insufficient_balance
Top up before the reservation can be created.
503
provider_not_configured
Provider is unavailable or intentionally disabled.
502
upstream_exception
Upstream provider failed; reservation is released.

Models

Anthropic / Claude
  • claude-haiku-4-5
  • claude-sonnet-4-6
  • Live for MVP testing
Google / Gemini
  • gemini-2.5-flash
  • gemini-2.5-pro
  • Live for MVP testing
OpenAI / ChatGPT
  • gpt-4.1-mini
  • gpt-4.1
  • Unavailable until upstream funding is ready

x402 pay-per-request

x402 pay-per-request routes are present for API users and agents. Challenge/probe behavior can be tested now, but settlement remains disabled until facilitator approval, production pay-to wallet, and risk policy are ready.

Payment Limits

USDC / USDT only. Wrong asset, wrong network, underpayment, duplicate tx, or unrecognized deposits must go to manual review. Automatic payment provider verification is tracked in the roadmap and should not block docs, console, or API work.

No credit before provider verification. This is the accounting invariant for every deposit path.