Resource Management

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.

curl -sS -X PUT "https://orchestration.flashnet.xyz/v1/affiliates/flashpartner" \
  -H "Authorization: Bearer fn_..." \
  -H "X-Idempotency-Key: affiliate:$(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "feeBps": 50,
    "payoutChain": "solana",
    "payoutAsset": "USDC",
    "payoutAddress": "So1YourPayoutAddress"
  }'

Request (EVM USDC payout):

{
  "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. Any (chain, asset) tuple in the live payout route table is accepted. Call GET /v1/affiliate-dashboard/payout-destinations for the current set. 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:

{
  "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.

curl -sS "https://orchestration.flashnet.xyz/v1/affiliates?includeDisabled=true" \
  -H "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.

curl -sS -X DELETE "https://orchestration.flashnet.xyz/v1/affiliates/flashpartner" \
  -H "Authorization: Bearer fn_..." \
  -H "X-Idempotency-Key: affiliate-disable:$(uuidgen)"

Response:

{ "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.

curl -sS -X POST "https://orchestration.flashnet.xyz/v1/affiliates/flashpartner/claim" \
  -H "Authorization: Bearer fn_..." \
  -H "X-Idempotency-Key: claim:$(uuidgen)"

No request body. The claim amount is the full available balance. Response:

{
  "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 the fees accrued and delivered to the configured payout destination. How an order’s fees resolve to a settlement ledger is documented in Fees. Valid payout destinations come from GET /v1/affiliate-dashboard/payout-destinations.

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).

curl -sS "https://orchestration.flashnet.xyz/v1/affiliate-dashboard/payout-destinations" \
  -H "Authorization: Bearer fn_..."

Response:

{
  "destinations": [
    { "chain": "arbitrum", "asset": "ETH" },
    { "chain": "arbitrum", "asset": "USDC" },
    { "chain": "bitcoin", "asset": "BTC" },
    { "chain": "solana", "asset": "USDC" },
    { "chain": "spark", "asset": "USDB" }
  ]
}

Entries are sorted alphabetically (case-insensitive) by (chain, asset). Lightning is intentionally excluded. The example above is truncated. Call the endpoint for the current canonical set.

GET /v1/affiliates/:affiliateId/claims

List claims for an affiliate.

curl -sS "https://orchestration.flashnet.xyz/v1/affiliates/flashpartner/claims?limit=50" \
  -H "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

curl -sS -X POST "https://orchestration.flashnet.xyz/v1/webhooks" \
  -H "Authorization: Bearer fn_..." \
  -H "X-Idempotency-Key: webhook:$(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/flashnet/webhooks" }'

Response:

{
  "webhookId": "wh_...",
  "secret": "hex string"
}

secret is only returned at creation time. Store it.

DELETE /v1/webhooks/:id

Disable an endpoint.

curl -sS -X DELETE "https://orchestration.flashnet.xyz/v1/webhooks/wh_..." \
  -H "Authorization: Bearer fn_..." \
  -H "X-Idempotency-Key: webhook-disable:$(uuidgen)"

Response:

{ "ok": true }

See 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.

curl -sS "https://orchestration.flashnet.xyz/v1/partner/dashboard/fee-invoices?limit=25" \
  -H "Authorization: Bearer fn_..."

Query parameters:

Param	Required	Notes
`limit`	No	Number of recent invoices to return. Default `25`, max `100`.

Response:

{
  "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": "[email protected]",
      "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. Inline app fee recipients:

curl -sS -X POST "https://orchestration.flashnet.xyz/v1/accumulation-addresses" \
  -H "Authorization: Bearer fn_..." \
  -H "X-Idempotency-Key: accumulation:$(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "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:

{
  "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 for details. Response:

{
  "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-register your enabled Solana-sourced accumulation addresses into the configured Helius deposit-detection webhooks. Relay-backed addresses (EVM and other non-Solana sources) are not touched; use the per-address reindex endpoint for those.

curl -sS -X POST "https://orchestration.flashnet.xyz/v1/accumulation-addresses/sync" \
  -H "Authorization: Bearer fn_..." \
  -H "X-Idempotency-Key: accumulation-sync:$(uuidgen)"

POST /v1/accumulation-addresses/:idOrAddress/reindex

Ask Relay to rescan one Relay-backed deposit address for missed deposits. :idOrAddress accepts the acu_... id or the reusable deposit address itself. If Relay finds a balance, it queues the sweep and the normal fill-detection path creates the order. Native Solana accumulation addresses return 400; they have no Relay deposit address to rescan.

curl -sS -X POST "https://orchestration.flashnet.xyz/v1/accumulation-addresses/acu_.../reindex" \
  -H "Authorization: Bearer fn_..." \
  -H "X-Idempotency-Key: accumulation-reindex:$(uuidgen)"

Like address creation, this endpoint accepts client keys with the accumulation:create scope in addition to server keys.

GET /v1/accumulation-addresses

List accumulation addresses.

curl -sS "https://orchestration.flashnet.xyz/v1/accumulation-addresses" \
  -H "Authorization: Bearer fn_..."

GET /v1/accumulation-addresses/:id

Get a single accumulation address, including subscription status.

curl -sS "https://orchestration.flashnet.xyz/v1/accumulation-addresses/acu_..." \
  -H "Authorization: Bearer fn_..."

DELETE /v1/accumulation-addresses/:id

Disable an accumulation address.

curl -sS -X DELETE "https://orchestration.flashnet.xyz/v1/accumulation-addresses/acu_..." \
  -H "Authorization: Bearer fn_..." \
  -H "X-Idempotency-Key: accumulation-disable:$(uuidgen)"

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. Inline app fee recipients:

curl -sS -X POST "https://orchestration.flashnet.xyz/v1/liquidation-addresses" \
  -H "Authorization: Bearer fn_..." \
  -H "X-Idempotency-Key: liquidation:$(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "optional",
    "destinationChain": "ethereum",
    "destinationAsset": "USDC",
    "destinationAddress": "0x...",
    "slippageBps": 50,
    "feeBps": 5,
    "appFees": [
      { "recipient": "So1FeeRecipient...", "fee": 50 }
    ]
  }'

Registered affiliates with per-address bps override:

{
  "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 for details. Response:

{
  "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.

curl -sS "https://orchestration.flashnet.xyz/v1/liquidation-addresses" \
  -H "Authorization: Bearer fn_..."

GET /v1/liquidation-addresses/:id

Get a single liquidation address (enabled or disabled).

curl -sS "https://orchestration.flashnet.xyz/v1/liquidation-addresses/liq_..." \
  -H "Authorization: Bearer fn_..."

GET /v1/liquidation-addresses/orders

List the orders for a liquidation address. Provide exactly one of id or label; sending both, neither, or an empty label returns 400. An unknown or non-owned id returns 404; a label matching none of your addresses returns an empty list. label matches every address you own with that exact label (labels are not unique).

curl -sS "https://orchestration.flashnet.xyz/v1/liquidation-addresses/orders?id=liq_...&limit=50" \
  -H "Authorization: Bearer fn_..."

Query params:

id: a single liquidation address id (exactly one of id / label is required)
label: every liquidation address you own with this exact label
status (optional): filter to one order status; paused orders are hidden unless status=paused
limit (default 50, max 200)
offset (default 0)

Returns { orders, nextOffset }. Each order matches the GET /v1/orchestration/status order shape, including terminal (completed, failed, refunded) orders. Requires a server key; client keys are rejected.

DELETE /v1/liquidation-addresses/:id

Disable a liquidation address.

curl -sS -X DELETE "https://orchestration.flashnet.xyz/v1/liquidation-addresses/liq_..." \
  -H "Authorization: Bearer fn_..." \
  -H "X-Idempotency-Key: liquidation-disable:$(uuidgen)"

POST /v1/liquidation-addresses/sync-blockdaemon

Synchronize enabled liquidation addresses into Blockdaemon Streaming watchlists.

curl -sS -X POST "https://orchestration.flashnet.xyz/v1/liquidation-addresses/sync-blockdaemon" \
  -H "Authorization: Bearer fn_..." \
  -H "X-Idempotency-Key: liquidation-sync:$(uuidgen)"

Pay links

Pay links are durable payment links. Each click on the public /pay/:shortId URL creates a fresh Lightning order delivered to the link’s recipient. All pay-link endpoints require a server key (fn_...); client keys are rejected. See Pay Links for the product flow and frontend integration.

POST /v1/pay-links

Create a pay link.

curl -sS -X POST "https://orchestration.flashnet.xyz/v1/pay-links" \
  -H "Authorization: Bearer fn_..." \
  -H "X-Idempotency-Key: paylink:$(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationChain": "solana",
    "destinationAsset": "USDC",
    "recipientAddress": "So1YourSolanaAddress...",
    "amountFiatUsd": "50.00",
    "label": "Tip jar"
  }'

Request body:

Field	Required	Type	Notes
`destinationChain`	Yes	string	`spark`, `solana`, or a supported EVM chain (e.g. `base`, `tron`). The route `lightning:BTC -> chain:asset` must exist, otherwise `unsupported_route`.
`destinationAsset`	Yes	string	A stablecoin the destination chain supports on a `lightning:BTC` route (e.g. `USDB`, `USDC`). Check `GET /v1/orchestration/routes`.
`recipientAddress`	Yes	string	Destination address, validated against the chain’s address format
`amountOut`	One of	string	Desired output in smallest units. Stablecoin amounts must be whole cents. Receiver gets exactly this; sender pays it plus fees.
`amountFiatUsd`	One of	string	Sender’s USD amount as a decimal string (e.g. `"50.00"`). Range $1.00 to$ 50,000.00.
`affiliateId`	No	string	Must reference an affiliate registered via `PUT /v1/affiliates/:affiliateId`
`label`	No	string	Partner-facing label, max 255 characters

Exactly one of amountOut or amountFiatUsd must be set. Response (201):

{
  "payLink": {
    "id": "pl_abc123",
    "shortId": "DNHKySOZ",
    "destinationChain": "solana",
    "destinationAsset": "USDC",
    "recipientAddress": "So1YourSolanaAddress...",
    "amountOut": null,
    "amountFiatUsd": "50.00",
    "amountFiatCurrency": "USD",
    "affiliateId": null,
    "label": "Tip jar",
    "enabled": true,
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "shortUrl": "https://orchestration.flashnet.xyz/pay/DNHKySOZ"
  }
}

Exactly one of amountOut or amountFiatUsd is set on every link; the other is null. shortUrl is the shareable payment URL.

GET /v1/pay-links

List pay links for your partner. Returns { "payLinks": [...] } with the same per-link shape as create.

curl -sS "https://orchestration.flashnet.xyz/v1/pay-links?includeDisabled=true" \
  -H "Authorization: Bearer fn_..."

Query params:

includeDisabled (true|false, default false)
limit (default 200, max 1000)
offset (default 0)

GET /v1/pay-links/:id

Get a single pay link by pl_... id. Returns 404 when the link does not exist or belongs to another partner.

curl -sS "https://orchestration.flashnet.xyz/v1/pay-links/pl_abc123" \
  -H "Authorization: Bearer fn_..."

DELETE /v1/pay-links/:id

Disable a pay link (soft delete). The public URL returns 404 afterward; orders created before disabling continue to process.

curl -sS -X DELETE "https://orchestration.flashnet.xyz/v1/pay-links/pl_abc123" \
  -H "Authorization: Bearer fn_..." \
  -H "X-Idempotency-Key: paylink-disable:$(uuidgen)"

Response:

{ "ok": true }

Overview

Concepts

Guides

Reference

Security

Resource Management

Affiliates

PUT /v1/affiliates/:affiliateId

GET /v1/affiliates

DELETE /v1/affiliates/:affiliateId

POST /v1/affiliates/:affiliateId/claim

GET /v1/affiliate-dashboard/payout-destinations

GET /v1/affiliates/:affiliateId/claims

Partner webhooks

POST /v1/webhooks

DELETE /v1/webhooks/:id

Partner fee invoices

GET /v1/partner/dashboard/fee-invoices

Accumulation addresses

POST /v1/accumulation-addresses

POST /v1/accumulation-addresses/sync

POST /v1/accumulation-addresses/:idOrAddress/reindex

GET /v1/accumulation-addresses

GET /v1/accumulation-addresses/:id

DELETE /v1/accumulation-addresses/:id

Liquidation addresses

POST /v1/liquidation-addresses

GET /v1/liquidation-addresses

GET /v1/liquidation-addresses/:id

GET /v1/liquidation-addresses/orders

DELETE /v1/liquidation-addresses/:id

POST /v1/liquidation-addresses/sync-blockdaemon

Pay links

POST /v1/pay-links

GET /v1/pay-links

GET /v1/pay-links/:id

DELETE /v1/pay-links/:id

​Affiliates

​PUT /v1/affiliates/:affiliateId

​GET /v1/affiliates

​DELETE /v1/affiliates/:affiliateId

​POST /v1/affiliates/:affiliateId/claim

​GET /v1/affiliate-dashboard/payout-destinations

​GET /v1/affiliates/:affiliateId/claims

​Partner webhooks

​POST /v1/webhooks

​DELETE /v1/webhooks/:id

​Partner fee invoices

​GET /v1/partner/dashboard/fee-invoices

​Accumulation addresses

​POST /v1/accumulation-addresses

​POST /v1/accumulation-addresses/sync

​POST /v1/accumulation-addresses/:idOrAddress/reindex

​GET /v1/accumulation-addresses

​GET /v1/accumulation-addresses/:id

​DELETE /v1/accumulation-addresses/:id

​Liquidation addresses

​POST /v1/liquidation-addresses

​GET /v1/liquidation-addresses

​GET /v1/liquidation-addresses/:id

​GET /v1/liquidation-addresses/orders

​DELETE /v1/liquidation-addresses/:id

​POST /v1/liquidation-addresses/sync-blockdaemon

​Pay links

​POST /v1/pay-links

​GET /v1/pay-links

​GET /v1/pay-links/:id

​DELETE /v1/pay-links/:id

Affiliates

PUT /v1/affiliates/:affiliateId

GET /v1/affiliates

DELETE /v1/affiliates/:affiliateId

POST /v1/affiliates/:affiliateId/claim

GET /v1/affiliate-dashboard/payout-destinations

GET /v1/affiliates/:affiliateId/claims

Partner webhooks

POST /v1/webhooks

DELETE /v1/webhooks/:id

Partner fee invoices

GET /v1/partner/dashboard/fee-invoices

Accumulation addresses

POST /v1/accumulation-addresses

POST /v1/accumulation-addresses/sync

POST /v1/accumulation-addresses/:idOrAddress/reindex

GET /v1/accumulation-addresses

GET /v1/accumulation-addresses/:id

DELETE /v1/accumulation-addresses/:id

Liquidation addresses

POST /v1/liquidation-addresses

GET /v1/liquidation-addresses

GET /v1/liquidation-addresses/:id

GET /v1/liquidation-addresses/orders

DELETE /v1/liquidation-addresses/:id

POST /v1/liquidation-addresses/sync-blockdaemon

Pay links

POST /v1/pay-links

GET /v1/pay-links

GET /v1/pay-links/:id

DELETE /v1/pay-links/:id