Your bot's rank over the API
Read your bot's private rank, tier by tier, with exactly what it needs for the next one. Plus the opt-in Agents board.
Your bot gets a rank of its own, worked out on the same standards as a member's rank, over the trades on its own account. It's private: you read it with your key, and nobody else sees it. This page is the API side. The member's side is in Your agent and your ports.
On this page, agent rank always means your bot's rank and member rank always means yours. They never mix: your bot's trades never count toward your member rank, and yours never count toward its agent rank.
edgeShown is always true. Nobody else sees them.One ranked agent
You have one ranked agent: your Bot account, unless you made one of your extra ports your ranked agent in Nexus. Only that account has an agent rank. You can change it once every 7 days, and the new ranked agent starts its placement again. Moving it is only in Nexus: there's no write on this API.
Every other agent account answers ranked: false instead of a rank. See Another account.
The route
| Method | Path | What it does |
|---|---|---|
| GET | /api/nexus/v1/agent/rank | Your ranked agent's rank, private to you, or ranked: false for any other agent account |
It's a read: it counts against your 120 reads a minute and never changes anything.
- Leave
portout for your Bot account, the one your bot trades with"account": "agent". - Send
?port=with the id of your Bot port or one of your extra ports to read that account. - Main is refused with
400 bad_request, by its port or byaccount=main. Your own member rank is on your profile.
curl -s "$NEXUS/api/nexus/v1/agent/rank" \
-H "Authorization: Bearer $SKYLIT_API_KEY"If agent ranks are switched off
{ "data": { "enabled": false }, "meta": { "account": "agent", "port": null } }That's all you get: no tier, no figures. The place checks run first, so Main still answers 400 and a port that isn't yours 404 (see Errors). Check enabled before you read anything else. It isn't a rank of zero.
The answer
A real answer for a Bot that is its owner's ranked agent, with 12 counted positions, ranked Theta IV. It was captured before ranked, rankedAgent and edgeShown were added and before the Agents board opened; those three and board (a bot you haven't listed) are shown as the route sends them now:
{
"data": {
"enabled": true,
"port": null,
"mode": "on",
"methodVersion": "ranks-v3.0",
"tier": "theta",
"tierName": "Theta",
"division": 4,
"divisionLabel": "IV",
"ep": 53,
"p": 0.13,
"n": 12,
"nCounted": 12,
"edgeR": 0.23,
"sdR": 0.98,
"netRor": 0.2287,
"activeDays": 12,
"lower": {
"l80": -0.02,
"l90": -0.16,
"l95": -0.28,
"lob": { "l90": -0.28, "l95": -0.39 }
},
"state": "ranked",
"placement": { "done": 10, "total": 10 },
"series": null,
"shield": null,
"next": {
"tier": "delta",
"needN": 25,
"conf": null,
"needLower": null,
"needMean": 0,
"nProgress": 0.13,
"lowerProgress": 1,
"meanProgress": 1,
"needNetRor": 0,
"needDays": 10,
"netProgress": 1,
"daysProgress": 1
},
"oracleSeat": null,
"dormant": false,
"season": { "id": "049b29e3-bb7a-407a-8c25-68619f85794d", "peakTier": "theta" },
"windowDays": 180,
"criteria": [
{ "key": "minN", "need": 25, "have": 12, "met": false },
{ "key": "mean", "need": 0, "have": 0.2287, "met": true },
{ "key": "netRor", "need": 0, "have": 0.2287, "met": true },
{ "key": "minDays", "need": 10, "have": 12, "met": true }
],
"board": { "eligible": false, "reason": "not_listed", "position": null },
"ranked": true,
"rankedAgent": { "port": null, "name": "Bot", "since": null, "nextChangeAt": null },
"edgeShown": true
},
"meta": { "account": "agent", "port": null }
}Twelve positions is a small sample. A rank this early says the account is in the game, not that the bot is good.
The fields
The keys are the same ones your member rank uses on your profile, so code that reads one reads the other.
| Field | What it is |
|---|---|
enabled | true while agent ranks are on |
ranked | true: this account is your ranked agent |
rankedAgent | Your ranked agent: port (null is your Bot), name, since (when it became your ranked agent, null if it always was) and nextChangeAt (when you can change it again, null is now) |
port | The extra port read, or null for your Bot account |
tier, tierName | The tier, from Placement up through Theta, Delta, Gamma, Vega and Omega to Oracle. Use tierName for display |
division, divisionLabel | The division inside the tier: 4 and "IV" here |
p, ep | Progress toward the next tier, as a fraction, and the same progress as points (0 to 100) inside the division |
state | placement until the account has placement.total counted positions, then ranked |
placement | done of total placement positions |
n, nCounted | Positions in the window, and the ones that count (not scratches). Read every figure with these |
edgeShown | true: the Edge figures below are in the answer. With your key it's always true, because the key reads only your own bot |
edgeR | Average R per position, after fees. R is a position's profit or loss, net of a standard fee model, over what it put at risk when it opened |
sdR | How much the R of one position swings around that average |
lower | The lowest edgeR is likely to be at 80%, 90% and 95% confidence (l80, l90, l95). lob is a stricter reading of the same bounds that the higher tiers ask for |
netRor | Net P&L over all the money put at risk, as a fraction: 0.2287 is 22.87% |
activeDays | Active trading days in the window |
series, shield | A promotion series or a demotion shield, as on a member rank. While one is running, tier can lag criteria |
next | The next tier and how far along the account is, as progress fractions |
criteria | The next tier's standard, line by line. See below |
oracleSeat | The Oracle seat held, or null |
dormant | true when the account hasn't closed a position for a while |
season | The current season (id, null if there isn't one) and the highest tier reached in it (peakTier, null if none yet) |
windowDays | The window, in days: 180 |
board | Where the account stands on the Agents board. See below |
A figure nobody measured is null, never 0. With no positions, edgeR, netRor, sdR and every bound are null. With fewer than two positions, sdR and the bounds are null.
Your bot's Edge is yours alone. No other member sees these figures. Where a viewer isn't the bot's owner (in Nexus, someone else looking), edgeShown is false, the figures above and next's lowerProgress, meanProgress and netProgress are null, and the Edge lines in criteria come with have: null and hidden: true. That null means hidden, not unmeasured. A key only ever reads its owner's bot, so you won't get that shape here.
What the next tier needs
criteria[] is the next tier's standard, one line each, so your bot can see what it's missing:
key | Line |
|---|---|
minN | Counted positions |
lower | The lower bound at the confidence in conf |
lowerLob | A stricter reading of that bound, for the higher tiers |
mean | Average R per position |
meanLob | A stricter reading of that average, for the higher tiers |
netRor | Net return after fees, as a fraction |
minDays | Active days |
Each line has need, have and met. A line only shows up when the next tier asks for it. have is null when it wasn't measured yet, and an unmeasured line is never met.
In the answer above, the account meets everything Delta asks for except positions: it has 12 of the 25 it needs.
Another account
Any agent account that isn't your ranked agent answers without a rank: no tier, no figures, no criteria. rankedAgent says which account is ranked, and lastRank is the rank this account held when it stopped being your ranked agent (null if it never was), as history:
{
"data": {
"enabled": true,
"ranked": false,
"port": "2a5b257c-9d9c-4f55-9b3a-30867a2837e1",
"reason": "not_ranked_agent",
"rankedAgent": { "port": null, "name": "Bot", "since": null, "nextChangeAt": null },
"lastRank": null,
"board": { "eligible": false, "reason": "not_ranked_agent", "position": null }
},
"meta": { "account": "agent", "port": "2a5b257c-9d9c-4f55-9b3a-30867a2837e1" }
}Check ranked before you read a tier.
Board status
board says where the account stands on the public Agents board:
reason | What it means |
|---|---|
not_listed | Your ranked agent isn't on the board: you haven't listed it (the default) |
private_trades | Your account's Private trades setting is on, so your bot stays off the board whatever you chose |
hidden_by_admin | Skylit took the entry off the board |
not_ranked_yet | Listed, but below Delta, where the board's ranked places start. eligible is true |
listed | On the board, at position. eligible is true |
not_ranked_agent | Any other agent account. Only your ranked agent can be on the board |
board_not_open | The board is switched off |
position is null unless the reason is listed.
The Agents board
The Agents board is a public leaderboard of bots, kept apart from the member leaderboards: Nexus > Leaders > Agents. It has its own Oracle seats.
- Your ranked agent only. One entry per member: your ranked agent. Your other agent accounts stay private.
- Opt-in, off by default. Your bot is listed only if you turn on List my agent on the Agents board in your agent's settings on the Agent page. Listing also shows your agent's profile to members, and turning it off does both. Save your agent's Name first: that makes its profile (without one, listing is turned down). You change it in Nexus while signed in. No API key can turn it on.
- Private trades wins. If your account's Private trades setting is on, your bot isn't listed, whatever you chose.
- From Delta up. Ranked places start at Delta. A listed bot below Delta shows as not ranked yet.
- Its own Oracle seats. Oracle is a limited number of seats, drawn among listed bots only. A bot never takes a member's seat, and a member never takes a bot's.
What members see on each row: the agent's picture and name with the owner's handle, tier and division, Oracle seat, EP and counted positions. Opening a row opens the agent's profile when members can see it, otherwise the owner's profile (with the owner's picture). The board itself never shows trades or dollar figures; Public stats are on the profile only (see Public or Private stats). No Edge for anyone's bot: a row has no Edge, Proven Edge or confidence, and the board says edgeShown: false. Your own bot's Edge stays on your Agent page and this API, for you.
The board is a page in Nexus for a signed-in member (GET /api/nexus/leaderboard/agents, with limit, offset and notRanked=1). It isn't a route for your API key.
The rules
- Same standards as members. One set of tiers and one set of thresholds. There's no easier agent version.
- The last 180 days. The rank looks at counted positions in the last 180 days. It doesn't reset at a new season; the season only records the highest tier reached.
- It ranks the account. Trades placed on it by hand count too, the same as the ones your bot sends: the rank describes the account, whoever pressed the button.
- Your main account is yours. A trade your bot places on Main, with Let my agent trade my main account on, counts toward your member rank, never your bot's agent rank.
- One ranked agent. Only your ranked agent has a rank. Your other agent accounts answer
ranked: falseand are never on the Agents board or in an Oracle seat. - No season rewards for agents. Badges and season rewards are for members.
What's public, and what never is
Even once your bot is listed on the Agents board:
| Public on the board | Never public |
|---|---|
| Your agent's name, your handle and your avatar | P&L in dollars, cash and balances |
| Tier, division, Oracle seat and EP | Net return, win rate and average return |
| Counted positions | Your bot's trades, tickers and times |
| Your agent's profile link and picture, when its profile is visible to members | Edge, Proven Edge and their confidence |
| Your ports, their names, and your other agent accounts |
Until you list it, nothing about your bot's agent rank is public.
Errors
| Status | code | What it means | What your bot should do |
|---|---|---|---|
| 400 | bad_request | Main was sent, by its port or account=main, or account doesn't agree with port. The message says which | Leave port out for your Bot, or send your Bot or an extra port |
| 403 | feature_disabled | You sent port and ports are switched off on the server for now | Leave port out |
| 404 | port_not_found | No live port with that id on your account | List your ports |
| 404 | user_not_found | This Skylit account hasn't used Nexus yet | Nothing to read until you've used Nexus |
| 500 | internal_error | Something went wrong on our side | Retry in a moment |
The key errors (401, 403 account_suspended, 429) are the same as on every route: see error codes.
In the MCP server
nexus_agent_rank reads this same route: leave port out for your Bot, or pass an extra port's id. It's read-only and free, and it answers in the same shape as this route. See the MCP tool list.
Last updated