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.
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.
| Endpoint | Returns |
|---|---|
| /v1/settlement/contracts | Contract 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/keys | The 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>"
}
}
| status | Meaning |
|---|---|
| released | The 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. |
| withheld | The 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_available | No 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.
The publisher's announced release time.
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.
When the figure was committed to the FXMacroData store and became available to the API.
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.