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

# Asset Retrieval

> Learn how to retrieve assets from a budget or incentive

<Warning>
  The One-Time Actions docs are under active development and will be subject to changes.
</Warning>

There are two locations assets are stored within the Boost Protocol, [budgets](/v2/boost-sdk/budgets/managed/retrieval) and [incentives](/v2/boost-sdk/incentives/erc20/overview).

Both budgets and incentives only allow authorized users to retrieve funds, requiring the sender to either be the owner, or have the [Roles.MANAGER](https://sdk.boost.xyz/enums/Roles.html#MANAGER)

## Retrieve from Budget

### `clawback`

The clawback function is used to reclaim available funds from the budget. Can only be called by owner or admin.

<CodeGroup>
  ```ts index.ts theme={null}
  await budget.clawback({
    amount: 0n,
    asset: '0xf3B2d0E4f2d8F453DBCc278b10e88b20d7f19f8D',
    target: account.address, // Address to receive the funds
  });
  ```
</CodeGroup>

<Tip>
  * Using `clawback` with `0n` will reclaim all available funds for the given asset.
  * Use the zero address (`0x0000000000000000000000000000000000000000`) to clawback native assets (ie. ETH).
</Tip>

#### Parameters

<ParamField path="transfer" type={<a href="https://sdk.boost.xyz/interfaces/FungibleTransferPayload.html">FungibleTransferPayload</a>} required>
  <Expandable title="properties">
    <ParamField path="amount" type="bigint" required>
      The amount of tokens to transfer.
    </ParamField>

    <ParamField path="asset" type="string" required>
      The address of the asset. Use zero address (0x0) for ETH transfers.
    </ParamField>

    <ParamField path="target" type="string" required>
      The address to receive the funds.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="parameters" type="Omit<wagmi.WriteContractParameters, 'address' | 'args' | 'functionName' | 'abi'>">
  Optional parameters to pass to the underlying `writeContract` method. Checkout [wagmi's documentation](https://wagmi.sh/core/api/actions/writeContract#parameters) for more information. `address`, `args`, `functionName`, `abi` are handled for you under the hood.
</ParamField>

#### Returns

<ResponseField name="Promise<boolean>" type="boolean">
  Returns true if the clawback was successful.
</ResponseField>

### `disburse`

Transfers available funds from the budget to a specified recipient. You must have the manager, admin or owner role to call this function.

<Warning>
  The `disburse` method is authorized for the `MANAGER` role. Be aware that this allows a manager to disburse funds from the budget at will. Make sure you trust the manager before giving them authorization.
</Warning>

<CodeGroup>
  ```ts index.ts theme={null}
  import { parseUnits } from "viem";

  await budget.disburse({
    amount: parseUnits('1', 18),
    asset: '0xf3B2d0E4f2d8F453DBCc278b10e88b20d7f19f8D',
    target: account.address, // Address to receive the funds
  });
  ```
</CodeGroup>

#### Parameters

<ParamField path="transfer" type={<a href="https://sdk.boost.xyz/interfaces/FungibleTransferPayload.html">FungibleTransferPayload</a>} required>
  <Expandable title="properties">
    <ParamField path="amount" type="bigint" required>
      The amount of tokens to transfer.
    </ParamField>

    <ParamField path="asset" type="string" required>
      The address of the asset. Use zero address (0x0) for ETH transfers.
    </ParamField>

    <ParamField path="target" type="string" required>
      The address to receive the funds.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="parameters" type="Omit<wagmi.WriteContractParameters, 'address' | 'args' | 'functionName' | 'abi'>">
  Optional parameters to pass to the underlying `writeContract` method. Checkout [wagmi's documentation](https://wagmi.sh/core/api/actions/writeContract#parameters) for more information. `address`, `args`, `functionName`, `abi` are handled for you under the hood.
</ParamField>

#### Returns

<ResponseField name="Promise<boolean>" type="boolean">
  Returns true if the disbursement was successful.
</ResponseField>

### `disburseBatch`

Transfers available funds from the budget to a list of specified recipients. You must have the manager, admin or owner role to call this function. This method is more gas-efficient for multiple transfers.

<CodeGroup>
  ```ts index.ts theme={null}
  import { parseUnits } from "viem";

  await budget.disburseBatch([
    {
      amount: parseUnits('1', 18),
      asset: '0xf3B2d0E4f2d8F453DBCc278b10e88b20d7f19f8D',
      target: recipient1.address, // Address to receive the funds
    },
    {
      amount: parseUnits('1', 18),
      asset: '0xf3B2d0E4f2d8F453DBCc278b10e88b20d7f19f8D',
      target: recipient2.address, // Address to receive the funds
    },
  ]);
  ```
</CodeGroup>

#### Parameters

<ParamField path="transfers" type={<a href="https://sdk.boost.xyz/interfaces/FungibleTransferPayload.html">FungibleTransferPayload[]</a>} required>
  <Expandable title="properties">
    <ParamField path="amount" type="bigint" required>
      The amount of tokens to transfer.
    </ParamField>

    <ParamField path="asset" type="string" required>
      The address of the asset. Use zero address (0x0) for ETH transfers.
    </ParamField>

    <ParamField path="target" type="string" required>
      The address to receive the funds.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="parameters" type="Omit<wagmi.WriteContractParameters, 'address' | 'args' | 'functionName' | 'abi'>">
  Optional parameters to pass to the underlying `writeContract` method. Checkout [wagmi's documentation](https://wagmi.sh/core/api/actions/writeContract#parameters) for more information. `address`, `args`, `functionName`, `abi` are handled for you under the hood.
</ParamField>

#### Returns

<ResponseField name="Promise<boolean>" type="boolean">
  Returns true if the disbursement was successful.
</ResponseField>

## Retrieve from Incentive

### `clawbackFromTarget`

The clawback function allows authorized users (admin or manager) to reclaim assets from a Boost's incentive back to its associated budget.

<Info>
  The amount reclaimed will be subject to protocol fee collection, so attempting to reclaim an amount where `reclaimAmount + calculatedProtocolFee > incentiveBalance` will revert with an `InsufficientFunds` error.
</Info>

<Warning>
  For `ERC20Incentive`, the amount specified in the clawback data must be an exact multiple of the reward value set in the incentive. Otherwise, the transaction will fail.
</Warning>

Depending on the type of incentive, calculating the clawback amount will be different.

<Tabs>
  <Tab title="ERC20Incentive">
    ```ts theme={null}
    // Example for fixed-reward ERC20 incentives
    const boost = await core.getBoost(0n)
    const budget = boost.budget
    const incentiveIndex = 0
    const incentive = boost.incentives.at(incentiveIndex)

    if (incentive instanceof ERC20Incentive) {
      // Calculate exact amount to clawback based on remaining claims
      const remainingClaims = await incentive.getRemainingClaimPotential()
      const rewardValue = await incentive.reward()
      const clawbackAmount = remainingClaims * rewardValue

      await budget.clawbackFromTarget(
        core.assertValidAddress(),
        incentive.buildClawbackData(clawbackAmount),
        boost.id,
        incentiveIndex
      );
    }
    ```
  </Tab>

  <Tab title="Variable Incentives">
    ```ts theme={null}
    // Example for variable-reward incentives
    const boost = await core.getBoost(0n)
    const budget = boost.budget
    const incentiveIndex = 0
    const incentive = boost.incentives.at(incentiveIndex)

    if (incentive instanceof ERC20VariableIncentive ||
        incentive instanceof ERC20VariableCriteriaIncentive) {
      // For variable incentives, we can directly get the remaining claimable amount
      const remainingFunds = await incentive.getRemainingClaimPotential()

      await budget.clawbackFromTarget(
        core.assertValidAddress(),
        incentive.buildClawbackData(remainingFunds),
        boost.id,
        incentiveIndex
      );
    }
    ```
  </Tab>
</Tabs>

<Tip>
  Using `clawbackFromTarget` will modify the amount of the asset marked as distributed via the budget.
</Tip>

#### Parameters

<ParamField path="target" type="address" required>
  The address of the contract implementing `clawback`, typically the Boost Core contract address.
</ParamField>

<ParamField path="data" type="Hex" required>
  The encoded clawback data payload. Generate this using `incentive.buildClawbackData(amount)`.
</ParamField>

<ParamField path="boostId" type="bigint | number" required>
  The ID of the Boost containing the target incentive.
</ParamField>

<ParamField path="incentiveId" type="bigint | number" required>
  The index of the incentive to clawback from.
</ParamField>

<ParamField path="parameters" type="Omit<wagmi.WriteContractParameters, 'address' | 'args' | 'functionName' | 'abi'>">
  Optional parameters to pass to the underlying `writeContract` method. Checkout [wagmi's documentation](https://wagmi.sh/core/api/actions/writeContract#parameters) for more information. `address`, `args`, `functionName`, `abi` are handled for you under the hood.
</ParamField>

#### Returns

<ResponseField name="Promise<[amount, Address]>" type="Promise<[amount, Address]>">
  Returns a tuple containing:

  * The amount that was successfully clawed back
  * The address of the token that was retrieved
</ResponseField>