# ProofSwap for coding agents

> Operational instructions for an AI coding agent (Claude Code, Codex, Cursor or similar) acting for the owner of a website. Product overview for assistants: https://proofswap.me/llms.txt

## What ProofSwap is

ProofSwap gives indie founders a free public testimonial wall and an embeddable widget. Give another founder an honest tweet, testimonial, video review, or app feedback to activate your Free listing, then fill the wall with exchange proof, quotes you already have, or customer submissions you approve.

## 1. Create a private draft wall

One request, no account, no API key:

```sh
curl -sS -X POST https://proofswap.me/api/agent/walls \
  -H 'content-type: application/json' \
  -d '{
    "email": "owner@example.com",
    "url": "https://example.com",
    "name": "Example",
    "description": "One or two plain sentences about what the product does.",
    "app_type": "Developer tool"
  }'
```

Fields (JSON object, body at most 16 KiB):

- `email` (required): the owner's real email address. The claim link is sent there. Use the address of the person you are working for, never a made-up one.
- `url` (required): the product's public http(s) URL. Localhost, private and internal hosts are refused.
- `name` (required): 2 to 120 characters.
- `description` (required): 10 to 500 characters, written from what the site actually says.
- `app_type` (optional): a short category, at most 120 characters.

Responses:

- **201 Created**: a private draft exists. The body has `wall.slug`, `wall.status` (`draft`), `wall.public_url_when_published`, `claim.sent_to`, `claim.expires_in_hours`, `verification.meta_tag` and `verification.check` (method and URL), plus a `next` list.
- **409 Conflict**: `already_listed` means the URL already has a public ProofSwap wall (`public_url` links to it); the owner signs in and manages it there. `claim_pending` means this email already has an unclaimed wall; it must be claimed first (repeat the request with that wall's URL to resend the link).
- **429 Too Many Requests**: at most 5 requests per hour per address and 3 per day per email. Wait for `retry-after` seconds. Do not rotate addresses or emails to get around it.

Other answers you may see: **202** (this email already has a ProofSwap account, so nothing was created and the owner got a sign-in link instead), **400** (`invalid_input`, with the failing `field` where known), **415** (send `content-type: application/json`), **413** (body too large), **503** (`unavailable` or `email_unavailable`; agent creation is switched off or the email failed, retry later or send the owner to https://proofswap.me).

## 2. What happens next

- The owner receives an email with a single-use claim link. It expires in 1 hour; repeating the same request sends a fresh one. The link is never returned to you. Whoever controls the inbox controls the wall.
- Until the owner claims it, the wall is a private draft: not listed, not public, `/p/{slug}` answers 404.
- A draft nobody claims is deleted after 7 days. No credit is spent on any path.

## 3. Verify the domain

The wall can only be published on a verified domain.

1. Add `verification.meta_tag` from the 201 to the `<head>` of the page at `url`. It looks like `<meta name="proofswap-verification" content="<token>">`. A ProofSwap launch badge linking to the wall also counts.
2. Deploy the site. Commit and deploy only with the owner's approval, the same as any other change to their repository.
3. Check it:

```sh
curl -sS -X POST https://proofswap.me/api/agent/walls/<slug>/verify
```

The answer has a `state`:

- `present`: domain verified (`verified: true`).
- `absent`: the tag was not found. Add it, deploy, check again. An unknown slug answers the same way.
- `unknown`: the site could not be read just now (timeout, DNS, server error). Nothing changed; check again in a minute.

At most 10 checks per hour per wall. Verifying never publishes anything.

## 4. Join a launch week (optional)

ProofSwap runs free weekly founder launches with a public, voted board at https://proofswap.me/launches. There is no cap per week and nothing to pay. Ask the owner first: a launch is public.

This only works for a wall the owner has already claimed, verified and published (see section 5). It books the first bookable week; there is no body and no week choice here.

```sh
curl -sS -X POST https://proofswap.me/api/agent/walls/<slug>/launch
```

Answers:

- **201 Created**: `launch.week_start`, `launch.status` (`reserved`) and `launch.approval` (`approved` for a verified domain). The launch goes live on the board when its week starts, and the owner gets an email naming the week. ProofSwap can still pull a launch before its week starts.
- **409 Conflict**: `not_eligible` for every wall that is not published, whatever the reason (unknown slug, not claimed, not verified, draft). `already_queued`: the wall already holds a launch (`week_start` says which week).
- **429** (at most 10 requests per hour per wall and 20 per hour per address), **503** (`unavailable`, retry later).

To pick a later week, use `proofswap_join_launch_week` over MCP (publish permission, optional `weekStart`: an upcoming Monday, UTC) or the owner's dashboard. Votes and rank are earned on the board, never bought. Adding the ProofSwap launch badge to the site turns the wall's link dofollow: https://proofswap.me/launches/badge

## 5. Publishing rules

- **Private until verified.** A wall created this way stays private until the owner claims it, the domain is verified, it has at least one displayable proof, and the owner explicitly publishes it.
- **Nofollow until the owner gives proof.** The link from the wall to the product is nofollow until the owner has given proof to another founder on ProofSwap. Payment never changes this.
- **Not indexed by default.** Published walls created this way are served `noindex` today. Do not tell the owner the wall will appear in search results.
- **Widget ceiling.** One widget request returns at most 50 cards, whatever the plan. Free shows up to 5, Starter up to 25.
- **Proof sources are labeled.** Exchange proof, owner-added quotes and customer-collected quotes are shown with separate labels.

## 6. Connect over MCP (after the claim)

Everything after the claim (adding proof, verifying the domain, publishing, widget settings) runs through the owner's signed-in ProofSwap account or an MCP connection the owner approves.

- Endpoint (Streamable HTTP): `https://proofswap.me/api/mcp`
- Authorization server metadata: `https://proofswap.me/.well-known/oauth-authorization-server` (issuer `https://proofswap.me`)
- Protected resource metadata: `https://proofswap.me/.well-known/oauth-protected-resource/api/mcp` (resource `https://proofswap.me/api/mcp`)
- OAuth: authorization code with S256 PKCE and dynamic client registration. Let your client discover the metadata; do not override issuer or resource.
- Scopes: `proofswap:read`, `proofswap:write`, `proofswap:review`, `proofswap:publish`, `proofswap:widget`, and `proofswap:create` for creating projects. Ask only for what the task needs. The owner picks projects and capabilities on the consent screen; every box starts unchecked.

```sh
# Claude Code
claude mcp add --transport http proofswap https://proofswap.me/api/mcp
claude mcp login proofswap

# Codex CLI
codex mcp add proofswap --url https://proofswap.me/api/mcp
codex mcp login proofswap
```

Cursor: add `{ "mcpServers": { "proofswap": { "url": "https://proofswap.me/api/mcp" } } }` to `~/.cursor/mcp.json` and follow its sign-in prompt.

Observed so far: Claude Code completed OAuth sign-in and a read tool call against the hosted endpoint (2026-11-14). Codex CLI completed OAuth and a scoped tool workflow in local test runs only. Write tools over the hosted endpoint, and Claude Desktop and Cursor sign-in, are unverified. If the endpoint is unavailable or a tool is missing, the owner can do every step on proofswap.me instead.

Never put a token, refresh token or client secret in a config file, chat or log.

## 7. Do not claim

- Do not tell the owner a payment, plan or credit buys a dofollow link, a rank or a placement. Dofollow is earned by giving proof, never sold.
- Do not promise search indexing, rankings or traffic.
- Do not write, invent or paraphrase testimonials. Only add proof that really exists, from the person who gave it.
- Written proof needs the owner's confirmation that they have permission to publish that exact wording under that name.
- Do not describe owner-added or customer-collected quotes as exchange-verified.
- Credits only pay for additional project listings. Receiving proof is free.
