Migration Guide

Migrating to .agent/wallets.json

If your agent currently declares wallets at .x402books/wallets.json, this guide covers the migration to the canonical path.

TL;DR: Rename the file. Both paths are fetched — no schema changes required, no re-submission needed. The old path continues to work indefinitely as a fallback.

What changed

The manifest is now part of an open, ecosystem-neutral standard — not a Zetta-specific format. The canonical path has moved from .x402books/wallets.json to.agent/wallets.json to reflect this.

Before

.x402books/wallets.json

After

.agent/wallets.json

Migration steps

Rename the directory

Rename .x402books/ to .agent/ in your repository root. The wallets.json filename stays the same.

# In your repo root
mv .x402books .agent

# Or create fresh
mkdir .agent
cp .x402books/wallets.json .agent/wallets.json

Optionally add the version field

Add "version": "1.0" to your manifest root. This signals to all tooling that you're on the current spec.

{
  "version": "1.0",
  "agent": "Your Agent",
  "wallets": [...]
}

Update your GitHub Action (if applicable)

If you have a CI workflow that validates your manifest, update the path.

# .github/workflows/validate-manifest.yml
- name: Validate manifest
  run: |
    curl -s -X POST https://zetta.xyz/api/validate-manifest \
      -H "Content-Type: application/json" \
      -d @.agent/wallets.json | jq -e '.ok == true'

No re-submission needed

Your existing registry record is not affected. Zetta fetches both paths on every manifest check — your attribution status, books, and profile remain unchanged.

Backward compatibility

The fetch pipeline checks both paths in order. .agent/wallets.json is tried first; .x402books/wallets.json is tried as a fallback. The legacy path will continue to work indefinitely.

Fetch order

.agent/wallets.json (main)Primary

.agent/wallets.json (master)Primary fallback

.x402books/wallets.json (main)Legacy fallback

.x402books/wallets.json (master)Legacy fallback

Role changes in v1.0

The role vocabulary expanded in v1.0. Old roles continue to work — they are normalized to their v1.0 equivalents:

Old role	Maps to	Action required
fee	fee_recipient	Optional update — same classification
treasury	treasury	No change
deployer	deployer	No change
operator	operator	No change
unknown	unknown	No change

New roles available in v1.0: revenue, expense, payment_receiver, token_contract, token_bound_account. See full role reference →

Questions?

If your manifest is not being picked up after migration, verify the file exists at .agent/wallets.json on the main or master branch of a public GitHub or Gitlawb repo. Use the validator to confirm the format is correct.

Validate your manifest →

← Examples Back to Spec →