API 参考

接口、Webhook 与错误模型

由构建期从 OpenAPI 契约渲染。字段描述逐字取自契约，这里不做任何改写。

契约版本: 1.0.0
契约摘要: 0c75891a35d8

来源: api/openapi.yaml
契约版本: 1.0.0
规范: OpenAPI 3.1.0
契约摘要: sha256:0c75891a35d8

契约总述

Foreshock normalizes heterogeneous stablecoin freeze mechanisms across issuers and chains into one event model, one API, and one deposit-handling workflow.

The API answers three questions:

Exposure — which of your own addresses currently relate to an enforcement event, how, and how severely.
Screening — what authoritative lists say about an address, with a reference to the raw response snapshot behind each answer.
Decision — whether an inbound deposit may be credited, held, or rejected, with an immutable evidence record.

Fail-closed by contract

Every degraded path in this API resolves to HOLD. There is no fail-open branch. Vendor timeouts, exhausted budgets, and stale lists return HTTP 200 with verdict: HOLD and a reason code. Foreshock being unavailable returns 5xx with no verdict, and clients MUST treat any 5xx as HOLD. The official SDKs do this by default; if you write your own client, you must implement it yourself.

No synthetic scores

Foreshock does not publish a blended risk score. Results from multiple sources are returned side by side, unmodified, each with a snapshot reference. Third-party vendor scores are passed through verbatim and are not converted to a common scale — different vendors' scores are not comparable, and converting them would manufacture false precision. There is no debug or verbose mode that reveals an internal score, because no internal score is ever placed in an outbound response body.

Blind spots are disclosed, not hidden

Enforcement visibility is a by-product of each issuer's governance structure, not a capability Foreshock provides, and an issuer can change how it executes at any time. coverage_health therefore accompanies exposure results and is separately inspectable at GET /v1/coverage, so you can tell "nothing is wrong" apart from "we cannot currently see". observable: false, a stale verified_at, or an abnormal collector_lag_s should be treated as a blind spot, and your client should fall back to a more conservative policy.

What this API deliberately does not return

The address that is the subject of an enforcement event.
Any path detail, upstream address, or counterparty identity.
Any bulk export of enforcement data in a non-terminal stage.
Any expectation of how much advance notice a given issuer will provide.

Examples in this document

Every address, transaction hash, identifier, and snapshot reference in the examples below is a synthetic placeholder and is intentionally not valid on any chain. Placeholders contain the literal string EXAMPLE or a repeated digit so they cannot be mistaken for real data.

认证

http · bearer · Foreshock API key

Authorization: Bearer <api_key>.

Keys are scoped to a single customer account. Cross-customer reads are not expressible: customer_id is the leading key column and partition key of every customer data table, so a key cannot address another account's data even in principle.

Operations marked x-kyb-required: true additionally require the account to have completed institutional KYB verification. A valid key on a non-verified account receives 403 with type: .../kyb-required, not 401.

服务端点

https://api.foreshock.org

Managed endpoint.

https://{host}

Self-hosted deployment. Self-hosting is a first-class delivery form: the customer address book never leaves the customer environment.

接口

GET /v1/exposure

List matches between enforcement events and your own addresses

Bearer 密钥需 KYB

Returns the enforcement matches for your own address book, newest first by cursor order, together with the coverage health of the authorities relevant to your account.

Each match answers exactly three things: which of your addresses matched (as an opaque reference), how it relates to the enforcement event, and how severe the relation is. It does not identify the subject of the enforcement event, and it does not describe how the relation was established.

Pagination. Pass the next_cursor from the previous response as since to continue. When next_cursor is null you have consumed everything currently available. limit is capped; this endpoint is a change feed, not an export.

No bulk export. There is no endpoint, parameter, or format that dumps enforcement data in a non-terminal stage, in this API or elsewhere.

Access requires a KYB-verified institutional account.

契约扩展

x-kyb-required: true
x-no-bulk-export: true

参数

名称位置类型必填描述

since

query

string

否

名称	位置	类型	必填	描述
since	query	string	否	Opaque cursor from the `next_cursor` of a previous response. Omit to start from the beginning of your currently retained window. Cursor contents are not structured and must not be parsed, constructed, or ordered by the client. 约束 `maxLength=512` 示例 `eyJFWEFNUExFIjoiY3Vyc29yLXBsYWNlaG9sZGVyIn0`
limit	query	integer	否	Maximum number of matches to return in one page. The cap is deliberate: this endpoint is a change feed for your own address book, not an export interface. 约束 `minimum=1` `maximum=200` `default=100`

Opaque cursor from the next_cursor of a previous response. Omit to start from the beginning of your currently retained window. Cursor contents are not structured and must not be parsed, constructed, or ordered by the client.

约束 maxLength=512

示例 eyJFWEFNUExFIjoiY3Vyc29yLXBsYWNlaG9sZGVyIn0

limit

query

integer

否

Maximum number of matches to return in one page. The cap is deliberate: this endpoint is a change feed for your own address book, not an export interface.

约束 minimum=1 maximum=200 default=100

响应

200 application/json · ExposureResponse

Matches and coverage health as of the returned timestamp.

响应头

名称	类型	必填	描述
RateLimit-Limit	integer	否	Requests permitted in the current window for this account. 示例 `600`
RateLimit-Remaining	integer	否	Requests remaining in the current window. 示例 `597`
RateLimit-Reset	integer	否	Seconds until the current window resets. 示例 `42`

名称	类型	必填	描述
as_of	string(date-time)	是	Instant this response describes. 约束 `format=date-time` 示例 `2026-08-24T09:05:00Z`
coverage_health	array<CoverageHealthEntry>	是	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	array<ExposureMatch>	是	Matches against your own address book, in cursor order.
next_cursor	string \| null	否	Cursor to pass as `since` on the next call, or `null` when you are caught up. Opaque; do not parse. 示例 `eyJFWEFNUExFIjoibmV4dC1jdXJzb3ItcGxhY2Vob2xkZXIifQ`

{
  "as_of": "2026-08-24T09:05:00Z",
  "coverage_health": [
    {
      "authority_id": "authority-EXAMPLE-0001",
      "observable": true,
      "verified_at": "2026-08-24T09:00:00Z",
      "collector_lag_s": 3
    },
    {
      "authority_id": "authority-EXAMPLE-0002",
      "observable": false,
      "verified_at": "2026-08-23T21:40:00Z",
      "collector_lag_s": 1
    }
  ],
  "matches": [
    {
      "customer_address_ref": "caref_EXAMPLE0000000000000001",
      "relation": "PATH",
      "severity": "R1",
      "stage": "PROPOSED",
      "observed_at": "2026-08-24T09:04:11Z",
      "evidence_ref": "cas:sha256:EXAMPLE00000000000000000000000000000000000000000000000000000000"
    }
  ],
  "next_cursor": "eyJFWEFNUExFIjoibmV4dC1jdXJzb3ItcGxhY2Vob2xkZXIifQ"
}

400 application/problem+json · Problem

The request was malformed or failed validation.

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

{
  "type": "https://foreshock.org/problems/invalid-request",
  "title": "Invalid request",
  "status": 400,
  "detail": "`chain` is required.",
  "request_id": "req_EXAMPLE0000000001"
}

401 application/problem+json · Problem

Missing, malformed, or revoked API key.

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

{
  "type": "https://foreshock.org/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "API key missing or not recognised.",
  "request_id": "req_EXAMPLE0000000002"
}

403 application/problem+json · Problem

The key is valid, but this operation is restricted to KYB-verified institutional accounts. Enforcement data in a non-terminal stage is not available to unverified accounts under any plan.

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

{
  "type": "https://foreshock.org/problems/kyb-required",
  "title": "KYB verification required",
  "status": 403,
  "detail": "This account has not completed institutional KYB verification.",
  "request_id": "req_EXAMPLE0000000004"
}

429 application/problem+json · Problem

Rate limit exceeded.

响应头

名称	类型	必填	描述
Retry-After	integer	否	Seconds to wait before retrying. On the decision endpoint, waiting is not a substitute for a verdict: the deposit stays on `HOLD` until a 200 is received. 示例 `30`
RateLimit-Limit	integer	否	Requests permitted in the current window for this account. 示例 `600`
RateLimit-Remaining	integer	否	Requests remaining in the current window. 示例 `597`
RateLimit-Reset	integer	否	Seconds until the current window resets. 示例 `42`

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

{
  "type": "https://foreshock.org/problems/rate-limited",
  "title": "Too many requests",
  "status": 429,
  "detail": "Rate limit exceeded for this account.",
  "request_id": "req_EXAMPLE0000000007"
}

503 application/problem+json · Problem

Foreshock is temporarily unavailable.

响应头

名称	类型	必填	描述
Retry-After	integer	否	Seconds to wait before retrying. On the decision endpoint, waiting is not a substitute for a verdict: the deposit stays on `HOLD` until a 200 is received. 示例 `30`

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

{
  "type": "https://foreshock.org/problems/unavailable",
  "title": "Service unavailable",
  "status": 503,
  "detail": "Temporarily unavailable.",
  "request_id": "req_EXAMPLE0000000009"
}

GET /v1/coverage

Inspect coverage health

Bearer 密钥需 KYB

Returns the current observability health of the enforcement authorities relevant to your account: whether each is currently observable, when its registry entry was last verified, and the current collector lag.

Scope is per-customer. An authenticated caller sees the authorities that bear on the assets and addresses they have registered — not the full Foreshock registry. The set of authorities, issuers, and chains is returned as data to authenticated customers; it is not enumerated in this schema and is not published to unauthenticated parties. Absence of an entry means the authority is out of scope for your account, and must not be read as a statement about Foreshock's registry as a whole.

Use this endpoint to distinguish "no alert" from "we cannot currently see".

Access requires a KYB-verified institutional account.

契约扩展

x-kyb-required: true
x-scope: per-customer

响应

200 application/json · CoverageResponse

Coverage health for the authorities in scope for the caller.

响应头

名称	类型	必填	描述
RateLimit-Limit	integer	否	Requests permitted in the current window for this account. 示例 `600`
RateLimit-Remaining	integer	否	Requests remaining in the current window. 示例 `597`
RateLimit-Reset	integer	否	Seconds until the current window resets. 示例 `42`

名称类型必填描述

as_of

string(date-time)

是

Instant this response describes.

约束 format=date-time

示例 2026-08-24T09:05:00Z

coverage_health

array<CoverageHealthEntry>

是

{
  "as_of": "2026-08-24T09:05:00Z",
  "coverage_health": [
    {
      "authority_id": "authority-EXAMPLE-0001",
      "observable": true,
      "verified_at": "2026-08-24T09:00:00Z",
      "collector_lag_s": 3
    },
    {
      "authority_id": "authority-EXAMPLE-0002",
      "observable": false,
      "verified_at": "2026-08-23T21:40:00Z",
      "collector_lag_s": 1
    }
  ]
}

401 application/problem+json · Problem

Missing, malformed, or revoked API key.

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

{
  "type": "https://foreshock.org/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "API key missing or not recognised.",
  "request_id": "req_EXAMPLE0000000002"
}

403 application/problem+json · Problem

The key is valid, but this operation is restricted to KYB-verified institutional accounts. Enforcement data in a non-terminal stage is not available to unverified accounts under any plan.

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

{
  "type": "https://foreshock.org/problems/kyb-required",
  "title": "KYB verification required",
  "status": 403,
  "detail": "This account has not completed institutional KYB verification.",
  "request_id": "req_EXAMPLE0000000004"
}

429 application/problem+json · Problem

Rate limit exceeded.

响应头

名称	类型	必填	描述
Retry-After	integer	否	Seconds to wait before retrying. On the decision endpoint, waiting is not a substitute for a verdict: the deposit stays on `HOLD` until a 200 is received. 示例 `30`
RateLimit-Limit	integer	否	Requests permitted in the current window for this account. 示例 `600`
RateLimit-Remaining	integer	否	Requests remaining in the current window. 示例 `597`
RateLimit-Reset	integer	否	Seconds until the current window resets. 示例 `42`

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

{
  "type": "https://foreshock.org/problems/rate-limited",
  "title": "Too many requests",
  "status": 429,
  "detail": "Rate limit exceeded for this account.",
  "request_id": "req_EXAMPLE0000000007"
}

503 application/problem+json · Problem

Foreshock is temporarily unavailable.

响应头

名称	类型	必填	描述
Retry-After	integer	否	Seconds to wait before retrying. On the decision endpoint, waiting is not a substitute for a verdict: the deposit stays on `HOLD` until a 200 is received. 示例 `30`

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

{
  "type": "https://foreshock.org/problems/unavailable",
  "title": "Service unavailable",
  "status": 503,
  "detail": "Temporarily unavailable.",
  "request_id": "req_EXAMPLE0000000009"
}

POST /v1/screen/address

Screen one address against authoritative lists

Bearer 密钥

Screens a single address. Layer A covers authoritative lists and is not billed. Layer B covers third-party attribution vendors and is billed per call; whether Layer B runs is governed by your routing and cost-gate configuration.

Every hit and every vendor result carries a snapshot_ref / raw_ref pointing at the immutable, content-addressed snapshot of the raw upstream response that produced it. Answers are references, not bare booleans, so any result can be re-derived and audited later.

Vendor scores are returned exactly as the vendor produced them. They are not rescaled, not merged, and not combined into any Foreshock score.

This endpoint reports on an address. It is not a credit decision — use POST /v1/decide/deposit for that, which is the only endpoint that produces a binding, evidence-backed verdict.

参数

名称位置类型必填描述

Idempotency-Key

header

string

否

名称	位置	类型	必填	描述
Idempotency-Key	header	string	否	Client-generated key that makes this request safely retryable. A repeat of the same key with an identical body replays the stored response and is not billed again; the same key with a different body returns `409`. Keys are scoped to your account and retained for 24 hours. Use a UUID. 约束 `minLength=8` `maxLength=255` 示例 `22222222-2222-4222-8222-222222222222`

Client-generated key that makes this request safely retryable. A repeat of the same key with an identical body replays the stored response and is not billed again; the same key with a different body returns 409. Keys are scoped to your account and retained for 24 hours. Use a UUID.

约束 minLength=8 maxLength=255

示例 22222222-2222-4222-8222-222222222222

请求体 · application/json · ScreenAddressRequest

名称类型必填描述

chain

名称	类型	必填	描述
chain	Chain	是	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. 约束 `minLength=1` `maxLength=64` 示例 `example-chain`
address	Address	是	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. 约束 `minLength=1` `maxLength=128` 示例 `0xEXAMPLEaddress0000000000000000000000000`
depth	string	否	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. 取值 `AB` 约束 `default=A` 示例 `A`

Chain

是

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.

约束 minLength=1 maxLength=64

示例 example-chain

address

Address

是

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.

约束 minLength=1 maxLength=128

示例 0xEXAMPLEaddress0000000000000000000000000

depth

string

否

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.

取值 AB

约束 default=A

示例 A

{
  "chain": "example-chain",
  "address": "0xEXAMPLEaddress0000000000000000000000000",
  "depth": "A"
}

响应

200 application/json · ScreenAddressResponse

Screening result.

响应头

名称	类型	必填	描述
Foreshock-Coverage-Health	string	否	Coarse coverage signal for the authorities in scope for this request. `ok` means every relevant authority is currently observable and within its lag and verification thresholds; `degraded` means at least one is not. This header is a pointer, not a report: on `degraded`, call `GET /v1/coverage` for the per-authority detail. It exists so that coverage health is never absent from a response, without altering the response body. 取值 `okdegraded` 示例 `ok`
Idempotency-Replayed	boolean	否	Present and `true` when this response was replayed from a stored idempotent result. 示例 `true`
RateLimit-Limit	integer	否	Requests permitted in the current window for this account. 示例 `600`
RateLimit-Remaining	integer	否	Requests remaining in the current window. 示例 `597`
RateLimit-Reset	integer	否	Seconds until the current window resets. 示例 `42`

名称类型必填描述

layer_a

名称	类型	必填	描述
layer_a	LayerAResult	是
layer_b	LayerBResult \| null	是	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	integer	是	Billable units consumed by this call. Layer A is never billed, so a layer-A only response is `0`. 约束 `minimum=0` 示例 `0`

LayerAResult

是

layer_b

LayerBResult | null

是

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

integer

是

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

约束 minimum=0

示例 0

{
  "layer_a": {
    "hits": [
      {
        "source": "example_issuer_blacklist",
        "hit": true,
        "detail": {
          "stage": "EXECUTED",
          "executed_at": "2026-08-22T14:31:07Z"
        },
        "snapshot_ref": "cas:sha256:EXAMPLE00000000000000000000000000000000000000000000000000000001"
      },
      {
        "source": "sanctions_list",
        "hit": false,
        "list_version": "example-list-v2026.08.24",
        "snapshot_ref": "cas:sha256:EXAMPLE00000000000000000000000000000000000000000000000000000002"
      }
    ],
    "latency_ms": 41
  },
  "layer_b": null,
  "billable_units": 0
}

400 application/problem+json · Problem

The request was malformed or failed validation.

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

{
  "type": "https://foreshock.org/problems/invalid-request",
  "title": "Invalid request",
  "status": 400,
  "detail": "`chain` is required.",
  "request_id": "req_EXAMPLE0000000001"
}

401 application/problem+json · Problem

Missing, malformed, or revoked API key.

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

{
  "type": "https://foreshock.org/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "API key missing or not recognised.",
  "request_id": "req_EXAMPLE0000000002"
}

409 application/problem+json · Problem

The Idempotency-Key was already used with a different request body.

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

{
  "type": "https://foreshock.org/problems/idempotency-conflict",
  "title": "Idempotency key reused with a different body",
  "status": 409,
  "detail": "Use a new key, or resend the original body to replay the stored result.",
  "request_id": "req_EXAMPLE0000000006"
}

429 application/problem+json · Problem

Rate limit exceeded.

响应头

名称	类型	必填	描述
Retry-After	integer	否	Seconds to wait before retrying. On the decision endpoint, waiting is not a substitute for a verdict: the deposit stays on `HOLD` until a 200 is received. 示例 `30`
RateLimit-Limit	integer	否	Requests permitted in the current window for this account. 示例 `600`
RateLimit-Remaining	integer	否	Requests remaining in the current window. 示例 `597`
RateLimit-Reset	integer	否	Seconds until the current window resets. 示例 `42`

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

{
  "type": "https://foreshock.org/problems/rate-limited",
  "title": "Too many requests",
  "status": 429,
  "detail": "Rate limit exceeded for this account.",
  "request_id": "req_EXAMPLE0000000007"
}

503 application/problem+json · Problem

Foreshock is temporarily unavailable.

响应头

名称	类型	必填	描述
Retry-After	integer	否	Seconds to wait before retrying. On the decision endpoint, waiting is not a substitute for a verdict: the deposit stays on `HOLD` until a 200 is received. 示例 `30`

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

{
  "type": "https://foreshock.org/problems/unavailable",
  "title": "Service unavailable",
  "status": 503,
  "detail": "Temporarily unavailable.",
  "request_id": "req_EXAMPLE0000000009"
}

POST /v1/decide/deposit

Decide whether an inbound deposit may be credited

Bearer 密钥需 KYB Fail-closed

The credit gate. Returns CREDIT, HOLD, or REJECT for one inbound deposit, and writes an append-only decision record with an evidence reference.

Fail-closed. There is no branch of this endpoint that returns CREDIT on degradation.

Condition	Verdict	Reason code	HTTP
Vendor timeout or vendor unavailable	`HOLD`	`SCREENING_DEGRADED`	200
Customer daily budget exhausted	`HOLD`	`BUDGET_EXHAUSTED`	200
A required list is older than its freshness SLO	`HOLD`	`LIST_STALE`	200
A registry entry has not been re-verified in time	`HOLD`	`REGISTRY_ENTRY_STALE`	200
An authority in scope for this deposit is not observable	`HOLD`	`COVERAGE_BLIND_SPOT`	200
Decision could not complete within its latency budget	`HOLD`	`DECISION_TIMEOUT`	200
Foreshock is unavailable	no response body	—	5xx

Clients MUST treat any 5xx response from this endpoint as HOLD. Do not credit the deposit, do not retry-until-success and credit on the first 2xx without re-evaluating, and do not fall back to a local allow rule. The official Foreshock SDKs implement 5xx-as-HOLD as the default behaviour and it cannot be disabled by configuration; if you build your own client, this is your obligation. A timeout on your side, a TLS failure, or a DNS failure is the same case: HOLD.

reasons are classification codes, not derivations. They tell you why the deposit was stopped. They do not tell you how the determination was reached, and they never contain an enforcement target address, a path detail, or a score.

Idempotency: send an Idempotency-Key. A repeat of the same key with the same body replays the stored decision, including its original decision_id, and is not billed again.

Access requires a KYB-verified institutional account.

契约扩展

x-fail-closed: true
x-kyb-required: true
x-client-contract: Any 5xx, connection error, or client-side timeout MUST be treated as verdict HOLD.

参数

名称位置类型必填描述

Idempotency-Key

header

string

否

名称	位置	类型	必填	描述
Idempotency-Key	header	string	否	Client-generated key that makes this request safely retryable. A repeat of the same key with an identical body replays the stored response and is not billed again; the same key with a different body returns `409`. Keys are scoped to your account and retained for 24 hours. Use a UUID. 约束 `minLength=8` `maxLength=255` 示例 `22222222-2222-4222-8222-222222222222`

约束 minLength=8 maxLength=255

示例 22222222-2222-4222-8222-222222222222

请求体 · application/json · DecideDepositRequest

名称	类型	必填	描述
deposit_ref	string	是	Your own identifier for this deposit. Echoed into the decision record. 约束 `maxLength=128` 示例 `deposit-EXAMPLE-0001`
chain	Chain	是	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. 约束 `minLength=1` `maxLength=64` 示例 `example-chain`
tx_hash	string	是	Transaction hash of the inbound transfer. 约束 `maxLength=128` 示例 `0xEXAMPLEtxhash000000000000000000000000000000000000000000000000000`
from_address	Address	是	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. 约束 `minLength=1` `maxLength=128` 示例 `0xEXAMPLEaddress0000000000000000000000000`
to_address	Address	是	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. 约束 `minLength=1` `maxLength=128` 示例 `0xEXAMPLEaddress0000000000000000000000000`
asset	string	是	Asset symbol or contract reference for the transferred asset. Values are data; the supported set for your account is reflected in `GET /v1/coverage`. 约束 `maxLength=128` 示例 `EXAMPLEUSD`
amount_usd	string	是	Amount in USD, as a decimal string to avoid floating-point loss. Used against the thresholds you configured. 约束 `pattern=^[0-9]+(\.[0-9]+)?$` 示例 `25000.00`
user_ref	string	否	Your identifier for the depositing user. Foreshock does not perform KYC and stores this only as a reference. 约束 `maxLength=128` 示例 `user-EXAMPLE-0001`
kyc_ref	string	否	Your identifier for the user's existing KYC record. A reference only; Foreshock does not perform or evaluate KYC. 约束 `maxLength=128` 示例 `kyc-EXAMPLE-0001`

{
  "deposit_ref": "deposit-EXAMPLE-0001",
  "chain": "example-chain",
  "tx_hash": "0xEXAMPLEtxhash000000000000000000000000000000000000000000000000000",
  "from_address": "0xEXAMPLEaddress0000000000000000000000001",
  "to_address": "0xEXAMPLEaddress0000000000000000000000002",
  "asset": "EXAMPLEUSD",
  "amount_usd": "25000.00",
  "user_ref": "user-EXAMPLE-0001",
  "kyc_ref": "kyc-EXAMPLE-0001"
}

响应

200 application/json · DecideDepositResponse

A decision was produced. This includes every degraded case in the table above, which returns 200 with verdict: HOLD and a reason code.

响应头

名称	类型	必填	描述
Foreshock-Coverage-Health	string	否	Coarse coverage signal for the authorities in scope for this request. `ok` means every relevant authority is currently observable and within its lag and verification thresholds; `degraded` means at least one is not. This header is a pointer, not a report: on `degraded`, call `GET /v1/coverage` for the per-authority detail. It exists so that coverage health is never absent from a response, without altering the response body. 取值 `okdegraded` 示例 `ok`
Idempotency-Replayed	boolean	否	Present and `true` when this response was replayed from a stored idempotent result. 示例 `true`
RateLimit-Limit	integer	否	Requests permitted in the current window for this account. 示例 `600`
RateLimit-Remaining	integer	否	Requests remaining in the current window. 示例 `597`
RateLimit-Reset	integer	否	Seconds until the current window resets. 示例 `42`

名称	类型	必填	描述
decision_id	string(uuid)	是	Identifier of the append-only decision record. Use it to fetch the evidence bundle. Decision records are never updated or deleted. 约束 `format=uuid` 示例 `11111111-1111-4111-8111-111111111111`
verdict	string	是	`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. 取值 `CREDITHOLDREJECT` 示例 `HOLD`
risk_level	RiskLevel	是	Ordinal risk band assigned to a decision, `R0` (lowest) through `R4` (highest). A band, not a score; no numeric score is published. 取值 `R0R1R2R3R4` 示例 `R1`
pool	Pool	是	Segregation pool the funds should be routed to. Keeping pools separate is what prevents differently classified funds from being swept into one collection address. 取值 `cleantaggedquarantine` 示例 `quarantine`
reasons	array<DecisionReason>	是	Classification codes behind the verdict. Empty only on a clean `CREDIT`.
vendor_disagreement	boolean	是	Whether third-party vendors returned mutually inconsistent classifications. Reported so you can see the disagreement. Foreshock does not resolve it into a single answer. 示例
rule_version	string	是	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. 示例 `rules-EXAMPLE-2026.08.01`
required_actions	array<RequiredAction>	是	Steps your workflow must complete before this deposit can leave `HOLD`.
sla_deadline	string \| null	否	When the required actions are due under your configured service levels. `null` when no deadline applies. 约束 `format=date-time` 示例 `2026-08-24T13:05:00Z`
evidence_ref	SnapshotRef	是	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. 约束 `pattern=^cas:sha256:[0-9a-zA-Z]{8,128}$` 示例 `cas:sha256:EXAMPLE00000000000000000000000000000000000000000000000000000000`
billable_units	integer	是	Billable units consumed by this decision. 约束 `minimum=0` 示例 `1`

{
  "decision_id": "11111111-1111-4111-8111-111111111111",
  "verdict": "HOLD",
  "risk_level": "R1",
  "pool": "quarantine",
  "reasons": [
    {
      "code": "ACTIVE_ENFORCEMENT_RELATION",
      "severity": "R1"
    },
    {
      "code": "VENDOR_HIGH_RISK",
      "vendor": "example-vendor",
      "raw_ref": "cas:sha256:EXAMPLE00000000000000000000000000000000000000000000000000000003"
    }
  ],
  "vendor_disagreement": false,
  "rule_version": "rules-EXAMPLE-2026.08.01",
  "required_actions": [
    "COLLECT_SOURCE_OF_FUNDS",
    "L2_REVIEW"
  ],
  "sla_deadline": "2026-08-24T13:05:00Z",
  "evidence_ref": "cas:sha256:EXAMPLE00000000000000000000000000000000000000000000000000000004",
  "billable_units": 1
}

400 application/problem+json · Problem

The request was malformed or failed validation.

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

{
  "type": "https://foreshock.org/problems/invalid-request",
  "title": "Invalid request",
  "status": 400,
  "detail": "`chain` is required.",
  "request_id": "req_EXAMPLE0000000001"
}

401 application/problem+json · Problem

Missing, malformed, or revoked API key.

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

{
  "type": "https://foreshock.org/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "API key missing or not recognised.",
  "request_id": "req_EXAMPLE0000000002"
}

403 application/problem+json · Problem

The key is valid, but this operation is restricted to KYB-verified institutional accounts. Enforcement data in a non-terminal stage is not available to unverified accounts under any plan.

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

{
  "type": "https://foreshock.org/problems/kyb-required",
  "title": "KYB verification required",
  "status": 403,
  "detail": "This account has not completed institutional KYB verification.",
  "request_id": "req_EXAMPLE0000000004"
}

409 application/problem+json · Problem

The Idempotency-Key was already used with a different request body.

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

{
  "type": "https://foreshock.org/problems/idempotency-conflict",
  "title": "Idempotency key reused with a different body",
  "status": 409,
  "detail": "Use a new key, or resend the original body to replay the stored result.",
  "request_id": "req_EXAMPLE0000000006"
}

429 application/problem+json · Problem

Rate limit exceeded. No verdict was produced. Treat as HOLD. Back off and retry; do not credit the deposit in the meantime.

响应头

名称	类型	必填	描述
Retry-After	integer	否	Seconds to wait before retrying. On the decision endpoint, waiting is not a substitute for a verdict: the deposit stays on `HOLD` until a 200 is received. 示例 `30`
RateLimit-Limit	integer	否	Requests permitted in the current window for this account. 示例 `600`
RateLimit-Remaining	integer	否	Requests remaining in the current window. 示例 `597`
RateLimit-Reset	integer	否	Seconds until the current window resets. 示例 `42`

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

{
  "type": "https://foreshock.org/problems/rate-limited",
  "title": "Too many requests",
  "status": 429,
  "detail": "Rate limit exceeded. No verdict was produced; treat as HOLD.",
  "fail_closed_action": "HOLD",
  "request_id": "req_EXAMPLE0000000008"
}

500 application/problem+json · Problem

Foreshock failed to produce a decision. No verdict exists. Treat as HOLD.

响应头

名称	类型	必填	描述
Retry-After	integer	否	Seconds to wait before retrying. On the decision endpoint, waiting is not a substitute for a verdict: the deposit stays on `HOLD` until a 200 is received. 示例 `30`

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

{
  "type": "https://foreshock.org/problems/internal-error",
  "title": "Internal error",
  "status": 500,
  "detail": "No verdict was produced; treat as HOLD.",
  "fail_closed_action": "HOLD",
  "request_id": "req_EXAMPLE0000000010"
}

503 application/problem+json · Problem

Foreshock is unavailable. No verdict exists. Treat as HOLD. This is the "our side is down" row of the degradation table: it is deliberately not returned as a 200 with a verdict, so that a client which ignores status codes cannot mistake an outage for a decision.

响应头

名称	类型	必填	描述
Retry-After	integer	否	Seconds to wait before retrying. On the decision endpoint, waiting is not a substitute for a verdict: the deposit stays on `HOLD` until a 200 is received. 示例 `30`

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

{
  "type": "https://foreshock.org/problems/unavailable",
  "title": "Service unavailable",
  "status": 503,
  "detail": "No verdict was produced; treat as HOLD.",
  "fail_closed_action": "HOLD",
  "request_id": "req_EXAMPLE0000000011"
}

504 application/problem+json · Problem

The request did not complete in time at the edge. No verdict exists. Treat as HOLD. A client-side timeout is the same case.

响应头

名称	类型	必填	描述
Retry-After	integer	否	Seconds to wait before retrying. On the decision endpoint, waiting is not a substitute for a verdict: the deposit stays on `HOLD` until a 200 is received. 示例 `30`

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

{
  "type": "https://foreshock.org/problems/gateway-timeout",
  "title": "Gateway timeout",
  "status": 504,
  "detail": "No verdict was produced; treat as HOLD.",
  "fail_closed_action": "HOLD",
  "request_id": "req_EXAMPLE0000000012"
}

GET /v1/decisions/{decision_id}/evidence

Download the evidence bundle for one decision

Bearer 密钥

Returns the immutable evidence bundle for a single decision the caller made, as a ZIP archive.

Bundle contents:

manifest.json          decision fields, evidence_hash, and verification instructions
layer_a/*.json         raw response snapshots from each authoritative list source
layer_b/*.json         raw vendor response bodies, subject to vendor licence terms
rule/{rule_version}.json
chain/{tx_hash}.json
report.pdf

evidence_hash in manifest.json lets you verify the bundle independently, without trusting Foreshock.

Where a vendor's licence does not permit redistribution of its raw response, the layer_b/ directory contains a call record summary plus the vendor name and list version instead of the raw body. The bundle states which form it used.

One decision per request. There is no batch or date-range export of evidence.

契约扩展

x-no-bulk-export: true

参数

名称位置类型必填描述

decision_id

path

string(uuid)

是

名称	位置	类型	必填	描述
decision_id	path	string(uuid)	是	Identifier of a decision previously returned to this account. 约束 `format=uuid` 示例 `11111111-1111-4111-8111-111111111111`
format	query	string	否	Bundle format. Only `bundle` is defined in v1. 取值 `bundle` 约束 `default=bundle`

Identifier of a decision previously returned to this account.

约束 format=uuid

示例 11111111-1111-4111-8111-111111111111

format

query

string

否

Bundle format. Only bundle is defined in v1.

取值 bundle

约束 default=bundle

响应

200 application/zip · string

The evidence bundle.

响应头

名称	类型	必填	描述
Content-Disposition	string	否	Suggested filename for the archive. 示例 `attachment; filename="foreshock-evidence-11111111-1111-4111-8111-111111111111.zip"`
RateLimit-Limit	integer	否	Requests permitted in the current window for this account. 示例 `600`
RateLimit-Remaining	integer	否	Requests remaining in the current window. 示例 `597`
RateLimit-Reset	integer	否	Seconds until the current window resets. 示例 `42`

401 application/problem+json · Problem

Missing, malformed, or revoked API key.

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

{
  "type": "https://foreshock.org/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "API key missing or not recognised.",
  "request_id": "req_EXAMPLE0000000002"
}

403 application/problem+json · Problem

The key is valid but not entitled to this resource.

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

{
  "type": "https://foreshock.org/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "This decision does not belong to the authenticated account.",
  "request_id": "req_EXAMPLE0000000003"
}

404 application/problem+json · Problem

No such resource for this account.

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

{
  "type": "https://foreshock.org/problems/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "No decision with that identifier.",
  "request_id": "req_EXAMPLE0000000005"
}

429 application/problem+json · Problem

Rate limit exceeded.

响应头

名称	类型	必填	描述
Retry-After	integer	否	Seconds to wait before retrying. On the decision endpoint, waiting is not a substitute for a verdict: the deposit stays on `HOLD` until a 200 is received. 示例 `30`
RateLimit-Limit	integer	否	Requests permitted in the current window for this account. 示例 `600`
RateLimit-Remaining	integer	否	Requests remaining in the current window. 示例 `597`
RateLimit-Reset	integer	否	Seconds until the current window resets. 示例 `42`

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

{
  "type": "https://foreshock.org/problems/rate-limited",
  "title": "Too many requests",
  "status": 429,
  "detail": "Rate limit exceeded for this account.",
  "request_id": "req_EXAMPLE0000000007"
}

503 application/problem+json · Problem

Foreshock is temporarily unavailable.

响应头

名称	类型	必填	描述
Retry-After	integer	否	Seconds to wait before retrying. On the decision endpoint, waiting is not a substitute for a verdict: the deposit stays on `HOLD` until a 200 is received. 示例 `30`

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

{
  "type": "https://foreshock.org/problems/unavailable",
  "title": "Service unavailable",
  "status": 503,
  "detail": "Temporarily unavailable.",
  "request_id": "req_EXAMPLE0000000009"
}

Webhook

由我们发给你 exposure.match

A match between an enforcement event and one of your addresses was created or updated

Sent when a match involving one of your own addresses is created, or when its stage or severity changes.

Payload carries the same fields as a match in GET /v1/exposure: an opaque reference to your address, the relation, the severity, the stage, the timestamp, and an evidence reference. It does not identify the subject of the enforcement event.

See #/components/schemas/WebhookEnvelope for delivery, signature, and retry semantics, and the request headers below for the verification inputs.

载荷 · ExposureMatchEvent

名称	类型	必填	描述
event_id	string(uuid)	是	Stable identifier for this event. Constant across retries. Deduplicate on this. 约束 `format=uuid` 示例 `44444444-4444-4444-8444-444444444444`
event_type	string	是	Type of this event. Mirrors the `Foreshock-Event-Type` header. 取值 `exposure.matchexposure.revokedcoverage.health_changed` 示例 `exposure.match`
occurred_at	string(date-time)	是	When the event occurred. Retries do not change this value. 约束 `format=date-time` 示例 `2026-08-24T09:04:11Z`
match	ExposureMatch	是	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. 示例 `[object Object]`

{
  "event_id": "44444444-4444-4444-8444-444444444444",
  "event_type": "exposure.match",
  "occurred_at": "2026-08-24T09:04:11Z",
  "match": {
    "customer_address_ref": "caref_EXAMPLE0000000000000001",
    "relation": "PATH",
    "severity": "R1",
    "stage": "PROPOSED",
    "observed_at": "2026-08-24T09:04:11Z",
    "evidence_ref": "cas:sha256:EXAMPLE00000000000000000000000000000000000000000000000000000000"
  }
}

响应

2XX

Acknowledged. Return any 2xx within 5 seconds. Anything else, or no response, is treated as a failed delivery and re-sent under the retry envelope.

default

Treated as a failed delivery. Delivery is retried with exponential backoff for up to 24 hours, after which the event goes to a dead-letter queue and an alert is raised on your account.

由我们发给你 exposure.revoked

A match was removed from your match set

Sent when a previously delivered match is removed from your match set.

Removals are always announced as their own event and are never silent. If they were silent, your local list would diverge from ours without you knowing.

A revocation is not a statement that the address is safe. It states only that the match is no longer in your active match set. Treat it as a change of state, not as a clearance.

载荷 · ExposureRevokedEvent

名称	类型	必填	描述
event_id	string(uuid)	是	Stable identifier for this event. Constant across retries. Deduplicate on this. 约束 `format=uuid` 示例 `44444444-4444-4444-8444-444444444444`
event_type	string	是	Type of this event. Mirrors the `Foreshock-Event-Type` header. 取值 `exposure.matchexposure.revokedcoverage.health_changed` 示例 `exposure.match`
occurred_at	string(date-time)	是	When the event occurred. Retries do not change this value. 约束 `format=date-time` 示例 `2026-08-24T09:04:11Z`
customer_address_ref	CustomerAddressRef	是	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. 约束 `minLength=1` `maxLength=128` 示例 `caref_EXAMPLE0000000000000001`
stage	RevocationStage	是	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. 取值 `REVOKEDEXPIREDSTALE` 示例 `REVOKED`
evidence_ref	SnapshotRef	是	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. 约束 `pattern=^cas:sha256:[0-9a-zA-Z]{8,128}$` 示例 `cas:sha256:EXAMPLE00000000000000000000000000000000000000000000000000000000`

{
  "event_id": "55555555-5555-4555-8555-555555555555",
  "event_type": "exposure.revoked",
  "occurred_at": "2026-08-24T10:12:00Z",
  "customer_address_ref": "caref_EXAMPLE0000000000000001",
  "stage": "REVOKED",
  "evidence_ref": "cas:sha256:EXAMPLE00000000000000000000000000000000000000000000000000000005"
}

响应

2XX

Acknowledged.

default

Treated as a failed delivery and retried under the 24-hour envelope.

由我们发给你 coverage.health_changed

The observability health of an authority in scope for your account changed

Sent when an authority in scope for your account becomes unobservable, becomes observable again, exceeds its lag threshold, or has a registry entry that is no longer within its verification window.

This is the blind-spot notification. On receipt, treat the affected scope as unverified and fall back to a more conservative policy until health is restored.

载荷 · CoverageHealthChangedEvent

名称	类型	必填	描述
event_id	string(uuid)	是	Stable identifier for this event. Constant across retries. Deduplicate on this. 约束 `format=uuid` 示例 `44444444-4444-4444-8444-444444444444`
event_type	string	是	Type of this event. Mirrors the `Foreshock-Event-Type` header. 取值 `exposure.matchexposure.revokedcoverage.health_changed` 示例 `exposure.match`
occurred_at	string(date-time)	是	When the event occurred. Retries do not change this value. 约束 `format=date-time` 示例 `2026-08-24T09:04:11Z`
coverage_health	array<CoverageHealthEntry>	是	Current health of the affected authorities.

{
  "event_id": "66666666-6666-4666-8666-666666666666",
  "event_type": "coverage.health_changed",
  "occurred_at": "2026-08-24T10:20:00Z",
  "coverage_health": [
    {
      "authority_id": "authority-EXAMPLE-0002",
      "observable": false,
      "verified_at": "2026-08-23T21:40:00Z",
      "collector_lag_s": 1
    }
  ]
}

响应

2XX

Acknowledged.

default

Treated as a failed delivery and retried under the 24-hour envelope.

投递请求头

名称	类型	必填	描述
Foreshock-Signature	string	是	Signature over the delivery, formatted as `t=<unix_seconds>,v1=<hex>` where `v1` is `HMAC-SHA256(signing_secret, "<t>.<raw_request_body>")` in lowercase hex. Verify before parsing the body: 1. Compute the HMAC over the raw bytes, not a re-serialized object. 2. Compare in constant time. 3. Reject if `\|now - t\| > 300` seconds, to bound replay. During secret rotation a delivery may carry more than one `v1=` value; accept the delivery if any of them verifies. 示例 `t=1700000000,v1=EXAMPLEsignature00000000000000000000000000000000000000000000000`
Foreshock-Signature-Timestamp	integer	是	Unix seconds at which the delivery was signed. Same value as `t` in the signature. 示例 `1700000000`
Foreshock-Delivery-Id	string(uuid)	是	Unique identifier of this delivery attempt. Distinct from `event_id`: retries of the same event carry the same `event_id` and different `Foreshock-Delivery-Id`. Deduplicate on `event_id`, log on `Foreshock-Delivery-Id`. 示例 `33333333-3333-4333-8333-333333333333`
Foreshock-Event-Type	string	是	Event type of this delivery. Mirrors `event_type` in the body. 取值 `exposure.matchexposure.revokedcoverage.health_changed` 示例 `exposure.match`
Foreshock-Webhook-Attempt	integer	是	1-based attempt number for this event. Increments on each retry. 示例 `1`

错误模型

CREDIT HOLD REJECT

RFC 9457 problem detail. All non-2xx responses use this shape.

fail_closed_action is present whenever the failure occurred on a decision path. Its only defined value is HOLD. It is a machine-readable restatement of the client obligation, not a verdict: a verdict only ever arrives in a 200 response body.

名称	类型	必填	描述
type	string(uri)	是	Stable URI identifying the problem class. 约束 `format=uri` 示例 `https://foreshock.org/problems/unavailable`
title	string	是	Short, human-readable summary of the problem class. 示例 `Service unavailable`
status	integer	是	HTTP status code, repeated for convenience. 示例 `503`
detail	string	否	Human-readable explanation specific to this occurrence. 示例 `No verdict was produced; treat as HOLD.`
fail_closed_action	string	否	Present on decision-path failures. Instructs the client what to do in the absence of a verdict. Always `HOLD`. 取值 `HOLD`
request_id	string	否	Identifier for this request, for support correlation. 示例 `req_EXAMPLE0000000013`

Problem 响应

响应	状态码	客户端动作	描述
BadRequest	400	—	The request was malformed or failed validation.
Unauthorized	401	—	Missing, malformed, or revoked API key.
Forbidden	403	—	The key is valid but not entitled to this resource.
ForbiddenKyb	403	—	The key is valid, but this operation is restricted to KYB-verified institutional accounts. Enforcement data in a non-terminal stage is not available to unverified accounts under any plan.
NotFound	404	—	No such resource for this account.
IdempotencyConflict	409	—	The `Idempotency-Key` was already used with a different request body.
TooManyRequests	429	—	Rate limit exceeded.
TooManyRequestsFailClosed	429	HOLD	Rate limit exceeded. No verdict was produced. Treat as `HOLD`. Back off and retry; do not credit the deposit in the meantime.
ServiceUnavailable	503	—	Foreshock is temporarily unavailable.
InternalErrorFailClosed	500	HOLD	Foreshock failed to produce a decision. No verdict exists. Treat as `HOLD`.
ServiceUnavailableFailClosed	503	HOLD	Foreshock is unavailable. No verdict exists. Treat as `HOLD`. This is the "our side is down" row of the degradation table: it is deliberately not returned as a 200 with a verdict, so that a client which ignores status codes cannot mistake an outage for a decision.
GatewayTimeoutFailClosed	504	HOLD	The request did not complete in time at the edge. No verdict exists. Treat as `HOLD`. A client-side timeout is the same case.