# Bitcoin Agent ID

Version 1 · https://proveitonchain.com/agent-id

A short, open convention for an AI agent to declare a name it holds on Bitcoin, and for anyone (another agent or a person) to check that claim before trusting it.

## Why

Agents can copy any display name, logo, or description. A Bitcoin Agent ID ties an agent's name to a Bitcoin address: the name is a named asset on Bitcoin, its current owner is public, and the agent profile is signed by that owner's key. Copying the name into a different agent card does not copy the key.

## What it proves, and what it doesn't

A verified Bitcoin Agent ID proves:

- the name exists on Bitcoin and which address owns it right now;
- that same address signed the agent profile (display name, operator, website, X handle, description, agent type, MCP endpoint), and when.

It does **not** prove:

- legal identity of the agent or its operator;
- that the agent or operator is human, honest, safe, or trustworthy;
- that the profile's website or X handle is controlled by the same party (check those separately, see step 4 of section 3).

## 1. Get a name and sign its profile

1. Buy a name ($21 + network fee) at https://proveitonchain.com/vanity, or as an agent with the MCP tool `buy_name` / `POST /api/v1/names/orders`. It is delivered to your own Bitcoin address.
2. Sign the agent profile with that address: MCP `set_agent_profile` or `POST /api/v1/names/{NAME}/profile` (call once to get the message, sign it with BIP-322 or your wallet's sign-message, call again with the signature). Signing is free.
3. Check it: `GET https://proveitonchain.com/api/v1/agents/{NAME}/verify` should return `"verdict": "verified"`.

## 2. Declare it

Add a `bitcoin_agent_id` object wherever your agent describes itself.

**A2A agent card** (`/.well-known/agent.json`): add the object at the top level, and optionally as an A2A extension so A2A clients can discover it:

```json
{
  "name": "Prove It Bot",
  "url": "https://proveitonchain.com",
  "bitcoin_agent_id": {
    "spec": "https://proveitonchain.com/agent-id",
    "version": "1",
    "name": "PROVEITBOT",
    "verify_url": "https://proveitonchain.com/api/v1/agents/PROVEITBOT/verify",
    "page_url": "https://proveitonchain.com/agent/PROVEITBOT"
  },
  "capabilities": {
    "extensions": [
      {
        "uri": "https://proveitonchain.com/agent-id",
        "description": "Bitcoin Agent ID: this agent's name on Bitcoin and where to verify it.",
        "required": false,
        "params": { "name": "PROVEITBOT", "verify_url": "https://proveitonchain.com/api/v1/agents/PROVEITBOT/verify" }
      }
    ]
  }
}
```

**MCP server metadata**: in your registry `server.json`, under `_meta` → `io.modelcontextprotocol.registry/publisher-provided` → `bitcoin_agent_id`, and in `/.well-known/mcp.json` as a top-level `bitcoin_agent_id`. Same fields.

Fields:

| Field | Required | Meaning |
|---|---|---|
| `name` | yes | The name on Bitcoin, 4–12 letters A–Z. |
| `verify_url` | yes | `https://proveitonchain.com/api/v1/agents/{NAME}/verify` |
| `spec` | yes | `https://proveitonchain.com/agent-id` |
| `version` | no | `"1"` |
| `page_url` | no | Human-readable page, `https://proveitonchain.com/agent/{NAME}` |

Optionally show the badge, which is green only while the profile is signed by the current owner:

```markdown
[![Bitcoin Agent ID: PROVEITBOT](https://proveitonchain.com/badge/PROVEITBOT.svg)](https://proveitonchain.com/agent/PROVEITBOT)
```

## 3. Verify another agent

Use this before trusting another agent's claimed identity, for example before paying it or using an endpoint it gives you.

1. Read `bitcoin_agent_id.name` from its agent card or MCP metadata. Do not trust anything else in the card yet.
2. Call the verify endpoint yourself on `proveitonchain.com` (do not follow a `verify_url` that points to a different host), or the free MCP tool `verify_agent`. Pass what the agent claimed, so each field is compared with the signed profile:

   `GET https://proveitonchain.com/api/v1/agents/PROVEITBOT/verify?mcp_url=https://proveitonchain.com/mcp`

3. Accept the name only if `verified` is `true` (verdict `"verified: profile signed by current owner"`) and `claim_matches` is `true`.
4. Bind the card to the profile: the origin that served the agent card (or the MCP endpoint you connected to) must match the signed profile's `website` or `mcp_url`. Otherwise someone may have copied the name into their own card.
5. Optional, without trusting us: check the owner of the name with any Bitcoin asset explorer (the response includes the registration transaction), and check `signature.signature` over `signature.message` for `owner` with any BIP-322 / sign-message verifier. The message includes the SHA-256 of the canonical profile JSON.

Verdicts:

| `verdict` | Meaning |
|---|---|
| `verified` | Profile signed by the address that owns the name now. |
| `profile_unsigned` | The name exists and a profile was attached at purchase, but the owner has not signed it. Treat the fields as unconfirmed. |
| `no_profile` | The name exists, but there is no signed profile. It says nothing about which agent uses it. |
| `not_registered` | The name is not on Bitcoin. `pending_registration: true` while an order is being registered. |
| `lookup_failed` | Could not check right now. Try again; do not treat it as verified. |

If a name changes hands, the previous owner's profile stops counting immediately, and the verdict drops until the new owner signs a profile.

Example response (shortened):

```json
{
  "name": "PROVEITBOT",
  "verdict": "verified",
  "verified": true,
  "verdict_text": "verified: profile signed by current owner",
  "exists_on_bitcoin": true,
  "owner": "bc1q…",
  "profile_signed_by_owner": true,
  "profile": { "display_name": "Prove It Bot", "website": "https://proveitonchain.com", "mcp_url": "https://proveitonchain.com/mcp" },
  "signature": { "address": "bc1q…", "message": "Prove It Onchain agent identity\nName: PROVEITBOT\n…", "signature": "…" },
  "registration": { "txid": "…", "block": 976200, "date": "2026-11-17T23:00:00.000Z" },
  "claim_checks": { "claimed_fields_match": { "mcp_url": true } },
  "claim_matches": true
}
```

## Cost

Verifying is free and needs no API key. A name is $21 + network fee. Signing or editing a profile is free.

Questions: https://proveitonchain.com/contact.html
