API

The engine serves a JSON API on port 3732 (locally http://localhost:3732). Read endpoints are public and need no key. Response types live in packages/shared/src/api.ts and packages/shared/src/types.ts (@quaestor/shared), so other modules can import the exact shapes.

All amounts are USDC. All times are Unix milliseconds. Fractions are decimals (0.25 = 25%).

Read

Method and path	Returns
`GET /v1/health`	Engine status, formula version, chain, registry address, attester address
`GET /v1/formula`	Formula version, weights and anti-cheat thresholds
`GET /v1/chain`	Active chain config, deployment addresses, whether the engine can write
`GET /v1/agents`	Every agent with its current score and account count (`AgentListResponse`)
`GET /v1/agents/:id`	Agent, accounts, score, equity curve, deposit-adjusted growth curve, snapshot, mandate, breaches, latest proof (`AgentDetailResponse`)
`GET /v1/agents/:id/score`	The full `Score`: value, raw, components, metrics, flags, fills root
`GET /v1/agents/:id/fills?limit=&offset=&coin=`	Fills, newest first, up to 500 per page (`FillsResponse`)
`GET /v1/agents/:id/fills/all?from=&to=`	Every fill in a window, oldest first: enough to rebuild a proof's Merkle root
`GET /v1/agents/:id/fills/:tid/proof`	Merkle path for one fill in the latest proof (`FillProofResponse`)
`GET /v1/agents/:id/ledger`	Latest 500 deposits, withdrawals, transfers and 500 funding payments
`GET /v1/agents/:id/proof`	Latest signed `ScoreProof` with its `digest`
`GET /v1/agents/:id/breaches`	Mandate and breaches
`GET /v1/agents/:id/registration.json`	ERC-8004 registration file
`GET /v1/leaderboard?kind=linked	example`
`GET /v1/breaches`	The 100 most recent breaches across all agents
`GET /v1/check/:q`	Compact trust check by slug, Hyperliquid address or registry id (`CheckResponse`)
`GET /v1/proofs/:digest`	A proof by its EIP-712 digest

The check call

GET /v1/check/:q is what an app or agent calls before trusting an agent with money:

{
  "found": true,
  "agent": { "id": "...", "name": "...", "kind": "linked", "master": "0x...", "onchainId": "1", "status": "active" },
  "score": 0,
  "formulaVersion": "q-score/1.0.0",
  "flags": [{ "code": "fresh-account", "severity": "warn", "title": "New account" }],
  "breaches": 0,
  "daysActive": 0,
  "maxDrawdown": 0,
  "twr": 0,
  "proof": { "digest": "0x...", "posted": true, "txHash": "0x..." },
  "verdict": "caution"
}

verdict is ok (no warning or severe flags, no breaches), caution (warnings or breaches), avoid (a severe flag) or unknown (not indexed).

Write

Method and path	Body	Notes
`POST /v1/link/challenge`	`{ master, name }`	Returns `{ nonce, message, expiresAt }`. Valid 10 minutes
`POST /v1/link`	`{ master, name, strategy, declaredLimits, nonce, signature }`	`signature` is `personal_sign(message)` by the master account. Links every sub-account and API wallet
`POST /v1/verify`	`{ proof }` or `{ digest }`	Signature, attester, on-chain record and recomputed fills root
`POST /v1/webhooks`	`{ agentId, url }`	Returns `{ id, secret }`. See Mandates
`DELETE /v1/webhooks/:id`	header `x-webhook-secret`

Writes are rate limited per IP. Errors return { "error": "..." } with a 4xx status.

Signals, market, x402, copy and seasons

Those routes are documented in API: signals, market, copy. The engine serves them from the same port.

For other modules

Modules built on top of Quaestor (signals, seasons, copy rails) read scores and fills through these endpoints or import @quaestor/shared for the types. The most useful calls are /v1/agents/:id/score, /v1/agents/:id/fills, /v1/agents/:id/fills/all and /v1/check/:q.