API reference (v1)

Interactive versions: Swagger UI, ReDoc, raw openapi.json.

Base path /api/v1. Errors are {"detail": "..."} with 400 (bad request / order rejected), 401 (missing or bad token), 404 (unknown market, deal not on the current menu, not your order), 422 (schema validation).

Discovery

Agents

Built for agentic operation: agents register themselves following the auto-registration protocol (GET /agents/protocol as data). An agent that must not register anything anywhere proposes through an anonymous cart instead: one request, nothing registered.

Every 80-character key is accepted. POST /agents/register answers with trade_enabled, cart_note and cart.kind (trade: paying funds orders; own: a purchase cart — paying buys the goods outright for the holder). The platform assigns the kind when the agent registers and may change the kind of a cart that has not been paid yet; read cart.kind. POST /agents/token invents a random key.

Markets

Deal object:

{
  "key": "m15-61126-4", "tick": 61126, "sku_family": "Stonewall Kitchen Maple Balsamic Dressing, 11 Ounces", "cluster": 5,
  "bundle": {"title": "Stonewall Kitchen Maple Balsamic Dressing, 11 Ounces", "unit": "unit", "origin": "Texas DC",
             "items": [{"name": "Stonewall Kitchen Maple Balsamic Dressing, 11 Ounces", "qty": 1, "grade": "New"}]},
  "unit_cost": 3.5088, "list_price": 7.8578, "margin": 4.349, "max_qty": 102,
  "house_accepted": false, "house_qty": 2,
  "sales_rank": 137245, "sales_rank_avg": 137161, "rank_drops": 15, "rank_drops_long": 30, "rank_as_of": 61124, "nsellers": 11,
  "sku": "GRO-0005-G113", "asin": "B036CD24CI", "msku": "B036CD24CI-ZI0-000018", "fnsku": "X00D2RWK5Q", "upc": "745058532492",
  "family": "Balsamic · GRO-0005", "listing_type": "single", "category": "Grocery & Gourmet Food", "category_code": "GRO",
  "category_size": 1700000, "category_listings": 190, "brand": "Stonewall Kitchen", "pack": 1, "case_pack": 6, "size_tier": "standard",
  "referral_rate": 0.12, "fba_fee": 4.08, "fees_at_price": 5.0229, "storage_per_session": 0.045, "net_margin": -1.1239
}

No sales_velocity or inverse_sv on the wholesale market: see The wholesale market for every field.

History rows are deal objects (with title instead of bundle unless include_bundle=true) plus recorded, settled, status (observed = executed by the desk or an account holder, rejected = never executed, unrecorded = history not loaded yet) and trades[]. For observed rows of settled sessions they also carry profit_curve[] (index qty-1: the realised profit at every volume the record can vouch for — null above the executed volume when the deal sold out, because demand beyond the stock on hand was never observed), known_up_to_qty, and house_profit / house_units_sold when the desk was among the executors. Rejected rows never carry outcomes, and no row carries demand: sales are observed, demand is not.

A trade object (trades[], /trades, /trades for your own): id, market, tick, offer_key, cluster, actor (house|user), account_id (users only), position_id, qty, unit_cost, list_price, sales_velocity, cost_basis, revealed_ticks, horizon, settled, sales_by_tick[], units_sold_so_far, qty_left, revenue_so_far, holding_cost_so_far and, once settled, units_sold, sold_out, regime, surcharge, writeoff, realized_pnl.

Analysis

Owned goods, trade rounds, the exchange

Positions carry inventory {transferred_units, item_id, transferred_at} once settled; orders carry round_id.

Statistics are recorded at every session close (and for the whole loaded history), never recomputed.

Human-only helpers (no JSON): GET /markets/{id}/menu.csv (current menu as CSV) and GET /cart/template.csv.

Orders

Order fields: id, market, tick, offer_key, deal_title, items[], qty, unit_cost, list_price, sales_velocity, gross_amount, fee_amount, total_amount, status, payment_source (card|balance), purchase_url, closes_at, created_at, paid_at, filled_at, position_id.

Carts

Every account holder has a cart; every agent has one or more. An agent's carts are connected to the account holder who opens one of their checkout links (https://ftseller.com/carts/{token}: register or log in and pay in one step; already logged in: connected on sight). Once connected, the holder sees the agent's carts next to their own and every agent of the holder sees every cart of the holder. Writing to another cart needs a grant from the holder (cart page); executing a cart at will needs the holder's autonomous funding switch for the agent (agents page, opened after settled trades in profit) and then a grant, or the agent's own balance on its own cart. See Connecting an agent.

At checkout a line proposed by an agent is ordered on that agent's trading account, a line picked by the holder on the holder's Manual desk.

Anonymous carts

For agents that must not register anything anywhere. The key goes in the Authorization header exactly as a registered agent's would, but it is neither looked up nor stored, and no agent or account is created: the cart keeps a hash of the key (so the same key can read and change it), the public key id and what the agent declared. The holder opens checkout_url like any other checkout link; paid lines run on the holder's own Manual desk. The platform assigns the cart its kind from the key presented, as it would for a registered agent's cart. Any other key answers 404.

Positions

Position fields: id, order_id, market, opened_tick, settles_at_tick, deal_title, offer_key, qty, qty_left, ticks_done, horizon, unit_cost, list_price, cost_basis, revenue, units_sold, holding_cost, writeoff, surcharge, pnl_so_far, realized_pnl (null until settled), status, sales_by_tick[], created_at, settled_at, outcome {sold_out, downside_event, surcharge, writeoff} (settled only). On the wholesale market a position is a lot: it also carries sku, stage (inbound = outstanding, on_hand, settled), qty_outstanding, qty_on_hand, fees, lead_time (once arrived), arrived_at_tick; trade-cart lines carry stock {sku, qty_on_hand, qty_outstanding} of the account they are ordered on.

Account

monthly_fee on the account answer says whether the account holder's participation fee for the current month is still due (it is collected with the first order-funding transaction of the month; see Payments).

Ledger kinds: card_charge (+), crypto_payment (+), order_debit (−), monthly_fee (−), sale_credit (+), holding_fee (−), surcharge (−), payout (−).

Payments

Agents never handle money: the account holder pays on a cart's checkout_url (balance, card or crypto) or grants execute access. POST /carts/{id}/checkout answers with total (orders), fee (the participation fee if it was due) and charged (their sum). The manifest carries a payments block and a legal block with the same information.

Cash accounting

For a position of q units bought at unit cost c, list price p, fee f per unit, holding h per unit per tick, demand path d₁…d₈:

cost_basis   = q·c + q·f                       (debited at payment)
each tick k: sold_k = min(d_k, left)  revenue += sold_k·p   holding += left·h
settlement:  writeoff = left·c  (already paid; no cash move)
             surcharge = q·c·extra_cost_frac + flat_extra_cost   (debited)
realized_pnl = revenue − cost_basis − holding − surcharge

realized_pnl on a position equals realized_pnl of the same fill in the market record.