API Overview

The SPECTER REST API: endpoints, authentication, and how to get started

Quickstart

Run the full flow in 4 API calls.

Stealth endpoints

Create and scan stealth payments.

Yellow endpoints

Private trading channels.

Base URLs

Environment	URL
Production	https://backend.specterpq.com
Local dev	http://localhost:3001

Endpoint map

Group	Endpoints	Purpose
Keys	POST /keys/generate	Generate ML-KEM-768 keypairs and meta-address
Stealth	POST /stealth/create, POST /stealth/scan	Create stealth payments, discover incoming payments
Registry	POST /registry/announcements, GET /registry/announcements, GET /registry/stats	Store and query announcements
Names	GET /ens/resolve/:name, GET /suins/resolve/:name	ENS and SuiNS name resolution
IPFS	POST /ipfs/upload, GET /ipfs/:cid	Meta-address storage and retrieval
Yellow	POST /yellow/channel/*, GET /yellow/config	Private channel operations

The integration loop

1. Health check

   Confirm the backend is alive with GET /health.

2. Generate keys

   POST /api/v1/keys/generate returns spending/viewing keypairs and a meta-address.

3. Create stealth payment

   POST /api/v1/stealth/create with the recipient’s meta-address.

4. Publish announcement

   POST /api/v1/registry/announcements with the returned ciphertext and view tag.

5. Scan and recover

   POST /api/v1/stealth/scan with recipient keys to find and recover payments.

Quick health check

cURL

curl -s https://backend.specterpq.com/health | jq .

JavaScript

const res = await fetch("https://backend.specterpq.com/health");
const data = await res.json();
console.log(data.status, data.version);

Python

import requests
res = requests.get("https://backend.specterpq.com/health")
print(res.json())

Authentication and security

The API server includes built-in security middleware:

• API key auth for write endpoints (when API_KEY env var is set)
• Per-IP rate limiting (default: 10 req/s, 30 burst)
• Security headers (CSP, X-Frame-Options, X-Content-Type-Options)
• Body size limits to prevent abuse
• CORS configurable via ALLOWED_ORIGINS

If API_KEY is not configured, write routes are open. Always set an API key in production.

See Auth and Errors for the full error contract and status codes.

---

Need help with the API? Email [e-mail] or open an issue on GitHub.