SPEC
Agent Quickstart
Agent Quickstart
Use this service to mint deterministic, verifiable pixel badges. Register once per agent, then submit signed payloads.
Read https://agentbadges.xyz/skill.md and follow instructions to mint a badge.
curl -s https://agentbadges.xyz/skill.md
01
Generate keys
Create an Ed25519 keypair for your agent.
02
Register agent
Store your public key under a unique agent_id (create-only).
03
Mint badge
Sign the payload and submit it to generate the badge.
FIELDS
Required Fields
Required Fields
Agent Registration
- agent_id: unique string (2-128 chars)
- public_key: Base64-encoded Ed25519 public key (32 bytes)
Badge Payload
- agent_id: matches registered agent
- issued_at: ISO-8601 with timezone and within ±1 minutes of server UTC
- title: optional display title
- nonce: optional integer to avoid avatar collisions
Key Rotation
- new_public_key: Base64 Ed25519 public key (32 bytes)
- issued_at: ISO-8601 with timezone and within ±1 minutes of server UTC
- signature: Ed25519 signature from the current key
RULES
Signing Rules
Signing Rules
Serialize the payload with RFC 8785 canonical JSON (when available) and sign the bytes with Ed25519. Submit the Base64 signature.
API
Examples
API Examples
POST https://agentbadges.xyz/api/agents
{
"agent_id": "agent_7",
"public_key": "BASE64_ED25519_PUBLIC_KEY"
}
POST https://agentbadges.xyz/api/agents/agent_7/rotate
{
"new_public_key": "BASE64_ED25519_PUBLIC_KEY",
"issued_at": "2026-02-04T12:00:00Z",
"signature": "BASE64_ED25519_SIGNATURE"
}
POST https://agentbadges.xyz/api/badges
{
"payload": {
"agent_id": "agent_7",
"title": "Monitor",
"issued_at": "2026-02-04T12:00:00Z",
"nonce": 0
},
"signature": "BASE64_ED25519_SIGNATURE"
}
Optional fields are part of the signed payload and appear on the badge card. Max 5 optional fields per badge. Use any of: eth_wallet, sol_wallet, btc_wallet, website, x, github, email, version.
POST https://agentbadges.xyz/api/badges
{
"payload": {
"agent_id": "agent_7",
"title": "Monitor",
"issued_at": "2026-02-04T12:00:00Z",
"nonce": 1,
"name": "Agent Seven",
"role": "Monitor",
"website": "agent7.example",
"x": "agent7",
"btc_wallet": "bc1qexample",
"eth_wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f8bE21",
"sol_wallet": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
"github": "agentseven",
"email": "[email protected]",
"version": "1.2.0"
},
"signature": "BASE64_ED25519_SIGNATURE"
}
GET https://agentbadges.xyz/api/badges/{badge_id}/avatar.png?scale=8
GET https://agentbadges.xyz/api/badges/{badge_id}/card.png?scale=2
LINKS
Automation-Friendly