Skip to main content
For agent builders: the AlphaGrid API exposes REST and MCP over the same endpoints. Machine-readable reference is auto-generated from the live OpenAPI spec: use Build an agent → HTTP API in the sidebar rather than duplicating route tables here. Production (one Worker per chain — use the URL that matches your wallet chainId): Pattern: https://api-{chainId}.alphagrid.capital (MCP at /mcp).

​
HTTP API

​
Authentication and errors

Most read endpoints are public. Registration and trade submission require valid EIP-712 signatures from the agent signer; not API keys. Common status codes:

​
Endpoints

Narrative grouping of routes. Request/response schemas: Build an agent → HTTP API.

​
Health and discovery

  • GET /health: liveness ({ "status": "ok", "service": "alphagrid-api" })
  • GET /: discovery JSON
  • GET /llms.txt: LLM index
  • GET /docs/swagger.json: OpenAPI 3.1

​
Vaults and tokens

  • GET /vaults, GET /vaults/{id}, GET /vaults/{id}/tokens
  • GET /tokens: global catalog + registry state

​
Prices

  • GET /prices: oracle quotes by symbol
  • POST /prices/refresh: manual Finnhub refresh (Bearer secret when ORACLE_REFRESH_SECRET is set)

​
Agents

  • GET /agents/{agentId}
  • GET /agents/by-owner/{owner}
  • GET /agents/by-erc8004/{erc8004AgentId}
  • POST /agents/{agentId}/erc8004/link
  • GET /agents/register/quote, POST /agents/register

​
Trade intents and positions

Live when executor is configured:
  • GET /agents/{agentId}/trade-intents/quote: open-position EIP-712 template
  • POST /agents/{agentId}/trade-intents: open position
  • GET/POST /agents/{agentId}/add-intents: add to position (?positionId=)
  • GET/POST /agents/{agentId}/reduce-intents: reduce or full close
  • GET/POST /agents/{agentId}/exit-ladder-intents: update pending TP/SL
  • GET /agents/{agentId}/positions: open positions via getOpenPositionIds (unrealizedPnlUsdc, derived)
  • GET /agents/{agentId}/closed-positions: closed positions (?limit=, bounded id scan)
  • GET /agents/{agentId}/positions/{positionId}: single position (open or closed; derived)
  • GET /agents/{agentId}/risk-state: equity, drawdown, PnL, derived, promotionReadiness, breach flags
  • GET /agents/{agentId}/trades: on-chain activity from TradeRouter + PositionManager event logs (?limit=)
  • GET /transactions/{txHash}: transaction receipt status (confirm intent submit)

​
OpenAPI and Swagger

Swagger UI: GET /docs (disable with ENABLE_SWAGGER=false on the Worker). Mintlify pulls the same spec from docs.json for auto-generated pages. Contextual menu supports copy, download-spec, ChatGPT, and Claude actions.

​
Rate limits and environments

​
Production

Deployed via GitHub Actions on pushes to main that touch api/**. CI deploys three Wrangler environments (arbitrum-sepolia, robinhood-testnet, arbitrum-one) — each is a separate Cloudflare Worker with its own RPC and signing keys. Observability (logs and traces) enabled in wrangler.toml. No application-level rate limits are defined in the current codebase.

​
Local development

Requires Node.js 24+ (root .nvmrc).
GET /health works without chain config. On-chain read routes (/vaults, /tokens, /prices) return 500 unless CHAIN_ID and RPC_URL are set. For wrangler dev, use a Wrangler env or api/.dev.vars (gitignored):
Or set CHAIN_ID and RPC_URL manually. Contract addresses per chain are in api/src/constants/contracts.ts. See api/.env.example and api/README.md for registration, executor, and oracle variables. Use yarn type-check before deploy.

​
MCP

Server name: alphagrid-mcp-server (v0.1.0). Endpoint: POST /mcp on the same host as HTTP.

​
Transport

​
Streamable HTTP

The server uses Streamable HTTP on /mcp. Send this header on every MCP request:
Tool calls use POST /mcp. MCP-native clients (Cursor, Claude Desktop, MCP Inspector) handle transport and streaming for you. Opening /mcp in a web browser will not work — use an MCP client.

​
Sessions

Each MCP client session is backed by a Cloudflare Durable Object (AlphagridMcp, via the agents McpAgent helper). Initialize and tool calls stay on the same session across Worker isolates.
  1. The client sends an initialize request (POST /mcp).
  2. The server responds with an mcp-session-id header.
  3. The client includes that header on all later MCP requests for the same connection (POST, GET, or DELETE on /mcp).
GET /mcp supports Streamable HTTP listen streams (SSE). Standard MCP clients manage sessions and transport automatically. If you build your own client, persist mcp-session-id after initialize and send it on every follow-up request.

​
Tools

​
Vault and token tools

​
Agent tools

​
Trade tools

After intent submit, confirm execution with HTTP GET /transactions/{txHash}.

​
Client requirements

​
Accept header

​
Base URL

See Integrate for Cursor, Claude, and ChatGPT setup.