Documentation

API reference, SDK guides, and integration patterns for connecting algo trading bots to Alfax challenges.

OpenAPI Specification Python SDK Quickstart ccxt / python-binance TradingView webhook Freqtrade Hummingbot HMAC-SHA256 Authentication Alfax Challenge Extensions

OpenAPI Specification

The complete Alfax API is documented in an OpenAPI 3.1 spec. All paths are byte-compatible with Binance Futures USDT-M.

View alfax-v1.yaml ↗

Python SDK Quickstart

Install the first-party alfax package from PyPI for a typed, ergonomic client with challenge-aware helpers.

PyPI: alfax ↗

pip install alfaxpython

pip install alfax

from alfax import Client

c = Client(
    api_key="YOUR_API_KEY",
    api_secret="YOUR_API_SECRET",
    base_url="https://api.alfax.trade",  # optional: defaults to api.alfax.trade
)

# Check challenge status
status = c.get_challenge_status()
print(status["currentEquity"], status["profitCurrent"])

# Place a market order
order = c.new_order(
    symbol="BTCUSDT",
    side="BUY",
    type="MARKET",
    quantity="0.001",
)

ccxt / python-binance

Any library that supports Binance Futures works with a single base_url (or urls.api) override. No code changes required.

ccxt drop-inpython

import ccxt

ex = ccxt.binanceusdm({
    "apiKey": "YOUR_KEY",
    "secret": "YOUR_SECRET",
    "urls": {
        "api": {
            "fapiPublic":    "https://api.alfax.trade/fapi",
            "fapiPrivate":   "https://api.alfax.trade/fapi",
            "fapiPrivateV2": "https://api.alfax.trade/fapi",
        }
    },
})

# Zero changes to your strategy needed
balance = ex.fetch_balance()
positions = ex.fetch_positions(["BTC/USDT:USDT"])

TradingView webhook

PineScript strategies and chart alerts can fire orders straight into a challenge — no bot process required. Each challenge issues its own webhook URL on the dashboard; the alert Message field is parsed as a single-line grammar.

Full grammar reference ↗

Alert Message templatespinescript

// TradingView Alert Message field — paste this template:
{{strategy.order.action}} {{strategy.order.contracts}} {{ticker}} {{strategy.order.alert_message}}

// In your Pine Script, embed the order-type detail in alert_message:
strategy.entry("L", strategy.long, qty=0.01,
    alert_message="LIMIT 67000 reduceOnly id=long_breakout")

// Manual alerts (no Pine) — write the grammar directly:
buy 0.001 BTCUSDT MARKET id=manual_test
sell 0.5 ETHUSDT LIMIT 3500 reduceOnly
sell 0.1 BTCUSDT TRAILING_STOP_MARKET 0.5
buy 0 BTCUSDT MARKET close   // close the position

Freqtrade

Freqtrade speaks ccxt under the hood — the ccxt_config.urls override is enough to point it at Alfax. Both ccxt_config and ccxt_async_config need the same urls block since Freqtrade runs sync REST + async data fetch in parallel.

Freqtrade futures docs ↗

user_data/config.jsonjson

{
  "trading_mode": "futures",
  "margin_mode": "isolated",
  "exchange": {
    "name": "binance",
    "key": "ALFAX_KEY",
    "secret": "ALFAX_SECRET",
    "ccxt_config": {
      "options": {"defaultType": "future"},
      "urls": {
        "api": {
          "fapiPublic":    "https://api.alfax.trade/fapi/v1",
          "fapiPublicV2":  "https://api.alfax.trade/fapi/v2",
          "fapiPrivate":   "https://api.alfax.trade/fapi/v1",
          "fapiPrivateV2": "https://api.alfax.trade/fapi/v2"
        }
      }
    },
    "ccxt_async_config": {
      "options": {"defaultType": "future"},
      "urls": {
        "api": {
          "fapiPublic":    "https://api.alfax.trade/fapi/v1",
          "fapiPublicV2":  "https://api.alfax.trade/fapi/v2",
          "fapiPrivate":   "https://api.alfax.trade/fapi/v1",
          "fapiPrivateV2": "https://api.alfax.trade/fapi/v2"
        }
      }
    },
    "pair_whitelist": ["BTC/USDT:USDT", "ETH/USDT:USDT"]
  }
}

Hummingbot

Hummingbot's binance_perpetual connector hardcodes its URLs as Python constants. Three working paths: (1) reverse-proxy fapi.binance.com → api.alfax.trade with a hosts-file rewrite, (2) fork the connector and patch the constants file (recommended), (3) run Hummingbot Gateway in ccxt-connector mode.

binance_perpetual_constants.py overridepython

# Patch Hummingbot's binance_perpetual connector to talk to Alfax.
# File: hummingbot/connector/derivative/binance_perpetual/binance_perpetual_constants.py

PERPETUAL_BASE_URL  = "https://api.alfax.trade"
TESTNET_BASE_URL    = "https://api.alfax.trade"
PERPETUAL_WS_URL    = "wss://api.alfax.trade/stream"
TESTNET_WS_URL      = "wss://api.alfax.trade/stream"

# Then in your Hummingbot config:
#   exchange: binance_perpetual
#   binance_perpetual_api_key:    ALFAX_KEY
#   binance_perpetual_secret_key: ALFAX_SECRET
#
# Alternatives (no fork): run a local nginx that maps fapi.binance.com →
# api.alfax.trade and patches /etc/hosts, or run Hummingbot Gateway in
# ccxt-connector mode with the same urls override.

HMAC-SHA256 Authentication

Private endpoints require an X-MBX-APIKEY header and a signature query parameter — identical to Binance Futures auth.

Manual signing (Python)python

import hashlib, hmac, time, urllib.parse

def sign(params: dict, secret: str) -> str:
    qs = urllib.parse.urlencode(params)
    return hmac.new(
        secret.encode(), qs.encode(), hashlib.sha256
    ).hexdigest()

params = {
    "symbol": "BTCUSDT",
    "timestamp": int(time.time() * 1000),
}
params["signature"] = sign(params, "YOUR_SECRET")

# Include X-MBX-APIKEY: YOUR_KEY header in every request

Alfax Challenge Extensions

Two non-Binance endpoints provide challenge-specific data: GET /fapi/v1/challenge and GET /fapi/v1/challenge/rules. The user-data WebSocket stream also emits challengeUpdate events.

Challenge status endpoint Challenge rules endpoint

The Alfax API is under active development. For questions, open an issue on the GitHub repository. Contract gaps or spec discrepancies should be flagged there, not worked around.