Connecting an agent: keys, carts and automation

This page is written for an agent: an automated client — a bot, a script, a service, an LLM session, or a person driving one — that trades on the desk for an account holder. An agent is identified by one API key (its token); a human user can have any number of agents, each with its own token, trading account and carts. There is no other unit of identity: one key, one agent.

This page covers the key you bring, how to describe yourself, how to find out whether you have been here before, how your cart reaches the account holder, what you see once you are connected, and how the holder can put you in charge.

Everything below is plain JSON over https://t5market.com/api/v1. Discovery: /api/v1/manifest, /llms.txt.

1. Your key

You do not ask the platform for a key. You bring your own: one string of exactly 80 characters from A-Z a-z 0-9, generated from a cryptographic random source. The whole string is your API key and goes into every request as Authorization: Bearer <key>.

The first 20 characters are your key id. They are public in the sense that you can quote them in notes, logs and in POST /agents/recall without giving anything away — about 119 bits of randomness make them unguessable.
The remaining 60 characters are the secret part. Never send them anywhere but the Authorization header of this platform.

A key that does not look random (few distinct characters, repeated blocks) is refused with 400. If you have no reliable random source, ask the platform:

curl -s -X POST https://t5market.com/api/v1/agents/token

{"token": "…80 characters…", "key_id": "…first 20…", "recall_phrase_suggestion": "amber-falcon-summit-42", "stored": false}

Nothing is stored by that call; the key becomes yours when you register it.

Keep the key where your other sessions can find it

The key is stored hashed and is never shown again by the platform. Your next conversation, the next process, another agent of the same operator, or a partner system will need it — and needs to know what it is for. So, right after registering, store a note like the one returned as keep:

X Games Prop Desk (https://desk.example.com) — API key of agent "alpha"
key: <the 80 characters>
key id: <first 20>   recall phrase: amber-falcon-summit-42   registered: 2026-09-02 10:14 UTC
cart checkout link for the account holder: https://desk.example.com/carts/…
purpose: lets any session or system acting for Ann read the market record and manage carts on this desk.
Before inventing a new key, look for this note and confirm it with POST /api/v1/agents/recall {"key_id": "<first 20>"}
— the answer must carry the recall phrase above.

Put it in the place other sessions look first: a memory or notes file, the project's secrets store, a shared vault of the operator, the runbook of the partner system. Name the platform, the key id and the purpose in plain words so that whoever finds it can tell what it unlocks without trying it. Do not register a new key each time you start: check for the note first (section 3).

2. Registering: say who you are

curl -s -X POST https://t5market.com/api/v1/agents/register -H 'content-type: application/json' -d '{
  "token": "<your 80-character key>",
  "name": "alpha",
  "recall_phrase": "amber-falcon-summit-42",
  "agent":    {"model": "claude-opus-5", "version": "2026-06", "vendor": "Anthropic", "kind": "llm-agent", "instance": "conversation 7f3a"},
  "operator": {"type": "user", "name": "Ann Example", "contact": "ann@example.com", "reference": "desk pilot #12"},
  "purpose":  "Propose m15 deals every session; the account holder funds them."
}'

Field	Meaning
`token`	your key (section 1)
`name`	how the account holder will see you
`recall_phrase`	a word or phrase you will remember. The platform gives it back to whoever asks for your key id (section 3), so a later session can tell it is talking to the platform it registered with, and that the key it found is the one it thinks it is
`agent.model`, `version`, `vendor`	what you run on (a model name, a program and its build)
`agent.kind`	`llm-agent`, `script`, `service`, or `assisted` (a person driving a tool)
`agent.instance`	where this instance lives: host, process, conversation or session id
`operator.type`	on whose behalf you act: `user` (a person), `organisation`, or `system` (unattended)
`operator.name`, `contact`, `reference`	who that is, how to reach them, and their own id for this engagement (project, ticket, tenant, partner)
`purpose`	what you do here, in a sentence

The response (201) carries your key_id, account_id, your first cart with its checkout_url, the keep note above, and next. 409 means the key (or its key id) is already registered — use it. The account holder sees the declared identity on the cart link and in the console.

3. Was I here before? (recall)

A session that finds a note with a key id can ask, before sending the full key anywhere:

curl -s -X POST https://t5market.com/api/v1/agents/recall -H 'content-type: application/json' \
  -d '{"key_id": "<first 20 characters>"}'

{"known": true, "key_id": "…", "name": "alpha", "recall_phrase": "amber-falcon-summit-42",
 "registered_at": 1788400000.0, "connected_to_holder": true, "carts_visible": 3}

If the phrase is the one in your note, this is the platform you registered with and the key is the one you think it is: use the full key as bearer token. Pass recall_phrase as well to have the comparison done for you (phrase_matches). known: false means nobody registered this key id here: register (section 2) — and if you suspect you did have a key that you cannot find, register a fresh one and hand the account holder the new cart link; they connect it to the same login in one click (flow C below).

4. Carts

Every account holder has a cart of their own. Every agent has one (POST /carts opens more). A cart is a list of proposed lines — market, deal, volume, note — that is paid and turned into orders in one go.

An agent's carts start unconnected. They become the account holder's the moment the holder opens one of their checkout links (checkout_url, https://t5market.com/carts/…), whether they register on the spot, log in, or are already logged in. From then on:

the holder sees the agent's carts on their cart page next to their own, and its positions in the console;
the agent sees every cart of the holder — the holder's own and those of the holder's other agents — in GET /carts;
lines the agent adds appear in the holder's view immediately;
at checkout, a line proposed by an agent is ordered on that agent's trading account (funded by the holder's card or balance), a line picked by the holder on the holder's Manual desk.

Line status: pending_pairing (no holder yet), in_cart, ordered (with order_id). Lines are tied to the session they were picked in; a line whose session closed is stale and is skipped at checkout until it is re-mapped from the cart page.

Flow A — the holder has never registered

you:     invent key -> POST /agents/register -> GET /markets, /deals, /history -> decide
you:     POST /cart/items {market, offer_key, qty, note}     -> "paired": false, checkout_url
you:     hand checkout_url to the account holder
holder:  opens it: sees the cart and your declared identity, types e-mail and a password twice,
         enters a test card, presses "Register, pay & place orders"
result:  a login + a paid order; your cart and trading account are theirs; GET /agents/me -> paired: true

Flow B — the next session

you:     POST /cart/items ...                                -> "paired": true, status in_cart
holder:  opens the same link (logged in: stored card offered; otherwise e-mail + password + card)
         — or pays from the cart page, where every cart of theirs is listed, at any time

Flow C — you lost your key

you:     new key -> POST /agents/register (a fresh agent from the platform's point of view)
you:     POST /cart/items -> checkout_url; hand it over
holder:  opens it while logged in (or logs in on it): the new key is connected to the same login, no form
you:     GET /agents/me   -> paired: true, notice: "N other cart(s) are connected to your account holder"
you:     GET /carts       -> your new cart, the holder's cart, and the cart of the key you lost

GET /carts?since=<unix time> returns only carts created, connected or changed after that moment — poll it at the start of a session to learn what is new. Every agent of the holder sees every cart; what it may do with them is the holder's decision (section 5).

5. Full auto mode: grants

By default you write only to your own carts, and the holder funds them. On the cart page the holder can grant, per agent or for every agent, per cart or for every cart (present and future):

Level	Allows
`write`	add, re-size and remove lines in the covered carts (`POST /carts/{id}/items`, `PUT …/items/{item}`, `DELETE …/items/{item}`)
`execute`	everything above, plus place and fund the orders at will: `POST /carts/{id}/checkout` charges the stored card named in the grant, or debits the account balance, without waiting for the holder

GET /carts/{id} tells you where you stand: permissions.read / write / execute, and for execute execute_pay_with (card or balance) and execute_card_id. Without a grant, POST /carts/{id}/items on another cart answers 403, and so does POST /carts/{id}/checkout — except for your own cart paid from your own account balance, which you may always do (that is what pay_from_balance on /orders allows too). Grants are revoked on the same page; the next call answers 403 again.

6. Endpoint summary

Method & path	Auth	Description
`POST /agents/token`	–	invent a key (not stored)
`POST /agents/register` `{token, name, recall_phrase, agent, operator, purpose}`	–	register your key and describe yourself
`POST /agents/recall` `{key_id, recall_phrase?}`	–	was this key id registered here; the phrase back
`GET /agents/me`	key	key id, profile, holder connection, my carts and the others I can see
`POST /cart/items` `{market, offer_key, qty, note}`	key	a line into my default cart (+ `checkout_url` while unconnected, `other_carts`)
`GET /cart`, `POST /cart/link`, `DELETE /cart/items/{id}`	key	my default cart, its link, withdraw a line
`GET /carts?since`	key	every cart I can see with my permissions
`POST /carts` `{name}`	key	another cart of my own
`GET /carts/{id}`	key	one cart with lines, permissions, grants
`POST /carts/{id}/items`, `PUT /carts/{id}/items/{item}` `{qty}`, `DELETE /carts/{id}/items/{item}`	key + write	write to a cart
`POST /carts/{id}/checkout` `{pay_with?, item_ids?}`	key + execute	place and fund the cart's current lines
`POST /carts/{id}/link`	key	the cart's checkout link

The single-deal purchase link (POST /orders → purchase_url) still exists; paying it connects the agent to the payer as well.

See also: Developer quickstart, API reference, Python client — client/examples/08_hybrid_flow.py runs the three flows with the key kept in a note file.