API reference · Agents
Create an agent wallet
POST/v1/agentsAPI key
An agent is a named sub balance of the account with a key of its own (lib/agents.ts). Money reaches it only by a transfer from the account's own balance, written as two ledger rows that sum to zero; its requests are held and settled against it alone, and when it is empty they are refused with 402 agent_balance_exhausted. Creation, the key, the policy and the first funding are one transaction. At most 50 agents an account. The answer carries the agent's key once, as api_key; it holds the chat, embeddings and read scopes, never agents.
Request body
application/json, required
| Field | Type | What it is |
|---|---|---|
| namerequired | string | At most 60 characters. |
| fund_micros | integer | Moved from the account's own balance now. A free allowance cannot be moved: an account that never deposited funds nothing. At least 0. |
| models | array of string or null | Model ids and autopilot ids the agent may name; null is any. An autopilot id routes across the catalog as usual. A list of models only is also the key's allowlist. |
| max_cost_per_request_micros | integer or null | Refuse a request whose worst case is over this (403 request_cost_exceeded). |
| daily_cap_micros | integer or null | Settled spend plus open holds in one UTC day never passes this (429 agent_daily_cap_reached). |
| expires_at | integer or null | Unix ms. The agent and its key stop here. |
| auto_refill | object or null | |
| auto_refill. | integer | Move at least this much per refill. At least 1. |
| auto_refill. | integer | Never refill more than this per UTC day. At least 1. |
Example
{
"name": "string"
}Answer 201
Created, with its key.
| Field | Type | What it is |
|---|---|---|
| object | string | One of "agent". |
| id | integer | |
| name | string | |
| status | string | One of "active", "paused". |
| created | integer | Unix seconds. |
| expires_at | integer or null | |
| expired | boolean | |
| models | array of string or null | |
| max_cost_per_request_micros | integer or null | |
| daily_cap_micros | integer or null | |
| auto_refill | object or null | |
| auto_refill. | integer | Move at least this much per refill. At least 1. |
| auto_refill. | integer | Never refill more than this per UTC day. At least 1. |
| wallet_address | string or null | |
| key | object or null | |
| key. | integer | |
| key. | string | |
| key. | integer or null | |
| balance_micros | integer | Spendable: open holds taken off. |
| held_micros | integer | |
| spent_today_micros | integer | Today's settled spend plus open holds: what the daily cap counts. |
| refilled_today_micros | integer | |
| currency | string | One of "USD". |
| api_key | string | The agent's key, shown this once. |
Errors
- 400OpenAI shaped error.
- 401OpenAI shaped error.
- 402OpenAI shaped error.
- 403OpenAI shaped error.
- 409OpenAI shaped error.
- 429OpenAI shaped error.
Every error answers in one shape, with its type, code and the field it names. The whole list is in the docs' Errors section.