Registry endpoints

Publish

POST /api/v1/registry/announcements validates and stores new announcements.

List

GET /api/v1/registry/announcements returns paginated announcements with filters.

Stats

GET /api/v1/registry/stats returns total count and non-zero view-tag distribution.

POST /api/v1/registry/announcements

Request schema

payment_idstring

Preferred publish path. Use the payment_id returned by /api/v1/stealth/create.

announcementobject

Fallback publish path. Use the full announcement object returned by /api/v1/stealth/create only when payment_id is unavailable or expired.

tx_hashstring

Monad announce transaction hash. Required when the relayer is not configured; ignored when server-side relaying is active.

payment_tx_hashstring

Optional source-chain payment transaction hash for verification and encrypted metadata.

source_chain_idinteger

Optional EIP-155 chain ID for the source-chain payment.

amountstring

Optional amount string in decimal base units or 0x hex uint256.

chainstring

Optional source-chain name (for example ethereum, arbitrum, base, monad-testnet).

tokenstring

Optional ERC-20 token contract address for source-chain payment verification.

Response schema

idintegerrequired

Assigned registry announcement id.

successbooleanrequired

Publish confirmation.

monad_tx_hashstring

Monad Testnet transaction hash of the announce() call. Monad is the registry chain where announcements are recorded. When the relayer is not configured, this matches the tx_hash you supplied.

GET /api/v1/registry/announcements

Query parameters

view_taginteger

Filter announcements by a specific view tag.

from_timestampinteger

Start of time-range filter (Unix timestamp).

to_timestampinteger

End of time-range filter (Unix timestamp).

offsetintegerdefault: 0

Pagination offset.

limitintegerdefault: 100

Pagination limit.

Response schema

announcementsarrayrequired

Paginated announcement rows.

totalintegerrequired

Total matching rows before pagination.

GET /api/v1/registry/stats

Response schema

total_announcementsintegerrequired

Current total number of stored announcements.

view_tag_distributionarrayrequired

Array of non-zero tag buckets (tag, count).

Example calls

Publish (cURL)

curl -s -X POST https://backend.specterpq.com/api/v1/registry/announcements \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id":"<PAYMENT_ID_FROM_STEALTH_CREATE>",
    "tx_hash":"0xabc123...",
    "payment_tx_hash":"0xdef456...",
    "source_chain_id":1,
    "chain":"ethereum",
    "amount":"100000000000000000"
  }' | jq .

List (cURL)

curl -s "https://backend.specterpq.com/api/v1/registry/announcements?view_tag=42&offset=0&limit=20" | jq .

Stats (cURL)

curl -s "https://backend.specterpq.com/api/v1/registry/stats" | jq .

Behavior notes

Duplicate transaction hashes are rejected

Publish reserves a dedup slot before relaying. When server DB keys are configured, payment_tx_hash is normalized and HMACed for duplicate-payment prevention without storing the payment hash plaintext.

List filter precedence

Listing uses view_tag when present. If absent, it uses time range only when both from_timestamp and to_timestamp are provided. Otherwise it returns all.

Storage scope

API state uses MemoryRegistry in local/dev mode and Turso when REGISTRY_BACKEND=turso is configured.

Metadata encryption

The preferred payment_id path encrypts payment metadata into a 93-byte blob while keeping byte 0 (view_tag) plaintext. The fallback announcement path has no shared secret and emits 77-byte plaintext metadata.

The plaintext block is 77 bytes laid out as:

Bytes	Field	Size
0	view_tag	1
1-32	tx_hash	32
33-64	amount (uint256)	32
65-72	source_chain_id (big-endian u64)	8
73-76	reserved	4

Encryption uses AES-256-GCM and adds a 16-byte authentication tag over bytes 1-76, leaving the view_tag in the clear: 1 + 76 + 16 = 93 bytes. The @specterpq/sdk produces the same block client-side. See announcement metadata.