Commissions

Every partner sets their own fee at signup. Your fee is added on top of GhostSwap's flat 2% baseline. Together they form the total markup that's charged on each swap; the markup is split automatically and tracked per-swap in USD.

The fee stack

User swaps 0.1 BTC → 3.31 ETH

Layer 1 — your fee (set at signup):                 1.0%   (example)
Layer 2 — GhostSwap baseline:                       2.0%   (always)
                                                    -----
Total markup user pays:                              3.0%

Allowed range for your fee: 0.5% – 10%. Two decimal places. Set during the application form, locked thereafter (changing requires emailing support@ghostswap.io).

How the split is enforced

Once your application is approved, GhostSwap provisions a dedicated upstream liquidity key configured with your total fee (2% + your%). The fee is set on that key by our liquidity team during onboarding and stays fixed for the life of the key. All swaps from your organization route through that key, so the upstream provider's per-key payout report is the settlement source-of-truth — no manual splitting on our side.

Provisioning typically completes within 1–3 business days of approval. While it's in flight, swap creation returns a friendly provider_credential_pending (HTTP 503); read endpoints (currencies, pairs, quotes, address validation) work normally.

You never handle the upstream key yourself. It lives encrypted in our infrastructure, signs every swap on your behalf, and is what the upstream pays against.

When your commission is calculated

Real-time, the moment a swap reaches finished:

Background worker observes the status transition
Fetches the live USD spot price for the source currency

Computes:

amount_from_usd  = amountFrom × spot_price
your_commission  = amount_from_usd × (your_fee_percent / 100)

Inserts an estimated row in your commission ledger

You see the new row appear on /dashboard/earnings within ~30 seconds of swap completion.

Estimated → settled

Two-phase accounting:

State	Meaning
`estimated`	Computed at swap-finish using live USD spot. Locked in your currency at that moment.
`settled`	The upstream paid GhostSwap for this swap; admin reconciled the per-key report. The `estimated` value matched within ±5%.
`voided`	Rare. Swap was charged-back or refunded after finishing.

v1 status: the estimated → settled flip currently runs as a manual operations process — a GhostSwap engineer reconciles the upstream per-key payout report against our ledger after each upstream settlement. A self-serve admin reconciliation upload is on the near-term roadmap. While we're manual, settlement cadence is weekly.

You're paid in USDT after your settled balance crosses the $100 minimum threshold. Request payouts from /dashboard/payouts; admin reviews and sends the funds, then pastes the on-chain tx hash so you can verify it on the block explorer.

Per-swap visibility

Every swap row carries:

partner_reference_id (your end-user ID, if you sent one) — so you can see which of your users drove which swap
api_credential_id — which of your gspk_live_* credentials created the swap (useful if you have multiple)
commission_amount_usd joined in — your earning for that specific swap

/dashboard/transactions lets you filter by both. /dashboard/earnings rolls them up into per-credential and per-end-user breakdowns.

Pass `partnerReferenceId` to attribute swaps to your end-users

fetch(`${BASE}/v1/swaps`, {
  method: 'POST',
  headers: { 'Authorization': AUTH, 'Content-Type': 'application/json',
             'Idempotency-Key': uuid() },
  body: JSON.stringify({
    from: 'btc', to: 'eth', amountFrom: '0.01',
    address: '0xUserPayoutAddress',
    refundAddress: 'bc1qUserRefundAddress',
    partnerReferenceId: 'user_42_order_8731',  // ← any string up to 120 chars
  }),
});

The reference id is stored on the swap row and surfaces in:

/dashboard/earnings "Top end users" list
/dashboard/transactions per-row column + filter
GET /v1/swaps?…&endUser=user_42 for programmatic queries (planned)

Worked example

You signed up with partnerFeePercent: 1.0. Today three of your end-users do swaps:

End-user ID	Pair	amountFrom	spot price	volume USD	Your earning
`user_42`	btc → eth	0.01 BTC	$65,000	$650	$6.50
`order_8731`	eth → usdt	5 ETH	$3,300	$16,500	$165.00
`wallet_99`	usdt → btc	1,000 USDT	$1.00	$1,000	$10.00

Your estimated balance: $181.50. After the upstream settles (typically within 7 days), it flips to settled and becomes payable.

Settlement currency for payouts

USDT is the default for partner payouts. Network selection is admin-configured per partner (TRC-20 default for low fees; ERC-20 available on request).

What if I want to change my fee later?

Email support@ghostswap.io with your org_public_id (visible on /dashboard) and the new fee. The change requires updating the upstream provider's apiExtraFee on your dedicated key — typically 1–3 business days. Existing swaps keep their partner_fee_percent_at_creation snapshot, so historical commissions stay locked in.