docs

The base URL in development is http://localhost:6014 and in production https://autopons.ai. Paths are the same on both, because the local server runs the same handler files that production runs.

Every endpoint is read-only. Nothing here writes to a chain, holds a key or signs anything. There is no authentication and no API key: /api/chain and /api/colony are plain GET requests, and /api/rpc accepts only the read methods on its allowlist. Responses are JSON with content-type: application/json.

Honesty. The chain reads are real — block number, block hash, timestamp and gas price come from Robinhood Chain. The agent population is derived from those reads by the deterministic simulation in lib/colony.js. Those are not deployed contracts, and no address returned by this API belongs to anything on chain.

A small cacheable summary for the status strips. It takes no query parameters; anything you send is ignored. Three reads are issued in parallel upstream — eth_blockNumber, eth_gasPrice and eth_chainId — and the response is sent with cache-control: public, max-age=2, stale-while-revalidate=15.

When no upstream endpoint answers, the handler still returns a body — it answers 503 rather than hanging or sending an empty page. Treat a 503 as a normal outcome and render the offline state.

Reads the latest block, seeds a grid from its hash, steps that grid forward gen generations and returns the roster derived from it. Because gen is applied server-side without touching the chain again, a client can scrub through generations of one block cheaply.

Every parameter is parsed with parseInt and clamped. A value that is not a number falls back to the default; a value outside the range is pulled to the nearest bound rather than rejected.

If the chain read fails the endpoint still answers 200. It seeds from a fixed genesis hash instead, sets source to "genesis" and leaves block.number and block.timestamp at 0. Check source before presenting a colony as a fact about the head of chain. An unexpected server-side failure answers 500 with { "error": "…" }.

Deploying an agent, and reading the ones that exist. An agent is a contract that holds its own balance and carries its own task; it is alive exactly while it can pay, which is the argument the rest of this site makes. Pay a small fee to the factory and everything you send above that fee becomes the new agent's opening balance.

Two things hold throughout. Every figure carries the eth_call that produced it and the raw word that came back, so any of it can be repeated against the chain. And nothing signs: deploy is calldata, this repository holds no key, /api/rpc refuses write methods, and the agent you make is owned by you — the factory keeps no power over it once it exists.

A contract cannot wake itself up, so an agent is an account with a task rather than a process. Its owner signs when it should act, and the gas comes out of the agent's own balance through execute. That is the honest shape of the idea: the money and the identity live on chain, the decision to act does not.

When the chain cannot be reached the endpoint answers 503 with an error and an empty agents array. When the factory has not been broadcast yet, factory.deployed is false and factory.reason says so — the endpoint still returns everything else, because a page that cannot tell you why it is empty is worse than one that can.

The model itself, as one ES module with no imports, no node builtins and no DOM. The server loads it from api/colony.js and the browser loads the same file over /lib/colony.js, so the roster a page draws and the roster the API serves cannot drift apart. It is served as a static file, which means you can import it directly from a page of your own.

An agent is a cell. The block hash supplies the seed and B3/S23 supplies the biology. A cell with two or three live neighbours has enough of the block's gas to keep running; an empty cell with exactly three is funded from three directions at once and an agent is born there.

Nothing in the roster is random. The block hash is folded to a seed with fnv1a, that seed drives the PRNG, and each agent's name, role and energy are drawn from a second stream seeded by the hash, the cell index and the generation. Its id and address come from the hash and the cell index alone, so they stay the same as the colony steps forward while the rest of the agent moves with it. Same hash, same width, same height, same generation, same roster — on any runtime, in any order, as many times as you ask. That reproducibility is what makes the roster a fact about the chain rather than a decoration, and it is also why you can verify it yourself: run roster() in your own page against a hash from the explorer and compare it to what this API returns.

The agent population is derived. Block number, block hash, timestamp, gas price and gas used are read from Robinhood Chain and are real; everything about an agent — its name, role, energy, age, transaction count, gas total and address — is computed from those reads by lib/colony.js. An address returned by /api/colony is not a deployed contract and holds nothing.

No endpoint here can send anything: the RPC route allows reads only and the server holds no key. $AUTOPONS (0x4dBb51a72ab680DadDEA5Eb6A1e6c43552e9a5EE) is on the ponsfamily bonding curve and is linked in the footer — it is the only buyable thing on this site, it is not returned by any endpoint, and holding it grants no claim on any agent. Agents are funded in native ETH and owned by their deployer.

The endpoints are read-only and their rate is the upstream's rate. There is no quota of our own and no key to apply one to, so treat the public RPC's limits as yours: keep batches under twelve, cache what you can — /api/chain and /api/colony both send short cache headers — and expect an occasional 503 from /api/chain or a source of "genesis" from /api/colony when the chain is unreachable. Both are normal, and both are documented above rather than hidden.