Skip to main content

API Quickstart

Note

This quickstart uses the hosted backend at https://backend.specterpq.com. For local development, see Development Setup.

The full flow in 4 steps​

Step 1: Generate recipient keys​

curl -s -X POST https://backend.specterpq.com/api/v1/keys/generate | tee /tmp/specter-keys.json
META_ADDRESS=$(jq -r '.meta_address' /tmp/specter-keys.json)
VIEWING_SK=$(jq -r '.viewing_sk' /tmp/specter-keys.json)
SPENDING_PK=$(jq -r '.spending_pk' /tmp/specter-keys.json)
SPENDING_SK=$(jq -r '.spending_sk' /tmp/specter-keys.json)

This creates two ML-KEM-768 keypairs and bundles the public keys into a meta_address.

Step 2: Create the stealth payload​

curl -s -X POST https://backend.specterpq.com/api/v1/stealth/create \
  -H 'Content-Type: application/json' \
  -d "{\"meta_address\":\"$META_ADDRESS\"}" | tee /tmp/specter-create.json

EPHEMERAL_KEY=$(jq -r '.ephemeral_ciphertext' /tmp/specter-create.json)
VIEW_TAG=$(jq -r '.view_tag' /tmp/specter-create.json)
STEALTH_ADDRESS=$(jq -r '.stealth_address' /tmp/specter-create.json)
echo "Stealth destination: $STEALTH_ADDRESS"

The API encapsulates to the recipient's viewing_pk, derives a shared secret, and computes the stealth address + view tag.

Step 3: Publish the announcement​

curl -s -X POST https://backend.specterpq.com/api/v1/registry/announcements \
  -H 'Content-Type: application/json' \
  -d "{\"ephemeral_key\":\"$EPHEMERAL_KEY\",\"view_tag\":$VIEW_TAG,\"tx_hash\":\"0x1111111111111111111111111111111111111111111111111111111111111111\",\"amount\":\"0.01\",\"chain\":\"ethereum\"}" | jq .

Step 4: Scan and recover​

curl -s -X POST https://backend.specterpq.com/api/v1/stealth/scan \
  -H 'Content-Type: application/json' \
  -d "{\"viewing_sk\":\"$VIEWING_SK\",\"spending_pk\":\"$SPENDING_PK\",\"spending_sk\":\"$SPENDING_SK\"}" | jq .

You should see:

  • One discovery in the results
  • stealth_address matching what you got in step 2
  • eth_private_key for spending the funds
Warning

Treat the scan response like wallet secret material. The eth_private_key and stealth_sk fields can spend real funds. Don't log them or expose them in client analytics.

What just happened?​

You ran the complete SPECTER protocol:

  1. Key generation - Created ML-KEM-768 keypairs
  2. Payment creation - Used ML-KEM encapsulation to derive a one-time stealth address
  3. Announcement - Published the encrypted breadcrumb
  4. Scanning - Used view tag filtering + ML-KEM decapsulation to find and recover the payment

The stealth address from step 2 has no visible link to the meta-address from step 1. That's the privacy.

Full protocol explanation

Understand each step in depth.

API reference

Full endpoint documentation.

Integration guide

Build SPECTER into your app.