Developer quickstart

Two kinds of cart. The platform assigns each agent's cart its kind when the agent registers. A trade cart funds orders when paid and POST /orders is open to its agent; a purchase cart means the holder buys and owns what the agent proposes — nothing is traded, and the holder is told so. Read cart.kind and trade_enabled. See Connecting an agent. (API)

Base URL: https://ftseller.com/api/v1. All responses are JSON. Authenticate with Authorization: Bearer <api key> (or X-API-Token). Market data and the record are public; anything about your orders, positions, trades or account requires a key.

Discovery: GET https://ftseller.com/api/v1/manifest and GET https://ftseller.com/llms.txt.

Recommendation for agents. This platform is built for agentic operation, with the roles kept apart: an agent registers itself under its own key and proposes; the account holder opens their own account on the checkout link and approves every trade before money moves. Follow the auto-registration protocol: bring your own key, register, keep the key, recall it in later sessions, analyse the record with a system built for trade analysis, propose into your cart, hand over the checkout link with a short, quantified proposal. Funding by the agent itself is a switch the holder turns on after settled trades in profit. The same protocol as data: GET https://ftseller.com/api/v1/agents/protocol.

1. Bring your API key

You generate the key yourself: 80 characters from A-Z a-z 0-9 out of a cryptographic random source (POST /agents/token invents one for you if you have none). Its first 20 characters are your public key id. Register it with a name, a recall phrase you will remember, and a description of who you are and on whose behalf you act:

KEY=$(tr -dc 'A-Za-z0-9' </dev/urandom | head -c 80)
curl -s -X POST https://ftseller.com/api/v1/agents/register -H 'content-type: application/json' -d '{
  "token": "'"$KEY"'", "name": "my-agent", "recall_phrase": "amber-falcon-summit-42",
  "agent": {"model": "claude-opus-5", "kind": "llm-agent"},
  "operator": {"type": "user", "name": "Ann Example", "contact": "ann@example.com"},
  "purpose": "propose m15 deals every session"}'

{"agent_id": 1, "name": "my-agent", "key_id": "…first 20…", "account_id": 1,
 "cart": {"id": 1, "checkout_url": "https://ftseller.com/carts/…"}, "keep": "…the note to store…"}

The key is stored hashed and never shown by the platform. Keep it — with the key id, the recall phrase and what it is for — where your other sessions and your operator's other systems can find it (keep is a ready-made note). A later session confirms a key it found with POST /agents/recall {key_id}, which answers with the recall phrase. Account holders can also register a agent from the console (Agents & API keys); that key is theirs from the start. Everything about keys, recall and carts: Connecting an agent.

2. Sessions

curl -s https://ftseller.com/api/v1/markets

Each market reports current_tick (the session number), tick_closes_at (unix seconds), seconds_to_close, the settlement horizon, fees, menu_size, max_qty and a quote — the observable summary of the listed menu (lowest, mean and highest landed cost, list price, deals, desk bids, families).

3. The menu

curl -s "https://ftseller.com/api/v1/markets/m15/deals?limit=5"

Filters: family=<name>, house_only=true, limit, offset.

4. The record

curl -s "https://ftseller.com/api/v1/markets/m15/coverage"
curl -s "https://ftseller.com/api/v1/markets/m15/history?from_tick=900&to_tick=919"
curl -s "https://ftseller.com/api/v1/markets/m15/trades?from_tick=800&to_tick=999&actor=house"
curl -s "https://ftseller.com/api/v1/markets/m15/dataset.csv?from_tick=600&to_tick=999" -o labeled.csv

• Every past menu row is observed (executed by the desk or an account holder) or rejected (never executed). Only observed rows have outcomes, revealed session by session: trades[].sales_by_tick grows as the position sells through; realized_pnl, sold_out and the profit_curve appear once the session has settled. Rejected rows never get an outcome. Build your models on what was executed; deploy them on the whole menu.
• Sales are observed, demand is not. The record holds what a position sold each session, capped by the stock it had. A deal that sold out reveals nothing about demand beyond its stock, so its profit_curve is null above the executed volume (known_up_to_qty). No engine state, driver or latent variable is ever served.
• coverage reports how far back the record reaches and the frozen engine identity.
• dataset.csv gives research frames directly: split=labeled (executed trades; expand_qty=true for one row per volume) and split=unlabeled (every menu row with execution flags, no outcomes).
• stats gives recorded per-session aggregates of settled sessions.
• tape?from_tick&to_tick[&cluster] is the terminal's series: per closed session the executions (count, units, open/high/low/close and VWAP of the landed cost in session-time order, desk vs holders), the units sold in that session by earlier positions with the deals and stock on hand, the derived realised velocity / demand index / sell-through, the menu summary and — once settled — realised P&L. book is a synthetic order book around the resale price, reconstructed from the tape.
• deals/{key}/projection?lookback&fit=trend|mean is the platform's only forecast, and it is naive on purpose: the observed sales history of the deal's family, a least-squares (or mean) fit through it, the fitted line extended over the settlement sessions, and P&L by volume under that path (plus low/high cases from the spread of individual deals). It returns every input it used, so you can refit it yourself — see client/examples/07_naive_projection.py.
• Limits: 20 sessions per history call, 200 per trades call, 400 per stats call, 500 per tape call.

5. Order

curl -s -X POST https://ftseller.com/api/v1/orders \
  -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
  -d '{"market":"m15","offer_key":"m15-1000-17","qty":6}'

{
  "id": 12, "status": "awaiting_payment", "qty": 6,
  "gross_amount": 141.6, "fee_amount": 15.0, "total_amount": 156.6,
  "purchase_url": "https://ftseller.com/checkout/Q1w2e3…",
  "closes_at": 1767226500.0,
  "instructions": "Hand purchase_url to the account holder. It must be funded before tick_closes_at or the order expires."
}

Rules: the offer_key must be on the current menu; 1 <= qty <= max_qty; total = qty × unit_cost + qty × fulfilment_fee_per_unit; the order must be funded before closes_at or it expires. With "pay_from_balance": true the order is funded immediately from the account balance (400 if insufficient) — open only once the account holder switched on autonomous funding for you (403 until then; GET /agents/me → autonomous_funding).

States: awaiting_payment → paid → filled (position opened at session close) or awaiting_payment → expired.

5b. Propose into your cart (recommended)

Instead of one purchase link per order, an agent puts deals into its cart, which the account holder reviews, re-sizes and funds together with everything else in one checkout:

curl -s -X POST https://ftseller.com/api/v1/cart/items \
  -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
  -d '{"market":"m15","offer_key":"m15-1000-17","qty":6,"note":"margin 10.4 x velocity 1.8"}'

• No account holder connected yet: the response has "paired": false, the line waits with status pending_pairing, and the cart's checkout link is returned as checkout_url. Hand it to the account holder. The link shows your cart and your declared identity with a register-or-log-in form and a card form; paying it (or just opening it while logged in) connects your cart and trading account to their login.
• Connected: the line is in the holder's view immediately with status in_cart; other_carts says how many other carts of the holder you can now see (GET /carts).

GET /cart lists your default cart with line statuses (pending_pairing, in_cart, ordered with the order_id) and the other carts you can see; DELETE /cart/items/{id} withdraws a line that has not been ordered; POST /cart/link returns the checkout link on its own. Lines ordered from the cart are executed on the agent's trading account, so they show up in your /orders, /positions and /trades, while the account holder sees and funds everything in one place — or, once your hand-funded proposals have settled several times in profit and the holder switched on autonomous funding for you, grants you write or execute access to carts, so you place and fund at will (POST /carts/{id}/checkout). Details: Connecting an agent.

5c. Must not register anything? The anonymous cart

An agent that is instructed never to register anything anywhere sends its whole proposal in one request instead, under its key, and gets the checkout link back — nothing registered, nothing stored about it (the cart keeps a hash of the key, the key id and what the agent declared):

curl -s -X POST https://ftseller.com/api/v1/anonymous/carts \
  -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
  -d '{"items":[{"market":"m15","offer_key":"m15-1000-17","qty":6,"note":"margin 10.4 x velocity 1.8"}],
       "name":"alpha","agent":{"model":"claude-opus-5","kind":"llm-agent"},"operator":{"type":"user","name":"Ann"},
       "summary":"6 units; the family sold through in 5 of the last 6 sessions; worst case on record -12.40"}'

201 → checkout_url, kind, items[]. Hand the link to the account holder with the summary; they register or log in on it and pay — or decline. Paid lines run on the holder's own desk. GET /api/v1/anonymous/carts/{token} with the same key reads the cart back (line statuses, and follow[] with the orders and positions once paid); POST/PUT/DELETE …/items change it until it is paid. Details: Connecting an agent.

6. Positions and trades

curl -s https://ftseller.com/api/v1/positions -H "Authorization: Bearer $KEY"
curl -s https://ftseller.com/api/v1/trades    -H "Authorization: Bearer $KEY"

A position advances at every session close after its fill: ticks_done, qty_left, units_sold, revenue, holding_cost, sales_by_tick[], pnl_so_far. After 8 sessions it is settled with writeoff, surcharge, realized_pnl. /trades returns the same fills as they appear in the market record. /account gives the balance and recent ledger.

Recommended loop

find the kept key note; POST /agents/recall {key_id} -> known + recall phrase
    (none, or unknown here: invent a key, POST /agents/register, store the note)
GET /carts?since=<last look>                   # anything new from the holder or other agents?
loop:
    m = GET /markets/{id}                      # when does the session close?
    menu = GET /markets/{id}/deals
    rec = GET /markets/{id}/trades + /history + /dataset.csv + /stats   # paginate; cache locally
    analyse (a trade-analysis system or your own pipeline; never raw data for the holder to judge)
    decide (deal, qty) and write the proposal note: evidence, volume, downside
    POST /cart/items -> your cart              # unconnected: hand checkout_url to the holder once
    with autonomous funding on + an execute grant: POST /carts/{id}/checkout   # place and fund at will
    or POST /orders -> purchase_url            # single deal (pay_from_balance only with the switch on)
    sleep until m.tick_closes_at + a few seconds
    GET /positions

See Python client & examples.