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

# API overview

> Read Kamui vault and wallet data, and build unsigned deposit and redeem request transactions, from your backend with your own API key.

The Kamui External API is an HTTP API for vault and wallet data and for vault transactions.

* **Read actions** return the Kamui vaults with their live state, each vault's share price and TVL history, and a wallet's positions and transaction history across the vaults.
* **Transaction actions** quote and build the unsigned transactions that deposit USDC into a vault or create a redeem request on it.

The API never signs or sends a transaction: your users sign and send the transactions it builds, with your own wallet stack.

## Base URL

```
https://api.kamui.finance/functions/v1/external-api
```

<Tip>
  Every endpoint page has a **Try it** playground. It sends real requests to the base URL in its **Server** section, which defaults to the URL above. Paste your key under **Authorization**, edit the body, and click **Send**.

  To work from Postman instead, download the [Postman collection](/api/postman).
</Tip>

## Requests

* Call every action as `POST <base URL>/<action>`, with a JSON object body and `Content-Type: application/json`. The body may be at most 16 KiB.
* Send your API key in the `x-partner-api-key` header on every request. See [Authentication](/api/authentication).
* Bodies are strict: an unknown field answers 400, and so does a field named twice in one object.
* Only `POST` is allowed. Any other method answers 405.
* Call the API from your backend only. It sends no CORS headers, and a browser or mobile app must never hold your key.

## Get started

<Steps>
  <Step title="Get an API key">
    Kamui issues one key per client. Store it in a secret manager: it is shown only once.
  </Step>

  <Step title="Check the key">
    Call `health.ping` with an empty body. A `200` with `"status": "ok"` means the key works.

    ```bash theme={null}
    curl -X POST "https://api.kamui.finance/functions/v1/external-api/health.ping" \
      -H "Content-Type: application/json" \
      -H "x-partner-api-key: $KAMUI_API_KEY" \
      -d '{}'
    ```

    ```json theme={null}
    { "data": { "status": "ok", "service": "external-api" }, "asOf": 1791454901 }
    ```
  </Step>

  <Step title="Read data">
    Call [`vaults.list`](/api-reference/vaults-list) for the vaults, then the other read actions below. Every success response is `{ "data": …, "asOf": <Unix seconds> }`.
  </Step>

  <Step title="Build transactions">
    Ask Kamui to enable transaction building for your API client. Then quote and build deposits and redeem requests: see [Build transactions](/api/transactions).
  </Step>
</Steps>

## Read actions

| Action | Returns |
| - | - |
| [`health.ping`](/api-reference/health-ping) | Checks that the API is up and that your key works. |
| [`vaults.list`](/api-reference/vaults-list) | Every vault with its live state: APY, total assets, share price, TVL, fees and whether deposits are open. |
| [`vaults.get`](/api-reference/vaults-get) | One vault by slug, with the same live state as `vaults.list`. |
| [`vaults.history`](/api-reference/vaults-history) | Share price or TVL history of one vault, one point per UTC day. |
| [`users.positions`](/api-reference/users-positions) | One wallet's positions in every active vault, read at one block. |
| [`users.transactions`](/api-reference/users-transactions) | One wallet's deposits, redeem requests and withdrawals, newest first, in pages. |

## Transaction actions

Both take a `type`: `DEPOSIT` (a USDC deposit, `syncDeposit`) or `REDEEM_REQUEST` (a redeem request, `requestRedeem`).

| Action | Returns |
| - | - |
| [`transaction.quote`](/api-reference/transaction-quote) | The expected shares or assets, the fees, the steps and whether the vault takes the transaction now. Builds nothing. |
| [`transaction.build`](/api-reference/transaction-build) | Runs every check, then returns the unsigned transactions and their simulation. Nothing is signed or sent. |

Transaction building must be enabled for your API client: until it is, both actions answer `403 actions_not_enabled`. See [Build transactions](/api/transactions).

## 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 the request id when you contact Kamui about a request.

## Limits

Kamui limits the number of requests of each API client per minute. All the keys of one client share its limits. There are two limits, one per group of actions:

| Limit | Actions | Default |
| - | - | - |
| `read` | The read actions, and any action that does not exist | 120 requests per minute |
| `actions` | `transaction.quote` and `transaction.build` | 20 requests per minute |

* Kamui sets the limits per client and can change them. The `RateLimit-Policy` header shows yours.
* The windows are fixed UTC minutes: each count starts again at the start of the next minute.
* A request counts once its API key is accepted, whatever the answer. A `400`, a `404 route_not_found`, a `403 actions_not_enabled` and a `503 actions_disabled` count too. A request with a missing or rejected key (`401`) or another method than `POST` (`405`) does not count.
* The two limits are separate. Over the `actions` limit, the read actions still answer.

Every counted response carries the state of its limit:

```http theme={null}
RateLimit-Policy: "read";q=120;w=60
RateLimit: "read";r=119;t=42
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1791454980
```

* `RateLimit-Policy`: the limit (`q`, requests) and the window (`w`, seconds).
* `RateLimit`: the requests left (`r`) and the seconds until the window resets (`t`).
* `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (Unix seconds) give the same values.

Over the limit, the API answers `429` with a `Retry-After` header in seconds, and runs nothing:

```json theme={null}
{ "error": "Too many requests. Wait and try again.", "code": "rate_limited", "requestId": "8e2f4a6c-1b3d-4e5f-9a7b-0c2d4e6f8a1b" }
```

* Wait `Retry-After` seconds before you send the next request of that limit.
* Avoid tight polling loops. Space out repeated reads of the same data.
* If the API cannot check your limit for a moment, the read actions still answer, without the rate-limit headers. The transaction actions answer `503 service_unavailable` instead: retry them with backoff.

Ask Kamui if your integration needs higher limits.


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