Skip to main content
These conventions apply to all Platform API endpoints. Understanding them will help you work with any resource in the API.

​
Base URL

https://api.sumvin.com/v0
Your platform may use a custom domain. Check with your account manager for the correct base URL. Every response includes a _links object with navigation and available actions: 
{
  "user": { "...": "..." },
  "_links": {
    "self": { "href": "/v0/user/me", "method": "GET" },
    "wallets": { "href": "/v0/wallets", "method": "GET" },
    "kyc-status": { "href": "/v0/kyc/status", "description": "Check KYC verification status" }
  }
}
Links include the HTTP method, so clients can discover available actions without hardcoding URLs. Action links (like set-primary or delete) only appear when the action is permitted for the current resource state.

​
Expand Parameters

Fetch related resources in a single request to reduce round-trips: 
GET /v0/user/me?expand=wallets&expand=onboarding
Each endpoint documents its supported expand options. Unknown expand values are silently ignored.

​
Error Responses

All errors follow RFC 7807 Problem Details: 
{
  "type": "https://api.sumvin.com/errors/wal-404-001",
  "title": "Wallet Not Found",
  "status": 404,
  "detail": "No wallet found with ID 12345",
  "instance": "/v0/wallets/12345",
  "error_code": "WAL-404-001",
  "trace_id": "abc-123-def"
}
Error codes follow the format {DOMAIN}-{STATUS}-{SEQUENCE} (e.g., USR-409-001, KYC-403-001). The trace_id can be shared with support for debugging. See Error Handling for the full reference.

​
Timestamps

Timestamps are epoch milliseconds by default. To receive ISO 8601 strings instead, include the header: 
X-Timestamp-Format: iso8601
This affects all timestamp fields (created_at, updated_at, etc.).

​
Async Operations

Some operations (Safe wallet deployment, KYC processing) happen asynchronously. These return 202 Accepted with a current snapshot and _links to poll for the result: 
{
  "id": 42,
  "safe_creation_event_id": "evt_abc123def456",
  "_links": {
    "self": { "href": "/v0/wallets/42" },
    "safe-status": { "href": "/v0/user/me" }
  }
}
Poll the linked resource until the operation completes. Typical async operations complete in 10–30 seconds.

​
Idempotency

Several endpoints are idempotent. Creating a resource that already exists returns 208 Already Reported with the existing resource, rather than an error. This makes retries safe — you can replay requests without side effects.

​
Pagination

List endpoints support offset-based pagination: 
GET /v0/wallets/{wallet_id}/assets/{asset_id}/transactions?offset=0&limit=50
When more results are available, the response includes next and prev links in _links.