Stability metrics

Overview

A stock’s compliance status can change at its next analysis, when the figures come from a newer filing or a share-price move has changed market cap, the denominator of the debt and cash ratios. The stability signal shows which holdings sit close enough to a limit for that to matter, so you know which ones to review before you rebalance. You can read it in two places:

On /compliance

A rating and the drivers behind it. Enough to flag a holding for review.

In the Evidence Packet

The same rating and drivers, plus the ratio closest to its limit and the distance to it.

The signal on `/compliance`

The /compliance response has a compact stability object: a rating and the drivers behind it. It is null while the determination is pending.

{
  "stability": {
    "rating": "stable",
    "drivers": [
      {
        "code": "COMFORTABLE_BUFFERS",
        "message": "All financial ratios are well within limits",
        "severity": "info"
      }
    ]
  }
}

Field	Values
`rating`	`stable`, `watch` or `borderline`.
`drivers[].code`	Machine-readable reason code, such as `RATIO_NEAR_THRESHOLD` or `COMFORTABLE_BUFFERS`.
`drivers[].message`	Human-readable explanation.
`drivers[].severity`	`info`, `warning` or `critical`.

Stability rating

The rating comes from how close each of the three ratios sits to its limit, and from signs that the figures behind a ratio could move:

`rating`	When
`stable`	Every ratio is comfortably inside its limit or, for a non-compliant stock, far past it, and no warning signal applies.
`watch`	A ratio is approaching its limit from either side, or one of these applies: an old filing, moderate confidence, estimated or broadly sourced interest income, a small market cap, a business-activity concern, or a non-compliant verdict that rests on the business-activity screen alone.
`borderline`	A ratio is very close to its limit or just past it, two or more ratios are approaching theirs, or confidence is low and a ratio is near its limit.

A rating has up to three drivers, each with the severity behind the rating: critical for borderline, warning for watch, info for stable.

The signal in the Evidence Packet

The Evidence Packet stability object repeats the rating and drivers as stability_rating and stability_drivers, and adds closest_threshold.

{
  "stability": {
    "closest_threshold": {
      "screen": "prohibited_revenue",
      "current_distance": 0.004
    },
    "stability_rating": "borderline",
    "stability_drivers": [
      {
        "code": "RATIO_NEAR_THRESHOLD",
        "message": "Prohibited revenue at 4.6%, very close to the 5% limit",
        "severity": "critical"
      }
    ]
  }
}

Closest threshold

closest_threshold is the passing ratio screen nearest its limit: debt_to_market_cap, cash_to_market_cap or prohibited_revenue. current_distance is the gap to the threshold as a decimal (0.004 is 0.4 percentage points). It is null when no ratio passes or none was measured.

Deprecated fields

The packet’s stability object has four deprecated fields with no data in them: quarters_compliant, quarters_total and flip_rate are always null, and closest_threshold.trend is always stable. They stay in the packet throughout /v1 and will be removed in the next major version. For how a stock’s status has changed across its filings, read GET /instruments/{symbol}/history.

Using stability in a portfolio

Read stability.rating from each /compliance response to triage a watchlist, then pull the Evidence Packet for any holding rated watch or borderline to see which ratio is closest to its limit, and by how much.

# 1. Check status and stability for a holding
curl https://api.halal.sh/v1/instruments/NVDA/compliance \
  -H "X-API-Key: hsh_sandbox_your_key"

# 2. For a holding rated watch or borderline, see the closest limit
curl https://api.halal.sh/v1/instruments/NVDA/evidence \
  -H "X-API-Key: hsh_sandbox_your_key"

The rating describes the latest analysis; it is not a forecast. A stable stock can still change status on a new filing or a large move in its share price.

Getting Started

Core Concepts

Guides

Overview

On /compliance

In the Evidence Packet

The signal on `/compliance`

Stability rating

The signal in the Evidence Packet

Closest threshold

Deprecated fields

Using stability in a portfolio

Overview

On /compliance

In the Evidence Packet

The signal on /compliance

Stability rating

The signal in the Evidence Packet

Closest threshold

Deprecated fields

Using stability in a portfolio

The signal on `/compliance`