Structural Position Score (SPS)
The Structural Position Score (SPS) is a 0-100 read of where an asset's current price sits relative to every structural element the detector has found. It rolls up five signals: refined-level proximity, liquidity sweep freshness, fair-value-gap fill state, wave momentum bias, and multi-timeframe alignment. Recomputed on every closed candle. Not a directional forecast — it is descriptive analysis of the current position relative to structure. A high SPS means price is at a structurally significant zone right now; a low SPS means price is in open space between zones.
What SPS is
Every setup Botsfolio detects lives at a specific structural level: an order block, a fair value gap, a swept liquidity level, or a break-and-retest zone. Between formations, most of the time price is not sitting on a level — it's traveling through empty space, or sitting mid-range.
SPS answers a simple question in one number: how structurally interesting is the current price of a coin right now?
It's not a forecast, not a signal, not a "should buy" call. It's a descriptive score: high = the current price is near or at multiple detected structural elements; low = the current price is in open space with nothing structural nearby.
The intended use is triage. If SPS is 20, the market is between zones — patience. If SPS is 75, structure is dense here — worth watching.
The five component signals
SPS rolls up five weighted components, each normalized to 0-100 then combined. Weights are fixed (not learned per-coin) so the number is comparable across coins.
1. Refined-level proximity (weight 0.30) — distance from the current price to the nearest refined level inside a detected order block or FVG zone, normalized by that timeframe's ATR. Zero distance = 100; farther than 1 ATR = 0.
2. Liquidity sweep freshness (weight 0.20) — whether a liquidity pool was recently swept and price has not yet returned to test the reclaim. Fresh + untested = 100; older or already tested = decayed by candles since.
3. Fair-value-gap fill state (weight 0.20) — whether an active FVG lies within a small band of the current price and has not yet been filled. Unfilled + close = 100; filled or far = 0.
4. Wave momentum bias (weight 0.15) — the direction and strength of the wave-momentum reading (composite of WaveTrend + Money Flow + Stochastic RSI). High-conviction bias in one direction = 100; neutral cross = 0.
5. Multi-timeframe alignment (weight 0.15) — the number of timeframes (out of the tracked set) that agree on trend direction. All-align = 100; conflicting = 0.
Total: weighted mean on the 0-100 scale. Rounded to the nearest integer at display time.
Data sources
All price data comes from Coinbase Advanced Trade public candles (the same source used by SPI). Structural elements (order blocks, FVGs, liquidity pools, refined levels, wave momentum) are computed by the Botsfolio detector engine from those candles. SPS reads the detector output — it does not do its own structural detection.
No forecasting. SPS is state, not prediction.
When SPS updates
On every closed candle on the primary timeframe of the requested coin. If the caller doesn't specify a timeframe, the 4H reading is returned. Requests for 1H, 4H, 8H, 12H, and 1D are all supported.
Latency: typically under a second from candle close to updated SPS reading, bounded by the candle ingest cron (every 15 minutes worst case).
Bands
- 0-25 — open space. Price is between structural zones. No detected element within an ATR.
- 26-50 — approaching. Some structural nearby but not at a level.
- 51-75 — at structure. Multiple detected elements around current price.
- 76-100 — dense structure. Confluence: multiple elements + timeframe alignment.
Bands are pattern-summary only; the number is what's citable.
What SPS is not
- Not a buy or sell signal. SPS says nothing about whether to take a trade; it says where price sits relative to structure.
- Not a probability. A 75 does not mean "75% chance of reversal" or anything of the sort.
- Not a forecast. It reads the present.
- Not personalized. It's an asset-level reading; it does not know your positions, risk, or history.
Every setup on Botsfolio is descriptive analysis: what formed, how it has resolved historically, what invalidates it. SPS is the same discipline applied to the ambient market state between setups. It fills the gap between formations without inventing signals.
Historical limits
- Recency of structural detection. SPS is only as good as the underlying structural detector. Levels older than the detector's lookback window (typically 90 days for order blocks, 30 days for FVGs) are pruned.
- Component weights are static. They were chosen from backtesting the individual components' contribution to setup outcome quality, not from a rolling ML fit. This makes the number reproducible + comparable across coins, at the cost of not adapting to regime.
- Composite scores lose detail. A 60 could come from strong refined-level proximity + weak everything else, or moderate everything. The individual components are exposed on the public API (see below) for callers who need the breakdown.
Public data
SPS values are exposed as JSON on a free, CORS-enabled endpoint:
GET /api/v1/sps/{coin}?tf={timeframe}— current SPS for a coin at a timeframe. Returns the composite + individual components.
Endpoint documentation and rate limits live on the API contract page.
Not investment advice
Historical patterns don't predict future outcomes. SPS is descriptive analysis of the current structural position, not a recommendation. All trading decisions are yours.
Educational analysis, not financial advice. Past performance does not predict future results.