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

# Fees

> Rates, earnings, and claims

Orchestra charges a platform fee and can collect partner-defined app or affiliate fees on an order.

## Read the quote

The platform rate and minimum depend on the partner and route. App and affiliate rates apply to the amount remaining after the platform fee. Flashnet's share comes out of the gross app or affiliate fee; it is not another deduction from the user's remaining amount. The default share is 20%, subject to configured fee policy.

* `feeAmount`: platform fee; `feeBps` is its rate.
* `appFeeAmount`: gross app or affiliate fee.
* `appFeePlatformCutAmount`: Flashnet's share of that fee.
* `sweepFeeAmount`: sweep fee.
* `networkCostAmount`: destination network cost.
* `roundingFeeAmount`: rounding fee.

Per-recipient entries report `amount`, `platformCutAmount`, and net `recipientAmount`. Use these returned amounts to reconcile earnings. Invoice-billed platform fees are billed separately rather than deducted as `feeAmount`.

On a quote, `totalFeeAmount` sums `feeAmount`, `roundingFeeAmount`, `appFeeAmount`, `sweepFeeAmount`, and `networkCostAmount`. Do not add `appFeePlatformCutAmount` again. Embedded pool or provider costs can affect output without a separate fee field; `totalFeeAmount` is not a measure of every economic cost. [ZeroConf](/orchestra/zeroconf) reports its deposit fee separately in sats.

Quote fee amounts use `feeAsset` and the decimals in `feeAssetDetails`. Accrued earnings use the returned settlement chain and asset. A claim pays to its recorded payout chain, asset, and address. These denominations can differ; interpret raw integer amounts using the relevant asset's decimals.

### Example

For an exact-in amount of 1,000 USD in a six-decimal stablecoin, assume a 5 bps platform fee, a 100 bps affiliate fee, and the default 20% share. This calculation excludes other costs, conversion, and minimum-fee adjustments.

The platform fee is 1,000 x 0.0005. The affiliate fee is 999.50 x 0.01, and Flashnet's share is 9.995 x 0.20.

| Component           | USD     |
| ------------------- | ------- |
| Platform fee        | 0.50    |
| Affiliate base      | 999.50  |
| Gross affiliate fee | 9.995   |
| Flashnet share      | 1.999   |
| Net earnings        | 7.996   |
| Remaining           | 989.505 |

The remaining amount is not a guaranteed delivery amount. Keep integer precision through the calculation rather than rounding intermediate values to cents.

## Attach an affiliate

Register the affiliate in the [partner dashboard](https://orchestra.flashnet.xyz/dashboard), or use `PUT /v1/affiliates/:affiliateId` with a server key and `X-Idempotency-Key`. The API requires `feeBps`, `payoutChain`, `payoutAsset`, and `payoutAddress` on every upsert. Rates are 1 through 9999 bps.

Add the registered ID to an authenticated quote request:

```json theme={null}
{ "affiliateIds": ["acme_app"] }
```

Server keys can instead pass `{ "affiliateId": "acme_app", "feeBps": 100 }` as an array entry to override the rate for that request. Client keys cannot override rates; a configured client affiliate pin takes precedence over request IDs.

Inline `appFees` are an alternative on routes that support them: entries contain `recipient` and `fee` in bps. Each rate is 1 through 9999, with at most 16 entries and a combined cap of 10000 bps. Do not combine `appFees` with affiliate IDs. Client keys cannot set inline app fees, and xchain routes reject them; use registered affiliates there.

## Available and claimable

Affiliate earnings accrue net of Flashnet's share. A quoted fee becomes available only after it is recorded and custody is confirmed. Available fees are unpaid and not reserved by another claim.

A claim reserves fees from a selected settlement balance for its recorded payout destination. The server determines the claim amount; partial-amount claims are not supported.

Claimability also depends on the payout path. A normalized USD 1 minimum applies, but the route can require more or be unavailable. Read `claimable`, `unclaimableCode`, and `unclaimableReason` for each balance. Claim creation rechecks eligibility and can require a live payout quote.

<Warning>
  Changing an affiliate's payout destination affects subsequently recorded fees. Existing fees with a recorded destination keep it. Review the destination and address for the balance before claiming.
</Warning>

## Claim through the API

Use a partner server key. Affiliate reporting client keys cannot create or inspect claims through these endpoints. For the browser workflow, see [Claim fees](/orchestra/dashboard#claim-fees).

1. Read `GET /v1/affiliate-dashboard/:affiliateId/stats`. Inspect `stats.claimBalances` for the settlement asset, recorded payout destination, available amount, and eligibility.
2. Submit `POST /v1/affiliates/:affiliateId/claim` with `Authorization: Bearer SERVER_KEY` and `X-Idempotency-Key`. Generate a key for each new claim request and reuse it with the same body when retrying that request.
3. Store the returned `claim.id`. Follow `GET /v1/affiliates/:affiliateId/claims/:id`, or list claims at `GET /v1/affiliates/:affiliateId/claims`.

The optional JSON body selects a balance, never a new payout address. Supply `settlementChain` and `settlementAsset` together. To select a recorded destination, also supply all of `payoutChain`, `payoutAsset`, and `payoutAddress`. There is no `amount` field.

For a returned Solana USDC balance with a Solana USDC payout, the body is:

```json theme={null}
{
  "settlementChain": "solana",
  "settlementAsset": "USDC",
  "payoutChain": "solana",
  "payoutAsset": "USDC",
  "payoutAddress": "RECIPIENT_ADDRESS"
}
```

Replace `RECIPIENT_ADDRESS` with that balance's recorded address. Use the returned chain and asset values for other balances. When several settlement balances exist, the settlement pair is required.

HTTP `201` means the claim was created and payment queued. A `processing` claim has not confirmed delivery; `completed` means its payout completed. For `failed` claims, inspect the failure and current balance before submitting another claim. Funds are not always released immediately. Settlement amounts and delivered payout amounts can differ because of conversion and payout costs.