Types, enumerations, and reason codes

Stable URI identifying the problem class.

Short, human-readable summary of the problem class.

HTTP status code, repeated for convenience.

Human-readable explanation specific to this occurrence.

Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always HOLD.

Identifier for this request, for support correlation.

Identifier of one enforcement authority — a single "who can freeze what, where" entry — as it appears in your account's coverage. Treat it as an opaque, stable string. The live set of authorities is returned by GET /v1/coverage to authenticated customers and is not enumerated in this document.

Whether this authority is currently observable to Foreshock. Observability is a property of the authority, not a Foreshock capability, and it can change without notice.

When this authority's registry entry was last verified against the chain. An entry that has not been re-verified within its window is reported as degraded and downgrades any decision that depends on it.

Current lag, in seconds, between chain state and Foreshock's view of this authority.

Opaque reference to one entry in your own address book. Stable for the lifetime of that entry and resolvable only by your account. It is not the address and cannot be reversed into one.

An enum indicating how the customer address relates to the enforcement event.

• DIRECT — the customer address is itself the subject of the event.
• INDIRECT — the event does not name the customer address, but is related to it.
• PATH — the relation is expressed at the level of the inbound route, not at the level of any individual party on it.

The values are ordinal in specificity only. No further detail about the relation is available through this API by any parameter, plan, or mode.

Ordinal severity band of the match. R0 is the lowest band and R2 the highest band exposed on the exposure endpoint.

A band is not a score. Foreshock publishes no numeric risk score, on this endpoint or any other, in any mode.

Stage of the enforcement event underlying this match, at observed_at.

• PROPOSED — the event exists and is not yet executed; treat as live and begin declining inbound funds on the matched address.
• CONFIRMING — the event is progressing toward execution.
• EXECUTED — the event has been carried out.

Matches that leave this set are announced through the exposure.revoked webhook and disappear from subsequent pages. They are never removed silently.

When Foreshock observed this match.

Content-addressed reference to an immutable snapshot of a raw upstream response, of the form cas:sha256:<hex>. Snapshots are append-only and version-locked, so a reference resolves to the same bytes forever. Derived conclusions can be recomputed; the raw data behind them cannot be rewritten.

Instant this response describes.

Coverage health of the authorities in scope for your account, returned with every exposure response so that "no matches" can be told apart from "we cannot currently see".

Matches against your own address book, in cursor order.

Cursor to pass as since on the next call, or null when you are caught up. Opaque; do not parse.

Instant this response describes.

Chain identifier. Values are data, not a fixed vocabulary: the set supported for your account is returned by GET /v1/coverage. New chains appear without a version bump of this document.

On-chain address, in the canonical textual form for its chain.

On chains where the freeze primitive operates on a token account rather than a wallet, state is per token account: two token accounts of the same wallet can be in different states, and must be submitted separately.

How far to screen. A runs authoritative lists only and is not billed. B additionally permits third-party vendor calls, subject to your routing rules, cost gate, and cache; requesting B does not guarantee a vendor call is made.

Identifier of the list source. Values are data; the set available to your account is not enumerated in this document.

Whether the address is present on this source.

Source-specific detail about the hit, present only when hit is true. Contents vary by source and are passed through as the source expressed them.

Version identifier of the list as published by its source.

Content-addressed reference to an immutable snapshot of a raw upstream response, of the form cas:sha256:<hex>. Snapshots are append-only and version-locked, so a reference resolves to the same bytes forever. Derived conclusions can be recomputed; the raw data behind them cannot be rewritten.

One entry per authoritative list source consulted, hit or not.

Wall-clock time spent on layer A, in milliseconds.

Vendor name.

The vendor's own classification, verbatim.

The vendor's own score, if the vendor produces one, on the vendor's own scale. null when the vendor does not provide one. Never normalised, never combined with any other source, and never a Foreshock score.

The vendor's own labels, untranslated.

Version identifier of the vendor data set consulted.

Content-addressed reference to an immutable snapshot of a raw upstream response, of the form cas:sha256:<hex>. Snapshots are append-only and version-locked, so a reference resolves to the same bytes forever. Derived conclusions can be recomputed; the raw data behind them cannot be rewritten.

Wall-clock time spent on layer B, in milliseconds.

Vendor results, or null when no vendor call was made — because depth was A, because your cost gate suppressed it, or because a cached result covered it.

Billable units consumed by this call. Layer A is never billed, so a layer-A only response is 0.

Your own identifier for this deposit. Echoed into the decision record.

Chain identifier. Values are data, not a fixed vocabulary: the set supported for your account is returned by GET /v1/coverage. New chains appear without a version bump of this document.

Transaction hash of the inbound transfer.

On-chain address, in the canonical textual form for its chain.

On chains where the freeze primitive operates on a token account rather than a wallet, state is per token account: two token accounts of the same wallet can be in different states, and must be submitted separately.

On-chain address, in the canonical textual form for its chain.

On chains where the freeze primitive operates on a token account rather than a wallet, state is per token account: two token accounts of the same wallet can be in different states, and must be submitted separately.

Asset symbol or contract reference for the transferred asset. Values are data; the supported set for your account is reflected in GET /v1/coverage.

Amount in USD, as a decimal string to avoid floating-point loss. Used against the thresholds you configured.

Your identifier for the depositing user. Foreshock does not perform KYC and stores this only as a reference.

Your identifier for the user's existing KYC record. A reference only; Foreshock does not perform or evaluate KYC.

Classification code explaining why a verdict came out the way it did.

Reason codes classify. They do not describe derivation, and none of them is accompanied by an enforcement target address, a path detail, or a score.

Risk classifications

Degradations — every one of these yields HOLD with HTTP 200

There is no reason code that permits a credit on degradation, and none will be added. New codes may be introduced in a minor version; clients must treat an unrecognised code as at least as serious as the accompanying risk_level.

Severity band this reason contributed, when the reason carries one. A band, not a score.

Vendor name, present only on reasons that originate from a third-party vendor.

Reference to the immutable snapshot of the raw upstream response behind this reason, when one exists.

Identifier of the append-only decision record. Use it to fetch the evidence bundle. Decision records are never updated or deleted.

• CREDIT — the deposit may be credited.
• HOLD — the deposit must not be credited yet. Every degraded path resolves here.
• REJECT — the deposit must not be credited.

There is no fourth value, and no path returns CREDIT when any input was degraded, stale, unavailable, or over budget.

Ordinal risk band assigned to a decision, R0 (lowest) through R4 (highest). A band, not a score; no numeric score is published.

Segregation pool the funds should be routed to. Keeping pools separate is what prevents differently classified funds from being swept into one collection address.

Classification codes behind the verdict. Empty only on a clean CREDIT.

Whether third-party vendors returned mutually inconsistent classifications. Reported so you can see the disagreement. Foreshock does not resolve it into a single answer.

Version of your rule set that produced this decision. Rule versions are stored, two-person reviewed, and reproducible, so a past decision can be replayed against the rules that were actually in force at the time.

Steps your workflow must complete before this deposit can leave HOLD.

When the required actions are due under your configured service levels. null when no deadline applies.

Content-addressed reference to an immutable snapshot of a raw upstream response, of the form cas:sha256:<hex>. Snapshots are append-only and version-locked, so a reference resolves to the same bytes forever. Derived conclusions can be recomputed; the raw data behind them cannot be rewritten.

Billable units consumed by this decision.

Stable identifier for this event. Constant across retries. Deduplicate on this.

Type of this event. Mirrors the Foreshock-Event-Type header.

When the event occurred. Retries do not change this value.

Stable identifier for this event. Constant across retries. Deduplicate on this.

Type of this event. Mirrors the Foreshock-Event-Type header.

When the event occurred. Retries do not change this value.

One match between an enforcement event and an entry in your own address book.

This object is the complete match record. There is no expanded, verbose, or premium form of it that adds the subject address, any path detail, or any score, and no parameter that requests one.

Stable identifier for this event. Constant across retries. Deduplicate on this.

Type of this event. Mirrors the Foreshock-Event-Type header.

When the event occurred. Retries do not change this value.

Opaque reference to one entry in your own address book. Stable for the lifetime of that entry and resolvable only by your account. It is not the address and cannot be reversed into one.

Terminal stage that removed a match from the active set.

• REVOKED — the underlying event was withdrawn. Not a clearance.
• EXPIRED — the event did not execute within its configured window.
• STALE — the underlying data can no longer be trusted. Not a clearance either; treat the affected scope as a blind spot and fall back to a more conservative policy.

Content-addressed reference to an immutable snapshot of a raw upstream response, of the form cas:sha256:<hex>. Snapshots are append-only and version-locked, so a reference resolves to the same bytes forever. Derived conclusions can be recomputed; the raw data behind them cannot be rewritten.

Stable identifier for this event. Constant across retries. Deduplicate on this.

Type of this event. Mirrors the Foreshock-Event-Type header.

When the event occurred. Retries do not change this value.

Current health of the affected authorities.