Black Tier Circle

Public API v1

Versioned, key-authenticated REST API for reseller integrations. Breaking changes go to /api/v2/ only.

1. Authentication

Send the raw API key on every request. Keys look like btc_live_ or btc_test_ plus 32 hex characters. Raw keys are shown once at creation.

X-API-Key: btc_test_0123456789abcdef0123456789abcdef

2. Rate limits

Default: 60/minute
Reads: 120/minute
Order create: 10/minute
Payment verify: 20/minute

429 responses include a Retry-After header.

3. Idempotency

POST /api/v1/orders requires X-Idempotency-Key. The same key plus the same productId returns the original order.

4. Error format

{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "…" } }

5. Endpoints

GET/api/v1/products

Scope: products:read

Response

{ "success": true, "data": [{ "id": "…", "sku": "EBOOK-001", "retailPrice": "12.000000" }], "meta": { "page": 1, "limit": 20, "total": 1, "hasMore": false } }

GET/api/v1/orders

Scope: orders:read

Response

{ "success": true, "data": [{ "orderId": "…", "status": { "payment": "awaiting" } }], "meta": { "page": 1, "limit": 20, "total": 1, "hasMore": false } }

POST/api/v1/orders

Scope: orders:write

Request

{ "productId": "uuid", "customerRef": "your-customer-id", "quantity": 1 }

Response

{ "success": true, "data": { "orderId": "…", "paymentOptions": { "bep20": { "walletAddress": "0x…" } } } }

GET/api/v1/orders/{orderId}

Scope: orders:read

Response

{ "success": true, "data": { "orderId": "…", "customerRef": "…", "paymentClaim": null } }

POST/api/v1/orders/{orderId}/pay/binance

Scope: payments:write

Response

{ "success": true, "data": { "prepayId": "…", "checkoutUrl": "…", "isDemoMode": true } }

POST/api/v1/orders/{orderId}/pay/binance/verify

Scope: payments:write

Request

{ "binanceOrderId": "PAY_123" }

Response

{ "success": true, "data": { "verified": true, "message": "Payment verified" } }

POST/api/v1/orders/{orderId}/pay/bep20

Scope: payments:write

Request

{ "txHash": "0x" + 64 hex chars }

Response

{ "success": true, "data": { "verified": true, "message": "Payment verified" } }

GET/api/v1/wallet

Scope: orders:read

Response

{ "success": true, "data": { "balanceTotal": "20.000000", "balanceReserved": "0.000000", "balanceAvailable": "20.000000" } }

GET | POST | DELETE/api/v1/webhooks

Scope: webhook:manage

Request

POST { "url": "https://example.com/hook", "events": ["order.fulfilled"] }
DELETE { "webhookId": "uuid" }

Response

{ "success": true, "data": { "webhookId": "…", "secret": "shown-once" } }

6. Webhooks

We POST JSON to your HTTPS URL with header X-BTC-Signature set to HMAC-SHA256 (hex) of the raw body using the webhook secret. Verify with a timing-safe compare.

{ "event": "order.payment_verified", "timestamp": "2026-09-21T00:00:00.000Z", "data": { "orderId": "…", "tenantId": "…" } }

Events: order.payment_verified, order.fulfilled, order.delivered, order.failed, order.cancelled, order.paid, reseller.activated

7. SDKs

Official SDKs coming soon. Use any HTTP client with the headers above.