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

# Claim Custom Quote Fees

> Discover and claim custom-quote Fee Share entitlements, pool fees, holding balances, and shared partner or deployer balances.

Custom-quote DBC and direct DAMM Fee Share launches pay recipients in the **original quote token**. Bags does not automatically convert those fees to SOL or USDC. A token transfer fee can reduce what reaches the destination wallet.

Use this guide for launches created with a Fee Share config. Existing [SOL recipient claims](/how-to-guides/claim-fees) and [DAMM v2 custody claims](/how-to-guides/launch-token-custody#5-claim-creator-fees) keep their own flows. A direct DAMM pool or non-SOL mint alone does not tell you which fee model it uses.

## Prerequisites

* An API key from the [Bags Developer Portal](https://dev.bags.fm).
* The wallet entitled to the fees and a signer for it.
* The base token mint when claiming a specific token.
* SOL for any rent, reimbursement, or transaction costs assigned to your wallet. Sponsorship does not make every claim cost-free.
* A client that can execute [Transaction Plans](/principles/transaction-plans). The examples request v0.

All requests use `https://public-api-v2.bags.fm/api/v1` with the `x-api-key` header. Replace uppercase placeholders before sending.

## 1. Discover Balances

For one token, call [Get Custom Quote Claimable Position for a Token](/api-reference/get-claimable-position-solo-v2):

```bash theme={null}
curl 'https://public-api-v2.bags.fm/api/v1/token-launch/claimable-position/solo/v2?wallet=YOUR_WALLET&tokenMint=TOKEN_MINT' \
  -H 'x-api-key: YOUR_API_KEY'
```

For the wallet's full set of positions and shared role balances, use [Get Custom Quote Claimable Positions](/api-reference/get-claimable-positions-v2):

```bash theme={null}
curl 'https://public-api-v2.bags.fm/api/v1/token-launch/claimable-positions/v2?wallet=YOUR_WALLET' \
  -H 'x-api-key: YOUR_API_KEY'
```

Read `response.items`, `response.complete`, and `response.issues`. HTTP 200 can still contain unavailable sources. An unavailable amount is `null`, not zero; preserve restricted entries and explain their `availability.reason`.

Each item carries its exact `asset.mint`, `asset.tokenProgram`, and raw amount string. Use `BigInt(item.rawAmount)` only after checking for null; do not convert raw amounts to JavaScript numbers. Decimals can be unknown, and display multipliers require separate evidence. Missing valuation does not prevent an otherwise valid claim.

## 2. Choose What to Claim

| Discovered `source.kind` | Meaning                                                             | Claim request                                                                |
| ------------------------ | ------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `pair_entitlement`       | Fees already credited to this recipient's pair ledger               | `source: { "kind": "pair" }`                                                 |
| `pool_estimate`          | Fees still in the identified upstream pool                          | `source: { "kind": "pool", "protocol": "dbc" or "damm_v2", "pool": "POOL" }` |
| `holding_balance`        | Tokens moved into the user's holding vault by an earlier settlement | `source: { "kind": "holding", "authority": "HOLDING_AUTHORITY" }`            |
| `role_balance`           | A shared partner or deployer balance for this quote                 | Use the shared vault endpoint in step 4                                      |

You can also request `source: { "kind": "position" }` (or omit `source`) to build the recipient flow across applicable pool fees, pair entitlement, and a holding balance. This is useful for a current config recipient. Use the explicit holding source to withdraw after removal from a config.

Do not submit both a whole-position claim and separate claims from its old discovery results. Confirm the chosen plan, then fetch balances again before building further claims. A pool-specific claim also settles the wallet's pair entitlement; it is not a second independent income source.

## 3. Build and Execute the Claim Plan

Call [Create Custom Quote Claim Plan](/api-reference/create-claim-transactions-v2):

```bash theme={null}
curl -X POST 'https://public-api-v2.bags.fm/api/v1/token-launch/create-claim-txs/v2' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'content-type: application/json' \
  -d '{
    "feeClaimer": "YOUR_WALLET",
    "tokenMint": "TOKEN_MINT",
    "quoteMint": "QUOTE_MINT",
    "source": { "kind": "position" },
    "transactionFormat": "v0"
  }'
```

Use the exact quote from discovery. To withdraw a holding balance, replace `source` with:

```json theme={null}
{
  "kind": "holding",
  "authority": "HOLDING_AUTHORITY_FROM_DISCOVERY"
}
```

The returned plan is `response`, not `response.plan`. Follow [Transaction Plans](/principles/transaction-plans) for signed fee ceilings, setup stages, co-signing, and confirmation. Do not send the JSON response itself to an RPC endpoint.

A direct recipient claim settles the **gross entitlement**. The wallet receives the net amount after any token withholding. A force-to-holding operation has already settled that pair entitlement; withdrawing the holding balance later is neither another settlement nor newly earned fees. Holding withdrawals pay the available balance and remain possible after the user leaves the recipient list.

## 4. Claim Partner and Deployer Balances

Use a `role_balance` entry from wallet discovery with the existing [Claim DAMM v2 Vault](/api-reference/claim-damm-v2-vault) endpoint. Despite its path name, this endpoint withdraws the shared role vault used by both custom-quote Fee Share receipts and custody receipts.

```bash theme={null}
curl -X POST 'https://public-api-v2.bags.fm/api/v1/token-launch/damm-v2/claim-vault' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'content-type: application/json' \
  -d '{
    "kind": "partner",
    "wallet": "YOUR_WALLET",
    "quoteMint": "QUOTE_MINT",
    "transactionFormat": "v0"
  }'
```

Use `kind: "deployer"` for a deployer balance. Supplying `transactionFormat` or `feeLimits` opts into bounded construction; omitting both preserves the existing endpoint behavior.

This endpoint returns the existing `response.transaction` **base58** string and `response.claimable`, not a staged plan. Extended requests also return format/encoding metadata and `claimable.claimableAmountRaw`. For v0, decode with `VersionedTransaction.deserialize(bs58.decode(response.transaction))`, co-sign with the owner wallet while retaining the sponsor signature, then submit and confirm. Do not use the base64 plan decoder for this response.

Shared vault balances can contain Fee Share receipts, custody receipts, and unsolicited transfers. One withdrawal can pay all of them; it cannot establish how much each source earned. Treat withdrawals as balance movement, not additional revenue. The destination remains the role owner's token account.

## 5. Handle Unavailable or Interrupted Claims

| Condition                                                | What to do                                                                                                 |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `asset_frozen`, `asset_paused`, or `transfer_restricted` | Keep the position visible and show why it cannot currently transfer                                        |
| `pair_shortfall`                                         | Claims wait until the pair has backing for all outstanding entitlements; do not represent the debt as zero |
| `rpc_unavailable` or `metadata_unavailable`              | Report unavailable evidence and retry the read later                                                       |
| `nothing_to_claim`                                       | Refresh discovery; another confirmed action may already have settled the balance                           |
| `fee_limit_exceeded`                                     | Review the new token fee before approving replacement limits                                               |
| Uncertain submission                                     | Stop, reconcile the original signature and state, then resume only unresolved work                         |

For a claim-all interface, skip clearly unavailable positions with an explicit report. Do not continue sending other claims after an uncertain submission. After each confirmed plan, refresh discovery so later requests use current balances.

## Endpoints Used

* [Get Custom Quote Claimable Positions](/api-reference/get-claimable-positions-v2)
* [Get Custom Quote Claimable Position for a Token](/api-reference/get-claimable-position-solo-v2)
* [Create Custom Quote Claim Plan](/api-reference/create-claim-transactions-v2)
* [Claim DAMM v2 Vault](/api-reference/claim-damm-v2-vault)