Skip to main content

​
Responses

Every successful response has this envelope:
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

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 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.