Reference

API Reference

Build against Alphonce with an API token from your account. Portfolio, trading, strategies, and research are reached through MCP over HTTP.

Authentication

Client integrations use an Alphonce API token. Create one in Settings → Connected accounts. It is shown once. Send it as Authorization: Bearer aph_… or ?apikey=. Included from Chui (Premium) upwards.

curl http://localhost:3000/api/mcp \
  -H "Authorization: Bearer aph_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-client","version":"1"}}}'

For apps that sign users in, prefer OAuth instead of embedding a long-lived personal token.

Base URL

http://localhost:3000/api

All client paths below hang off this host. There is no separate api.alphonce.io gateway.

Capabilities

What your token can do is expressed as MCP tools — not as a pile of REST resources. Full names and scopes: MCP Server.

Area	Server	Example tools
Portfolio	Trading MCP	GET_PORTFOLIO_SUMMARY, GET_HOLDINGS, GET_EXCHANGE_CONNECTIONS
Trading	Trading MCP	PLACE_ORDER, CANCEL_ORDER, GET_ORDERS (needs trades:execute)
Strategies & bots	Trading MCP	GET_STRATEGIES, CONTROL_STRATEGY, GET_BOT_STATUS
Rebalancing	Trading MCP	GENERATE_REBALANCE_PLAN, EXECUTE_REBALANCE_PLAN
Research & backtests	Research MCP	research_ticker, scan_market, run_simulation

Discovery

Public endpoints — no token required. Handy for health checks and importing the spec.

Platform statusChecking…/api/status

MCP manifestChecking…/api/mcp/manifest.json

Method	Path	Auth	Summary
GET	/api/status	Public	System status
GET	/api/openapi	Public	OpenAPI document
GET	/api/mcp/manifest.json	Public	MCP server manifest

GET/api/statusPublic

System status. Public availability for Alphonce platform, AI, and connected services.

curl http://localhost:3000/api/status

GET/api/openapiPublic

OpenAPI document. Machine-readable OpenAPI 3.1 for this client API.

curl http://localhost:3000/api/openapi

GET/api/mcp/manifest.jsonPublic

MCP server manifest. Discovery metadata for the Trading and Research MCP servers (endpoints, scopes, tool names).

curl http://localhost:3000/api/mcp/manifest.json

MCP

The main client surface. Trading and Research are separate MCP servers on the same auth. Tool catalogue: MCP Server.

Method	Path	Auth	Summary
POST	/api/mcp	Bearer aph_* or ?apikey= (Chui / Premium+)	Trading MCP
GET	/api/mcp	Bearer aph_* or ?apikey= (Chui / Premium+)	Trading MCP (SSE)
DELETE	/api/mcp	Bearer aph_* or ?apikey= (Chui / Premium+)	Close Trading MCP session
POST	/api/mcp/research	Bearer aph_* or ?apikey= (Chui / Premium+)	Research MCP
GET	/api/mcp/oauth/authorize	Browser / OAuth client	OAuth authorize
POST	/api/mcp/oauth/token	OAuth client credentials	OAuth token exchange

POST/api/mcpBearer aph_* or ?apikey= (Chui / Premium+)

Trading MCP. Streamable HTTP MCP for portfolio, strategies, bots, rebalancing, and trading. Use an Alphonce API token from Settings → Connected accounts.

curl http://localhost:3000/api/mcp \
  -H "Authorization: Bearer aph_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-client","version":"1"}}}'

GET/api/mcpBearer aph_* or ?apikey= (Chui / Premium+)

Trading MCP (SSE). Same server over GET / SSE once a session exists.

curl "http://localhost:3000/api/mcp" \
  -H "Authorization: Bearer aph_YOUR_TOKEN" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID"

DELETE/api/mcpBearer aph_* or ?apikey= (Chui / Premium+)

Close Trading MCP session. End a streamable HTTP session.

curl -X DELETE "http://localhost:3000/api/mcp" \
  -H "Authorization: Bearer aph_YOUR_TOKEN" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID"

POST/api/mcp/researchBearer aph_* or ?apikey= (Chui / Premium+)

Research MCP. Streamable HTTP MCP for ticker research, market scan, batch research, and backtests. Same token as Trading MCP.

curl http://localhost:3000/api/mcp/research \
  -H "Authorization: Bearer aph_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

GET/api/mcp/oauth/authorizeBrowser / OAuth client

OAuth authorize. OAuth 2.0 authorization code + PKCE for third-party apps. Prefer this over embedding long-lived tokens in your product.

open "http://localhost:3000/api/mcp/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https://your.app/callback&scope=portfolio:read&state=…&code_challenge=…&code_challenge_method=S256"

POST/api/mcp/oauth/tokenOAuth client credentials

OAuth token exchange. Exchange an authorization code (or refresh) for an access token.

curl -X POST http://localhost:3000/api/mcp/oauth/token \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=https://your.app/callback" \
  -d "code_verifier=…"

Limits

MCP requires Chui (Premium) or higher. Metered calls also enforce per-plan requests per minute. How Compute Units are spent is covered in Compute Units.

Plan	Requests / minute
Free	20
Plus	60
Premium	150
Pro	300
Team	1,000
Enterprise	1,000

OpenAPI

Machine-readable description of this client surface — import into Postman, Insomnia, or your SDK generator:

curl http://localhost:3000/api/openapi -o alphonce.openapi.json

Open /api/openapi

Start with MCP

Wire Claude, Cursor, or Gemini using the MCP guide. Same Alphonce token, no extra REST surface to maintain.