# Square Town for AI agents: read the wall for free, buy a square via one POST

> How an AI agent or bot uses Square Town — GET /api/state to read the favicon wall, POST /api/buy to get a Stripe checkout URL, /llms.txt for context. No API key, reads are free.

Source: https://square.pov.town/for/ai-agents

Square Town (square.pov.town) is a favicon wall where every square costs $1 once, and it is readable by any agent with an HTTP client: `GET https://square.pov.town/api/state` returns the entire wall as JSON, free, with no API key. To buy, an agent sends `POST /api/buy` with a URL and coordinates, gets back a Stripe Checkout URL, and hands that URL to a human who pays by card. `/llms.txt` summarises the site for language models.

> **TL;DR** — Reads: `GET /api/state`, no auth, no key, JSON. Writes: `POST /api/buy` reserves a cell for 30 minutes and returns `checkoutUrl`; a human completes payment. Kissing an icon is `POST /api/kiss/:id`, free. There is no rate-limit promise, no SLA, and no way to pay without a card. Documentation lives at [/api](/api) and [/llms.txt](/llms.txt).

## The problem

Most "internet real estate" walls are built for humans clicking through a form: upload a logo, drag a rectangle, log in. An agent trying to represent a site — or a person's set of sites — has to scrape a canvas or drive a browser. A handful of 2026 walls turned that around and became agent-only, usually with crypto payment, which locks out anyone whose owner just wants to pay a dollar with a card.

Square Town sits between the two. It is human-first (the wall is a WebGL page you look at), but everything an agent needs is a plain URL: the state, the docs, and the purchase step. Nothing requires an account.

## What a $1 square gives you (or your human)

| You get | Detail |
|---|---|
| A permanent favicon on a live wall | The site's favicon (fetched from the URL by Square Town) on the shared grid at [square.pov.town](/); one-time payment, no expiry |
| A click-through | Visitors click the square and follow the link via `/go/:id`, a counted 302 redirect |
| Machine-readable stats | `clicks`, `views` and `kisses` for every listing in `/api/state`; per-day charts on the deed page for $5 one-time |
| A tower in 3D | Each favicon's height on the tilted wall equals its click count |
| Game state you can watch | Evictions (double the last price), the Throne (intro $100, doubles per eviction), 90-day fade unless kissed, ring unlocks at 70 % fill — all visible in the JSON |
| Adjacency | Every square is 1×1; an agent managing several sites can place them on neighbouring cells |

## How to do it

1. **Read the docs once.** `GET https://square.pov.town/llms.txt` is the machine-friendly index; `/llms-full.txt` is every content page in one Markdown file, and every HTML page also exists with a `.md` suffix. The endpoint reference is at [/api](/api).
2. **Fetch the wall.** `GET /api/state` returns `grid` (1024), `half` (the unlocked half-width — 8 at launch, meaning the live area is x and y from 504 to 519), `sold`, `revenue`, `boxArea`, `fillPct`, `center` (the Throne block, its price and current owner), `prices` (`base` 100, `center` 10000, `analytics` 500, in cents), `waterMs` (90 days), `listings`, `pending`, `events` (last 20) and `clowns`.
3. **Pick a free cell.** A cell is buyable when it is inside the unlocked box, not overlapped by any `listings` or `pending` entry, not in the 4×4 Throne block (`center`) and not in the one-cell aura ring around it. Coordinates are integers; the Throne occupies x 510–513, y 510–513, so the aura covers 509–514.
4. **Reserve it.** `POST /api/buy` with a JSON body `{ "url": "https://example.com", "mode": "pick", "x": 504, "y": 504 }`. The response is `{ checkoutUrl, deed, price, block }`. Errors come back as `{ "error": "…" }` — for example when someone got there first, when the cell is still locked, or when it is the Throne or its aura.
5. **Hand off payment.** Open `checkoutUrl` for a human; it is a Stripe Checkout page. The reservation holds the cell for 30 minutes and then lapses if unpaid. Square Town does not accept crypto, invoices or agent-held wallets — a card is required.
6. **Store the deed.** The `deed` token in the response is the secret ownership proof. The deed page is `/deed.html?token=<deed>` and the JSON is at `/api/deed/<deed>`. There are no accounts and no recovery; if the token is lost, so is control of the square.
7. **Other write modes.** `mode: "evict"` with `evictId` (a listing id from `/api/state`) takes that square for double its owner's per-square price. `mode: "center"` claims the Throne. `mode: "auto"` lets the server spiral-place the square. All return a checkout URL the same way.
8. **Keep it alive.** `POST /api/kiss/:id` kisses a listing (free, public, counted). An icon not kissed for 90 days fades to grayscale but stays owned. Be polite: there is no rate limit today, and abusive kissing will simply get rate-limited later.

## Tips

- **Choose cells near the Throne** if visibility matters — the camera starts centred and the live area is small early on. Compare `fillPct` to `unlockAt` (0.7) to predict when the next ring opens.
- **Kiss the icons you manage** on a schedule (monthly is plenty; the fade threshold is 90 days).
- **Check `clowns` before buying.** If the domain has no favicon, Square Town shows a clown emoji and lists it in the [Hall of Clowns](/glossary/hall-of-clowns). Fix the favicon first, then `POST /api/recheck/:id` after buying if it was wrong at purchase time.
- **Save deed tokens** in whatever the agent's owner considers durable. This is the whole ownership model.
- **Poll gently.** `/api/state` is the same document the site's browsers fall back to every 30 seconds; the site itself pushes updates over WebSockets at `/ws`. Once a minute is generous for an agent.

## How Square Town compares to agent-oriented walls

As of August 2026, from our [competitor snapshot](/vs/one-million-pixels-ai):

| Wall | Model | Agent angle | Where Square Town differs |
|---|---|---|---|
| [One Million Pixels (.ai)](https://onemillionpixels.ai) | $1/pixel, 1M pixels, free tier | API for agents, free pixels, anonymity | Square Town sells favicon squares (no image to supply), has evictions and decay, and pays by card only |
| [overwrite.place](https://overwrite.place) | Agents pay/submit; the current occupant is the biggest square, dethroned entries shrink to small permanent squares sized by tenure | Built for agents | Essentially Square Town's Throne as a whole product; no grid purchase and no favicons |
| Million Dollar Botpage | Bot-oriented wall with a live feed (on our watch-list; pricing not verified) | Bots as the audience | Square Town is human-first: people look at the wall, agents read it |

Square Town has no agent-only mode and no free tier. What it has is a public read API, one POST to buy, and a human at the end who pays a dollar.

## What it won't do

- **No API key, no auth — and no promises.** There is no rate-limit guarantee, no uptime SLA and no versioning contract for the JSON shape. It runs on Cloudflare's free tier.
- **No SEO value.** Clicks are 302 redirects from a canvas; nothing here builds backlinks or ranking for the site an agent represents.
- **No traffic guarantees.** Views and clicks are reported honestly and may be small.
- **No autonomous payment.** An agent cannot complete a purchase alone; a human must pay through Stripe Checkout.
- **Squares can be evicted** by anyone paying double, and there is no notification API — watch `events` in `/api/state` if you care.

## FAQ

### Does Square Town have an API for AI agents?

Yes, in the plain sense: `GET /api/state` returns the whole wall as JSON with no key or auth, `POST /api/buy` returns a Stripe Checkout URL, and `/llms.txt` describes the site for language models. Details are at [/api](/api).

### Can an agent buy a square without a human?

No. `POST /api/buy` reserves a cell for 30 minutes and returns a `checkoutUrl`; a person must open it and pay by card. Square Town does not take crypto or agent wallets.

### Is reading the wall free? Is there a rate limit?

Reading is free and unauthenticated. There is no published rate limit and no promise of one either way; poll about once a minute and you will never be a problem.

### How does an agent find a free cell?

Read `half` from `/api/state` (live cells are x and y from 512−half to 511+half), exclude cells overlapped by `listings` or `pending`, and exclude the Throne block (x and y 510–513) plus its aura ring (509–514). Anything left is buyable at $1.

### What does the deed token do?

It is the secret proof of ownership. `/deed.html?token=…` shows the square's views, clicks and kisses; `/api/deed/…` returns the same as JSON. There are no accounts, so losing the token means losing the square's controls.

### How is Square Town different from One Million Pixels .ai or overwrite.place?

One Million Pixels .ai sells pixels with an agent API and a free tier; overwrite.place is a single occupant slot for agents. Square Town sells $1 favicon squares on a human-visible 3D wall with evictions and decay, and payment is card-only. See [Square Town vs One Million Pixels .ai](/vs/one-million-pixels-ai).

### Can an agent keep the icon from fading?

Yes. `POST /api/kiss/:id` is free and public. Icons fade to grayscale after 90 days without a kiss; a monthly kiss is enough.