{"openapi":"3.0.3","info":{"title":"Jester Agent API","version":"1.0.0","description":"Headless trading and discovery API for delegated agents and third-party platforms. Agents prefer propose_trade. Platforms use POST /api/v1/orders (no webhook fan-out)."},"servers":[{"url":"https://app.jester.trade"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}}},"paths":{"/api/delegated/whoami":{"get":{"operationId":"whoami","summary":"whoami","description":"Resolve API key to identity. Returns telegramId (use as id in trades) plus legacy compatibility flags. Always call with ?include=summary first.","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"}},"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"include","in":"query","schema":{"type":"string"},"example":"summary"}]}},"/api/delegated/usage":{"get":{"operationId":"get_usage","summary":"get usage","description":"Artifice/agent usage for the current period (API POST quota, tokens, compute, x402). Observe class; GET does not consume the daily POST cap. Same payload as GET /api/v1/usage. Auth: x-api-key or PAYMENT-SIGNATURE (paying wallet needs no key).","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"}},"security":[{"ApiKeyAuth":[]}]}},"/api/delegated/positions":{"get":{"operationId":"get_positions","summary":"get positions","description":"Open positions for the authenticated account (Hyperliquid-first).","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"}},"security":[{"ApiKeyAuth":[]}]}},"/api/delegated/positions/close":{"post":{"operationId":"close_position","summary":"close position","description":"Stage a close (action=close|close_all) then confirm. Unstaged flatten is disabled. POST /api/delegated/propose with action=close|close_all (or d=close + a) then confirm, or pass proposalId here.","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"},"429":{"description":"Daily quota exceeded (agent API POST cap or compute/backtest cap). Retry-After header present."}},"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"example":{"proposalId":"abc123…","action":"close_all"}}}}}},"/api/delegated/pnl/summary":{"get":{"operationId":"pnl_summary","summary":"pnl summary","description":"Portfolio equity, unrealized PnL, and period PnL summary.","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"}},"security":[{"ApiKeyAuth":[]}]}},"/api/delegated/strategies/top-backtests":{"get":{"operationId":"discover_top_backtests","summary":"discover top backtests","description":"Browse top cached backtests (WR%, return, drawdown). Use filter=good|excellent|all. Read-only strategy discovery.","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"}},"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"filter","in":"query","schema":{"type":"string"},"example":"good"},{"name":"includeAll","in":"query","schema":{"type":"string"},"example":"false"}]}},"/api/delegated/strategies/top-live":{"get":{"operationId":"discover_top_live","summary":"discover top live","description":"Browse top strategies by live signal replay. Use with discover_top_backtests for live vs cached comparison.","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"}},"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"windowDays","in":"query","schema":{"type":"string"},"example":"7"},{"name":"limit","in":"query","schema":{"type":"string"},"example":"20"}]}},"/api/delegated/strategies/top-optimized-combos":{"get":{"operationId":"discover_top_optimized_combos","summary":"discover top optimized combos","description":"Browse top Redis optimizer parameter sets across all strategies (flat list with full parameters). Use for tuning/deploy; filter=good|all; default BTC-USD 5m 30d.","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"}},"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"pair","in":"query","schema":{"type":"string"},"example":"BTC-USD"},{"name":"timeframe","in":"query","schema":{"type":"string"},"example":"5m"},{"name":"days","in":"query","schema":{"type":"string"},"example":"30"},{"name":"perStrategy","in":"query","schema":{"type":"string"},"example":"3"},{"name":"limit","in":"query","schema":{"type":"string"},"example":"100"},{"name":"filter","in":"query","schema":{"type":"string"},"example":"good"},{"name":"minReturnPct","in":"query","schema":{"type":"string"},"example":"2.5"},{"name":"minTrades","in":"query","schema":{"type":"string"},"example":"5"}]}},"/api/delegated/strategies/available":{"get":{"operationId":"discover_strategies","summary":"discover strategies","description":"List available strategy catalog entries (id, name, category). Read-only discovery.","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"}},"security":[{"ApiKeyAuth":[]}]}},"/api/delegated/backtests":{"post":{"operationId":"run_backtest","summary":"run backtest","description":"Enqueue an async strategy backtest. Returns jobId and pollUrl — poll get_backtest_job until status=done.","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"},"429":{"description":"Daily quota exceeded (agent API POST cap or compute/backtest cap). Retry-After header present."}},"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"example":{"strategyId":"artifice_v2_56","pair":"BTC-USD","timeframe":"5m","days":30,"parameters":{}}}}}}},"/api/delegated/backtests/{jobId}":{"get":{"operationId":"get_backtest_job","summary":"get backtest job","description":"Poll async backtest job status and results (from run_backtest).","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"}},"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/delegated/propose":{"post":{"operationId":"propose_trade","summary":"propose trade","description":"Preferred trade path: stage a trade for human approval. Returns proposalId — call confirm_trade with the same API key to execute.","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"},"429":{"description":"Daily quota exceeded (agent API POST cap or compute/backtest cap). Retry-After header present."}},"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"example":{"id":"69420000738291","strategy":"Agent","a":"ETHUSDT","d":"long","p":"3500","tp":"3800","sl":"3300","o":"market"}}}}}},"/api/delegated/confirm":{"post":{"operationId":"confirm_trade","summary":"confirm trade","description":"Execute a staged trade or close proposal (from propose_trade). Proposals expire in 5 minutes. Confirm runs in-process (no HTTP loopback).","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"},"429":{"description":"Daily quota exceeded (agent API POST cap or compute/backtest cap). Retry-After header present."}},"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"example":{"proposalId":"abc123…"}}}}}},"/api/v1/trades":{"post":{"operationId":"place_order","summary":"place order","description":"Submit a trade signal immediately (no confirmation). Requires a webhook:alerts or legacy key. mcp:mutate keys must use propose_trade. platform:trade keys use POST /api/v1/orders. Direct account execute always runs; set fanout:false or X-Jester-Fanout: 0 to skip subscriber fan-out.","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"},"429":{"description":"Daily quota exceeded (agent API POST cap or compute/backtest cap). Retry-After header present."}},"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"example":{"id":"69420000738291","strategy":"Agent","a":"BTCUSDT","d":"long","p":"95000","tp":"98000","sl":"93000","o":"market","fanout":false}}}}}},"/api/v1/hyperliquid/builder-fee":{"post":{"operationId":"approve_builder_fee","summary":"approve builder fee","description":"Submit the account wallet signature for ApproveBuilderFee. Body: hyperliquidWallet, nonce from the GET payload, signature (0x hex or {r,s,v}). Do this before POST /api/v1/orders.","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"},"429":{"description":"Daily quota exceeded (agent API POST cap or compute/backtest cap). Retry-After header present."}},"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"example":{"hyperliquidWallet":"0xYourAccount","nonce":1706745600123,"signature":"0x…","signatureChainId":"0x3e7"}}}}}},"/api/v1/orders":{"get":{"operationId":"list_open_orders","summary":"list open orders","description":"List resting orders for the API key account. Query exchange=hyperliquid|propr|all (default all). Hyperliquid rows include oid for platform_cancel_order.","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"}},"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"exchange","in":"query","schema":{"type":"string"},"example":"all"}]}},"/api/v1/positions/close":{"post":{"operationId":"platform_close_position","summary":"platform close position","description":"Close one position immediately (pair or positionId). Flatten (close_all) stays propose → confirm. Optional hyperliquidApiKey + hyperliquidWallet for true headless. Requires platform:trade or legacy. mcp:mutate keys stage close via propose_trade.","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"},"429":{"description":"Daily quota exceeded (agent API POST cap or compute/backtest cap). Retry-After header present."}},"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"example":{"pair":"BTC-USD","percentage":100,"exchange":"hyperliquid"}}}}}},"/api/v1/orders/cancel":{"post":{"operationId":"platform_cancel_order","summary":"platform cancel order","description":"Cancel one or more resting Hyperliquid orders by oid. Optional hyperliquidApiKey + hyperliquidWallet for true headless. Requires platform:trade or legacy.","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"},"429":{"description":"Daily quota exceeded (agent API POST cap or compute/backtest cap). Retry-After header present."}},"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"example":{"oid":123456,"coin":"BTC"}}}}}},"/api/v1/signal-destinations":{"post":{"operationId":"create_signal_destination","summary":"create signal destination","description":"Register an HTTPS URL. Jester POSTs a signed signal JSON when listed strategyIds fire. signingSecret is shown once. strategyIds: [\"artifice_v2_56\"] or [\"*\"].","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"},"429":{"description":"Daily quota exceeded (agent API POST cap or compute/backtest cap). Retry-After header present."}},"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"example":{"url":"https://your-platform.example/jester/signals","strategyIds":["artifice_v2_56"],"directions":["BUY","SELL","CLOSE"],"name":"My exchange"}}}}}},"/api/delegated/logs":{"get":{"operationId":"list_audit_logs","summary":"list audit logs","description":"Recent delegated execute attempts for this API key’s account only (no telegramId override). Returns 503 audit_unavailable if the log store is down.","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"}},"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"string"},"example":"50"}]}},"/api/delegated/tools":{"get":{"operationId":"list_tools","summary":"list tools","description":"Return the live Jester agent tool catalog, OpenAPI URL, and install hints for OpenClaw / Hermes.","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"}},"security":[{"ApiKeyAuth":[]}]}},"/api/delegated/mcp/capabilities":{"get":{"operationId":"list_mcp_capabilities","summary":"list mcp capabilities","description":"Full jester_* MCP tool catalog with JSON schemas (observe/experiment/mutate tiers). Used by the Cursor/Claude stdio bridge. Requires MCP_DELEGATED_ENABLE on the deployment.","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"}},"security":[{"ApiKeyAuth":[]}]}},"/api/delegated/mcp/tool":{"post":{"operationId":"execute_mcp_tool","summary":"execute mcp tool","description":"Execute a single jester_* MCP tool directly (tool-only mode — your own LLM does the reasoning). Mutate tools may return a confirmToken to re-submit in args.","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"},"429":{"description":"Daily quota exceeded (agent API POST cap or compute/backtest cap). Retry-After header present."}},"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"example":{"name":"artifice_portfolio_summary","args":{}}}}}}},"/api/delegated/mcp/chat":{"post":{"operationId":"mcp_agent_chat","summary":"mcp agent chat","description":"Full Jester Agent turn: the server runs its own LLM + jester_* tool loop using the LLM provider key saved in your Jester settings and returns the final reply.","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"},"429":{"description":"Daily quota exceeded (agent API POST cap or compute/backtest cap). Retry-After header present."}},"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"example":{"messages":[{"role":"user","content":"Summarize my open positions and PnL"}]}}}}}},"/api/delegated/mcp/cli":{"post":{"operationId":"mcp_cli","summary":"mcp cli","description":"Deterministic slash-command CLI (no LLM). Use /synapse start <task>, /synapse, /synapse say <message>, /synapse stop, or /help.","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"},"429":{"description":"Daily quota exceeded (agent API POST cap or compute/backtest cap). Retry-After header present."}},"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"example":{"command":"/synapse start Find me a new BTC edge."}}}}}},"/api/terminal/synapse/runs/active":{"get":{"operationId":"synapse_status","summary":"synapse status","description":"Active Synapse run for this account (Prime + spawned agents). Session, x-api-key, or PAYMENT-SIGNATURE.","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"}},"security":[{"ApiKeyAuth":[]}]}},"/api/terminal/synapse/runs":{"post":{"operationId":"synapse_start","summary":"synapse start","description":"Start a Synapse run. Prime begins immediately. Follow up with synapse_message; stop with synapse_stop.","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"},"429":{"description":"Daily quota exceeded (agent API POST cap or compute/backtest cap). Retry-After header present."}},"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"example":{"task":"Find me a new BTC edge."}}}}}},"/api/terminal/synapse/runs/{runId}/message":{"post":{"operationId":"synapse_message","summary":"synapse message","description":"Send a follow-up to Prime on an active Synapse run.","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"},"429":{"description":"Daily quota exceeded (agent API POST cap or compute/backtest cap). Retry-After header present."}},"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"example":{"message":"Ignore strategies requiring options data."}}}}}},"/api/terminal/synapse/runs/{runId}/stop":{"post":{"operationId":"synapse_stop","summary":"synapse stop","description":"Stop a Synapse run. Remnants and artifacts remain.","tags":["Jester Agent"],"responses":{"200":{"description":"Success — check json_summary when present"},"401":{"description":"Invalid or missing x-api-key"},"429":{"description":"Daily quota exceeded (agent API POST cap or compute/backtest cap). Retry-After header present."}},"security":[{"ApiKeyAuth":[]}]}}}}