> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kimia.live/llms.txt
> Use this file to discover all available pages before exploring further.

# Build on Kimia

> How to integrate with Kimia's programs. No published SDK — you fork the repo.

Kimia is a set of permissionless Anchor programs with deterministic PDAs.
Integrating does not require permission, an API key, or a keeper whitelist.

<Warning>
  Kimia does **not** publish an npm package or a crates.io crate. There is no
  `@kimia/sdk` you can `npm install`. Everything below assumes you either:

  * Fork this repo and import the generated TS clients directly, or
  * Regenerate TS clients from the on-chain IDLs into your own project.

  CPI from another Solana program works but requires a `path` or `git`
  Cargo dependency — no published crate.
</Warning>

## What actually ships

| Surface                     | Where it lives                                           | How you use it                                                   |
| --------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------- |
| Anchor IDLs                 | `Perp-engine/target/idl/`, `Programs/target/idl/`        | Build the workspaces, then point any IDL-aware tool at the JSON  |
| Codama-generated TS clients | `frontend/app/generated/<program>/`                      | Copy the folder into your project (only dep is `@solana/kit`)    |
| Rust program crates         | `Perp-engine/programs/kimia-perp`, `Programs/programs/*` | Cargo `path`/`git` dependency with `features = ["cpi"]`          |
| Reference UI code           | `frontend/app/**`                                        | Read for wiring examples (send helper, matching, PDA derivation) |

## Choose your integration path

<CardGroup cols={2}>
  <Card title="TypeScript via Codama" icon="code" href="/build/sdk">
    Copy `frontend/app/generated/<program>/` into your project. Only runtime dep
    is `@solana/kit`.
  </Card>

  <Card title="Regenerate from IDL" icon="gear" href="/build/codama">
    If you want the TS client in your own package, re-run Codama against the
    IDLs under `target/idl/`.
  </Card>

  <Card title="On-chain CPI" icon="cubes">
    Depend on the program crate by `path` or `git` with
    `features = ["cpi"]`. Reference: `Programs/programs/delta-vault/src/instructions/deposit.rs`.
  </Card>

  <Card title="Keeper bot" icon="robot" href="/guides/run-a-keeper">
    Crank funding, liquidations, rewards, rebalancing — permissionlessly.
  </Card>
</CardGroup>

## Source IDLs

After building the Anchor workspaces with `anchor build`:

```
Perp-engine/target/idl/kimia_perp.json
Programs/target/idl/delta_vault.json
Programs/target/idl/split_engine.json
Programs/target/idl/yield_amm.json
Programs/target/idl/intent_router.json
Programs/target/idl/kusd_mint.json
```

Each `codama.*.json` in `frontend/` pins one IDL to an output directory:

```json theme={null}
{
  "idl": "../Perp-engine/target/idl/kimia_perp.json",
  "outDir": "./app/generated/perp",
  "programName": "kimiaPerp"
}
```

## Typical wiring (inside this repo)

<Steps>
  <Step title="Build programs, regenerate clients">
    From the Perp-engine and Programs workspaces: `anchor build`.
    Then from `frontend/`: `npm run codama:all`.
  </Step>

  <Step title="Import the generated builder">
    ```ts theme={null}
    import { getPlaceOrderInstruction } from '@/app/generated/perp/instructions';
    ```
  </Step>

  <Step title="Resolve PDAs">
    Use the generated `find*Pda` helpers; they encapsulate seed derivation.
  </Step>

  <Step title="Prepend an oracle update">
    Use `@pythnetwork/pyth-solana-receiver` to post a fresh Hermes update in the
    same transaction.
  </Step>

  <Step title="Sign and send">
    The reference sender lives at `frontend/app/lib/send-transaction.ts`.
  </Step>
</Steps>

## Next

<CardGroup cols={2}>
  <Card title="Generated client shape" icon="book" href="/build/sdk">
    What Codama output looks like.
  </Card>

  <Card title="Data formats & precision" icon="ruler" href="/build/precision">
    Decimals, rounding, BigInt.
  </Card>

  <Card title="Error handling" icon="circle-exclamation" href="/build/error-handling">
    Map program errors to user messages.
  </Card>
</CardGroup>