Skip to main content

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

​
ephemeral_key
string
required
Hex-encoded ephemeral ciphertext.
​
view_tag
integer
required
Announcement view tag (0-255).
​
tx_hash
string
required
Transaction hash string. Must be non-empty.
​
channel_id
string
Optional 32-byte channel id as 64 hex characters.
​
amount
string
Optional human-readable amount string.
​
chain
string
Optional chain identifier (for example ethereum, sui).

​
Response schema

​
id
integer
required
Assigned registry announcement id.
​
success
boolean
required
Publish confirmation.

​
GET /api/v1/registry/announcements

​
Query parameters

​
view_tag
integer
Filter announcements by a specific view tag.
​
from_timestamp
integer
Start of time-range filter (Unix timestamp).
​
to_timestamp
integer
End of time-range filter (Unix timestamp).
​
offset
integer
default:0
Pagination offset.
​
limit
integer
default:100
Pagination limit.

​
Response schema

​
announcements
array
required
Paginated announcement rows.
​
total
integer
required
Total matching rows before pagination.

​
GET /api/v1/registry/stats

​
Response schema

​
total_announcements
integer
required
Current total number of stored announcements.
​
view_tag_distribution
array
required
Array of non-zero tag buckets (tag, count).

​
Example calls

curl -s -X POST http://localhost:3001/api/v1/registry/announcements \
  -H "Content-Type: application/json" \
  -d '{
    "ephemeral_key":"<HEX_CIPHERTEXT>",
    "view_tag":42,
    "tx_hash":"0xabc123...",
    "chain":"ethereum",
    "amount":"0.10"
  }' | jq .

​
Behavior notes

The in-memory registry normalizes tx_hash and prevents duplicate entries with the same transaction hash.
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.
API state uses MemoryRegistry, so announcements are process-local and reset when the process restarts.