---
name: namid-names
description: Find, price and ask for NamID names on Chia, read the TLD owner's rules, and publish or check an agent card. The agent never pays or signs; a person approves in their own wallet.
---

# NamID names for agents

NamID names are coins on the Chia blockchain: `yourname.mojo` is a name under the TLD `mojo`.
This file tells an AI agent how to use them. Network today: **testnet11** (test coins only).

Base URL: `https://testnet.namidbase.com` (registry API under `/api/`).
Everything the registry can do is described in one JSON document: `GET /api/agent`.

## Rules you must follow

1. **You never hold the key that owns a name, and you never pay for one yourself.** You file a
   request; a person approves it in their own wallet (the NamID app and wallet). Send them the `approve_url`.
2. **The TLD owner's rules come first.** Before you ask for a name, read them:
   `GET /api/namespace/terms?root=<tld>` tells you whether names expire and whether they can
   change hands. Tell the person what the rules say. Do not promise anything the rules forbid.
3. Names are lowercase `a-z` and `0-9`, 1–63 characters per label, no hyphens.
4. A refusal is JSON `{ok: false, code, error}`. Show `error` to the person; do not retry a
   refusal unless it says `retry: true`.

## Find a name and its price

```
GET /api/agent/roots                                  which TLDs take names, on what terms
GET /api/names/wallet-register/plan?root=x&label=mybot   available? price? lock mode?
GET /api/namespace/terms?root=x                       the owner's rules (expiry, transfer)
```

## Ask for a name (a person approves)

```
POST /api/agent/requests
{"name": "mybot.x",
 "from": "who you are, ≤80 characters",
 "note": "why, for the person approving, ≤280 characters",
 "card": { …an agent card, optional… }}
```

The answer has `id` and `approve_url`. Give the link to the person who will own the name.
Then poll `GET /api/agent/requests?id=<id>`: `state` is `waiting`, `registered`, `done` or
`expired` (after 7 days). A request does not hold the name; someone else may register it first.

To put a card on a name that already exists, send the same request with that name and the card.

## The agent card

A record on the name that says what the agent does, where to reach it and how to pay it.
The shape follows the open A2A agent card; NamID adds payment and spending fields.

```json
{"name": "AgentR",
 "description": "Explains NamID names and agent cards, and takes payment to its own name",
 "role": "agent",
 "url": "https://agentr.example/a2a",
 "skills": [{"id": "explain-names", "name": "Explain NamID names", "tags": ["help"]}],
 "protocols": ["a2a", "mcp"],
 "mcp": [{"name": "help", "endpoint": "https://agentr.example/mcp"}],
 "pay_to": "name",
 "accepts": ["XCH"],
 "spending": "owner-approves",
 "operator": "mayank.nm"}
```

- `role`: `agent` | `assistant` | `service`
- `pay_to`: `"name"` pays the name's own address record, or a Chia address
- `spending`: `owner-approves` (a person approves each payment), `within-limit`, or `none`
- Links must be `https://` (MCP may be `wss://`). The whole card is at most 6 KB.

## Read and check a card

```
GET /api/names/agent?name=agentr.x        the card, its sha256 card_hash, an A2A view
GET /api/agents?q=calendar               every name with a card
```

To check a copy: serialise the card as JSON with sorted keys and no spaces, take sha256, and
compare with `card_hash`. The same bytes are the pair `agent/card` in the name's records store:
`GET /api/names/datalayer/proof?name=agentr.x&key=agent/card` returns the inclusion proof
against the store's root, which is on chain. A card that does not match is not the owner's.

## Pay a name

Resolve the name (`GET /api/names/resolve?name=…`) and pay its `records.address`, or the
address in its card. Ask the person before any payment unless the card's `spending` and the
person's instructions say otherwise.

## Spend within a limit (your own allowance)

If your name's card carries `allowance` and says `"spending": "within-limit"`, your owner gave
you your own spending money on chain. You pay from it with YOUR key (never the owner's, never
the name's); every Chia node refuses a payment that would take you over `limit_mojos` in a
window of `period_blocks` (payments and network fees count together).

1. `GET /api/agent/allowance?name=<your name>` — balance and `may_spend_now_mojos`.
2. `POST /api/agent/allowance/pay` `{"name": "<your name>", "to": "txch1…", "amount_mojos": N}`
   returns `coin_spend`, `pays` and `sign.agg_sig_me`. Before you sign, recompute the bytes:
   sha256tree((payee_puzzle_hash amount fee now)) + the coin's id + the network's genesis
   challenge, and check they equal `sign.agg_sig_me` (the client `namid_agent.py pay` does this).
3. Sign those bytes with your key (BLS, AugSchemeMPL) and
   `POST /api/agent/allowance/push` `{"coin_spends": [coin_spend], "aggregated_signature": "…"}`.

Over the limit you get `over-limit` (403) with the height at which the window resets. Wait,
or ask your owner. Your owner can empty the allowance at any time; that is not an error.

## MCP

`tools/namid-agent/namid_mcp.py` (stdio) exposes the same flows: `namid_roots`, `namid_plan`,
`namid_rules`, `namid_request_name`, `namid_request_status`, `namid_agent_card`,
`namid_agents`, `namid_resolve`, `namid_allowance`, `namid_pay` (your own allowance,
within its limit), and, with a wallet the person runs, `namid_register` and
`namid_set_records` (which say PAYS or SIGNS in their description).