Commissions

Every partner sets their own fee at signup. That fee is your partner earning rate on completed swap volume and is tracked per swap in USD.

Your fee

User swaps $1,000 equivalent
Your approved fee: 1.0%
Your estimated earning: $10.00

Allowed range for your fee: 0% – 4%. 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 for your approved partner fee. The key is set up by our liquidity team during onboarding and stays fixed for the life of the key. All fee-sensitive quotes and swaps from your organization route through that key so the quote shown to your user matches the swap they create.

Activation typically completes within 1-3 business days of approval. While it's in flight, fee-sensitive quotes and swap creation return a friendly provider_credential_pending (HTTP 503). Currency, pair, and address-validation endpoints remain useful while you build the rest of the integration.

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:

1. Background worker observes the status transition
2. Snapshots the actual source amount received on-chain
3. Fetches the live USD spot price for the source currency
4. Computes:

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

5. Inserts an estimated row in your commission ledger

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

amountFrom remains the requested amount from creation. If a user sends more or less than requested, the dashboard and ledger use amountActualFrom, the amount actually received, so earnings match the completed on-chain swap.

Estimated → reviewed

Two-phase accounting:

v1 status: the estimated → settled flip currently runs as a manual operations process. In the dashboard, treat settled rows as reviewed and approved for manual payout.

You're paid in USDT after your reviewed 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)
• amount_from — the requested source amount
• actual_amount_from — the amount actually received once known
• 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:

Your estimated balance: $183.50. After GhostSwap reviews it, it flips to settled and becomes payable.

Referral commissions

Beyond the API integration, you can also earn by sharing a referral link. Visitors who arrive on https://ghostswap.io/?ref={your_code} get a cookie that tags them as referred by you — every swap they complete on ghostswap.io earns you a commission, with no integration work required.

End user clicks https://ghostswap.io/?ref=orangefren
  → cookie gs_ref=orangefren  (30 days)
  → user does a swap on the ghostswap.io widget
  → 1% of the swap volume credited to orangefren

The rate is set per code at admin-approval time (you'll be notified of yours when referrals are enabled on your account). Your referral commission combines with your API integration commission into one balance — same /dashboard/earnings, same $100 payout threshold, same USDT settlement.

Only finished swaps trigger a referral commission. Mid-flight, failed, expired, or refunded swaps earn nothing — same rule as API integration swaps.

Pick your code

Active partners can claim their own referral slug on the Overview page. Go to /dashboard, type the slug you want under "Pick your referral code", and click Claim slug. Allowed characters: lowercase letters, digits, hyphens, 2–64 chars total. Reserved words (api, admin, dashboard, ghostswap, etc.) can't be used. Slugs are first-come-first-served and globally unique — pick something memorable that's tied to your brand.

See your link

Once you've claimed a slug, your dashboard shows a "Your referral link" card on the Overview page with a copy button and 30-day stats (referred swap count, volume, estimated + reviewed earnings).

Change your referral link

Click Change my Referral Link inside the referral card on the Overview page, then confirm. Disabling frees the slug for someone else and shows you the picker again so you can claim a new one. Disabled codes stop earning immediately — visitors who click an old link still land on ghostswap.io, but won't be attributed to you.

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 our liquidity team to reconfigure your dedicated key — typically 24 hours. Existing swaps keep their partner_fee_percent_at_creation snapshot, so historical commissions stay locked in.

See also

• Status lifecycle — when commission entries are written
• Idempotency — partnerReferenceId vs Idempotency-Key
• Errors — provider_credential_pending and how to handle pre-activation