Response Format

All API responses follow consistent envelope formats.

Success Response

Single-item responses wrap the result in a data field:

{
  "ok": true,
  "data": {
    "address": "0x1234...abcd",
    "name": "Emerald USD",
    "symbol": "eUSD",
    "totalAssets": "500000000000",
    "isPaused": false
  }
}

Paginated Response

List endpoints include a meta object with pagination info:

{
  "ok": true,
  "data": [
    { "id": 1, "txHash": "0xabc...", "assetAmount": "1000000000" },
    { "id": 2, "txHash": "0xdef...", "assetAmount": "2000000000" }
  ],
  "meta": {
    "page": 1,
    "pageSize": 20,
    "total": 150,
    "totalPages": 8
  }
}

Error Response

Error responses include a machine-readable code and human-readable message:

{
  "ok": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Vault not found"
  }
}

Error Codes

HTTP Status	Code	Description
400	INVALID_ADDRESS	Malformed Ethereum address
400	INVALID_QUERY	Invalid query parameters
400	INVALID_BODY	Invalid request body
400	INVALID_PARAM	Invalid path parameter
401	UNAUTHORIZED	Missing or invalid API key
404	NOT_FOUND	Resource not found
429	RATE_LIMITED	Too many requests

Important Notes

Amounts Are Strings

All numeric amounts (asset amounts, shares, prices) are returned as strings to preserve precision for large integers. This avoids JavaScript Number overflow for uint256 values.

// Bad — may lose precision for large values
const amount = Number(deposit.assetAmount);

// Good — use BigInt
const amount = BigInt(deposit.assetAmount);

Timestamps Are ISO 8601

All timestamps are returned as ISO 8601 strings:

"2025-01-15T10:30:00.000Z"