Stealth endpoints

Create stealth payment payloads and scan announcements for discoveries

Create payment payload

POST /api/v1/stealth/create derives stealth destination and announcement data.

Scan announcements

POST /api/v1/stealth/scan discovers payments addressed to your keys.

Publish announcement

Push announcement objects to the registry so recipients can discover them.

Workflow

1. Create stealth payload

   Send recipient meta_address to /api/v1/stealth/create.

2. Publish announcement

   Store the returned announcement with /api/v1/registry/announcements.

3. Scan with recipient keys

   Use /api/v1/stealth/scan and recipient key material to recover discoveries.

POST /api/v1/stealth/create

Request schema

meta_address · string · required

Hex-encoded recipient meta-address.

channel_id · string

Optional channel identifier field in DTO. Current create handler does not use this field.

Response schema

stealth_address · string · required

Checksummed stealth EVM address.

stealth_sui_address · string · required

Stealth Sui address derived from the same key material.

ephemeral_ciphertext · string · required

Hex-encoded ephemeral ciphertext.

view_tag · integer · required

1-byte view tag for fast filtering.

announcement · object · required

Announcement object ready for registry publication.

id · integer · required

Announcement ID value from in-memory construction.

ephemeral_key · string · required

Hex ephemeral ciphertext.

view_tag · integer · required

Announcement view tag.

timestamp · integer · required

Unix timestamp set at creation.

channel_id · string

Optional channel id.

tx_hash · string

Optional transaction hash.

amount · string

Optional amount string.

chain · string

Optional chain identifier.

POST /api/v1/stealth/scan

Request schema

viewing_sk · string · required

Viewing secret key in hex.

spending_pk · string · required

Spending public key in hex.

spending_sk · string · required

Spending secret key in hex.

view_tags · array

Optional list of specific view tags to pre-filter announcements.

from_timestamp · integer

Optional scan window start (Unix timestamp).

to_timestamp · integer

Optional scan window end (Unix timestamp).

Response schema

discoveries · array · required

Array of discovered payments.

stats · object · required

Scan execution metrics.

total_scanned · integer · required

Number of announcements scanned.

view_tag_matches · integer · required

Count of matching results returned by the scan path.

discoveries · integer · required

Number of discovered payments.

duration_ms · integer · required

Total scan duration in milliseconds.

rate · number · required

Scan throughput (announcements per second).

Example calls

Create (cURL)

curl -s -X POST http://localhost:3001/api/v1/stealth/create \
  -H "Content-Type: application/json" \
  -d '{"meta_address":"<HEX_META_ADDRESS>"}' | jq .

Scan (cURL)

curl -s -X POST http://localhost:3001/api/v1/stealth/scan \
  -H "Content-Type: application/json" \
  -d '{
    "viewing_sk":"<HEX_VIEWING_SK>",
    "spending_pk":"<HEX_SPENDING_PK>",
    "spending_sk":"<HEX_SPENDING_SK>",
    "view_tags":[42]
  }' | jq .

JavaScript

const createRes = await fetch("http://localhost:3001/api/v1/stealth/create", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ meta_address })
});

const createData = await createRes.json();
console.log(createData.stealth_address, createData.view_tag);

Filter precedence in scan handler

Scan selection uses this order: view_tags filter first, else time range when both from_timestamp and to_timestamp are provided, else full registry scan.

Hex prefix handling

Scan key fields accept values with or without a 0x prefix (strip_hex_prefix in handler).

Secret material in discoveries

Discovery output includes stealth_sk and eth_private_key. Treat response payload as highly sensitive.

Treat all secret key fields and scan discovery private keys as production secrets.