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

# SDK overview

> Install @hedginvault/sdk, create a client, and run a manager action from build to confirmation in one call.

`@hedginvault/sdk` is a TypeScript client for the Hedgin manager API. It turns the API's build, sign, send, and confirm sequence into one call, and it refuses to sign any server-built transaction that could move funds out of the manager wallet.

The API still builds every transaction. The SDK calls the API, inspects what comes back, signs locally, sends, and tracks the result. The manager key never leaves your process.

<Note>
  The SDK targets the manager API described in the [API reference](/api-reference/introduction). Use it when you run a bot or script that manages a vault. To click through the same actions, use the [Telegram bot](/managers/telegram-bot).
</Note>

## Install

The package is not on npm. `sdk/package.json` is marked `private`, so for now you consume a packed tarball built from the `sdk/` repository:

```sh theme={null}
cd sdk && yarn build && yarn pack --filename ../my-bot/vendor/hedginvault-sdk.tgz
cd ../my-bot && yarn add file:./vendor/hedginvault-sdk.tgz @solana/web3.js
```

`@solana/web3.js` (`^1.98.4`) is a peer dependency. Install it yourself so the SDK and your code share one copy of `Keypair`, `PublicKey`, and `VersionedTransaction`.

The SDK builds to CommonJS and uses the global `fetch` and `AbortSignal.timeout`, so it needs Node 18 or later. It has two runtime dependencies, `zod` and `bs58`.

## Get an API key

A manager key looks like `hv1_<id>_<secret>`. A Hedgin admin issues it from the admin dashboard. Each key is bound to one manager wallet and carries a list of allowed actions, called scopes. See [Key scopes](/sdk/actions#key-scopes) for what each SDK call needs.

Keep the key and the wallet keypair in your secret store. The examples read the API key from `HEDGE_API_KEY` and the keypair from a Solana CLI JSON file.

## Create a client and run an action

`createHedgeClient` returns a `HedgeClient`. `keypairSigner` wraps a `Keypair` as a `TransactionSigner`, and `keypairFromFile` reads a Solana CLI keypair file.

```ts theme={null}
import { createHedgeClient, keypairFromFile, keypairSigner } from "@hedginvault/sdk";

const hedge = createHedgeClient({ apiKey: process.env.HEDGE_API_KEY ?? "" });
const signer = keypairSigner(keypairFromFile("/secure/path/manager.json"));

const [vault] = await hedge.listVaults();
if (!vault) throw new Error("This key manages no vaults");
const holdings = await hedge.getHoldings(vault.address);

const outcome = await hedge.execute(
  {
    action: "jupiter/swap",
    vault: vault.address,
    sourceMint: holdings.depositToken.mint,
    destinationMint: "So11111111111111111111111111111111111111112",
    amount: "1000000", // base units: 1 USDC
    slippageBps: 50,
  },
  signer,
  { onProgress: (progress) => console.log(progress) },
);
console.log(outcome.kind);
```

`execute` builds the transaction, inspects it, signs it, sends it, and polls until it lands or fails. The result is an `Outcome`.

### Client options

`createHedgeClient` takes a `HedgeClientOptions` object.

| Option | Type | Default | Meaning |
| - | - | - | - |
| `apiKey` | `string` | Required | The `hv1_…` manager key. Sent as a bearer token. |
| `baseUrl` | `string` | `https://hedgin.xyz` | The site origin. The API base URL ending in `/api/external/v1` also works. |
| `programId` | `string` | `HEDGE_VAULT_PROGRAM_ID` | The Hedge Vault program the signing policy allows. Override only for a non-production deployment. |
| `maxComputeUnitPriceMicroLamports` | `bigint` | `100_000n` | The highest priority fee the SDK signs, in microLamports per compute unit. |
| `fetch` | `typeof fetch` | Global `fetch` | A replacement `fetch`, for tests or a proxy. |

```ts theme={null}
const hedge = createHedgeClient({
  apiKey: process.env.HEDGE_API_KEY ?? "",
  baseUrl: "https://hedgin.xyz",
  maxComputeUnitPriceMicroLamports: 50_000n,
});
```

Reads time out after 10 seconds and builders after 30 seconds. A builder simulates on chain and can call Jupiter, so it gets more time.

## Read the outcome

`execute` and `onboardPhoenix` return an `Outcome`. Check `outcome.kind` before you act on anything else.

| Kind | Meaning | What to do |
| - | - | - |
| `confirmed` | Every transaction landed. `created` holds the new `vault` or `position` address when the action made one. | Done. |
| `refused` | The API built a transaction the SDK will not sign. Nothing was sent. `reason` says why. | Report it. Do not bypass the policy. |
| `failed` | The API rejected the request, or a transaction failed on chain. `code` and `message` say why. | Earlier transactions in a batch may have landed. Read state before you retry. |
| `unresolved` | A transaction was sent, but its result is unknown after 120 seconds. `pending` lists the signatures. | Look the signatures up on an explorer. Do not resend. |

Every kind carries `signatures`, the signatures of everything sent so far. See [Execute and safety](/sdk/safety) for how `execute` reaches each outcome and why it never rebuilds after an ambiguous send.

## Amounts are strings

Token amounts cross JSON as base-unit integer strings, such as `"1000000"` for 1 USDC. The SDK types them as `BaseUnitString` and never uses a JavaScript `number` for an amount. Convert display values with `parseUnits` and `formatUnits`. See [Units and helpers](/sdk/reads#units-and-helpers).

## Where to go next

<CardGroup cols={2}>
  <Card title="Reads" href="/sdk/reads">
    Every read method, with its route and return type.
  </Card>

  <Card title="Actions" href="/sdk/actions">
    Every action that `execute` runs, and the key scope each needs.
  </Card>

  <Card title="Execute and safety" href="/sdk/safety">
    The signing policy, batches, continuations, and unknown outcomes.
  </Card>

  <Card title="API checker" href="/sdk/api-checker">
    Probe a live API for drift from the SDK's schemas.
  </Card>
</CardGroup>


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