REST Endpoints — Full API Reference | DeFiMara

Endpoint Reference

GET /auth/challenge — Get a one-time sign challenge (public). POST /auth/verify — Verify signed challenge, returns JWT (public). POST /chat — Send natural-language message to agent, supports stream: true for SSE (requires JWT). GET /health — Server health check (public). GET /me — Returns authenticated wallet address (requires JWT).

Request Format

POST /chat body: { "message": "swap 10 USDC for ETH", "stream": true, "chain": "arbitrum" }. Only message is required.

Error Codes

401 Unauthorized — missing or expired JWT, re-authenticate. 400 Bad Request — malformed JSON or missing required fields. 422 Unprocessable — agent understood the request but cannot fulfill it. 500 Internal Server Error — unexpected agent or tool failure.

Back to Blog
API
November 20255 min read

REST Endpoints

1. Overview

All endpoints are served over HTTP from the Defimara backend (default port 8000). Authentication endpoints are public. All others require a valid JWT in the Authorization header.

2. Endpoint Reference

GET
/auth/challengepublic

Get a one-time sign challenge for a wallet address. Pass ?address=0x...

POST
/auth/verifypublic

Verify a signed challenge. Returns access_token (JWT).

POST
/chat

Send a natural-language message to the agent. Supports stream: true for SSE.

GET
/healthpublic

Server health check. Returns {status: "ok"}.

GET
/me

Returns the authenticated wallet address from the JWT.

3. Request / Response Format

POST /chat - request body
{
  "message": "swap 10 USDC for ETH",  // required
  "stream":  true,                     // optional, default false
  "chain":   "arbitrum"               // optional override
}

• Error Codes

401 Unauthorized - missing or expired JWT, re-authenticate
400 Bad Request - malformed JSON or missing required fields
422 Unprocessable - agent understood the request but cannot fulfill it (e.g. insufficient balance)
500 Internal Server Error - unexpected agent or tool failure, check server logs

Share this article

View All Articles