Authentication
All API requests require a Bearer token in the Authorization header. Your API key is available in your dashboard after subscribing to the API & Business plan.
Header
Authorization: Bearer sk_live_your_api_key_here
Keep your API key secret. Do not expose it in client-side code, public repositories, or shared documents. If you believe your key has been compromised, rotate it immediately from your dashboard.
Signals
GET
/v1/signals/{symbol}
Returns signal scores, regime context, confidence levels, and risk/reward ratios for a given trading pair. Scores are calculated across multiple timeframes by the AI decision pipeline.
| Parameter | Type | Description | |
|---|---|---|---|
| symbol | string | required | Trading pair, e.g. BTCUSDT, ETHUSDT |
| timeframe | string | optional | Filter by timeframe: 15m, 1h, 4h, 1d, 1w. Default: all |
Response
{
"symbol": "BTCUSDT",
"timestamp": "2026-03-26T14:30:00Z",
"regime": "TRENDING_BULL",
"signals": {
"4h": {
"score": 67,
"direction": "LONG",
"confidence": 0.73,
"risk_reward": 3.2,
"indicators": {
"rsi": 58.4,
"macd_signal": "BULLISH",
"volume_trend": "INCREASING"
}
}
}
}
Response fields
| score | integer | Signal strength 0–100. Higher = stronger conviction | |
| direction | string | LONG, SHORT, or NEUTRAL | |
| confidence | float | Model confidence 0.0–1.0 | |
| risk_reward | float | Calculated risk/reward ratio |
Market Regime
GET
/v1/regime/current
Returns the current market regime classification with confidence score and macro context. The regime is determined by the AI pipeline using on-chain, derivatives, and macro data.
Response
{
"regime": "TRENDING_BULL",
"confidence": 0.73,
"fgi": 62,
"macro_risk": "LOW",
"fed_rate": 4.25,
"dxy_trend": "WEAKENING",
"updated_at": "2026-03-26T14:30:00Z"
}
Regime types
| TRENDING_BULL | Strong uptrend with bullish momentum | ||
| TRENDING_BEAR | Strong downtrend with bearish momentum | ||
| RANGING | Sideways consolidation, no clear direction | ||
| VOLATILE | High volatility, rapid regime changes | ||
| ACCUMULATION | Low volatility with signs of smart money accumulation | ||
Forecast
GET
/v1/forecast/{symbol}
Returns the AI directional forecast with probability scores and price targets across multiple timeframes. Forecasts incorporate changes over time, not only the current state.
| Parameter | Type | Description | |
|---|---|---|---|
| symbol | string | required | Trading pair, e.g. BTCUSDT |
Response
{
"symbol": "BTCUSDT",
"direction": "UP",
"probability": 0.67,
"current_price": 87241,
"targets": {
"4h": { "low": 86200, "mid": 87800, "high": 89100 },
"1d": { "low": 85500, "mid": 89500, "high": 92800 },
"1w": { "low": 82000, "mid": 93200, "high": 101500 }
},
"generated_at": "2026-03-26T14:30:00Z"
}
Live Trades
GET
/v1/trades/live
Returns StackSats' own live trading positions — every entry and exit with full transparency. This is our actual trade feed, not simulated data. Includes actionable price data and context.
| Parameter | Type | Description | |
|---|---|---|---|
| status | string | optional | Filter: open, closed, all. Default: open |
| limit | integer | optional | Number of results. Default: 20, max: 100 |
Response
{
"positions": [
{
"id": "t_28a3f9",
"action": "STRIKING: BTC",
"symbol": "BTCUSDT",
"side": "LONG",
"entry_price": 87241,
"current_price": 87890,
"pnl_pct": 0.74,
"confidence": 0.73,
"risk_reward": 3.2,
"opened_at": "2026-03-26T09:15:00Z",
"status": "OPEN"
}
],
"total": 1
}
Rate Limits
API rate limits depend on your subscription tier. Exceeding the limit returns a 429 status code with a Retry-After header.
| Plan | Requests / day | Requests / minute | Webhooks |
|---|---|---|---|
| API & Business | 10,000 | 60 | Included |
| Enterprise | 100,000 | 300 | Included + priority |
Rate limit headers are included in every response:
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 a message field.
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
{
"error": true,
"code": 401,
"message": "Invalid or expired API key"
}