Setting up earnings
what exists, how to switch it on.

01What exists in the code

02Swap fee

1. Open Admin → Monetization → Swap Fee Configuration
2. EVM fee walletAn EVM address you control: 0x + 40 hex characters. The same address receives fees on every EVM chain you offer, so use a wallet you can open on all of them. A hardware wallet or multisig is a good idea.
3. Solana fee walletA Solana address you control. Leave it empty if you do not want a fee on Solana swaps. Before you fill it, read Solana token accounts below.
4. Pick a presetFree, 0.10, 0.15, 0.20, 0.30, 0.50, 1.0 or 2.0 %. Stored as basis points (fee_bps, 100 bps = 1 %). The maximum is 200 bps (2 %); the admin and the app refuse anything higher. A fresh install starts at Free.
5. PRO users fee waiverOn: PRO subscribers swap without your fee. Off: everyone pays it.
6. Apply Fee Config, then Publish to mobile app

The swap screen shows the fee, price impact and minimum received before the user confirms.

Solana token accounts

On Solana each token sits in its own token account that belongs to a wallet. Jupiter pays your fee in the token the user receives, into your Solana fee wallet's token account for that token. That account must already exist; if it does not, your fee cannot be paid for swaps into that token.

• Create the accounts for the tokens your users swap into most (for example USDC, USDT, wrapped SOL). Receiving a small amount of a token in the fee wallet creates its account in most Solana wallet apps.
• With the Solana command-line tools you can create one directly: spl-token create-account <token-mint-address> --owner <your-solana-fee-wallet>.
• Opening a token account costs a small refundable SOL deposit (rent), paid by whoever creates it.

Example, not a forecast

Tracking

After each swap the app calls recordFeeEvent; aggregateFeeStats rolls the records up every night (02:00 UTC). You see them in Revenue, Overview and Analytics. The records are reporting only: the money is already in your fee wallet; check it on a block explorer.

03PRO subscription

1 · Create the product in the stores

1. Pick one product IDFor example com.yourcompany.wallet.pro.weekly. Use the same ID in both stores.
2. App Store ConnectCreate an auto-renewable subscription in a subscription group with that ID and set its price, as described in Apple's guide Offer auto-renewable subscriptions.
3. Google Play ConsoleCreate a subscription with the same ID and one weekly base plan, as described in Google's guide Create and manage subscriptions.
4. Put the ID in both configsIAP_PRO_WEEKLY_ID in the app's .env and PRO_WEEKLY_PRODUCT_ID in functions/.env.
5. Turn on purchase checksFill the App Store and Google Play variables in functions/.env (table) and redeploy the functions.

How a store purchase becomes PRO

A store subscription unlocks PRO only for the account that bought it:

• When the user buys, the app passes an account token derived from the user's Firebase uid to the store. StoreKit keeps it on the transaction as appAccountToken; Google Play keeps it as obfuscatedExternalAccountId.
• validatePremiumEntitlement reads the subscription from Apple's App Store Server API or Google's Play Developer API (not from the app), checks the product, the expiry and the app, and refuses the purchase if its token is not the caller's.
• The purchase is recorded by its lineage (Apple original transaction ID, Google order ID and linked purchase tokens). The ownership check, the PRO record and the users/{uid} copy (used by the admin PRO counts and the new-PRO webhook) are written in one Firestore transaction.
• Restore on the same account (same app install, or a reinstall that keeps the account) activates PRO automatically.
• Restore on a new device creates a new app account, so the purchase still carries the old account's token. Nothing changes automatically: the server files a transfer request, shown in Admin → Users → Store PRO Transfer Requests with the store evidence (transaction ID or purchase token, the account tokens, the store expiry). When you approve it, the server checks the purchase with Apple or Google again, moves it to the new account for the remaining store period and ends it on the old account, so it is never active on two accounts. Requests older than 7 days must be filed again; a rejected request stays rejected.
• After you approve a transfer, the purchase stays with the new account: its renewals and restores keep extending PRO there. If the old account later restores the same purchase, it is not taken back automatically; a new transfer request appears for you to decide.
• Purchases made before account tokens existed (apps older than 1.1.0) move to the restoring account automatically, and end on the previous one. If such a move was wrong, revoke PRO on that account in Admin → Users.
• Sandbox purchases (TestFlight, App Review) unlock PRO only while APP_STORE_ALLOW_SANDBOX=true is set in functions/.env; leave it empty in production.

2 · Show the price

In the iOS and Android apps the paywall shows the price the store reports for your product, in the user's currency. Admin → Monetization → PRO Pricing sets the weekly price in EUR used for the crypto payment (web and self-distributed macOS builds) and the trial days (No trial by default).

3 · Web

Store subscriptions do not exist on the web. On the web, PRO is sold with the crypto payment below, or granted by hand (Admin → Users). On iOS and Android, digital features must be sold with In-App Purchase (Apple guideline 3.1.1, Google Play Payments), so those builds do not show the crypto payment.

4 · Crypto payment (optional)

Web build, and macOS builds you distribute yourself and build with --dart-define=DIRECT_DISTRIBUTION=true (deployment). The iOS and Android builds never show it, and neither does a macOS build without that flag (the Mac App Store build). Admin → System Config → Crypto PRO Payment: your receiving wallet, token (ETH, USDT, USDC), chain ID, the weekly price in EUR, optional monthly and annual prices in EUR, confirmations, validity. A plan whose price is 0 is not sold for crypto: the server never works out a longer plan from the weekly price.

You do not approve payments. The quoteProCryptoPayment function tells the app how much to send for the chosen plan at the current EUR price, and verifyProCryptoPayment reads the transaction from the chain, checks the recipient, the token contract, the amount against that plan's price, the confirmations and a signature from the paying wallet, and only then activates PRO for the plan's length (7, 30 or 365 days). Each transaction activates one account once. Admin → Users → Crypto PRO Payments lists every attempt and its outcome; for one the server left pending you can still Grant PRO by hand.

04Trials and campaigns

• Manual PRO (Users): grant, revoke or start the configured free trial for one person — useful for support, partners and store reviewers.
• Campaigns: zero-fee or reduced-fee periods, and promo banners on the home screen, for a target group. For a discount on a store subscription, use an offer code in App Store Connect or Google Play Console.

05Earnings checklist

• EVM fee wallet set to a wallet you control, preset chosen (2 % at most), published.
• Solana fee wallet set, or left empty on purpose; token accounts exist for the tokens users swap into.
• A small test swap on a cheap EVM chain shows your fee and it arrives in your wallet.
• The swap appears in Admin → Revenue (totals after the nightly roll-up).
• PRO product created in both stores with the same ID as IAP_PRO_WEEKLY_ID.
• Purchase-check variables set in functions/.env, functions redeployed.
• Admin price matches the store prices.
• Crypto payment wallet set, or the feature turned off.