Agents & automation

Belt Wars is fully onchain. Every fact about the game is a table in the World contract, and every action is a call to it. An agent, bot, or script needs no permission from the game and no special API: a wallet with ETH on Base that has paid entry can do everything a player can do in either client. This chapter lists what exists for automation. There is nothing else; if a service is not on this page, it does not exist.

Addresses

The World is a MUD 2.0.9 World. Its tables, systems, and function names follow MUD conventions, so MUD tooling and the original Primodium developer documentation apply, with the addresses above.

Bring your own RPC. The public Base endpoints answer bursts with rate-limit errors, and one of them refuses receipt lookups without a token. A paid or self-hosted Base node makes an agent far more reliable than the browser clients, which have to live with those limits.

Identity

A player is a wallet address. The game keys its tables by the player entity: the address left-padded with zeros to 32 bytes. Everything a player owns, from the home asteroid to fleets and buildings, is an entity (a bytes32) that points back to that player through the OwnedBy table.

One wallet is one player. An agent that plays as itself needs its own entry payment and its own colony.

Reading the game

Table ids are built from the type, the namespace, and the name: 0x + tb + the namespace padded to 14 bytes + the table name padded to 16 bytes. Names longer than 16 characters are cut to 16. For example, Home in Pri_11 is:

0x74625072695f31310000000000000000486f6d65000000000000000000000000

Direct from the chain. Call getRecord(bytes32 tableId, bytes32[] keyTuple) on the World with eth_call and decode the static and dynamic data with the table's schema. This is exact and works at any block the node still holds.

From the indexer. The indexer answers GET /api/queryLogs?input=<json> where the JSON is {"address": <World>, "queries": [{"tableId": …, "where": {"column": "entity", "operation": "eq", "value": …}, "include": [{"tableId": …}]}]}. It returns the matching Store_SetRecord records and the block they are current at. It is shared with the browser clients, has no authentication, lags the chain by a few seconds, and is provided as-is.

Live. Subscribe to logs on the World address over a WebSocket RPC (eth_subscribe, logs) to see every table write as it happens.

Tables an agent reads most:

Tables whose names start with P_ are configuration and do not change during play. The World has 124 tables in all.

Acting

Player actions are World functions named Pri_11__<action>. Sending a transaction to the World with that selector runs the action as the sender. The same functions can be reached through the MUD entry points call(systemId, callData) and, for a delegate acting on behalf of a player, callFrom(delegator, systemId, callData); batchCall and batchCallFrom group several actions in one transaction. System ids are built like table ids with the type sy: 0x7379 + namespace + system name.

Simulate every action with eth_call or eth_estimateGas before sending it. A rejected action reverts with the reason the game gives, which is cheaper than a failed transaction.

Unit, building, resource, and objective arguments are the game's enums (EUnit, EBuilding, EResource, EObjectives); their order is fixed in the World's P_EnumToPrototype table and in the MUD ABI. Array arguments such as unitCounts and resourceCounts are indexed by the order in P_UnitPrototypes and P_Transportables, not by enum value.

Functions whose names start with S_, admin, resolve, applyDamage, initAsteroidOwner, transferAsteroid, createSecondaryAsteroid, buildRaidableAsteroid, and increment are internal or owner-only. Calling them as a player reverts.

Two ways to sign

As your own player. Fund a wallet with ETH on Base, call admit() on the entry contract with the value returned by its fee() (check open() and isAdmitted(address) first), then call spawn(). From then on the wallet plays like any other. Entry is paid once per wallet and is not refunded.

As a delegate of a human player. This is what the browser session does. Two options:

1. Reuse the browser session. In the lobby's Session account dialog, choose Export session key. That key is already a delegate of the player with per-system call allowances and holds the session gas. Sign callFrom(player, systemId, callData) transactions with it. Do not run the browser client and the agent on the same session key at the same time: they share one nonce sequence and one gas balance.
2. Register your own key. From the player's wallet, call registerDelegation(delegatee, delegationControlId, initCallData) on the World with the systembound control (0x7379 + 14 zero bytes + systembound padded to 16 bytes) and initCallData = initDelegation(delegatee, systemId, numCalls), once per system you want to allow. The lobby grants all 27 game systems with 10,000 calls each in a single batchCall. Fund the delegate with ETH for gas. Revoke at any time with unregisterDelegation(delegatee).

A delegate can only run game systems it was granted. It cannot move the player's ETH, claim a name, or pay entry; those stay with the player's wallet. Unlimited delegation exists in MUD, but the lobby never uses it and it is not recommended for an agent key.

Costs and limits

Nothing tops up a session or an agent wallet automatically. There is no prize pool and no payout; points are game points.

Rehearse safely

There is one game, on Base mainnet, and every action costs real ETH. Rehearse an agent against a local fork of the World (any Base-compatible fork tool pointed at the World address and a recent block) before letting it spend, and simulate each action with eth_call before sending it.

What is not available

There is no REST game API, no hosted matchmaking, no official bot framework, and no way to act without paying gas. Client code is not published; the interface is the World contract itself, which is complete and public on chain.

Continue with troubleshooting.

September 2026 edition · Use the game panel for current costs and timers.