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

# Postman collection

> Try every action from Postman, with example responses and tests that check each answer.

The Kamui Postman collection has a request for every action, saved example responses, and tests that check each answer. Import it into your own Postman to explore the API before you write code, or run it from the command line.

## Download

* <a href="/postman/kamui-external-api.postman_collection.json" download>Collection</a> (`kamui-external-api.postman_collection.json`): every request, its tests and its example responses.
* <a href="/postman/kamui-external-api-production.postman_environment.json" download>Production environment</a> (`kamui-external-api-production.postman_environment.json`): the base URL and a secret variable for your API key.

You can also import a file by its link: in Postman, click **Import**, then paste the link of a file above (right-click it, then **Copy link address**).

## Import into Postman

<Steps>
  <Step title="Import both files">
    In Postman, click **Import** and drop both files into the dialog.
  </Step>

  <Step title="Select the environment">
    In the environment selector at the top right, select **Kamui External API - Production**.
  </Step>

  <Step title="Add your API key">
    Open the environment and paste your key into the **Current value** of `partnerApiKey`. It is a secret variable, so Postman masks it. Leave **Initial value** empty: Postman shares initial values with your team and includes them in exports.
  </Step>

  <Step title="Check the key">
    Open **Health → health.ping** and click **Send**. A `200` with `"status": "ok"` means your key works.
  </Step>
</Steps>

Then set `walletAddress` in the collection's **Variables** tab to a wallet you want to read, and try the **Vaults** and **Users** requests.

To build transactions, set `senderAddress` to a wallet that holds USDC or vault shares, and `depositAmount` and `redeemShares` to the amounts you want, then try the **Transactions** requests.

<Note>
  The **Transactions** requests need transaction building, which Kamui enables per API client. Until it is enabled for yours, they answer `403 actions_not_enabled`, and the **Test Results** tab says so. Ask Kamui to enable it. The collection never signs or sends a transaction.
</Note>

<Note>
  Postman on the web needs the Postman Desktop Agent or the Cloud Agent to send requests, because the API sends no CORS headers. The Postman desktop app needs nothing extra.
</Note>

## What's in the collection

| Folder | Requests |
| - | - |
| Health | `health.ping` |
| Vaults | `vaults.list`; `vaults.get`, also with a legacy slug; `vaults.history` for share price, TVL, a custom range and a legacy slug |
| Users | `users.positions`; `users.transactions`: first page, next page, and one vault with some types |
| Transactions | `transaction.quote` for a `DEPOSIT` and a `REDEEM_REQUEST`; `transaction.build` for a `DEPOSIT` (also without simulation) and a `REDEEM_REQUEST` |
| Errors | One request for each error you can trigger without a funded wallet: `400` (including the transaction actions' amount, type, slug, sender and receiver checks), `401`, `404`, `405`, `413` and `415` |

* Every request sends your key in `x-partner-api-key` and a new `x-request-id`. Quote the `x-request-id` of a response when you contact Kamui.
* Tests run after every response and show in the **Test Results** tab. They check the response envelope and the fields of each action. The **Errors** requests check that the API answers the expected status and `code`.
* For `users.transactions`, send **first page**, then **next page** until the Postman Console shows "Last page". The collection keeps the cursor for you.
* Every request has saved example responses, so you can see the response shapes before you have a key. The **Transactions** requests also have saved examples of the `403`, `409` and `422` answers that depend on the wallet or the vault. **health.ping** and the **Transactions** requests have a saved `429 rate_limited` example, with its rate-limit headers.

### Variables

| Variable | Where | Default |
| - | - | - |
| `baseUrl` | environment | `https://api.kamui.finance/functions/v1/external-api` |
| `partnerApiKey` | environment | empty: paste your key |
| `vaultSlug` | collection | `stable-vault` |
| `walletAddress` | collection | an example address with no positions |
| `senderAddress` | collection | an example address that holds nothing: set a funded wallet to build |
| `depositAmount` | collection | `1000000000`: 1,000 USDC in base units (6 decimals) |
| `redeemShares` | collection | `250000000000000000000`: 250 vault shares in base units (18 decimals) |
| `historyFrom`, `historyTo` | collection | empty: the last 30 days (Unix seconds) |
| `transactionsCursor` | collection | set by the `users.transactions` requests |

A value in the selected environment overrides the collection's value, even an empty one. Keep your key in the environment.

## Run from the command line

[Newman](https://www.npmjs.com/package/newman), Postman's command-line runner, runs the whole collection, for example in CI:

```bash theme={null}
npx newman run kamui-external-api.postman_collection.json \
  -e kamui-external-api-production.postman_environment.json \
  --env-var partnerApiKey="$KAMUI_API_KEY"
```

Every request runs once, and the run fails if a test fails. The **Errors** requests expect their errors, so they pass when the API rejects them as documented. The **Transactions** requests fail until Kamui enables transaction building for your client and `senderAddress` holds enough USDC and shares; run only the other folders with `--folder Health --folder Vaults --folder Users --folder Errors`.

One run sends 11 requests to the transaction actions and 30 to the read actions, within the default [limits](/api/overview#limits) of 20 and 120 per minute. Every request counts, the failing **Errors** requests included. If you run the collection several times in a row, or your client has lower limits, space the requests out with `--delay-request`, for example `--delay-request 3000` (3 seconds).

## Troubleshooting

If every request answers `401 unauthorized`, the **Test Results** tab shows a failing test named **API key accepted** with the likely cause:

* the environment is not selected, or `partnerApiKey` is empty;
* the key is not the full `kmi_<id>_<secret>` value;
* the key was revoked, or its rotation grace period has ended. Ask Kamui for a new key.

If a request answers `429 rate_limited`, your client is over its per-minute limit. The **Test Results** tab shows a failing test named **rate limit not exceeded**, with the `Retry-After` wait in seconds and your limit from the `RateLimit-Policy` header. Wait that long, then send the request again.

If only the **Transactions** requests fail, the **Test Results** tab names the cause: transaction building is not enabled for your client yet (`403 actions_not_enabled`), Kamui has switched it off for now (`503 actions_disabled`), or the `senderAddress` wallet cannot make the transaction (`403`, `409` or `422`, with the `code` in the response).


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