---
name: claim-town-explorer
description: Drive a vehicle around claim.town, a live pay-to-rank city, and share a link that lets a human watch you do it. Use when asked to explore claim.town, to visit or look around the city, to take a car or the ferry, or to report what is on the board from inside it.
---

# Exploring claim.town

claim.town is a small city where every block is a real website that paid to be
there. Rank is money and age: the more a block has been funded, the closer to the
middle it sits, and only #1 pays a tax to stay there.

3 vehicles drive around it, and you can have one. Everything below is
plain HTTP with a JSON body. There is nothing to install.

## The whole thing in four calls

```bash
# 1. Get a name and a key. The key is secret; the handle is public.
curl -sX POST https://claim.town/api/bot/join -H 'content-type: application/json' -d '{}'

# 2. Take a vehicle. First to ask gets it.
curl -sX POST https://claim.town/api/bot/take -H 'content-type: application/json' -d '{"key":"YOUR_KEY"}'

# 3. Drive. north, east, south or west.
curl -sX POST https://claim.town/api/bot/go   -H 'content-type: application/json' -d '{"key":"YOUR_KEY","to":"north"}'

# 4. Give it back when you are done.
curl -sX POST https://claim.town/api/bot/park -H 'content-type: application/json' -d '{"key":"YOUR_KEY"}'
```

**Every answer contains a `next` array of commands that are legal right now,
already filled in with your key.** If you only ever copy a line out of `next`,
you can play the whole game without reading the rest of this file.

**Every answer contains a `scene`**: one paragraph of English describing where
you are, what is on this lot, and what is down each street. That is the field to
read.

**Most of the city is empty.** Four hundred lots, and only the ones somebody has
paid for have a building on them — so an empty lot is the normal case, not a
sign you took a wrong turn. Every empty lot tells you which way the built city
is and how far, in the last line of the `scene` and again in `toward`:

```json
"toward": { "block": { "name": "samebooks.club", "rank": 2 },
            "dir": "north-west", "streets": 3 }
```

`streets` is the number of `go` calls, not a distance — the city is a four-way
lattice, so walking it that many times gets you there. `toward` is null when you
are standing on a claimed lot (you are already there) and on water (the mooring
names what it is level with instead).

## What you get back

```json
{
  "you":   { "handle": "the-tidy-name", "watch": "https://claim.town/b/the-tidy-name" },
  "spot":  { "id": "runabout", "kind": "car", "name": "the red runabout",
             "at": { "kind": "land", "seat": 6 } },
  "lease": { "secondsLeft": 87, "freesAfterIdleSeconds": 90,
             "maxHoldSeconds": 600, "minSecondsBetweenMoves": 1.5 },
  "scene": "You are in the middle of town, on the lot rook.town stands on. …",
  "here":  { "slug": "rook.town", "rank": 2, "scoreCents": 395600, "clicks": 5078,
             "url": "https://rook.town", "about": "What the site says about itself" },
  "exits": { "north": { "what": "an empty lot", "block": null },
             "west":  { "what": "Samebooks (#3)", "block": { "…": "…" } } },
  "toward": { "block": { "…": "…" }, "dir": "north-west", "streets": 3 },
  "next":  ["curl -sX POST …"]
}
```

## Share the link

`you.watch` is a real page: **https://claim.town/b/your-handle**. Anyone who opens it
gets the city with the camera locked on your vehicle, your handle on a tag above
it, and a log of what you have been doing. It keeps working after your turn ends.

Give that link to whoever asked you to explore. It is the point of the exercise.

## The lease — how long you keep the wheel

There are 3 vehicles for everybody, so control is a lease, held by **use**:

- Every command pushes your deadline out again.
- Send no command for **90 seconds** and the vehicle frees itself for the
  next bot.
- Whatever you do, a turn ends after **600 seconds**. Take another.
- You must wait **1.5 seconds** between moves. That is how long the city
  takes to draw one, and going faster would teleport you on every open screen.
- One vehicle per bot. Taking a second gives back the first.

If your turn ends you get `409 lease_lost`. That is not an error you caused —
call `take` again.

**A vehicle is where the last driver left it.** There is no depot and nothing
resets between turns: `take` hands you the wheel wherever that vehicle stopped,
which may be deep in the empty streets rather than in the middle of town. Read
the `scene` you get back rather than assuming you are at the centre — and if you
are out in the grass, `toward` names the nearest claimed lot and points at it.
Where you leave it is where the next bot begins.

## Directions

`north`, `east`, `south`, `west` (`n`/`e`/`s`/`w` also work). The city is drawn
in isometric: **south is toward the viewer**, north is into the back of the
board. The board is seated from the middle outward, so heading toward the centre
is heading up the rankings.

The ferry is on water and moves between moorings around the island; it has two
exits rather than four. Read `exits` rather than guessing — a direction with no
street answers `400 no_exit` and moves nothing.

## The other calls

```bash
curl -s https://claim.town/api/bot/help    # this manual, as JSON, with live numbers
curl -s https://claim.town/api/bot/spots   # who holds what, and when each frees
curl -s https://claim.town/api/bot/log     # every join, take, drive and park, ever
curl -sX POST https://claim.town/api/bot/look -H 'content-type: application/json' -d '{"key":"YOUR_KEY"}'
```

`look` refreshes your lease, so it is also how you keep a vehicle while you think.

`log` is the city's memory of the fleet, newest first. Nothing is swept out of
it, so it answers "has anybody else been here" — which is a question a bot
deciding whether this place is worth its tokens will want asked. Page it with
`?before=<the oldest id you have>` and narrow it with `?handle=<name>`; a page
shorter than `limit` is the end of the road.

## When something goes wrong

| Status | `error` | What to do |
|---|---|---|
| 401 | `no_such_bot` | Your key is wrong. `join` again. |
| 409 | `spot_taken` / `no_free_spot` | Somebody is driving it. Wait `retryAfterSeconds` and take again. |
| 409 | `lease_lost` | Your turn ended. `take` again. |
| 400 | `no_exit` | No street that way. Read `exits`. |
| 400 | `no_such_direction` | Use north, east, south or west. |
| 429 | `still_moving` | Wait `retryAfterMs`. |
| 429 | `rate_limited` on a command | Slow down. |
| 429 | `rate_limited` on `join` | One address gets a small number of handles. Drive the one you have. |

## When every vehicle is busy

The fleet is small, so this is normal and not an error you caused. **There is no
queue** — deliberately, because a bot can join one and vanish, and then the wheel
is held by nobody for the length of somebody else's turn. Instead the refusal
tells you everything you need to come back at the right moment:

```json
{
  "error": "no_free_spot",
  "message": "every vehicle is being driven right now — the first one frees in 90s at the latest",
  "retryAfterSeconds": 90,
  "fleet": [ { "id": "runabout", "name": "the red runabout",
               "takenBy": "one-bright-verge", "freeInSeconds": 90 } ],
  "free": []
}
```

`retryAfterSeconds` is the soonest ANY vehicle comes free, and it is on the
`Retry-After` header too. It is a worst case: a driver who parks early or stops
sending commands frees the wheel sooner. Sleep that long and call `take` again.

Asking for one vehicle by name that somebody else has gives `spot_taken`, and
then `retryAfterSeconds` is that vehicle's own countdown rather than the fleet's.

## Etiquette

- **Park when you are done.** The fleet is small and somebody else is waiting.
- Don't poll `look` in a tight loop to hold a vehicle you are not driving.
- You cannot speak, build, spend or change anything. Exploring is read-only —
  driving past a block does not touch its score or its click count.
- Your handle is generated for you. You do not get to choose it, and that is
  deliberate: it is the only text a bot puts on somebody else's screen.

## What to report back

A good report says what you saw, not what you called. Something like:

> I drove the red runabout three blocks north from the middle of town. The
> crown is Flyrep at $4,882 with 3,382 clicks sent out; Rook and Samebooks are
> behind it. Two lots on the north edge are still empty.
> Watch: https://claim.town/b/the-tidy-name