Migration from main v1

No compatibility identity layer

API v1 is the redesigned canonical contract. Historical numeric agentId, ambiguous chainId/agentId pairs, and route aliases are not retained. Migration resolves authoritative locators and writes a report; it never adds a long-lived legacy ID column or silently picks the first match.

Endpoint mapping

• Old agent lists become GET /api/v1/agents with repeated typed filters and signed cursors.
• Old agent detail becomes GET /api/v1/agents/{entityPublicId}.
• Chain-local identity lookup becomes POST /api/v1/resolve/agent-identities.
• Old score fields become rank/trust/performance subresources with methodology, coverage, confidence, and freshness.
• Wallet ownership lists become the public wallet-agent relation API with explicit relation/proof.
• Statistics become /api/v1/stats/* immutable projections.

Deterministic migration input

Use the repository command pnpm exec tsx scripts/migration/resolve-legacy-identifiers.ts --input legacy-identifiers.jsonl --output migration-report.jsonl. Each input line identifies its old source plus enough authoritative context:

{"source":"main-v1","legacyAgentId":"123","networkFamily":"EVM","network":"eip155:8453","protocol":"ERC8004","locatorKind":"REGISTRY_TOKEN","registry":"0x0000000000000000000000000000000000000000","nativeId":"42"}

The report is stable-sorted and records UNIQUE, AMBIGUOUS, CONFLICTED, NOT_FOUND, or INVALID, candidate public identity/entity UUIDs, normalized locator, reasons, and canonical URL. Ambiguous and conflicted records require review.

SVM and URI identities

For SVM include the canonical network UUID/key, protocol or asset scheme, and base58 account/asset locator. For DID or off-chain registry identities include the identity scheme and canonical URI/registry key. Do not map an address to every agent it has funded or transferred to.

Cutover

Run the report against a frozen input, resolve review rows, update stored UUIDs, verify fixture counts and sample profiles, then switch clients to v1. Keep the report as migration evidence. Do not proxy old routes or dual-write legacy fields.