> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sumvin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Conventions

> Patterns and conventions used across the Sumvin Platform API

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.

## Hypermedia Links (HAL)

Every response includes a `_links` object with navigation and available actions:

```json theme={null}
{
  "user": { "...": "..." },
  "_links": {
    "self": { "href": "/v0/user/me" },
    "wallets": { "href": "/v0/wallets" },
    "kyc": { "href": "/v0/kyc/applicant", "method": "POST" },
    "kyc-status": { "href": "/v0/kyc/status", "description": "Check KYC verification status" }
  }
}
```

Action links (like `set-primary` or `delete`) only appear when the action is permitted for the current resource state.

### Default `method`

<Note>
  When a link omits the `method` field, the method is `GET`. Any link that requires `POST`, `PATCH`, `PUT`, or `DELETE` always sets `method` explicitly. Clients can model `method` as optional and default it to `GET`.
</Note>

In the example above, `self` and `wallets` are `GET` (implicit), and `kyc` is `POST` (explicit).

## Expand Parameters

Fetch related resources in a single request to reduce round-trips:

```bash theme={null}
GET /v0/user/me?expand=wallets&expand=status_history
```

Each endpoint documents its supported expand options. Unknown expand values are silently ignored.

## Error Responses

All errors follow [RFC 7807 Problem Details](https://tools.ietf.org/html/rfc7807):

```json theme={null}
{
  "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](/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:

```json theme={null}
{
  "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:

```bash theme={null}
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`.