Time-series forecasting through one API.

Idempotency-Key: forecast-2026-08-26-001

{
  "forecasts": [
    {
      "quantiles": {
        "0.1": [103.8, 104.1, 104.5],
        "0.5": [105.2, 105.7, 106.1],
        "0.9": [106.9, 107.4, 108.0]
      }
    }
  ],
  "meta": {
    "gateway_request_id": "req_01J...",
    "request_id": "model_01J...",
    "models_used": ["chronos2"],
    "model_revisions": { "chronos2": "3f9c1e0a..." },
    "billing": {
      "settled_mc": "12",
      "balance_mc": "4988"
    }
  }
}

forecasts has one entry per input series, in request order. Univariate entries return flat horizon arrays; multivariate entries return nested arrays. Quantile keys are decimal strings such as 0.5. meta.model_revisions names the exact weights (Hugging Face commit) each model served, so a forecast can be tied to a model revision, not just an API version.

{
  "mcpServers": {
    "ephemeris": {
      "url": "https://ephemeris-staging.cascade.industries/api/mcp",
      "headers": {
        "Authorization": "Bearer pc_live_your_key"
      }
    }
  }
}

{
  "mcpServers": {
    "ephemeris": {
      "url": "https://ephemeris-staging.cascade.industries/api/mcp",
      "headers": {
        "Authorization": "Bearer pc_live_your_key"
      }
    }
  }
}

claude mcp add --transport http ephemeris \
  https://ephemeris-staging.cascade.industries/api/mcp \
  --header "Authorization: Bearer pc_live_your_key"

{
  "servers": {
    "ephemeris": {
      "type": "http",
      "url": "https://ephemeris-staging.cascade.industries/api/mcp",
      "headers": {
        "Authorization": "Bearer pc_live_your_key"
      }
    }
  }
}

[mcp_servers.ephemeris]
url = "https://ephemeris-staging.cascade.industries/api/mcp"
bearer_token_env_var = "EPHEMERIS_API_KEY"

{
  "mcpServers": {
    "ephemeris": {
      "httpUrl": "https://ephemeris-staging.cascade.industries/api/mcp",
      "headers": {
        "Authorization": "Bearer pc_live_your_key"
      }
    }
  }
}

{
  "mcpServers": {
    "ephemeris": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://ephemeris-staging.cascade.industries/api/mcp",
        "--header", "Authorization: Bearer pc_live_your_key"
      ]
    }
  }
}

"tools": [{
  "type": "mcp",
  "server_label": "ephemeris",
  "server_url": "https://ephemeris-staging.cascade.industries/api/mcp",
  "headers": { "Authorization": "Bearer pc_live_your_key" }
}]

"mcp_servers": [{
  "type": "url",
  "url": "https://ephemeris-staging.cascade.industries/api/mcp",
  "name": "ephemeris",
  "authorization_token": "pc_live_your_key"
}]

URL:     https://ephemeris-staging.cascade.industries/api/mcp
Header:  Authorization: Bearer pc_live_your_key

Stateless: no session id, no SSE stream to keep open.
Stdio-only clients: npx mcp-remote <url> --header "Authorization: Bearer <key>"

The transport is stateless Streamable HTTP; there is no session to keep alive. Every forecast result includes settled_mc and balance_mc so the agent, and you, can see what each call cost. A missing or revoked key returns 401; an empty balance returns a tool error carrying a top-up link the agent can hand back to you. OAuth sign-in for one-click connectors is planned; today every client needs a key.

Discover models and their prices

Browse model capabilities and the public pricing page. Agents with an API key can retrieve the JSON catalog below. Use the returned model name exactly, and check its capabilities, price_per_kslot_mc, and billing_context_cap. Without an API key, the unsigned x402 request gives the authoritative price for that request.

curl https://ephemeris-staging.cascade.industries/api/v1/models \
  --header "Authorization: Bearer $EPHEMERIS_API_KEY"

Get a quote before paying

Send a forecast with mode: explicit and an active model. Routing and ensembles are not supported by x402. The example returns HTTP 402 with a JSON challenge and a base64 PAYMENT-REQUIREDheader. This request does not make a payment or run a forecast.

curl --include --request POST \
  --url https://ephemeris-staging.cascade.industries/api/v1/x402/forecast \
  --header "Content-Type: application/json" \
  --data '{
    "mode": "explicit",
    "model": "chronos2",
    "series": [{"values": [100.2, 101.4, 99.8, 103.1, 104.6, 102.2], "freq": "H"}],
    "context_len": 256,
    "horizon": 16,
    "quantiles": [0.1, 0.5, 0.9]
  }'

Let your wallet client pay and receive the forecast

1. Use an x402 v2 client, such as Coinbase Agentic Wallet tooling. Fund the buyer wallet with USDC on the network in the challenge.
2. Inspect accepts: check network, asset, payTo, and amount against your spending policy. USDC has six decimals: an amount of 1000 is 0.001 USDC.
3. Sign the offered requirements, preserving all extra fields including ephemerisQuote. Retry the same URL and unchanged JSON body with the base64 PAYMENT-SIGNATURE header. A compatible client handles this exchange automatically.
4. HTTP 200 returns the forecast and a base64 PAYMENT-RESPONSE settlement receipt. Decode that receipt to record the transaction, payer, and network alongside the forecast.

Follow the official Coinbase buyer quickstart for wallet client setup, then use this POST endpoint and request body. Buyer wallet credentials stay in your agent environment; never send private keys or CDP secrets to Ephemeris.

Pay directly through MCP

Connect to /api/mcp/x402 over Streamable HTTP without an Authorization header. This server exposes free list_modelsdiscovery and a paid forecast tool. Use an x402 v2 MCP client with a funded wallet; a regular MCP client alone cannot sign a payment. Forecast arguments require mode: explicitand a model returned by discovery.

1. Call forecast without payment. The result has isError: true and the same payment challenge in structuredContent and content[0].text; no forecast runs.
2. Select one offered network, inspect the price and payee, and sign with your wallet. Preserve all accepted requirements, including extra.ephemerisQuote.
3. Repeat the unchanged tool arguments with the payment at params._meta["x402/payment"]. The successful result contains the forecast and a settlement receipt at _meta["x402/payment-response"].
4. Keep the signed tool call for retries. An identical completed retry returns the stored result and receipt without another charge. A quote belongs to its REST or MCP entry point; obtain a new unpaid quote when switching transports.

Follow Coinbase's MCP payment guide for the wire format. Wallet keys stay with the buyer. This endpoint has no account balance or credit-pack purchase tools.

Price, expiry, and safe retries

The same model cost formula below applies. One mc costs 0.000001 USDC; 3000 mc costs 0.003 USDC. Credit-pack bonuses do not apply. Quotes last ten minutes and requests above 100 USDC are rejected. A challenge can offer multiple configured networks: Base, Polygon, Arbitrum or World on mainnet, and Base Sepolia or World Sepolia for testing. Choose one entry from accepts that your wallet supports and holds USDC on. Only networks enabled on this deployment and available from the facilitator are offered. A payment on one network does not move funds across chains. Solana is not supported by this EVM payment integration.

If your wallet SDK has no default token for World, explicitly allow the verified USDC contract from the challenge with a per-payment spending cap. Keep your network, token and payee allowlists enabled.

After submitting a signed payment, retain that exact signed request. A completed retry returns the saved forecast and receipt without another charge. HTTP 409 means the payment is processing, conflicts, or needs reconciliation: do not create a second payment. On a timeout or HTTP 503, retry the same signed request. If unresolved, contact support with the payer address and receipt, if available. A signed request cannot be reused for a different forecast.

Before signing, HTTP 400 means the request or price is invalid, and HTTP 402 supplies a quote or rejects a payment authorization. HTTP 429 means rate limited. HTTP 502 means forecast or settlement failure; read the returned error before attempting another payment. HTTP 503 can also mean x402 is disabled on that deployment.

Each model is priced per series, per 1,024 context points, and per 64 forecast steps.

Slots × horizon × quantiles must not exceed 120,000 output values. Requests without explicit quantiles are budgeted as 21 quantiles. API-key forecasts use a token bucket of 10 requests per minute with a burst of 20. Calls waiting longer than 30 seconds return 429 with guidance on when to retry.