Get started
What Foreshock is, for an integrator
One API over heterogeneous stablecoin freeze mechanisms, one change feed against your own address book, and one fail-closed gate in front of your credit path.
You are here because something upstream of your ledger can be frozen, and you would rather find out before you credit a user than after. This section is written for the engineer wiring that path.
The three questions the API answers
Exposure. Which of your own addresses currently relate to an enforcement event, how, and how severely. GET /v1/exposure returns matches against the address book you registered, newest first by cursor order.
Screening. What authoritative lists say about a single address, and what third-party vendors said, each answer carrying a reference to the immutable snapshot of the raw upstream response behind it. POST /v1/screen/address.
Decision. Whether one inbound deposit may be credited, held, or rejected, written to an append-only decision record with an evidence reference. POST /v1/decide/deposit.
Only the third produces a binding verdict. Screening reports on an address; it does not decide anything.
What you send, and what comes back
You send references, not identities. Your address book is registered once; every subsequent answer refers to an entry in it through an opaque customer_address_ref that only your account can resolve. Deposits are described by deposit_ref, chain, tx_hash, from_address, to_address, asset, and amount_usd, plus your own user_ref and kyc_ref if you keep them.
What comes back is a match, a screening result, or a verdict — and, on every path, an indication of whether we can currently see. coverage_health accompanies exposure results, is separately queryable at GET /v1/coverage, and is condensed into a Foreshock-Coverage-Health response header on the screening and decision endpoints.
What the API deliberately does not return
- The address that is the subject of an enforcement event.
- Any detail of how a relation was established.
- Any bulk export of enforcement data in a non-terminal stage.
- Any blended risk score. Vendor results are returned side by side on the vendor’s own scale, never rescaled and never merged. There is no debug or verbose mode that adds a Foreshock score, because no such mode exists.
- Any expectation of how much advance notice you will get. Visibility is a by-product of each issuer’s governance structure, not something Foreshock provides, and an issuer can change how it executes at any time.
What Foreshock is not
It does not perform KYC. kyc_ref is a reference you keep; it is stored and echoed, never evaluated.
It holds no key that can move funds. That is an architectural fact about the collectors, not a policy commitment.
It does not move money, freeze anything, or act on your behalf. Every action stays on your side of the boundary. The product position is advance refusal — declining to credit — and nothing else.
Where to go next
Read the shape of an integration, then read the fail-closed client contract before you write the first request. Everything else in these docs assumes you have.