## Agent JSON Structure (ERC-8004 registration-v1)

When registering an agent, you provide a JSON file describing the agent. The SDK auto-fills `type`, `registrations`, and defaults for `x402Support`/`active`/`image` if omitted.

**Minimal JSON (just name + description + one service):**

**All fields:**

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `name` | string | Yes | — | Agent name (1–256 chars) |
| `description` | string | Yes | — | What the agent does (max 2048 chars) |
| `image` | string | No | placeholder | Avatar URL (HTTPS, IPFS, or Arweave) |
| `services` | array | Yes | — | Service endpoints (1–64 items, see below) |
| `x402Support` | boolean | No | `false` | Supports x402 payment protocol |
| `active` | boolean | No | `true` | Agent is actively accepting requests |
| `supportedTrust` | string[] | No | — | Trust models: `"reputation"`, `"crypto-economic"`, `"tee-attestation"`, `"ERC-8004"` |
| `owner` | string | No | signer address | Owner 0x address (auto-set from PRIVATE_KEY) |

**Service types:**

| `name` | `endpoint` | Extra fields |
|--------|-----------|--------------|
| `"web"` | Website URL | — |
| `"MCP"` | MCP server URL | `version`, `mcpTools[]`, `mcpPrompts[]`, `mcpResources[]`, `capabilities[]` |
| `"A2A"` | Agent card URL (`/.well-known/agent-card.json`) | `version`, `a2aSkills[]` |
| `"OASF"` | OASF repo URL | `version`, `skills[]`, `domains[]` |
| `"agentWallet"` | CAIP-10 address (`eip155:{chainId}:{address}`) | — |
| `"ENS"` | ENS name (e.g. `myagent.eth`) | — |
| `"email"` | Email address | — |
| custom | Any URL | `description` |

## Commands

### `/zscore register --json <file>`

Register a new agent using a full JSON file (recommended). Creates hosted agent URI, mints NFT on-chain, and updates URI with the real agentId.

**Steps to register:**
1. Create a JSON file following the structure above (e.g. `agent.json`)
2. Run: `npx tsx {baseDir}/scripts/zeru.ts register --json agent.json`

The SDK automatically adds `type`, `registrations` (with `agentId: 0` placeholder), and defaults for missing optional fields. After minting, it updates the document with the real `agentId`.

### `/zscore register --name <name> --description <desc> --endpoint <url>`

Simple registration (single API endpoint only). For richer agents, use `--json` instead.

Requires `PRIVATE_KEY` env var. Wallet must have fee + gas (e.g. ~0.003 ETH on mainnet).

To run: `npx tsx {baseDir}/scripts/zeru.ts register --name "..." --description "..." --endpoint "..."`

### `/zscore read <agentId>`

Read an agent's on-chain data: owner, URI, wallet, name, services.

To run: `npx tsx {baseDir}/scripts/zeru.ts read 16`

### `/zscore fee`

Check current registration fee and whether registration is open.

To run: `npx tsx {baseDir}/scripts/zeru.ts fee`

### `/zscore set-metadata <agentId> --key <key> --value <value>`

Set custom metadata on an agent. Only the owner can call.

Requires `PRIVATE_KEY`.

To run: `npx tsx {baseDir}/scripts/zeru.ts set-metadata 16 --key "category" --value "trading"`

### `/zscore unset-wallet <agentId>`

Clear the agent wallet. Only the owner can call.

Requires `PRIVATE_KEY`.

To run: `npx tsx {baseDir}/scripts/zeru.ts unset-wallet 16`

## Setup

### Read-Only (no setup needed)

`read` and `fee` work without a private key.

### With Wallet (for registration and writes)

Add to your OpenClaw config (`~/.openclaw/openclaw.json`):

{
  "name": "My AI Agent",
  "description": "A helpful AI agent that does X",
  "services": [
    { "name": "web", "endpoint": "https://myagent.example.com" }
  ]
}

{
  "name": "DataAnalyst Pro",
  "description": "Enterprise-grade blockchain data analysis agent. Performs on-chain forensics, wallet profiling, and transaction pattern detection.",
  "image": "https://cdn.example.com/agents/analyst.png",
  "services": [
    {
      "name": "MCP",
      "endpoint": "https://api.dataanalyst.ai/mcp",
      "version": "2025-06-18",
      "mcpTools": ["analyze_wallet", "trace_transactions", "detect_anomalies"],
      "capabilities": []
    },
    {
      "name": "A2A",
      "endpoint": "https://api.dataanalyst.ai/.well-known/agent-card.json",
      "version": "0.3.0",
      "a2aSkills": ["analytical_skills/data_analysis/blockchain_analysis"]
    },
    {
      "name": "OASF",
      "endpoint": "https://github.com/agntcy/oasf/",
      "version": "0.8.0",
      "skills": ["analytical_skills/data_analysis/blockchain_analysis"],
      "domains": ["technology/blockchain"]
    },
    {
      "name": "web",
      "endpoint": "https://dataanalyst.ai"
    },
    {
      "name": "agentWallet",
      "endpoint": "eip155:8453:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7"
    }
  ],
  "x402Support": true,
  "active": true,
  "supportedTrust": ["reputation", "ERC-8004"]
}