# Khalani Docs

> Swap, bridge and convert tokens across chains with one order API.

Build every new integration on the Khalani API (v2) at `https://api.hyperstream.dev/v2/`. API v1 (`/v1/*`) is deprecated, so use its pages only to maintain an existing v1 integration. The OpenAPI 3.1 spec for the v2 routes is at https://docs.khalani.network/openapi/v2.json. Every page linked below is plain Markdown. Read it raw, for example with curl, because a summarizing fetch tool drops exact values from tables and code.

Rules an integration must follow:

- Call the API from your backend, with your key in the `X-API-Key` header. A key shipped in a browser or app bundle is a key anyone can use. See [API access](https://docs.khalani.network/api-access.md).
- Send amounts as decimal strings of integer base units. The same token can have different decimals on different chains, so read `decimals` from `GET /v2/params`. See [Conventions](https://docs.khalani.network/guides/conventions.md).
- Send the quote's `build` object to `POST /v2/build` unchanged, `terms` included. Without `terms` nothing ties the order to the quote. A changed field returns `400`, and after five minutes the terms expire and the build returns `409`. See [Quotes and pricing](https://docs.khalani.network/guides/quotes.md).
- Never retry a build that returned an `orderId`, because every successful build creates a new order. A `500` or `502` can leave reserved state: back off and retry at most once, then contact Khalani. See [Build and deposit](https://docs.khalani.network/guides/build-and-deposit.md).
- Record the time of each build. An EVM-source order's deadline is that time plus `orderTtl` from `GET /v2/params`, in Unix seconds, and no response returns it. See [Order lifecycle](https://docs.khalani.network/guides/order-lifecycle.md).
- A smart-contract wallet must pass `payoutAddr` and `refundAddr`, since the defaults assume the depositor controls the same address on every chain. A TRON destination needs `payoutAddr` and a TRON source needs `refundAddr`.
- Send each `approveTxs` entry in order and check that its receipt succeeded. Then send `depositTx` from `depositor`, once, with its `value`, and check that receipt too. Source-chain transaction gas and the native-token relay fee in `value` are additional to the quote's token amounts. A deposit from any other account creates no order, and neither does a second deposit.
- On a TRON source, transfer exactly `expectedAmount` to `depositAddress` before `deadline`. A transfer of any other amount is rejected.
- Poll `GET /v2/orders/{orderId}` every 10 to 15 seconds until `delivered` or `delivery_failed`. Keep polling through `withdrawn_on_hub`: hub settlement does not confirm delivery. Use a local timeout and retain the `orderId` to resume; a timeout means unconfirmed, not failed. See [Track orders](https://docs.khalani.network/guides/track-orders.md).

## Get started

- [API access](https://docs.khalani.network/api-access.md): Get an API key, keep it on your backend, and know what it can and cannot do.
- [Quickstart](https://docs.khalani.network/quickstart.md): Quote, build, deposit and track one real order, end to end, in one TypeScript file.

## Guides

- [Conventions](https://docs.khalani.network/guides/conventions.md): Base URL, amounts, addresses, request ids and error bodies, shared by every endpoint.
- [Order lifecycle](https://docs.khalani.network/guides/order-lifecycle.md): The five steps of an order, its eight states, and when to stop polling.
- [Quotes and pricing](https://docs.khalani.network/guides/quotes.md): Price a trade from either side, what a quote guarantees, and how size limits work.
- [Build and deposit](https://docs.khalani.network/guides/build-and-deposit.md): Create the order, choose recipients, and send the deposit from the user's wallet.
- [Track orders](https://docs.khalani.network/guides/track-orders.md): Track delivery success or failure, read what was paid and refunded, and list your orders.
- [Cancel and refunds](https://docs.khalani.network/guides/cancel-and-refunds.md): When orders refund, how a user cancels early, and how to sign the cancel.
- [Fees and commission](https://docs.khalani.network/guides/fees.md): The flat fee, Khalani's fee and your commission, and how they show up in quotes and orders.
- [Errors and retries](https://docs.khalani.network/guides/errors.md): What each status means, which errors to retry, and the errors of quote and build.
- [Rate limits and reliability](https://docs.khalani.network/guides/rate-limits.md): Rate limits, maintenance windows, what an outage can and cannot affect, and how to get help.
- [Supported chains and tokens](https://docs.khalani.network/guides/supported-assets.md): The chains and tokens the Khalani API trades today, and how to read the live list.

## Concepts

- [How Khalani works](https://docs.khalani.network/concepts/how-khalani-works.md): Hub and spokes, mTokens, and what happens to the user's funds from deposit to payout.
- [Intents and orders](https://docs.khalani.network/concepts/intents-and-orders.md): What an intent is, how an API order becomes one, and how partial fills form a chain.
- [Solvers and solver markets](https://docs.khalani.network/concepts/solvers-and-solver-markets.md): Who fills orders, how they compete, and what they can and cannot do with your users' funds.
- [Collaborative solving](https://docs.khalani.network/concepts/collaborative-solving.md): How one order is filled from many sources of liquidity, settled together or in parts, without ever going below its rate.
- [Trust model](https://docs.khalani.network/concepts/trust-model.md): What the contracts enforce on every order, which operated services you also trust, and what happens when one of them stalls.
- [Glossary](https://docs.khalani.network/concepts/glossary.md): The terms these docs use, in one place.

## Solvers

- [Solving on Khalani](https://docs.khalani.network/solvers.md): Fill orders from one shared book across every chain and token, with your downside bounded by on-chain validation.
- [Run a solver](https://docs.khalani.network/solvers/run-a-solver.md): Subscribe to the book, build a solution, sign it, submit it, and keep your state in step.
- [Medusa API](https://docs.khalani.network/solvers/medusa-api.md): The JSON-RPC interface solvers use to watch the book, publish intents and submit solutions.
- [Intent and settlement reference](https://docs.khalani.network/solvers/intent-reference.md): The intent and solution types, the rules the hub validates every solution against, and a worked fill.

## API v1 (deprecated)

- [API v1 overview](https://docs.khalani.network/v1.md): The original swap and bridge API. Deprecated but supported, and what it still does that v2 does not.
- [Migrate to v2](https://docs.khalani.network/v1/migrate.md): Map each v1 endpoint to v2, the behaviour that changes, and what v2 does not cover yet.
- [Quickstart (v1)](https://docs.khalani.network/v1/quickstart.md): Quote, build, deposit, submit and track one v1 order from a browser page with an EVM wallet.
- [Integration guide (v1)](https://docs.khalani.network/v1/integration-guide.md): The v1 flow end to end. Routes, deposit methods, quotes with and without a wallet, fees, and production rules.
- [Wallet execution (v1)](https://docs.khalani.network/v1/wallet-execution.md): Run a v1 deposit plan. EIP-1193 requests on EVM, base64 transactions on Solana, deposit addresses, and server-side broadcast.
- [Handling exceptions (v1)](https://docs.khalani.network/v1/handling-exceptions.md): Every v1 error shape, what each exception means, and which errors to retry.
- [Limits and reliability (v1)](https://docs.khalani.network/v1/limits.md): Access without a key, the optional integrator id, rate limits, maintenance, and what an outage can affect.
- [Quotes (v1)](https://docs.khalani.network/v1/reference/quotes.md): POST /v1/quotes. Ask every route for a price, as one JSON response or as an NDJSON stream.
- [Deposit (v1)](https://docs.khalani.network/v1/reference/deposit.md): POST /v1/deposit/build and PUT /v1/deposit/submit. Build the deposit plan, then register the deposit to create the order.
- [Orders (v1)](https://docs.khalani.network/v1/reference/orders.md): GET /v1/orders/{address} and GET /v1/orders/by-id/{orderId}. Track v1 orders from created to filled or refunded.
- [Tokens (v1)](https://docs.khalani.network/v1/reference/tokens.md): The v1 token list, token search, wallet balances and natural-language autocomplete.
- [Chains (v1)](https://docs.khalani.network/v1/reference/chains.md): GET /v1/chains and chain icons, the chains v1 covers, and how to check support for a pair.
- [Data types (v1)](https://docs.khalani.network/v1/reference/data-types.md): The enums, shared objects, address formats and amounts used across API v1.

## Documentation Sets

- [Abridged documentation](https://docs.khalani.network/llms-small.txt): a compact version of the documentation for Khalani Docs, with non-essential content removed
- [Complete documentation](https://docs.khalani.network/llms-full.txt): the full documentation for Khalani Docs
- [Khalani API](https://docs.khalani.network/_llms-txt/khalani-api.txt): get started, guides and concepts for integrating the v2 API. Start here
- [Solvers](https://docs.khalani.network/_llms-txt/solvers.txt): for third-party solvers who fill orders from the intent book through the Medusa API
- [API v1 (deprecated)](https://docs.khalani.network/_llms-txt/api-v1-deprecated.txt): only for maintaining an existing v1 integration

## Notes

- The complete documentation includes all content from the official documentation
- The content is automatically generated from the same source as the official documentation