Skip to content

Settlement API

Settlement records for event contracts on official releases

Prediction markets list contracts that settle on one release of one official series: CPI above a strike, payrolls below a number, a central bank cutting or holding. The settlement endpoints return a single record for that release: the first-print value at the publisher's printed precision, the latest value and whether it was revised, the official source links, the release timing, the outcome for your strike, and an attestation you can verify.

GET only Ed25519 signed First-print settlement

A market's own rules always govern its settlement. Before relying on a template, check that the market names the same release, measure, seasonal adjustment and printed precision.

Endpoints

Base URL https://api.fxmacrodata.com/v1. Send your key in the X-API-Key header. Access follows the announcements endpoint: USD records are available without a key on a 15-minute delay, other currencies need a key, and the contract templates and verification keys are free.

EndpointReturns
/v1/settlement/contractsContract templates: contract_id, series, unit, publisher, outcome_type (threshold or decision), published_decimals and the question each template answers.
/v1/settlement/contracts/{contract_id}The settlement record for one template. Query: period (reference date YYYY-MM-DD or latest, the default), strike, comparison.
/v1/settlement/{currency}/{indicator}The settlement record for any announcement series. Query: period or announcement_id, strike, comparison, decimals (0 to 6; defaults to the matching template's precision).
/v1/settlement/keysThe Ed25519 public keys that verify signed records, with the canonicalisation rule.

comparison is one of above (the default), at_or_above, below, at_or_below or equal. The strike is compared with settlement_value, the first print rounded half up to the published precision, so a stored 0.2499 on a series printed to one decimal is judged as 0.2.

Settle a contract

List the templates, then settle one for a reference period and strike. The example asks whether US CPI inflation for September 2026 printed above 3.0%.

curl

curl "https://api.fxmacrodata.com/v1/settlement/contracts"

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.fxmacrodata.com/v1/settlement/contracts/usd_cpi_yoy?period=2026-09-30&strike=3.0&comparison=above"

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.fxmacrodata.com/v1/settlement/usd/non_farm_payrolls_change?period=latest&strike=100&comparison=at_or_above"

Python

import os
import requests

BASE = "https://api.fxmacrodata.com/v1"
headers = {"X-API-Key": os.environ["FXMACRODATA_API_KEY"]}

record = requests.get(
    f"{BASE}/settlement/contracts/usd_cpi_yoy",
    params={"period": "2026-09-30", "strike": 3.0, "comparison": "above"},
    headers=headers,
    timeout=30,
).json()

if record["status"] == "released":
    print(record["period"], record["settlement_value"], record["outcome"]["resolves_yes"])
else:
    print("Not settled yet:", record["status"])

The API is designed for server-side use. Keep your key out of browser code.

The settlement record

Every record has the same shape. Placeholders below describe each field's type.

{
  "schema": "fxmacrodata.settlement.v1",
  "currency": "USD",
  "indicator": "inflation",
  "contract_id": "usd_cpi_yoy",
  "generated_at": "<ISO 8601 UTC>",
  "status": "released | withheld | not_available",
  "announcement_id": "usd_inflation_<YYYY-MM-DD>",
  "period": "<YYYY-MM-DD>",
  "unit": "%YoY",
  "settles_on": "first_release",
  "settlement_value": <number>,
  "published_decimals": 1,
  "first_release": {
    "value": <number>,
    "source_url": "<official URL or null>",
    "source_url_scope": "release | dataset | series",
    "announcement_source_url": "<official URL or null>",
    "publication_time_status": "<string>",
    "source_artifact_sha256": "<hex or null>"
  },
  "latest": { "value": <number>, "revised": <boolean> },
  "timing": {
    "scheduled_at": "<ISO 8601 UTC or null>",
    "actual_release": {
      "published_after": "<ISO 8601 UTC or null>",
      "published_by": "<ISO 8601 UTC or null>",
      "basis": "<string or null>"
    },
    "ingested_at": "<ISO 8601 UTC>",
    "latency_ms": <number or null>,
    "latency_status": "measured | not_measured",
    "latency_reference": "actual_release_to_ingested_upper_bound"
  },
  "outcome": {
    "type": "threshold",
    "strike": 3.0,
    "comparison": "above",
    "value_used": <number>,
    "resolves_yes": <boolean>
  },
  "attestation": {
    "canonicalization": "json-sorted-keys-compact-utf8",
    "payload_sha256": "<hex>",
    "algorithm": "ed25519",
    "key_id": "fxmd-settle-<hex>",
    "signature_base64": "<base64>"
  }
}
statusMeaning
releasedThe release is in the record. settlement_value is the first print at the published precision; latest shows the current value and whether it has since been revised.
withheldThe release has been published, but a request without a key reads USD on a 15-minute delay. The record carries a freemium_delay object with the cutoff and when the release becomes readable. A key removes the delay.
not_availableNo release exists for that period yet, or the series has no value for it.

Decision contracts

Central-bank decision templates (outcome_type decision, for example usd_fed_decision) report the move without a strike: outcome.decision is hike, hold or cut, with change_bps and previous_value. Where the central bank sets a range, the outcome also carries target_range with lower and upper bounds; for the Federal Reserve the settled value is the upper bound of the federal funds target range. Pass a strike to evaluate the decision value as a threshold instead.

Release timing: four numbers

Each record reports the timing of its release as exactly four numbers. Latency is measured from the actual release, the moment the publisher really posted the figure, not from the scheduled time.

1. Scheduled timing.scheduled_at

The publisher's announced release time.

2. Actual release actual_release.published_after / published_by

The window in which the publisher posted the figure: our last read still showing the old figure, and our first read showing the new one.

3. Ingested timing.ingested_at

When the figure was committed to the FXMacroData store and became available to the API.

4. Latency timing.latency_ms

Ingested minus the actual release, measured from published_after, so it is an upper bound.

When the actual release window was not captured for a release, latency_ms is null and latency_status is not_measured. Report latency for that release as not measured; the record never substitutes a delay measured from the scheduled time.

Verify a signed record

The attestation covers the record without its attestation field, serialised as UTF-8 JSON with keys sorted and no whitespace. payload_sha256 is the SHA-256 of those bytes. When the record is signed, signature_base64 is an Ed25519 signature over the same bytes, made with the key named by key_id; fetch the public keys from /v1/settlement/keys and pin the one you trust. When no signing key is published, records carry the canonical hash only and signature_base64 is null.

Python, with the cryptography package

import base64
import hashlib
import json

import requests
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey

BASE = "https://api.fxmacrodata.com/v1"


def canonical_bytes(record: dict) -> bytes:
    body = {k: v for k, v in record.items() if k != "attestation"}
    return json.dumps(
        body, sort_keys=True, separators=(",", ":"), ensure_ascii=False
    ).encode("utf-8")


def verify(record: dict, keys: dict) -> bool:
    attestation = record["attestation"]
    payload = canonical_bytes(record)
    if hashlib.sha256(payload).hexdigest() != attestation["payload_sha256"]:
        return False
    if not attestation.get("signature_base64"):
        return False  # hash-only record: nothing to verify against a key
    public_key = Ed25519PublicKey.from_public_bytes(
        base64.b64decode(keys[attestation["key_id"]])
    )
    try:
        public_key.verify(base64.b64decode(attestation["signature_base64"]), payload)
    except Exception:
        return False
    return True


key_list = requests.get(f"{BASE}/settlement/keys", timeout=30).json()["data"]
keys = {item["key_id"]: item["public_key_base64"] for item in key_list}
record = requests.get(
    f"{BASE}/settlement/contracts/usd_cpi_yoy",
    params={"period": "2026-09-30"},
    headers={"X-API-Key": "YOUR_API_KEY"},
    timeout=30,
).json()
print(verify(record, keys))

Verify the record exactly as received. Python's json module re-serialises parsed numbers to the same bytes; in other languages, make sure numbers are written the way Python writes them (for example 3.0, not 3) before hashing.

From an AI agent

The FXMacroData MCP server exposes the same records through the event_contract_settlement tool. Call it with no arguments to list the templates, with contract_id and period to settle a template, or with currency and indicator for any series. The record is returned unchanged, so its signature still verifies.

AI Answer-Ready

Key Facts

Page
Settlement
Section
Documentation
Canonical URL
https://fxmacrodata.com/documentation/settlement
Source
FXMacroData editorial and official publisher references
Last Updated
See page metadata

Provenance And Trust

Cite the canonical URL and source field above. Where available, this page maps to official publisher releases and timestamped updates.

Quick Q&A

What is this page about? This page explains Settlement with directly usable context for trading, research, and API workflows.

What source should be cited? Use the canonical URL and the listed source field; cite official publisher references when available.

How fresh is this content? The last updated value above reflects the page metadata or latest available data timestamp.

Can this be used in AI assistants? Yes. This section is intentionally structured for retrieval and citation in chat assistants.

Prompt Packs

Use these in ChatGPT, Claude, Gemini, Mistral, Perplexity, or Grok for consistent source-aware outputs.