Bots can play FOLK now: an MMO with a bot API

FOLK has a bot API now. A bot is a player account that plays over plain HTTP, at human pace, by the same rules as everyone else, with a bot label so you can tell.

The adventurer's dashboard: its modes and how it moves between them on the left, its Kappa on the overworld map, the regions it remembers on the right and its log below — The adventurer at level 4, camping by the shelter it just built.

We built it for ourselves first. How long does it take to reach level 10? Does a dungeon pay back its entry fee? Is there a corner of the map nobody visits? You can guess, or play for a hundred hours and take notes.

A bot is a player

A bot has its own Folk, backpack and coins, and belongs to a player. The server holds it to the same rules as you: every step costs energy, every fight takes as long as it takes, and it only sees what your client would.

const API = "https://api.folk.lol/v1";
const headers = { authorization: `Bearer ${process.env.FOLK_BOT_KEY}` };

const state = await fetch(`${API}/state`, { headers });
const { me, error } = await state.json();
if (!state.ok) throw new Error(error); // a wrong key, or the API closed
console.log(`Hello, world! I'm at ${me.x}, ${me.y}`);

const events = await fetch(`${API}/events`, {
  headers: { ...headers, accept: "text/event-stream" },
});

let buffer = "";
for await (const chunk of events.body.pipeThrough(new TextDecoderStream())) {
  buffer += chunk;
  const lines = buffer.split("\n");
  buffer = lines.pop();

  for (const line of lines) {
    if (line.startsWith("data: ")) console.log(line.slice(6));
  }
}

$ FOLK_BOT_KEY=folkbot_... node hello.mjs
Hello, world! I'm at 168, 210
{"type":"won","enemy":"e36","dealt":22,"took":10}
{"type":"earned","xp":24,"coins":12,"reputation":0}

Our first bot hunted Folk around its level, ate, built a shelter, bought spells in town, ran dungeons and summoned stronger Folk, on its way to the level cap. Every tick it went down a checklist of thirty-two questions and acted on the first yes.

The adventurer's strategy tab: its rules in the order it checks them, what each does, and how this tick went — The checklist. On this tick it had fallen, so the very first question came back yes.

What the bots found

Energy: 1,000 is not enough to explore the world. The adventurer spent half its first day waiting for it to refill, and our players told us the same, so this update raises the energy cap to 5,000.
Artifacts: some could not be found anywhere in the world (like cactus), which left some food recipes impossible to cook.

All of these findings turned into a more robust set of checks that we now run before every new version release.

Bring yours

The bot API is documented and free. Your bot plays at human pace, keeps its label and stays out of islands, the town's other shops, fishing and co-op dungeon runs. Keys that break the rules get revoked.

Get a key in the game: Settings -> My account -> Bots. Everything else is on /bots, or as markdown for your agent at /bots.md.

FAQ

Can I play FOLK with ChatGPT, Claude or another AI agent?

Yes. Give it a bot key and point it at /bots.md - the whole API as markdown. It plays through the same HTTP API as any other bot.

Is botting allowed?

Through the bot API, yes. A bot is its own account, belongs to a player and wears a bot label, so everyone can see it's a bot.

Do bots ruin the game for people?

They play by the same rules at human pace and stay out of islands, the town's other shops, fishing and co-op dungeon runs. A key that breaks the rules is revoked.

How fast can a bot play?

As fast as you: every step costs energy and every action takes as long as the game says. The API itself takes up to 10 requests a second, and one player's bots play in up to 2 sessions at once.

Can I give my bot coins and items?

Yes: gift them from My account -> Bots, no friendship needed for your own bot. It only goes one way, though - bots can't give anything to people, at least for now.

Does it cost anything?

Your first bot is free; each one after it costs 42 Mushi Mushi.