How to make a loot box or gacha on Solana without a smart contract
A paid loot box needs four things on chain: a price, odds, prizes, and a roll that nobody can steer. Here all four are one JSON file, on loot, a Solana program every project shares. You write no Anchor program, deploy nothing of your own, and see what it costs before anything is sent.
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).
What you need
Node 22 or later. No Rust, no Anchor, no Solana CLI. With an AI coding agent you type one sentence and the agent runs the commands below; the toolkit’s page has the install line for Claude Code, Codex, Cursor and the chat apps.
1. Say what you want
To an agent with the xsolana tools, or to yourself:
“A mystery crate for 0.1 SOL: a 1% legendary sword, a 9% epic shield, a 30% rare helmet, otherwise nothing. Most of the money goes to the treasury.”
The agent looks for the nearest worked example and writes a spec. From a terminal the same search is:
npx -y @xgamesfun/solana@0.29.3 examples loot box gacha2. The spec
An economy is one file, xsolana.json. This one has three collectible items and one box:
{
"version": 2,
"network": "devnet",
"name": "Mystery Crate",
"currency": "sol",
"tokens": [{ "key": "sol", "source": "sol" }],
"collection": { "name": "Crate Gear" },
"items": [
{ "key": "sword", "name": "Legendary Sword", "rarity": "Legendary", "value": 2 },
{ "key": "shield", "name": "Epic Shield", "rarity": "Epic", "value": 0.3 },
{ "key": "helmet", "name": "Rare Helmet", "rarity": "Rare", "value": 0.05 }
],
"boxes": [
{
"key": "crate",
"name": "Mystery crate",
"price": 0.1,
"currency": "sol",
"split": [{ "to": "treasury", "percent": 100 }],
"outcomes": [
{ "gives": "item", "item": "sword", "chance": 1 },
{ "gives": "item", "item": "shield", "chance": 9 },
{ "gives": "item", "item": "helmet", "chance": 30 },
{ "gives": "nothing", "chance": 60 }
]
}
]
}The four chances add up to 100. value is what you think an item is worth: it is used only to say what a player gets back on average.
3. Check it
npx -y @xgamesfun/solana@0.29.3 check xsolana.jsonThe checker refuses anything the program would refuse, before anything is signed. This spec is ready, with two warnings. Each opening also pays the platform’s player fee of 0.002 SOL, which is 2% on top of a 0.1 SOL price. And a paid random item that can be resold is treated as gambling in some places.
4. See where the money goes
npx -y @xgamesfun/solana@0.29.3 simulate xsolana.jsonAt 100 openings a day it prints:
Box “Mystery crate”: costs 0.1 SOL (about 0.10405 SOL in all (the price, the player fee, the oracle,
the network, the collectible’s rent, when it gives one, which never comes back); the wallet needs about
0.112899 SOL when it signs, and the rest comes back), gives back 0.062 SOL on average (62%); the game
keeps 38% of each price.
1%: sword (worth 2)
9%: shield (worth 0.3)
30%: helmet (worth 0.05)
60%: nothing
Each day players pay 10 SOL and get back 6.2 SOL on average (items at the value you gave them), plus
0.2 SOL in player fees, 0.08 SOL to MagicBlock’s oracle and 0.001 SOL in network fees.
The treasury gets 10 SOL a day; burned: nothing. The platform’s fees: 0.2 SOL a day.“In all” is what leaves a player’s wallet for good. Change a chance or a value and run it again: this is where you find out that a box pays back too much or too little, before a player does.
5. Price it
npx -y @xgamesfun/solana@0.29.3 cost xsolana.jsonGoing live takes 3 transactions and about 0.017214686 SOL:
rent 0.01712468 SOL for 10 accounts; program fees 0.00007 SOL; network fees 0.000020006 SOL.
…
open “Mystery crate” (player): about 0.10405 SOL in all (the price, the player fee, the oracle, the
network, the collectible’s rent, when it gives one, which never comes back); …
settle an order (the player, a key they named, or the project’s keys): 0.000005 SOL network. …(… marks where the output is cut.) The 10 accounts are the project, its collection, the three items, the box, a lookup table and the token accounts. Rent is a deposit Solana holds for each account.
6. Read it the way a cheater would
npx -y @xgamesfun/solana@0.29.3 review xsolana.jsonFor every route that pays or gives value, the review says who can trigger it, what the program enforces, what it trusts off the chain, and the most one cheater gets:
- box “Mystery crate” (box:crate)
Who: any wallet that pays 0.1 SOL
The program keeps: the price, 0.1 SOL; the roll is on its written odds, by the oracle
Trusts off the chain: MagicBlock’s oracle (the roll)
Most one cheater gets: What they pay for, at the price: nobody, the project included, can steer the roll.Its one finding here is a reminder: the owner’s key changes every price and rate, so keep it safe.
7. Go live, signed on your own computer
npx -y @xgamesfun/solana@0.29.3 keygen ~/.config/xsolana/loot-box.json
npx -y @xgamesfun/solana@0.29.3 approve xsolana.json --keypair ~/.config/xsolana/loot-box.jsonkeygen makes a key file for the project and prints its address, never the key. Send that address the devnet SOL that cost named. approve then lists every transaction with what it pays and trusts, ends with a code, and sends nothing. Run it again with --yes and that code, and it sends exactly what it listed.
Nothing asks for a seed phrase or for the key of a wallet you already have. The key file is the project’s owner for good: keep it outside any repository, back it up yourself, and never paste it anywhere.
8. Let players open it
npm install @xgamesfun/solanaimport { solanaApp, walletStandardSigner } from '@xgamesfun/solana/play';
const spec = await (await fetch('./xsolana.json')).json(); // the live spec, served with the page
const app = solanaApp({
spec,
rpcUrl: 'https://api.devnet.solana.com',
wallet: walletStandardSigner(wallet, account), // the player's own wallet: Phantom, Solflare, Backpack…
});
const boxes = await app.boxes(); // each box's price and outcome chances: show the odds
await app.openBox('crate', { listing: boxes.find(box => box.key === 'crate') }); // pays, waits for the roll, settlesThe player module needs no Solana SDK and runs in a browser. The roll is asked of the oracle when the box is opened and settled once it answers, a few seconds later. If the oracle never answers, an order still waiting after 7 days can be refunded. The app reference shows a whole page, the wallet connection included.
Other ways to build one
- Your own program. An Anchor program with a randomness oracle (MagicBlock, Switchboard and ORAO each offer one) can do anything you can write. You also write, test, deploy, upgrade and audit it, and pay to deploy it.
- A mint machine. Metaplex’s Candy Machine sells each NFT of a fixed set once, in a random order if you like. That fits a drop. It is not a box with odds, blanks and token prizes that sells again and again.
- A shared program, as here. Nothing to write or deploy, and the same checks for every project. The trade-off: a box can only be what the spec can say.
Where to go next
- The examples: gacha pity, card packs, prizes from a stash of NFTs, a box whose outcomes run out.
- The program reference: who signs what, every instruction, the fees and the known limits.
- Trust and cheating: what a game’s server has to check before it vouches for a result.
Questions people ask
Do I need to write or deploy a Solana program for a loot box?
No. The box is an entry in a JSON file, and it runs on loot, one Solana program that every project shares. You need Node 22 or later to run the tools; there is no Rust, no Anchor and no Solana CLI to install, and nothing of your own to deploy or audit.
How is the roll random, and can the project rig it?
The roll is asked of MagicBlock’s verifiable randomness oracle when the box is opened, and the program settles it on the odds written in the spec. The review of this spec says it in one line: nobody, the project included, can steer the roll. The project can still change the odds by publishing the spec again, so show players the odds as they are now.
What does a loot box cost to set up, and what does each opening cost?
This one takes 3 transactions and about 0.0172 SOL to put live, almost all of it rent for 10 accounts. On devnet each opening costs the player the price plus about 0.004 SOL: a 0.002 SOL player fee (0.0005 SOL on mainnet today), 0.0008 SOL to the oracle, the network fee, and the rent of the collectible when they win one. Run xsolana cost on your own spec for its numbers.
Can the prizes be tokens or NFTs I already hold?
Yes. An outcome can give an item the project mints, an amount of SOL or of any token from a pool, or an NFT from a stash the project holds, such as NFTs of a partner collection. Run xsolana examples with your own words to find the nearest worked spec.
Can I do gacha pity, or a pack with a guaranteed rare?
Yes. Both are fields of a box. A pack is a box that draws several times in one open, and a guaranteed rare is one of those draws made among the rare outcomes only. The examples that ship with the toolkit include a pity box. Opening ten packs is one purchase and one wallet approval.
Is a paid loot box legal?
It depends on where your players are. Some places treat a paid chance at a prize that can be resold as gambling, and many require the odds to be shown. The checker says so every time it sees one. Show the odds on the page, and take legal advice before real money.
Does it run on mainnet?
Yes. The same file runs on mainnet when it says "network": "mainnet", and then every price is real SOL. The program has not been independently audited, so build and try a box on devnet first.
More how-tos
- 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.
- Add Solana to a browser game: Payments, loot boxes and token rewards in a game you already made.
- 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.