> ## 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.
# Get vault history
> Share price (`metric: "share_price"`) or TVL (`metric: "tvl"`) history of one vault, in its deposit asset.
- Each point is the last value recorded on a UTC day: `t` is the day's start in Unix seconds and `v` the value as a decimal string. Days without a change have no point. Points are in ascending order.
- `to` defaults to now and `from` to 90 days before `to`. `from` must be before `to`, and the range may be at most 366 days.
- Timestamps before 2024-01-01 or more than one day in the future are rejected.
- A legacy slug resolves to its canonical vault, and the response carries the canonical slug.
## OpenAPI
````yaml api-reference/openapi.json POST /vaults.history
openapi: 3.1.0
info:
title: Kamui External API
description: >-
API for Kamui vault data and for the unsigned transactions that deposit into
a vault or create a redeem request on it, served by a Supabase Edge
Function. The function never signs or sends a transaction: your users sign
and send the transactions it builds. It writes no state apart from recording
when each API key was last used.
## Base URL
`https://api.kamui.finance/functions/v1/external-api`
## Requests
- Call every action as `POST /` with a JSON object body
and `Content-Type: application/json`. The body may be at most 16 KiB.
- Bodies are strict: an unknown field is a 400, and so is a field named
twice in one object (`is a duplicate field`).
- Only POST is allowed. Any other method answers 405 `method_not_allowed`.
- The function checks the method first, then the API key, then your rate
limit, then the action. An unknown action counts against your read limit and
answers 404 `route_not_found` with a valid key, and 401 without one.
## Authentication
- Send your API key in the `x-partner-api-key` header on every request,
including `health.ping`.
- A key looks like `kmi__`: `kmi_`, 12 lowercase base32
characters, `_`, then 43 base64url characters (60 characters in total).
`kmi_` is the key prefix. After creation Kamui sees only the prefix.
- Kamui issues the keys. The full key is shown once, when it is created, so
store it in a secret manager. A lost key cannot be recovered; Kamui rotates
it instead.
- Rotation issues a new key. The old key keeps working for a grace period
that Kamui sets when it rotates (24 hours by default), then stops.
- Kamui can also revoke a key at once.
- A missing, malformed, unknown, revoked or expired key always answers the
same 401 `unauthorized`.
- Call the API from your backend only. The function sends no CORS headers,
and a browser or mobile app must never hold the key.
## Request ids
- You may send an `x-request-id` header: 1 to 128 letters, digits, `.`, `_`,
`:` or `-`. Any other value is replaced with a new UUID.
- Every response carries the id in its `x-request-id` header, and every
error body in `requestId`. Quote it when you contact Kamui.
## Responses
- Success: `{ "data": …, "asOf": }`.
- Error: `{ "error": "", "code": "", "requestId": "" }`,
plus `details` (a list of `{ "path", "issue" }`) when the request is
invalid. Branch on `code`; the message text may change.
- Responses are never cached (`Cache-Control: no-store`).
| HTTP | `code` | Meaning |
| --- | --- | --- |
| 400 | `invalid_request` | A field is missing, has the wrong type or value,
or is unknown. See `details`. |
| 400 | `invalid_amount` | The amount is above the per-request limit. See
`details`. |
| 400 | `amount_below_minimum` | The deposit is below the minimum. See
`details`. |
| 401 | `unauthorized` | The API key is missing, malformed, unknown, revoked
or expired. |
| 403 | `actions_not_enabled` | Transaction building is not enabled for your
API client. Ask Kamui. |
| 403 | `wallet_not_allowed` | The vault's allow list (`isAllowed`) does not
accept the wallet. |
| 404 | `route_not_found` | The action does not exist. |
| 404 | `vault_not_found` | No vault has this slug. |
| 405 | `method_not_allowed` | Use POST. |
| 409 | `vault_not_active` | The vault exists but is not open yet. |
| 409 | `vault_paused` | The vault is paused. |
| 409 | `deposits_unavailable` | The vault does not accept synchronous
deposits now (sync mode, or the NAV is being updated). |
| 409 | `deposit_cap_reached` | The deposit would exceed the vault's cap. |
| 409 | `redeem_request_already_pending` | The wallet already has a redeem
request waiting for settlement in this vault. |
| 413 | `payload_too_large` | The body is over 16 KiB. |
| 415 | `unsupported_media_type` | Send `Content-Type: application/json`. |
| 422 | `insufficient_balance` | The wallet holds less USDC than the
deposit. |
| 422 | `insufficient_shares` | The wallet holds fewer shares than the
redeem request. |
| 422 | `simulation_failed` | A built transaction reverts in simulation.
`details` names the transaction and the error. |
| 429 | `rate_limited` | Your client is over its per-minute limit. Wait
`Retry-After` seconds. |
| 500 | `internal_error` | Unexpected error. Retry later and quote the
request id. |
| 502 | `upstream_error` | A data source (the vault indexer or the chain)
returned an error. Retry with backoff. |
| 503 | `service_unavailable` | The service is temporarily unavailable.
Retry with backoff. |
| 503 | `actions_disabled` | Transaction building is switched off. The read
actions still answer. |
| 504 | `upstream_timeout` | A data source did not answer in time. Retry
with backoff. |
## Data conventions
- Onchain amounts are base-unit integer strings: USDC has 6 decimals, vault
shares have 18.
- In `vaults.history`, share prices and TVL are decimal strings in the
deposit asset, with its decimals (`"1.002182"`).
- APY and APR values are numbers in percent (`3.55` is 3.55% a year). Fees
are in basis points (`100` is 1%).
- USD values are numbers for display. USDC counts as exactly $1.
- Timestamps are Unix seconds, UTC.
- Addresses are accepted in lowercase or EIP-55 and returned in EIP-55.
Other mixed case, all-uppercase hex and a `0X` prefix are a 400.
- Vault slugs: `stable-vault`, `balanced-vault`, `boosted-vault`. The legacy
slugs `advanced-vault` and `aggressive-vault` are accepted; responses always
carry the canonical slug. Slugs are matched exactly: case and whitespace
count, so `Stable-Vault` is a 400.
- `users.transactions` cursors are opaque and signed. Send `nextCursor` back
unchanged, with the same filters; a changed cursor is a 400
`invalid_cursor`.
- Ethereum mainnet only (`chainId` 1).
## Transactions
`transaction.quote` and `transaction.build` cover two transaction types, set
in the body's `type`:
- `DEPOSIT`: a synchronous deposit of USDC (`syncDeposit`). The shares are
minted in the same transaction.
- `REDEEM_REQUEST`: a redeem request (`requestRedeem`). The shares leave the
wallet at once, and the vault settles the request later. A redeem request is
the only way out of a Kamui vault.
Both take the vault's `slug` in the body, like every other action.
- `transaction.quote` prices the transaction and says whether the vault
takes it now (`availability`). It builds no transaction.
- `transaction.build` runs every check in a fixed order (the first failure
answers), returns the unsigned transactions and simulates them.
- Send the transactions in `step` order from `from`, and wait for each
receipt before you send the next. Each `to` is the vault or, for an
approval, the deposit asset; `value` is always `"0"`. An approval is for the
exact deposit amount, never unlimited.
- Every read is pinned to `blockNumber`, and the simulation runs on top of
it. Build again after a 409, or when more than 10 minutes have passed.
- Once a redeem request settles, its assets are claimable. The API builds no
claim: the wallet claims them in the Kamui app, or Lagoon pays them out in
the wallet's next redeem request (`claimFirst`).
- Transaction building must be enabled for your API client; until it is,
both actions answer 403 `actions_not_enabled`.
- Transaction building can be switched off. It then answers 503
`actions_disabled`, and the read actions keep answering.
## Limits
- Each client has per-minute request limits, shared by all of its API keys:
one for the read actions and a lower one for the transaction-building
actions. By default they are 120 read requests and 20 transaction requests a
minute; Kamui can set other limits for your client.
- Every request with a valid API key counts, whatever the answer: a 400, 413
or 415 counts too, and an unknown action counts against the read limit. A
request without a valid key (401) or with another method (405) does not
count.
- The transaction limit is checked before transaction building's own checks,
so a 429 can come before a 403 `actions_not_enabled` or a 503
`actions_disabled`.
- The windows are fixed UTC minutes. Every counted response carries
`RateLimit-Policy` (for example `"read";q=120;w=60`: the limit and the
window in seconds), `RateLimit` (`"read";r=119;t=42`: the requests left and
the seconds until the window resets), and `X-RateLimit-Limit`,
`X-RateLimit-Remaining` and `X-RateLimit-Reset` (Unix seconds).
- Over the limit, the API answers 429 `rate_limited` with `Retry-After` in
seconds. Wait that long before the next request.
- If Kamui cannot check the limit for a moment, the read actions still
answer (without the rate-limit headers), and the transaction actions answer
503 `service_unavailable`.
- Avoid tight polling loops.
version: 1.0.0
contact:
name: Kamui
url: https://kamui.finance
servers:
- url: '{baseUrl}'
description: Kamui External API
variables:
baseUrl:
default: https://api.kamui.finance/functions/v1/external-api
description: >-
The API base URL. It defaults to production; change it only if Kamui
gave you another base URL.
security: []
tags:
- name: Health
description: Check that the API is up and that your key works.
- name: Vaults
description: Vault data that is the same for every wallet.
- name: Users
description: Data about one wallet.
- name: Transactions
description: >-
Quotes and unsigned transactions that deposit into a vault or create a
redeem request on it, and the checks behind them.
paths:
/vaults.history:
post:
tags:
- Vaults
summary: Get vault history
description: >-
Share price (`metric: "share_price"`) or TVL (`metric: "tvl"`) history
of one vault, in its deposit asset.
- Each point is the last value recorded on a UTC day: `t` is the day's
start in Unix seconds and `v` the value as a decimal string. Days
without a change have no point. Points are in ascending order.
- `to` defaults to now and `from` to 90 days before `to`. `from` must be
before `to`, and the range may be at most 366 days.
- Timestamps before 2024-01-01 or more than one day in the future are
rejected.
- A legacy slug resolves to its canonical vault, and the response
carries the canonical slug.
operationId: vaults_history
parameters:
- $ref: '#/components/parameters/RequestId'
requestBody:
required: true
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
slug:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
description: >-
Vault slug, matched exactly: lowercase letters, digits and
single hyphens (`stable-vault`). Case and whitespace count,
so `Stable-Vault` and ` stable-vault` answer 400. A legacy
slug works; the response carries the canonical one.
metric:
type: string
enum:
- share_price
- tvl
from:
type: integer
minimum: 1704067200
maximum: 9007199254740991
to:
type: integer
minimum: 1704067200
maximum: 9007199254740991
required:
- slug
- metric
additionalProperties: false
examples:
sharePrice:
summary: Share price, last 90 days (default range)
value:
slug: stable-vault
metric: share_price
tvl:
summary: TVL, last 90 days (default range)
value:
slug: stable-vault
metric: tvl
customRange:
summary: Share price for a custom range (Unix seconds)
value:
slug: stable-vault
metric: share_price
from: 1788825600
to: 1791417600
legacySlug:
summary: 'Legacy slug: aggressive-vault resolves to boosted-vault'
value:
slug: aggressive-vault
metric: share_price
responses:
'200':
description: Success
headers:
x-request-id:
$ref: '#/components/headers/RequestId'
ratelimit-policy:
$ref: '#/components/headers/RateLimitPolicy'
ratelimit:
$ref: '#/components/headers/RateLimit'
x-ratelimit-limit:
$ref: '#/components/headers/XRateLimitLimit'
x-ratelimit-remaining:
$ref: '#/components/headers/XRateLimitRemaining'
x-ratelimit-reset:
$ref: '#/components/headers/XRateLimitReset'
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
data:
type: object
properties:
slug:
type: string
metric:
type: string
enum:
- share_price
- tvl
unit:
type: string
from:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
to:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
points:
type: array
items:
type: object
properties:
t:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
v:
type: string
required:
- t
- v
additionalProperties: false
required:
- slug
- metric
- unit
- from
- to
- points
additionalProperties: false
asOf:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
required:
- data
- asOf
additionalProperties: false
examples:
sharePrice:
summary: Share price (points trimmed)
value:
data:
slug: stable-vault
metric: share_price
unit: USDC
from: 1783678901
to: 1791454901
points:
- t: 1788048000
v: '1.000000'
- t: 1788825600
v: '0.999999'
- t: 1789084800
v: '1.000000'
- t: 1791244800
v: '1.002024'
- t: 1791331200
v: '1.002103'
- t: 1791417600
v: '1.002182'
asOf: 1791454901
tvl:
summary: TVL (points trimmed)
value:
data:
slug: stable-vault
metric: tvl
unit: USDC
from: 1783678901
to: 1791454901
points:
- t: 1788048000
v: '0.000000'
- t: 1788480000
v: '100.000000'
- t: 1788652800
v: '80.000000'
- t: 1791417600
v: '250180.420000'
asOf: 1791454901
legacySlug:
summary: >-
A legacy slug answers with the canonical slug (points
trimmed)
value:
data:
slug: boosted-vault
metric: share_price
unit: USDC
from: 1783678901
to: 1791454901
points:
- t: 1791331200
v: '1.002103'
- t: 1791417600
v: '1.002182'
asOf: 1791454901
'400':
description: The request is not valid. `details` names each failing field.
headers:
x-request-id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalApiError'
examples:
invalidMetric:
summary: Unknown metric
value:
error: The request is not valid. See details.
code: invalid_request
requestId: bd6dfdcb-2d50-46b2-af72-786c15b1cf82
details:
- path: body.metric
issue: 'Invalid option: expected one of "share_price"|"tvl"'
invalidRange:
summary: from is not before to
value:
error: The request is not valid. See details.
code: invalid_request
requestId: a595eee8-ac82-4aa9-9ec5-d31750f583c3
details:
- path: body.from
issue: must be before to
unknownField:
summary: Unknown field in the body
value:
error: The request is not valid. See details.
code: invalid_request
requestId: a5ba5c77-7339-4e12-b2cf-3c1f848f8da8
details:
- path: body.foo
issue: is not a known field
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/VaultNotFound'
'409':
$ref: '#/components/responses/VaultNotActive'
'413':
$ref: '#/components/responses/PayloadTooLarge'
'415':
$ref: '#/components/responses/UnsupportedMediaType'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
'502':
$ref: '#/components/responses/UpstreamError'
'503':
$ref: '#/components/responses/ServiceUnavailable'
'504':
$ref: '#/components/responses/UpstreamTimeout'
default:
description: Error
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
error:
type: string
code:
type: string
enum:
- invalid_request
- invalid_address
- invalid_amount
- amount_below_minimum
- invalid_cursor
- unsupported_chain
- wallet_not_allowed
- vault_not_found
- route_not_found
- method_not_allowed
- vault_not_active
- vault_paused
- deposits_unavailable
- deposit_cap_reached
- redeem_request_already_pending
- payload_too_large
- unsupported_media_type
- insufficient_balance
- insufficient_shares
- simulation_failed
- rate_limited
- jurisdiction_restricted
- internal_error
- upstream_error
- service_unavailable
- actions_disabled
- history_unavailable
- upstream_timeout
- unauthorized
- actions_not_enabled
requestId:
type: string
details:
maxItems: 10
type: array
items:
type: object
properties:
path:
type: string
maxLength: 128
issue:
type: string
maxLength: 200
required:
- path
- issue
additionalProperties: false
required:
- error
- code
- requestId
additionalProperties: false
security:
- partnerApiKey: []
components:
parameters:
RequestId:
name: x-request-id
in: header
required: false
description: >-
Your id for this request: 1 to 128 letters, digits, `.`, `_`, `:` or
`-`. It is echoed in the response. Any other value is replaced with a
new UUID.
schema:
type: string
pattern: ^[A-Za-z0-9._:-]{1,128}$
headers:
RequestId:
description: >-
The request id: yours when it was valid, otherwise a new UUID. Quote it
when you contact Kamui.
schema:
type: string
RateLimitPolicy:
description: >-
Your client's limit for this kind of action, as an IETF RateLimit-Policy
field: `"read";q=120;w=60` is 120 requests per 60-second window.
`"actions"` is the transaction-building actions.
schema:
type: string
RateLimit:
description: >-
The current window, as an IETF RateLimit field: `"read";r=119;t=42` is
119 requests left and 42 seconds until the window resets.
schema:
type: string
XRateLimitLimit:
description: Requests allowed in the current window.
schema:
type: integer
XRateLimitRemaining:
description: Requests left in the current window.
schema:
type: integer
XRateLimitReset:
description: When the current window resets, in Unix seconds.
schema:
type: integer
RetryAfter:
description: Seconds to wait before the next request.
schema:
type: integer
schemas:
ExternalApiError:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
error:
type: string
code:
type: string
enum:
- invalid_request
- invalid_address
- invalid_amount
- amount_below_minimum
- invalid_cursor
- unsupported_chain
- wallet_not_allowed
- vault_not_found
- route_not_found
- method_not_allowed
- vault_not_active
- vault_paused
- deposits_unavailable
- deposit_cap_reached
- redeem_request_already_pending
- payload_too_large
- unsupported_media_type
- insufficient_balance
- insufficient_shares
- simulation_failed
- rate_limited
- jurisdiction_restricted
- internal_error
- upstream_error
- service_unavailable
- actions_disabled
- history_unavailable
- upstream_timeout
- unauthorized
- actions_not_enabled
requestId:
type: string
details:
maxItems: 10
type: array
items:
type: object
properties:
path:
type: string
maxLength: 128
issue:
type: string
maxLength: 200
required:
- path
- issue
additionalProperties: false
required:
- error
- code
- requestId
additionalProperties: false
responses:
Unauthorized:
description: The API key is missing, malformed, unknown, revoked or expired.
headers:
x-request-id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalApiError'
examples:
unauthorized:
summary: The API key is missing, malformed, unknown, revoked or expired.
value:
error: Unauthorized.
code: unauthorized
requestId: ea80702c-a332-4e32-922e-76bcb02e6156
VaultNotFound:
description: No vault has this slug.
headers:
x-request-id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalApiError'
examples:
vault_not_found:
summary: No vault has this slug.
value:
error: No vault exists with this slug.
code: vault_not_found
requestId: 3e515e1a-ad93-4506-81fc-aa47575c15f6
VaultNotActive:
description: The vault exists but is not open yet.
headers:
x-request-id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalApiError'
examples:
vault_not_active:
summary: The vault exists but is not open yet.
value:
error: This vault is not open yet.
code: vault_not_active
requestId: 6f1d2c3b-8a47-4e59-b0c6-2d9e4f7a1b85
PayloadTooLarge:
description: The body is over 16 KiB.
headers:
x-request-id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalApiError'
examples:
payload_too_large:
summary: The body is over 16 KiB.
value:
error: The request body is too large.
code: payload_too_large
requestId: 0c8e5a7d-3f21-4b96-a4d8-7e1b9c2f6a30
UnsupportedMediaType:
description: The body was not sent as application/json.
headers:
x-request-id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalApiError'
examples:
unsupported_media_type:
summary: The body was not sent as application/json.
value:
error: Send the request body as application/json.
code: unsupported_media_type
requestId: 9b4f6e2a-1c7d-4a85-8e3f-5d0a2b6c9e17
RateLimited:
description: >-
Your client is over its per-minute limit for this kind of action. Wait
`Retry-After` seconds before the next request.
headers:
x-request-id:
$ref: '#/components/headers/RequestId'
retry-after:
$ref: '#/components/headers/RetryAfter'
ratelimit-policy:
$ref: '#/components/headers/RateLimitPolicy'
ratelimit:
$ref: '#/components/headers/RateLimit'
x-ratelimit-limit:
$ref: '#/components/headers/XRateLimitLimit'
x-ratelimit-remaining:
$ref: '#/components/headers/XRateLimitRemaining'
x-ratelimit-reset:
$ref: '#/components/headers/XRateLimitReset'
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalApiError'
examples:
rate_limited:
summary: >-
Your client is over its per-minute limit for this kind of
action. Wait `Retry-After` seconds before the next request.
value:
error: Too many requests. Wait and try again.
code: rate_limited
requestId: 8e2f4a6c-1b3d-4e5f-9a7b-0c2d4e6f8a1b
InternalError:
description: Unexpected error. Retry later and quote the request id.
headers:
x-request-id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalApiError'
examples:
internal_error:
summary: Unexpected error. Retry later and quote the request id.
value:
error: An unexpected error occurred.
code: internal_error
requestId: 4a7c9e1f-6b2d-4f83-9c05-8e3a1d7b2f64
UpstreamError:
description: >-
A data source (the vault indexer or the chain) returned an error. Retry
with backoff.
headers:
x-request-id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalApiError'
examples:
upstream_error:
summary: >-
A data source (the vault indexer or the chain) returned an
error. Retry with backoff.
value:
error: An upstream data source returned an error.
code: upstream_error
requestId: 2e6b8d4f-9a13-4c57-b8e2-1f7c3a5d9b06
ServiceUnavailable:
description: The service is temporarily unavailable. Retry with backoff.
headers:
x-request-id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalApiError'
examples:
service_unavailable:
summary: The service is temporarily unavailable. Retry with backoff.
value:
error: The service is temporarily unavailable.
code: service_unavailable
requestId: 7d3a1f9c-5e82-4b06-a3c7-9f2e6b4d1a58
UpstreamTimeout:
description: A data source did not answer in time. Retry with backoff.
headers:
x-request-id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalApiError'
examples:
upstream_timeout:
summary: A data source did not answer in time. Retry with backoff.
value:
error: An upstream data source did not respond in time.
code: upstream_timeout
requestId: 5c9e3b7a-2d64-4f18-b7a9-3e1d8c6f2b40
securitySchemes:
partnerApiKey:
type: apiKey
in: header
name: x-partner-api-key
description: >-
The client's own API key (`kmi__`), issued by Kamui. A
missing, malformed, unknown, revoked or expired key answers 401
unauthorized.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.