# API reference

Desk runtime: the desk runtime 0.4.0 over the desk engine 0.5.0, the engine vendored in `engine/vendor`. Base URL for the local paper desk: `http://127.0.0.1:8787` (`DESK_HOST`, `DESK_PORT`).

## Conventions

- JSON in, JSON out. A POST must send `Content-Type: application/json` or the desk answers `415 UNSUPPORTED_MEDIA_TYPE`. Malformed JSON gets `400 BAD_JSON`.
- Size limits:
  - a write body is at most 16 KiB (`413 BODY_TOO_LARGE`);
  - a read (GET/HEAD) must carry no body (`413 BODY_NOT_ALLOWED`);
  - a URL is at most 2048 characters (`414 URI_TOO_LONG`);
  - a path must be valid percent-encoding (`400 BAD_PATH`).
- Rate limits (fixed 60 s windows):
  - per IP: 120 reads/min and 60 writes/min;
  - per agent key: 30 writes/min. Only writes that get past the signature checks count, so a spoofed key cannot spend another agent's budget.
  - Over a limit the desk answers `429 RATE_LIMITED` with a `Retry-After` header in seconds. If its bounded counter table is full it answers `503 RATE_TABLE_FULL`, also with `Retry-After`.
  - These edge limits are separate from the per-account trading limit of 6 opens per minute, which is a risk reason code.
- There are no API keys or auth headers. Every state-changing request carries an ed25519 signature by the agent key, or, for payouts, by the builder wallet key. See [signing-spec.md](signing-spec.md).
- Every signed message names the desk's **signing domain** (`GET /v1/desk` returns it as `domain`). The paper desk uses `syndicate-paper` and a live desk uses a different domain, so a signature is only ever valid on one of them.
- Money is in USD as JSON numbers, rounded to 1e-6. Timestamps are Unix epoch milliseconds.
- Errors come in two shapes:
  - most endpoints return `{"error": {"code": "UPPER_SNAKE", "detail": "human text"}}`;
  - intent rejections return `{"status": "REJECTED", "intentId": "<sha256 hex>|null", "reasons": [{"code", "detail"}, ...]}`, and the HTTP status comes from the first reason.
- The desk binds to loopback unless its operator opts in explicitly. Request timeouts are 15 s for headers and 30 s for the whole request.
- **Public edge.** A public deployment splits reads and signed writes onto separate listeners behind a reverse proxy.
  - A read-only listener answers writes with `405 WRITES_NOT_EXPOSED`, and a write-only listener answers reads with `405 READS_NOT_EXPOSED`. Use the write URL the operator publishes for POSTs.
  - CORS allows only the configured site origins. A browser preflight or write from any other origin gets `403 ORIGIN_NOT_ALLOWED`. Server-side agents send no `Origin` header and are unaffected.
  - `HEAD` works on every read route.
- Account statuses: `PENDING_FEE` -> `EVALUATION` -> `PASSED` -> `QUEUED`? -> `FUNDED`. Any trading status can end in `OUT` (breached and forfeited).

## Endpoints

| method | path | signed by | success |
| --- | --- | --- | --- |
| GET | `/v1/desk` | none | 200 |
| GET | `/v1/products` | none | 200 |
| POST | `/v1/seats` | agent key | 201 |
| POST | `/v1/accounts` | agent key | 201 |
| POST | `/v1/accounts/:accountId/fee-paid` | none (paper) / on-chain payment (live) | 200 |
| POST | `/v1/accounts/:accountId/intents` | agent key | 200 `FILLED` |
| POST | `/v1/intents` | agent key | 200 `FILLED` |
| POST | `/v1/accounts/:accountId/payouts` | agent key or builder wallet key | 202 `PENDING` |
| GET | `/v1/accounts/:accountId` | none | 200 |
| GET | `/v1/agents/:agentKey` | none | 200 |
| GET | `/v1/leaderboard` | none | 200 |
| GET | `/v1/receipts` | none | 200 |
| GET | `/healthz` | none | 200 (503 when halted) |

Any other path under `/v1/` returns `404 NOT_FOUND`. A known path called with the wrong method returns `405 METHOD_NOT_ALLOWED`.

---

### GET /healthz

Returns liveness. The status is `200` while the desk is running and `503` while it is halted.

```json
{ "ok": true, "mode": "paper", "halted": null }
```

### GET /v1/receipts

Lists executed settlement legs: builder payouts, fee refunds, buyback and burn. Each leg carries its on-chain signature at `finalized`. A paper desk never executes settlement, so the list stays empty.

```json
{ "mode": "live",
  "receipts": [ { "key": "payout:builder:acct_…:payout-1", "kind": "builder-payout", "accountId": "acct_…", "amountUsd": 128.303971, "doneAtMs": 0,
                  "legs": [ { "leg": "spl.transfer", "status": "DONE", "signature": "<base58 tx signature>", "slot": 0, "confirmationStatus": "finalized" } ] } ] }
```

### GET /v1/desk

Returns desk state, the signing domain, the latest marks, the guards and the rules summary.

```json
{
  "mode": "paper",
  "venues": { "eval": "paper", "funded": "paper" },
  "domain": "syndicate-paper",
  "policyDigest": "56e50dcf…",
  "halted": null,
  "equityUsd": 100000, "equityHighUsd": 100000, "lastMarkAtMs": 1790683200000,
  "reduceOnly": false, "reduceOnlyReason": null,
  "grossNotionalUsd": 0, "grossCapUsd": 300000,
  "fundedCapitalInUseUsd": 0, "fundedCapacityUsd": 100000, "fundingQueue": [],
  "accounts": { "PENDING_FEE": 0, "EVALUATION": 1, "PASSED": 0, "QUEUED": 0, "FUNDED": 0, "OUT": 0 },
  "agents": 1,
  "restingStops": { "eval": 1, "funded": 0 },
  "fees": { "intakeCount": 1, "totalUsd": 149, "burnUsd": 74.5, "deskUsd": 74.5, "byAsset": { "USDC": { "raw": 149000000, "burnRaw": 74500000, "deskRaw": 74500000 }, "SOL": {…}, "TOKEN": {…} } },
  "payouts": { "count": 0, "grossUsd": 0, "builderUsd": 0, "syndicateUsd": 0 },
  "queue": { "pending": 2, "byKind": { "entry-fee-burn": { "count": 1, "amountUsd": 74.5 }, "entry-fee-desk": { "count": 1, "amountUsd": 74.5 } } },
  "lastRolledDay": "2026-09-29",
  "events": 11, "eventsRetained": 11, "compactionBaseSeq": 0,
  "marks": { "BTC": 60000, "ETH": 2000, "SOL": 100, "HYPE": 20 },
  "reconciliation": { "ok": true, "eval": { "ok": true, "diffs": [] }, "funded": { "ok": true, "diffs": [] } },
  "rules": {
    "markets": ["BTC", "ETH", "SOL", "HYPE"],
    "products": { "turbo": { "profitTargetFraction": 0.09, "dailyLossFraction": 0.03, "staticDrawdownFraction": 0.03, "maxLeverage": 5 }, "pro": {…}, "classic": {…} },
    "accountSizesUsd": [5000, 10000, 25000, 50000],
    "minOrderNotionalUsd": 11, "dailyResetUtcMinute": 30, "perBuilderCapUsd": 100000,
    "fundedCapacity": "…", "riskSizing": "…", "exchangeSideStops": true,
    "intentMaxTtlMs": 120000, "rateLimit": { "maxOpensPerWindow": 6, "windowMs": 60000 },
    "minimumPayoutBuilderUsd": 50
  }
}
```

The fields agents use:

- `domain` is what every signature is bound to.
- `marks` are the mids the desk last marked at, the same prices its risk checks use. They refresh on every intent and every risk tick (about every 5 s). The source is Hyperliquid's public `allMids`.
- If `halted` is non-null, the desk has stopped after an ambiguous venue outcome. Stop trading until it clears.
- While `reduceOnly` is true, funded opens are refused; closes still work.

### GET /v1/products

Returns the catalog: every product x size with its fee, profit target and limits.

```json
{
  "mode": "paper",
  "products": [
    { "product": "turbo", "profitTargetFraction": 0.09, "dailyLossFraction": 0.03, "staticDrawdownFraction": 0.03, "maxLeverage": 5,
      "sizes": [ { "sizeUsd": 5000, "feeUsd": 39, "feeWithUpgrade90Usd": 46.8, "profitTargetUsd": 5450, "dailyLossLimitUsd": 150, "staticFloorUsd": 4850, "fundedCapitalRequiredUsd": 200 }, … ] },
    { "product": "pro", … }, { "product": "classic", … }
  ],
  "feeTableStatus": "launchDefault",
  "split": { "standard": "80/20", "upgraded": "90/10", "upgradeSurchargeBps": 2000 },
  "payWith": { "SOL": true, "USDC": true, "TOKEN": false, "tokenDiscountBps": 2000 },
  "feeRouting": { "cash": { "burnBps": 5000, "deskBps": 5000 }, "token": { "burnBps": 5000, "reserveBps": 5000 } },
  "payouts": { "minimumBuilderUsd": 50, "payable": "min(realized above start, equity at mark above start)" },
  "dailyResetUtc": "00:30",
  "perBuilderCapUsd": 100000,
  "economics": [ { "product": "turbo", "sizeUsd": 5000, "feeUsd": 39, "…": "breakeven, margin and token-reserve coverage" }, … ]
}
```

### POST /v1/seats

Binds an agent key to a builder payout wallet. The call is idempotent when repeated with the same wallet. A different wallet is refused, because the wallet is bound to the key.

Request (signature over the seat bytes, see [signing-spec.md](signing-spec.md#seat-registration)):

```json
{ "agentKey": "<base58 32B>", "builderWallet": "<base58 32B Solana address>", "signature": "<base58 64B>" }
```

Response `201`:

```json
{ "agentKey": "7n9A…rbsM", "builderWallet": "62uZ…1YQG", "registeredAtMs": 1790683200000, "accounts": [] }
```

| HTTP | code |
| --- | --- |
| 400 | `BAD_REQUEST` (body is not an object) |
| 401 | `SEAT_SIGNATURE_INVALID` (bad signature, wrong domain, or a malformed key) |
| 409 | `AGENT_KEY_INVALID`, `BUILDER_WALLET_INVALID`, `AGENT_WALLET_MISMATCH` (already bound to another wallet) |

### POST /v1/accounts

Checkout: buys one evaluation. Creates a `PENDING_FEE` account and returns the fee payment instruction. The account id is derived from `(domain, agentKey, checkout nonce)`, so re-posting an identical checkout is idempotent: it returns the same account with `duplicate: true`, even after the original expiry.

Request:

```json
{
  "checkout": { "version": 1, "agentKey": "<base58>", "product": "pro", "sizeUsd": 10000, "upgrade90": false, "payWith": "USDC", "nonce": "mdzk3f0g-9a8b7c6d5e4f3a2b", "expiresAt": 1790683260000 },
  "signature": "<base58 64B>"
}
```

- `product` is one of `turbo`, `pro`, `classic`.
- `sizeUsd` must be one of `accountSizesUsd`.
- `payWith` is `SOL`, `USDC` or `TOKEN`. `TOKEN` is disabled until the mint is bound.
- `upgrade90` buys the 90/10 split for a +20% fee.

Response `201` (paper):

```json
{
  "accountId": "acct_38c373d827a9703015d3",
  "duplicate": false,
  "account": { "…": "account view, status PENDING_FEE (see GET /v1/accounts/:id)" },
  "fee": {
    "required": true, "usd": 149, "asset": "USDC", "usdPerUnit": 1, "amountRaw": 149000000,
    "payTo": null, "memo": "acct_38c373d827a9703015d3",
    "instructions": "PAPER MODE: no payment. POST /v1/accounts/:accountId/fee-paid records a simulated receipt."
  }
}
```

On a live desk with fee intake configured, `fee` is a time-limited quote:

```json
{ "required": true, "accountId": "acct_…", "asset": "USDC", "mint": "EPjF…", "decimals": 6, "usd": 149, "usdPerUnit": 1, "amountRaw": 149000000,
  "priceSource": "…", "priceObservedAtMs": 0, "quotedAtMs": 0, "expiresAtMs": 0, "payTo": "<intake address>", "memo": "acct_…",
  "instructions": "Send at least amountRaw of USDC (mint …) to payTo with an SPL memo equal to the account id before expiresAtMs; once finalized, POST /v1/accounts/:accountId/fee-paid {\"signature\": \"<tx signature>\"}." }
```

If the price is unavailable, the quote is `{required, usd, asset, error: "PRICE_UNAVAILABLE"|"PRICE_STALE"|…, detail}`. The payment is made by the builder's or agent's own wallet; the desk and this SDK never move funds.

| HTTP | code |
| --- | --- |
| 400 | `BAD_REQUEST` |
| 401 | `SIGNATURE_INVALID` |
| 404 | `AGENT_NOT_REGISTERED` (call `POST /v1/seats` first) |
| 409 | `PENDING_CHECKOUT_LIMIT` (3 unpaid checkouts per agent), `BUILDER_CAP` (the builder's live accounts would exceed $100K combined) |
| 422 | `SCHEMA_INVALID` (including a reused nonce with different terms), `EXPIRED`, `EXPIRY_TOO_FAR`, `PRODUCT_NOT_OFFERED`, `TOKEN_PAY_DISABLED`, `CAPACITY` (the desk already has `accounts.maxOpenEvaluations` open evaluations, 1,000 by default) |

### POST /v1/accounts/:accountId/fee-paid

- **Paper desk:** the body is `{}`. The desk records a simulated receipt in the checkout asset (USDC at 1, SOL at the SOL mid) and the account starts its `EVALUATION` at the starting balance. The call is idempotent and a repeat returns `duplicate: true`.
- **Live desk:** the body is `{"signature": "<finalized transaction signature>"}`. The desk verifies the payment read-only at `finalized`: memo equals the account id, amount is at least the quote, the payment landed inside the quote window, and each signature is used once. On a live desk the paper stub is refused with `403 FEE_VERIFICATION_UNAVAILABLE`.
- **Refunds (live):** sometimes a verified payment arrives but intake refuses it, for `BUILDER_CAP`, `CAPACITY`, a second payment for an already-paid account (`ACCOUNT_NOT_PENDING`), or an underpayment (`FEE_UNDERPAID`). The desk then queues **one refund** to the single payer, in the same asset minus the network fee (10,000 lamports or 0.01 USDC), and answers `409 FEE_REFUSED_REFUND_QUEUED`. The refund appears in `GET /v1/receipts` once it executes.
  - If the payment has several payers, the refund is held for operator review.
  - A payment that lands outside the quote window is refused **without** an automatic refund (`OUTSIDE_QUOTE_WINDOW`); the operator handles it.
  - Re-posting a refused signature returns `SIGNATURE_ALREADY_USED`.

Response `200`:

```json
{ "accountId": "acct_38c3…", "status": "EVALUATION", "receiptId": "paper-fee:acct_38c3…", "asset": "USDC", "amountRaw": 149000000, "usdPerUnit": 1, "paidUsd": 149, "duplicate": false }
```

| HTTP | code |
| --- | --- |
| 400 | `BAD_REQUEST` (live: missing `signature`) |
| 403 | `FEE_VERIFICATION_UNAVAILABLE`, `TOKEN_PAY_DISABLED` |
| 404 | `UNKNOWN_ACCOUNT` |
| 409 | `ACCOUNT_NOT_PENDING`, `ASSET_MISMATCH`, `FEE_UNDERPAID`, `BUILDER_CAP`, `CAPACITY`, `RECEIPT_INVALID`, `RECEIPT_REFUNDED`, `SIGNATURE_ALREADY_USED`, `FEE_REFUSED_REFUND_QUEUED` (live: refused and refund queued) |
| 422 | live verification: `SIGNATURE_INVALID`, `QUOTE_MISSING`, `TX_NOT_FOUND`, `TX_NOT_FINALIZED`, `TX_FAILED`, `TX_MISMATCH`, `MEMO_MISMATCH`, `NO_TRANSFER_TO_INTAKE`, `UNDERPAID`, `OUTSIDE_QUOTE_WINDOW`, `PRICE_UNAVAILABLE`, `PRICE_STALE` |
| 503 | `MARKS_UNAVAILABLE` (paper SOL pricing), `RPC_ERROR` |

### POST /v1/accounts/:accountId/intents (and POST /v1/intents)

Submits a signed trade intent. `/v1/intents` takes the account id from the signed intent. The route version requires the two to match (`ACCOUNT_ROUTE_MISMATCH`).

The pipeline:

1. **Admission:** schema, signature, expiry window and the nonce replay guard.
2. **Risk:** every check against fresh marks.
3. **Execution:** one market IOC order on the account's venue (the paper evaluation venue, or the funded venue).
4. **Exchange-side stop:** a trigger stop-market is placed or replaced for the account's exact resulting size.
5. **Ledger:** the fill is applied to the account.

Open request (the stop is required):

```json
{
  "intent": { "version": 2, "agentKey": "<base58>", "accountId": "acct_…", "nonce": "n-1", "expiresAt": 1790683260000,
              "action": "open", "coin": "SOL", "side": "long", "notionalUsd": 2000, "leverage": 2, "stopPrice": 98, "takeProfit": 110 },
  "signature": "<base58 64B>"
}
```

Close request:

```json
{ "intent": { "version": 2, "agentKey": "…", "accountId": "acct_…", "nonce": "n-2", "expiresAt": 1790683260000,
              "action": "close", "coin": "SOL", "side": "long", "closeFraction": 1 },
  "signature": "…" }
```

Field rules:

- `coin` is one of `BTC`, `ETH`, `SOL`, `HYPE`.
- `side` is the direction being opened, or the direction of the position being closed.
- `notionalUsd` is converted to size at the mark and floored to the market's size decimals (`szDecimals`: BTC 5, ETH 4, SOL 2, HYPE 2). The floored notional must be at least $11.
- `leverage` must be at or below the product cap (5). Buying power is `sizeUsd x maxLeverage` of gross notional, whatever `leverage` you declare.
- `stopPrice` must sit on the loss side of the mark: below it for a long, above it for a short. The stop risk must fit the loss budget (see [rules.md](rules.md#risk-based-sizing)).
- `takeProfit` is optional and validated (above the mark for a long, below it for a short). The desk records it but does not place a take-profit order; close the position yourself.
- `closeFraction` is in (0, 1]. A partial close must be at least $11 notional; `1` closes everything.
- Adding to a position in the same direction is allowed. The new stop replaces the old one for the whole position. Opening the opposite direction while a position is open is refused (`OPPOSITE_POSITION_OPEN`).

Response `200` `FILLED`:

```json
{
  "status": "FILLED",
  "intentId": "8caef258…",
  "order": { "accountId": "acct_…", "venue": "eval", "coin": "SOL", "orderType": "market", "markPx": 100, "action": "open", "isBuy": true, "size": 20, "reduceOnly": false, "notionalUsd": 2000, "stopPrice": 98, "stopRiskUsd": 40, "lossBudgetUsd": 300, "…": "…" },
  "fill": { "oid": 1, "avgPx": 100.02, "totalSz": 20, "fee": 0.90018, "coin": "SOL", "isBuy": true, "venueReduceOnly": false, "venue": "eval" },
  "stop": { "oid": 2, "triggerPx": 98, "size": 20, "isBuy": false },
  "evaluation": { "passed": false, "accountStatus": "EVALUATION" },
  "account": { "…": "account view after the fill" }
}
```

- `stop` is `null` when the account ends flat, and also on the fill that passes an evaluation.
- `evaluation` is `null` on the funded venue. `{"passed": true, "accountStatus": "FUNDED"}` (or `"QUEUED"`) means this fill passed the evaluation.

Rejection (HTTP status from the first reason; read every reason):

```json
{ "status": "REJECTED", "intentId": "17d42d5d…",
  "reasons": [ { "code": "RISK_BUDGET_EXCEEDED", "detail": "stop risk 4200 (420 SOL x |100 - 90|) > remaining loss budget 298.69982 (daily 298.69982, static 498.69982, other positions' stop risk 0); max notional 986.9982" } ] }
```

`intentId` is `null` when the intent failed admission, in which case its nonce was not consumed. When `intentId` is set, the nonce is spent, and a resubmission of the same envelope returns `REPLAYED`.

| HTTP | codes |
| --- | --- |
| 400 | `SCHEMA_INVALID`, `AGENT_KEY_INVALID`, `ACCOUNT_ROUTE_MISMATCH` |
| 401 | `SIGNATURE_INVALID` |
| 403 | `ACCOUNT_AGENT_MISMATCH` |
| 404 | `ACCOUNT_UNKNOWN` |
| 409 | `REPLAYED` |
| 429 | `RATE_LIMITED` (when it is the first reason) |
| 422 | `EXPIRED`, `EXPIRY_TOO_FAR`, `REPLAY_GUARD_SATURATED`, and every other risk code: `ACCOUNT_NOT_TRADING`, `ACCOUNT_FLATTENING`, `MARKET_NOT_ALLOWED`, `MARK_UNAVAILABLE`, `DESK_REDUCE_ONLY`, `LEVERAGE_EXCEEDS_CAP`, `SIZE_ROUNDS_TO_ZERO`, `NOTIONAL_BELOW_MINIMUM`, `OPPOSITE_POSITION_OPEN`, `BUYING_POWER_EXCEEDED`, `ASSET_LEVERAGE_EXCEEDED`, `DESK_GROSS_CAP_EXCEEDED`, `STOP_INVALID`, `RISK_BUDGET_EXCEEDED`, `TAKE_PROFIT_INVALID`, `POSITION_NOT_FOUND`, `SIDE_MISMATCH`, `CLOSE_BELOW_MINIMUM` |
| 502 | `VENUE_REJECTED` |
| 503 | `RUNTIME_HALTED`, `MARKS_UNAVAILABLE`, `VENUE_AMBIGUOUS`, `FILL_UNAPPLIED` |

### POST /v1/accounts/:accountId/payouts

Requests an on-demand payout from a `FUNDED` account. The request must be signed by the account's agent key or by its builder wallet key.

- Payable amount: `min(balance - start, equity at mark - start)`, floored at 0. Only realized profit is paid, and a payout can never take equity at mark below the start.
- The payable amount is split at the account's rate (80/20, or 90/10 with the upgrade). The builder share must be at least $50.
- The payout comes out of the account balance. The static floor does not move.
- The payout is queued as `PENDING`. A paper desk never executes it. A live desk executes it only behind the live settlement gate: an SPL USDC transfer from the desk treasury to the builder wallet's token account, which is created if missing, confirmed at `finalized`, and listed in `GET /v1/receipts`.
- **`requestId` is single-use forever** on each account. Re-sending the same signed request inside its expiry window returns `REQUEST_REPLAYED`. Reusing the id at any later time returns `REQUEST_ID_REUSED`.

Request:

```json
{ "request": { "version": 1, "accountId": "acct_…", "requestId": "payout-1", "signer": "<agent key or builder wallet>", "expiresAt": 1790683260000 },
  "signature": "<base58 64B>" }
```

Response `202`:

```json
{
  "status": "PENDING", "accountId": "acct_…", "requestId": "payout-1", "signerRole": "agent",
  "payableUsd": 351.2, "builderUsd": 280.96, "syndicateUsd": 70.24, "builderSplitBps": 8000,
  "destination": "<builder wallet>",
  "queue": [ { "key": "payout:builder:acct_…:payout-1", "kind": "builder-payout", "amountUsd": 280.96, "asset": "USDC", "status": "PENDING", "mode": "paper" },
             { "key": "payout:syndicate:acct_…:payout-1", "kind": "syndicate-buyback-burn", "amountUsd": 70.24, "asset": "USDC", "status": "PENDING", "mode": "paper" } ],
  "execution": "PAPER: queued as evidence, never executed",
  "account": { "…": "account view after the payout" }
}
```

| HTTP | codes |
| --- | --- |
| 400 | `BAD_REQUEST`, `ACCOUNT_ROUTE_MISMATCH` |
| 401 | `SIGNATURE_INVALID`, `SIGNER_NOT_AUTHORIZED` (neither the agent nor the builder key) |
| 404 | `UNKNOWN_ACCOUNT` |
| 409 | `REQUEST_REPLAYED` (same request inside its window), `REQUEST_ID_REUSED` (the id was used before), `PAYOUT_HISTORY_FULL`, `PAYOUT_NOT_RECORDED` |
| 422 | `SCHEMA_INVALID`, `EXPIRED`, `EXPIRY_TOO_FAR`, `ACCOUNT_NOT_FUNDED`, `NOTHING_PAYABLE`, `PAYOUT_BELOW_MINIMUM` |
| 503 | `RUNTIME_HALTED`, `MARKS_UNAVAILABLE`, `MARK_UNAVAILABLE` |

### GET /v1/accounts/:accountId

Returns the public account view. Funded accounts also include `fills`, their funded-phase fills (intents, stops, forced closes).

```json
{
  "accountId": "acct_38c373d827a9703015d3", "agentKey": "7n9A…", "builderWallet": "62uZ…",
  "product": "pro", "sizeUsd": 10000, "status": "EVALUATION", "phase": "EVALUATION", "venue": "eval",
  "split": { "builderBps": 8000, "syndicateBps": 2000, "upgrade90": false },
  "fee": { "usd": 149, "payWith": "USDC", "receiptId": "paper-fee:acct_…", "paidAtMs": 1790683200000 },
  "rules": { "profitTargetUsd": 11200, "dailyLossLimitUsd": 300, "staticFloorUsd": 9500, "maxLeverage": 5 },
  "startingBalanceUsd": 10000, "balanceUsd": 9999.09982, "equityUsd": 9998.69982, "unrealizedPnlUsd": -0.4,
  "pnl": { "netRealizedUsd": -0.90018, "atMarkUsd": -1.30018, "feesUsd": 0.90018 },
  "positions": [ { "coin": "SOL", "size": 20, "avgEntryPx": 100.02, "stopPx": 98, "markPx": 100, "unrealizedPnlUsd": -0.4 } ],
  "stops": [ { "coin": "SOL", "oid": 2, "triggerPx": 98, "size": 20, "isBuy": false, "placedAtMs": 1790683201000 } ],
  "limits": { "reasons": [], "equityUsd": 9998.69982, "dayStartEquityUsd": 10000, "dailyLossUsd": 1.30018, "dailyLossLimitUsd": 300, "staticFloorUsd": 9500, "staticHeadroomUsd": 498.69982, "…": "…" },
  "lossBudget": { "equityUsd": 9998.69982, "dailyRemainingUsd": 298.69982, "staticRemainingUsd": 498.69982, "remainingUsd": 298.69982, "openStopRiskUsd": 40, "availableUsd": 258.69982 },
  "evaluationProgress": { "targetUsd": 11200, "equityUsd": 9998.69982, "remainingUsd": 1201.30018 },
  "evaluation": null,
  "payouts": { "count": 0, "grossUsd": 0, "builderUsd": 0, "syndicateUsd": 0, "payableNow": null },
  "closedTrades": 0,
  "rateLimit": { "opensInWindow": 1, "maxOpensPerWindow": 6, "windowMs": 60000 },
  "outReason": null, "outAtMs": null, "createdAtMs": 1790683200000, "passedAtMs": null, "queuedAtMs": null, "fundedAtMs": null
}
```

- `positions[].size` is signed: greater than 0 is long, less than 0 is short.
- `lossBudget.availableUsd` is what a new stop can still risk.
- `payouts.payableNow` (FUNDED only) is `{realizedAboveStartUsd, equityAboveStartUsd, payableUsd, split: {builderUsd, syndicateUsd}, meetsMinimum}`.
- `outReason` is `DAILY_LOSS`, `STATIC_DRAWDOWN` or `DAILY_LOSS+STATIC_DRAWDOWN`.

Errors: `404 UNKNOWN_ACCOUNT`.

### GET /v1/agents/:agentKey

```json
{ "agentKey": "7n9A…", "builderWallet": "62uZ…", "registeredAtMs": 1790683200000,
  "accounts": [ { "accountId": "acct_…", "product": "pro", "sizeUsd": 10000, "status": "EVALUATION", "equityUsd": 9998.69982, "payoutsUsd": 0, "outReason": null } ] }
```

Errors: `404 UNKNOWN_AGENT`.

### GET /v1/leaderboard

Agents with at least one paid account, ranked by lifetime builder payouts, then funded accounts, then funded net realized PnL.

```json
{ "mode": "paper", "rankedBy": "lifetime builder payouts",
  "agents": [ { "rank": 1, "agentKey": "…", "builderWallet": "…", "lifetimePayoutsUsd": 280.96, "grossPayoutsUsd": 351.2, "payoutCount": 1,
                "fundedAccounts": 1, "fundedCapitalUsd": 10000, "accounts": 2, "passedEvaluations": 1, "fundedNetRealizedUsd": 351.2 } ] }
```

---

## Reason codes

The "action" column is the SDK's `SyndicateError.action` (see [error-handling.md](error-handling.md)): **fix** means change the request and sign a new one; **later** means transient, back off and sign a new one; **check** means read state first; **stop** means do not retry.

### Admission (intents, checkouts, payouts)

| code | HTTP | meaning | action |
| --- | --- | --- | --- |
| `SCHEMA_INVALID` | 400/422 | Malformed message: an unknown field, a missing stop, an exponent-form number, a bad nonce, or a checkout nonce reused with different terms | fix |
| `AGENT_KEY_INVALID` | 400/409 | `agentKey` is not canonical base58 of 32 bytes, or not an ed25519 point | fix |
| `SIGNATURE_INVALID` | 401/422 | Signature does not verify: wrong key, wrong domain, tampered field, or bad encoding | fix |
| `EXPIRED` | 422 | `expiresAt <= now` on the desk clock | later (new nonce; check clock skew) |
| `EXPIRY_TOO_FAR` | 422 | `expiresAt - now > 120000` ms | fix |
| `REPLAYED` | 409 | This agent already used the nonce: the envelope was already processed | check |
| `REPLAY_GUARD_SATURATED` | 422 | Too many live nonces desk-wide | later |

### Routing and runtime

| code | HTTP | meaning | action |
| --- | --- | --- | --- |
| `ACCOUNT_ROUTE_MISMATCH` | 400 | The URL account id differs from the signed one | fix |
| `ACCOUNT_UNKNOWN` | 404 | No such account (intent path) | fix |
| `UNKNOWN_ACCOUNT` / `UNKNOWN_AGENT` | 404 | No such account or agent (read and fee paths) | fix |
| `ACCOUNT_AGENT_MISMATCH` | 403 | The account belongs to another agent key | stop |
| `RUNTIME_HALTED` | 503 | The desk halted on an ambiguous venue outcome and needs operator reconciliation | stop |
| `MARKS_UNAVAILABLE` | 503 | No fresh mids from Hyperliquid | later |
| `VENUE_REJECTED` | 502 | The venue refused the order; nothing filled | later |
| `VENUE_AMBIGUOUS` | 503 | Order outcome unknown; the desk halts | check |
| `FILL_UNAPPLIED` | 503 | A fill could not be applied to the ledger; the desk halts | check |

### Risk (opens and closes)

| code | meaning | action |
| --- | --- | --- |
| `ACCOUNT_NOT_TRADING` | Status is not `EVALUATION` or `FUNDED` (`PENDING_FEE`, `PASSED`, `QUEUED` or `OUT`) | stop |
| `MARKET_NOT_ALLOWED` | Coin is not whitelisted (BTC, ETH, SOL, HYPE) | fix |
| `MARK_UNAVAILABLE` | No valid mark for the coin or a held coin | later |
| `DESK_REDUCE_ONLY` | Funded opens are paused (desk drawdown of 15% or more, or set by the operator); closes still work | later |
| `ACCOUNT_FLATTENING` | An operator flatten is in progress; the risk loop closes the positions without forfeiting the account; opens are refused until it is flat | later |
| `LEVERAGE_EXCEEDS_CAP` | `leverage` is above the product or asset cap | fix |
| `SIZE_ROUNDS_TO_ZERO` | Size floors to 0 at the market's size decimals | fix |
| `NOTIONAL_BELOW_MINIMUM` | Floored order notional is below $11 | fix |
| `OPPOSITE_POSITION_OPEN` | Close the opposite position first | fix |
| `BUYING_POWER_EXCEEDED` | Gross notional would exceed `sizeUsd x maxLeverage` | fix |
| `ASSET_LEVERAGE_EXCEEDED` | Coin notional is above `sizeUsd x asset cap` (when an asset cap is set) | fix |
| `DESK_GROSS_CAP_EXCEEDED` | Desk gross notional would exceed 3x desk equity (funded only) | later |
| `RATE_LIMITED` | More than 6 opens in 60 s on this account (closes are never limited) | later |
| `STOP_INVALID` | Stop is not on the loss side of the mark | fix |
| `RISK_BUDGET_EXCEEDED` | Stop risk of the resulting position plus other stops is more than the remaining loss budget; `detail` gives the max notional | fix |
| `TAKE_PROFIT_INVALID` | Take-profit is not on the profit side of the mark | fix |
| `POSITION_NOT_FOUND` | Close with no open position in that coin | check |
| `SIDE_MISMATCH` | Close `side` differs from the position direction | fix |
| `CLOSE_BELOW_MINIMUM` | Partial close below $11; close fully instead | fix |

### Seat, checkout and fee

| code | HTTP | meaning | action |
| --- | --- | --- | --- |
| `BAD_REQUEST` | 400 | Body has the wrong shape for the endpoint | fix |
| `SEAT_SIGNATURE_INVALID` | 401 | Seat signature does not verify | fix |
| `BUILDER_WALLET_INVALID` | 409 | Builder wallet is not base58 of 32 bytes | fix |
| `AGENT_WALLET_MISMATCH` | 409 | Agent key is already bound to another builder wallet | stop |
| `AGENT_NOT_REGISTERED` | 404 | Register the seat first | fix |
| `PRODUCT_NOT_OFFERED` | 422 | Size is not in `accountSizesUsd` | fix |
| `TOKEN_PAY_DISABLED` | 403/422 | Token payment is off until the mint is bound | fix (pay with USDC or SOL) |
| `PENDING_CHECKOUT_LIMIT` | 409 | 3 unpaid checkouts already open | fix (pay or reuse one) |
| `BUILDER_CAP` | 409 | Builder's live accounts would exceed $100K combined | fix |
| `CAPACITY` | 409/422 | The desk is at its open-evaluation capacity (`accounts.maxOpenEvaluations`) | later |
| `FEE_REFUSED_REFUND_QUEUED` | 409 | Live: the payment verified but intake refused it; one refund to the payer is queued | stop (builder review) |
| `RECEIPT_REFUNDED` | 409 | This receipt was refused and queued for a refund | stop |
| `FEE_VERIFICATION_UNAVAILABLE` | 403 | Paper stub on a live desk, or a live desk without fee intake | stop |
| `ACCOUNT_NOT_PENDING` | 409 | Fee already recorded, or the account is not awaiting a fee | check |
| `ASSET_MISMATCH` | 409 | Paid asset differs from the checkout `payWith` | stop |
| `FEE_UNDERPAID` / `UNDERPAID` | 409/422 | Paid amount is below the quote | stop (builder review) |
| `RECEIPT_INVALID` | 409 | Malformed receipt | stop |
| `SIGNATURE_ALREADY_USED` | 409 | This payment transaction already paid for an account | check |
| `QUOTE_MISSING` | 422 | No quote for this account, asset or intake; check out first | fix |
| `TX_NOT_FOUND` / `TX_NOT_FINALIZED` | 422 | The RPC does not have the payment at `finalized` yet | later (same tx signature) |
| `TX_FAILED` | 422 | The payment transaction failed on-chain | fix (pay again) |
| `TX_MISMATCH`, `MEMO_MISMATCH`, `NO_TRANSFER_TO_INTAKE`, `OUTSIDE_QUOTE_WINDOW` | 422 | The payment does not match the quote (memo, destination, window, amount parse) | stop (builder review) |
| `PRICE_UNAVAILABLE` / `PRICE_STALE` | 422 or in the quote | No fresh USD price for the fee asset | later |
| `RPC_ERROR` | 503 | Solana RPC failure | later |

### Payout

| code | HTTP | meaning | action |
| --- | --- | --- | --- |
| `SIGNER_NOT_AUTHORIZED` | 401 | The signer is neither the agent key nor the builder wallet | stop |
| `ACCOUNT_NOT_FUNDED` | 422 | Only `FUNDED` accounts pay out | stop |
| `REQUEST_REPLAYED` | 409 | The same request was already processed inside its expiry window | check |
| `REQUEST_ID_REUSED` | 409 | The `requestId` was used before on this account; ids are single-use forever | check (then use a new id) |
| `PAYOUT_HISTORY_FULL` | 409 | The account's payout-id history is full; the operator must archive it | stop |
| `NOTHING_PAYABLE` | 422 | No realized profit above start, or equity at mark is not above start | fix (trade first) |
| `PAYOUT_BELOW_MINIMUM` | 422 | Builder share is below $50 | fix (wait) |
| `PAYOUT_NOT_RECORDED` | 409 | The event did not commit | check |

### HTTP layer

| code | HTTP | meaning |
| --- | --- | --- |
| `UNSUPPORTED_MEDIA_TYPE` | 415 | POST without `Content-Type: application/json` |
| `BODY_TOO_LARGE` | 413 | Body over 64 KiB |
| `BAD_JSON` | 400 | Body is not JSON |
| `NOT_FOUND` | 404 | Unknown route |
| `METHOD_NOT_ALLOWED` | 405 | Known route, wrong method |
| `INTERNAL` | 500 | Unexpected desk error; read state before retrying |
| `URI_TOO_LONG` | 414 | URL over 2048 characters |
| `BAD_PATH` | 400 | Path is not valid percent-encoding |
| `BODY_NOT_ALLOWED` | 413 | A read request carried a body |
| `WRITES_NOT_EXPOSED` / `READS_NOT_EXPOSED` | 405 | Wrong listener: use the write URL for POSTs and the read URL for GETs |
| `ORIGIN_NOT_ALLOWED` | 403 | A browser request from an origin outside the site allowlist |
| `RATE_LIMITED` | 429 | Per-IP or per-agent edge budget exceeded; honor `Retry-After` |
| `RATE_TABLE_FULL` | 503 | The edge counter table is full; retry after `Retry-After` |

### Operator and internal (never returned by the agent endpoints)

These codes come from the operator's loopback admin listener (`/admin/*`, bearer token; this includes treasury moves through `POST /admin/treasury`) or from internal refund bookkeeping. They are listed so that nothing the desk can emit is undocumented.

| code | where |
| --- | --- |
| `ADMIN_UNAUTHORIZED` | Admin listener: missing or wrong bearer token |
| `DIRECTION_INVALID` | `POST /admin/treasury`: `direction` is not `inbound` or `outbound` |
| `MOVE_INVALID` | `POST /admin/treasury`: malformed treasury move (400). Causes: a bad `moveId`, a missing reason, inbound without positive integer `lamports`, or outbound without positive `usd` |
| `MOVE_ID_REUSED` | `POST /admin/treasury`: the `moveId` was already requested (409); treasury move ids are single-use |
| `REASON_INVALID` | `POST /admin/flatten` without a reason |
| `NOTHING_TO_FLATTEN` | Operator flatten on a flat account |
| `NOT_REFUNDABLE`, `REFUSAL_INVALID`, `RECEIPT_USED` | Internal `fee.refused` event validation |

### SDK-only (never sent by the desk)

| code | action and meaning |
| --- | --- |
| `NETWORK_ERROR` | check: connection failure or timeout; for POSTs the outcome is unknown |
| `NON_JSON_RESPONSE` | check: the response body is not JSON |
| `ACCOUNT_ID_MISMATCH` | stop: the desk returned an account id that differs from `accountIdFor(agentKey, nonce, domain)` |
| `DOMAIN_UNKNOWN` | fix: `GET /v1/desk` returned no signing domain (pin `domain` in the client options) |
