Agent API TokenAddy

Everything on this page works with plain HTTP + JSON from any language or agent framework. No SDKs, no keys to buy.

Resolve a name free · no auth

curl https://tokenaddy.com/resolve/alice
curl https://tokenaddy.com/resolve/vitalik.eth        # ENS passthrough, no blockchain scanning
curl "https://tokenaddy.com/resolve/vitalik.eth?all=1" # side-by-side TokenAddy + ENS + DNS TXT

Animal Tier + human-readable age free · no auth

curl https://tokenaddy.com/tier/alice
# {"name":"alice","tier":"Dolphin","emoji":"🐬","balance_eth":12.4,"balance_human":"12.400000 ETH",
#  "age_human":"Created 2.1 years old","wallet":"0x.."}
# Tiers: Shrimp 🦐 <0.05 ETH · Seahorse 🐠 <0.5 · Tuna 🐟 <5 · Dolphin 🐬 <50 · Whale 🐳 ≥50

Register / update (agent auth token)

Generate any random string 16–128 chars — that string IS ownership. Keep it secret.

TOKEN=$(python3 -c "import secrets;print(secrets.token_hex(24))")
curl -X POST https://tokenaddy.com/register \
  -H 'Content-Type: application/json' \
  -d "{\"name\":\"mybot\",\"auth_token\":\"$TOKEN\",
       \"pointers\":{\"agent\":\"https://me.example.com\",\"eth\":\"0x..\"}}"

Multi-destination pointers are just JSON — wallets per chain, live agent endpoints, URLs, nested objects. Max 4KB. Same call updates an existing name you own.

Register / update (wallet signature)

For wallet-backed identities: request a challenge, sign with personal_sign, send once. Challenges expire in 5 minutes and are single-use.

CH=$(curl -s "https://tokenaddy.com/wallet/challenge?address=0xYOURADDR" | jq -r .challenge)
SIGNATURE=...   # personal_sign(CH) with your wallet
curl -X POST https://tokenaddy.com/register \
  -H 'Content-Type: application/json' \
  -d '{"name":"mybot",
       "wallet_auth":{"address":"0xYOURADDR","signature":"'$SIGNATURE'","challenge":"'$CH'"},
       "pointers":{"agent":"https://..."}}'

List everything you control

curl -X POST https://tokenaddy.com/my-names \
  -H 'Content-Type: application/json' -d '{"auth_token":"'$TOKEN'"}'
# or wallet_auth:{...} for wallet-owned names

Transfer ownership x402-ready hook

curl -X POST https://tokenaddy.com/transfer \
  -H 'Content-Type: application/json' \
  -d '{"name":"mybot","auth_token":"$TOKEN","to_wallet":"0xNEWOWNER"}'
# or "to_token":"new-secret-token" to hand it to another agent.
# If this action ever becomes paid, the endpoint returns HTTP 402 with an
# x402-style `accepts` payload — handle that and retry with X-Payment.

Release a name

curl -X DELETE https://tokenaddy.com/name/mybot \
  -H 'Content-Type: application/json' -d '{"auth_token":"$TOKEN"}'

Extras

Endpoint	What
`GET /available/<name>`	{"available":true\|false} — checks TokenAddy + ENS
`GET /history/<name>`	last 20 pointer changes (from → to)
`GET /whois/<name>`	created/updated timestamps
`GET /.well-known/tokenaddy/<name>`	TXT-style paste-ready record view
`GET /txt/<domain>`, `/dnssec/<domain>`	DNS-over-HTTPS lookups
`GET /qr/<name>`, `/card/<name>`	SVG QR + share card

x402 readiness

All mutating actions pass through a single server-side paywall hook. Today every action is free and the hook is a no-op. When premium names or priority updates go paid, affected endpoints return HTTP 402 with:

{"error":"payment_required","accepts":[{"scheme":"exact","maxAmountRequired":"1000","resource":"https://tokenaddy.com/register","network":"base"}]}

Retry the same request with an X-Payment header carrying your x402 payment payload. Free actions (resolve, tier, lookup, history) will never be paywalled.

← Back to the app