API Documentation

Reference for every REST endpoint the platform exposes

Base URL: https://remora.nordtribe.eu
API Endpoint Prefix: https://remora.nordtribe.eu/api

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:

curl https://remora.nordtribe.eu/api/portfolios \
  -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
POST/api/portfolios
GET/api/portfolios/{id}
PUT/api/portfolios/{id}
DEL/api/portfolios/{id}
GET/api/portfolios/{id}/performance
GET/api/portfolios/{id}/analytics
GET/api/portfolios/{id}/target-allocations
POST/api/portfolios/{id}/target-allocations
GET/api/portfolios/{id}/strategies
POST/api/portfolios/{id}/strategies
GET/api/portfolios/{id}/rebalance-trades
GET/api/portfolios/{id}/currency-rates
GET/api/portfolios/{id}/markets/performance
POST/api/portfolios/{id}/transactions
POST/api/portfolios/{id}/holdings/adjust
GET/api/portfolios/{id}/logs
POST/api/portfolios/{id}/logs
DEL/api/portfolios/{id}/logs/{logId}
POST/api/portfolios/{id}/share
POST/api/portfolios/{id}/copy

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).

REST + MCP JSON-RPC 2.0
Authentication

Authenticate using dedicated Agent API tokens issued in User Profile:

Authorization: Bearer remora_agent_...
Token Scopes
  • read:portfolios - Discovery & positions
  • write:remarks - Advisory notes
  • manage:portfolios - AI portfolio creation
  • write:trades - Trade execution
Portfolio AI Access Levels
  • private: Hidden from agents (404)
  • read_advise: Read & submit advice only
  • full_managed: Read, advice & trading
Read-Only Guardrail on /api/portfolios/*

Agent tokens (remora_agent_...) with read:portfolios scope may read portfolio states and analytics on /api/portfolios/*.

Mutation Guard: All non-GET/HEAD requests (POST, PUT, DELETE) on /api/portfolios/* with an agent token are strictly rejected with 403 Forbidden. All mutations must be dispatched via /api/agent/*.
Platform HMAC Signature Verification

When STRATEGY_SUITE_SHARED_SECRET is configured, all requests to /api/agent/* must include two platform security headers:

X-Strategy-Suite-Timestamp: Unix timestamp (±300s drift window)
X-Strategy-Suite-Signature: sha256_hmac(timestamp . "." . METHOD . "." . /path . "." . body, secret)

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.

HTTP Remote MCP Endpoint

Forward JSON-RPC 2.0 requests with Bearer token (and HMAC headers when configured):

POST https://remora.nordtribe.eu/api/agent/mcp
Authorization: Bearer remora_agent_...
X-Strategy-Suite-Timestamp: 1715000000
X-Strategy-Suite-Signature: <hmac-sha256-hex>
Claude Desktop / Cursor STDIO Configuration
{
  "mcpServers": {
    "remora": {
      "command": "php",
      "args": ["artisan", "remora:mcp-server", "--token=remora_agent_..."]
    }
  }
}