API Reference

The Coalesce Finance REST API for indexed protocol data.

Base URL

Production: https://api.coalescefi.com
Devnet:     https://api.devnet.coalescefi.com

Authentication

The API has public and protected routes.

Public routes: no API key required.
Protected routes: send X-API-Key.
In production, protected-route auth is enabled by default.

Send API Key

curl -X GET https://api.coalescefi.com/api/positions/YOUR_WALLET \
  -H "X-API-Key: your-api-key"

Permissions

Permission	Access
`read`	Protected read routes (positions, notifications)
`write`	Includes read routes
`admin`	Includes read/write + `/api/admin/*`

`API_KEYS` Format

# key:permission:label:expiresAt:walletAddress
API_KEYS="key_read_abc:read:web,key_admin_xyz:admin:ops:1767225600"

Fields:

permission: read | write | admin (defaults to read)
label: optional
expiresAt: optional Unix timestamp (seconds)
walletAddress: optional wallet binding for wallet-scoped routes
In production (NODE_ENV=production), API keys must be at least 32 characters.

Auth Mode Controls

REQUIRE_AUTH controls protected-route enforcement.
Production default: true (cannot be set to false in production).
Development default: false.

Rate Limits

Layer	Default	Scope
Global IP limit	100 requests/minute	Per IP, all API routes
API key limit	1,000 requests/minute	Per API key
Health endpoint limit	10 requests/minute	Per IP on `/health`, `/readyz`, `/health/db`

Headers:

X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
X-RateLimit-Limit-Key, X-RateLimit-Remaining-Key, X-RateLimit-Reset-Key
Retry-After (when rate-limited)

If health endpoints are rate-limited and a cached health response exists, the API serves cached data with X-Cache: HIT-RATE-LIMITED.

Environment variables:

RATE_LIMIT_ENABLED (default true)
RATE_LIMIT_MAX (default 100)
RATE_LIMIT_PER_KEY (default 1000)
REDIS_URL (optional Redis backing)

Endpoints

Health and Service

Method	Endpoint	Auth	Description
GET	`/health`	No	Service health (DB + RPC)
GET	`/livez`	No	Liveness probe
GET	`/readyz`	No	Readiness probe
GET	`/health/db`	No	DB pool + circuit-breaker health
GET	`/metrics`	Conditional	Prometheus metrics (protected in production)

Protocol Data

Method	Endpoint	Auth	Description
GET	`/api/markets`	No	List markets
GET	`/api/markets/:address`	No	Market details + lender positions
GET	`/api/borrower-whitelists/:borrower`	No	Borrower whitelist entries
GET	`/api/protocol-config`	No	Current protocol config
GET	`/api/stats`	No	Protocol statistics

Wallet and Notifications

Method	Endpoint	Auth	Description
GET	`/api/positions/:address`	Yes (`read`)	Wallet positions + borrower summary
GET	`/api/lender-positions`	Yes (`read`)	Lender positions with filters
POST	`/api/notifications/token`	Yes (`read`)	Register push token
DELETE	`/api/notifications/token`	Yes (`read`)	Unregister push token
GET	`/api/notifications/preferences`	Yes (`read`)	Get notification preferences
PUT	`/api/notifications/preferences`	Yes (`read`)	Update notification preferences

Admin

Method	Endpoint Pattern	Auth	Description
GET/POST/DELETE	`/api/admin/*`	Yes (`admin`)	Internal admin and metadata endpoints

Common Query Parameters

`GET /api/markets`

borrower (optional) - Borrower wallet filter
mint (optional) - Mint filter
sortBy (optional) - updated | deposited | created (default updated)
sortOrder (optional) - asc | desc (default desc)
limit (optional) - Page size (max 100)
offset (optional) - Offset

`GET /api/lender-positions`

market_address (optional) - Market filter
lender (optional) - Lender wallet filter
limit (optional) - Page size (max 100)
offset (optional) - Offset

Response Format

Success

{
  "success": true,
  "data": { "...": "..." },
  "requestId": "f5fd7f52-7ec2-4f3e-85c2-2f17f47ebf4e"
}

Error

{
  "success": false,
  "error": "Invalid API key",
  "code": "UNAUTHORIZED",
  "requestId": "f5fd7f52-7ec2-4f3e-85c2-2f17f47ebf4e"
}

For full error format, status codes, handling examples, and retry guidance, see Error Responses.

Example: List Markets

curl -X GET "https://api.coalescefi.com/api/markets?limit=10&sortBy=updated&sortOrder=desc"

{
  "success": true,
  "data": {
    "markets": [
      {
        "address": "4xM5...",
        "borrower": "7bN3...",
        "annualInterestBps": 800,
        "maturityTimestamp": "1713571200",
        "maxTotalSupply": "1000000000000",
        "scaledTotalSupply": "500000000000000000000",
        "scaleFactor": "1020000000000000000"
      }
    ],
    "pagination": {
      "total": 1,
      "limit": 10,
      "offset": 0,
      "hasMore": false,
      "maxLimit": 100
    }
  },
  "requestId": "f5fd7f52-7ec2-4f3e-85c2-2f17f47ebf4e"
}

Example: Get Wallet Positions

curl -X GET https://api.coalescefi.com/api/positions/YOUR_WALLET \
  -H "X-API-Key: your-api-key"