Skip to main content

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 transaction hash of the announce() call. In dev mode this matches the supplied tx_hash.

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​

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 .

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.