TopoLabs
[Getting started]

Authentication

Every request is authenticated with an API key sent as a bearer token. Keys belong to a team wallet and can be scoped by model, spend, region and IP.

API keys

Send your key in the Authorization header on every request. Keys are created in the dashboard and shown exactly once.

cURL
curl https://api.topolabs.ai/v1/models \  -H "Authorization: Bearer $TOPO_API_KEY"
PrefixEnvironmentSettlesUse it for
tp_live_ProductionOn-chainReal traffic, billed per token from the team wallet.
tp_test_SandboxNeverCI and local tests. Returns deterministic outputs at no cost.
tp_agent_Agent walletOn-chainKeys bound to one agent's balance and limits.

Key scopes

Every key carries its own limits. A request outside a key's scope fails with 403 key_scope_violation before any tokens are served.

  • spend_limitstring (USDT)

    Maximum spend per calendar month. Requests past it return 402 spend_limit_reached.

  • modelsstring[]

    Allow list of model IDs this key may call.

    Default: every model

  • regionsstring[]

    Pin traffic to regions such as eu-west-2. Max and Enterprise plans.

  • ip_allowliststring[] (CIDR)

    Only accept requests from these address ranges.

  • expires_atstring (ISO 8601)

    The key stops working at this time.

Rotate a key

Rotation issues a replacement and keeps the old key valid for a grace period, so you can deploy without downtime. Revoked keys fail with 401 invalid_api_key within 10 seconds in every region.

cURL
curl -X POST https://api.topolabs.ai/v1/keys/key_prod_agents/rotate \  -H "Authorization: Bearer $TOPO_ADMIN_KEY" \  -H "Content-Type: application/json" \  -d '{ "grace_period": "24h" }'

Wallet signatures

Agents that hold their own wallet can skip API keys and sign each request instead. See Agent wallets for the header format.