> ## 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. # Resource Management > Manage affiliates, fee invoice visibility, webhooks, accumulation addresses, and liquidation addresses through the Orchestra resource API. ## Affiliates Affiliate profiles let you register a partner-scoped app-fee recipient with a payout destination on any supported chain under a stable `affiliateId`, then reference that id in quote requests. ### PUT /v1/affiliates/:affiliateId Create or update an affiliate profile. Headers: ```bash theme={null} Authorization: Bearer fn_... X-Idempotency-Key: ``` Request (Solana USDC payout): ```json theme={null} { "feeBps": 50, "payoutChain": "solana", "payoutAsset": "USDC", "payoutAddress": "So1YourPayoutAddress" } ``` Request (EVM USDC payout): ```json theme={null} { "feeBps": 50, "payoutChain": "base", "payoutAsset": "USDC", "payoutAddress": "0xYourBaseUsdcAddress" } ``` All four fields are required. `payoutAddress` is where affiliate fee claims are settled, and it is validated against the chosen `payoutChain`'s address format. Supported `(payoutChain, payoutAsset)` combinations include: | Chain | Supported assets | | ---------- | ------------------------------------ | | `arbitrum` | `USDC`, `USDT`, `ETH` | | `base` | `USDC`, `cbBTC`, `ETH` | | `bsc` | `USDT`, `BNB` | | `bitcoin` | `BTC` | | `ethereum` | `DAI`, `USDC`, `USDT`, `WBTC`, `ETH` | | `monad` | `USDC`, `cbBTC` | | `optimism` | `USDC`, `USDT`, `ETH` | | `plasma` | `USDT` | | `polygon` | `USDC`, `USDC.e` | | `solana` | `USDC`, `SOL` | | `spark` | `BTC`, `USDB` | | `tempo` | `USDC`, `PathUSD` | | `tron` | `USDT`, `TRX` | Any `(chain, asset)` tuple in the live payout route table is accepted. This table lists the common ones. The full live list is available via [`GET /v1/affiliate-dashboard/payout-destinations`](#get-v1affiliate-dashboardpayout-destinations). The server validates the pair on `PUT /v1/affiliates/:affiliateId` and rejects unsupported combinations with `invalid_payout_destination`. Lightning is intentionally excluded. Lightning invoices are single-use and amount-bound, so they do not fit a static payout-address model. Response: ```json theme={null} { "affiliate": { "affiliateId": "flashpartner", "feeBps": 50, "payoutChain": "solana", "payoutAsset": "USDC", "payoutAddress": "So1YourPayoutAddress", "enabled": true, "createdAt": "2026-02-12T18:00:00.000Z", "updatedAt": "2026-02-12T18:00:00.000Z" } } ``` ### GET /v1/affiliates List affiliate profiles for your partner. Headers: ```bash theme={null} Authorization: Bearer fn_... ``` Query params: * `includeDisabled` (`true|false`, default `false`) * `limit` (default `200`, max `1000`) * `offset` (default `0`) ### DELETE /v1/affiliates/:affiliateId Disable an affiliate profile. Headers: ```bash theme={null} Authorization: Bearer fn_... X-Idempotency-Key: ``` Response: ```json theme={null} { "ok": true } ``` ### POST /v1/affiliates/:affiliateId/claim Create a claim for the full available affiliate fee balance. The available balance reflects the affiliate's 80% share after Flashnet's 20% platform cut. Minimum claim is \$1 USDC. Headers: ```bash theme={null} Authorization: Bearer fn_... X-Idempotency-Key: ``` No request body. The claim amount is the full available balance. Response: ```json theme={null} { "claimId": "acl_...", "affiliateId": "flashpartner", "amount": "5000000", "status": "processing", "createdAt": "2026-02-27T12:00:00.000Z" } ``` Claims require a payout destination configured on the affiliate profile (`payoutChain`, `payoutAsset`, `payoutAddress`). Claims are settled out of the same ledger where fees accrued (`solana:USDC` or `spark:USDB` depending on the orders that generated them) and delivered to the configured payout destination. The worker pipeline depends on the source ledger and destination: | Source | Destination | Pipeline | | ----------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | Solana USDC | Solana USDC | Single `deliver-solana-usdc` step | | Solana USDC | EVM stablecoin (USDC, USDT, and so on, on Base, Ethereum, Arbitrum, Optimism, Polygon, BSC, Monad) | Single delivery step from the Solana USDC float wallet | | Spark USDB | Spark USDB | Single `deliver-spark-usdb` step | | Spark USDB | Solana USDC or EVM stablecoin | Bridge USDB to USDC, then delivery | | Spark USDB | Spark BTC or Bitcoin BTC | Swap USDB to BTC, then deliver or withdraw. No USDC hop. | ### GET /v1/affiliate-dashboard/payout-destinations List every `(chain, asset)` tuple supported as a payout destination. The list is derived live from the orchestrator's pipeline route table, so it stays in sync with backend reality without doc updates whenever new supported chains are added. Use this for discovery instead of `GET /v1/orchestration/routes` (which only returns user-facing orchestration routes, not payout routes). Headers: ```bash theme={null} Authorization: Bearer fn_... ``` Response: ```json theme={null} { "destinations": [ { "chain": "arbitrum", "asset": "ETH" }, { "chain": "arbitrum", "asset": "USDC" }, { "chain": "arbitrum", "asset": "USDT" }, { "chain": "base", "asset": "cbBTC" }, { "chain": "base", "asset": "ETH" }, { "chain": "base", "asset": "USDC" }, { "chain": "bitcoin", "asset": "BTC" }, { "chain": "bsc", "asset": "BNB" }, { "chain": "bsc", "asset": "USDT" }, { "chain": "ethereum", "asset": "DAI" }, { "chain": "ethereum", "asset": "ETH" }, { "chain": "ethereum", "asset": "USDC" }, { "chain": "ethereum", "asset": "USDT" }, { "chain": "ethereum", "asset": "WBTC" }, { "chain": "monad", "asset": "USDC" }, { "chain": "monad", "asset": "cbBTC" }, { "chain": "optimism", "asset": "ETH" }, { "chain": "optimism", "asset": "USDC" }, { "chain": "optimism", "asset": "USDT" }, { "chain": "plasma", "asset": "USDT" }, { "chain": "polygon", "asset": "USDC" }, { "chain": "polygon", "asset": "USDC.e" }, { "chain": "solana", "asset": "SOL" }, { "chain": "solana", "asset": "USDC" }, { "chain": "spark", "asset": "BTC" }, { "chain": "spark", "asset": "USDB" }, { "chain": "tempo", "asset": "PathUSD" }, { "chain": "tempo", "asset": "USDC" }, { "chain": "tron", "asset": "TRX" }, { "chain": "tron", "asset": "USDT" } ] } ``` Entries are sorted alphabetically (case-insensitive) by `(chain, asset)`. Lightning is intentionally excluded. The list above is the live snapshot at the time of writing. Call the endpoint for the current canonical set. ### GET /v1/affiliates/:affiliateId/claims List claims for an affiliate. Headers: ```bash theme={null} Authorization: Bearer fn_... ``` Query params: * `limit` (default `50`, max `200`) * `offset` (default `0`) ## Partner webhooks Webhooks deliver order status changes for your partner account. ### POST /v1/webhooks Register an endpoint. Headers: ```bash theme={null} Authorization: Bearer fn_... X-Idempotency-Key: ``` ```json theme={null} { "url": "https://example.com/flashnet/webhooks" } ``` Response: ```json theme={null} { "webhookId": "wh_...", "secret": "hex string" } ``` `secret` is only returned at creation time. Store it. ### DELETE /v1/webhooks/:id Disable an endpoint. Headers: ```bash theme={null} Authorization: Bearer fn_... X-Idempotency-Key: ``` Response: ```json theme={null} { "ok": true } ``` See [Webhooks](/products/orchestration/webhooks) for signature verification, payload shape, and retry behavior. ## Partner fee invoices Invoice billing is enabled by Flashnet for approved partner-route combinations. Partners cannot opt into it by request. When invoice billing is enabled, the transaction does not deduct the platform fee from the user flow. The billed bps accrue to the partner and can be reviewed from the dashboard API. ### GET /v1/partner/dashboard/fee-invoices Read the partner-scoped fee amount owed, split between uninvoiced accruals and draft or issued invoices. Headers: ```bash theme={null} Authorization: Bearer fn_... ``` Query parameters: | Param | Required | Notes | | ------- | -------- | ------------------------------------------------------------- | | `limit` | No | Number of recent invoices to return. Default `25`, max `100`. | Response: ```json theme={null} { "asOf": "2026-05-04T18:00:00.000Z", "totals": [ { "feeAsset": "USDC", "totalFeeAmount": "1000000", "pendingAccrualAmount": "200000", "pendingAccrualCount": 1, "outstandingInvoiceAmount": "800000", "outstandingInvoiceCount": 1 } ], "pending": [ { "partnerId": "ptnr_...", "partnerName": "Example Partner", "billingPeriod": "2026-05", "feeAsset": "USDC", "accrualCount": 1, "totalVolumeAmount": "25000000", "totalFeeAmount": "200000", "oldestAccruedAt": "2026-05-04T17:30:00.000Z", "newestAccruedAt": "2026-05-04T17:30:00.000Z" } ], "recentInvoices": [ { "id": "pfi_...", "partnerId": "ptnr_...", "partnerName": "Example Partner", "billingPeriod": "2026-05", "feeAsset": "USDC", "totalVolumeAmount": "100000000", "totalFeeAmount": "800000", "accrualCount": 1, "status": "draft", "createdBy": "admin@example.com", "createdAt": "2026-05-04T18:00:00.000Z", "updatedAt": "2026-05-04T18:00:00.000Z", "issuedAt": null, "paidAt": null, "voidedAt": null } ] } ``` All amounts are in the fee asset's smallest units. `totalFeeAmount` in `totals` is `pendingAccrualAmount + outstandingInvoiceAmount`. Paid and void invoices are excluded from outstanding totals. ## Accumulation addresses Accumulation addresses are reusable deposit addresses on Solana and any supported chain. Each deposit automatically creates an order that delivers `BTC` or `USDB` on Spark. ### POST /v1/accumulation-addresses Create an accumulation address. Headers: ```bash theme={null} Authorization: Bearer fn_... X-Idempotency-Key: ``` Inline app fee recipients: ```json theme={null} { "label": "optional", "sourceChain": "solana", "sourceAsset": "USDC", "destinationAsset": "BTC", "recipientSparkAddress": "spark1...", "feeBps": 5, "slippageBps": 50, "appFees": [ { "recipient": "So1FeeRecipient...", "fee": 50 } ] } ``` Registered affiliates with per-address bps override: ```json theme={null} { "label": "optional", "sourceChain": "solana", "sourceAsset": "USDC", "destinationAsset": "BTC", "recipientSparkAddress": "spark1...", "feeBps": 5, "slippageBps": 50, "affiliateIds": [ "referrer-alice", { "affiliateId": "platform-fee", "feeBps": 25 } ] } ``` `appFees` and `affiliateIds` are both optional and mutually exclusive (use one or the other, not both). `affiliateIds` entries accept the same `string | { affiliateId, feeBps }` union shape as `POST /v1/orchestration/quote`. The fee plan you submit is validated at creation time and frozen onto the address. Every deposit processed through this address replays the same plan without re-evaluating affiliate profiles. See [Reusable Addresses](/products/orchestration/reusable-addresses#app-fees-and-affiliates) for details. Response: ```json theme={null} { "accumulationAddressId": "acu_...", "sourceChain": "solana", "sourceAsset": "USDC", "destinationAsset": "BTC", "recipientSparkAddress": "spark1...", "feeBps": 5, "slippageBps": 50, "enabled": true, "depositAddress": "So1...", "createdAt": "2026-02-04T01:00:00.000Z", "appFees": [ { "affiliateId": "platform-fee", "recipient": "So1PlatformPayoutAddress...", "feeBps": 25 } ], "subscriptions": [] } ``` The response `appFees` array reflects the frozen fee plan. Each entry always has `recipient` and `feeBps`. `affiliateId` is present for entries backed by a registered affiliate profile (the `recipient` is pulled from the profile's `payoutAddress`); inline `appFees` entries omit `affiliateId`. The array is omitted from the response when no fee plan was configured at creation. ### POST /v1/accumulation-addresses/sync Re-sync all enabled accumulation addresses into the configured deposit detection webhooks. Headers: ```bash theme={null} Authorization: Bearer fn_... X-Idempotency-Key: ``` ### GET /v1/accumulation-addresses List accumulation addresses. ### GET /v1/accumulation-addresses/:id Get a single accumulation address, including subscription status. ### DELETE /v1/accumulation-addresses/:id Disable an accumulation address. Headers: ```bash theme={null} Authorization: Bearer fn_... X-Idempotency-Key: ``` ## Liquidation addresses Liquidation addresses are reusable Bitcoin L1 deposit addresses. Each deposit automatically creates an order that delivers to any supported chain and asset. ### POST /v1/liquidation-addresses Create a liquidation address. Headers: ```bash theme={null} Authorization: Bearer fn_... X-Idempotency-Key: ``` Inline app fee recipients: ```json theme={null} { "label": "optional", "destinationChain": "ethereum", "destinationAsset": "USDC", "destinationAddress": "0x...", "slippageBps": 50, "feeBps": 5, "appFees": [ { "recipient": "So1FeeRecipient...", "fee": 50 } ] } ``` Registered affiliates with per-address bps override: ```json theme={null} { "label": "optional", "destinationChain": "ethereum", "destinationAsset": "USDC", "destinationAddress": "0x...", "slippageBps": 50, "feeBps": 5, "affiliateIds": [ "referrer-alice", { "affiliateId": "platform-fee", "feeBps": 25 } ] } ``` `appFees` and `affiliateIds` are both optional and mutually exclusive. `affiliateIds` entries accept the same `string | { affiliateId, feeBps }` union shape as `POST /v1/orchestration/quote`. The fee plan is frozen at creation time and replayed into every Bitcoin L1 deposit processed through the address. `appFees` inline recipients must be valid addresses on the fee settlement chain (Solana USDC for most routes, Spark USDB for USDB destinations), not the destination chain. See [Reusable Addresses](/products/orchestration/reusable-addresses#app-fees-and-affiliates) for details. Response: ```json theme={null} { "liquidationAddressId": "liq_...", "sparkAddress": "spark1...", "l1DepositAddress": "bc1...", "destination": { "chain": "ethereum", "asset": "USDC", "address": "0x..." }, "feeBps": 5, "slippageBps": 50, "enabled": true, "createdAt": "2026-02-04T01:00:00.000Z", "appFees": [ { "affiliateId": "platform-fee", "recipient": "So1PlatformPayoutAddress...", "feeBps": 25 } ] } ``` The response `appFees` array reflects the frozen fee plan. Each entry always has `recipient` and `feeBps`. `affiliateId` is present for entries backed by a registered affiliate profile; inline `appFees` entries omit it. The array is omitted when no fee plan was configured. ### GET /v1/liquidation-addresses List enabled liquidation addresses. ### GET /v1/liquidation-addresses/:id Get a single liquidation address (enabled or disabled). ### DELETE /v1/liquidation-addresses/:id Disable a liquidation address. Headers: ```bash theme={null} Authorization: Bearer fn_... X-Idempotency-Key: ``` ### POST /v1/liquidation-addresses/sync-blockdaemon Synchronize enabled liquidation addresses into Blockdaemon Streaming watchlists. Headers: ```bash theme={null} Authorization: Bearer fn_... X-Idempotency-Key: ```