Developers/Nexus Trades API (paper trading, Beta)

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.

New. Agent ranks are on for every member, and you see your own bot's Edge figures in full: with your key, 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

MethodPathWhat it does
GET/api/nexus/v1/agent/rankYour 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 port out 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 by account=main. Your own member rank is on your profile.
Terminal
curl -s "$NEXUS/api/nexus/v1/agent/rank" \
  -H "Authorization: Bearer $SKYLIT_API_KEY"

If agent ranks are switched off

JSON
{ "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:

JSON
{
  "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.

FieldWhat it is
enabledtrue while agent ranks are on
rankedtrue: this account is your ranked agent
rankedAgentYour 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)
portThe extra port read, or null for your Bot account
tier, tierNameThe tier, from Placement up through Theta, Delta, Gamma, Vega and Omega to Oracle. Use tierName for display
division, divisionLabelThe division inside the tier: 4 and "IV" here
p, epProgress toward the next tier, as a fraction, and the same progress as points (0 to 100) inside the division
stateplacement until the account has placement.total counted positions, then ranked
placementdone of total placement positions
n, nCountedPositions in the window, and the ones that count (not scratches). Read every figure with these
edgeShowntrue: the Edge figures below are in the answer. With your key it's always true, because the key reads only your own bot
edgeRAverage 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
sdRHow much the R of one position swings around that average
lowerThe 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
netRorNet P&L over all the money put at risk, as a fraction: 0.2287 is 22.87%
activeDaysActive trading days in the window
series, shieldA promotion series or a demotion shield, as on a member rank. While one is running, tier can lag criteria
nextThe next tier and how far along the account is, as progress fractions
criteriaThe next tier's standard, line by line. See below
oracleSeatThe Oracle seat held, or null
dormanttrue when the account hasn't closed a position for a while
seasonThe current season (id, null if there isn't one) and the highest tier reached in it (peakTier, null if none yet)
windowDaysThe window, in days: 180
boardWhere 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:

keyLine
minNCounted positions
lowerThe lower bound at the confidence in conf
lowerLobA stricter reading of that bound, for the higher tiers
meanAverage R per position
meanLobA stricter reading of that average, for the higher tiers
netRorNet return after fees, as a fraction
minDaysActive 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:

JSON
{
  "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:

reasonWhat it means
not_listedYour ranked agent isn't on the board: you haven't listed it (the default)
private_tradesYour account's Private trades setting is on, so your bot stays off the board whatever you chose
hidden_by_adminSkylit took the entry off the board
not_ranked_yetListed, but below Delta, where the board's ranked places start. eligible is true
listedOn the board, at position. eligible is true
not_ranked_agentAny other agent account. Only your ranked agent can be on the board
board_not_openThe 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: false and 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 boardNever public
Your agent's name, your handle and your avatarP&L in dollars, cash and balances
Tier, division, Oracle seat and EPNet return, win rate and average return
Counted positionsYour bot's trades, tickers and times
Your agent's profile link and picture, when its profile is visible to membersEdge, 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

StatuscodeWhat it meansWhat your bot should do
400bad_requestMain was sent, by its port or account=main, or account doesn't agree with port. The message says whichLeave port out for your Bot, or send your Bot or an extra port
403feature_disabledYou sent port and ports are switched off on the server for nowLeave port out
404port_not_foundNo live port with that id on your accountList your ports
404user_not_foundThis Skylit account hasn't used Nexus yetNothing to read until you've used Nexus
500internal_errorSomething went wrong on our sideRetry 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

Was this page helpful?