API Reference

The Dualis Finance API exposes 272 endpoints across 19 domain groups, served by Fastify 5.7 over HTTP and WebSocket. This page provides an overview of the API structure, authentication, and example requests.

Base URL

All API endpoints are served under a versioned base path:

http://localhost:4000/v1

In production, replace the host with your deployment domain (e.g., https://api.dualis.finance/v1). All responses use application/json content type.

Authentication

Protected endpoints require a JWT Bearer token in the Authorization header. Obtain a token by authenticating through the /v1/auth/login endpoint.

curl -X POST http://localhost:4000/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "demo@dualis.finance", "password": "Demo1234!"}'

Include the returned token in subsequent requests:

curl http://localhost:4000/v1/pools \
  -H "Authorization: Bearer <your-jwt-token>"

Endpoint Groups

The 272 endpoints are organized into the following domain groups:

Example: List Lending Pools

Retrieve all active lending pools with their current rates and utilization:

curl http://localhost:4000/v1/pools \
  -H "Authorization: Bearer <token>"

{
  "data": [
    {
      "id": "pool_usdc_01",
      "asset": "USDC",
      "totalSupply": "12500000.00",
      "totalBorrow": "8750000.00",
      "utilization": 0.70,
      "supplyAPY": 0.0342,
      "borrowAPR": 0.0521,
      "collateralFactor": 0.85
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 8
  }
}

Example: Request a Borrow

Submit a borrow request against existing collateral:

curl -X POST http://localhost:4000/v1/borrow/request \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "poolId": "pool_usdc_01",
    "amount": "5000.00",
    "collateralPositionIds": ["pos_eth_01", "pos_btc_02"]
  }'

{
  "data": {
    "borrowId": "brw_abc123",
    "poolId": "pool_usdc_01",
    "amount": "5000.00",
    "borrowRate": 0.0521,
    "healthFactor": 1.82,
    "status": "pending_settlement",
    "createdAt": "2026-02-28T10:30:00Z"
  }
}

Request and Response Format

All request bodies must be valid JSON. The API validates inputs using Zod 4 schemas and returns structured errors for invalid payloads (see the Error Codes page for details). Successful responses wrap data in a { "data": ... } envelope. Paginated endpoints include a pagination object with page, limit, and total fields.

Full Specification

For the complete endpoint specification including all request/response schemas, query parameters, and error responses, refer to the docs/API_CONTRACT.md file in the repository. The contract document covers all 272 endpoints with exhaustive type definitions.