Stealth endpoints

WS

Create payment payload

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

R

Scan announcements

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

M

Publish announcement

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

Workflow

01

Create stealth payload

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

02

Publish announcement

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

03

Scan with recipient keys

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

POST /api/v1/stealth/create

Request schema

meta_addressstringrequired

Hex-encoded recipient meta-address.

channel_idstring

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

Response schema

stealth_addressstringrequired

Checksummed stealth EVM address.

stealth_sui_addressstringrequired

Stealth Sui address derived from the same key material.

ephemeral_ciphertextstringrequired

Hex-encoded ephemeral ciphertext.

view_tagintegerrequired

1-byte view tag for fast filtering.

announcementobjectrequired

Announcement object ready for registry publication.

idintegerrequired

Announcement ID value from in-memory construction.

ephemeral_keystringrequired

Hex ephemeral ciphertext.

view_tagintegerrequired

Announcement view tag.

timestampintegerrequired

Unix timestamp set at creation.

channel_idstring

Optional channel id.

tx_hashstring

Optional transaction hash.

amountstring

Optional amount string.

chainstring

Optional chain identifier.

POST /api/v1/stealth/scan

Request schema

viewing_skstringrequired

Viewing secret key in hex.

spending_pkstringrequired

Spending public key in hex.

spending_skstringrequired

Spending secret key in hex.

view_tagsarray

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

from_timestampinteger

Optional scan window start (Unix timestamp).

to_timestampinteger

Optional scan window end (Unix timestamp).

Response schema

discoveriesarrayrequired

Array of discovered payments.

statsobjectrequired

Scan execution metrics.

total_scannedintegerrequired

Number of announcements scanned.

view_tag_matchesintegerrequired

Count of matching results returned by the scan path.

discoveriesintegerrequired

Number of discovered payments.

duration_msintegerrequired

Total scan duration in milliseconds.

ratenumberrequired

Scan throughput (announcements per second).

Example calls

Create (cURL)

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

Scan (cURL)

curl -s -X POST https://backend.specterpq.com/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("https://backend.specterpq.com/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.

Warning

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