API Overview
How Matrix HTTP surfaces are organized: the per-user daemon, the metered gateway, the router front door, and the agent-facing services (Chronos, Deus, LayerX, UWAC, Tachyon) plus the shared auth patterns.
Matrix exposes several HTTP surfaces. Each is a distinct service with its own base path and auth model.
Services at a glance
| Service | Base | Auth | Purpose |
|---|---|---|---|
| Daemon | :8080 | Bearer (MATRIX_DAEMON_TOKEN) | Per-user chat + intent execution surface |
| Gateway | /gw/v1 | Bearer + PAX ledger | Metered, OpenAI-compatible LLM proxy |
| Router | :443 | Supabase JWT | Public front door; wakes the user's daemon and reverse-proxies |
| Chronos | /v1 | Agent DID + transport bearer | Scheduler / wake-up alarms |
| Deus | /v1 | Developer + caller auth | Agent-service marketplace, invoke, receipts |
| LayerX | /v1 | Agent DID (signed intent or principal token) | Settlement: balances, pay, withdraw, settle |
| UWAC | /v1 | Agent DID + transport bearer | OAuth-vault connectors exposed as per-user MCP tools |
| Tachyon | MCP stdio | Bearer (MATRIX_TACHYON_TOKEN) | Solidity/EVM compile, test, simulate, deploy |
| Cortex MCP | :4242 (HTTP) | Bearer (CORTEX_MCP_TOKEN) | Persistent memory server (recall, search, remember) |
Common patterns
Agent DID authentication
Chronos, LayerX, and UWAC share a challenge/verify handshake that binds a request to an agent's ed25519 DID:
- Request a challenge --
POST /v1/agent/auth/challengewith the agent DID returns a nonce to sign. - Verify the signature --
POST /v1/agent/auth/verifywith the signed nonce returns a short-lived HMAC session token used for subsequent calls.
The DID format is did:matrix:<owner_user_id>:<16-hex-key-fingerprint>. The signed message is <service>-auth:<did>:<nonce>. The principal token is scoped to the owner extracted from the DID label.
Two-layer auth (transport + principal)
Chronos, LayerX, and UWAC use a two-layer auth model:
- Transport bearer -- a shared
MATRIX_*_TOKENproves the caller is a legitimate Matrix daemon (router-injected). Required on all non-public paths. - Principal token -- the agent's DID-derived session token proves which owner is calling. Alarm/balance/invoke operations are owner-scoped.
Health and version
Every service exposes GET /healthz (unauthenticated liveness). The router additionally serves GET /v/version. Chronos and LayerX serve GET / with service name and version.
Idempotency
Money-moving endpoints (LayerX POST /v1/pay, Chronos POST /v1/alarms, Deus POST /v1/invoke/{id}) accept an idempotency_key field so retries are safe. On conflict the original result is returned.
Response envelope
Chronos and LayerX use a uniform {ok, data, error} JSON envelope:
{"ok": true, "data": { ... }}{"ok": false, "error": {"code": "unauthorized", "message": "...", "retryable": false}}Rate limiting
LayerX enforces per-client IP token-bucket rate limiting with three classes: read (explorer), write (pay/withdraw), and auth (challenge/verify). Responses include Retry-After headers.