Skip to main content

Endpoint Details

Detailed documentation for each endpoint. For interactive testing, use the Swagger UI.

Vaults​

GET /api/v1/vaults​

Returns all Emerald vaults (max 6). No pagination needed.

Response: { ok: true, data: Vault[] }

GET /api/v1/vaults/{address}​

Returns a single vault with summary statistics.

Path params: address — vault Ethereum address

Response: { ok: true, data: VaultDetail } where VaultDetail extends Vault with:

{
  "stats": {
    "userCount": 42,
    "pendingWithdrawals": 3,
    "lastSweepAt": "2025-01-15T10:30:00.000Z",
    "lastNavAt": "2025-01-15T12:00:00.000Z"
  }
}

Errors: INVALID_ADDRESS (400), NOT_FOUND (404)

GET /api/v1/vaults/{address}/nav​

Paginated NAV update history for a vault.

Path params: address — vault Ethereum address

Query params: page, pageSize, from, to

Response: { ok: true, data: NavHistory[], meta: PaginationMeta }

Users​

GET /api/v1/users​

Paginated user list, sortable by firstSeen, totalDeposited, or totalWithdrawn.

Query params: page, pageSize, sortBy, sortOrder

Response: { ok: true, data: User[], meta: PaginationMeta }

GET /api/v1/users/{address}​

Returns a user's profile with per-vault deposit and withdrawal summaries.

Response: { ok: true, data: UserWithHoldings }

{
  "address": "0x...",
  "firstSeen": "2025-01-01T00:00:00.000Z",
  "totalDeposited": "1000000000",
  "totalWithdrawn": "500000000",
  "holdings": {
    "deposits": [
      { "vaultAddress": "0x...", "_sum": { "assetAmount": "..." }, "_count": 5 }
    ],
    "withdrawals": [
      { "vaultAddress": "0x...", "_sum": { "assetsEstimate": "..." }, "_count": 2 }
    ]
  }
}

GET /api/v1/users/{address}/deposits​

Paginated deposit history for a user.

Query params: page, pageSize, vault, from, to

Response: { ok: true, data: Deposit[], meta: PaginationMeta }

GET /api/v1/users/{address}/withdrawals​

Paginated withdrawal history for a user.

Query params: page, pageSize, vault, status

The status filter accepts: queued, claimed, cancelled

Response: { ok: true, data: WithdrawalRequest[], meta: PaginationMeta }

Queues​

GET /api/v1/queues/withdrawals​

Pending/claimable withdrawals (not yet claimed, cancelled, or expired).

Query params: page, pageSize, vault

Response: { ok: true, data: WithdrawalRequest[], meta: PaginationMeta }

GET /api/v1/queues/deposits​

Per-vault list of deposits that haven't been swept yet.

Query params: vault

Response:

{
  "ok": true,
  "data": [
    {
      "vaultAddress": "0x...",
      "vaultName": "Emerald USDC Vault",
      "deposits": [ ... ],
      "count": 5
    }
  ]
}

GET /api/v1/settlement/summary​

Per-vault summary of deposits to sweep and withdrawals to fund.

Response:

{
  "ok": true,
  "data": [
    {
      "vaultAddress": "0x...",
      "vaultName": "Emerald USDC Vault",
      "depositsToSweep": { "count": 3, "totalAmount": "5000000000" },
      "withdrawalsToFund": { "count": 1, "totalAmount": "1000000000" }
    }
  ]
}

Partner​

All partner endpoints require the x-api-key header.

GET /api/v1/partner/vaults​

Same as public /api/v1/vaults but authenticated and rate-limited.

GET /api/v1/partner/vaults/{address}/nav​

Same as public NAV endpoint but authenticated and rate-limited.

POST /api/v1/partner/webhooks​

Register or update a webhook URL.

Request body:

{
  "url": "https://your-server.com/webhooks/emerald"
}

Response:

{
  "ok": true,
  "data": { "webhookUrl": "https://your-server.com/webhooks/emerald" }
}

GET /api/v1/partner/stats​

Returns your referral statistics — total deposits, volume, unique users, and per-vault breakdown. Deposits are attributed on-chain via the DepositRouter contract.

Response:

{
  "ok": true,
  "data": {
    "partnerId": 1,
    "partnerName": "Acme Finance",
    "totalDeposits": 42,
    "totalVolume": "5000000000000000000000",
    "uniqueUsers": 15,
    "byVault": [
      {
        "vaultAddress": "0x...",
        "depositCount": 30,
        "totalVolume": "3000000000000000000000"
      }
    ]
  }
}

GET /api/v1/partner/deposits​

Paginated list of deposits attributed to your partner account.

Query params: page, pageSize

Response: { ok: true, data: Deposit[], meta: PaginationMeta }

Each Deposit includes a partnerId field when attributed via the vault's referral overload.

GET /api/v1/partner/router​

Returns the DepositRouter contract address and chain ID. Use this to know where to route deposits for on-chain attribution.

Response:

{
  "ok": true,
  "data": {
    "routerAddress": "0x...",
    "chainId": 1
  }
}