Reference

API reference

Every endpoint the simulator uses, with requests, responses, errors and limits.

These are the HTTP endpoints the simulator itself uses, all on https://www.kinfield.si. Requests and responses are JSON. They are documented so you can see exactly what the browser can and can't ask the server to do.

There are no API keys yet. Endpoints marked Signed in are authenticated by the kf_session cookie set when you sign in with GitHub, and writes from another website are refused. The endpoints may change as Kinfield develops.

Conventions

  • Prices are in US dollars; sizes are notional US dollars; times in responses are Unix milliseconds unless the field is an ISO string.
  • Errors return { "error": "message" } with a status code, and the message is written to be shown to a person.
  • Signed-in responses carry a server-timing header with the server's time for the request.
StatusMeaning
400The request was invalid, for example a size under $10 or a stop on the wrong side.
401Not signed in: Sign in to continue.
403A write came from another site.
404The order or position isn't open, or doesn't exist.
409The account was reset while the request was in flight.
429A rate limit was hit. See Rate limits below.
503Hyperliquid didn't return a price in time. Nothing was recorded; try again.

Trading

GET/api/sim/stateSigned in

The active account, after settling any triggers since it was last read.

{
  "accountId": "a3d9...",
  "startingBalance": 100000,
  "createdAt": 1760260440000,
  "cash": 100190.91,
  "positions": [ /* open positions */ ],
  "orders": [ /* resting limit orders */ ],
  "history": [ /* closed trades, newest first */ ],
  "ledger": { "entries": 311, "head": "e07a...5f19" }
}

POST/api/sim/ordersSigned in

Places a market or limit order.

Request

{
  "coin": "BTC",
  "side": "long",              // "long" or "short"
  "type": "market",            // "market" or "limit"
  "limitPx": null,             // required for "limit"
  "sizeUsd": 10000,            // at least 10
  "leverage": 5,               // capped at the market's limit and 20
  "tpPx": 104000,              // optional
  "slPx": 98500,               // optional
  "strategy": "Breakout",      // one of the seven strategy tags
  "rationale": "Broke the morning high on volume."   // optional, up to 1,000 characters
}

Response

{
  "position": { /* the new position, for a fill */ },
  "order": { /* the resting order, for a limit that didn't fill */ },
  "cash": 99995.5,
  "fill": { "px": 100000, "at": 1763384741880 },     // the price met, and Hyperliquid's time for it
  "timing": { "priceMs": 84, "serverMs": 131 }
}

POST/api/sim/positions/{id}/closeSigned in

Closes a position at the market. Body { "coin": "BTC" } is optional and only lets the price fetch start sooner. If the position had already hit a trigger, it closes there and triggered is true.

{ "trade": { /* the closed trade */ }, "cash": 100190.91, "triggered": false, "timing": { "priceMs": 79, "serverMs": 122 } }

POST/api/sim/positions/{id}/tpslSigned in

Sets or clears take profit and stop loss. Body { "tpPx": 104000, "slPx": null }; null or an empty string clears a level. Checked against the current price. Returns { "position": { ... } }.

POST/api/sim/orders/{id}/cancelSigned in

Cancels a resting limit order. Returns { "order": { ... } }, or 404 if it already filled.

POST/api/sim/resetSigned in

Archives the active account and starts a new one at $100,000. Returns { "ok": true }.

Account and sharing

GET/api/mePublic

Who is signed in, if anyone, their sharing choices, and which sign-in methods this server offers.

{
  "user": {
    "login": "octocat", "name": "The Octocat", "avatarUrl": "https://...",
    "sharing": {
      "agentId": "KIN001", "decided": true, "publishData": true,
      "showLogin": false, "publishRationale": false,
      "repo": "KinfieldLabs/kinfield-datasets"
    }
  },
  "signIn": { "available": true, "github": true, "dev": false }
}

POST/api/me/sharingSigned in

Updates any of publishData, showLogin and publishRationale (booleans); fields left out are unchanged. Returns { "ok": true }.

POST/api/me/deleteSigned in

Deletes the account. The body must repeat your GitHub username: { "confirm": "octocat" }. See Deleting your account.

GET/api/auth/githubPublic

Starts GitHub sign-in and returns you to /simulate. POST /api/auth/logout signs out.

Agent

GET/api/agent/evaluationSigned in

Everything on the /agent page:

  • agentId, publishing and datasetRepo;
  • accounts: every account, newest first, each with stats, readiness (its checks, passed, total, ready and day), equity points and its ledger length and head;
  • autonomous: teaching progress, status, model (samples, accuracy, trained at), last run and note, the trading rules, its account's evaluation, and its open and recent trades.

POST/api/agent/controlSigned in

Pauses or resumes the agent trading on its own: { "paused": true }.

Public

POST/api/hlPublic, 120 a minute per address

A read-only proxy to Hyperliquid's info endpoint, used for guest mode and charts. Only the request types allMids, candleSnapshot and metaAndAssetCtxs are allowed, with the same body Hyperliquid expects:

{ "type": "candleSnapshot", "req": { "coin": "BTC", "interval": "1m", "startTime": 1763380000000, "endTime": 1763384741880 } }

GET/api/healthPublic

The server's region and its round-trip time in milliseconds to its database and to Hyperliquid, measured at most every 15 seconds.

{ "region": "iad1", "dbMs": [1.9, 1.2, 1.1], "hyperliquidMs": [86.4, 81.0] }

Rate limits

LimitApplies to
20 writes in 10 secondsEach signed-in person, across all write endpoints
30 new trades a minute, 1,000 a dayEach account's orders; closes are never blocked
10 resets a dayEach person
120 requests a minute/api/hl, per IP address

Scheduled jobs

/api/cron/agents (every 15 minutes) and /api/cron/publish (03:00 UTC) are called by the host's scheduler with a secret bearer token, and refuse anything else. See Run Kinfield yourself.