xsolana
Enables building and operating game economies on Solana using the shared loot program, including shops, loot boxes, raffles, auctions, NFT staking, crafting, contests, rewards, and player trading. The server can check, simulate, cost, review, and deploy JSON economy specs, with transactions signed locally and receipts recorded on Solana.
This server has a remotely hosted endpoint. Open its connector listing for connection details, authentication requirements, and setup instructions:
xsolana: a toolkit for building game economies on Solana, with no smart contract to write
Design, check, simulate and review a game's economy on Solana: shops, items, crafting, rewards, NFT staking, loot boxes, raffles and auctions, as a JSON spec. No smart contract to write.
xsolana is the toolkit in this repository (@xgamesfun/solana on npm), and loot is the Solana program it drives.
It is not @solana/kit, the Solana JavaScript SDK.
You describe your game's or community's economy in a small JSON file: what players buy, open, stake, win or craft. The tools check it, show you where the money goes, tell you what it costs, and then it goes live, signed on your own computer once you have read what will be sent and said yes. It runs on loot, one Solana program that every project shares, so there is no Anchor or Rust to write, deploy or audit yourself.
Most people never touch the JSON: they ask an AI agent (Claude Code, Codex, Cursor, ChatGPT or Claude) for "a fishing game where each cast costs 0.02 SOL, with a rare golden fish and a monthly draw" and the agent does the rest.
On devnet and on mainnet. An economy runs on devnet, where nothing is real money, unless its file says
"network": "mainnet", where everything is. The program is not independently audited and the tools are provided as is: read DISCLAIMER.md before you use them, and before real money above all.
What you can build
Build | For example |
Shops | A potion for 0.01 SOL, a skin paid in your own token, an item that costs an NFT |
Loot boxes, gacha, packs | A crate with a 1% legendary, a five-card pack with a guaranteed rare, gacha pity |
Lotteries and raffles | A weekly draw, a no-loss lottery, a raffle for an NFT with an allowlist |
Auctions | Highest bid wins, and anyone outbid gets their money back at once |
NFT staking | Lock tiers and boosts, for your collection or any collection you didn't mint |
Crafting | Burn three common gems to forge a rare one |
Contests and predictions | Pick a side, prizes by rank or by stake |
Rewards, quests, airdrops | Capped rewards your game's server vouches for, daily chests, holder-only drops |
Trading between players | Listings for sale or rent, offers, and loans against an NFT |
Every move leaves a public receipt on chain. Random rolls come from MagicBlock's verifiable randomness.
Related MCP server: Solana MCP Server
How it works
Describe it. In a sentence to your agent, or as a spec file (
xsolana.json).Check it.
checkrefuses what it knows the program would refuse (should it miss something,approvestops in words and says what landed);simulateshows where the money goes, day by day;costprices going live and each player action;reviewshows what a cheater could get.Put it live.
approvelists every transaction with what it pays and trusts, ends with a code, and sends nothing; run again with that code, it sends exactly what it listed. A key file on your own computer signs (keygenmakes one for the project). Nothing here asks for a seed phrase or for the key of a wallet you already have, and no page opens unless you ask for your browser wallet.
Why a key file and not a browser wallet? A key file made for the project is a new key that has never held
anything else, so the wallet that holds what you own is never connected or asked to sign; it signs each transaction
exactly as it was prepared and shown; and nothing opens in your browser. What it costs: the key is a plain file, so
anything on your machine that can read it can sign as the project. It is the project's owner, for good (these tools
can't hand a project to another owner), so keep it like one: outside any repository (the tools refuse one inside,
unless git ignores it there), never pasted anywhere, and backed up by you, because nothing restores a lost one.
Unless your spec names a treasury, what the economy earns for you lands at the key's address: name a wallet you
hold ("treasury": "wallet:<address>") before going live. To sign in a browser wallet instead, approve --browser
serves the page for it.
New here? The loot box tutorial walks through all three with real output.
Get started
With an AI agent
Claude Code
/plugin marketplace add XGamesFun/solana-kit
/plugin install xsolana@xgamesfunCodex
codex plugin marketplace add XGamesFun/solana-kit
codex plugin add xsolana@xgamesfunclaude.ai, ChatGPT or Claude Desktop: add https://xgames.fun/mcp as a custom connector. Nothing to install.
Cursor, Cline, opencode or any MCP client: run npx -y --package=@xgamesfun/solana@0.29.3 xsolana mcp.
Any agent that reads skills (Copilot, Gemini CLI, Windsurf…): npx skills add XGamesFun/solana-kit.
Then ask for the economy you want. More ways in, such as the skill as a zip for desktop apps or the server over HTTP, are in docs/harnesses.md.
From a terminal
# find a worked example close to your idea
npx -y @xgamesfun/solana@0.29.3 examples shop with loot boxes
# using a coin you already launched? read it from the chain into its "tokens" entry
npx -y @xgamesfun/solana@0.29.3 token <its mint address>
# does it work? where does the money go? what does it cost?
npx -y @xgamesfun/solana@0.29.3 check xsolana.json
npx -y @xgamesfun/solana@0.29.3 simulate xsolana.json
npx -y @xgamesfun/solana@0.29.3 cost xsolana.json
# the whole economy in plain words, and what a cheater could get
npx -y @xgamesfun/solana@0.29.3 explain xsolana.json
npx -y @xgamesfun/solana@0.29.3 review xsolana.json
# go live: a key file for the project (it prints the address to send SOL to, never the key)…
npx -y @xgamesfun/solana@0.29.3 keygen ~/.config/xsolana/my-game.json
# …then everything going live would send, and a code; nothing is sent
npx -y @xgamesfun/solana@0.29.3 approve xsolana.json --keypair ~/.config/xsolana/my-game.json
# …and with that code, exactly what it listed is sent
npx -y @xgamesfun/solana@0.29.3 approve xsolana.json --keypair ~/.config/xsolana/my-game.json --yes <code>Each command names an exact version, so you always run the release you meant to. xsolana help lists them all.
A token the setup makes gets a new address for its mint. To have the mint at an address you chose, give both approve
commands the key file of that address: --mint-key <the token's key in the spec>=<key file>. The file signs the one
transaction that makes the mint and is never printed. Once the mint is made it can do nothing more at that address on
that cluster; on another cluster the same file can still make an account there, so keep it as you keep a key until it
is used wherever you mean to.
In your app
npm install @xgamesfun/solanaimport { solanaApp, walletStandardSigner } from '@xgamesfun/solana/play';
// spec: your live xsolana.json; wallet: the player's own (Phantom, Solflare, Backpack…)
const app = solanaApp({ spec, wallet: walletStandardSigner(wallet, account) });
// the player sees the price, then approves the purchase in their wallet
const shop = await app.shop();
await app.buy('potion', { listing: shop.find(item => item.key === 'potion') });No Solana SDK needed: it runs in the browser and in Node 22 or later, with TypeScript types included. The player module covers buying, opening boxes, staking, crafting, tickets, bids and claims; apps.md shows a whole page.
Import | What it gives you |
| everything a player does with a live economy, from a web page |
| one builder per instruction, every address, account and receipt decoders |
| your server pays players' fees (never their price), so players with no SOL can play |
| results and vouchers your game's server signs |
| the project's key file as a signer, for a script of the owner's own steps (Node) |
| the tools themselves: |
| the MCP server as a web handler, to host it yourself |
| small browser-safe Solana building blocks: base58, Borsh, transactions, tokens, Core |
| the program's IDL |
| the exact program build this release is for |
Using @solana/kit? loot.toKitInstruction(ix) turns any builder's instruction into Kit's shape.
Good to know
Devnet and mainnet, not independently audited. An economy is on devnet unless its file says
"network": "mainnet". Mainnet is real money: try everything on devnet first.Upgrades can mean setting up again. No program version so far has carried accounts over. Pin the package version.
Players trust the project. Your keys can mint and move your project's pools. The program protects players from each other and from mistakes, not from the project they chose.
The chain can't see your game. Wins and scores are vouched for by your server; checking that a player really did it is your job.
reviewshows what a cheater gets on each route.Nothing runs by itself. Draws, settles and schedule runs are sent by someone, usually your app.
Fees: per player action 0.002 SOL on devnet and 0.0005 SOL on mainnet, and 0.00001 SOL per project action, plus rent.
costgives the totals for the economy's own network.
The full list, with the details behind each, is in Before you use it. Some things aren't built yet: read the known limits before promising players something unusual.
Questions
How do I make a loot box or gacha on Solana without writing a smart contract? Describe it as a box (its price,
its outcomes and their odds), run check and simulate, then approve it with your project's key file. If the randomness oracle
never answers, the buyer can get a refund. See the tutorial and the
examples.
Can I add staking to an NFT collection I didn't mint? Yes. A staking farm takes any collection, with lock tiers, boosts and reward rates, and needs no authority over the NFTs. See NFTs and tokens.
Can I run a lottery, raffle or auction without deploying a program? Yes: lotteries (no-loss ones too), raffles with allowlists, and auctions that refund the outbid at once are all part of the same spec.
Is there an MCP server or Claude Code plugin for this? Yes: the xsolana plugin for Claude Code and Codex, the
hosted server at https://xgames.fun/mcp, and the local server for any MCP client. It's in the MCP Registry as
io.github.XGamesFun/solana-kit.
How is this different from writing my own Anchor program? Nothing is written or deployed per project: one shared program enforces every project's rules, and it is tested instruction by instruction. The trade-off is that you can build what the spec can describe, which is a lot, but not everything.
Can players with no SOL play? Yes, if you sponsor their fees from your own server
(@xgamesfun/solana/sponsor). They still pay any price themselves.
Does it run on Solana mainnet? Yes. An economy runs on devnet, where nothing is real money, unless its file says
"network": "mainnet", where everything is. The program has not been independently audited, so build and try an
economy on devnet first, and read DISCLAIMER.md before real money.
How do I add a Solana economy to a web game I already made? Use xcore
(@xgamesfun/xcore): xcore loot add ./my-game says where the game's xsolana.json goes and copies the page client
beside it, and xcore publish hosts the game on xgames.fun with player sign-in, saves, leaderboards and multiplayer
rooms. It takes plain HTML/JS, Vite, Next.js static exports, and Godot and Unity web exports.
Is this a gambling platform, an exchange or a wallet? No. It is a building tool: it designs, checks, simulates and
reviews the economy of a game or a community, and nothing is played, traded or held here. Parts that pay by chance (a
loot box, a raffle) are game mechanics; where one pays real money, check says what the law asks of it and tells you
to take advice before mainnet.
Does it hold my funds or my keys? No. Nothing an agent calls here signs or sends anything, and the hosted server only reads what you pass it and the public chain. An economy goes live with a command run on your own computer, signed by a key file you made for the project, after you have read exactly what will be sent.
Is this @solana/kit? No. @solana/kit is the Solana JavaScript SDK, for sending transactions and reading
accounts. This is xsolana (@xgamesfun/solana): a spec, a checker and a client for economies on one shared program.
Its client needs no Solana SDK.
Learn more
How-tos on xgames.fun, each a whole build with what the tools print: a loot box or gacha, NFT staking for any collection, an NFT raffle or a lottery, an NFT auction, an airdrop people claim, token rewards that are not farmed and Solana in a browser game
Solana MCP servers and plugins, by job: which one for docs, programs, chain data, NFTs, wallets and trading, and where this one fits
Loot box tutorial: one sentence to going live, step by step
Examples: whole economies that are checked and put live in the tests
How the program works: who signs, every instruction, fees, limits, receipts
NFTs and tokens: with and without the project's authority
Trust and cheating: what your server must check
The agent skill: what an AI agent follows to build an economy
Agents and harnesses: every way to reach the tools, and how releases are made
Contributing
Issues and pull requests are welcome. CONTRIBUTING.md has the setup (npm ci, npm run fixtures,
npm run check), the repository's layout and how to send a change. Report a vulnerability privately, as
SECURITY.md describes.
License
Apache-2.0. See NOTICE and DISCLAIMER.md.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Author, validate, simulate, and one-click-build game economies on the Magicweave platform.
Non-custodial Solana toolkit: rug-checks, swaps, token tools, multisig, DLMM pools, Arweave.
Autonomous RWA treasury on Solana: daily allocation, on-chain receipts, proofs, your own vault.
Solana wallet forensics SDK, x402 pay-per-call, AI agents.
Related MCP Servers
AlicenseBqualityDmaintenanceNon-custodial Solana swap & limit order engine for AI agents. 21 tools - swap, limit, trailing, TWAP, DCA, combo orders - across Raydium, PumpSwap, Orca, Meteora. Jito MEV-protected execution. Ed25519-verified server messages. Private key never leaves the process.21183 npm3MIT- AlicenseAqualityDmaintenanceEnables AI agents to read chain data, execute transactions, swap tokens, and manage wallets on Solana through 38 tools across 7 modules. Supports write operations with a private key and includes built-in prompts for common workflows.381MIT
- AlicenseAqualityCmaintenanceOn-chain Solana token safety for trading agents — traces coordinated wallet funding, same-block Jito bundles, serial-rug deployers and live coordinated dumps into one Exit-Liquidity Risk verdict before a swap. Free tier, then $0.02 USDC/query via x402.12MIT
- AlicenseNot gradedqualityDmaintenanceProvides 76 tools for enterprise Solana development, enabling stablecoin issuance, payments, trading, wallet management, and compliance screening via natural language.27 npmMIT