Entrpy Private Pilot Integration Guide

01 / Pilot scope

What is available today

API-key-authenticated latest-price queries.
Webhooks for every observed price change.
One-shot strict > and < absolute-price thresholds.
Subscription listing, signed test delivery, and deletion.
HMAC-SHA256 signatures and persistent, at-least-once delivery.

Supported topics

BTCUSD
ETHUSD
SOLUSD
BNBUSD
XRPUSD
DOGEUSD

02 / Getting started

Connect to the pilot API

Base URLhttps://api.entrpy.dev

Entrpy manually provides YOUR_API_KEY during onboarding. Send it as X-API-Key on every endpoint below. Keep API keys and webhook secrets out of source control.

Your webhook URL must normally be public HTTPS on port 443. Localhost and private network destinations are rejected.

Query the latest observed price

Shell

curl "https://api.entrpy.dev/query/BTCUSD" \
  -H "X-API-Key: YOUR_API_KEY"

Example response

{
  "topic": "BTCUSD",
  "value": "70125.5"
}

A supported topic returns 404 until Entrpy stores its first observation. Topic input is case-insensitive.

03 / Subscriptions

Create webhook subscriptions

Every observed price change

Omit both condition fields. This subscription remains active and emits price.changed events.

Unconditional

curl -X POST "https://api.entrpy.dev/subscribe" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "BTCUSD",
    "webhook_url": "YOUR_WEBHOOK_URL"
  }'

Price greater than a threshold

Strict >

curl -X POST "https://api.entrpy.dev/subscribe" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "ETHUSD",
    "webhook_url": "YOUR_WEBHOOK_URL",
    "condition_op": ">",
    "condition_value": 4000
  }'

Price less than a threshold

Strict <

curl -X POST "https://api.entrpy.dev/subscribe" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "BTCUSD",
    "webhook_url": "YOUR_WEBHOOK_URL",
    "condition_op": "<",
    "condition_value": 60000
  }'

condition_op and condition_value must both be present or both be omitted. Thresholds are strict, absolute, and one-shot. Once a matching event is persisted, the subscription is marked triggered; that event is retried if delivery fails.

Save the webhook_secret from the create response as YOUR_WEBHOOK_SECRET. It is not returned by the subscription list endpoint. An identical create request returns the existing subscription and secret with HTTP 200 and status: "already_exists".

04 / Manage and test

Operate your subscriptions

List subscriptions

Shell

curl "https://api.entrpy.dev/subscriptions" \
  -H "X-API-Key: YOUR_API_KEY"

Send a test webhook

Shell

curl -X POST "https://api.entrpy.dev/subscriptions/SUBSCRIPTION_ID/test" \
  -H "X-API-Key: YOUR_API_KEY"

A test follows the real signed delivery path and contains event_type: "test" and test: true. It does not change the latest price or trigger the subscription. Delivery failure returns 502; rapid repeated tests can return 429.

Delete a subscription

Shell

curl -X DELETE "https://api.entrpy.dev/subscriptions/SUBSCRIPTION_ID" \
  -H "X-API-Key: YOUR_API_KEY"

05 / Webhook contract

Payload and headers

Threshold event

{
  "event_id": "evt_2c886077c18f45749b58d1a2d85f9035",
  "event_type": "price.threshold_triggered",
  "topic": "BTCUSD",
  "old_value": "69950.0",
  "new_value": 70125.5,
  "condition": {
    "operator": ">",
    "threshold": 70000.0
  },
  "triggered_at": "2026-07-29T12:00:00Z"
}

Unconditional events use price.changed and condition: null. The current pipeline can encode old_value as a string and new_value as a number.

Request headers

Content-Type: application/json
Entrpy-Event-Id: evt_...
Entrpy-Timestamp: <Unix seconds>
Entrpy-Signature: v1=<hex HMAC-SHA256>

06 / Authentication

Verify the signature before parsing

Read the exact raw body. Entrpy signs ASCII(timestamp) + "." + raw_body using the subscription's YOUR_WEBHOOK_SECRET. The example enforces a 300-second timestamp tolerance.

Python

import hashlib
import hmac
import time

def verify_entrpy_webhook(raw_body, timestamp, signature, secret):
    try:
        timestamp_value = int(timestamp)
    except (TypeError, ValueError):
        return False
    if abs(int(time.time()) - timestamp_value) > 300:
        return False
    if not signature.startswith("v1="):
        return False
    supplied = signature[3:]
    if len(supplied) != 64:
        return False
    expected = hmac.new(
        secret.encode("ascii"),
        timestamp.encode("ascii") + b"." + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, supplied.lower())

A runnable FastAPI implementation is included in examples/webhook_receiver.py.

07 / Idempotency

Handle duplicate deliveries safely

Entrpy provides at-least-once delivery. The same event may arrive more than once with the same event_id, body, and signature headers.

Verify the signature and timestamp.
Match the header ID to the JSON event_id.
Atomically store the ID before side effects; return 200 for a known ID.

Use durable storage with a unique constraint for pilot workloads. An in-memory set loses state at restart.

08 / Troubleshooting

Common integration issues

Symptom	What to check
401 from Entrpy	Confirm the `X-API-Key` header and that your pilot key is enabled.
404 on query	Check the topic. A supported topic also returns 404 before its first observation.
422 on subscribe	Use a supported topic, paired condition fields, a finite threshold, and public HTTPS on port 443.
429 on test	Wait for the short per-key test cooldown.
502 on test	Check whether your receiver is public, reachable, certificate-valid, timely, and returning 2xx.
Bad signature	Use the secret for that subscription and verify the exact raw body before JSON parsing.
Stale timestamp	Synchronize your server clock; the example allows 300 seconds.
Repeated event	Expected with at-least-once delivery. Deduplicate by `event_id`.
No threshold event	Comparisons are strict, one-shot, and evaluated on newly observed values.

09 / Boundaries

Pilot limitations

Only the six listed crypto/USD topics are supported.
Prices are polled provider observations, not exchange tick data.
Thresholds support only strict, absolute > and < conditions and do not re-arm.
Delivery is at least once; receivers own idempotent processing.
No trading execution, dashboard, public delivery history, replay API, or self-service key management is provided.
Test throttling is process-local, and pilot interfaces may change.

10 / Support

Talk to the Entrpy team

If onboarding details, credentials, or delivery behavior are unclear, contact us through your pilot support channel. Include the affected event_id or subscription ID, but never send your API key or webhook secret in a support message.