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

# Data conventions

> Amounts, prices, APR, timestamps, addresses, vault slugs and response times in API requests and responses.

## Responses

Every successful response has this envelope:

```json theme={null}
{ "data": { }, "asOf": 1791454901 }
```

`asOf` is the time the response was built, in Unix seconds.

## Amounts and prices

* Onchain amounts are integer strings in base units. USDC has 6 decimals (`"1002182000"` is 1,002.182 USDC); vault shares have 18.
* Amounts you send (`amount` and `shares` in the transaction actions) use the same base units, as positive integer strings without sign, decimals, exponent or leading zeros: `"1000000"` is 1 USDC.
* In `vaults.history`, share prices and TVL are decimal strings in the vault's deposit asset, with that asset's decimals (`"1.002182"`).
* USD values are numbers for display. USDC counts as exactly \$1.
* APY and APR values are numbers in percent: `3.55` is 3.55% a year. Fees are in basis points: `100` is 1%.

Use the string forms for calculations. Parse them with a big-integer or decimal library, not as floating-point numbers.

## Net APR

`vaults.list` and `vaults.get` give `netApr.d7`, `netApr.d30` and `netApr.inception`: the vault's net APR over the last 7 days, the last 30 days and since inception, in percent, from Lagoon's indexer.

* Lagoon computes each window from the vault's NAV updates. A window is `null` when Lagoon has no figure for it. For example, `d7` is `null` when the vault's NAV was not updated in the last 7 days.
* `apy.value` is the 30-day net APR (`apy.source` is `"live"`), or the target set by Kamui (`"target"`) while the live value is unavailable.

## Time

* Timestamps are Unix seconds, in UTC.
* History points are one per UTC day: `t` is the day's start (00:00:00 UTC) and `v` the last value recorded that day. Days without a change have no point.
* Timestamps before 2024-01-01 or more than one day in the future are rejected.

## Blocks

Actions that read the chain (`vaults.list`, `vaults.get`, `users.positions` and the transaction actions) pin every onchain read to one block and return it as `blockNumber`, so the values of one response are consistent with each other. The transaction actions also simulate at that block.

## Transaction types

The transaction actions take a `type` in the body, and their answers echo it:

* `DEPOSIT`: a USDC deposit (`syncDeposit`). Its fields are `amount` and, for a build, `receiver` and `referral`.
* `REDEEM_REQUEST`: a redeem request (`requestRedeem`). Its field is `shares`.

The request and response schemas are one shape per type: switch on `type` before you read the other fields. `users.transactions` uses the same names for the history rows of these transactions.

## Addresses and chain

* Send an address as `0x` and 40 hex characters, either all lowercase or in EIP-55 checksum form. Responses always return the EIP-55 form.
* Any other mix of upper and lower case must be a valid EIP-55 checksum. An all-uppercase address fails the checksum, and a `0X` prefix fails the format. Both answer `400 invalid_request`, with `details` naming the field.
* Wallet fields (`address`, `sender`, `receiver`) refuse the zero address.
* Ethereum mainnet only (`chainId` 1).

## Vault slugs

| Slug | Vault |
| - | - |
| `stable-vault` | Stable Vault |
| `balanced-vault` | Balanced Vault |
| `boosted-vault` | Boosted Vault |

The legacy slugs `advanced-vault` (Balanced) and `aggressive-vault` (Boosted) are still accepted. Responses always carry the canonical slug.

Slugs are exact: lowercase letters, digits and single hyphens, at most 64 characters. The API does not change their case or trim them, so `Stable-Vault`, `STABLE-VAULT` and `" stable-vault"` answer `400 invalid_request`. A well-formed slug that names no vault answers `404 vault_not_found`.

## Paging

[`users.transactions`](/api-reference/users-transactions) returns rows in pages, newest first.

* Send `limit` (1 to 100, default 50) for the page size.
* Each page has a `nextCursor`. Send it back as `cursor`, with the same `address`, `slug` and `types`, to get the next page. `limit` may change between pages.
* The cursor is opaque and signed, at most 256 characters. Send it back exactly as you got it: do not decode, change or build one. A changed cursor answers `400 invalid_cursor`.
* Stop when `nextCursor` is `null`. A page can hold fewer rows than `limit`, even none, before the last page.
* The rows of one cursor chain stop at the page's `snapshotAt`, so an event indexed later never repeats or shifts a row. Start again from the first page to see newer rows.

## Response times

In tests on Kamui's staging environment, responses took 0.7 to 4 seconds, 1.8 seconds on average. Actions that read the chain or Lagoon's indexer wait for those reads.

* Set a client timeout of at least 15 seconds.
* Retry a `502`, `503` or `504` with exponential backoff, within your [limits](/api/overview#limits).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.