1. Getting started
Base URL
https://api.yieldguard.finance/v1
All requests must be made over HTTPS. Production and sandbox (testnet) base URLs are identical except the sub‑domain: `sandbox-api.yieldguard.finance`.
Authentication
YieldGuard uses HMAC‑signed API keys (shared‑secret) or OAuth 2.1 confidential‑client flows for server‑side integrations.
X-API-Key: pk_live_...
X-Signature: <HMAC‑SHA256(body,timestamp,secret)>
X-Timestamp: 2025-07-27T14:05:17ZIdempotency
Supply an `Idempotency-Key` header on every POST/DELETE to guarantee exactly‑once semantics.
Versioning
The version is the first path segment (`/v1/…`). Non‑breaking additions do not increment the major version. A deprecation header `Sunset:` advertises removal ≥ 90 days in advance, following the [RFC 8927] pattern.
2. Errors
YieldGuard follows RFC 9457 Problem Details for machine‑readable error bodies.
{
"type": "https://docs.yieldguard.finance/errors/kyc_pending",
"title": "KYC approval pending",
"status": 409,
"detail": "Cannot deposit until KYC_PASS NFT is minted",
"instance":"e7611be2-..."
}Common status codes: 400, 401, 403, 404, 409, 422, 429, 500.
3. Rate limits
Default: 600 requests / minute / API key and 20 websocket msgs / sec. Exceeding limits yields 429 Too Many Requests and the standard `X‑RateLimit‑*` headers.
4. Pagination
Collection endpoints support cursor‑based paging:
GET /transactions?limit=100&cursor=eyJv ...
Response → 200
{
"data":[ ... 100 items ... ],
"next_cursor":"eyJv ..."
}5. Resources
5.1 KYC
| Method & Path | Description | Required scope |
|---|---|---|
POST /kyc/request | Initiate Sumsub session; returns `redirect_url`. | admin |
GET /kyc/status | Poll status (`pending`, `approved`, `rejected`). | read |
5.2 Vault operations
| Method & Path | Body | Response | Scope |
|---|---|---|---|
POST /vault/deposit | { "amount":"10000000", "asset":"USDC" } | 202 Accepted + tx hash | trade |
POST /vault/withdraw | { "shares":"5000.00" } | 202 Accepted | trade |
POST /vault/redeem | { "amount":"5000000", "asset":"USDC" } | idem | trade |
GET /vault/stats | – | TVL, NAV, APY | read |
GET /vault/positions | – | Allocation per wrapper (%) | read |
5.3 Strategy & Governance
| Endpoint | Description |
|---|---|
GET /strategy/allocation | Current wrapper weights, issuer caps. |
GET /governance/proposals | Active Snapshot proposals incl. off-chain vote tallies. |
POST /governance/proposals | (internal) Create proposal. |
5.4 Transactions & Events
| Endpoint | Description |
|---|---|
GET /transactions | Filter by wallet, type, date. Returns cursor list. |
GET /transactions/{hash} | Details inc. on-chain gas & status. |
6. WebSocket API
Endpoint: wss://api.yieldguard.finance/v1/ws
Authentication: pass `X-API-Key` in the opening HTTP headers.
Supported channels (subscribe via JSON RPC 2.0):
| Channel | Push message | Notes |
|---|---|---|
vault_updates | Deposits, withdraws, NAV tick (15s) | |
allocation_updates | Triggered on each daily rebalance | |
risk_alerts | Oracle lag, PoR alerts → automatically pause deposits | |
governance | New/voted proposals |
7. Webhooks (optional)
Set a signed HTTPS callback URL (`POST /webhooks`) to receive the same events server‑to‑server (retry with exponential back‑off on 5xx).
8. Data models
8.1 Monetary amounts
Amounts are strings carrying integer micro‑units (1 USDC.e = `"1000000"`). This eliminates floating‑point drift and matches on‑chain ERC‑20 decimals. Client SDKs expose helpers.
8.2 Timestamps
All timestamps are ISO 8601 UTC (`YYYY‑MM‑DDThh:mm:ssZ`).
8.3 Identifiers
- `tx_hash` – 32‑byte hex.
- `proposal_id` – Snapshot numeric ID.
- `cursor` – URL‑safe base64.
9. OpenAPI & SDKs
The entire surface is defined in an OpenAPI 3.1 document (`openapi.yaml`) available in the repo root. Tooling such as Swagger UI or Speakeasy can generate language SDKs and tests automatically.
10. Changelog
| Version | Date | Notes |
|---|---|---|
| 0.1 | 2025-07-27 | Initial draft |
11. Support
- Email: dev-support@yieldguard.finance
- Status page: https://status.yieldguard.finance