API documentation

Quickstart for agents

1. Inspect the metadata

   Check /v1/status and /v1/meta first. A live feed alone does not mean paid access is enabled: require public_beta and payments.ready from metadata. Before launch, Cloudflare Access may also require owner or service-token access; an Access login page is not an x402 response.

2. Set your payment limits

   Use a dedicated local payer with USDC on the exact advertised Solana network. Obtain the expected payment recipient independently, then allow only that recipient, USDC mint, network and a fixed per-call maximum. These examples explicitly authorize mainnet risk calls up to $0.01; for the board use its advertised price with a consciously raised cap. Devnet uses different USDC and network identifiers.

3. Choose a client and keep the receipt

   Use the official x402 2.25.0 client for the selected scheme: Solana exact or Base EIP-3009 exact authorization. Base signing needs no token approval or SPL Memo. Pin the network, USDC contract, recipient and maximum total before signing. Never choose an offered network automatically just because it appears first. The examples below explicitly target Solana; Base customers use the SDK's EVM signer and the Base option advertised by the service.

   The Python imports and version were checked against the official x402 2.25.0 wheel and client source. The TypeScript package versions and interfaces could not be verified in the offline reference bundle: the example is a review starting point, not a tested version pin. Validate compatible official packages, pin them and retain the lockfile before funding a client. Do not assume their version equals the Python version.

   The SDK signs locally. HodlOdds never receives your private key. The facilitator supplies the transaction fee payer. Store payment receipts; do not log signed payment payloads or automatically retry after an ambiguous result. The examples use each library's payment client; they do not construct the x402 payment protocol themselves.

curl -i https://api.hodlodds.com/v1/status
curl -s https://api.hodlodds.com/v1/meta
curl -i 'https://api.hodlodds.com/v1/risk/REPLACE_WITH_MINT'
# A fresh covered mint returns 402 only after the public beta is enabled.
curl -i 'https://api.hodlodds.com/v1/board?sort=safest&limit=10&min_liquidity_sol=50'

# Python >=3.10; save as quickstart.py.
# python -m pip install 'x402[httpx,svm]==2.25.0'
# Set KEYPAIR_FILE, EXPECTED_PAY_TO and TOKEN_MINT in your environment.
# KEYPAIR_FILE is your local solana-keygen JSON file (64-byte array).
import asyncio, base64, json, os
from pathlib import Path
from x402 import x402Client
from x402.http.clients.httpx import x402HttpxClient
from x402.mechanisms.svm.constants import (
    SOLANA_MAINNET_CAIP2, USDC_MAINNET_ADDRESS,
)
from x402.mechanisms.svm.signers import KeypairSigner
from x402.mechanisms.svm.exact.register import register_exact_svm_client

NETWORK = SOLANA_MAINNET_CAIP2
PAY_TO = os.environ["EXPECTED_PAY_TO"]  # Confirm independently with HodlOdds.
MAX_ATOMIC = 10_000  # $0.01 USDC, six decimals; board totals are 5_000 per delivered coin.

def approve(version, offers):
    if version != 2:
        return []
    return [r for r in offers if r.scheme == "exact"
            and r.network == NETWORK and r.asset == USDC_MAINNET_ADDRESS
            and r.pay_to == PAY_TO and 0 < int(r.amount) <= MAX_ATOMIC
            and (r.extra or {}).get("paymentFlow") == "authorization"]

async def main():
    key_bytes = bytes(json.loads(Path(os.environ["KEYPAIR_FILE"]).read_text()))
    if len(key_bytes) != 64:
        raise ValueError("Expected a 64-byte solana-keygen keypair file")
    signer = KeypairSigner.from_bytes(key_bytes)
    client = x402Client()
    register_exact_svm_client(client, signer, networks=[NETWORK], policies=[approve])
    async with x402HttpxClient(client, timeout=30, follow_redirects=False) as http:
        # Each call can pay once: no outer retry loop on timeouts or errors.
        response = await http.get("https://api.hodlodds.com/v1/risk/" +
                                  os.environ["TOKEN_MINT"])
        receipt = response.headers.get("PAYMENT-RESPONSE")
        if receipt:
            result = json.loads(base64.b64decode(receipt, validate=True))
            print("Settlement:", result.get("success"), result.get("transaction"))
        print("HTTP", response.status_code)
        response.raise_for_status()
        answer = response.json()
        print(answer["row"]["p_crash_60m"], answer["expires_at"])

asyncio.run(main())

// Official TypeScript-library example; validate against your locked packages.
// Choose and verify compatible versions, then pin them with --save-exact:
// npm install --save-exact @x402/core@<verified-version> \
//   @x402/fetch@<verified-version> @x402/svm@<verified-version> \
//   @solana/kit@<compatible-version>
// Set KEYPAIR_FILE, EXPECTED_PAY_TO and TOKEN_MINT. Use Node with TS support
// or your project's TypeScript runner. Never commit the keypair file.
import { readFile } from "node:fs/promises";
import { x402Client } from "@x402/core/client";
import { wrapFetchWithPayment } from "@x402/fetch";
import { ExactSvmScheme } from "@x402/svm/exact/client";
import { createKeyPairSignerFromBytes } from "@solana/kit";

function required(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Missing ${name}`);
  return value;
}
const network = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
const asset = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
const payTo = required("EXPECTED_PAY_TO"); // Confirm independently.
const raw = JSON.parse(await readFile(required("KEYPAIR_FILE"), "utf8"));
if (!Array.isArray(raw) || raw.length !== 64 ||
    !raw.every(x => Number.isInteger(x) && x >= 0 && x <= 255)) {
  throw new Error("Expected a 64-byte solana-keygen keypair file");
}
const signer = await createKeyPairSignerFromBytes(new Uint8Array(raw));
const client = new x402Client().register(network, new ExactSvmScheme(signer));
client.registerPolicy((version, offers) => version !== 2 ? [] : offers.filter(r =>
  r.scheme === "exact" && r.network === network && r.asset === asset &&
  r.payTo === payTo && BigInt(r.amount) > 0n && BigInt(r.amount) <= 10_000n &&
  r.extra?.paymentFlow === "authorization"));
const paidFetch = wrapFetchWithPayment(fetch, client);
// No outer retries: reconcile a timeout or ambiguous receipt before paying again.
const response = await paidFetch("https://api.hodlodds.com/v1/risk/" +
  encodeURIComponent(required("TOKEN_MINT")), { redirect: "error" });
const receipt = response.headers.get("PAYMENT-RESPONSE");
if (receipt) {
  const result = JSON.parse(Buffer.from(receipt, "base64").toString("utf8"));
  console.log("Settlement:", result.success, result.transaction);
}
console.log("HTTP", response.status);
if (!response.ok) throw new Error("Reconcile the response before retrying");
console.log(await response.json());

Machine-readable contract: OpenAPI 3.1. Agent overview: llms.txt. Response examples in the contract are explicitly illustrative data. The forecast ends at horizon_end, not 60 minutes after your request.

These clients request fresh answers only and never fall back automatically. To opt in to last-known odds, explicitly request /v1/risk/{mint}/last and set the payment cap to its advertised price (default 2_000 USDC atomic units). Inspect stale, age_s and horizon_remaining_s before using the response.

How to read a score

HodlOdds estimates whether a completed one-minute close in SOL will be at least 90% below the reference close within the displayed 60-minute forecast window. It does not measure every kind of loss or whether a token can be sold.

The independent trading system operated by the publisher may trade these tokens. It receives no customer searches, API purchases or order flow. Payment does not change a score.

Freshness

1. Minute closesCompleted one-minute bars
2. Scored ~20 s laterComputation and publication can delay availability
3. Until the next updateRefresh once per minute

Scores are recomputed every 60 seconds, about 20 seconds after each minute closes, from completed one-minute bars up to as_of. Each score covers the 60 minutes after its as_of time and is valid only until the next update; the odds for the same token can rise sharply from one minute to the next. Scoring starts around :20; computation and publication can delay availability. For decisions, refresh immediately before acting and once per minute for continuous monitoring, checking as_of for a new minute. The API freshness cutoff is separate: by default, data becomes stale more than 120 seconds after issued_at or after expires_at. A new request does not restart the forecast window.

Historical confidence

Confidence describes how closely historical predictions in this probability range matched what happened, and how much evidence backs that. It is not a guarantee for this token.

Historical validation of weekly BF refits, September 1 through October 14, 2026 excluding September 20; already-seen data, not measured calibration of the frozen serving fit.

The additive confidence field uses rule hodlodds.confidence.v1. It never changes the probability, rank, alert threshold or feed freshness. A confidence level is an ordinal presentation label, not a statistical confidence interval or a claim that a token can be sold.

Let error be the absolute difference between observed incidence and mean prediction, and let tol = max(0.02, 0.25 × pred). Relative error is error / pred; when pred is zero it is zero only if observed is also zero, otherwise infinite. Approximate positives are n × observed.

• High: at least 100 positive landmarks, error ≤ tol/2 and relative error ≤25%.
• Medium: otherwise, at least 20 positive landmarks, error ≤ tol and relative error ≤50%.
• Low: otherwise, including missing or invalid evidence.

The relative limits prevent a small absolute error from hiding an incidence rate much larger than predicted. Direction says historically under-predicted or over-predicted only when error > tol/2 or relative error >25%.

Tokens younger than 120 minutes, or with unknown age, cannot receive high confidence. The historical bands include young tokens, but do not validate age-specific calibration or complete feature history. Non-SOL rows always receive experimental, with no SOL validation statistics attached.

All counts below are landmarks, which can repeat the same mint or crash. Approximate positives are not independent incidents. Per-band distinct-mint counts and confidence intervals are unavailable. The levels below assume a known age of at least 120 minutes.

This is the frozen reference evidence table, also available with its source hash and rule in /v1/meta. New response rows carry their own publisher-supplied evidence. Old snapshots without the additive field remain valid and have no inferred confidence level. On the separate last-known route, stale data applies the one-level downgrade described below; the original evidence and probability stay unchanged.

Coverage

Coverage is limited to supported, active SOL-quoted pump.fun graduates. Non-SOL pairs are experimental rankings: mid-range scores historically underpredicted incidence. Their scores are returned free with HTTP 404, never sold as probabilities.

Endpoints

Routes and prices

Payment and failure behavior

1. Send an unpaid request
2. Read the 402 challengePAYMENT-REQUIRED
3. Sign locallyPin the network, USDC asset, recipient and maximum total.
4. Retry with the signed paymentPAYMENT-SIGNATURE → 200 + PAYMENT-RESPONSE

x402 v2 uses PAYMENT-REQUIRED, PAYMENT-SIGNATURE and PAYMENT-RESPONSE. Read /v1/meta and the current challenge for accepted payment networks, recipients and native USDC assets. When enabled, Solana and Base are alternative ways to pay the same price for the same covered SOL-token answer. Payment chain never expands model coverage. Solana devnet and Base Sepolia use test funds; they are not mainnet.

A connection failure after settlement may leave the answer undelivered. Keep the transaction signature and reconcile before paying again. Never share a wallet seed phrase with this service.

Request limit: 60 requests per minute per IP by default, including unpaid probes. Do not cache last-known odds as current odds.

Status codes

How we charge

The normal risk and board routes remain fresh or free: only fresh, covered SOL answers settle. The separate opt-in last-known route may charge for a clearly labelled stored SOL answer no older than 30 minutes. Each route checks its age and coverage limits before payment work and again before settlement. Unknown, uncovered and experimental non-SOL answers are free refusals. Filters that return no rows are also free.

Risk and last-known have fixed per-answer prices; a board costs $0.005 per delivered coin, charged as one exact total. No subscription. Read current prices in /v1/meta and approve the exact x402 requirement. An already delivered signature is rejected with 409. A reconciled undelivered payment has one explicit redeem as described below. A lost connection after settlement can leave an answer undelivered: reconcile the receipt before signing again.

Redeem an undelivered answer

If an authorized call fails, keep its original PAYMENT-SIGNATURE private and check your wallet before signing another payment. The server checks uncertain settlements on-chain in the background. A receipt saying success: false with no transaction usually means nothing was charged; if your wallet shows payment, try redemption after about two minutes. Confirmation can take longer.

The Python SDK keeps the recovery credential in HodlOddsError.payment, excluded from its printed and JSON receipt fields. Explicitly call client.redeem(payment). The CLI saves an ambiguous attempt to a private 0600 file under ~/.config/hodlodds/pending/ and prints its path; run hodlodds redeem <file>. Neither automatically retries or signs again. Never log, upload or share that file or the signed header.

A manual redeem resends the identical header to the same route; boards require the same normalized query and original priced count. Add HodlOdds-Redeem: 1 to require recovery only, so an unknown payment cannot initiate settlement. Pending verification returns free 409 with Retry-After. A final unpaid result returns free 409 saying “this payment never settled; request a new offer”.

When a payment is confirmed on-chain and was not delivered, it can be redeemed once within 24 hours of its original verification. The response is the current eligible answer and includes HodlOdds-Redeemed: <transaction>, with no second settlement. Current route freshness and coverage rules still apply. A stale/uncovered answer or board with fewer matches than the original priced count is refused free and leaves the redeem available until expiry. Already redeemed or expired payments return 409. A lost redeem response cannot be delivered again.

Reference