Reference

API

The Sovereign API is an HTTP service that exposes the runtime, trading, provenance, and accounting surfaces. Agents interact with it through the SDK. Direct API calls are available for tooling, demos, and testing.

Default ports: 3002 (snapshot mode), 3003 (Postgres mode). Configurable via API_PORT.

Health

GET /health

Returns ok when the API is running. Used for health checks and deployment verification.

Demo

POST /v1/demo/seed

Seeds demo wallets, merchants, routes, and agent identities. Run once after starting the API.

Intents

POST /v1/intents

Submit a typed EconomicIntent for evaluation by the constitutional runtime.

Request body

{
  "walletId": "wallet_procurement_demo",
  "agentId": "akasha_agent",
  "kind": "mcp.paid_data_request",
  "merchantId": "merchant_akasha_market_data",
  "routeId": "route_eth_snapshot_v1",
  "taskId": "eth_market_cycle_001",
  "idempotencyKey": "eth_snapshot_001"
}

GET /v1/actions/:actionId

Retrieve a settled economic action record by ID. Includes status, decision packet reference, artifact links, and accounting entry.

Provenance

GET /v1/provenance/:artifactId

Returns the full provenance chain for a data artifact: merchant, route, wallet, constitution version, decision packet, agent, and downstream trade plans.

Accounting

GET /v1/accounting/export

Exports journal records for all settled economic actions. Returns CSV with debit/credit entries, wallet, agent, merchant, and timestamps.

Trading

POST /v1/trading/plans

Create a trade plan from a paid data artifact. Returns a plan ID for use in risk checks and execution requests.

POST /v1/trading/plans/:planId/risk-check

Run a deterministic risk evaluation on a trade plan. Returns pass/fail with signal breakdown across position size, concentration, leverage, and volatility.

POST /v1/trading/plans/:planId/paper-execute

Request paper execution of a risk-checked plan through the trading wallet. Live execution returns LIVE_TRADING_DENIED unless escalation is configured.