REST Endpoints
Reference for DeFiMara API endpoints — authentication, messaging, streaming and session management — with request format and error codes.
All endpoints are served from https://api.defimara.com. Protected endpoints take the JWT from Authorization: Bearer <token> (the web app uses an HttpOnly cookie instead). Session routes only accept the session_id that belongs to your token.
• Endpoint Reference
/api/agent/noncepublicOne-time nonce plus the exact message to sign. Query: wallet_address, chain_type (evm | solana). Valid for 5 minutes.
/api/agent/authpublicVerify the signed nonce. Returns access_token, session_id, user_id and expires_in.
/messageJWTQueue a message for Mara (1–5000 characters). Returns a JSON acknowledgement, not the reply.
/sessions/{session_id}/streamJWTServer-Sent Events stream with the reply to the queued message.
/sessions/{session_id}/statusJWTSession activity: history_length, created_at, last_activity, is_sse_active.
/sessions/{session_id}/quotaJWTMessage usage for this session (wallet tier or preview quota).
/sessions/{session_id}/walletJWTWallet addresses linked to the session.
/sessions/{session_id}JWTEnd the session. The JWT stops working immediately.
/connectpublicWeb-app session bootstrap. Without a wallet it creates a read-only preview session that cannot chat.
/healthpublicService health. With a preview JWT it also returns anonymous_msgs.
• POST /message Body
{
"message": "swap 10 USDC for ETH", // required, 1–5000 characters
"wallet_metadata": { "network": "base" } // optional context hints
}• Error Codes
| Status | When |
|---|---|
400 | Malformed request, e.g. an invalid chain_type or wallet address. |
401 | Missing, expired or deleted-session JWT, or a bad / expired / reused nonce. Authenticate again. |
403 | Not allowed: preview session sending /message, API access not enabled, not on Pro/Enterprise, IP not whitelisted, or session_id does not match the JWT. |
404 | Unknown session_id on a /sessions/{session_id} route. |
410 | Session expired after inactivity. Authenticate again. |
422 | Request body failed validation, e.g. an empty message or more than 5000 characters. |
429 | Rate limit: per-IP, per-wallet tier, or too many /connect attempts (10 per 60 s). |
500 | Unexpected server or tool failure. Retry later. |
Error bodies use FastAPI's shape: {"detail": ...}, where detail is a string or an object with error and message.