Developer docsread-only plus approval required

Mattheus REST API

Use the Mattheus REST API for current-launch market data, account reads, execution previews, and gated Hyperliquid, Alpaca, Uniswap, and Aave workflows with referenceId idempotency.

Short answer

The REST API base URL is $MATTHEUS_API_BASE_URL. Send Authorization: Bearer mt_... and use read-only data endpoints by default. Use /openapi.public.json for anonymous data, and /api/v1/capabilities plus /api/v1/workflow-nodes as the capability source of truth. Interactive execution uses create-approval, wallet-reauthenticated decision, and one-time approvalId submission; API-key execution requires an active scoped agent session.

Default API posture

Start integrations with read-only data endpoints for prices, funding, order book, yield, portfolio, and protocol intelligence.

Execution contract

Interactive clients call POST /api/v1/execute/approvals, review the exact instruction, approve it through PATCH /api/mattheus/ai/approvals/:approvalId with fresh wallet reauthentication, then submit the unchanged request with approvalId. API-key clients require an active scoped agent session instead.

Schema contracts

Use /openapi.public.json for public read-only data and GET /api/v1/capabilities plus GET /api/v1/workflow-nodes as the live agent/workflow source of truth. Authenticated execution OpenAPI artifacts remain in the repository for approved integrators and are served publicly only when API docs are enabled.

Who This Is For

Backend developers integrating raw HTTP, services that need idempotent execution previews, and teams that want stable API contracts without an SDK.

Before You Begin

  • An mt_ API key
  • HTTPS client with Bearer auth
  • Unique referenceId values for execution requests
  • Feature and approval readiness for any execution-capable endpoint

Answer engine brief

Mattheus overview

Mattheus is a private AI trading workspace for researching markets, testing reproducible strategies, reviewing portfolio context, and preparing governed actions. Developers can connect through REST APIs, SDKs, and MCP while account authority, policy checks, and approvals remain separate.

Does Mattheus require approval before execution?

Yes. An interactive request requires an exact short-lived one-time approval confirmed with fresh wallet reauthentication. API-key automation requires a separately activated, scoped agent session. Both paths still require wallet or signing readiness and policy checks.

Which markets are documented?

The active launch documentation covers Hyperliquid market data, paper trading, and gated Live workflows. Each page states whether an example is read-only, simulated, paper, or eligible for approval-gated Live execution.

How does policy-gated execution work?

Execution-capable requests are preview-first and must pass wallet readiness, protocol certification, feature gates, idempotency, configured policy controls, and either an exact interactive approval or a bounded API-key agent session before any live action.

Can users revoke permissions?

Users should be able to revoke supported scoped permissions and API keys. Documentation should keep stop, cancel, revoke, and policy rejection paths clear before users approve live execution.

Example

What this example does

Follow this example in order. Read the expected result below before connecting it to a live account or execution-capable workflow.

bash
curl $MATTHEUS_API_BASE_URL/api/v1/data/perps/price/HYPE \
  -H "Authorization: Bearer mt_your_key"

curl -X POST $MATTHEUS_API_BASE_URL/api/v1/execute/preview \
  -H "Authorization: Bearer mt_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "hyperliquid",
    "action": "place_order",
    "assetIn": { "token": "HYPE", "amount": "1" },
    "metadata": { "side": "buy", "type": "limit", "price": "28.40" },
    "referenceId": "preview-hype-order-001"
  }'

Common errors

  • 401 Unauthorized: the mt_ API key is missing, malformed, revoked, or not scoped to the request.
  • 429 Too Many Requests: back off and retry after the rate limit window.
  • 502 or 5xx: the control plane or upstream market data adapter is unavailable. Retry with jitter and do not treat stale data as a trade signal.
  • ACTION_NOT_CERTIFIED: the protocol/action is missing certification, disabled, blocked, partner-required, or legal-review-only.
  • ACTION_CANARY_ONLY: the action is canary-only and requires beta/canary access.
  • POLICY_DENIED: subscription, approval, wallet readiness, agent-session, quota, or configured policy controls blocked execution.
  • POLICY_UNAVAILABLE: policy enforcement could not be checked, so execution fails closed.
  • VENUE_UNHEALTHY: the venue health cache, kill switch, or circuit breaker blocked execution.
  • QUOTE_STALE: the quote, preview, simulation, or preflight is missing or expired.
  • INSUFFICIENT_BALANCE: the wallet or venue account lacks enough balance for the requested action.
  • IDEMPOTENCY_CONFLICT: the same referenceId is already in progress or conflicts with another request.
  • EXECUTION_DISABLED: public execution or the requested execution protocol is disabled in this environment.
  • 429 Too Many Requests: back off before retrying any execution-capable request.

Safety note

POST /api/v1/execute represents a real-money workflow. An interactive Privy session must first create and wallet-reauthenticate an exact approval, then submit the unchanged request with its one-time approvalId. An mt_ API key requires a separately active scoped Agent Portal session. Neither path bypasses launch, certification, regulatory, rate limits, signer, venue, or policy gates.

Review API accessTry SDK