Documentation Index
Fetch the complete documentation index at: https://developers.fireblocks.com/llms.txt
Use this file to discover all available pages before exploring further.
Bring Your Own Screening Check lets you add a manual review step to Fireblocks transaction screening. After automatic AML screening completes, eligible transactions pause for your verdict before Travel Rule processing begins. For a conceptual overview, see Bring Your Own Screening Check (requires Help Center login).
Quickstart
Follow these steps to set up and activate Bring Your Own Screening Check:
- Contact your Customer Success Manager to enable the feature for your workspace.
- Configure incoming and outgoing timeouts with
PUT /v1/screening/byork/config/timeouts.
- Open a support ticket to configure your pre-screening rules.
- Set up your webhook listener for screening events.
- Test your verdict API integration in the sandbox environment.
- Activate the feature with
POST /v1/screening/byork/config/activate.
- Monitor verdict submission latency against your configured timeouts.
Configuration
Get current configuration
GET /v1/screening/byork/config
Response example
{
"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 }
}
| Field | Type | Description |
|---|
active | boolean | Whether the feature is currently active for your tenant |
incomingTimeoutSeconds | number | Verdict timeout for incoming transactions (seconds) |
outgoingTimeoutSeconds | number | Verdict timeout for outgoing transactions (seconds) |
preScreeningRules | array | Configured pre-screening rules. See Pre-screening rules reference. |
provider | string | Provider identifier (e.g., BYORK_LITE) |
lastUpdate | string | ISO 8601 timestamp of the last configuration update |
timeoutRangeIncoming | object | Valid min/max bounds for incomingTimeoutSeconds |
timeoutRangeOutgoing | object | Valid min/max bounds for outgoingTimeoutSeconds |
Set timeouts
Configure how long the system waits for your verdict before auto-rejecting a transaction. Timeouts are set separately for incoming and outgoing transactions.
Always submit your verdict before the timeout expires. Once the timeout is reached, Fireblocks automatically rejects the transaction and the rejection cannot be reversed.
Request
PUT /v1/screening/byork/config/timeouts
incomingTimeoutSeconds or outgoingTimeoutSeconds in the request body. The response returns the full updated configuration.
Response example
{
"incomingTimeoutSeconds": 7200,
"outgoingTimeoutSeconds": 3600
}
| Parameter | Default | Min | Max |
|---|
incomingTimeoutSeconds | 3600 | 10 | 604800 (7 days) |
outgoingTimeoutSeconds | 3600 | 10 | JWT lifetime − 1800s |
Activate and deactivate
Once your timeouts and rules are set, activate to start screening transactions:
POST /v1/screening/byork/config/activate
POST /v1/screening/byork/config/deactivate
Submitting verdicts
Submit a verdict
POST /v1/screening/byork/verdict
POST verdict to avoid duplicate submissions.
Request body
{
"txId": "3b9cc47a-f8c2-4b09-9b1f-e12a53d9f74c",
"verdict": "ACCEPT"
}
| Field | Type | Description |
|---|
txId | string | Fireblocks transaction ID |
verdict | string | ACCEPT or REJECT |
Response example
{
"status": "COMPLETED",
"message": "Verdict ACCEPT applied"
}
Get verdict status
GET /v1/screening/byork/verdict?txId={txId}
| Status | Description |
|---|
PRE_ACCEPTED | Verdict submitted before the wait step was reached; applied automatically |
PENDING | The transaction is waiting for a verdict |
RECEIVED | Verdict received and being applied |
COMPLETED | Verdict applied; transaction continues |
Pre-acceptance
You can submit a verdict before a transaction reaches the review wait step — for example, while automatic AML screening is still running. Fireblocks stores the verdict and applies it automatically when the transaction reaches the waiting state.
This is useful when you have already completed your own review and want to avoid any delay.
Request
POST /v1/screening/byork/verdict
Response example
{
"txId": "3b9cc47a-f8c2-4b09-9b1f-e12a53d9f74c",
"verdict": "ACCEPT"
}
"status": "PRE_ACCEPTED" if the transaction has not reached the wait step yet.
Error handling
| HTTP status | Meaning | Action |
|---|
400 Bad Request | Bring Your Own Screening Check not enabled for tenant, or invalid payload | Check that the feature is enabled and the request body is correct |
404 Not Found | No verdict found for this transaction (GET only) | Verify txId is correct and the transaction has reached the screening step |
409 Conflict | Verdict already submitted, or transaction screening is complete | Do not retry; verdict is final |
425 Too Early | Transaction not found yet; screening has not started | Retry after a short delay |
Pre-screening rules reference
Rules are evaluated in order. The first matching rule determines whether the transaction is held for review (SCREEN) or bypasses it (PASS).
| Field | Type | Description |
|---|
sourceWorkspaceName | string | Source workspace name. For incoming transactions. |
destWorkspaceName | string | Destination workspace name. For outgoing transactions. |
sourceType | string | Source address type (e.g., VAULT_ACCOUNT, EXCHANGE). |
sourceSubType | string | Source address sub-type. |
sourceAddress | string | Source on-chain address. |
sourceId | string | ID of the source vault, exchange account, or unmanaged wallet. |
destType | string | Destination address type. |
destSubType | string | Destination address sub-type. |
destAddress | string | Destination on-chain address. |
destId | string | ID of the destination vault, exchange account, or unmanaged wallet. |
asset | string | Asset ID (e.g., BTC, ETH). |
amount | object | Amount range with currency. See Amount object. |
operation | string | Transaction operation type. |
direction | string | INBOUND or OUTBOUND. Limits the rule to one direction. |
isDefault | boolean | When true, applies when no other rule matches. |
action | string | Required. PASS (skip review) or SCREEN (hold for verdict). |
Amount object
{
"range": {
"min": "1000",
"max": "50000"
},
"currency": "USD"
}
currency is either "USD" (fiat-equivalent value) or "NATIVE" (on-chain amount). min and max are both optional.