About Bring Your Own Screening

Bring Your Own Screening holds matching incoming and outgoing transactions until you submit a verdict, ACCEPT or REJECT, based on whatever you choose: a manual review, your own risk logic, or a provider Fireblocks doesn’t integrate with natively. If no verdict arrives before your timeout, Fireblocks rejects the transaction, and that rejection can’t be reversed. It is in Early Access as a premium add-on, available on Developer Sandbox, Testnet, and Mainnet workspaces; contact your Customer Success Manager to join. In the API it is called BYORK Light.

What you can do through the API

Task	Console	API
Read the configuration	No	`GET /screening/byork/config`
Set timeouts	No	`PUT /screening/byork/config/timeouts`
Activate	No	`POST /screening/byork/config/activate`
Deactivate	No	`POST /screening/byork/config/deactivate`
Submit a verdict	No	`POST /screening/byork/verdict`
Check a verdict	No	`GET /screening/byork/verdict?txId={txId}`
Configure the Trigger (pre-screening rules)	No	No: open a support ticket

How it works

Your Trigger (pre-screening rules) decides whether a transaction is held for your verdict (SCREEN) or skips this step (PASS).
A held transaction waits in PENDING_AML_SCREENING. There is no dedicated notification for this step: poll the transaction or watch for its next transaction.status.updated event.
You submit ACCEPT or REJECT. ACCEPT continues the transaction; REJECT or a timeout rejects it with subStatus REJECTED_AML_SCREENING, or AUTO_FREEZE if your policy freezes instead.

Setup

Get the feature enabled by your Customer Success Manager.
Set your timeouts. Leave enough margin for your team or system to respond reliably.

Field	Default	Minimum	Maximum
`incomingTimeoutSeconds`	3600	10	604800 (7 days)
`outgoingTimeoutSeconds`	3600	10	Your access token’s remaining lifetime minus 1800 seconds

Include at least one field. The read, activate, and deactivate responses always show timeoutRangeOutgoing.maxSeconds as 604800, a static upper bound; the response to setting timeouts shows the enforced maximum.
Configure your Trigger (pre-screening rules) by opening a support ticket; see Trigger fields.
Track held transactions by polling or listening for transaction.status.updated.
Test in a sandbox workspace, including how your integration handles a timeout.
Activate. Matching transactions are held from then on. Deactivating pauses the step without removing your configuration; while inactive, every transaction skips it.

After going live, monitor how long your verdicts take against your timeouts. The configuration returns:

{
  "active": false,
  "incomingTimeoutSeconds": 3600,
  "outgoingTimeoutSeconds": 3600,
  "provider": "BYORK_LITE",
  "lastUpdate": "2026-03-01T00:00:00.000Z",
  "timeoutRangeIncoming": { "minSeconds": 10, "maxSeconds": 604800 },
  "timeoutRangeOutgoing": { "minSeconds": 10, "maxSeconds": 604800 }
}

Submit verdicts

Use an Idempotency-Key header to avoid duplicate submissions.

const { data } = await fireblocks.compliance.setByorkVerdict({
  byorkVerdictRequest: { txId, verdict: "ACCEPT" },
  idempotencyKey: `verdict-${txId}`,
});
console.log(data.status, data.message); // "COMPLETED", "Verdict ACCEPT applied"

You can submit a verdict before the transaction reaches the waiting step, for example while AML/KYT is still running. Fireblocks stores it as PRE_ACCEPTED and applies it when the transaction arrives.

Verdict status	Meaning
`PRE_ACCEPTED`	Submitted before the transaction reached the waiting step; applied when it does.
`PENDING`	The transaction is waiting for your verdict.
`RECEIVED`	Your verdict is final and is being applied.
`COMPLETED`	Your verdict is applied, and the transaction continues.

Trigger fields

Rules are evaluated in order; the first match decides. Omitted fields match any value. Fireblocks Support configures them.

Field	Description
`action`	Required. `SCREEN` holds the transaction; `PASS` skips this step.
`direction`	`INBOUND` or `OUTBOUND`.
`sourceType`, `sourceSubType`, `sourceId`, `sourceAddress`	Match on the source, for example `sourceType` `VAULT_ACCOUNT` or `EXCHANGE`.
`destType`, `destSubType`, `destId`, `destAddress`	Match on the destination.
`sourceWorkspaceName`	Source workspace name, for incoming transactions.
`destWorkspaceName`	Destination workspace name, for outgoing transactions.
`asset`	Asset ID, for example `BTC`.
`amount`	`{ "range": { "min": "1000", "max": "50000" }, "currency": "USD" }`. `currency` is `USD` or `NATIVE`; `min` and `max` are optional.
`operation`	Transaction operation type.
`isDefault`	`true` for the rule that applies when no other rule matches.

Errors

Status	Meaning	What to do
`400`	The feature isn’t enabled, or the request is invalid.	Check enablement and the request body.
`404`	No verdict exists for this transaction (check a verdict only).	Check the `txId`, and that the transaction has reached this step.
`409`	A verdict was already submitted, screening is complete, or the screening state is temporarily inconsistent.	If a verdict exists or screening is complete, don’t retry: it’s final. Otherwise, retry after a short delay.
`425`	The transaction isn’t found yet; screening hasn’t started.	Retry after a short delay.

Limitations

A verdict is final, and a timeout rejection can’t be reversed.
No Console flow; the Trigger (pre-screening rules) is set by Fireblocks Support.
Earlier integrations on BYORK Super Light use POST /screening/aml/verdict/manual, which covers incoming transactions only and will be deprecated when Super Light is retired. Use BYORK Light for new integrations.

On the Help Center

For a conceptual overview, see About Bring Your Own Screening.

Get Started

Transactions

API Co-Signers

Webhooks

Workspace & Security

Identity & Compliance

Manage Wallets

Smart Contracts & Tokenization

Treasury & Trading

Gas Management

Payments

Embedded Wallets

Offchain Signing

Direct Custody Wallets

Integrations

Assets & NFTs

Canton

Key Link

What you can do through the API

How it works

Setup

Submit verdicts

Trigger fields

Errors

Limitations

On the Help Center

​What you can do through the API

​How it works

​Setup

​Submit verdicts

​Trigger fields

​Errors

​Limitations

​On the Help Center

What you can do through the API

How it works

Setup

Submit verdicts

Trigger fields

Errors

Limitations

On the Help Center