Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.meteora.ag/llms.txt

Use this file to discover all available pages before exploring further.

The zap IDL exposes ledger helpers plus route-specific zap instructions. Most integrations should use the TypeScript SDK builders because they assemble token accounts, ledger transactions, downstream payloads, bin arrays, and cleanup transactions.

​
Instruction Index

InstructionTypeScript SDK pathUse
initialize_ledger_accountInternal to zap-in buildersCreate the user’s temporary UserLedger PDA.
close_ledger_accountInternal to zap-in buildersClose the ledger and send rent to rent_receiver.
set_ledger_balanceInternal to zap-in buildersSet one ledger side directly when the user already holds the pool token.
update_ledger_balance_after_swapInternal to zap-in buildersStore the post-swap token-account balance delta, capped by max_transfer_amount.
zap_outzapOut, zapOutThroughDammV2, zapOutThroughDlmm, zapOutThroughJupiterSwap a newly received token-account balance increase through a whitelisted downstream payload.
zap_in_damm_v2buildZapInDammV2TransactionAdd ledger balances to a DAMM v2 position, swap surplus, then add remaining liquidity.
zap_in_dlmm_for_initialized_positionrebalanceDlmmPositionRebalance an existing DLMM position using ledger balances and a selected strategy.
zap_in_dlmm_for_uninitialized_positionbuildZapInDlmmTransactionInitialize a new DLMM position and add liquidity using ledger balances.

​
Ledger Instructions

Zap-in flows use a short-lived ledger to keep token balances consistent across multiple transactions.
InstructionAccountsArgumentsBehavior
initialize_ledger_accountledger, owner, payer, system_programNoneInitializes UserLedger at ["user_ledger", owner] and stores owner.
close_ledger_accountledger, owner, rent_receiverNoneRequires ledger.owner == owner, closes the ledger, and sends rent to rent_receiver.
set_ledger_balanceledger, owneramount, is_token_aSets amount_a when is_token_a is true, otherwise sets amount_b.
update_ledger_balance_after_swapledger, token_account, ownerpre_source_token_balance, max_transfer_amount, is_token_aReads the current token account amount, stores min(current - pre_source_token_balance, max_transfer_amount) into the selected ledger side.
Use set_ledger_balance for a pool token the user already contributes directly. Use update_ledger_balance_after_swap when a previous swap transaction produced the token.

​
Zap Out

zap_out is a generic wrapper around a whitelisted downstream swap instruction.
InputRequirement
percentageMust be from 1 to 100.
payload_dataFirst 8 bytes must match a whitelisted DAMM v2, DLMM, or Jupiter V6 discriminator.
offset_amount_inMust point to an 8-byte u64 range inside payload_data.
pre_user_token_balanceMust be read before the upstream action that adds input tokens.
max_swap_amountCaps the computed swap amount.
remaining_accountsMust exactly match the downstream swap instruction account order.
Execution:
  1. Validate zap-out parameters and downstream discriminator.
  2. Read the post-action balance from user_token_in_account.
  3. Return without swapping if the balance did not increase.
  4. Compute swap_amount = min(balance_delta * percentage / 100, max_swap_amount).
  5. Overwrite the downstream payload amount at offset_amount_in.
  6. Invoke the downstream swap instruction with the provided remaining accounts.

​
DAMM v2 Zap In

zap_in_damm_v2 uses ledger balances to add liquidity to an existing DAMM v2 position.
AccountNotes
ledgerMutable UserLedger; owner must sign.
poolMutable DAMM v2 pool account.
positionMutable existing DAMM v2 position.
token_a_account, token_b_accountUser token accounts.
token_a_vault, token_b_vaultPool token vaults.
token_a_mint, token_b_mintPool token mints.
position_nft_accountPosition NFT token account proving position ownership to DAMM v2.
damm_program, damm_event_authorityDAMM v2 program and event authority.
ArgumentTypeUse
pre_sqrt_priceu128Pool square-root price observed before building the transaction.
max_sqrt_price_change_bpsu32Maximum allowed square-root price movement after the internal surplus swap.
Execution:
  1. Calculate liquidity from ledger token A/B amounts after transfer-fee exclusion.
  2. Add liquidity once so any following internal swap can still accrue pool fees to the position.
  3. Update the ledger with the amounts consumed by the first add-liquidity call.
  4. If one side remains, calculate a DAMM v2 swap2 amount for the surplus side and perform the swap through CPI.
  5. Check post_sqrt_price against pre_sqrt_price and max_sqrt_price_change_bps.
  6. Add liquidity again with the newly balanced token amounts.
  7. Update and log remaining ledger balances.
DAMM v2 rate-limited pools can require extra remaining accounts for the internal swap2 CPI. Preserve the remaining-account list generated by the SDK.

​
DLMM Zap In

DLMM zap-in uses DLMM rebalance_liquidity after constructing an add-liquidity distribution from the selected strategy.
InstructionPosition behaviorUse
zap_in_dlmm_for_initialized_positionposition is an existing DLMM positionRebalance or add liquidity to an existing position.
zap_in_dlmm_for_uninitialized_positionposition is an uninitialized signerCreate a DLMM position with initialize_position2, then rebalance liquidity into it.
ArgumentTypeUse
active_idi32Active bin expected by the client.
min_delta_idi32Lower bin offset from the pair active bin. Must be less than or equal to max_delta_id.
max_delta_idi32Upper bin offset from the pair active bin.
max_active_bin_slippageu16Maximum active-bin movement accepted by DLMM rebalance.
favor_x_in_active_idboolWhether the active bin allocation favors token X.
strategyStrategyTypeSpot, Curve, or BidAsk.
remaining_accounts_infoRemainingAccountsInfoDescribes transfer-hook and other DLMM remaining-account slices.
For uninitialized positions, Zap derives:
Derived valueFormula
lower_bin_idlb_pair.active_id + min_delta_id
widthmax_delta_id - min_delta_id + 1
The uninitialized position account must have the default owner and empty data, and must not equal owner or rent_payer.

​
Transaction Sequencing

StepTypical content
1. SetupCreate ATAs, wrap SOL if needed, and prepare any route-specific accounts.
2. SwapExecute Jupiter, DAMM v2, or DLMM swaps that produce pool token balances.
3. LedgerInitialize or reset UserLedger; set direct balances and record post-swap deltas.
4. ZapCall zap_in_damm_v2, zap_in_dlmm_for_uninitialized_position, or zap_in_dlmm_for_initialized_position.
5. CleanupClose UserLedger; unwrap SOL if needed.
For zap out, place the upstream action that creates the input token balance before the zap_out instruction in the same transaction or transaction sequence that preserves the pre-balance assumption.