API Documentation
Reference for every REST endpoint the platform exposes
Public Catalog API
Read-only, no authentication required.
GET /api/exchanges
Every exchange registered on the platform (e.g. Kraken, Binance, Bitvavo, Trade Republic). No parameters.
GET /api/exchange/{id}/assets
Every market listing (asset/pair) on the given exchange.
GET /api/assets
All assets, optionally filtered:
asset_class(crypto, stock, etf)enabled(1 / 0)search(name, code, or ISIN)
GET /api/asset/{id}
A single asset's full record.
GET /api/options
Option/specification definitions (e.g. period codes), optionally filtered:
idparent(parent category id)search(name, code, or description)
GET /api/option/{id}
A single option/specification record.
GET /api/markets/{id}/history
Full raw price-tick history for a market listing, exported from InfluxDB (mainly used to seed a development environment with real data).
Portfolio API
Requires a per-user Bearer token. Every endpoint only ever operates on portfolios the token's owner belongs to.
Authentication
Send the token as a Bearer token on every request:
-H "Authorization: Bearer <token>"
An administrator issues (or rotates) a user's token from the server with artisan remora:issue-api-token user@example.com. The token is shown once at generation time — only its hash is stored, so a lost token must be rotated.
GET /api/portfolios
Every portfolio the token's owner belongs to, with holdings and strategies.
POST /api/portfolios
Creates a portfolio. Requires name, type (real, dry_run, play, watchlist), risk_profile (defensive, conservative, moderate, growth, aggressive), base_currency; optional budget, weekly_deposit, deposit_frequency (weekly/monthly). The creator becomes owner.
GET /api/portfolios/{id}
One portfolio's holdings (with live valuation, P&L, and allocation %), strategies, total NAV, and risk metrics.
PUT /api/portfolios/{id}
Updates core settings (name, budget, deposits, risk profile). Owner only.
DELETE /api/portfolios/{id}
Deletes the portfolio. Owner only.
GET /api/portfolios/{id}/performance
Valuation history points. Optional timeframe (default 1M; e.g. 1D, 1W, 1M, 3M, 1Y, ALL).
GET /api/portfolios/{id}/analytics
TWR/MWR returns, realized/unrealized P&L, Sharpe and Sortino ratios, concentration warnings, projected income, and a BTC benchmark comparison. Optional timeframe.
GET/POST /api/portfolios/{id}/target-allocations
Reads or sets per-asset target allocation percentages. POST requires targets (a map of asset id to percentage, 0-100). Owner or editor.
GET/POST /api/portfolios/{id}/strategies
Reads or sets strategy allocation weights. POST requires allocations (each with a weight 0-100 and optional status: sandbox, active, or paused). Owner only.
GET /api/portfolios/{id}/rebalance-trades
Suggested buy/sell trades to bring the portfolio back to its target allocations.
GET /api/portfolios/{id}/currency-rates
Exchange rate from the portfolio's base currency to another. Requires to (EUR, USD, GBP, BTC, or ETH).
GET /api/portfolios/{id}/markets/performance
Market taxonomy performance breakdown scoped to this portfolio's holdings. Optional period (1d, 1w, 1m, 1y; default 1d).
POST /api/portfolios/{id}/transactions
Logs a BUY, SELL, DEPOSIT, WITHDRAW, DIVIDEND, or STAKING_REWARD. Requires asset_id, type, quantity, price; optional fee. Not available on watchlist portfolios. Owner or editor.
POST /api/portfolios/{id}/holdings/adjust
Sets a holding's quantity and cost basis directly (no cash budget or price involved). Requires asset_id, quantity; cost_basis required unless quantity is 0 (which removes the holding). Owner or editor.
GET/POST /api/portfolios/{id}/logs
Reads (paginated) or posts a logbook entry. POST requires author, category, message; optional payload. Posting is owner or editor.
DELETE /api/portfolios/{id}/logs/{logId}
Deletes a logbook entry. The owner can delete any entry; an editor can only delete their own.
POST /api/portfolios/{id}/share
Grants another user access. Requires email (an existing user) and role (editor or viewer). Owner only.
POST /api/portfolios/{id}/copy
Duplicates a portfolio with its holdings, target allocations, and strategy weights into a new portfolio with an isolated ledger. Optional parameters: name, type (real, dry_run, play, watchlist), ai_access_level, managed_by, copy_holdings, copy_target_allocations, copy_strategies, copy_budget. Owner only. (Note: External agent tokens are read-only and blocked on this endpoint).
Internal Integration Endpoints
Used by internal dashboards and integrations rather than general API consumers. Both require a Bearer token (Authorization: Bearer <token>), issued with php artisan remora:issue-api-token.
GET /api/balancePerMarket
A summary view of every market's balance data.
GET /api/altcoinexchanges/balances
Balance data across all connected exchange accounts.
External AI Agent API & Model Context Protocol (MCP)
Dedicated dual-protocol interface for autonomous AI agents, algorithmic platforms, and LLMs (Claude Desktop, Cursor, OpenAI Agents).
Authenticate using dedicated Agent API tokens issued in User Profile:
Authorization: Bearer remora_agent_...
- read:portfolios - Discovery & positions
- write:remarks - Advisory notes
- manage:portfolios - AI portfolio creation
- write:trades - Trade execution
- private: Hidden from agents (404)
- read_advise: Read & submit advice only
- full_managed: Read, advice & trading
Agent tokens (remora_agent_...) with read:portfolios scope may read portfolio states and analytics on /api/portfolios/*.
/api/portfolios/* with an agent token are strictly rejected with 403 Forbidden. All mutations must be dispatched via /api/agent/*.
When STRATEGY_SUITE_SHARED_SECRET is configured, all requests to /api/agent/* must include two platform security headers:
For GET requests or empty payloads, the canonical string is "{timestamp}.".
REST Endpoints (/api/agent/*)
GET /api/agent/me
Identifies the token owner (user: id, name, email), their subscription (tier, remark frequency, whether AI trading is allowed, max AI portfolios) and the token itself (name, scopes, expires_at, last_used_at). Any valid token, no extra scope. Used by Strategy Suite to link a token to the right client before storing it.
GET /api/agent/portfolios
Lists visible portfolios (read_advise or full_managed) belonging to the token owner. Requires scope read:portfolios.
GET /api/agent/portfolios/{id}
Full portfolio detail with current holdings, valuations, and target allocations. Private portfolios return 404.
POST /api/agent/portfolios/{id}/remarks
Submits periodic advisory remark (write:remarks scope). Payload: period, title, content, sentiment (bullish, bearish, neutral, cautious), optional recommendations array. Automatically mirrors to Logbook.
POST /api/agent/portfolios
Creates an autonomous AI-managed portfolio (manage:portfolios scope). Governed by user subscription tier (Pro: up to 3, Premium: up to 10).
POST /api/agent/portfolios/{id}/transactions
Executes a BUY or SELL trade on a full_managed portfolio (write:trades scope). Payload: asset_id, type, quantity, price, fee.
POST /api/agent/portfolios/{id}/holdings/adjust
Directly adjusts an asset holding position on an AI-managed portfolio (write:trades scope). Payload: asset_id, quantity, cost_basis.
Model Context Protocol (MCP) Interface
Remora exposes standard JSON-RPC 2.0 MCP tools: list_portfolios, get_portfolio_details, add_portfolio_remark, create_managed_portfolio, execute_trade, and adjust_holding.
Forward JSON-RPC 2.0 requests with Bearer token (and HMAC headers when configured):
Authorization: Bearer remora_agent_...
X-Strategy-Suite-Timestamp: 1715000000
X-Strategy-Suite-Signature: <hmac-sha256-hex>
{
"mcpServers": {
"remora": {
"command": "php",
"args": ["artisan", "remora:mcp-server", "--token=remora_agent_..."]
}
}
}