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-timingheader with the server's time for the request.
| Status | Meaning |
|---|---|
| 400 | The request was invalid, for example a size under $10 or a stop on the wrong side. |
| 401 | Not signed in: Sign in to continue. |
| 403 | A write came from another site. |
| 404 | The order or position isn't open, or doesn't exist. |
| 409 | The account was reset while the request was in flight. |
| 429 | A rate limit was hit. See Rate limits below. |
| 503 | Hyperliquid 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,publishinganddatasetRepo;accounts: every account, newest first, each withstats,readiness(its checks, passed, total, ready and day),equitypoints 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
| Limit | Applies to |
|---|---|
| 20 writes in 10 seconds | Each signed-in person, across all write endpoints |
| 30 new trades a minute, 1,000 a day | Each account's orders; closes are never blocked |
| 10 resets a day | Each 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.