Stealth endpoints

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

01

Create stealth payload

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

02

Publish announcement

Store the returned payment_id 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.

Response schema

payment_idstringrequired

Server-held pending-payment identifier required by the preferred publish path.

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. This value is bound to payment_id server-side.

announcementobjectrequired

Announcement object returned for client-side reference and fallback publish.

idintegerrequired

Announcement ID value from in-memory construction.

ephemeral_keystringrequired

Hex ephemeral ciphertext.

view_tagintegerrequired

Announcement view tag.

timestampintegerrequired

Unix timestamp set at creation.

source_chain_idinteger

Optional EIP-155 source-chain ID.

tx_hashstring

Optional Monad announce transaction hash.

payment_tx_hashstring

Optional source-chain payment transaction hash.

amountstring

Optional amount string.

chainstring

Optional chain identifier.

stealth_addressstring

Optional recipient stealth address.

POST /api/v1/stealth/scan

Request schema

viewing_skstringrequired

Viewing secret key in hex.

spending_pubstringrequired

Spending public key in hex (33-byte compressed secp256k1). The scan endpoint never accepts the spending secret key — it returns each match's shared_secret so the client derives spend keys locally.

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.

stealth_addressstringrequired

Discovered EVM stealth address.

stealth_sui_addressstringrequired

Discovered Sui stealth address.

shared_secretstringrequired

Hex ML-KEM shared secret for this match. The client uses it with the spending secret key locally to derive the one-time stealth private key — the server never sees the spend key.

announcement_idintegerrequired

Registry ID of the matched announcement.

timestampintegerrequired

Announcement timestamp (Unix seconds).

tx_hashstring

Optional Monad announce transaction hash.

payment_tx_hashstring

Source-chain payment transaction hash decrypted from metadata.

amountstring

Optional amount (hex uint256; empty when unavailable).

chainstring

Optional chain identifier.

source_chain_idinteger

EIP-155 source-chain ID decrypted from metadata.

statsobjectrequired

Scan execution metrics.

total_scannedintegerrequired

Number of announcements scanned.

view_tag_matchesintegerrequired

Number of announcements that passed the view-tag filter after decapsulation.

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_pub":"<HEX_SPENDING_PUB>",
    "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.payment_id, 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).

No private keys in discoveries

Discovery output contains shared_secret, not private keys. The scan is spend-key-free: the client combines shared_secret with the spending secret key locally to derive the one-time stealth private key. The server never receives or returns spend keys.

Warning

viewing_sk and every shared_secret in the response are sensitive — a shared secret plus the spending secret key recovers a spendable key. Treat them as production secrets.