API Documentation – StackSats

Authentication

All API requests require a Bearer token in the Authorization header. API keys are available with an active API & Business subscription.

Header

Authorization: Bearer sk_live_xxx

Keep your API key secret. Never expose it in client-side code, public repositories, or shared documents. Rotate compromised keys immediately from your dashboard.

Orders

GET/api/v1/orders

The current broker-verified managed shortlist shown in the PWA Orders tab. Ranking combines frozen setup quality with current fillability. No order size, broker ID or account data is exposed.

Response

{
  "status": "ok",
  "data": {
    "contract_version": "client_managed_orders_v1",
    "status": { "state": "FRESH", "verified_at": "2026-08-26T16:20:05Z" },
    "items": [{
      "asset": "SOL", "action": "ACCUMULATION",
      "price_eur": 78.771, "current_price_eur": 82.184,
      "customer_priority": 1, "top_quality_order": true
    }]
  }
}

Positions

GET/api/v1/positions

Current StackSats-managed positions from the authenticated broker snapshot, including average entry, live price, open return, portfolio allocation and the next managed action. Quantities and portfolio value stay private.

Response

{
  "status": "ok",
  "data": {
    "contract_version": "client_managed_positions_v1",
    "items": [{
      "asset": "DOGE", "direction": "LONG",
      "average_entry_eur": 0.08913, "current_price_eur": 0.08968,
      "unrealized_return_pct": 0.62, "data_live": true
    }]
  }
}

Results

GET/api/v1/results

Exact managed Long Term outcomes from the same proven cohort as PWA Results. Manual activity, retired strategies and Trade/Swing history do not enter this contract.

Parameter	Type		Description
limit	integer	optional	Maximum outcomes. Default: 100, max: 200

Response

{
  "status": "ok",
  "data": {
    "contract_version": "client_managed_results_v1",
    "summary": { "closed_outcomes": 22, "win_rate_pct": 100.0, "average_net_return_pct": 5.36 },
    "items": [{ "symbol": "DOGE", "net_return_pct": 3.72, "entry_price": 0.08913, "exit_price": 0.09245 }]
  }
}

Signals

GET /api/v1/signals

Returns trade and spot signals across symbols and timeframes. Filter by type, symbol, status, and date range. Includes signal score, direction, confidence, and risk/reward metrics.

Parameter	Type		Description
type	string	optional	Filter: trade, spot, all. Default: all
symbol	string	optional	Trading pair, e.g. BTCUSDT, ETHUSDT
status	string	optional	Filter: open, closed, all. Default: all
page	integer	optional	Pagination. Default: 1
per_page	integer	optional	Results per page. Default: 25, max: 100
from	string	optional	ISO 8601 start timestamp
to	string	optional	ISO 8601 end timestamp

Response

{
  "status": "ok",
  "data": [
    {
      "id": "sig_abc123",
      "symbol": "BTCUSDT",
      "type": "trade",
      "direction": "LONG",
      "score": 72,
      "confidence": 0.78,
      "risk_reward": 3.2,
      "status": "open",
      "created_at": "2026-03-26T14:30:00Z"
    }
  ],
  "meta": {
    "timestamp": "2026-03-29T10:15:00Z",
    "version": "1.0"
  }
}

Forecasts

GET /api/v1/forecasts

AI directional forecasts with probability scores and price targets. Forecasts incorporate changes over time, not only current state. Filter by symbol and date range.

Parameter	Type		Description
symbol	string	optional	Trading pair, e.g. BTCUSDT
page	integer	optional	Pagination. Default: 1
per_page	integer	optional	Results per page. Default: 20, max: 100
from	string	optional	ISO 8601 start timestamp
to	string	optional	ISO 8601 end timestamp

Response

{
  "status": "ok",
  "data": [
    {
      "id": "fc_xyz789",
      "symbol": "BTCUSDT",
      "direction": "UP",
      "probability": 0.68,
      "current_price": 67453,
      "targets": {
        "short_term": 69200,
        "medium_term": 71500,
        "long_term": 75000
      },
      "created_at": "2026-03-26T14:30:00Z"
    }
  ],
  "meta": {
    "timestamp": "2026-03-29T10:15:00Z",
    "version": "1.0"
  }
}

Market Regime

GET /api/v1/regime

Current market regime classification per symbol and timeframe. Determined by AI pipeline using on-chain, derivatives, and macro data.

Parameter	Type		Description
symbol	string	required	Trading pair, e.g. BTCUSDT
timeframe	string	optional	15m, 1h, 4h, 1d, 1w. Default: 4h

Response

{
  "status": "ok",
  "data": {
    "symbol": "BTCUSDT",
    "timeframe": "4h",
    "regime": "TRENDING_BULL",
    "confidence": 0.76
  },
  "meta": {
    "timestamp": "2026-03-29T10:15:00Z",
    "version": "1.0"
  }
}

Market Data

GET /api/v1/market

Market overview including Fear & Greed Index, BTC dominance, funding rates, open interest, liquidations, and DXY. Real-time snapshot of macro indicators.

Response

{
  "status": "ok",
  "data": {
    "fear_greed": {
      "value": 9,
      "label": "Extreme Fear"
    },
    "btc_dominance": 56.13,
    "funding_rate_btc": 0.002497,
    "open_interest_btc": "$49B",
    "dxy": 120.28
  },
  "meta": {
    "timestamp": "2026-03-29T10:15:00Z",
    "version": "1.0"
  }
}

Candles

GET /api/v1/candles

Historical OHLCV data since 2017. Required parameters: symbol and timeframe. Supports pagination via limit and date range filtering.

Parameter	Type		Description
symbol	string	required	Trading pair, e.g. BTCUSDT
timeframe	string	required	1m, 5m, 15m, 1h, 4h, 1d, 1w
from	string	optional	ISO 8601 start timestamp
to	string	optional	ISO 8601 end timestamp
limit	integer	optional	Max results. Default: 100, max: 1000

Response

{
  "status": "ok",
  "data": [
    {
      "timestamp": "2026-03-26T16:00:00Z",
      "open": 67200,
      "high": 68100,
      "low": 67050,
      "close": 67890,
      "volume": 1850.5
    }
  ],
  "meta": {
    "timestamp": "2026-03-29T10:15:00Z",
    "version": "1.0"
  }
}

Indicators

GET /api/v1/indicators

Technical indicators including RSI, MACD, Bollinger Bands, EMA, ATR, and more. Required parameters: symbol and timeframe.

Parameter	Type		Description
symbol	string	required	Trading pair, e.g. BTCUSDT
timeframe	string	required	15m, 1h, 4h, 1d, 1w

Response

{
  "status": "ok",
  "data": {
    "symbol": "BTCUSDT",
    "timeframe": "4h",
    "rsi": 35.27,
    "ema": {
      "9": 66808,
      "21": 67453,
      "50": 68672,
      "200": 69615
    },
    "macd": {
      "value": -1850,
      "signal": -1620,
      "histogram": -230
    },
    "atr": 920
  },
  "meta": {
    "timestamp": "2026-03-29T10:15:00Z",
    "version": "1.0"
  }
}

Account

GET /api/v1/account

API key usage statistics and account information. No parameters required.

Response

{
  "status": "ok",
  "data": {
    "plan": "API & Business",
    "requests_today": 3247,
    "requests_limit": 10000,
    "reset_at": "2026-03-30T00:00:00Z"
  },
  "meta": {
    "timestamp": "2026-03-29T10:15:00Z",
    "version": "1.0"
  }
}

Webhooks

Configure webhook endpoints in your dashboard to receive real-time event notifications. Each delivery is signed with HMAC-SHA256 via the X-StackSats-Signature header for verification.

Event Types

The following events are available for webhook subscriptions:

Event	Description
signal.trade	New trade signal generated
signal.spot	New spot signal generated
forecast	New forecast published

Webhook Signature

Verify webhook authenticity using HMAC-SHA256. The signature is sent in the X-StackSats-Signature header and is computed over the request body using your API secret.

Example Payload

{
  "event": "signal.trade",
  "data": {
    "id": "sig_abc123",
    "symbol": "BTCUSDT",
    "direction": "LONG",
    "score": 72,
    "entry_price": 67453
  },
  "timestamp": "2026-03-29T10:15:00Z"
}

Rate Limits

Rate limits are per API key and depend on your subscription tier. Exceeding limits returns HTTP 429 with a Retry-After header.

Plan	Requests / day	Requests / minute
API & Business	10,000	60
Enterprise	100,000	300

Rate Limit Headers

Every response includes rate limit information in headers:

Headers

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9847
X-RateLimit-Reset: 1711497600

Error Codes

The API uses standard HTTP status codes. Error responses include a JSON body with details.

400Bad RequestInvalid parameters or missing required fields

401UnauthorizedMissing or invalid Bearer token

403ForbiddenValid token but insufficient plan permissions

404Not FoundUnknown endpoint or invalid symbol

429Rate LimitedToo many requests. Check Retry-After header

500Server ErrorInternal error. Contact support if persistent

Error Response

{
  "status": "error",
  "code": 401,
  "message": "Invalid or expired API key",
  "meta": {
    "timestamp": "2026-03-29T10:15:00Z",
    "version": "1.0"
  }
}

Build with StackSats.

Authentication

Orders

Positions

Results

Rate Limits

Rate Limit Headers

Error Codes