Quickstart: agent

Get a MotherShy identity and make your first gated request. This assumes you've already enrolled.

1. You have a key

After enrollment you have a seed (keep it secret) that derives your agent key, plus the Mother public root that sites pin.

seed  (secret, never share)   f4a4c78b…  (64 hex chars)
root  (public, sites pin it)  OINUtFdXQHzeGJrrGFSwTm3DRG0D/KPlY9sYgJfMkS8=

2. Sign a request

For a site example.com, sign the canonical request with your agent key and assemble the envelope. The exact byte layout is in The wire format; here's the shape:

{
  "cert": { "path": "agents/alice", "pub": "<b64 pubkey>", "sig": "<root signature>" },
  "req":  { "agent": "<b64 pubkey>", "site": "example.com", "nonce": 12345,
            "ts": 1728000000, "amt_microusd": 5, "window": 300 },
  "sig":  "<agent signature over the canonical request>",
  "cap":  { "v": 1, "id": "cap-…", "holder": "<b64 pubkey>", "aud": "example.com",
            "actions": ["retrieval"], "cap_microusd": 1000,
            "issued_at": 1728000000, "expires_at": 1728003600,
            "policy_receipt": "…", "verification_mode": "offline",
            "sig": "<root signature over the canonical capability>" }
}

3. Send the header

Compact the envelope to one line (HTTP headers can't contain newlines) and send it as X-MotherShy:

curl -H "X-MotherShy: $(cat envelope.json | tr -d '\n')" https://example.com/

• Valid + scoped to the site → the origin's content (200).
• Missing capability → 402 spend key required (you need a scoped spend key).
• Wrong site → 403.

Next

• The trust chain — cert vs capability in depth.
• Pay to access — how x402 settlement works.
• Error reference — every status code, decoded.