Skip to the page
HOSTED (PREVIEW)/HOSTED APP

Hosted app

Preview: the hosted app is in beta, with limited free plans. Routes, scopes and limits can change during the beta. For every route and field, see https://app.tradefloor.dev/agents.md and /openapi.json.

The hosted app at app.tradefloor.dev keeps simulated markets, called sessions, on a server. An agent or a bot trades them through an MCP server at /mcp, an HTTP API at /v1, or an API shaped like Alpaca's trading API at /broker/{session_id}. Hosted tools place orders, and time in a session moves only when the caller advances it. To run a model on your own machine, use the LLM adapters or the local MCP server, which keeps its markets in memory on your machine.

Setup

Sign in to app.tradefloor.dev with your email address (there is no password) and make an API key on the Connect page, /connect, which also shows the configuration for each client. Send the key as Authorization: Bearer tfk_... on every request. MCP clients that support OAuth, such as claude.ai, Claude Desktop, Claude Code and Cursor, can sign in and skip the key. The token they get works on /v1 too, within the scope you granted.

You choose a key's scope when you make it:

ScopeWhat it can do
fullThe whole API, including forks, analysis, scoring and choosing a session's seed. Keys themselves are made and revoked only in the browser.
traderThe trading loop only: observe, orders, advance, close, fills, bars, series, events, its own sessions, describe and usage, a report on its line and that line's report card, and the whole Alpaca-shaped API. It opens a session only from a named template, on a seed it never sees, or trades one a full key opened and handed over. Use it for an agent under test.
read-onlyReads everything and changes nothing, for dashboards and reports.

A call outside the key's scope gets 403 forbidden, with the scope named in the message.

The loop

All three interfaces run this loop on a session:

  1. Open a session once and keep the session_id it returns.
  2. Observe the session: the clock, quotes, the account and open orders.
  3. Decide what to trade from that observation.
  4. Place orders, or cancel orders that are still waiting.
  5. Advance time by a step or more, and go back to the second step.
  6. Close the session. Its report carries caveats that say what the result does and does not show.

If your agent is given a simulation from the app's Simulator, an id that starts sim_, it skips the first step. list_sessions shows the session whose simulation_id matches, and the agent trades that one.

A market order fills at the start of the next step, when you advance, at the price the order book gives for its size. Right after you place it, its status is accepted. GET /v1/sessions/{id}/manifest returns the session's manifest, and the tradefloor package can rebuild the market from it.

MCP

The MCP endpoint is https://app.tradefloor.dev/mcp, over streamable HTTP. With Claude Code and a key in TF_KEY:

claude mcp add --transport http tradefloor https://app.tradefloor.dev/mcp \
  --header "Authorization: Bearer $TF_KEY"

Other clients, such as claude.ai, Codex and Cursor, take the same URL. The Connect page shows the configuration for each.

A first session takes four tool calls: open_session, observe, place_order with a ticker, a side and a whole-share quantity, and advance. To try it, ask the model to open a session, buy 10 shares of the first ticker, advance one step and observe again. close_session ends the session and returns the report. Every write takes an idempotency_key argument. Besides the loop, the tools include fork_session, list_fills, get_bars, get_events, list_presets, describe and get_usage. list_presets names the recommended preset, and a session records the preset it ran.

HTTP API

Here is the loop over /v1 with curl. A write carries an Idempotency-Key header with a new value for each action:

export TF_KEY=tfk_...
API=https://app.tradefloor.dev/v1
curl -H "Authorization: Bearer $TF_KEY" $API/describe

curl -X POST $API/sessions -H "Authorization: Bearer $TF_KEY" \
     -H "Idempotency-Key: $(uuidgen)" -H 'content-type: application/json' \
     -d '{"universe_size": 5, "seed": 7}'
# the answer carries "session_id"; set S to it

curl "$API/sessions/$S/observation?view=compact" -H "Authorization: Bearer $TF_KEY"
curl -X POST $API/sessions/$S/orders -H "Authorization: Bearer $TF_KEY" \
     -H "Idempotency-Key: $(uuidgen)" -H 'content-type: application/json' \
     -d '{"ticker": "AAA", "side": "buy", "quantity": 10}'
curl -X POST $API/sessions/$S/advance -H "Authorization: Bearer $TF_KEY" \
     -H "Idempotency-Key: $(uuidgen)" -H 'content-type: application/json' \
     -d '{"steps": 1}'
curl $API/sessions/$S/fills -H "Authorization: Bearer $TF_KEY"

POST /v1/sessions/{id}/close ends the session and returns its report. If you send a write again with the same Idempotency-Key, you get the first result back and nothing happens twice, so you can safely resend a request that timed out.

Alpaca-shaped API

A bot written for alpaca-py can trade a hosted session. Set its base URL to https://app.tradefloor.dev/broker/{session_id} and put the API key where alpaca-py takes the secret. You open sessions on the HTTP API and trade them through the facade. Simulated time moves only when the bot calls /tradefloor/advance, at the point where a live bot would sleep.

import os

from alpaca.trading.client import TradingClient
from alpaca.trading.enums import OrderSide, TimeInForce
from alpaca.trading.requests import MarketOrderRequest

KEY = os.environ["TF_KEY"]
url = f"https://app.tradefloor.dev/broker/{os.environ['SESSION_ID']}"
trading = TradingClient("tradefloor", KEY, url_override=url)

trading.submit_order(MarketOrderRequest(symbol="AAA", qty=10, side=OrderSide.BUY,
                                        time_in_force=TimeInForce.DAY))
trading.post("/tradefloor/advance", {"until": "next_open"})
print(trading.get_all_positions())

alpaca-py puts /v2 in front of every path, so the advance call goes to /broker/{session_id}/v2/tradefloor/advance. The app serves the route with and without the /v2.

The facade serves the account, clock, calendar, assets, positions, market, limit, stop and stop-limit orders with day or gtc, fill activities, latest trades and quotes, snapshots, bars, and news built from the session's event log. It refuses streaming, trailing-stop, bracket, OCO and OTO orders, notional and fractional orders, ioc, fok, opg and cls, extended hours, and replacing an order, with a message naming what it doesn't serve. A bot that depends on any of those needs more changes than the base URL.

Hosted sessions and the library

Hosted sessionLibrary on your machine
Order quantityWhole shares only. A fraction is refused, never rounded.Any finite number of shares, fractions included.
When a market order fillsAt the start of the next step, when you advance.When act returns, against the book at that step.
Ticks in a step30 by default, set when the session opens65 by default
Warm-up historyhistory_days up to 260history_days up to 2,520
Analysis toolscheck_envelope, evaluate_strategies, rank_strategies and explain_price_move, with tighter caps a call (20 days, 6 seeds and 4 strategies)The local MCP server's limits, or none through the library

Troubleshooting

Errors have one body shape over HTTP and MCP, {"code", "message", "hint"}. When waiting and resending the request will work, the body also has retry_after in seconds.

CodeStatusWhat to do
invalid_request400Fix the request as the message says.
unauthorized401Send a valid API key, or sign in.
forbidden403The key's scope does not cover the call. Use a key with a wider scope.
invalid_order400Fix the ticker, the quantity or the price. A fractional quantity lands here.
insufficient_buying_power403Send a smaller order or reduce a position first. The hint says how many shares would fit, and an order that lowers exposure is always accepted.
rate_limited429Wait retry_after seconds and resend.
quota_exceeded429 or 503A daily or capacity limit. The message says when it resets. A 503 means the whole service has used today's compute.
session_closed409The session is read-only now. Open a new one.
conflict409A race, or a reused idempotency key or client_order_id with a different request.
not_found404No such session or order for this account.
engine_mismatch409The session was made by an engine this server can no longer run. List it or delete it, and open a new one.
internal500A bug on our side. Resend once with the same idempotency key.

During the beta the free plan's limits are higher than they will be once paid plans launch, and you'll hear before they go down. They are 40 companies a session, 20 open sessions and 500 stored, 600 calls and 5,000 steps a minute, 200 open orders a session, and 20,000 simulated days and an hour of CPU time a day. A session plays to the close of day 1,260, five years, at most. GET /v1/usage, or the get_usage tool, gives the current limits and what's left today, and doesn't count as a call. Once paid plans launch, Free has 10 open sessions, and 10,000 simulated days and 30 minutes of compute a day. It includes 300 compute minutes, 60 minutes of code on tradefloor's servers and 100 AI credits a month, and stops there. Pro, 25 dollars a month and coming soon, includes more each month, has higher daily limits and bills usage past what it includes up to budgets you set. A bot with only a trader key that can't open a session needs open_from_template, or POST /v1/sessions/from-template.

Next steps