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).

The continuous marketplace. This deployment runs one market, us (the classic ids m15, m45, h2 and h10 are accepted as aliases in paths and parameters; answers say us), on a marketplace clock: a tick is one marketplace hour (ticks_per_day 24, time_scale marketplace seconds per real second), offers stay open for days, orders fill at the close of the hour they are paid in, and the record has one entry per marketplace day. Every from_tick / to_tick below is in marketplace hours; answers carry sim_at (the marketplace date) next to tick. The API version stays v1; a client tells this deployment by time_model: "continuous" in the market status. Every renamed field is listed on The marketplace.

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": "us-2541-1", "tick": 2541, "sku_family": "Unique Pretzel, Sourdough Craft Beer Pretzel Rings, 11 Ounce", "cluster": 29,
  "bundle": {"title": "Unique Pretzel, Sourdough Craft Beer Pretzel Rings, 11 Ounce (Pack of 3)", "unit": "pack", "origin": "Mountain DC",
             "items": [{"name": "Unique Pretzel, Sourdough Craft Beer Pretzel Rings, 11 Ounce", "qty": 3, "grade": "New"}]},
  "unit_cost": 8.4779, "list_price": 21.1616, "margin": 12.6837, "max_qty": 120, "house_accepted": false, "house_qty": 2,
  "valid_until": 3027, "hours_left": 27, "sim_valid_until": "2026-05-07T03:00:00Z",
  "sales_rank": 380669, "sales_rank_avg": 326910, "rank_drops": 7, "rank_drops_long": 28, "rank_as_of": 2998, "nsellers": 12,
  "sku": "GRO-0029-G1", "asin": "B0UO2MXSVH", "msku": "B0UO2MXSVH-JZ2-000000", "fnsku": "X00ORXO0KF", "upc": "",
  "family": "Pudding Mixes multipack · GRO-0029", "listing_type": "multipack", "category": "Grocery & Gourmet Food",
  "category_code": "GRO", "category_size": 3000000, "category_listings": 40, "brand": "Unique Snacks", "pack": 3, "case_pack": 12,
  "size_tier": "large_standard", "unit_weight_lb": 2.54, "dimensions_in": [10.56, 6.33, 5.32], "cubic_feet": 0.2058,
  "shipping_weight_lb": 2.558, "units_per_carton": 4, "prep": {"label": true, "kit": true, "per_unit": 0.75},
  "referral_rate": 0.1498, "referral_fee": 3.17, "referral_min": 0.0, "fulfilment_fee": 6.68, "fulfilment_base": 6.45,
  "peak_surcharge": 0.0, "fuel_surcharge": 0.2258, "fba_fee": 6.68, "fees_at_price": 9.85,
  "storage_per_day": 0.005277, "storage_per_month": 0.160522,
  "peak_season": false, "fee_schedule": 0, "inbound_route": "parcel", "inbound_per_unit": 2.02,
  "inbound_routes": [{"route": "parcel", "label": "Partnered parcel", "available": true, "per_unit": 2.02, "lead_typical": 12, "lead_max": 35},
                     {"route": "express", "label": "Express (own carrier)", "available": true, "per_unit": 4.19, "lead_typical": 12, "lead_max": 35},
                     {"route": "ltl", "label": "Partnered LTL (pallets)", "available": true, "per_unit": 2.63, "lead_typical": 15, "lead_max": 42}],
  "lead_time": {"typical": 12, "min": 9, "max": 35, "unit": "days",
                "distribution": {"9": 0.0115, "10": 0.0537, "11": 0.1163, "12": 0.1581, "13": 0.1563, "14": 0.1234, "…": 0.0}},
  "return_threshold": 0.029, "net_margin": 0.8137
}

No sales velocity on this market: see The marketplace for every field (valid_until is the first hour the offer is no longer open; inbound_per_unit is the default route's fee for the offer's max_qty; inbound_routes[] and lead_time are in days — ask GET /markets/us/deals/{key}/inbound?qty= for your quantity).

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 lots 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, sim_at, offer_key, cluster, actor (house|user), account_id (users only), position_id, qty, unit_cost, list_price, cost_basis, revealed_entries, settled, sales_by_day[], units_sold_so_far, qty_left, sku, arrived, lead_time, step_hours — one entry per marketplace day (step_hours 24; entry i covers the hours tick + 1 + 24i … tick + 24(i + 1)), lead_time in days once arrived. The desk's trades are held 112 days (horizon) and carry price_by_day[], nsellers_by_day[] and, once settled, units_sold, sold_out, realized_pnl. An account's lot is pooled and open_ended (horizon null): it reveals buy_box_by_day[] (never the account's own price), route, auto_removal_at_tick once arrived and, once settled, settled_tick, units_sold, sold_out, realized_pnl (and flows {kind: amount} on your own /trades only).

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 marketplace hour's 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, gross_amount, fee_amount, total_amount, status, payment_source (card|balance), purchase_url, closes_at, created_at, paid_at, filled_at, position_id, route, inbound, pricing, expires_tick, paid_tick (once paid), sim_at — fee_amount is the inbound fee, inbound the route's quote (lead times in days) and pricing the starting rule (when given).

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://v2.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). A position is a lot: it also carries sku, stage, qty_outstanding, qty_on_hand, arrival_tick, lead_time, age_days, auto_removal_at_tick, cash_flows, flows {kind: amount}, accrued_today {kind: amount}, units {sold, restocked, removed, disposed, lost, returned}, returns_pending, last_sale_tick, price_by_tick[] — stage is inbound, on_hand, awaiting_returns or settled, lead_time (days) is shown once arrived, sales_by_tick and price_by_tick have one entry per marketplace day (price_by_tick is your own price, private), cash_flows and pnl_so_far = cash flows − cost basis count the money posted at day closes, and accrued_today what the lot earned and paid since the last day close (it is posted at the next one); settles_at_tick is null (a lot settles at a day close once it is sold out, removed or disposed of and its returns are back). 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).

GET /account also carries available_balance (the cash orders and payouts spend), seller_balance, reserve, wallets[] (per market: balance, reserve, carry, eligible_now, next_release_tick, next_release_at, on_demand_available) and fulfilment {market: {capacity_cuft, used_cuft, inbound_cuft, ordered_cuft}} (the fulfilment-network capacity in cubic feet). Ledger entries of a seller balance carry wallet (the market), tick (the last hour of the marketplace day that posted them; one entry per lot, kind and day, note "day N") and statement_id.

Ledger kinds — cash: card_charge (+), crypto_payment (+), order_debit (−), monthly_fee (−), payout (−), disbursement (+), negative_balance_charge (−); seller balance: sale_credit (+), referral_fee (−), fulfilment_fee (−), storage_fee (−), aged_inventory_surcharge (−), utilization_surcharge (−), low_inventory_fee (−), refund (−), referral_refund (+), refund_admin_fee (−), returns_processing_fee (−), removal_fee (−), disposal_fee (−), inbound_defect_fee (−), reimbursement (+), disbursement (−), negative_balance_charge (+) — see Payments.

Seller

The seller's own endpoints. Reads need your key; writes need the same access as placing orders (trade access, or a competition account). See The marketplace.

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

A lot of q units bought at unit cost c with an inbound fee f per unit:

cost_basis   = q·c + q·f                        (debited from cash at payment)
each hour from its arrival, accrued on the lot and posted to the seller balance at the day close (ref=position:{id}):
    sale_credit = sold·price          referral_fee, fulfilment_fee per unit sold
    storage_fee, aged_inventory_surcharge, utilization_surcharge on the units on hand
    low_inventory_fee per unit shipped (when stock runs short)
    refund, referral_refund, refund_admin_fee, returns_processing_fee on customer returns
    removal_fee / disposal_fee, inbound_defect_fee
    reimbursement (+) of units lost inbound on a partnered route
cash_flows   = Σ of those entries
realized_pnl = cash_flows − cost_basis          (once sold out or removed and every return is back)

realized_pnl on a position equals realized_pnl of the same lot in the market record. The seller balance reaches cash only through settlement statements (disbursement); a lot's result does not depend on when its money is released.