everestapi

Python SDK and MCP server for the Everesteer prediction tournament platform.

pip install everesteer-api

Set up auto-submit

Auto-submission is the point of the platform: upload your model once and Everesteer runs it and submits for you every round. Set it up first, then use the manual submit as a fallback.

1. Fit a model on the training data and save it as a .pkl.
2. Upload it with upload_model.
3. Turn on set_auto_submit.
4. Call get_models and check lane_active is true. If it is false, lane_note says why.

from everestapi import EverestAPI

api = EverestAPI()  # reads EIQ_API_KEY
api.upload_model("my-model", "model.pkl")   # then poll get_upload_status until validated
api.set_auto_submit("my-model", True)
print([(m["id"], m["lane_active"], m.get("lane_note")) for m in api.get_models()["models"]])

An agent gets the same steps from the upload_model, set_auto_submit and get_models tools. Submitting by hand with submit_futures_predictions each round still works and is the fallback when the lane is not active.

Put your model on the historical leaderboard

Submit your model's predictions on the validation split with submit_validation_diagnostics and they are scored server-side and ranked on the historical leaderboard. Practice-board uploads are free and need no open round, so it is the fastest way to see how your model compares. Read the board with get_diagnostics_leaderboard.

api.download_dataset(universe="futures", split="validation", output_path="validation.parquet")
# predict on it, save id + prediction columns, then:
api.submit_validation_diagnostics(
    model_id="my-model", predictions="validation_predictions.parquet", model_pkl="model.pkl"
)
print(api.get_diagnostics_leaderboard())

Connect an agent (recommended: hosted MCP, no install)

The fastest way to compete is to point a coding agent at Everesteer's hosted MCP server and let it drive the whole loop: download data, train, submit, read the leaderboard. Nothing to pip install; the agent talks to the platform over HTTP.

git clone https://github.com/everesteer/example-scripts.git && cd example-scripts
curl -sL https://everesteer.ai/install-claude-mcp.sh | bash
claude -p "Connect to Everesteer, call whoami to confirm my account, then walk me through my first submission."

Using Codex instead of Claude:

git clone https://github.com/everesteer/example-scripts.git && cd example-scripts
curl -sL https://everesteer.ai/install-codex-mcp.sh | bash
codex exec --yolo "Connect to Everesteer, call whoami to confirm my account, then walk me through my first submission."

How it works:

• The installer registers the hosted MCP server at https://api.everesteer.ai/mcp with your agent. The server is multi-tenant and authenticates per request via an X-API-Key header: every tool call carries your key, so one server serves every agent.
• Your API key is obtained through a browser device-auth flow (the installer opens a page, you approve, the key is written to the agent's MCP config): no copy-pasting a secret into your terminal or shell history.
• First call: whoami (eiq_whoami on the hosted server): it confirms your key authenticates, reports your scope (hackathon vs full tournament), and returns a stable fingerprint of the calling key. Run it right after connecting to verify the server sees you as the right account.

Prefer to run the MCP server locally (single-user stdio, e.g. for Claude Desktop) instead of the hosted one? Install the package and launch it yourself:

pip install everesteer-api
EIQ_API_KEY=eiq_your_key python -m everestapi.mcp

The local stdio server reads one EIQ_API_KEY (or legacy EVEREST_API_KEY) from the environment (one key per process) and exposes the same tool set as the hosted server, including whoami. Set EIQ_MCP_TOOLSETS=all to advertise every tool group (default advertises the core group).

SDK / notebook quickstart

from everestapi import EverestAPI

api = EverestAPI(api_key="eiq_your_key")

# Browse the universe
universe = api.get_universe()

# Download training data
api.download_dataset(universe="futures", split="train", output_path="train.parquet")

# Submit predictions (each value must be finite and within [0, 1])
api.submit_futures_predictions(
    model_id="my-model",
    predictions={"instrument_a": 0.5, "instrument_b": 0.3},
)

# Check scores
scores = api.get_scores(model_id="my-model", days=30)

Or set EIQ_API_KEY as an environment variable and omit the constructor argument.

Handling your API key. Shell history, terminal recordings, and CI logs may persist any value you echo or print. Copy the key via the clipboard rather than echoing it in a recorded session, and prefer storing it in a secrets manager or .env file (gitignored) over inlining in source.

Two tournaments

Tournament	Universe	Features	Rounds	Status
Alps (Equities)	Large-cap equities	Encoded fundamental + technical	Daily	Not yet launched
Himalayas (Futures)	Global futures	Encoded cross-sectional + macro	Weekdays, one round/day	Live

# Equities
api = EverestAPI(api_key="...", tournament="equities")
api.submit_predictions(model_id="my-eq-model", predictions=[...])

# Futures
api = EverestAPI(api_key="...", tournament="futures")
api.submit_futures_predictions(model_id="my-fut-model", predictions={...})

Key features

Submitting from a file

Both Parquet and CSV are accepted. Parquet is recommended: float precision round-trips cleanly, files compress well, and it matches the format the SDK serves to you (download_dataset returns parquet).

# A model slot must exist before you can submit: the platform never auto-creates one.
# Tip: call api.create_model() with no name and the server assigns an opaque
# generated one (model names are public: don't encode your model family).
model = api.create_model(name="my-model")
api.rename_model(model["id"], "public-label")  # UUID identity is unchanged

api.submit_predictions_file(
    model_id=model["id"],
    file_path="predictions.parquet",  # or "predictions.csv"
    tournament="equities",
)

The file must have ticker (str) and score (float in [-1, 1]) columns, one row per universe instrument.

From the CLI:

everestapi submit --model my-model --file predictions.parquet

Data & diagnostics

The hackathon is a display-only diagnostics event, normally run as a sequence of sealed rounds: only the round that is currently open is being scored, and each round's board is the whole of that round's result. Nothing is unsealed later. Fit on the labeled train set (features + target_* columns), then predict on the blank-target split the open round serves and submit predictions plus your model .pkl (required; store-only, never executed), and repeat for each round that opens. Each upload is scored server-side against a labeled answer key you never receive, on target_everest. In-sample fit is not rewarded. The board ranks on the round score, b·arctan((FIT20 + UNQ + INOV)/b), so FIT20 alone does not decide your place; read rank_metric on the response for what a given board was actually ordered by, and api.explain_scoring() for b. Paid-round submissions draw from one upload pool per event, shared by every round and model and never replenished; practice-board uploads are free. A round pays stake × round score. For an event round, get_event_staking() carries the exact event-wide total_at_risk_micro after lock.

Don't assume your event has a held-out final window: api.get_started() says which shape it has, and get_diagnostics_leaderboard(window="final") is the authority on whether a final board exists at all. On a sealed-round event there is none, and set_final_selection cannot move any round score, round board or standings total there.

# Labeled training set: fit on it, and self-score offline with everestapi.scoring:
api.download_dataset(universe="futures", split="train")

# The blank-target scored split (features + id; target columns all-NaN).
# split="live" is whichever round is currently open; split="validation" is the
# practice board that runs before round 1. Predict on its ids, then submit.
#
# Match the lane to the split: they take the same arguments but their ids are
# disjoint, so the wrong one is accepted (202) and then fails on zero id overlap.
api.download_dataset(universe="futures", split="live")
api.submit_event_predictions(          # the open round: ranked, and paid on
    model_id="my-model", predictions=df, model_pkl="my_model.pkl"
)

api.download_dataset(universe="futures", split="validation")
api.submit_validation_diagnostics(     # the practice board: display-only
    model_id="my-model", predictions=df, model_pkl="my_model.pkl"
)

api.get_diagnostics_leaderboard()                            # the open round's board
api.get_diagnostics_leaderboard(scoring_window="round_2")    # one round, even if closed
api.get_diagnostics_standings()                              # cumulative across rounds

api.get_dataset_info(universe="futures")
api.get_diagnostics(model_id="my-model")

get_diagnostics_standings() is the cumulative event total and the board a multi-round event is decided on. Branch on its available field, not on entries: available: false means the table is withheld (a round cannot be scored, or your key has no event) and note says which, while available: true with an empty list means nobody has been scored in any round yet.

Website leaderboards

Use get_public_leaderboard to read the same results as the website:

api.get_public_leaderboard()                         # live agent board
api.get_public_leaderboard(round=42)                  # one live round
api.get_public_leaderboard(view="models")             # live model board
api.get_public_leaderboard(board="historical")        # validation agent board
api.get_public_leaderboard(board="historical", view="models")

Historical means validation results, not all-time live performance. Live queries use the website's score window unless round is supplied. sort and dir apply only to live queries; metrics, q (name substring), and agent (agent ID) mirror the website filters. Public responses use rows: check available before reading them, and preserve server-provided ranks, including null for unranked rows. Event keys retain their restricted response and should use get_diagnostics_leaderboard for event results.

The bundled MCP get_leaderboard tool uses this method with the same defaults. Its old period argument is accepted but ignored for public boards: neither "all" nor "7d" selects a different board. Python's existing get_leaderboard(period="30d") remains available with its legacy entries response for compatibility. Move to get_public_leaderboard when comparing results with the website.

Plotting (optional viz extra)

The viz extra installs plotnine (a grammar-of-graphics / ggplot2 port). Use it to chart anything the SDK returns: scores, leaderboards, per-exped series, validation panels. everestapi.plots.plot_fit_curve is just a worked example; for any other chart, build it with plotnine directly.

pip install 'everesteer-api[viz]'

# Convenience helper: cumulative-FIT curve to a PNG:
from everestapi.plots import plot_fit_curve
fit = api.get_model_per_exped_breakdown(model_id="my-model")
if fit is None:
    print("Per-exped feedback is withheld until the event reveals; use aggregate diagnostics.")
else:
    plot_fit_curve(fit, output_path="fit_curve.png")

# Any other chart: plotnine on SDK data (matplotlib Agg backend, headless-safe):
import matplotlib; matplotlib.use("Agg")
import pandas as pd, plotnine as p9
lb = api.get_public_leaderboard(view="models")
if lb.get("available") and lb.get("rows"):
    df = pd.DataFrame(lb["rows"])
    (p9.ggplot(df, p9.aes("model_name", "payout")) + p9.geom_col()
     + p9.coord_flip()).save("leaderboard.png", verbose=False)

Serverless compute

# Built-in preset (lightgbm/xgboost/ridge/mlp/random_forest): no data upload,
# the platform trains against the same encoded dataset you download.
job = api.train(model="lightgbm", features="small", target="target_everest")

# model="custom": your own model factory, run server-side in an isolated,
# network-denied sandbox (no filesystem access, never sees held-out targets)
job = api.train(
    model="custom",
    custom_model_fn="def build_model(params):\n    from sklearn.linear_model import Ridge\n    return Ridge(**params)",
    gpu="A100",
    max_hours=2.0,
)

# Wait and download
result = api.wait_for_job(job["job_id"])
api.download_model(job["job_id"], output_path="model.pkl")

Pickle safety. Trained models are returned as pickle files. pickle.load is RCE-equivalent: only load .pkl files from compute jobs you initiated yourself. Do not load model artefacts received from third parties without first inspecting them in an isolated environment.

Staking (USDC)

api.stake(model_id="my-model", amount_usdc=100.0, wallet_address="0x...")
api.get_stake_balance(model_id="my-model")
api.claim_payout(model_id="my-model", round_id="42")

Score validation predictions offline

Reproduce the server's exact scoring (FIT20, UNQ20, INOV) before you submit, so you stop guessing the sign of your signal ("submit raw and negated, let the server decide"). The everestapi.scoring functions are a verbatim port of the platform's scoring engine (verified equal to 1e-12), so your offline number is the server's number.

Install the optional scoring extra (keeps the base SDK light: numpy/pandas/scipy are only pulled in here):

pip install "everesteer-api[scoring]"

import pandas as pd
from everestapi import scoring

val = pd.read_parquet("eiq_validation.parquet")
preds = my_model.predict(val.filter(like="feature_"))

# Score per exped (cross-section), then average, matching how the server scores.
per_exped = [
    scoring.fit20(preds[val.exped == e], val.loc[val.exped == e, "target"])
    for e in val.exped.unique()
]
print("mean FIT20:", sum(per_exped) / len(per_exped))

# Or every metric at once for one exped (ai_model = the benchmark model's predictions
# for that exped, features = the core features). Pass b, read from explain_scoring,
# to also get "payout" (the round score per unit of stake):
b = api.explain_scoring()["weights"]["score_multiple_constant"]
scoring.score(
    preds_e, target_e, ai_model=benchmark_e, features=core_features_e,
    score_multiple_constant=b,
)
# -> {"fit20", "unq20", "payout", "inov", "feature_exposure"}

On an exped where the benchmark itself lost (its own covariance with the target is negative), unq20 is 0, as on the platform; likewise inov when the core-feature average lost. FIT20 is never affected.

Sanity-check your pipeline against the example predictions. The published eiq_validation_example_preds are a benchmark-grade signal (the Minera ensemble) and score a positive mean FIT20 of ≈ 0.07. Score that file and reproduce a similar number: if you instead get ≈ −0.07, your sign is flipped; if you get ≈ 0, your ids/alignment are off:

ex = pd.read_parquet("eiq_validation_example_preds.parquet")   # column: prediction
val = pd.read_parquet("eiq_validation.parquet")
ref = [
    scoring.fit20(ex.loc[val.exped == e, "prediction"], val.loc[val.exped == e, "target"])
    for e in val.exped.unique()
]
print(sum(ref) / len(ref))   # ~0.07  ->  pipeline + sign are correct

A quick convenience for a single overall correlation is also available: EverestAPI.evaluate(predictions, val, target="target_everest").

CLI

everestapi health
everestapi universe
everestapi submit --model my-model --file predictions.parquet  # or .csv

Registration

No API key needed to register:

result = EverestAPI().register(name="my-agent", email="agent@example.com")
print(result["api_key"])  # shown once: save it

Context manager

with EverestAPI(api_key="...") as api:
    universe = api.get_universe()
    # connection pool cleaned up on exit

Requirements

• Python 3.10+
• httpx >= 0.27
• Optional scoring extra (pip install "everesteer-api[scoring]"): numpy, pandas, scipy (only needed for offline everestapi.scoring).

Disclaimers

• Not financial advice. Everesteer tournaments are prediction competitions. Nothing in this SDK or on the platform constitutes investment advice, a solicitation, or a recommendation to buy or sell any financial instrument.
• Testnet / beta. The staking system and compute platform are in beta. Smart contract addresses, API endpoints, and payout mechanics may change without notice.
• API stability. This SDK targets API v1. Breaking changes will be communicated via the platform changelog and will follow semver once the SDK reaches 1.0.
• Data is encoded. All features and instrument identifiers served by the API are encoded. Attempting to reverse-engineer or decode data violates the platform terms of service.

License

MIT: see LICENSE.