How to add Solana payments, loot boxes and token rewards to a browser game
You have a web game that works. You want players to buy a skin, open a crate, or earn a token for winning. This is how to add that on Solana without writing a program: the economy is one JSON file on loot, a program every project shares, and xcore puts it in the game.
Devnet by default. Everything on this page runs on Solana devnet, where nothing is real money. The same file runs on mainnet when it says "network": "mainnet", and then it is real money. The program, loot, has not been independently audited. The fees quoted are devnet’s: the player fee is 0.002 SOL there and 0.0005 SOL on mainnet (read from the chain on 2026-11-21; the platform sets it, and the program caps it at 0.01 SOL).
First: what a page can pay safely
A game that runs only in the browser cannot prove what a player did there. Anyone can open the console and change the score. That decides what goes where:
| From the page alone | Needs the game’s server | |
|---|---|---|
| What | A shop, loot boxes, raffles and lotteries, staking, crafting, perks for holders | A reward for a result: a score, a win, a level |
| Why | The player pays for it, or the chain decides it | Somebody has to check the result before it is paid |
| How | The page calls the player client | The server checks, then a key vouches for the claim |
1. Bring the game
npx -y @xgamesfun/xcore adopt ./my-game # its record, and the list of what to fix
npm i -g @xgamesfun/xcore # or install it once, then: xcore …xcore takes a game that ends up as static files: plain HTML and JavaScript, a Vite, Next.js static export, Astro or SvelteKit project, or a Godot or Unity web export. Nothing about the game changes: it keeps its code, its framework and its build. (xcore alone on npm is another package: this one is @xgamesfun/xcore.) It needs Node 24 or later.
2. Write the economy
xcore loot add ./my-gameThis says where the economy’s file goes, and copies the page client beside it once the file is there. A shop with one item is this much:
{
"version": 2,
"network": "devnet",
"name": "My Game",
"currency": "sol",
"tokens": [{ "key": "sol", "source": "sol" }],
"collection": { "name": "My Game Items" },
"items": [
{ "key": "skin", "name": "Golden Skin", "price": 0.05, "split": [{ "to": "treasury", "percent": 100 }] }
]
}With a coding agent, xcore connect adds the xsolana tools and a skill to Claude Code or Codex, and you ask for the economy in a sentence. The other how-tos show a loot box, NFT staking and a raffle; they are more parts of the same file.
3. Check it, simulate it, price it
xcore loot check # what the program would refuse, and what to tell players
xcore loot simulate # where the money goes, day by day
xcore loot cost # what going live costs, and what each player action costs
xcore loot explain # the whole economy in plain wordsFor this spec the checker is ready with one warning: each purchase also pays the platform’s player fee of 0.002 SOL, which is 4% on top of a 0.05 SOL price. Going live takes 3 transactions and about 0.0143 SOL, and a player who buys the skin pays about 0.0551 SOL in all.
4. Call it from the game
// The page client is copied beside the game by xcore; load it at run time so a bundler leaves it alone.
const { solanaApp, walletStandardSigner } = await import(
/* @vite-ignore */ new URL('gf/loot/play/index.js', document.baseURI).href
);
const { solanaWallets, connectWallet, PAGE_RPC } = await import(
/* @vite-ignore */ new URL('gf/loot/wallets.js', document.baseURI).href
);
const spec = await (await fetch('xsolana.json')).json();
const [wallet] = await solanaWallets(); // the wallets in this browser; none: say so, and keep the game playable
const account = await connectWallet(wallet); // the wallet shows its own prompt
const app = solanaApp({ spec, rpcUrl: PAGE_RPC, wallet: walletStandardSigner(wallet, account) });
const shop = await app.shop(); // [{ key, name, price, currency, active, left }]
await app.buy('skin', { listing: shop.find(item => item.key === 'skin') }); // the price shown is the most it paysFrom Godot, Unity or any page with xcore’s gamesfun.js, the same economy is JSON in and out:
await GamesFun.loot.ready(); // {live, project, wallets: [names], spec}
await GamesFun.loot.connect(); // {address, wallet}: the wallet asks the player
const shop = await GamesFun.loot.call('shop');
await GamesFun.loot.call('buy', 'skin', { listing: shop.data[0] });Godot has GamesFun.loot_call("shop") and Unity GamesFun.LootCall("shop").
5. Try it as it will be hosted
xcore dev ./my-game # play it here as xgames.fun hosts it: its server, sign-in, rooms, economy6. Go live, then publish
xcore loot keygen ~/.config/xsolana/my-game.json # a key for the game: prints its address, never the key
xcore loot approve --keypair ~/.config/xsolana/my-game.json # everything it would send, and a code; sends nothing
xcore loot approve --keypair ~/.config/xsolana/my-game.json --yes <code> # sends exactly that
xcore login && xcore publish ./my-game # the game, at a link anyone can playThe economy goes live signed by a key file on your own computer, after you have read what it sends. Nothing asks for a seed phrase or for the key of a wallet you already have. The key file owns the project for good: keep it outside the game’s folder and out of git.
Paying a reward for a result
A reward for a score or a win is a grant that a player claims with a voucher. The voucher key must never be in the page. xcore gives the game a server of its own, and two ways to sign:
- The keeper. When the server already decides who won and the prize is fixed by place, it reports the winners and xgames.fun’s keeper signs. There is no key for you to keep.
- A key of the game’s own. When the amount depends on the result, or there are entry fees or a prize pool,
xcore add vouchersgives the server its own key. The live key is sent only to xgames.fun and never kept on your machine.
A wallet is free to make, so one person can have many. Pay rewards worth farming only to players signed in with X, and run xcore review ./my-game before players are paid: it reads the game the way a cheater would, and says what one person can take.
Without xcore
The economy does not need xgames.fun. In any web app:
npm install @xgamesfun/solana
import { solanaApp, walletStandardSigner } from '@xgamesfun/solana/play';You host the page and run any server yourself. The toolkit’s page has the tools and the install lines for coding agents.
Other ways to do it
- A plain payment. Solana Pay is a standard for payment requests: a link or a QR code a wallet opens. It is enough for “pay 0.05 SOL to this address”; your server then confirms the transfer and delivers the item.
- Your own program. An Anchor program and a wallet adapter can do anything you write. You test, deploy, upgrade and audit it.
- A shared program, as here. Nothing to write or deploy, and the checks every project gets. The trade-off: an economy can only be what the spec can say.
Where to go next
- xcore’s README: every command, what the hosting takes, and the plans.
- Before you build: what to challenge before an economy, a draw or anything a player pays for.
- Trust and cheating: what a game’s server has to check before it vouches for a result.
Questions people ask
How do I accept SOL or token payments in a browser game?
Describe what the game sells in an xsolana.json file, an item with a price for instance, and the page calls app.buy when the player presses the button. The player’s own wallet (Phantom, Solflare, Backpack) shows the price and signs. The sale runs on loot, one shared Solana program, so there is no program of yours to write or deploy.
Can a browser game pay players token rewards for a high score?
Not from the page alone: anyone can change a score in the browser console. A reward for a result is claimed with a voucher, and the game’s server checks the result before a key signs it. xcore gives a game that server and either xgames.fun’s keeper or a key of its own to sign with.
What can a page pay safely with no server?
Anything the player pays for or the chain decides: a shop, loot boxes, raffles and lotteries, staking, crafting, and perks for holders. Random outcomes are rolled by a verifiable randomness oracle, not by the page.
Does it work with Godot, Unity or Phaser?
Yes. It takes any game that ends up as static files a browser runs: plain HTML and JavaScript, a Vite, Next.js static export, Astro or SvelteKit project, and Godot 4 and Unity web exports. A Phaser or Three.js game is plain JavaScript. Godot and Unity call the economy through GamesFun.loot, with JSON in and out.
Do players need SOL to play?
To buy something, yes: the price and a small fee come from their wallet. A game can sponsor players’ fees from its own server, so a player with no SOL can still claim a reward. A sponsor never pays a player’s price for them.
Do I have to host the game on xgames.fun to use it?
No. The toolkit, @xgamesfun/solana, works in any web app: npm install @xgamesfun/solana and import the player module. xcore adds hosting on xgames.fun, player sign-in, saves, leaderboards, multiplayer rooms and a server for the game, and wires the economy into them.
What does it cost?
The one-item shop on this page takes 3 transactions and about 0.0143 SOL to put live. A player who buys the 0.05 SOL item pays about 0.0551 SOL in all on devnet: the price, a 0.002 SOL player fee (0.0005 SOL on mainnet today), the network fee and the rent of the collectible. Hosting has a free plan: everyone gets 2 free game slots.
Does it run on mainnet?
Yes. An economy is on devnet until its xsolana.json says "network": "mainnet", where every price is real SOL or real tokens. The program has not been independently audited, so build and try it on devnet first.
More how-tos
- Make a loot box or gacha: Odds, prizes and a roll nobody can steer, in one JSON file.
- Add NFT staking: Lock tiers and rewards for any collection, one you did not mint too.
- Run an NFT raffle or a lottery: The winner gets the NFT before the seller is paid; a short round refunds.
- Run an NFT auction: A reserve, a late-bid extension, and every outbid bidder refunded at once.
- Run an airdrop people claim: A list of wallets with an amount each; only its Merkle root goes on chain.
- Pay players token rewards: A server that checks, a voucher it signs, and caps a leaked key cannot pass.
- Solana MCP servers and plugins, by job: Which one for docs, programs, chain data, NFTs, wallets, trading and economies.
- Host a web game with xcore: A link anyone can play, with sign-in, saves, multiplayer and an economy.
- The whole toolkit: what else it builds, and how to install it in Claude Code, Codex, Cursor or a chat app.
Checked against @xgamesfun/solana 0.29.3 on 2026-11-21.