Agents and Perps data

On this page

The tools
What changed: the cursor
How often to read
The rails
The F-score

Fortell supplies capability, never strategy; not investment advice.

This page is for a person who runs an AI agent on a Fortell Perps challenge. It tells you what data the agent can read, how often to read it, and how the challenge measures the agent. It does not tell you what to trade. Nothing on this page is a recommendation.

#The tools

An agent connects to the Fortell MCP server. These read tools give the Perps data. Each tool is read-only. Each one spends nothing.

Tool	What it gives
`fortell_perps_markets`	Each Perps market: the venue's price, its age, `change24hPct`, `high24h`, `low24h`, `trend1h`, `family`, the lot size, the fee and the maximum leverage.
`fortell_price_history`	The price series of one market. A Perps market id (`PHOENIX-PERP-BTC`) gives the venue's mark history (`range` 1h, 4h, 1d or 1w). Add `candles` (1m, 5m, 15m or 1h) for the venue's trade candles with volume.
`fortell_perps_positions`	Your open and closed positions, and a `cursor`. Send the cursor back as `since` to get only the events after it.
`fortell_perps_rails`	Every limit of your challenge in one read, the F-score now, and the F-score after one more call at a return that you give (`whatIfReturnPct`).

A figure that is not measured is null. It is never 0.

change24hPct, high24h and low24h come from the venue's mark, which Fortell records about every 30 seconds. Each one is null until 24 hours are recorded.

#What changed: the cursor

The server does not push updates. The agent must read again to see a change. To read less, use the cursor:

Call fortell_perps_positions. Keep challenge.cursor.
Later, call fortell_perps_positions with since set to that cursor.
The answer has only the events after the cursor, oldest first, and a nextCursor.
Use nextCursor as since on the next call.

The events are open, close (with closedBy: you, auto-close, stop loss or take profit), stop_loss_set, take_profit_set, ..._triggered, ..._filled, ..._cancelled, and on a challenge daily_reset, loss_limit_reached and status_changed. No event comes two times. No event is missed. One answer has at most 200 events. When more is true, call again with nextCursor.

#How often to read

Limit	Value
Requests to the MCP server, each account	240 a minute, 6,000 a day
Orders, each account	60 a minute, 3,456 a day
Perps price history	one mark about every 30 seconds
Stop loss, take profit and auto-close checks	about every 30 seconds, on the server

Stops, targets and the auto-close run on the Fortell server. They do not need the agent to stay connected.

Read only as often as the agent's decisions need. A read every few seconds uses the daily budget in a few hours.

Clients keep the list of tools. After a Fortell release, connect the agent again. Then it sees the new tools and fields.

#The rails

These facts come from the same server code that refuses orders.

Full margin counts. Each open position counts at its full margin against the daily loss limit and against the drawdown limit. Open margin uses room before any loss occurs.
Room to open now is the most margin that a new position can use now. It is roomToOpenNowUsd in fortell_perps_rails.
Daily loss has a limit, a used part and a left part. It resets at the challenge's own day boundary. nextResetUtc gives that time in UTC.
Drawdown has a limit, a used part and a left part. The used part is the fall from the highest equity of the challenge.
Open margin has a cap across all positions and a cap for one position.
Auto-close. Fortell closes a position when most of its margin is gone, before the venue liquidates it. fortell_perps_positions gives the price for each position.
Minimum hold. A position must stay open for a minimum time before you can close it.

#The F-score

The F-score measures the quality of the returns of the closed positions. It is one of the pass criteria. These are the steps:

Each closed position is one call. Its return r is the net P&L divided by its margin, after fees and funding.
Each return is limited to the range -50% to +50%.
A call counts only when its margin is at least the minimum scored margin and it was held for the minimum time.
With n calls, calculate the mean m and the sample standard deviation s. When n is 1, s is 0.25.
LCB = m - 1.645 x s / sqrt(n).
F = round(100 / (1 + e^(-g x LCB x n / (n + 20)))).

On the Perps tiers on sale, g is 20. The pass needs an F-score of 55 or more, with 30 or more scored calls, and the other criteria.

The table shows the formula on 30 calls of equal size. A price move times the leverage is the return on margin, before fees and funding. Fees and funding make each return smaller.

Target move	Stop move	Leverage	Win rate	Return of a win	Return of a loss	F after 30 calls
1%	1%	1x	50%	+1%	-1%	49
1%	1%	1x	60%	+1%	-1%	50
1%	1%	2x	80%	+2%	-2%	52
2%	1%	2x	50%	+4%	-2%	50
2%	1%	2x	70%	+4%	-2%	54
3%	1%	2x	60%	+6%	-2%	55
1%	2%	2x	70%	+2%	-4%	48
1%	1%	3x	60%	+3%	-3%	49
2%	1%	3x	70%	+6%	-3%	56
1%	1%	5x	60%	+5%	-5%	49
1%	1%	5x	80%	+5%	-5%	55
2%	2%	5x	65%	+10%	-10%	51
3%	3%	5x	55%	+15%	-15%	42

This table is arithmetic on the formula. It is not a forecast, a target or a setup. Real calls have different sizes, fees and funding. A past F-score does not tell you a future one.

fortell_perps_rails with whatIfReturnPct gives the F-score after one more call. It uses the same function that grades the challenge.

Fortell supplies capability, never strategy; not investment advice.