Migrating from legacy

Existing read integrations keep working unchanged. To use v2 features, read from /v2 and write with signed actions.

What's new in v2

Area	Legacy registry	Registry v2
Edit metadata	Not possible	Category tags, trading venues and custom fields through signed issuer actions
Issuer key	Fixed forever	Rotation, with published key history
Authorization	Signature only for deletion	Every change signed, hash-chained, nonce-protected, time-limited
Domain proof	Per asset (HTTP file or DNS TXT)	Same, plus a pubkey-bound proof published once per domain
Contract format	Version 0, `issuer_pubkey`	Version 2 with `initial_issuer_pubkey`; same precision (0–8) and ticker (3–24) limits as legacy
Icons	All icons in one Base64 map (/icons.json), added and changed by registry admins	Issuers propose icons with a signed request, and admins still approve them. Each approved image gets its own PNG URL that never changes, so a new icon shows up as a new URL in `icon.href`
Moderation	—	Admin annotations: featured, delisted, malicious, asset type
History	Git commit history of the registry database (asset_registry_db): one commit per registration or deletion	Append-only audit log with a verifiable hash chain
Listing	One large object	Search with filters, sorting and paging
Operators	Shared credentials	Individually keyed admins with permissions

What keeps working

All legacy endpoints, at the same paths: POST /, GET /index.json (also served at GET /), GET /:asset_id, GET /icons.json, POST /contract/validate and DELETE /:asset_id.

What behaves differently

v2 assets in legacy listings have version: 2, their key in contract.initial_issuer_pubkey, and no top-level issuer_pubkey. Code that reads issuer_pubkey must handle its absence. For the key that currently controls an asset, read current_issuer_pubkey from GET /v2/assets/:asset_id: initial_issuer_pubkey never changes.
After a key rotation, legacy reads still show the original issuer_pubkey, and the legacy DELETE must be signed with the current key.
Flagged assets aren't hidden. Delisted or malicious assets still appear in every listing and lookup. Only v2 responses carry the flags (admin.delisted, admin.malicious), so check them before showing an asset; legacy endpoints don't show them at all.
v2 deregistration removes the asset from legacy endpoints too.
Stricter input: lower-case ASCII domains, no NUL characters, legacy contracts ≤ 4,096 bytes with ≤ 32 extra fields.
JSON errors (reference), and unknown query parameters are rejected.
Rate limit on registration (30 per minute per IP by default).

What to do

You are	Required	Recommended
Wallet, explorer, exchange (reads)	Handle a missing `issuer_pubkey`; read `current_issuer_pubkey` and the `admin` flags from v2 (legacy responses don't carry them); no unknown query parameters or `Content-Type` on bodiless GETs; parse both error shapes	Read /v2/assets/:asset_id; sync with updated_after; use `icon.href` instead of `/icons.json`
Issuer with a new asset	—	Issue with a version 2 contract and register through v2
Libraries & tooling that issue and register assets (e.g. LWK)	Nothing for legacy registration (version 0 contracts and POST / keep working). If you read GET /:asset_id, accept version 2 contracts: key in `contract.initial_issuer_pubkey`, no `issuer_pubkey`, and `issuance_txin`/`issuance_prevout` may be `null`. Parse JSON errors and handle 429 without blind retries (registration isn't idempotent)	Add version 2 contracts with `initial_issuer_pubkey`, register them through POST /v2/assets, and keep the issuer key signable for later updates. See Libraries that register assets
Issuer with a legacy asset	Nothing, to keep it as is	Get it migrated to update metadata, rotate keys or propose icons

🚧
Migration is admin-only today, and every mainnet asset is still legacy. Until issuer self-migration ships, contact Blockstream to get your asset migrated. Legacy assets without a ticker can't be migrated.