Signals and evidence, through an API.

Public signals · No key required

Responses include a success flag. A false flag means the data is unavailable; never treat it as a zero score. Scores are not success probabilities. Existing v1 score field names remain for compatibility. Historical score semantics are documented in the response metadata.

curl https://optaimaze.com/api/payment-reliability

Cache lifetime: 90–120 seconds. Public endpoints are limited to 60 requests per minute per connecting IP; forced cache bypass is disabled on public HTTP requests.

Submit observed outcomes

Create a telemetry key in your workspace. Send one terminal outcome per logical payment. Generate a random event ID and reuse it on retries to prevent duplicate counting. Do not send invoices, preimages, payment hashes, recipient identifiers, credentials, or raw logs.

curl -X POST https://optaimaze.com/api/telemetry \
  -H "Authorization: Bearer $OPTAIMAZE_TELEMETRY_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "event_id": "example-event-001",
    "outcome": "failed",
    "amount_sats": 10000,
    "fee_msat": 0,
    "latency_ms": 2500,
    "attempts": 2,
    "failure_code": "NO_ROUTE",
    "occurred_at": "REPLACE_WITH_CURRENT_UTC_TIMESTAMP"
  }'

Use a UTC timestamp such as 2026-11-03T17:34:52Z, within the past 90 days. Supported outcomes: succeeded and failed. Integer fields must be JSON integers. Failure categories use uppercase letters, digits, and underscores. Unknown fields are ignored and never persisted.

201: accepted. 200 with duplicate: true: event ID already exists. 401/403: authentication or scope error. 413: payload over 16 KB. 422: invalid data. 429: rate or quota limit. 503: unavailable. Retry temporary failures with exponential backoff and the same event ID.

Pilot limits: 60 requests/minute per account and 10,000 accepted events per rolling day. Keep keys server-side. Revocation takes effect immediately.

Read-only LND collector

Run the Python collector on your own node host. It reads ListPayments and submits only terminal outcomes. Your macaroon, TLS certificate, routes, invoices, and payment hashes stay in your infrastructure. It never sends payments or changes routing settings.

export LND_REST_URL=https://localhost:8080
export LND_READONLY_MACAROON=/private/path/listpayments.macaroon
export LND_TLS_CERT=/private/path/tls.cert
# Set OPTAIMAZE_TELEMETRY_KEY in your protected service environment.
python3 optaimaze-lnd.py --state /private/path/optaimaze-lnd-state.json

Use Python 3.10+ and a macaroon restricted to /lnrpc.Lightning/ListPayments. Preserve the private state file for stable hashed event IDs and pending-payment checkpoints. Schedule the command every few minutes. It limits submissions to the pilot API rate, retains checkpoints on errors, and revisits in-flight payments. Defaults to ten pages per run; --max-pages supports up to 100.

The collector reports attempts=1 because HTLC shards do not identify logical retries. Latency depends on LND resolution timestamps, with a creation-time fallback. For exact application retry counts, submit your own terminal outcomes. The connector has fixture tests; testing against your node requires your local setup.

Signed monitoring webhooks

Configure an HTTPS endpoint for a saved monitor in your workspace after the pilot team approves its hostname. Save the one-time signing secret securely. Verify HMAC-SHA256 over the timestamp header, a period, and the raw body; compare with X-Optaimaze-Signature (sha256=hex). Reject timestamps older than five minutes and deduplicate event_id. Delivery records show sent, failed, or dry run. Temporary failures retry up to five times with backoff. Your receiver must deduplicate event_id because delivery is at least once.

Scheduled reports

Choose daily, weekly, or off in your workspace. Verify your email from the workspace, then save a daily or weekly schedule. You can turn it off at any time.

Read your aggregate report

Create a separate reports key. It cannot submit events.

curl https://optaimaze.com/api/customer-report \
  -H "Authorization: Bearer $OPTAIMAZE_REPORTS_KEY"

Returns seven-day totals, observed success percentage, average latency, reported fees, retries, and failure categories. With no events, success percentage is null.

Collector integration

Run the collector within your infrastructure. After a payment finishes, map its result into the minimal event schema and submit over HTTPS. Use a persistent event ID for delivery retries. The ingestion key grants no access to your node. An optional read-only LND collector is available below; other applications can submit the same minimal schema.