Signals API

GET /api/variants/{variant_id}/signal/export

Resolve a variant by slug with curl and jq

# Set KEY and VARIANT_SLUG to your API key and chosen variant slug.
# A slug is stable; numeric IDs must come from the live response.
SLUG=haa
DETAIL=$(curl --fail --silent --show-error \
  -H "X-API-Key: $KEY" \
  "https://bestfolio.app/api/strategies/slug/$SLUG") || exit 1
VARIANT_ID=$(printf '%s' "$DETAIL" | jq -er --arg slug "$VARIANT_SLUG" '
  [.variants[] | select(.slug == $slug and .active == true)]
  | if length == 1 then .[0].id else error("Choose one active variant slug") end
') || exit 1

JSON, inspect the live recent history

# After resolving VARIANT_ID above:
curl --fail --silent --show-error -H "X-API-Key: $KEY" \
  "https://bestfolio.app/api/variants/$VARIANT_ID/signal/export?format=json&limit=6"

CSV, for a spreadsheet

# After resolving VARIANT_ID above:
curl --fail --silent --show-error -H "X-API-Key: $KEY" \
  "https://bestfolio.app/api/variants/$VARIANT_ID/signal/export?format=csv&limit=24"

Python, resolve the variant before reading signals

import os
import requests

BASE = "https://bestfolio.app"
headers = {"X-API-Key": os.environ["BESTFOLIO_API_KEY"]}
slug = os.environ["BESTFOLIO_STRATEGY_SLUG"]
variant_slug = os.environ["BESTFOLIO_VARIANT_SLUG"]

def read_json(path, **params):
    response = requests.get(BASE + path, headers=headers, params=params, timeout=30)
    response.raise_for_status()
    return response.json()

detail = read_json(f"/api/strategies/slug/{slug}")
matches = [v for v in detail["variants"]
           if v["slug"] == variant_slug and v["active"] is True]
if len(matches) == 1:
    variant = matches[0]
else:
    raise SystemExit("Choose exactly one active variant slug")

history = read_json(f"/api/variants/{variant['id']}/signal/export",
                    format="json", limit=6)
# Strategy detail supplies the stable signal ID; the export omits it.
signal = variant.get("latest_signal")
print(signal)  # Inspect the live response; apply every safety check below.

Python, fail closed on signal and data checks

from datetime import date, datetime, timedelta, timezone

def checked_signal(variant, status_payload, approved_version, expected_cutoff):
    # expected_cutoff comes from your reviewed strategy calendar, not the
    # newest row returned by the API. A monthly cutoff need not be yesterday.
    try:
        now = datetime.now(timezone.utc)
        today = now.date()
        verified = datetime.fromisoformat(status_payload["generated_at"].replace("Z", "+00:00"))
        if not timedelta(0) <= now - verified <= timedelta(minutes=10):
            return None
        if not approved_version or status_payload["methodology_version"] != approved_version:
            return None
        signal = variant["latest_signal"]
        if variant["active"] is not True or signal["status"] != "current":
            return None
        if date.fromisoformat(signal["as_of_date"]) != today:
            return None
        period = signal["period"]
        cutoff = date.fromisoformat(period["data_cutoff"])
        if cutoff != expected_cutoff or cutoff > today:
            return None  # Stale, unexpected or future data: do nothing.
        if period["provisional"] is not False:
            return None
        if not date.fromisoformat(period["holding_start"]) <= today <= date.fromisoformat(period["holding_end"]):
            return None
        if type(signal["id"]) is not int or signal["id"] <= 0:
            return None
        return signal
    except (KeyError, TypeError, ValueError, AttributeError):
        return None  # Missing or malformed fields: do nothing.

# Pin this value only after reviewing the methodology and corrections.
# Do not automatically approve the version the status endpoint returns.
status_payload = read_json("/api/system/status-public")
safe = checked_signal(variant, status_payload,
                      os.environ["REVIEWED_METHODOLOGY_VERSION"],
                      date.fromisoformat(os.environ["EXPECTED_DATA_CUTOFF"]))
if safe is None:
    raise SystemExit("No workflow action: safety checks did not pass")

Your workflow, reconcile and require human approval

# Pseudocode: these adapters belong to your own workflow, not BestFolio.
# Any adapter failure stops the workflow. This example submits no orders.
def prepare_reviewed_workflow(signal, proposed_orders, max_order_size):
    signal_id = signal["id"]
    if already_processed(signal_id):
        return None
    if reconcile_actual_positions_and_open_orders() is not True:
        return None
    if not proposed_orders or not valid_positive_cap(max_order_size):
        return None
    if not all(finite_order_size_within_cap(order, max_order_size)
               for order in proposed_orders):
        return None
    if human_approved(signal_id, proposed_orders) is not True:
        return None
    # Recheck freshness and positions if approval took time or inputs changed.
    if inputs_still_match_review(signal, proposed_orders) is not True:
        return None
    # Atomic durable claim, shared by workers, scoped to this workflow/account.
    # Keep uncertain outcomes claimed until a human reconciles them.
    if claim_signal_once(signal_id) is not True:
        return None
    return proposed_orders  # Reviewed handoff only; no broker call here.