---
title: "Public signed safe-to-trade receipt (free, rate-limited)"
method: GET
path: "/v1/safe-to-trade/sample"
tags: ["Market State"]
---

# Public signed safe-to-trade receipt (free, rate-limited)

`GET /v1/safe-to-trade/sample`

## Request

- Base URL: `https://headlessoracle.com`
- URL: `https://headlessoracle.com/v1/safe-to-trade/sample`
- Auth: none declared

Public-discovery door for the safe-to-trade circuit-breaker receipt. Returns a byte-identical signed receipt to the paid /v1/safe-to-trade (same Ed25519 key, same 60-second TTL, same Tier-0 override merge, same GAP-012 cross-venue scan, same fail-closed reason taxonomy, receipt_mode=live). No authentication; rate-limited to 60 req/min/IP. max_age is REQUIRED with no default — the IETF environment.* freshness-discipline contract is modeled at this surface. Canonical field list is /v5/keys → canonical_payload_spec.safe_to_trade_fields. Use the unsigned wrapper fields (door, note, discovery_url) to navigate; they sit OUTSIDE the signed payload.

## Query parameters

- `venue` string
- `max_age` integer, required
- `instrument` string

## Response `200`

Signed safe-to-trade receipt

- object
  - `cross_venue` string, required: JSON-stringified { realtime_overrides: string[], scan_ok: boolean }. Strings-only invariant for signPayload.
  - `expires_at` string, date-time, required
  - `instrument` string, required
  - `issued_at` string, date-time, required
  - `issuer` 'headlessoracle.com', required
  - `max_age` string, required: Integer 1–60 encoded as string for the strings-only canonical payload.
  - `public_key_id` string, required
  - `reasons` string, required: JSON-stringified string[] of fail-closed reason codes.
  - `receipt_id` string, uuid, required
  - `receipt_mode` 'live', required: 'live' — receipt attests provenance-of-content, not provenance-of-payment. The free door does not change the data.
  - `safe` 'true' | 'false', required
  - `schema_version` 'v5.0', required
  - `venue` string, required
  - `venue_source` 'SCHEDULE' | 'OVERRIDE' | 'SYSTEM', required
  - `venue_status` 'OPEN' | 'CLOSED' | 'HALTED' | 'UNKNOWN', required
  - `signature` string, required: Ed25519 over the alphabetically-sorted strings-only canonical payload.
  - `receipt` object, required: Mirror of the signed fields + signature. The same bytes that ship at the top level. Convenient for verifiers that want a single contained object.
  - `discovery_url` string, uri, required
  - `door` 'public-sample', required: Unsigned wrapper field — names the door, not the data.
  - `note` string, required: Unsigned wrapper field — human-readable hint pointing at the canonical spec and the verification path.

## Other responses

- `400`: UNKNOWN_VENUE / MAX_AGE_REQUIRED / MAX_AGE_INVALID / INSTRUMENT_TOO_LONG
- `429`: RATE_LIMITED — 60 req/min/IP cap reached. Retry-After header indicates seconds until the next minute bucket opens.
- `500`: Signing system offline — CRITICAL_FAILURE (UNKNOWN/SYSTEM/safe=false, unsigned)

---

[API](https://skmtc.dev/headlessoracle/apis/headless-oracle.md) · [All operations](https://skmtc.dev/headlessoracle/apis/headless-oracle/llms.txt) · [OpenAPI document](https://skmtc.dev/headlessoracle/apis/headless-oracle/revisions/4e82fe332f29?raw)