REST API Overview

The Emerald Vault API provides programmatic access to vault data, user positions, NAV history, and more. All endpoints are served from the backend at <BASE_URL>/api/v1/.

For a live interactive explorer, visit Swagger UI.

Public Endpoints (no auth)

Method	Path	Description
GET	/api/v1/vaults	List all vaults
GET	/api/v1/vaults/{address}	Vault detail + stats
GET	/api/v1/vaults/{address}/nav	NAV history (paginated)
GET	/api/v1/users	User list (paginated, sortable)
GET	/api/v1/users/{address}	User profile + holdings
GET	/api/v1/users/{address}/deposits	User deposits (paginated)
GET	/api/v1/users/{address}/withdrawals	User withdrawals (paginated)
GET	/api/v1/queues/withdrawals	Pending withdrawal queue
GET	/api/v1/queues/deposits	Unswept deposits per vault
GET	/api/v1/settlement/summary	Settlement summary

Partner Endpoints (API key required)

These mirror public data but require authentication and are rate-limited per partner.

Method	Path	Description
GET	/api/v1/partner/me	Your profile + numeric partnerId
GET	/api/v1/partner/router	DepositRouter address + chainId
GET	/api/v1/partner/vaults	List vaults (authenticated)
GET	/api/v1/partner/vaults/{address}/nav	NAV history (authenticated)
GET	/api/v1/partner/stats	Your referral stats
GET	/api/v1/partner/deposits	Your attributed deposits
POST	/api/v1/partner/webhooks	Register/update webhook URL

Admin Endpoints (wallet auth)

These are not available to partners. They require SIWE wallet-based authentication.

Method	Path	Description
GET	/api/v1/admin/partners	List partners
POST	/api/v1/admin/partners	Create partner
PATCH	/api/v1/admin/partners/{id}	Update partner
DELETE	/api/v1/admin/partners/{id}	Delete partner (hard delete; 409 if referral history — use PATCH isActive:false to deactivate)

Common Query Parameters

Pagination

Parameter	Type	Default	Description
page	integer	1	Page number (min 1)
pageSize	integer	20	Items per page (min 1, max 100)

Sorting (user list only)

Parameter	Type	Default	Description
sortBy	string	firstSeen	Sort field: firstSeen, totalDeposited, totalWithdrawn
sortOrder	string	desc	Sort order: asc or desc

Date Filters

Parameter	Type	Description
from	ISO 8601	Start date (inclusive)
to	ISO 8601	End date (inclusive)

Vault Filter

Parameter	Type	Description
vault	Ethereum address	Filter results by vault address

Address Path Parameter

All {address} path parameters must be valid Ethereum addresses matching ^0x[0-9a-fA-F]{40}$.