wrld docs
01overview
Every coin launched on wrld comes with a rulebook: up to six rules of the form when <the world does something> -> <the coin does something>. The world is read from public sources: world events (live Polymarket odds on war, politics and money), prices, sports results and the weather. Posts on X switch on once the X API key is set. The coin acts with its own money, the creator fees its trading produces.
02launching
- You fill in the coin (name, ticker, picture), write the rulebook and choose a first buy.
- wrld records it, derives the coin’s wallet and its mint address, and tells you one amount to send.
- You send that one SOL transfer. No program approvals and no other signature.
- The engine creates the coin on pump.fun from the coin’s wallet with your first buy, then sends the tokens and any unused SOL to your wallet.
- From that moment the rules watch the world. Anything that happened before launch never counts.
| first buy | your choice, 0.01–10 SOL (+2% for fees) |
| pump.fun rent and fees | about 0.03 SOL, the unused part comes back |
| gas reserve, kept in the coin’s wallet | 0.015 SOL |
| wrld’s cut | nothing at launch; 5% of each fee claim |
03the language
Rules are stored as data and shown as one line each. The fingerprint is the first 12 hex characters of the SHA-256 of the rulebook’s canonical JSON. It is written into the coin’s pump.fun description at launch, so anyone can check the rulebook on the coin’s page against it.
04sensors
| watch | conditions | source |
|---|---|---|
| world events | war, politics, money, sports, crypto, tech: a market’s YES odds rise above / fall below X%, or it resolves YES / NO | Polymarket (public odds) |
| price | SOL, BTC, ETH, XRP, DOGE, BONK, WIF goes above / below a price, pumps / dumps X% in 1h or 24h | Coinbase spot and candles |
| weather | any city: rains, snows, clear sky, hotter / colder than X°C, wind above X km/h | Open-Meteo |
| sports | a team in the Premier League, La Liga, Serie A, Bundesliga, Ligue 1, Champions League, MLS, NBA, NFL, MLB or NHL wins / loses a game | ESPN scoreboards |
| x posts | an account posts anything, or a post containing a word | the X API (off until the house sets its key) |
| the coin | its market cap reaches $X, it graduates from pump.fun | Dexscreener, the bonding curve |
| time | every N hours after launch | the engine’s clock |
05actions
buyback_burn(N% chest): buys the coin with N% of the chest and burns every token bought.airdrop_holders(N% chest): buys the coin and sends the tokens to the top holders, pro rata.pay_holders(N% chest): sends SOL to the top holders (up to 20), pro rata to their bags.pay_creator(N% chest): sends SOL to the wallet that launched the coin.
Holders are the largest token accounts on-chain, minus the bonding curve, pools (program-owned accounts) and the coin’s own wallet. There is no sell action.
06when a rule fires
- Levels (prices, weather, market cap) must be true on two reads in a row, at least 45 seconds apart. Then they fire once, and re-arm only after the level stops being true.
- Events (a game result, a post, a time period) fire once per event, and only for events after launch.
- Every rule has a cooldown: at most one fire per N hours (1–168).
- A rule spends N% of the chest at the moment it fires. Below 0.002 SOL the fire is recorded but nothing is spent.
- If the action fails, it is retried on the next passes, up to three times, and every try is logged.
07custody
Each coin’s wallet and mint keys are derived on the server from one master secret and the launch id, using HMAC-SHA256. They are never stored. The derived wallet is the coin’s pump.fun creator, so pump.fun pays creator fees to it.
- The engine’s code has four spending actions, the four above, plus the launch hand-back, refunds and wrld’s 5%.
- You can audit every one: the coin’s wallet is public, and each action appears in the coin’s log with its transaction.
- What you are trusting: that the engine keeps running, and that the master secret stays secret. If either fails, rules stop firing; the fees stay in the coin’s wallet.
08fees and the chest
When at least 0.003 SOL of creator fees is waiting, the engine claims it into the coin’s wallet. wrld takes 5% of each claim. The rest, minus a 0.015 SOL gas reserve, is the chest that rules spend from. Swaps go through PumpPortal’s local transaction API, which adds its own 0.5% to each trade.
09sources, live
Each row times a real read from the server right now.
| source | status | ms | sample |
|---|---|---|---|
| press try | |||
10failure paths
| if | then |
|---|---|
| the deposit never arrives in full within 3 hours | the launch expires and anything sent is returned |
| creating the coin fails | the whole deposit is returned to your wallet |
| a source doesn’t answer | the rule waits; it never fires on a missing reading |
| an action fails three times | the fire is closed and the rule re-arms on the next crossing |
| the chest is under 0.002 SOL when a rule fires | the fire is recorded; nothing is spent |
| the engine stops | nothing fires; the fees stay in the coin’s wallet |
11api
| endpoint | what |
|---|---|
| /api/world | the live board |
| /api/world?op=eval (POST {rules}) | read a rulebook against the world now |
| /api/coins | every coin; ?m=<mint> for one, ?op=log for the engine log |
| /api/launch?op=config | costs and limits |
| /api/tick | one engine pass (rate-limited, safe to call) |