# Hosted app

Source: https://docs.tradefloor.dev/hosted.html

> Preview documentation for the hosted app at app.tradefloor.dev: how an agent or a bot connects over MCP, the HTTP API at /v1 and an Alpaca-shaped API.

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](https://docs.tradefloor.dev/llm-adapters.html) or the [local MCP server](https://docs.tradefloor.dev/mcp-local.html), 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:

| Scope | What it can do |
| --- | --- |
| full | The whole API, including forks, analysis, scoring and choosing a session's seed. Keys themselves are made and revoked only in the browser. |
| trader | The 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-only | Reads 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:
- Open a session once and keep the `session_id` it returns.
- Observe the session: the clock, quotes, the account and open orders.
- Decide what to trade from that observation.
- Place orders, or cancel orders that are still waiting.
- Advance time by a step or more, and go back to the second step.
- 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](https://docs.tradefloor.dev/glossary.html#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](https://docs.tradefloor.dev/glossary.html#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 session | Library on your machine |
| --- | --- | --- |
| Order quantity | Whole shares only. A fraction is refused, never rounded. | Any finite number of shares, fractions included. |
| When a market order fills | At the start of the next step, when you advance. | When act returns, against the book at that step. |
| Ticks in a step | 30 by default, set when the session opens | 65 by default |
| Warm-up history | history_days up to 260 | history_days up to 2,520 |
| Analysis tools | check_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.

| Code | Status | What to do |
| --- | --- | --- |
| invalid_request | 400 | Fix the request as the message says. |
| unauthorized | 401 | Send a valid API key, or sign in. |
| forbidden | 403 | The key's scope does not cover the call. Use a key with a wider scope. |
| invalid_order | 400 | Fix the ticker, the quantity or the price. A fractional quantity lands here. |
| insufficient_buying_power | 403 | Send 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_limited | 429 | Wait retry_after seconds and resend. |
| quota_exceeded | 429 or 503 | A daily or capacity limit. The message says when it resets. A 503 means the whole service has used today's compute. |
| session_closed | 409 | The session is read-only now. Open a new one. |
| conflict | 409 | A race, or a reused idempotency key or client_order_id with a different request. |
| not_found | 404 | No such session or order for this account. |
| engine_mismatch | 409 | The session was made by an engine this server can no longer run. List it or delete it, and open a new one. |
| internal | 500 | A 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](https://tradefloor.dev/plans.html), 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
- Watch [No install](https://tradefloor.dev/video-no-install.html), a 3:47 video recorded on the hosted app.
- Watch [Can Claude out-trade a bot?](https://tradefloor.dev/video-claude-trades.html), a 2:07 video recorded on the hosted app.
