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

# SDK Reference

> Complete method-by-method reference for the @symmetry-hq/sdk package.

## Installation

```bash theme={null}
npm install @symmetry-hq/sdk @solana/web3.js @coral-xyz/anchor
```

## Imports

```typescript theme={null}
import {
  SymmetryCore,
  KeeperMonitor,
  RebalanceHandler,

  // Transaction types
  VaultCreationTx,
  TxPayloadBatchSequence,
  VersionedTxs,

  // Core data types
  GlobalConfig,
  Vault,
  VaultFilter,
  Intent,
  IntentFilter,
  RebalanceIntent,
  RebalanceIntentFilter,

  // Formatted types
  FormattedGlobalConfig,
  FormattedVault,
  FormattedAsset,
  FormattedIntent,
  FormattedRebalanceIntent,
  UIRebalanceIntent,

  // Settings input types
  EditCreatorSettings,
  EditManagerSettings,
  EditFeeSettings,
  EditScheduleSettings,
  EditAutomationSettings,
  EditLpSettings,
  EditMetadataSettings,
  EditDepositsSettings,
  EditForceRebalanceSettings,
  EditCustomRebalanceSettings,
  EditAddTokenSettings,
  EditUpdateWeightsSettings,
  EditMakeDirectSwapSettings,
  AddOrEditTokenInput,
  OracleInput,
  UpdateWeightsInput,
  MakeDirectSwapInput,
  Settings,
  TaskContext,
  TaskType,

  // Rebalance data types
  DepositData,
  PriceUpdatesData,
  AuctionData,
  MintData,
  RedeemData,
  ClaimBountyData,

  // Utilities
  getJupTokenLedgerAndSwapInstructions,
  getSwapPairs,
  isRebalanceRequired,
} from "@symmetry-hq/sdk";
```

## Token and Oracle Support

* Token standards: SPL and Token Extensions (`Token22`) are supported in vault composition and token flows (`addOrEditTokenTx`, `buyVaultTx`, `sellVaultTx`, `depositTokensTx`, `redeemTokensTx`, etc.).
* Oracle types: Pyth, Raydium CLMM, Raydium CPMM, and LST (SPL/Sanctum stake pool) are supported.

## SymmetryCore

### Constructor

```typescript theme={null}
const sdk = new SymmetryCore({
  connection: Connection,
  network: "devnet" | "mainnet",
  priorityFee?: number, // micro-lamports, default: 25,000
});
```

### Configuration

#### `setPriorityFee(priorityFee: number): void`

Updates the priority fee for all subsequent transactions.

#### `fetchGlobalConfig(): Promise<GlobalConfig>`

Returns the protocol-wide configuration account.

***

## Vault Methods

### Fetching

#### `fetchVault(vaultPubkey: string): Promise<Vault>`

Fetch a single vault by its on-chain account public key. Does not load oracle prices — call `loadVaultPrice()` separately.

#### `fetchMultipleVaults(vaultPubkeys: string[]): Promise<Map<string, Vault>>`

Batch-fetch multiple vaults. Returns a map keyed by public key.

#### `fetchAllVaults(filter?: VaultFilter): Promise<Vault[]>`

Fetch all vaults on-chain with an optional filter:

```typescript theme={null}
type VaultFilter = {
  type: "creator" | "host" | "manager";
  pubkey: string;
};
```

#### `fetchCreatedVaults(creatorPubkey: string): Promise<Vault[]>`

Shorthand for `fetchAllVaults({ type: "creator", pubkey })`.

#### `fetchHostedVaults(hostPubkey: string): Promise<Vault[]>`

Shorthand for `fetchAllVaults({ type: "host", pubkey })`.

#### `fetchManagedVaults(managerPubkey: string): Promise<Vault[]>`

Shorthand for `fetchAllVaults({ type: "manager", pubkey })`.

#### `fetchVaultsFromMints(mints: string[]): Promise<Map<string, Vault>>`

Fetch vaults by their token mint addresses.

#### `deriveVaultsByMints(mints: string[]): Promise<Map<string, string>>`

Derive vault account addresses from mint addresses without RPC calls.

#### `loadVaultPrice(vault: Vault): Promise<Vault>`

Loads live oracle prices, computes TVL and vault token price. Populates `vault.tvl`, `vault.price`, and per-asset price/value.

### Creation

#### `createVaultTx(params): Promise<VaultCreationTx>`

Creates a new vault. The `metadata_uri` is a URL (max 200 chars) pointing to a JSON file with the vault's metadata. The JSON should contain: `name` (vault token name), `symbol` (vault token ticker), `description` (vault description), `image` (token image/icon URL), and `cover` (vault cover image URL). You can include additional fields for your own integrations.

```typescript theme={null}
params: {
  creator: string,
  start_price: string,        // human USD terms, e.g. "1.0" = $1.00; encoded to program fraction format by the SDK
  name: string,               // max 32 chars
  symbol: string,             // max 10 chars
  metadata_uri: string,       // URL to JSON with name, symbol, description, image, cover
  host_platform_params?: {
    host_pubkey: string,
    host_deposit_fee_bps: number,
    host_withdraw_fee_bps: number,
    host_management_fee_bps: number,    // currently disabled in global config
    host_performance_fee_bps: number,   // currently disabled in global config
  },
}

// Returns:
interface VaultCreationTx extends TxPayloadBatchSequence {
  mint: string;
  vault: string;
}
```

### Editing

All edit methods accept a `TaskContext` and settings, returning `Promise<TxPayloadBatchSequence>`:

```typescript theme={null}
interface TaskContext {
  vault: string;
  manager: string;
  activation_timestamp?: number;
  expiration_timestamp?: number;
  min_bounty?: number;            // raw amount in bounty token's smallest units
  max_bounty?: number;            // raw amount in bounty token's smallest units
}
```

| Method                                    | Settings Type                 | Description                                                                               |
| ----------------------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------- |
| `editCreatorTx(ctx, settings)`            | `EditCreatorSettings`         | Transfer creator role                                                                     |
| `editManagersTx(ctx, settings)`           | `EditManagerSettings`         | Edit managers, weights, authorities                                                       |
| `editFeesTx(ctx, settings)`               | `EditFeeSettings`             | Update fee structure                                                                      |
| `editScheduleTx(ctx, settings)`           | `EditScheduleSettings`        | Configure repeating time cycles that gate deposits, automation, and management windows    |
| `editAutomationTx(ctx, settings)`         | `EditAutomationSettings`      | Configure automation                                                                      |
| `editLpTx(ctx, settings)`                 | `EditLpSettings`              | Configure LP settings                                                                     |
| `editMetadataTx(ctx, settings)`           | `EditMetadataSettings`        | Update name, symbol, and metadata URI (JSON with name, symbol, description, image, cover) |
| `editDepositsTx(ctx, settings)`           | `EditDepositsSettings`        | Enable/disable deposits                                                                   |
| `editForceRebalanceTx(ctx, settings)`     | `EditForceRebalanceSettings`  | Enable/disable force rebalance                                                            |
| `editCustomRebalanceTx(ctx, settings)`    | `EditCustomRebalanceSettings` | Enable/disable custom rebalance                                                           |
| `editAddTokenDelayTx(ctx, settings)`      | `EditAddTokenSettings`        | Set add-token time-lock                                                                   |
| `editUpdateWeightsDelayTx(ctx, settings)` | `EditUpdateWeightsSettings`   | Set weight-update time-lock                                                               |
| `editSwapDelayTx(ctx, settings)`          | `EditMakeDirectSwapSettings`  | Set direct-swap time-lock                                                                 |

### Token Composition

#### `addOrEditTokenTx(ctx, settings): Promise<TxPayloadBatchSequence>`

Add a new token or edit an existing token's oracle configuration. Settings type: `AddOrEditTokenInput`.

#### `updateWeightsTx(ctx, settings): Promise<TxPayloadBatchSequence>`

Update target weights for tokens in the vault. Settings type: `UpdateWeightsInput`.

#### `makeDirectSwapTx(ctx, settings, jup_swap_ix?): Promise<TxPayloadBatchSequence>`

Execute a direct token swap within the vault. Settings type: `MakeDirectSwapInput`.

***

## Intent Methods

### Fetching

#### `fetchIntent(intentPubkey: string): Promise<Intent>`

#### `fetchMultipleIntents(intentPubkeys: string[]): Promise<Map<string, Intent>>`

#### `fetchAllIntents(filter?: IntentFilter): Promise<Intent[]>`

```typescript theme={null}
type IntentFilter = {
  type: "manager" | "vault";
  pubkey: string;
};
```

#### `fetchCreatedIntents(creatorPubkey: string): Promise<Intent[]>`

#### `fetchVaultIntents(vaultPubkey: string): Promise<Intent[]>`

### Execution & Cancellation

#### `executeVaultIntentTx(params): Promise<TxPayloadBatchSequence>`

Execute a pending intent after its time-lock has elapsed.

```typescript theme={null}
params: { keeper: string, intent: string }
```

#### `executeDirectSwapVaultIntentTx(params): Promise<TxPayloadBatchSequence>`

Execute a pending direct swap intent with a flash swap.

```typescript theme={null}
params: {
  keeper: string,
  intent: string,
  jup_token_ledger_ix?: TransactionInstruction,
  jup_swap_ix: TransactionInstruction,
  jup_address_lookup_table_addresses?: PublicKey[],
}
```

#### `cancelVaultIntentTx(params): Promise<TxPayloadBatchSequence>`

```typescript theme={null}
params: { keeper: string, intent: string }
```

***

## Rebalance Intent Methods

### Fetching

#### `fetchRebalanceIntent(pubkey: string): Promise<UIRebalanceIntent>`

#### `fetchMultipleRebalanceIntents(pubkeys: string[]): Promise<Map<string, UIRebalanceIntent>>`

#### `fetchAllRebalanceIntents(filter?: RebalanceIntentFilter): Promise<UIRebalanceIntent[]>`

```typescript theme={null}
type RebalanceIntentFilter = {
  type: "owner" | "vault";
  pubkey: string;
};
```

#### `fetchOwnerRebalanceIntents(ownerPubkey: string): Promise<UIRebalanceIntent[]>`

#### `fetchVaultRebalanceIntents(vaultPubkey: string): Promise<UIRebalanceIntent[]>`

***

## Deposit & Withdrawal Methods

#### `buyVaultTx(params): Promise<TxPayloadBatchSequence>`

Deposit tokens into a vault to receive vault tokens.

```typescript theme={null}
params: {
  buyer: string,
  vault_mint: string,
  contributions: { mint: string, amount: number }[],  // amount in raw smallest units (e.g. lamports)
  rebalance_slippage_bps?: number,       // default: 100
  per_trade_rebalance_slippage_bps?: number,
  execution_start_time?: number,
  min_bounty_amount?: number,            // raw amount in bounty token's smallest units
  max_bounty_amount?: number,            // raw amount in bounty token's smallest units
}
```

#### `depositTokensTx(params): Promise<TxPayloadBatchSequence>`

Add more tokens to an existing deposit before locking.

```typescript theme={null}
params: {
  buyer: string,
  contributions: { mint: string, amount: number }[],  // amount in raw smallest units (e.g. lamports)
  rebalance_intent?: string,
  rebalance_intent_chain_data?: RebalanceIntent,
}
```

#### `lockDepositsTx(params): Promise<TxPayloadBatchSequence>`

Lock deposits and start the auction process.

```typescript theme={null}
params: { buyer: string, vault_mint: string }
```

#### `sellVaultTx(params): Promise<TxPayloadBatchSequence>`

Withdraw from a vault by burning vault tokens. If `keep_tokens` contains ALL mints from the vault's composition (including inactive), price updates and auctions are skipped — the withdrawal goes directly to the redeem stage. The user can then call `redeemTokensTx` themselves (no keeper needed) for the fastest withdrawal path. This is still two transactions: `sellVaultTx` + `redeemTokensTx`.

```typescript theme={null}
params: {
  seller: string,
  vault_mint: string,
  withdraw_amount: number,        // raw vault token amount to burn (smallest units)
  keep_tokens: string[],
  rebalance_slippage_bps?: number,
  per_trade_rebalance_slippage_bps?: number,
  execution_start_time?: number,
  min_bounty_amount?: number,     // raw amount in bounty token's smallest units
  max_bounty_amount?: number,     // raw amount in bounty token's smallest units
}
```

***

## Rebalancing Methods

All rebalancing methods are permissionless. The `keeper` parameter is simply the signing wallet.

#### `rebalanceVaultTx(params): Promise<TxPayloadBatchSequence>`

Trigger a keeper-initiated rebalance to restore target weights.

```typescript theme={null}
params: {
  keeper: string,
  vault_mint: string,
  rebalance_slippage_bps?: number,
  per_trade_rebalance_slippage_bps?: number,
  execution_start_time?: number,
  min_bounty_amount?: number,
  max_bounty_amount?: number,
}
```

#### `cancelRebalanceIntentTx(params): Promise<TxPayloadBatchSequence>`

```typescript theme={null}
params: { keeper: string, rebalance_intent: string }
```

***

## Oracle Price Updates

#### `updateTokenPricesTx(params): Promise<TxPayloadBatchSequence>`

Refresh on-chain oracle prices for all tokens during a rebalance. Handles Pyth VAA lifecycle automatically.

```typescript theme={null}
params: { keeper: string, vault: string, rebalance_intent: string }
```

#### `updatePythPriceFeedsTx(params): Promise<TxPayloadBatchSequence>`

Update specific Pyth price feeds standalone (no rebalance context). Find price feed IDs at [Pyth Price Feed IDs](https://docs.pyth.network/price-feeds/core/price-feeds/price-feed-ids).

```typescript theme={null}
params: { keeper: string, accounts: string[] }
```

***

## Flash Swaps

#### `flashSwapTx(params): Promise<TxPayloadBatchSequence>`

Execute an atomic flash swap during rebalance auctions.

```typescript theme={null}
params: {
  keeper: string,
  vault: string,
  rebalance_intent?: string,
  intent?: string,
  mint_in: string,
  mint_out: string,
  amount_in: number,
  amount_out: number,
  mode?: number,               // 0=exact_in, 1=exact_out, 2=IOC
  jup_token_ledger_ix?: TransactionInstruction,
  jup_swap_ix?: TransactionInstruction,
  jup_address_lookup_table_addresses?: PublicKey[],
}
```

***

## Minting & Redeeming

> These methods are permissionless. The `keeper` parameter is simply the signing wallet — any user can call them. Users performing a fast withdrawal (all `keep_tokens`) can call `redeemTokensTx` directly without waiting for a keeper.

#### `mintTx(params): Promise<TxPayloadBatchSequence>`

Mint vault tokens after a deposit rebalance completes auctions.

```typescript theme={null}
params: { keeper: string, rebalance_intent: string }
```

#### `redeemTokensTx(params): Promise<TxPayloadBatchSequence>`

Redeem underlying tokens from a withdrawal that has reached the redeem stage. For fast withdrawals (all `keep_tokens`), this is ready immediately after `sellVaultTx`.

```typescript theme={null}
params: { keeper: string, rebalance_intent: string }
```

***

## Bounties

#### `addBountyTx(params): Promise<TxPayloadBatchSequence>`

Add bounty to a vault for incentivizing keeper automation.

```typescript theme={null}
params: { keeper: string, vault: string, amount: number }  // amount in raw smallest units (e.g. lamports)
```

#### `claimBountyTx(params): Promise<TxPayloadBatchSequence>`

Distribute earned bounties to all keepers who completed tasks during the rebalance, award a task bounty to the caller, return unused bounty to the depositor, and close the rebalance intent account. Any wallet can call this.

```typescript theme={null}
params: { keeper: string, rebalance_intent: string }
```

***

## Fee Management

#### `withdrawVaultFeesTx(params): Promise<TxPayloadBatchSequence>`

Withdraw accumulated fees. Auto-detects which fee types the claimer can collect.

```typescript theme={null}
params: { claimer: string, vault: string }
```

#### `claimTokenFeesFromVaultTx(params): Promise<TxPayloadBatchSequence>`

Claim remaining fee tokens from an existing WithdrawVaultFees account.

```typescript theme={null}
params: { claimer: string, withdrawVaultFees: string }
```

### Fee Account Fetching

#### `fetchWithdrawVaultFees(pubkey: string): Promise<WithdrawVaultFees>`

#### `fetchMultipleWithdrawVaultFees(pubkeys: string[]): Promise<Map<string, WithdrawVaultFees>>`

#### `fetchAllWithdrawVaultFees(filter?: WithdrawVaultFeesFilter): Promise<WithdrawVaultFees[]>`

```typescript theme={null}
type WithdrawVaultFeesFilter = {
  type: "vault" | "manager" | "creator" | "host" | "symmetry";
  pubkey: string;
};
```

Convenience methods: `fetchVaultWithdrawVaultFees`, `fetchManagerWithdrawVaultFees`, `fetchCreatorWithdrawVaultFees`, `fetchHostWithdrawVaultFees`, `fetchSymmetryWithdrawVaultFees`.

***

## Lookup Tables

#### `rewriteLookupTablesTx(params): Promise<TxPayloadBatchSequence>`

Rebuild address lookup tables for a vault.

```typescript theme={null}
params: { signer: string, vault_mint: string, additional_accounts: string[] }
```

***

## Sending Transactions

#### `signAndSendTxPayloadBatchSequence(params): Promise<TransactionSignature[][]>`

Sign and send a TxPayloadBatchSequence. Batches are sent sequentially; transactions within a batch in parallel.

```typescript theme={null}
params: {
  txPayloadBatchSequence: TxPayloadBatchSequence,
  wallet: Wallet,
  simulateTransactions?: boolean,  // enables preflight-style send path; does NOT perform offline-only simulation
}
```

#### `signAndSendVersionedTxs(params): Promise<TransactionSignature[][]>`

Sign and send pre-built versioned transactions.

```typescript theme={null}
params: { versionedTxs: VersionedTxs, wallet: Wallet }
```

***

## Wallet Interface

```typescript theme={null}
interface Wallet {
  signTransaction<T extends Transaction | VersionedTransaction>(tx: T): Promise<T>;
  signAllTransactions<T extends Transaction | VersionedTransaction>(txs: T[]): Promise<T[]>;
  publicKey: PublicKey;
  payer?: Keypair;
}
```

***

## Standalone Utilities

| Export                                 | Signature                                                                                                    | Description                                     |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- |
| `getJupTokenLedgerAndSwapInstructions` | `(params) => Promise<{tokenLedgerInstruction, swapInstruction, addressLookupTableAddresses, quoteResponse}>` | Build Jupiter swap instructions for flash swaps |
| `getSwapPairs`                         | `(rebalanceIntent: RebalanceIntent, vault: Vault) => SwapPair[]`                                             | Compute required swap pairs for a rebalance     |
| `isRebalanceRequired`                  | `(vault: Vault, connection: Connection) => Promise<boolean>`                                                 | Check if vault needs rebalancing                |

<Note>
  The on-chain program uses "basket" terminology internally (e.g., `Basket`, `basket_fees`, `mint_basket`). The SDK and documentation use "vault" as the user-facing term. When reading on-chain data or error messages, "basket" and "vault" refer to the same thing.
</Note>

## Constants

| Constant                         | Value                                          | Description                           |
| -------------------------------- | ---------------------------------------------- | ------------------------------------- |
| `VAULTS_V3_PROGRAM_ID`           | `BASKT7aKd8n7ibpUbwLP3Wiyxyi3yoiXsxBk4Hpumate` | Program address                       |
| `COMPUTE_UNITS`                  | 1,000,000                                      | Default compute unit limit            |
| `PRIORITY_FEE`                   | 25,000                                         | Default priority fee (micro-lamports) |
| `MAX_SUPPORTED_TOKENS_PER_VAULT` | 100                                            | Max tokens per vault                  |
| `MAX_MANAGERS_PER_VAULT`         | 10                                             | Max managers per vault                |
| `MAX_ORACLES_PER_TOKEN`          | 4                                              | Max oracle sources per token          |
| `HUNDRED_PERCENT_BPS`            | 10,000                                         | 100% in basis points                  |