REST API and OpenAPI

Call every Papertrade AI tool over plain HTTPS. Free public endpoints for Papertrade markets, charts, liquidation maps, leaderboards and wallet analytics, with an OpenAPI 3.1 document for GPT Actions and agent frameworks.

Every MCP tool is also an HTTPS endpoint, for agent frameworks, GPT Actions, bots, dashboards and scripts that do not speak MCP.

• Base URL: https://papertrade-ai.ninabrekkerese.workers.dev
• OpenAPI 3.1: /openapi.json (also at /.well-known/openapi.json)
• CORS: open (Access-Control-Allow-Origin: *) on all public endpoints

Public tools (no auth)#

GET  /api/v1/tools                  list tools with descriptions and annotations
GET  /api/v1/tools/{name}?arg=value query-string arguments (numbers and booleans are coerced)
POST /api/v1/tools/{name}           JSON body arguments

Examples:

curl https://papertrade-ai.ninabrekkerese.workers.dev/api/v1/tools/get_markets

curl "https://papertrade-ai.ninabrekkerese.workers.dev/api/v1/tools/get_price_chart?market=ETH&interval=1h"

curl -X POST https://papertrade-ai.ninabrekkerese.workers.dev/api/v1/tools/calculate_position \
  -H 'content-type: application/json' \
  -d '{"market":"BTC","side":"long","entryPrice":83000,"marginUsd":20,"leverage":500,"exitPrice":83500}'

Response shape#

Success:

{
  "ok": true,
  "summary": "BTC 83023 (0.59% 24h), ... Minimum margin $10.00, minimum position size $10,000.",
  "data": { "markets": [ { "market": "BTC", "markPrice": 83023, "maxLeverage": 1000 } ] }
}

summary is a human-readable sentence the model (or your UI) can show directly. data is structured and stable.

Error:

{ "ok": false, "error": { "code": "wallet_required", "message": "No wallet given and none is connected. ..." } }

Authenticated tools#

With an OAuth access token from the same flow MCP clients use (see the authorization server metadata at /.well-known/oauth-authorization-server):

GET  /api/v1/me                     wallet, mode, canTrade and guardrails for the token
POST /api/v1/me/tools/{name}        any tool, as the connected wallet

curl -X POST https://papertrade-ai.ninabrekkerese.workers.dev/api/v1/me/tools/get_account \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{}'

Trading tools on this path enforce the same guardrails and preview-then-confirm flow as MCP.

Library#

The npm package exports the same tool registry for Node.js:

import { runTool } from 'papertrade-ai';

const res = await runTool('get_liquidation_map', { market: 'ETH' }, {
  principal: {},
  quoteSecret: crypto.randomUUID(),
  connectHint: 'npx papertrade-ai login',
});
console.log(res.summary);

Fair use#

The public endpoints are cached for 5 seconds and proxy Papertrade and Hyperliquid public data. Please poll no faster than once per second; for streaming, use the Papertrade SSE endpoints directly.