# Update admin quorum threshold
Source: https://developers.fireblocks.com/api-reference/admin-quorum/update-admin-quorum-threshold

https://docs.fireblocks.com/api/v1/swagger.yaml put /admin_quorum
Update admin quorum threshold



# Create API Key
Source: https://developers.fireblocks.com/api-reference/api-user/create-api-key

https://docs.fireblocks.com/api/v1/swagger.yaml post /management/api_users
Create a new API key in your workspace.
Learn more about Fireblocks API Keys management in the following [guide](https://developers.fireblocks.com/docs/manage-api-keys).
Endpoint Permission: Admin, Non-Signing Admin.



# Get API Keys
Source: https://developers.fireblocks.com/api-reference/api-user/get-api-keys

https://docs.fireblocks.com/api/v1/swagger.yaml get /management/api_users
List all API keys in your workspace.
- Please note that this endpoint is available only for API keys with Admin/Non Signing Admin permissions.
Endpoint Permission: Admin, Non-Signing Admin.



# Get audit logs
Source: https://developers.fireblocks.com/api-reference/audit-logs/get-audit-logs

https://docs.fireblocks.com/api/v1/swagger.yaml get /management/audit_logs
Get Audit logs for the last Day/Week.

- Please note that this endpoint is available only for API keys with Admin/Non Signing Admin permissions.
Endpoint Permission: Admin, Non-Signing Admin.



# Get a Blockchain by ID
Source: https://developers.fireblocks.com/api-reference/blockchains-&-assets/get-a-blockchain-by-id

https://docs.fireblocks.com/api/v1/swagger.yaml get /blockchains/{id}
Returns a blockchain by ID or legacyID.




# Get an asset
Source: https://developers.fireblocks.com/api-reference/blockchains-&-assets/get-an-asset

https://docs.fireblocks.com/api/v1/swagger.yaml get /assets/{id}
Returns an asset by ID or legacyID.

**Note**:

  - We will continue displaying and supporting the legacy ID (API ID). Since not all Fireblocks services fully support the new Assets UUID, please use only the legacy ID until further notice.




# List assets
Source: https://developers.fireblocks.com/api-reference/blockchains-&-assets/list-assets

https://docs.fireblocks.com/api/v1/swagger.yaml get /assets
Retrieves a paginated list of all assets supported by Fireblocks in your workspace

**Note:** We will continue to support and display the legacy ID (API ID). Since not all Fireblocks services fully support the new Assets UUID, please use only the legacy ID until further notice.




# List assets (Legacy)
Source: https://developers.fireblocks.com/api-reference/blockchains-&-assets/list-assets-legacy

https://docs.fireblocks.com/api/v1/swagger.yaml get /supported_assets
**This legacy endpoint has not been deprecated but it should not be used in your operations. Instead, use the new [List assets](https://developers.fireblocks.com/reference/listassets) endpoint for better performance and to retrieve more detailed asset information.**

Retrieves all assets supported by Fireblocks in your workspace.

**Endpoint Permissions:** Admin, Non-Signing Admin, Signer, Approver, Editor.




# List blockchains
Source: https://developers.fireblocks.com/api-reference/blockchains-&-assets/list-blockchains

https://docs.fireblocks.com/api/v1/swagger.yaml get /blockchains
Returns all blockchains supported by Fireblocks.




# Register an asset
Source: https://developers.fireblocks.com/api-reference/blockchains-&-assets/register-an-asset

https://docs.fireblocks.com/api/v1/swagger.yaml post /assets
Register a new asset to a workspace and return the newly created asset's details. Currently supported chains are:
- EVM based chains
- Stellar
- Algorand
- TRON
- NEAR
- Solana
- Sui
- TON




# Set asset price
Source: https://developers.fireblocks.com/api-reference/blockchains-&-assets/set-asset-price

https://docs.fireblocks.com/api/v1/swagger.yaml post /assets/prices/{id}
Set asset price for the given asset id. Returns the asset price response.




# Update the user’s metadata for an asset
Source: https://developers.fireblocks.com/api-reference/blockchains-&-assets/update-the-user’s-metadata-for-an-asset

https://docs.fireblocks.com/api/v1/swagger.yaml patch /assets/{id}
Update the user’s metadata for an asset.

Endpoint Permission: Owner, Admin, Non-Signing Admin, NCW Admin, Signer, Editor.



# Get AML Screening Policy Configuration
Source: https://developers.fireblocks.com/api-reference/compliance-screening-configuration/get-aml-screening-policy-configuration

https://docs.fireblocks.com/api/v1/swagger.yaml get /screening/aml/policy_configuration
Retrieves the configuration for Travel Rule screening policy.



# Get Travel Rule Screening Policy Configuration
Source: https://developers.fireblocks.com/api-reference/compliance-screening-configuration/get-travel-rule-screening-policy-configuration

https://docs.fireblocks.com/api/v1/swagger.yaml get /screening/travel_rule/policy_configuration
Retrieves the configuration for Travel Rule screening policy.



# Activate BYORK Light
Source: https://developers.fireblocks.com/api-reference/compliance/activate-byork-light

https://docs.fireblocks.com/api/v1/swagger.yaml post /screening/byork/config/activate
Activates BYORK Light for the authenticated tenant (sets config.active to true). Once activated, BYORK screening applies to matching transactions. Requires BYORK Light to be enabled for the tenant (contact your CSM to enable).



# Add vault accounts to the address registry opt-out list
Source: https://developers.fireblocks.com/api-reference/compliance/add-vault-accounts-to-the-address-registry-opt-out-list

https://docs.fireblocks.com/api/v1/swagger.yaml post /address_registry/vaults
Adds one or more vault account ids to the workspace opt-out list for the address registry.



# AML - View Post-Screening Policy
Source: https://developers.fireblocks.com/api-reference/compliance/aml--view-post-screening-policy

https://docs.fireblocks.com/api/v1/swagger.yaml get /screening/aml/post_screening_policy
Get the post-screening policy for AML.



# AML - View Screening Policy
Source: https://developers.fireblocks.com/api-reference/compliance/aml--view-screening-policy

https://docs.fireblocks.com/api/v1/swagger.yaml get /screening/aml/screening_policy
Get the screening policy for AML.



# Assign vault accounts to a legal entity
Source: https://developers.fireblocks.com/api-reference/compliance/assign-vault-accounts-to-a-legal-entity

https://docs.fireblocks.com/api/v1/swagger.yaml post /legal_entities/{legalEntityId}/vaults
Assigns one or more vault accounts to a specific legal entity registration. Explicitly mapped vault accounts take precedence over the workspace default legal entity.
Endpoint Permission: Admin, Non-Signing Admin.



# Calling the "Bypass Screening Policy" API endpoint triggers a new transaction, with the API user as the initiator, bypassing the screening policy check
Source: https://developers.fireblocks.com/api-reference/compliance/calling-the-"bypass-screening-policy"-api-endpoint-triggers-a-new-transaction-with-the-api-user-as-the-initiator-bypassing-the-screening-policy-check

https://docs.fireblocks.com/api/v1/swagger.yaml post /screening/transaction/{txId}/bypass_screening_policy
This endpoint is restricted to Admin API users and is only applicable to outgoing transactions.



# Create a counterparty group
Source: https://developers.fireblocks.com/api-reference/compliance/create-a-counterparty-group

https://docs.fireblocks.com/api/v1/swagger.yaml post /counterparty_groups
Creates a new counterparty group.

**Endpoint Permissions:** Admin, Non-Signing Admin.




# Deactivate BYORK Light
Source: https://developers.fireblocks.com/api-reference/compliance/deactivate-byork-light

https://docs.fireblocks.com/api/v1/swagger.yaml post /screening/byork/config/deactivate
Deactivates BYORK Light for the authenticated tenant (sets config.active to false). Once deactivated, BYORK screening no longer applies until activated again. Requires BYORK Light to be enabled for the tenant (contact your CSM to enable).



# Delete a counterparty group
Source: https://developers.fireblocks.com/api-reference/compliance/delete-a-counterparty-group

https://docs.fireblocks.com/api/v1/swagger.yaml delete /counterparty_groups/{groupId}
Permanently deletes a counterparty group.

**Endpoint Permissions:** Admin, Non-Signing Admin.




# Get a counterparty group
Source: https://developers.fireblocks.com/api-reference/compliance/get-a-counterparty-group

https://docs.fireblocks.com/api/v1/swagger.yaml get /counterparty_groups/{groupId}
Returns the details of a specific counterparty group.

**Endpoint Permissions:** Admin, Non-Signing Admin, Viewer.




# Get a legal entity
Source: https://developers.fireblocks.com/api-reference/compliance/get-a-legal-entity

https://docs.fireblocks.com/api/v1/swagger.yaml get /legal_entities/{legalEntityId}
Returns details of a specific legal entity registration, including GLEIF data when available.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.



# Get address registry participation status for the authenticated workspace
Source: https://developers.fireblocks.com/api-reference/compliance/get-address-registry-participation-status-for-the-authenticated-workspace

https://docs.fireblocks.com/api/v1/swagger.yaml get /address_registry/tenant
Returns whether the workspace is `OPTED_IN` or `OPTED_OUT` of the address registry.



# Get BYORK Light configuration
Source: https://developers.fireblocks.com/api-reference/compliance/get-byork-light-configuration

https://docs.fireblocks.com/api/v1/swagger.yaml get /screening/byork/config
Retrieves BYORK Light configuration for the authenticated tenant (timeouts, active flag, allowed timeout ranges). Returns default config when none exists. Requires BYORK Light to be enabled for the tenant.



# Get BYORK Light verdict
Source: https://developers.fireblocks.com/api-reference/compliance/get-byork-light-verdict

https://docs.fireblocks.com/api/v1/swagger.yaml get /screening/byork/verdict
Returns the current BYORK verdict and status for a transaction. Status can be PRE_ACCEPTED, PENDING, RECEIVED (verdict is final but processing not yet complete), or COMPLETED. Requires BYORK Light to be enabled for the tenant. Returns 404 if no BYORK verdict is found for the transaction.



# Get whether a vault account is opted out of the address registry
Source: https://developers.fireblocks.com/api-reference/compliance/get-whether-a-vault-account-is-opted-out-of-the-address-registry

https://docs.fireblocks.com/api/v1/swagger.yaml get /address_registry/vaults/{vaultAccountId}
Returns whether this vault account is on the workspace opt-out list (`optedOut` true or false). List, add, and clear-all are available on `/v1/address_registry/vaults`; this path reads or removes one vault.



# List counterparty groups
Source: https://developers.fireblocks.com/api-reference/compliance/list-counterparty-groups

https://docs.fireblocks.com/api/v1/swagger.yaml get /counterparty_groups
Returns a paginated list of counterparty groups.

**Endpoint Permissions:** Admin, Non-Signing Admin, Viewer.




# List legal entities (Paginated)
Source: https://developers.fireblocks.com/api-reference/compliance/list-legal-entities-paginated

https://docs.fireblocks.com/api/v1/swagger.yaml get /legal_entities
Returns legal entity registrations for the workspace with cursor-based pagination.
If query parameter vaultAccountId is used it returns the legal entity registration associated with a specific vault account. If no explicit mapping exists for the vault, the workspace default legal entity is returned. Returns an empty response if neither a vault mapping nor a default legal entity is configured.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.



# List vault accounts for a legal entity (Paginated)
Source: https://developers.fireblocks.com/api-reference/compliance/list-vault-accounts-for-a-legal-entity-paginated

https://docs.fireblocks.com/api/v1/swagger.yaml get /legal_entities/{legalEntityId}/vaults
Returns vault account IDs explicitly assigned to a specific legal entity registration, with cursor-based pagination.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.



# List vault-level address registry opt-outs (paginated)
Source: https://developers.fireblocks.com/api-reference/compliance/list-vault-level-address-registry-opt-outs-paginated

https://docs.fireblocks.com/api/v1/swagger.yaml get /address_registry/vaults
Lists vault accounts that are opted out of the address registry for this workspace. Pagination uses `next` and `prev` cursors from the response. If `pageSize` is omitted, **50** items are returned per page; allowed range is **1–100** per request.



# Look up legal entity by blockchain address
Source: https://developers.fireblocks.com/api-reference/compliance/look-up-legal-entity-by-blockchain-address

https://docs.fireblocks.com/api/v1/swagger.yaml get /address_registry/legal_entities/{address}
Returns legal entity information for the given blockchain address (verification status, LEI, Travel Rule providers, contact email, and related fields — see response schema). URL-encode `{address}` when required.



# Opt the workspace in to the address registry
Source: https://developers.fireblocks.com/api-reference/compliance/opt-the-workspace-in-to-the-address-registry

https://docs.fireblocks.com/api/v1/swagger.yaml post /address_registry/tenant
Opts the workspace in. No request body. Response uses the same JSON shape as GET; status is OPTED_IN.



# Opt the workspace out of the address registry
Source: https://developers.fireblocks.com/api-reference/compliance/opt-the-workspace-out-of-the-address-registry

https://docs.fireblocks.com/api/v1/swagger.yaml delete /address_registry/tenant
Opts the workspace out. No request body. Response uses the same JSON shape as GET; status is OPTED_OUT.



# Provides all the compliance details for the given screened transaction.
Source: https://developers.fireblocks.com/api-reference/compliance/provides-all-the-compliance-details-for-the-given-screened-transaction

https://docs.fireblocks.com/api/v1/swagger.yaml get /screening/transaction/{txId}
Provides all the compliance details for the given screened transaction.



# Register a new legal entity
Source: https://developers.fireblocks.com/api-reference/compliance/register-a-new-legal-entity

https://docs.fireblocks.com/api/v1/swagger.yaml post /legal_entities
Registers a new legal entity for the workspace using its LEI (Legal Entity Identifier) code. The LEI is validated against the GLEIF registry. Each workspace can register multiple legal entities.
Endpoint Permission: Admin, Non-Signing Admin.



# Remove a single vault account from the address registry opt-out list
Source: https://developers.fireblocks.com/api-reference/compliance/remove-a-single-vault-account-from-the-address-registry-opt-out-list

https://docs.fireblocks.com/api/v1/swagger.yaml delete /address_registry/vaults/{vaultAccountId}
Removes this vault account id from the workspace opt-out list if it is present; otherwise the call still succeeds. Response body matches GET (`optedOut` is `false` after success). To clear the whole list, use `DELETE /v1/address_registry/vaults`.



# Remove all vault-level address registry opt-outs for the workspace
Source: https://developers.fireblocks.com/api-reference/compliance/remove-all-vault-level-address-registry-opt-outs-for-the-workspace

https://docs.fireblocks.com/api/v1/swagger.yaml delete /address_registry/vaults
Removes all vault accounts from the workspace opt-out list.



# Set AML Verdict (BYORK Super Light)
Source: https://developers.fireblocks.com/api-reference/compliance/set-aml-verdict-byork-super-light

https://docs.fireblocks.com/api/v1/swagger.yaml post /screening/aml/verdict/manual
Set AML verdict for incoming transactions when **BYORK Super Light** (Manual Screening Verdict) is enabled. This endpoint is for Super Light only. For **BYORK Light**, use POST /screening/byork/verdict instead. When Super Light is retired, this endpoint will be deprecated; use the BYORK Light verdict API for new integrations.



# Set BYORK Light timeouts
Source: https://developers.fireblocks.com/api-reference/compliance/set-byork-light-timeouts

https://docs.fireblocks.com/api/v1/swagger.yaml put /screening/byork/config/timeouts
Updates timeout values for BYORK wait-for-response (incoming and/or outgoing). At least one of incomingTimeoutSeconds or outgoingTimeoutSeconds is required. Values must be within the ranges returned in GET config (timeoutRangeIncoming for incomingTimeoutSeconds, timeoutRangeOutgoing for outgoingTimeoutSeconds). Requires BYORK Light to be enabled for the tenant (contact your CSM to enable).



# Set BYORK Light verdict
Source: https://developers.fireblocks.com/api-reference/compliance/set-byork-light-verdict

https://docs.fireblocks.com/api/v1/swagger.yaml post /screening/byork/verdict
Submit verdict (ACCEPT or REJECT) for a transaction in the BYORK Light flow. If the transaction is awaiting your decision, the verdict is applied immediately (response status COMPLETED). If processing has not yet reached that point, the verdict is stored and applied when it does (response status PRE_ACCEPTED). Requires BYORK Light to be enabled for the tenant.



# Tenant - Screening Configuration
Source: https://developers.fireblocks.com/api-reference/compliance/tenant--screening-configuration

https://docs.fireblocks.com/api/v1/swagger.yaml put /screening/configurations
Update tenant screening configuration.



# Travel Rule - View Post-Screening Policy
Source: https://developers.fireblocks.com/api-reference/compliance/travel-rule--view-post-screening-policy

https://docs.fireblocks.com/api/v1/swagger.yaml get /screening/travel_rule/post_screening_policy
Get the post-screening policy for Travel Rule.



# Travel Rule - View Screening Policy
Source: https://developers.fireblocks.com/api-reference/compliance/travel-rule--view-screening-policy

https://docs.fireblocks.com/api/v1/swagger.yaml get /screening/travel_rule/screening_policy
Get the screening policy for Travel Rule.



# Update a counterparty group
Source: https://developers.fireblocks.com/api-reference/compliance/update-a-counterparty-group

https://docs.fireblocks.com/api/v1/swagger.yaml patch /counterparty_groups/{groupId}
Updates an existing counterparty group.

**Endpoint Permissions:** Admin, Non-Signing Admin.




# Update AML Configuration
Source: https://developers.fireblocks.com/api-reference/compliance/update-aml-configuration

https://docs.fireblocks.com/api/v1/swagger.yaml put /screening/aml/policy_configuration
Updates bypass screening, inbound delay, or outbound delay configurations for AML.



# Update legal entity
Source: https://developers.fireblocks.com/api-reference/compliance/update-legal-entity

https://docs.fireblocks.com/api/v1/swagger.yaml put /legal_entities/{legalEntityId}
Updates the status of a legal entity registration. Setting isDefault to true marks the registration as the workspace default, which is applied to vault accounts that have no explicit legal entity mapping.
Endpoint Permission: Admin, Non-Signing Admin.



# Update Travel Rule Configuration
Source: https://developers.fireblocks.com/api-reference/compliance/update-travel-rule-configuration

https://docs.fireblocks.com/api/v1/swagger.yaml put /screening/travel_rule/policy_configuration
Updates bypass screening, inbound delay, or outbound delay configurations for Travel Rule.



# Disconnect connected account
Source: https://developers.fireblocks.com/api-reference/connected-accounts-beta/disconnect-connected-account

https://docs.fireblocks.com/api/v1/swagger.yaml delete /connected_accounts/{accountId}
Disconnect a connected account by ID.

**Note**:
- This endpoint is currently in beta and might be subject to changes.




# Get balances for an account
Source: https://developers.fireblocks.com/api-reference/connected-accounts-beta/get-balances-for-an-account

https://docs.fireblocks.com/api/v1/swagger.yaml get /connected_accounts/{accountId}/balances
Retrieve current asset balances for a specific connected account as a flat list (one row per `assetId`, `balanceType`).

**Note:** This endpoint is currently in beta and might be subject to changes.




# Get connected account
Source: https://developers.fireblocks.com/api-reference/connected-accounts-beta/get-connected-account

https://docs.fireblocks.com/api/v1/swagger.yaml get /connected_accounts/{accountId}
Retrieve detailed information about a specific connected account by ID.

**Note:** This endpoint is currently in beta and might be subject to changes.




# Get connected accounts
Source: https://developers.fireblocks.com/api-reference/connected-accounts-beta/get-connected-accounts

https://docs.fireblocks.com/api/v1/swagger.yaml get /connected_accounts
Returns all connected accounts.

**Note:** This endpoint is currently in beta and might be subject to changes.




# Get exchange rates for an account
Source: https://developers.fireblocks.com/api-reference/connected-accounts-beta/get-exchange-rates-for-an-account

https://docs.fireblocks.com/api/v1/swagger.yaml get /connected_accounts/{accountId}/rates
Retrieve current exchange rates for converting between specific assets in a connected account.

**Note:** This endpoint is currently in beta and might be subject to changes.




# Get supported trading pairs for an account
Source: https://developers.fireblocks.com/api-reference/connected-accounts-beta/get-supported-trading-pairs-for-an-account

https://docs.fireblocks.com/api/v1/swagger.yaml get /connected_accounts/{accountId}/manifest/capabilities/trading/pairs
Retrieve all asset trading pairs supported by a specific connected account, including the pair type (`quote`, `market`, `onOffRamp`).

**Note:** This endpoint is currently in beta and might be subject to changes.




# Rename Connected Account
Source: https://developers.fireblocks.com/api-reference/connected-accounts-beta/rename-connected-account

https://docs.fireblocks.com/api/v1/swagger.yaml post /connected_accounts/{accountId}/rename
Rename a connected account by account ID.

**Note:** This endpoint is currently in beta and might be subject to changes.




# Create console user
Source: https://developers.fireblocks.com/api-reference/console-user/create-console-user

https://docs.fireblocks.com/api/v1/swagger.yaml post /management/users
Create console users in your workspace
- Please note that this endpoint is available only for API keys with Admin/Non Signing Admin permissions.
Learn more about Fireblocks Users management in the following [guide](https://developers.fireblocks.com/docs/manage-users).
Endpoint Permission: Admin, Non-Signing Admin.



# Get console users
Source: https://developers.fireblocks.com/api-reference/console-user/get-console-users

https://docs.fireblocks.com/api/v1/swagger.yaml get /management/users
Get console users for your workspace.
- Please note that this endpoint is available only for API keys with Admin/Non Signing Admin permissions.
Endpoint Permission: Admin, Non-Signing Admin.



# Call a read function on a deployed contract
Source: https://developers.fireblocks.com/api-reference/contract-interactions/call-a-read-function-on-a-deployed-contract

https://docs.fireblocks.com/api/v1/swagger.yaml post /contract_interactions/base_asset_id/{baseAssetId}/contract_address/{contractAddress}/functions/read
Call a read function on a deployed contract by blockchain native asset id and contract address



# Call a write function on a deployed contract
Source: https://developers.fireblocks.com/api-reference/contract-interactions/call-a-write-function-on-a-deployed-contract

https://docs.fireblocks.com/api/v1/swagger.yaml post /contract_interactions/base_asset_id/{baseAssetId}/contract_address/{contractAddress}/functions/write
Call a write function on a deployed contract by blockchain native asset id and contract address. This creates an onchain transaction, thus it is an async operation. It returns a transaction id that can be polled for status check



# Decode a function call data, error, or event log
Source: https://developers.fireblocks.com/api-reference/contract-interactions/decode-a-function-call-data-error-or-event-log

https://docs.fireblocks.com/api/v1/swagger.yaml post /contract_interactions/base_asset_id/{baseAssetId}/contract_address/{contractAddress}/decode
Decode a function call data, error, or event log from a deployed contract by blockchain native asset id and contract address.



# Get contract address by transaction hash
Source: https://developers.fireblocks.com/api-reference/contract-interactions/get-contract-address-by-transaction-hash

https://docs.fireblocks.com/api/v1/swagger.yaml get /contract_interactions/base_asset_id/{baseAssetId}/tx_hash/{txHash}
Retrieve the contract address by blockchain native asset ID and transaction hash



# Get transaction receipt
Source: https://developers.fireblocks.com/api-reference/contract-interactions/get-transaction-receipt

https://docs.fireblocks.com/api/v1/swagger.yaml get /contract_interactions/base_asset_id/{baseAssetId}/tx_hash/{txHash}/receipt
Retrieve the transaction receipt by blockchain native asset ID and transaction hash
> **Note** > This functionality is exclusively available for EVM (Ethereum Virtual Machine) compatible chains. 
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, and Viewer.



# Return deployed contract's ABI
Source: https://developers.fireblocks.com/api-reference/contract-interactions/return-deployed-contracts-abi

https://docs.fireblocks.com/api/v1/swagger.yaml get /contract_interactions/base_asset_id/{baseAssetId}/contract_address/{contractAddress}/functions
Return deployed contract's ABI by blockchain native asset id and contract address.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, and Viewer.



# Delete a contract template by id
Source: https://developers.fireblocks.com/api-reference/contract-templates/delete-a-contract-template-by-id

https://docs.fireblocks.com/api/v1/swagger.yaml delete /tokenization/templates/{contractTemplateId}
Delete a contract by id. allowed only for private contract templates. Notice: it is irreversible!



# Deploy contract
Source: https://developers.fireblocks.com/api-reference/contract-templates/deploy-contract

https://docs.fireblocks.com/api/v1/swagger.yaml post /tokenization/templates/{contractTemplateId}/deploy
Deploy a new contract by contract template id. If you wish to deploy a token (ERC20, ERC721 etc), and create asset please use POST /tokenization



# Get supported blockchains for the template
Source: https://developers.fireblocks.com/api-reference/contract-templates/get-supported-blockchains-for-the-template

https://docs.fireblocks.com/api/v1/swagger.yaml get /tokenization/templates/{contractTemplateId}/supported_blockchains
Get supported blockchains for the template



# List all contract templates
Source: https://developers.fireblocks.com/api-reference/contract-templates/list-all-contract-templates

https://docs.fireblocks.com/api/v1/swagger.yaml get /tokenization/templates
Return minimal representation of all the contract templates available for the workspace.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.



# Return contract template by id
Source: https://developers.fireblocks.com/api-reference/contract-templates/return-contract-template-by-id

https://docs.fireblocks.com/api/v1/swagger.yaml get /tokenization/templates/{contractTemplateId}
Return detailed information about the contract template



# Return contract template's constructor
Source: https://developers.fireblocks.com/api-reference/contract-templates/return-contract-templates-constructor

https://docs.fireblocks.com/api/v1/swagger.yaml get /tokenization/templates/{contractTemplateId}/constructor
Return contract template's constructor ABI



# Return contract template's function
Source: https://developers.fireblocks.com/api-reference/contract-templates/return-contract-templates-function

https://docs.fireblocks.com/api/v1/swagger.yaml get /tokenization/templates/{contractTemplateId}/function
Return contract template`s function ABI by signature



# Upload contract template
Source: https://developers.fireblocks.com/api-reference/contract-templates/upload-contract-template

https://docs.fireblocks.com/api/v1/swagger.yaml post /tokenization/templates
Upload a new contract template. This contract template will be available for the workspace



# Add a contract
Source: https://developers.fireblocks.com/api-reference/contracts/add-a-contract

https://docs.fireblocks.com/api/v1/swagger.yaml post /contracts
Adds a contract to the workspace whitelist. Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Add an asset to a whitelisted contract
Source: https://developers.fireblocks.com/api-reference/contracts/add-an-asset-to-a-whitelisted-contract

https://docs.fireblocks.com/api/v1/swagger.yaml post /contracts/{contractId}/{assetId}
Adds an asset to a whitelisted contract. Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Delete a contract
Source: https://developers.fireblocks.com/api-reference/contracts/delete-a-contract

https://docs.fireblocks.com/api/v1/swagger.yaml delete /contracts/{contractId}
Deletes a contract by ID. Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Delete an asset from a whitelisted contract
Source: https://developers.fireblocks.com/api-reference/contracts/delete-an-asset-from-a-whitelisted-contract

https://docs.fireblocks.com/api/v1/swagger.yaml delete /contracts/{contractId}/{assetId}
Deletes a whitelisted contract asset by ID. Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Find a Specific Whitelisted Contract
Source: https://developers.fireblocks.com/api-reference/contracts/find-a-specific-whitelisted-contract

https://docs.fireblocks.com/api/v1/swagger.yaml get /contracts/{contractId}
Returns a whitelisted contract by Fireblocks Contract ID. Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Find a whitelisted contract's asset
Source: https://developers.fireblocks.com/api-reference/contracts/find-a-whitelisted-contracts-asset

https://docs.fireblocks.com/api/v1/swagger.yaml get /contracts/{contractId}/{assetId}
Returns a whitelisted contract's asset by ID. Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# List Whitelisted Contracts
Source: https://developers.fireblocks.com/api-reference/contracts/list-whitelisted-contracts

https://docs.fireblocks.com/api/v1/swagger.yaml get /contracts
Gets a list of whitelisted contracts. Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.



# Add cosigner
Source: https://developers.fireblocks.com/api-reference/cosigners-beta/add-cosigner

https://docs.fireblocks.com/api/v1/swagger.yaml post /cosigners
Add a new cosigner. The cosigner will be pending pairing until the API key is manually paired
Endpoint Permission: Admin and Non-Signing Admin.



# Get all API keys
Source: https://developers.fireblocks.com/api-reference/cosigners-beta/get-all-api-keys

https://docs.fireblocks.com/api/v1/swagger.yaml get /cosigners/{cosignerId}/api_keys
Get all cosigner paired API keys (paginated).
**Note:** These endpoints are currently in beta and might be subject to changes.
Endpoint Permission: Admin and Non-Signing Admin.



# Get all cosigners
Source: https://developers.fireblocks.com/api-reference/cosigners-beta/get-all-cosigners

https://docs.fireblocks.com/api/v1/swagger.yaml get /cosigners
Get all workspace cosigners (paginated).
**Note:** These endpoints are currently in beta and might be subject to changes.
Endpoint Permission: Admin and Non-Signing Admin.



# Get API key
Source: https://developers.fireblocks.com/api-reference/cosigners-beta/get-api-key

https://docs.fireblocks.com/api/v1/swagger.yaml get /cosigners/{cosignerId}/api_keys/{apiKeyId}
Get an API key by ID.
**Note:** These endpoints are currently in beta and might be subject to changes.
Endpoint Permission: Admin and Non-Signing Admin.



# Get cosigner
Source: https://developers.fireblocks.com/api-reference/cosigners-beta/get-cosigner

https://docs.fireblocks.com/api/v1/swagger.yaml get /cosigners/{cosignerId}
Get a cosigner by ID.
**Note:** These endpoints are currently in beta and might be subject to changes.
Endpoint Permission: Admin and Non-Signing Admin.



# Get request status
Source: https://developers.fireblocks.com/api-reference/cosigners-beta/get-request-status

https://docs.fireblocks.com/api/v1/swagger.yaml get /cosigners/{cosignerId}/api_keys/{apiKeyId}/{requestId}
Get the status of an asynchronous request
Endpoint Permission: Admin and Non-Signing Admin.



# Pair API key
Source: https://developers.fireblocks.com/api-reference/cosigners-beta/pair-api-key

https://docs.fireblocks.com/api/v1/swagger.yaml put /cosigners/{cosignerId}/api_keys/{apiKeyId}
Pair an API key to a cosigner
Endpoint Permission: Admin and Non-Signing Admin.



# Rename cosigner
Source: https://developers.fireblocks.com/api-reference/cosigners-beta/rename-cosigner

https://docs.fireblocks.com/api/v1/swagger.yaml patch /cosigners/{cosignerId}
Rename a cosigner by ID.
**Note:** These endpoints are currently in beta and might be subject to changes.
Endpoint Permission: Admin and Non-Signing Admin.



# Unpair API key
Source: https://developers.fireblocks.com/api-reference/cosigners-beta/unpair-api-key

https://docs.fireblocks.com/api/v1/swagger.yaml delete /cosigners/{cosignerId}/api_keys/{apiKeyId}
Unpair an API key from a cosigner
Endpoint Permission: Admin and Non-Signing Admin.



# Update API key callback handler
Source: https://developers.fireblocks.com/api-reference/cosigners-beta/update-api-key-callback-handler

https://docs.fireblocks.com/api/v1/swagger.yaml patch /cosigners/{cosignerId}/api_keys/{apiKeyId}
Update the callback handler of an API key
Endpoint Permission: Admin and Non-Signing Admin.



# Fetch the contract ABI
Source: https://developers.fireblocks.com/api-reference/deployed-contracts/fetch-the-contract-abi

https://docs.fireblocks.com/api/v1/swagger.yaml post /tokenization/contracts/fetch_abi
Fetch the ABI. If not found fetch the ABI from the block explorer



# List deployed contracts data
Source: https://developers.fireblocks.com/api-reference/deployed-contracts/list-deployed-contracts-data

https://docs.fireblocks.com/api/v1/swagger.yaml get /tokenization/contracts
Return a filtered lean representation of the deployed contracts data on all blockchains (paginated)



# Return deployed contract data
Source: https://developers.fireblocks.com/api-reference/deployed-contracts/return-deployed-contract-data

https://docs.fireblocks.com/api/v1/swagger.yaml get /tokenization/contracts/{assetId}/{contractAddress}
Return deployed contract data by blockchain native asset id and contract address



# Return deployed contract data by id
Source: https://developers.fireblocks.com/api-reference/deployed-contracts/return-deployed-contract-data-by-id

https://docs.fireblocks.com/api/v1/swagger.yaml get /tokenization/contracts/{id}
Return deployed contract data by id



# Save contract ABI
Source: https://developers.fireblocks.com/api-reference/deployed-contracts/save-contract-abi

https://docs.fireblocks.com/api/v1/swagger.yaml post /tokenization/contracts/abi
Save contract ABI for the tenant



# Approve earn provider terms of service
Source: https://developers.fireblocks.com/api-reference/earn-beta/approve-earn-provider-terms-of-service

https://docs.fireblocks.com/api/v1/swagger.yaml post /earn/providers/{providerId}/approve_terms_of_service
Approves the lending provider's terms of service for this workspace. When
`isTermsApprovalRequired` is true on the provider (see list providers),
call this once before creating or executing earn actions with that provider.
After success, `GET /earn/providers` reflects `isTermsOfServiceApproved`.

**Note:** This endpoint is currently in beta and might be subject to changes.




# Create and execute a lending action (deposit or withdraw)
Source: https://developers.fireblocks.com/api-reference/earn-beta/create-and-execute-a-lending-action-deposit-or-withdraw

https://docs.fireblocks.com/api/v1/swagger.yaml post /earn/actions
Creates and runs a sequence of on-chain steps for either a deposit into or a withdrawal from an earn
vault/market. Specify the operation with `action` in the request body (`DEPOSIT` or `WITHDRAW`).

**Note:** This endpoint is currently in beta and might be subject to changes.




# Get a single earn lending action
Source: https://developers.fireblocks.com/api-reference/earn-beta/get-a-single-earn-lending-action

https://docs.fireblocks.com/api/v1/swagger.yaml get /earn/actions/{id}
Returns one lending action by its action sequence id (tenant-scoped).

**Note:** This endpoint is currently in beta and might be subject to changes.




# Get list of earn opportunities
Source: https://developers.fireblocks.com/api-reference/earn-beta/get-list-of-earn-opportunities

https://docs.fireblocks.com/api/v1/swagger.yaml get /earn/opportunities
Get list of earn opportunities (vaults).

**Note:** This endpoint is currently in beta and might be subject to changes.




# Get list of earn positions
Source: https://developers.fireblocks.com/api-reference/earn-beta/get-list-of-earn-positions

https://docs.fireblocks.com/api/v1/swagger.yaml get /earn/positions
Get list of earn positions for accounts tracked for this workspace. 
Optional query parameters filter by chain, provider, and pagination.

**Note:** This endpoint is currently in beta and might be subject to changes.




# Get list of earn providers
Source: https://developers.fireblocks.com/api-reference/earn-beta/get-list-of-earn-providers

https://docs.fireblocks.com/api/v1/swagger.yaml get /earn/providers
Get list of earn providers.

**Note:** This endpoint is currently in beta and might be subject to changes.




# List earn lending actions
Source: https://developers.fireblocks.com/api-reference/earn-beta/list-earn-lending-actions

https://docs.fireblocks.com/api/v1/swagger.yaml get /earn/actions
Returns a paginated list of lending actions (deposits and withdrawals) for the authenticated tenant.

**Note:** This endpoint is currently in beta and might be subject to changes.




# Add asset to account
Source: https://developers.fireblocks.com/api-reference/embedded-wallets/add-asset-to-account

https://docs.fireblocks.com/api/v1/swagger.yaml post /ncw/wallets/{walletId}/accounts/{accountId}/assets/{assetId}
Get the addresses of a specific asset, under a specific account, under a specific Non Custodial Wallet



# Assign a wallet
Source: https://developers.fireblocks.com/api-reference/embedded-wallets/assign-a-wallet

https://docs.fireblocks.com/api/v1/swagger.yaml post /ncw/wallets/{walletId}/assign
Assign a specific Non Custodial Wallet to a user



# Create a new account
Source: https://developers.fireblocks.com/api-reference/embedded-wallets/create-a-new-account

https://docs.fireblocks.com/api/v1/swagger.yaml post /ncw/wallets/{walletId}/accounts
Create a new account under a specific Non Custodial Wallet



# Create a new wallet
Source: https://developers.fireblocks.com/api-reference/embedded-wallets/create-a-new-wallet

https://docs.fireblocks.com/api/v1/swagger.yaml post /ncw/wallets
Create new Non Custodial Wallet



# Get a account
Source: https://developers.fireblocks.com/api-reference/embedded-wallets/get-a-account

https://docs.fireblocks.com/api/v1/swagger.yaml get /ncw/wallets/{walletId}/accounts/{accountId}
Get a specific account under a specific Non Custodial Wallet



# Get a wallet
Source: https://developers.fireblocks.com/api-reference/embedded-wallets/get-a-wallet

https://docs.fireblocks.com/api/v1/swagger.yaml get /ncw/wallets/{walletId}
Get a wallet



# Get device key setup state
Source: https://developers.fireblocks.com/api-reference/embedded-wallets/get-device-key-setup-state

https://docs.fireblocks.com/api/v1/swagger.yaml get /ncw/wallets/{walletId}/devices/{deviceId}/setup_status
Get the state of the specific device setup key under a specific Non Custodial Wallet



# Get Embedded Wallet Device
Source: https://developers.fireblocks.com/api-reference/embedded-wallets/get-embedded-wallet-device

https://docs.fireblocks.com/api/v1/swagger.yaml get /ncw/wallets/{walletId}/devices/{deviceId}
Get specific device for a specific s Wallet



# Get registered devices - paginated
Source: https://developers.fireblocks.com/api-reference/embedded-wallets/get-registered-devices--paginated

https://docs.fireblocks.com/api/v1/swagger.yaml get /ncw/wallets/{walletId}/devices_paginated
Get a paginated list of registered devices for a specific Non Custodial Wallet



# Get the public key for a derivation path
Source: https://developers.fireblocks.com/api-reference/embedded-wallets/get-the-public-key-for-a-derivation-path

https://docs.fireblocks.com/api/v1/swagger.yaml get /ncw/wallets/{walletId}/public_key_info
Gets the public key information based on derivation path and signing algorithm within a Non-Custodial Wallet



# Get the public key of an asset
Source: https://developers.fireblocks.com/api-reference/embedded-wallets/get-the-public-key-of-an-asset

https://docs.fireblocks.com/api/v1/swagger.yaml get /ncw/wallets/{walletId}/accounts/{accountId}/assets/{assetId}/{change}/{addressIndex}/public_key_info
Gets the public key of an asset associated with a specific account within a Non-Custodial Wallet



# Get the public key of an asset
Source: https://developers.fireblocks.com/api-reference/embedded-wallets/get-the-public-key-of-an-asset-1

https://docs.fireblocks.com/api/v1/swagger.yaml get /ncw/{walletId}/accounts/{accountId}/{assetId}/{change}/{addressIndex}/public_key_info
Gets the public key of an asset associated with a specific account within a Non-Custodial Wallet



# Get wallet key setup state
Source: https://developers.fireblocks.com/api-reference/embedded-wallets/get-wallet-key-setup-state

https://docs.fireblocks.com/api/v1/swagger.yaml get /ncw/wallets/{walletId}/setup_status
Get the key setup state for a specific Non Custodial Wallet, including required algorithms and device setup status



# Get wallet Latest Backup details
Source: https://developers.fireblocks.com/api-reference/embedded-wallets/get-wallet-latest-backup-details

https://docs.fireblocks.com/api/v1/swagger.yaml get /ncw/wallets/{walletId}/backup/latest
Get wallet Latest Backup details, including the deviceId, and backup time



# List wallets
Source: https://developers.fireblocks.com/api-reference/embedded-wallets/list-wallets

https://docs.fireblocks.com/api/v1/swagger.yaml get /ncw/wallets
Get all Non Custodial Wallets



# Refresh asset balance
Source: https://developers.fireblocks.com/api-reference/embedded-wallets/refresh-asset-balance

https://docs.fireblocks.com/api/v1/swagger.yaml put /ncw/wallets/{walletId}/accounts/{accountId}/assets/{assetId}/balance
Refresh the balance of an asset in a specific account



# Retrieve asset
Source: https://developers.fireblocks.com/api-reference/embedded-wallets/retrieve-asset

https://docs.fireblocks.com/api/v1/swagger.yaml get /ncw/wallets/{walletId}/accounts/{accountId}/assets/{assetId}
Get asset under a specific account, under a specific Non Custodial Wallet



# Retrieve asset addresses
Source: https://developers.fireblocks.com/api-reference/embedded-wallets/retrieve-asset-addresses

https://docs.fireblocks.com/api/v1/swagger.yaml get /ncw/wallets/{walletId}/accounts/{accountId}/assets/{assetId}/addresses
Get the addresses of a specific asset, under a specific account, under a specific Non Custodial Wallet



# Retrieve asset balance
Source: https://developers.fireblocks.com/api-reference/embedded-wallets/retrieve-asset-balance

https://docs.fireblocks.com/api/v1/swagger.yaml get /ncw/wallets/{walletId}/accounts/{accountId}/assets/{assetId}/balance
Get balance for specific asset, under a specific account



# Retrieve assets
Source: https://developers.fireblocks.com/api-reference/embedded-wallets/retrieve-assets

https://docs.fireblocks.com/api/v1/swagger.yaml get /ncw/wallets/{walletId}/accounts/{accountId}/assets
Retrieve assets for a specific account under a specific Non Custodial Wallet



# Retrieve supported assets
Source: https://developers.fireblocks.com/api-reference/embedded-wallets/retrieve-supported-assets

https://docs.fireblocks.com/api/v1/swagger.yaml get /ncw/wallets/supported_assets
Get all the available supported assets for the Non-Custodial Wallet



# Update device status
Source: https://developers.fireblocks.com/api-reference/embedded-wallets/update-device-status

https://docs.fireblocks.com/api/v1/swagger.yaml patch /ncw/wallets/{walletId}/devices/{deviceId}/status
Update the enabled/disabled status of a specific device for a Non Custodial Wallet



# Update wallet status
Source: https://developers.fireblocks.com/api-reference/embedded-wallets/update-wallet-status

https://docs.fireblocks.com/api/v1/swagger.yaml patch /ncw/wallets/{walletId}/status
Update the enabled/disabled status of a specific Non Custodial Wallet



# Add an exchange account
Source: https://developers.fireblocks.com/api-reference/exchange-accounts/add-an-exchange-account

https://docs.fireblocks.com/api/v1/swagger.yaml post /exchange_accounts
Add an exchange account to exchanges. 

Note: This endpoint currently only supports the following exchanges `INDEPENDENT_RESERVE`,`BIT`, `BITHUMB`, `BITSO`, `CRYPTOCOM`, `BYBIT_V2`, `WHITEBIT`, `HITBTC`, `GEMINI`, `HUOBI`, `GATEIO`, `COINHAKO`, `BULLISH`, `BITGET`, and `LUNO`

To add an exchange account, please use the following [guide](https://developers.fireblocks.com/docs/add-an-exchange-account).




# Convert exchange account funds
Source: https://developers.fireblocks.com/api-reference/exchange-accounts/convert-exchange-account-funds

https://docs.fireblocks.com/api/v1/swagger.yaml post /exchange_accounts/{exchangeAccountId}/convert
Convert exchange account funds from the source asset to the destination asset. Coinbase (USD to USDC, USDC to USD) and Bitso (MXN to USD) are supported conversions.
Learn more about Fireblocks Exchange Connectivity in the following [guide](https://developers.fireblocks.com/docs/connect-to-exchanges-and-fiat-providers).
Endpoint Permission: Admin, Non-Signing Admin.



# Get a specific exchange account
Source: https://developers.fireblocks.com/api-reference/exchange-accounts/get-a-specific-exchange-account

https://docs.fireblocks.com/api/v1/swagger.yaml get /exchange_accounts/{exchangeAccountId}
Returns an exchange account by ID.
Endpoint Permission: Admin, Non-Signing Admin.



# Get an asset for an exchange account
Source: https://developers.fireblocks.com/api-reference/exchange-accounts/get-an-asset-for-an-exchange-account

https://docs.fireblocks.com/api/v1/swagger.yaml get /exchange_accounts/{exchangeAccountId}/{assetId}
Returns an asset for an exchange account.
Endpoint Permission: Admin, Non-Signing Admin.



# Get public key to encrypt exchange credentials
Source: https://developers.fireblocks.com/api-reference/exchange-accounts/get-public-key-to-encrypt-exchange-credentials

https://docs.fireblocks.com/api/v1/swagger.yaml get /exchange_accounts/credentials_public_key
Return public key



# Internal transfer for exchange accounts
Source: https://developers.fireblocks.com/api-reference/exchange-accounts/internal-transfer-for-exchange-accounts

https://docs.fireblocks.com/api/v1/swagger.yaml post /exchange_accounts/{exchangeAccountId}/internal_transfer
Transfers funds between trading accounts under the same exchange account.
Learn more about Fireblocks Exchange Connectivity in the following [guide](https://developers.fireblocks.com/docs/connect-to-exchanges-and-fiat-providers).
Endpoint Permission: Admin, Non-Signing Admin.



# List connected exchange accounts
Source: https://developers.fireblocks.com/api-reference/exchange-accounts/list-connected-exchange-accounts

https://docs.fireblocks.com/api/v1/swagger.yaml get /exchange_accounts/paged
Returns a list of the connected exchange accounts in your workspace. Endpoint Permission: Admin, Non-Signing Admin.



# List exchange accounts
Source: https://developers.fireblocks.com/api-reference/exchange-accounts/list-exchange-accounts

https://docs.fireblocks.com/api/v1/swagger.yaml get /exchange_accounts
DEPRECATED - Please use the `/exchange_accounts/paged` endpoint.
Endpoint Permission: Admin, Non-Signing Admin.



# Add an asset to an external wallet.
Source: https://developers.fireblocks.com/api-reference/external-wallets/add-an-asset-to-an-external-wallet

https://docs.fireblocks.com/api/v1/swagger.yaml post /external_wallets/{walletId}/{assetId}
Adds an asset to an existing external wallet. Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Create an external wallet
Source: https://developers.fireblocks.com/api-reference/external-wallets/create-an-external-wallet

https://docs.fireblocks.com/api/v1/swagger.yaml post /external_wallets
Creates a new external wallet with the requested name.

External Wallet is a whitelisted address of a wallet that belongs to your users/counterparties.

- You cannot see the balance of the external wallet.
- You cannot initiate transactions from an external wallet as the source via Fireblocks.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Delete an asset from an external wallet
Source: https://developers.fireblocks.com/api-reference/external-wallets/delete-an-asset-from-an-external-wallet

https://docs.fireblocks.com/api/v1/swagger.yaml delete /external_wallets/{walletId}/{assetId}
Deletes an external wallet asset by ID. Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Delete an external wallet
Source: https://developers.fireblocks.com/api-reference/external-wallets/delete-an-external-wallet

https://docs.fireblocks.com/api/v1/swagger.yaml delete /external_wallets/{walletId}
Deletes an external wallet by ID. External Wallet is a whitelisted address of a wallet that belongs to your users/counterparties. Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Find an external wallet
Source: https://developers.fireblocks.com/api-reference/external-wallets/find-an-external-wallet

https://docs.fireblocks.com/api/v1/swagger.yaml get /external_wallets/{walletId}
Returns an external wallet by ID. External Wallet is a whitelisted address of a wallet that belongs to your users/counterparties. Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.



# Get an asset from an external wallet
Source: https://developers.fireblocks.com/api-reference/external-wallets/get-an-asset-from-an-external-wallet

https://docs.fireblocks.com/api/v1/swagger.yaml get /external_wallets/{walletId}/{assetId}
Returns an external wallet by wallet ID and asset ID. External Wallet is a whitelisted address of a wallet that belongs to your users/counterparties. Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.



# List external wallets
Source: https://developers.fireblocks.com/api-reference/external-wallets/list-external-wallets

https://docs.fireblocks.com/api/v1/swagger.yaml get /external_wallets
Gets a list of external wallets under the workspace.

External Wallet is a whitelisted address of a wallet that belongs to your users/counterparties.

- You cannot see the balance of the external wallet.
- You cannot initiate transactions from an external wallet as the source via Fireblocks.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.



# Set an AML customer reference ID for an external wallet
Source: https://developers.fireblocks.com/api-reference/external-wallets/set-an-aml-customer-reference-id-for-an-external-wallet

https://docs.fireblocks.com/api/v1/swagger.yaml post /external_wallets/{walletId}/set_customer_ref_id
Sets an AML/KYT customer reference ID for the specific external wallet. External Wallet is a whitelisted address of a wallet that belongs to your users/counterparties. Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Deposit funds from DDA
Source: https://developers.fireblocks.com/api-reference/fiat-accounts/deposit-funds-from-dda

https://docs.fireblocks.com/api/v1/swagger.yaml post /fiat_accounts/{accountId}/deposit_from_linked_dda
Deposits funds from the linked DDA.



# Find a specific fiat account
Source: https://developers.fireblocks.com/api-reference/fiat-accounts/find-a-specific-fiat-account

https://docs.fireblocks.com/api/v1/swagger.yaml get /fiat_accounts/{accountId}
Returns a fiat account by ID.
Endpoint Permission: Admin, Non-Signing Admin.



# List fiat accounts
Source: https://developers.fireblocks.com/api-reference/fiat-accounts/list-fiat-accounts

https://docs.fireblocks.com/api/v1/swagger.yaml get /fiat_accounts
Returns all fiat accounts.
Endpoint Permission: Admin, Non-Signing Admin.



# Redeem funds to DDA
Source: https://developers.fireblocks.com/api-reference/fiat-accounts/redeem-funds-to-dda

https://docs.fireblocks.com/api/v1/swagger.yaml post /fiat_accounts/{accountId}/redeem_to_linked_dda
Redeems funds to the linked DDA.



# Edit gas station settings
Source: https://developers.fireblocks.com/api-reference/gas-stations/edit-gas-station-settings

https://docs.fireblocks.com/api/v1/swagger.yaml put /gas_station/configuration
Configures gas station settings for ETH.
Learn more about the Fireblocks Gas Station in the following [guide](https://developers.fireblocks.com/docs/work-with-gas-station).
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Edit gas station settings for an asset
Source: https://developers.fireblocks.com/api-reference/gas-stations/edit-gas-station-settings-for-an-asset

https://docs.fireblocks.com/api/v1/swagger.yaml put /gas_station/configuration/{assetId}
Configures gas station settings for a requested asset.
Learn more about the Fireblocks Gas Station in the following [guide](https://developers.fireblocks.com/docs/work-with-gas-station).
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Get gas station settings
Source: https://developers.fireblocks.com/api-reference/gas-stations/get-gas-station-settings

https://docs.fireblocks.com/api/v1/swagger.yaml get /gas_station
Returns gas station settings and ETH balance.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Get gas station settings by asset
Source: https://developers.fireblocks.com/api-reference/gas-stations/get-gas-station-settings-by-asset

https://docs.fireblocks.com/api/v1/swagger.yaml get /gas_station/{assetId}
Returns gas station settings and balances for a requested asset.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Add an asset to an internal wallet
Source: https://developers.fireblocks.com/api-reference/internal-wallets/add-an-asset-to-an-internal-wallet

https://docs.fireblocks.com/api/v1/swagger.yaml post /internal_wallets/{walletId}/{assetId}
Adds an asset to an existing internal wallet.



# Create an internal wallet
Source: https://developers.fireblocks.com/api-reference/internal-wallets/create-an-internal-wallet

https://docs.fireblocks.com/api/v1/swagger.yaml post /internal_wallets
Creates a new internal wallet with the requested name.
Learn more about Whitelisted Internal Addresses [here](https://developers.fireblocks.com/docs/whitelist-addresses#internal-wallets)



# Delete a whitelisted address
Source: https://developers.fireblocks.com/api-reference/internal-wallets/delete-a-whitelisted-address

https://docs.fireblocks.com/api/v1/swagger.yaml delete /internal_wallets/{walletId}/{assetId}
Deletes a whitelisted address (for an asset) from an internal wallet.



# Delete an internal wallet
Source: https://developers.fireblocks.com/api-reference/internal-wallets/delete-an-internal-wallet

https://docs.fireblocks.com/api/v1/swagger.yaml delete /internal_wallets/{walletId}
Deletes an internal wallet by ID.



# Get an asset from an internal wallet
Source: https://developers.fireblocks.com/api-reference/internal-wallets/get-an-asset-from-an-internal-wallet

https://docs.fireblocks.com/api/v1/swagger.yaml get /internal_wallets/{walletId}/{assetId}
Returns information for an asset in an internal wallet.



# Get assets for internal wallet
Source: https://developers.fireblocks.com/api-reference/internal-wallets/get-assets-for-internal-wallet

https://docs.fireblocks.com/api/v1/swagger.yaml get /internal_wallets/{walletId}
Returns information for an internal wallet.



# List assets in an internal wallet (Paginated)
Source: https://developers.fireblocks.com/api-reference/internal-wallets/list-assets-in-an-internal-wallet-paginated

https://docs.fireblocks.com/api/v1/swagger.yaml get /internal_wallets/{walletId}/assets
Returns a paginated response of assets in an internal wallet.



# List internal wallets
Source: https://developers.fireblocks.com/api-reference/internal-wallets/list-internal-wallets

https://docs.fireblocks.com/api/v1/swagger.yaml get /internal_wallets
Gets a list of internal wallets.




# Set an AML/KYT customer reference ID for internal wallet
Source: https://developers.fireblocks.com/api-reference/internal-wallets/set-an-amlkyt-customer-reference-id-for-internal-wallet

https://docs.fireblocks.com/api/v1/swagger.yaml post /internal_wallets/{walletId}/set_customer_ref_id
Sets an AML/KYT customer reference ID for the specific internal wallet.



# Add a new signing key
Source: https://developers.fireblocks.com/api-reference/key-link-beta/add-a-new-signing-key

https://docs.fireblocks.com/api/v1/swagger.yaml post /key_link/signing_keys
Adds a new signing key to the workspace. The added key will be linked to the specific Fireblocks agent user ID. The same user will receive the proof of ownership message to be signed, and upon successful proof, the key will become enabled.



# Add a new validation key
Source: https://developers.fireblocks.com/api-reference/key-link-beta/add-a-new-validation-key

https://docs.fireblocks.com/api/v1/swagger.yaml post /key_link/validation_keys
Adds a new validation key used to validate signing keys. The new validation key will undergo an approval process by the workspace quorum.



# Disables a validation key
Source: https://developers.fireblocks.com/api-reference/key-link-beta/disables-a-validation-key

https://docs.fireblocks.com/api/v1/swagger.yaml patch /key_link/validation_keys/{keyId}
Allows disabling validation key even if it has not expired yet. It is not allowed to enable the validation key back. Another key has to be used for future validations.



# Get a signing key by `keyId`
Source: https://developers.fireblocks.com/api-reference/key-link-beta/get-a-signing-key-by-`keyid`

https://docs.fireblocks.com/api/v1/swagger.yaml get /key_link/signing_keys/{keyId}
Returns a signing key if it exists, identified by the specified `keyId`.



# Get a validation key by `keyId`
Source: https://developers.fireblocks.com/api-reference/key-link-beta/get-a-validation-key-by-`keyid`

https://docs.fireblocks.com/api/v1/swagger.yaml get /key_link/validation_keys/{keyId}
Returns a validation key if it exists, identified by the specified `keyId`.



# Get list of registered validation keys
Source: https://developers.fireblocks.com/api-reference/key-link-beta/get-list-of-registered-validation-keys

https://docs.fireblocks.com/api/v1/swagger.yaml get /key_link/validation_keys
Returns the list of validation keys in the workspace



# Get list of signing keys
Source: https://developers.fireblocks.com/api-reference/key-link-beta/get-list-of-signing-keys

https://docs.fireblocks.com/api/v1/swagger.yaml get /key_link/signing_keys
Returns the list of signing keys in the workspace



# Modify the signing keyId
Source: https://developers.fireblocks.com/api-reference/key-link-beta/modify-the-signing-keyid

https://docs.fireblocks.com/api/v1/swagger.yaml patch /key_link/signing_keys/{keyId}
Allows assigning the signing key to a vault account, if it hasn't been assigned to any other vault accounts yet.



# Set agent user id
Source: https://developers.fireblocks.com/api-reference/key-link-beta/set-agent-user-id

https://docs.fireblocks.com/api/v1/swagger.yaml patch /key_link/signing_keys/{keyId}/agent_user_id
Can modify existing signing key id if the key is not enabled. The change done in background and will be visible once applied. If key is already enabled (after proof of ownership) the user cannot be changed.



# Get list of mpc keys
Source: https://developers.fireblocks.com/api-reference/keys-beta/get-list-of-mpc-keys

https://docs.fireblocks.com/api/v1/swagger.yaml get /keys/mpc/list
Returns a list of MPC signing keys of the workspace. For each key, the list of players associated with it is attached.
**Note:** 
This endpoint is currently in beta and might be subject to changes.



# Get list of mpc keys by `userId`
Source: https://developers.fireblocks.com/api-reference/keys-beta/get-list-of-mpc-keys-by-`userid`

https://docs.fireblocks.com/api/v1/swagger.yaml get /keys/mpc/list/{userId}
Returns a list of MPC signing keys of a specific user. For each key, the list of players associated with it is attached.
**Note:**
This endpoint is currently in beta and might be subject to changes.



# Create a new network connection
Source: https://developers.fireblocks.com/api-reference/network-connections/create-a-new-network-connection

https://docs.fireblocks.com/api/v1/swagger.yaml post /network_connections
Initiates a new network connection.
**Note:** This API call is subject to Flexible Routing Schemes.

Your routing policy defines how your transactions are routed.
You can choose 1 of the 3 different schemes mentioned below for each asset type:
  - **None**; Defines the profile routing to no destination for that asset type. Incoming transactions to asset types routed to `None` will fail.
  - **Custom**; Route to an account that you choose. If you remove the account, incoming transactions will fail until you choose another one.
  - **Default**; Use the routing specified by the network profile the connection is connected to. This scheme is also referred to as "Profile Routing"

Default Workspace Presets:
  - Network Profile Crypto → **Custom**
  - Network Profile FIAT → **None**
  - Network Connection Crypto → **Default**
  - Network Connection FIAT → **Default**

Supported asset groups for routing police can be found at `/network_ids/routing_policy_asset_groups`

    - **Note**: By default, Custom routing scheme uses (`dstId` = `0`, `dstType` = `VAULT`).




# Creates a new Network ID
Source: https://developers.fireblocks.com/api-reference/network-connections/creates-a-new-network-id

https://docs.fireblocks.com/api/v1/swagger.yaml post /network_ids
Create a new Network ID.



# Delete a network connection by ID
Source: https://developers.fireblocks.com/api-reference/network-connections/delete-a-network-connection-by-id

https://docs.fireblocks.com/api/v1/swagger.yaml delete /network_connections/{connectionId}
Deletes an existing network connection specified by its connection ID.



# Delete specific network ID.
Source: https://developers.fireblocks.com/api-reference/network-connections/delete-specific-network-id

https://docs.fireblocks.com/api/v1/swagger.yaml delete /network_ids/{networkId}
Deletes a network by its ID.



# Get a network connection
Source: https://developers.fireblocks.com/api-reference/network-connections/get-a-network-connection

https://docs.fireblocks.com/api/v1/swagger.yaml get /network_connections/{connectionId}
Gets a network connection by ID.



# Get all network IDs
Source: https://developers.fireblocks.com/api-reference/network-connections/get-all-network-ids

https://docs.fireblocks.com/api/v1/swagger.yaml get /network_ids
Retrieves a list of all local and discoverable remote network IDs.



# Get both local IDs and discoverable remote IDs
Source: https://developers.fireblocks.com/api-reference/network-connections/get-both-local-ids-and-discoverable-remote-ids

https://docs.fireblocks.com/api/v1/swagger.yaml get /network_ids/search
Retrieves a list of all local and discoverable remote network IDs. Can be filtered.




# List network connections
Source: https://developers.fireblocks.com/api-reference/network-connections/list-network-connections

https://docs.fireblocks.com/api/v1/swagger.yaml get /network_connections
Returns all network connections.

**Note:** This API call is subject to Flexible Routing Schemes.

Your routing policy defines how your transactions are routed.
You can choose 1 of the 3 different schemes mentioned below for each asset type:
  - **None**; Defines the profile routing to no destination for that asset type. Incoming transactions to asset types routed to `None` will fail.
  - **Custom**; Route to an account that you choose. If you remove the account, incoming transactions will fail until you choose another one.
  - **Default**; Use the routing specified by the network profile the connection is connected to. This scheme is also referred to as "Profile Routing"

Default Workspace Presets:
  - Network Profile Crypto → **Custom**
  - Network Profile FIAT → **None**
  - Network Connection Crypto → **Default**
  - Network Connection FIAT → **Default**



# Retrieve third-party network routing validation
Source: https://developers.fireblocks.com/api-reference/network-connections/retrieve-third-party-network-routing-validation

https://docs.fireblocks.com/api/v1/swagger.yaml get /network_connections/{connectionId}/is_third_party_routing/{assetType}
The Fireblocks Network allows for flexibility around incoming deposits. A receiver can receive network deposits to locations other than Fireblocks. This endpoint validates whether future transactions are routed to the displayed recipient or to a 3rd party.



# Return all enabled routing policy asset groups
Source: https://developers.fireblocks.com/api-reference/network-connections/return-all-enabled-routing-policy-asset-groups

https://docs.fireblocks.com/api/v1/swagger.yaml get /network_ids/routing_policy_asset_groups
Returns all enabled routing policy asset groups



# Return specific network ID.
Source: https://developers.fireblocks.com/api-reference/network-connections/return-specific-network-id

https://docs.fireblocks.com/api/v1/swagger.yaml get /network_ids/{networkId}
Returns specific network ID.



# Update network connection routing policy.
Source: https://developers.fireblocks.com/api-reference/network-connections/update-network-connection-routing-policy

https://docs.fireblocks.com/api/v1/swagger.yaml patch /network_connections/{connectionId}/set_routing_policy
Updates an existing network connection's routing policy.



# Update network id routing policy.
Source: https://developers.fireblocks.com/api-reference/network-connections/update-network-id-routing-policy

https://docs.fireblocks.com/api/v1/swagger.yaml patch /network_ids/{networkId}/set_routing_policy
Updates the routing policy of a specified network ID.



# Update network ID's discoverability.
Source: https://developers.fireblocks.com/api-reference/network-connections/update-network-ids-discoverability

https://docs.fireblocks.com/api/v1/swagger.yaml patch /network_ids/{networkId}/set_discoverability
Update whether or not the network ID is discoverable by others.



# Update network ID's name.
Source: https://developers.fireblocks.com/api-reference/network-connections/update-network-ids-name

https://docs.fireblocks.com/api/v1/swagger.yaml patch /network_ids/{networkId}/set_name
Updates name of a specified network ID.



# List all distinct owned tokens (paginated)
Source: https://developers.fireblocks.com/api-reference/nfts/list-all-distinct-owned-tokens-paginated

https://docs.fireblocks.com/api/v1/swagger.yaml get /nfts/ownership/assets
Returns all owned distinct tokens (for your tenant) and their data in your workspace.




# List all owned tokens (paginated)
Source: https://developers.fireblocks.com/api-reference/nfts/list-all-owned-tokens-paginated

https://docs.fireblocks.com/api/v1/swagger.yaml get /nfts/ownership/tokens
Returns all tokens and their data in your workspace.




# List owned collections (paginated)
Source: https://developers.fireblocks.com/api-reference/nfts/list-owned-collections-paginated

https://docs.fireblocks.com/api/v1/swagger.yaml get /nfts/ownership/collections
Returns all collections in your workspace




# List token data by ID
Source: https://developers.fireblocks.com/api-reference/nfts/list-token-data-by-id

https://docs.fireblocks.com/api/v1/swagger.yaml get /nfts/tokens/{id}
Returns the requested token data.




# List tokens by IDs
Source: https://developers.fireblocks.com/api-reference/nfts/list-tokens-by-ids

https://docs.fireblocks.com/api/v1/swagger.yaml get /nfts/tokens
Returns the requested tokens data.




# Refresh token metadata
Source: https://developers.fireblocks.com/api-reference/nfts/refresh-token-metadata

https://docs.fireblocks.com/api/v1/swagger.yaml put /nfts/tokens/{id}
Updates the latest token metadata.




# Refresh vault account tokens
Source: https://developers.fireblocks.com/api-reference/nfts/refresh-vault-account-tokens

https://docs.fireblocks.com/api/v1/swagger.yaml put /nfts/ownership/tokens
Updates all tokens and balances per blockchain and vault account.
Learn more about Fireblocks NFT management in the following [guide](https://developers.fireblocks.com/reference/deploy-an-nft-collection).

Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Update token ownership status
Source: https://developers.fireblocks.com/api-reference/nfts/update-token-ownership-status

https://docs.fireblocks.com/api/v1/swagger.yaml put /nfts/ownership/tokens/{id}/status
Updates token status for a tenant, in all tenant vaults.




# Update tokens ownership spam property
Source: https://developers.fireblocks.com/api-reference/nfts/update-tokens-ownership-spam-property

https://docs.fireblocks.com/api/v1/swagger.yaml put /nfts/ownership/tokens/spam
Updates tokens spam property for a tenant's token ownerships, in all tenant vaults.



# Update tokens ownership status
Source: https://developers.fireblocks.com/api-reference/nfts/update-tokens-ownership-status

https://docs.fireblocks.com/api/v1/swagger.yaml put /nfts/ownership/tokens/status
Updates tokens status for a tenant, in all tenant vaults.



# Add Collateral
Source: https://developers.fireblocks.com/api-reference/off-exchanges/add-collateral

https://docs.fireblocks.com/api/v1/swagger.yaml post /off_exchange/add
Add collateral and create deposit request.
Learn more about Fireblocks Off Exchange in the following [guide](https://developers.fireblocks.com/docs/off-exchange).
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Create Settlement for a Trader
Source: https://developers.fireblocks.com/api-reference/off-exchanges/create-settlement-for-a-trader

https://docs.fireblocks.com/api/v1/swagger.yaml post /off_exchange/settlements/trader
Create settlement for a trader.
Learn more about Fireblocks Off Exchange in the following [guide](https://developers.fireblocks.com/docs/off-exchange).
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Find a specific collateral exchange account
Source: https://developers.fireblocks.com/api-reference/off-exchanges/find-a-specific-collateral-exchange-account

https://docs.fireblocks.com/api/v1/swagger.yaml get /off_exchange/collateral_accounts/{mainExchangeAccountId}
Returns a collateral account by mainExchangeAccountId.
Learn more about Fireblocks Off Exchange in the following [guide](https://developers.fireblocks.com/docs/off-exchange).
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Get Settlements Transactions
Source: https://developers.fireblocks.com/api-reference/off-exchanges/get-settlements-transactions

https://docs.fireblocks.com/api/v1/swagger.yaml get /off_exchange/settlements/transactions
Get settlements transactions from exchange.
Learn more about Fireblocks Off Exchange in the following [guide](https://developers.fireblocks.com/docs/off-exchange).
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Remove Collateral
Source: https://developers.fireblocks.com/api-reference/off-exchanges/remove-collateral

https://docs.fireblocks.com/api/v1/swagger.yaml post /off_exchange/remove
Remove collateral, create withdraw request.
Learn more about Fireblocks Off Exchange in the following [guide](https://developers.fireblocks.com/docs/off-exchange).
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Fetch onchain transactions for a contract
Source: https://developers.fireblocks.com/api-reference/onchain-data/fetch-onchain-transactions-for-a-contract

https://docs.fireblocks.com/api/v1/swagger.yaml get /onchain_data/base_asset_id/{baseAssetId}/contract_address/{contractAddress}/transactions
Returns a paginated list of onchain transactions for the specified contract address and base asset ID, optionally filtered by date range.



# Get historical balance data for a specific account in a contract
Source: https://developers.fireblocks.com/api-reference/onchain-data/get-historical-balance-data-for-a-specific-account-in-a-contract

https://docs.fireblocks.com/api/v1/swagger.yaml get /onchain_data/base_asset_id/{baseAssetId}/contract_address/{contractAddress}/account_address/{accountAddress}/balance_history
Returns the paginated balance history of the specified account in a contract with optional date range and interval filtering.



# Get historical total supply data for a contract
Source: https://developers.fireblocks.com/api-reference/onchain-data/get-historical-total-supply-data-for-a-contract

https://docs.fireblocks.com/api/v1/swagger.yaml get /onchain_data/base_asset_id/{baseAssetId}/contract_address/{contractAddress}/total_supply
Returns the paginated total supply history of the specified contract with optional date range and interval filtering.



# Get latest balances for all addresses holding tokens from a contract
Source: https://developers.fireblocks.com/api-reference/onchain-data/get-latest-balances-for-all-addresses-holding-tokens-from-a-contract

https://docs.fireblocks.com/api/v1/swagger.yaml get /onchain_data/base_asset_id/{baseAssetId}/contract_address/{contractAddress}/balances
Returns the latest balance for each unique address with support for numeric balance sorting. The `prev` cursor is reserved for future support.



# Get summary for the token contract
Source: https://developers.fireblocks.com/api-reference/onchain-data/get-summary-for-the-token-contract

https://docs.fireblocks.com/api/v1/swagger.yaml get /onchain_data/base_asset_id/{baseAssetId}/contract_address/{contractAddress}/summary
Returns the total number of unique addresses holding balances and the total supply for the specified contract.



# Get the current state of addresses in an access registry
Source: https://developers.fireblocks.com/api-reference/onchain-data/get-the-current-state-of-addresses-in-an-access-registry

https://docs.fireblocks.com/api/v1/swagger.yaml get /onchain_data/base_asset_id/{baseAssetId}/access_registry_address/{accessRegistryAddress}/list
Returns the current state of addresses in the specified access registry. Only addresses that are currently active (added but not removed) are included.



# List of active roles for a given contract address and base asset ID
Source: https://developers.fireblocks.com/api-reference/onchain-data/list-of-active-roles-for-a-given-contract-address-and-base-asset-id

https://docs.fireblocks.com/api/v1/swagger.yaml get /onchain_data/base_asset_id/{baseAssetId}/contract_address/{contractAddress}/roles
Returns a list of currently active roles for the specified baseAssetId and contractAddress.



# Summary of access registry state
Source: https://developers.fireblocks.com/api-reference/onchain-data/summary-of-access-registry-state

https://docs.fireblocks.com/api/v1/swagger.yaml get /onchain_data/base_asset_id/{baseAssetId}/access_registry_address/{accessRegistryAddress}/summary
Returns a summary of the current state of the access registry for the specified baseAssetId and accessRegistryAddress.



# Enable or disable transactions to OTA
Source: https://developers.fireblocks.com/api-reference/ota-beta/enable-or-disable-transactions-to-ota

https://docs.fireblocks.com/api/v1/swagger.yaml put /management/ota
Enable or disable transactions to One Time Addresses (Non Whitelisted addresses).
Learn more about [One Time Addresses](https://support.fireblocks.io/hc/en-us/articles/4409104568338-One-Time-Address-OTA-feature)



# Returns current OTA status
Source: https://developers.fireblocks.com/api-reference/ota-beta/returns-current-ota-status

https://docs.fireblocks.com/api/v1/swagger.yaml get /management/ota
Returns current OTA status



# Create payment flow configuration
Source: https://developers.fireblocks.com/api-reference/payments--flows/create-payment-flow-configuration

https://docs.fireblocks.com/api/v1/swagger.yaml post /payments/workflow_config
Generate a new configuration ID to be used for initiating executions in subsequent phases. This configuration should include the operations you intend to incorporate into the workflow, such as TRANSFER, CONVERT, and DISBURSE, in addition to your pre-screening preferences, which are disabled by default.



# Create workflow execution
Source: https://developers.fireblocks.com/api-reference/payments--flows/create-workflow-execution

https://docs.fireblocks.com/api/v1/swagger.yaml post /payments/workflow_execution
Validate the "workflow-config" previously created by utilizing the unique "configId". This step requires the mandatory field amount, and allows for modifications to other fields defined via the "workflow-config" endpoint, including pre-screening preferences. A response containing the "workflowExecutionId" and detailing the validation status will be provided. Execution is ready when the "workflow-execution" status is READY_FOR_LAUNCH, at which point it can be initiated with "POST /workflow-execution/{workflowExecutionId}/actions/execute".



# Delete workflow configuration
Source: https://developers.fireblocks.com/api-reference/payments--flows/delete-workflow-configuration

https://docs.fireblocks.com/api/v1/swagger.yaml delete /payments/workflow_config/{configId}
Delete a configuration using the specified "configId".



# Execute the payments workflow
Source: https://developers.fireblocks.com/api-reference/payments--flows/execute-the-payments-workflow

https://docs.fireblocks.com/api/v1/swagger.yaml post /payments/workflow_execution/{workflowExecutionId}/actions/execute
Launch the execution of a pre-configured workflow, identified by "workflowExecutionId", once it reaches the READY_FOR_LAUNCH state. The workflow undergoes several phases during execution - EXECUTION_IN_PROGRESS - Marks the start of the workflow execution. EXECUTION_COMPLETED or EXECUTION_FAILED - Indicates the execution has reached a final state.



# Get workflow execution details
Source: https://developers.fireblocks.com/api-reference/payments--flows/get-workflow-execution-details

https://docs.fireblocks.com/api/v1/swagger.yaml get /payments/workflow_execution/{workflowExecutionId}
Retrieve details of a previously initiated workflow execution by specifying the "workflowExecutionId"



# Retrieve workflow configuration
Source: https://developers.fireblocks.com/api-reference/payments--flows/retrieve-workflow-configuration

https://docs.fireblocks.com/api/v1/swagger.yaml get /payments/workflow_config/{configId}
Retrieve a previously created workflow configuration using the specified "configId".



# Create a payout instruction set
Source: https://developers.fireblocks.com/api-reference/payments--payout/create-a-payout-instruction-set

https://docs.fireblocks.com/api/v1/swagger.yaml post /payments/payout
**Note:** The reference content in this section documents the Payments
Engine endpoint. The Payments Engine endpoints include APIs available only
for customers with Payments Engine enabled on their accounts.

These endpoints are currently in beta and might be subject to
changes.

If you want to learn more about Fireblocks Payments Engine, please
contact your Fireblocks Customer Success Manager or email
CSM@fireblocks.com.

**Create a payout instruction set.**

A payout instruction set is a set of instructions for distributing payments
from a single payment account to a list of payee accounts.

The instruction set defines:

- the payment account and its account type (vault, exchange, or fiat).
- the account type (vault account, exchange account, whitelisted address,
  network connection, fiat account, or merchant account), the amount, and the
  asset of payment for each payee account.

Learn more about Fireblocks Payments - Payouts in the following
[guide](https://developers.fireblocks.com/docs/create-payouts).

Endpoint Permission: Admin, Non-Signing Admin.




# Execute a payout instruction set
Source: https://developers.fireblocks.com/api-reference/payments--payout/execute-a-payout-instruction-set

https://docs.fireblocks.com/api/v1/swagger.yaml post /payments/payout/{payoutId}/actions/execute
**Note:** The reference content in this section documents the Payments
Engine endpoint. The Payments Engine endpoints include APIs available only
for customers with Payments Engine enabled on their accounts.

These endpoints are currently in beta and might be subject to
changes.

If you want to learn more about Fireblocks Payments Engine, please
contact your Fireblocks Customer Success Manager or email
CSM@fireblocks.com.

**Execute a payout instruction set.**

The instruction set will be verified and executed.

**Source locking**

If you are executing a payout instruction set from a payment account with an
already active payout the active payout will complete before the new payout
instruction set can be executed.

You cannot execute the same payout instruction set more than once.




# Get the status of a payout instruction set
Source: https://developers.fireblocks.com/api-reference/payments--payout/get-the-status-of-a-payout-instruction-set

https://docs.fireblocks.com/api/v1/swagger.yaml get /payments/payout/{payoutId}
**Note:** The reference content in this section documents the Payments Engine endpoint. The Payments Engine endpoints include APIs available only for customers with Payments Engine enabled on their accounts. 
These endpoints are currently in beta and might be subject to changes.
If you want to learn more about Fireblocks Payments Engine, please contact your Fireblocks Customer Success Manager or email CSM@fireblocks.com. 
Endpoint Permission: Admin, Non-Signing Admin.




# Get the active draft
Source: https://developers.fireblocks.com/api-reference/policy-editor-beta/get-the-active-draft

https://docs.fireblocks.com/api/v1/swagger.yaml get /tap/draft
Legacy Endpoint – Returns the active draft and its validation. 
**Note:** 
- This endpoint will remain available for the foreseeable future and is not deprecated. - The `getDraft` endpoint under policy/paths provides policy type-specific operations and improved functionality. - These endpoints are currently in beta and might be subject to changes.
If you want to participate and learn more about the Fireblocks TAP, please contact your Fireblocks Customer Success Manager or send an email to CSM@fireblocks.com.




# Get the active policy and its validation
Source: https://developers.fireblocks.com/api-reference/policy-editor-beta/get-the-active-policy-and-its-validation

https://docs.fireblocks.com/api/v1/swagger.yaml get /tap/active_policy
Legacy Endpoint – Returns the active policy and its validation. 
**Note:** 
- This endpoint will remain available for the foreseeable future and is not deprecated. - The `getActivePolicy` endpoint under policy/paths provides policy type-specific operations and improved functionality. - These endpoints are currently in beta and might be subject to changes.
If you want to participate and learn more about the Fireblocks TAP, please contact your Fireblocks Customer Success Manager or send an email to CSM@fireblocks.com.




# Send publish request for a certain draft id
Source: https://developers.fireblocks.com/api-reference/policy-editor-beta/send-publish-request-for-a-certain-draft-id

https://docs.fireblocks.com/api/v1/swagger.yaml post /tap/draft
Legacy Endpoint – Send publish request of certain draft id and returns the response. 
**Note:** 
- This endpoint will remain available for the foreseeable future and is not deprecated. - The `publishDraft` endpoint under policy/paths provides improved functionality and better performance. - These endpoints are currently in beta and might be subject to changes.
If you want to participate and learn more about the Fireblocks TAP, please contact your Fireblocks Customer Success Manager or send an email to CSM@fireblocks.com.




# Send publish request for a set of policy rules
Source: https://developers.fireblocks.com/api-reference/policy-editor-beta/send-publish-request-for-a-set-of-policy-rules

https://docs.fireblocks.com/api/v1/swagger.yaml post /tap/publish
Send publish request of set of policy rules and returns the response. 
**Note:** These endpoints are currently in beta and might be subject to changes.
If you want to participate and learn more about the Fireblocks TAP, please contact your Fireblocks Customer Success Manager or send an email to CSM@fireblocks.com.




# Update the draft with a new set of rules
Source: https://developers.fireblocks.com/api-reference/policy-editor-beta/update-the-draft-with-a-new-set-of-rules

https://docs.fireblocks.com/api/v1/swagger.yaml put /tap/draft
Legacy Endpoint – Update the draft and return its validation. 
**Note:** 
- This endpoint will remain available for the foreseeable future and is not deprecated. - The `updateDraft` endpoint under policy/paths provides policy type-specific operations and improved functionality. - These endpoints are currently in beta and might be subject to changes.
If you want to participate and learn more about the Fireblocks TAP, please contact your Fireblocks Customer Success Manager or send an email to CSM@fireblocks.com.




# Get the active draft by policy type
Source: https://developers.fireblocks.com/api-reference/policy-editor-v2-beta/get-the-active-draft-by-policy-type

https://docs.fireblocks.com/api/v1/swagger.yaml get /policy/draft
Returns the active draft and its validation for a specific policy type. 
**Note:** These endpoints are currently in beta and might be subject to changes.




# Get the active policy and its validation by policy type
Source: https://developers.fireblocks.com/api-reference/policy-editor-v2-beta/get-the-active-policy-and-its-validation-by-policy-type

https://docs.fireblocks.com/api/v1/swagger.yaml get /policy/active_policy
Returns the active policy and its validation for a specific policy type.

**Note:** This endpoint is currently in beta and subject to change. If you want to participate in the Policies beta, contact your Fireblocks Customer Success Manager or send an email to csm@fireblocks.com.

Endpoint Permissions: Owner, Admin, Non-Signing Admin.




# Send publish request for a certain draft id
Source: https://developers.fireblocks.com/api-reference/policy-editor-v2-beta/send-publish-request-for-a-certain-draft-id

https://docs.fireblocks.com/api/v1/swagger.yaml post /policy/draft
Send publish request of certain draft id and returns the response. 
**Note:** These endpoints are currently in beta and might be subject to changes.
If you want to participate and learn more about the Fireblocks Policy Editor, please contact your Fireblocks Customer Success Manager or send an email to CSM@fireblocks.com.




# Update the draft with a new set of rules by policy types
Source: https://developers.fireblocks.com/api-reference/policy-editor-v2-beta/update-the-draft-with-a-new-set-of-rules-by-policy-types

https://docs.fireblocks.com/api/v1/swagger.yaml put /policy/draft
Update the draft and return its validation for specific policy types. 
**Note:** These endpoints are currently in beta and might be subject to changes.




# Resets device
Source: https://developers.fireblocks.com/api-reference/reset-device/resets-device

https://docs.fireblocks.com/api/v1/swagger.yaml post /management/users/{id}/reset_device
Resets mobile device for given console user, that user will need to do mobile onboarding again.
- Please note that this endpoint is available only for API keys with Admin/Non Signing Admin permissions.
Endpoint Permission: Admin, Non-Signing Admin.



# Add external ref. ID
Source: https://developers.fireblocks.com/api-reference/smart-transfer/add-external-ref-id

https://docs.fireblocks.com/api/v1/swagger.yaml put /smart-transfers/{ticketId}/external-id
Set external id Smart Transfer ticket. Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Cancel Ticket
Source: https://developers.fireblocks.com/api-reference/smart-transfer/cancel-ticket

https://docs.fireblocks.com/api/v1/swagger.yaml put /smart-transfers/{ticketId}/cancel
Cancel Smart Transfer ticket. Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Create leg (term)
Source: https://developers.fireblocks.com/api-reference/smart-transfer/create-leg-term

https://docs.fireblocks.com/api/v1/swagger.yaml post /smart-transfers/{ticketId}/terms
Creates new smart transfer ticket term (when the ticket status is DRAFT). Learn more about Fireblocks Smart Transfers in the following [guide](https://developers.fireblocks.com/docs/execute-smart-transfers). Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Create Ticket
Source: https://developers.fireblocks.com/api-reference/smart-transfer/create-ticket

https://docs.fireblocks.com/api/v1/swagger.yaml post /smart-transfers
Creates a new Smart Transfer ticket. Learn more about Fireblocks Smart Transfers [here](https://developers.fireblocks.com/docs/execute-smart-transfers).

**Note:** The `DVP` value is in Early Access and should only be used if Fireblocks has enabled it in your workspace. Contact your Customer Success Manager for more information.

**Endpoint Permissions:** Admin, Non-Signing Admin, Signer, Approver, Editor.




# Define funding source
Source: https://developers.fireblocks.com/api-reference/smart-transfer/define-funding-source

https://docs.fireblocks.com/api/v1/swagger.yaml put /smart-transfers/{ticketId}/terms/{termId}/fund
Set funding source for ticket term (in case of ASYNC tickets, this will execute transfer immediately). Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Delete ticket leg (term)
Source: https://developers.fireblocks.com/api-reference/smart-transfer/delete-ticket-leg-term

https://docs.fireblocks.com/api/v1/swagger.yaml delete /smart-transfers/{ticketId}/terms/{termId}
Delete ticket term when ticket is in DRAFT status



# Find Ticket
Source: https://developers.fireblocks.com/api-reference/smart-transfer/find-ticket

https://docs.fireblocks.com/api/v1/swagger.yaml get /smart-transfers
Find tickets by their title or ticker. You can also query all tickets without filters by not providing any input parameters.
**Endpoint Permissions:** Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.



# Fund dvp ticket
Source: https://developers.fireblocks.com/api-reference/smart-transfer/fund-dvp-ticket

https://docs.fireblocks.com/api/v1/swagger.yaml put /smart_transfers/{ticketId}/dvp/fund
Create or fulfill dvp ticket order



# Fund ticket manually
Source: https://developers.fireblocks.com/api-reference/smart-transfer/fund-ticket-manually

https://docs.fireblocks.com/api/v1/swagger.yaml put /smart-transfers/{ticketId}/fulfill
Manually fulfill ticket, in case when all terms (legs) are funded manually. Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Get Smart Transfer ticket term
Source: https://developers.fireblocks.com/api-reference/smart-transfer/get-smart-transfer-ticket-term

https://docs.fireblocks.com/api/v1/swagger.yaml get /smart-transfers/{ticketId}/terms/{termId}
Find a specific term of a specific Smart Transfer ticket. Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.



# Get smart transfers statistic
Source: https://developers.fireblocks.com/api-reference/smart-transfer/get-smart-transfers-statistic

https://docs.fireblocks.com/api/v1/swagger.yaml get /smart_transfers/statistic
Get smart transfer statistic



# Get user group
Source: https://developers.fireblocks.com/api-reference/smart-transfer/get-user-group

https://docs.fireblocks.com/api/v1/swagger.yaml get /smart-transfers/settings/user-groups
Get Smart Transfer user groups.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.



# Manually add term transaction
Source: https://developers.fireblocks.com/api-reference/smart-transfer/manually-add-term-transaction

https://docs.fireblocks.com/api/v1/swagger.yaml put /smart-transfers/{ticketId}/terms/{termId}/manually-fund
Manually set ticket term transaction.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Search Ticket by ID
Source: https://developers.fireblocks.com/api-reference/smart-transfer/search-ticket-by-id

https://docs.fireblocks.com/api/v1/swagger.yaml get /smart-transfers/{ticketId}
Find Smart Transfer ticket by id. Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.



# Set expiration
Source: https://developers.fireblocks.com/api-reference/smart-transfer/set-expiration

https://docs.fireblocks.com/api/v1/swagger.yaml put /smart-transfers/{ticketId}/expires-in
Set expiration date on Smart Transfer ticket. Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Set funding source and approval
Source: https://developers.fireblocks.com/api-reference/smart-transfer/set-funding-source-and-approval

https://docs.fireblocks.com/api/v1/swagger.yaml put /smart_transfers/{ticketId}/terms/{termId}/dvp/approve
Set funding source for ticket term and creating approving transaction for contract to transfer asset



# Set user group
Source: https://developers.fireblocks.com/api-reference/smart-transfer/set-user-group

https://docs.fireblocks.com/api/v1/swagger.yaml post /smart-transfers/settings/user-groups
Set Smart Transfers user group to receive email notifications for Smart Transfers.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Submit ticket
Source: https://developers.fireblocks.com/api-reference/smart-transfer/submit-ticket

https://docs.fireblocks.com/api/v1/swagger.yaml put /smart-transfers/{ticketId}/submit
Submit Smart Transfer ticket - change status into ready for approval if auto approval is not turned on, or OPEN if auto approval is on. Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Update ticket leg (term)
Source: https://developers.fireblocks.com/api-reference/smart-transfer/update-ticket-leg-term

https://docs.fireblocks.com/api/v1/swagger.yaml put /smart-transfers/{ticketId}/terms/{termId}
Update ticket term (when ticket status is DRAFT)



# Approve provider terms of service
Source: https://developers.fireblocks.com/api-reference/staking/approve-provider-terms-of-service

https://docs.fireblocks.com/api/v1/swagger.yaml post /staking/providers/{providerId}/approveTermsOfService
Approves the provider's terms of service. Must be called once before performing any staking operation with this provider.



# Claim accrued rewards
Source: https://developers.fireblocks.com/api-reference/staking/claim-accrued-rewards

https://docs.fireblocks.com/api/v1/swagger.yaml post /staking/chains/{chainDescriptor}/claim_rewards
Claims available staking rewards for the specified chain and vault. Supported chains: Solana and Polygon (POL/Matic). Behavior depends on protocol reward distribution.



# Consolidate staking positions (ETH validator consolidation)
Source: https://developers.fireblocks.com/api-reference/staking/consolidate-staking-positions-eth-validator-consolidation

https://docs.fireblocks.com/api/v1/swagger.yaml post /staking/chains/{chainDescriptor}/consolidate
Consolidates the source staking position into the destination, merging the balance into the destination and closing the source position once complete. Both positions must be from the same vault account (i.e. same withdrawal credentials).  On chain, this translates into a consolidation transaction, where the  source validator is consolidated into the destination validator.  Supported chains: Ethereum (ETH) only.
Endpoint Permission: Owner, Admin, Non-Signing Admin, Signer, Approver, Editor.
**Note:** This endpoint is currently in beta and might be subject to changes.



# Get chain-level staking parameters
Source: https://developers.fireblocks.com/api-reference/staking/get-chain-level-staking-parameters

https://docs.fireblocks.com/api/v1/swagger.yaml get /staking/chains/{chainDescriptor}/chainInfo
Returns chain-specific staking information such as epoch/slot cadence, lockup or unbonding periods, fee/reward mechanics, and other operational constraints.



# Get position details
Source: https://developers.fireblocks.com/api-reference/staking/get-position-details

https://docs.fireblocks.com/api/v1/swagger.yaml get /staking/positions/{id}
Returns full details for a single staking position: amounts, rewards, status, chain, and vault.



# Get positions summary
Source: https://developers.fireblocks.com/api-reference/staking/get-positions-summary

https://docs.fireblocks.com/api/v1/swagger.yaml get /staking/positions/summary
Returns an aggregated cross-vault summary: active/inactive counts, total staked, and total rewards per chain.



# Get positions summary by vault
Source: https://developers.fireblocks.com/api-reference/staking/get-positions-summary-by-vault

https://docs.fireblocks.com/api/v1/swagger.yaml get /staking/positions/summary/vaults
Returns per-vault aggregates: status breakdown, total staked, and total rewards per chain.



# Initiate or add to existing stake
Source: https://developers.fireblocks.com/api-reference/staking/initiate-or-add-to-existing-stake

https://docs.fireblocks.com/api/v1/swagger.yaml post /staking/chains/{chainDescriptor}/stake
Creates a new staking position and returns its unique ID. For Ethereum compounding validator (EIP-7251): when the 'id' of an existing compounding validator position is provided, adds to that position; otherwise creates a new position. For Ethereum legacy validator: creates a new position regardless of existing delegations. For Cosmos chains and Ethereum liquid staking (Lido): automatically add to existing positions for the same validator provider and same vault account if one exists, otherwise create a new position. For Solana and Polygon (MATIC/POL): always create new positions regardless of existing delegations.



# Initiate unstake
Source: https://developers.fireblocks.com/api-reference/staking/initiate-unstake

https://docs.fireblocks.com/api/v1/swagger.yaml post /staking/chains/{chainDescriptor}/unstake
Submits a chain-specific unstake request.



# List staking positions
Source: https://developers.fireblocks.com/api-reference/staking/list-staking-positions

https://docs.fireblocks.com/api/v1/swagger.yaml get /staking/positions
Returns all staking positions with core details: amounts, rewards, status, chain, and vault.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# List staking positions (Paginated)
Source: https://developers.fireblocks.com/api-reference/staking/list-staking-positions-paginated

https://docs.fireblocks.com/api/v1/swagger.yaml get /staking/positions_paginated
Returns staking positions with core details: amounts, rewards, status, chain, and vault. It supports cursor-based pagination for efficient data retrieval. This endpoint always returns a paginated response with {data, next} structure.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# List staking providers
Source: https://developers.fireblocks.com/api-reference/staking/list-staking-providers

https://docs.fireblocks.com/api/v1/swagger.yaml get /staking/providers
Returns all available staking providers with metadata such as name, ID, and supported chains.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# List supported staking chains
Source: https://developers.fireblocks.com/api-reference/staking/list-supported-staking-chains

https://docs.fireblocks.com/api/v1/swagger.yaml get /staking/chains
Returns an alphabetical list of blockchains supported for staking by the current workspace context.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Merge staking positions
Source: https://developers.fireblocks.com/api-reference/staking/merge-staking-positions

https://docs.fireblocks.com/api/v1/swagger.yaml post /staking/chains/{chainDescriptor}/merge
Merges the source stake account into the destination, consolidating the balance into the destination and closing the source account once complete. Both accounts must be from the same validator provider and of same vault account.. Supported chains: Solana (SOL).
Endpoint Permission: Owner, Admin, Non-Signing Admin, Signer, Approver, Editor.



# Split a staking position
Source: https://developers.fireblocks.com/api-reference/staking/split-a-staking-position

https://docs.fireblocks.com/api/v1/swagger.yaml post /staking/chains/{chainDescriptor}/split
Splits a staking position by creating a new stake account with the requested amount, while keeping the original account with the remaining balance. Supported chains: Solana (SOL).



# Withdraw staked funds
Source: https://developers.fireblocks.com/api-reference/staking/withdraw-staked-funds

https://docs.fireblocks.com/api/v1/swagger.yaml post /staking/chains/{chainDescriptor}/withdraw
Withdraws funds that have completed the unbonding period. Typically requires the position to be deactivated first (unstake → unbond → withdraw). Amount and timing vary by chain protocol.

Partial withdrawal is supported for ETH compounding validators (EIP-7251/Pectra) and Cosmos chains via the optional 'amount' field. For ETH compounding validators, the remaining balance must be at least 32 ETH after the withdrawal. For all other chains, omitting 'amount' withdraws the entire available balance.



# Cancel an approval request by id
Source: https://developers.fireblocks.com/api-reference/tags/cancel-an-approval-request-by-id

https://docs.fireblocks.com/api/v1/swagger.yaml post /tags/approval_requests/{id}/cancel
Cancel an approval request by id. Can only cancel requests in PENDING status. Returns 202 Accepted when the cancellation is processed.



# Create a new tag
Source: https://developers.fireblocks.com/api-reference/tags/create-a-new-tag

https://docs.fireblocks.com/api/v1/swagger.yaml post /tags
Create a new tag.
Endpoint Permissions: For protected tags: ADMIN,NON_SIGNING_ADMIN,OWNER. For non protected tags: ADMIN,NON_SIGNING_ADMIN,OWNER,SIGNER,EDITOR,APPROVER.



# Delete a tag
Source: https://developers.fireblocks.com/api-reference/tags/delete-a-tag

https://docs.fireblocks.com/api/v1/swagger.yaml delete /tags/{tagId}
Delete the specified tag.
Endpoint Permission: For protected tags: Owner, Admin, Non-Signing Admin. For non protected tags: Owner, Admin, Non-Signing Admin, Signer, Editor, Approver.



# Get a tag
Source: https://developers.fireblocks.com/api-reference/tags/get-a-tag

https://docs.fireblocks.com/api/v1/swagger.yaml get /tags/{tagId}
Retrieve an existing tag by ID.



# Get an approval request by id
Source: https://developers.fireblocks.com/api-reference/tags/get-an-approval-request-by-id

https://docs.fireblocks.com/api/v1/swagger.yaml get /tags/approval_requests/{id}
Get an approval request by id



# Get list of tags
Source: https://developers.fireblocks.com/api-reference/tags/get-list-of-tags

https://docs.fireblocks.com/api/v1/swagger.yaml get /tags
Retrieve a paged list of all tags according to filters.



# Update a tag
Source: https://developers.fireblocks.com/api-reference/tags/update-a-tag

https://docs.fireblocks.com/api/v1/swagger.yaml patch /tags/{tagId}
Update an existing specified tag.
Endpoint Permission: For protected tags: Owner, Admin, Non-Signing Admin. For non protected tags: Owner, Admin, Non-Signing Admin, Signer, Editor, Approver.



# Burn tokens
Source: https://developers.fireblocks.com/api-reference/tokenization/burn-tokens

https://docs.fireblocks.com/api/v1/swagger.yaml post /tokenization/collections/{id}/tokens/burn
Burn tokens in a collection



# Create a new collection
Source: https://developers.fireblocks.com/api-reference/tokenization/create-a-new-collection

https://docs.fireblocks.com/api/v1/swagger.yaml post /tokenization/collections
Create a new collection and link it as a token.
Endpoint Permission: Owner, Admin, Non-Signing Admin, Signer, and Editor.



# Delete a collection link
Source: https://developers.fireblocks.com/api-reference/tokenization/delete-a-collection-link

https://docs.fireblocks.com/api/v1/swagger.yaml delete /tokenization/collections/{id}
Delete a collection link



# Deploy LayerZero adapters
Source: https://developers.fireblocks.com/api-reference/tokenization/deploy-layerzero-adapters

https://docs.fireblocks.com/api/v1/swagger.yaml post /tokenization/multichain/bridge/layerzero
Deploy LayerZero adapters for multichain token bridging functionality. This endpoint creates adapter contracts that enable cross-chain token transfers.



# Get a collection by id
Source: https://developers.fireblocks.com/api-reference/tokenization/get-a-collection-by-id

https://docs.fireblocks.com/api/v1/swagger.yaml get /tokenization/collections/{id}
Get a collection by id



# Get collection token details
Source: https://developers.fireblocks.com/api-reference/tokenization/get-collection-token-details

https://docs.fireblocks.com/api/v1/swagger.yaml get /tokenization/collections/{id}/tokens/{tokenId}
Get collection token details by id



# Get collections
Source: https://developers.fireblocks.com/api-reference/tokenization/get-collections

https://docs.fireblocks.com/api/v1/swagger.yaml get /tokenization/collections
Get collections (paginated).
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.



# Get deterministic address for contract deployment
Source: https://developers.fireblocks.com/api-reference/tokenization/get-deterministic-address-for-contract-deployment

https://docs.fireblocks.com/api/v1/swagger.yaml post /tokenization/multichain/deterministic_address
Get a deterministic address for contract deployment. The address is derived from the contract's bytecode and  provided salt. This endpoint is used to get the address of a contract that will be deployed in the future.



# Get LayerZero DVN configuration
Source: https://developers.fireblocks.com/api-reference/tokenization/get-layerzero-dvn-configuration

https://docs.fireblocks.com/api/v1/swagger.yaml get /tokenization/multichain/bridge/layerzero/config/{adapterTokenLinkId}/dvns
Retrieve the DVN (Data Verification Network) configuration for a specific adapter. Returns DVN configurations for channels between the source adapter and its peers.



# Get LayerZero peers
Source: https://developers.fireblocks.com/api-reference/tokenization/get-layerzero-peers

https://docs.fireblocks.com/api/v1/swagger.yaml get /tokenization/multichain/bridge/layerzero/config/{adapterTokenLinkId}/peers
Retrieve the LayerZero peers configured for a specific adapter. Returns information about peer relationships for cross-chain communication.



# Get the total count of linked tokens
Source: https://developers.fireblocks.com/api-reference/tokenization/get-the-total-count-of-linked-tokens

https://docs.fireblocks.com/api/v1/swagger.yaml get /tokenization/tokens/count
Get the total count of linked tokens



# Issue a new token
Source: https://developers.fireblocks.com/api-reference/tokenization/issue-a-new-token

https://docs.fireblocks.com/api/v1/swagger.yaml post /tokenization/tokens
Facilitates the creation of a new token, supporting both EVM-based and Stellar/Ripple platforms. For EVM, it deploys the corresponding contract template to the blockchain and links the token to the workspace. For Stellar/Ripple, it links a newly created token directly to the workspace without deploying a contract. Returns the token link with status "PENDING" until the token is deployed or "SUCCESS" if no deployment is needed.
Endpoint Permission: Owner, Admin, Non-Signing Admin, Signer, and Editor.



# Issue a token on one or more blockchains
Source: https://developers.fireblocks.com/api-reference/tokenization/issue-a-token-on-one-or-more-blockchains

https://docs.fireblocks.com/api/v1/swagger.yaml post /tokenization/multichain/tokens
Facilitates the creation of a new token on one or more blockchains.



# Link a contract
Source: https://developers.fireblocks.com/api-reference/tokenization/link-a-contract

https://docs.fireblocks.com/api/v1/swagger.yaml post /tokenization/tokens/link
Link an a contract



# List all linked tokens
Source: https://developers.fireblocks.com/api-reference/tokenization/list-all-linked-tokens

https://docs.fireblocks.com/api/v1/swagger.yaml get /tokenization/tokens
Return all linked tokens (paginated)



# Mint tokens
Source: https://developers.fireblocks.com/api-reference/tokenization/mint-tokens

https://docs.fireblocks.com/api/v1/swagger.yaml post /tokenization/collections/{id}/tokens/mint
Mint tokens and upload metadata



# Reissue a multichain token
Source: https://developers.fireblocks.com/api-reference/tokenization/reissue-a-multichain-token

https://docs.fireblocks.com/api/v1/swagger.yaml post /tokenization/multichain/reissue/token/{tokenLinkId}
Reissue a multichain token. This endpoint allows you to reissue a token on one or more blockchains. The token must be initially issued using the issueTokenMultiChain endpoint.



# Remove LayerZero adapters
Source: https://developers.fireblocks.com/api-reference/tokenization/remove-layerzero-adapters

https://docs.fireblocks.com/api/v1/swagger.yaml delete /tokenization/multichain/bridge/layerzero
Remove LayerZero adapters by deactivating and unlinking them. This endpoint revokes roles and deactivates the specified adapter contracts.



# Remove LayerZero peers
Source: https://developers.fireblocks.com/api-reference/tokenization/remove-layerzero-peers

https://docs.fireblocks.com/api/v1/swagger.yaml delete /tokenization/multichain/bridge/layerzero/config/peers
Remove LayerZero peers to disconnect adapter contracts. This endpoint removes peer relationships between LayerZero adapters.



# Return a linked token
Source: https://developers.fireblocks.com/api-reference/tokenization/return-a-linked-token

https://docs.fireblocks.com/api/v1/swagger.yaml get /tokenization/tokens/{id}
Return a linked token, with its status and metadata.



# Set LayerZero DVN configuration
Source: https://developers.fireblocks.com/api-reference/tokenization/set-layerzero-dvn-configuration

https://docs.fireblocks.com/api/v1/swagger.yaml post /tokenization/multichain/bridge/layerzero/config/dvns
Configure DVN settings for LayerZero adapters. This endpoint sets up the DVN configuration for message verification between source and destination adapters.



# Set LayerZero peers
Source: https://developers.fireblocks.com/api-reference/tokenization/set-layerzero-peers

https://docs.fireblocks.com/api/v1/swagger.yaml post /tokenization/multichain/bridge/layerzero/config/peers
Set LayerZero peers to establish connections between adapter contracts. This endpoint creates peer relationships that enable cross-chain communication. It sets the destination adapter as a peer of the source adapter. If `bidirectional` is true, it also sets the source adapter as a peer of the destination adapter(s).



# Unlink a token
Source: https://developers.fireblocks.com/api-reference/tokenization/unlink-a-token

https://docs.fireblocks.com/api/v1/swagger.yaml delete /tokenization/tokens/{id}
Unlink a token. The token will be unlinked from the workspace. The token will not be deleted on chain nor the refId, only the link to the workspace will be removed.



# Validate LayerZero channel configuration
Source: https://developers.fireblocks.com/api-reference/tokenization/validate-layerzero-channel-configuration

https://docs.fireblocks.com/api/v1/swagger.yaml get /tokenization/multichain/bridge/layerzero/validate
Validate the LayerZero channel configuration between adapters. This endpoint checks if the channel configuration is correct and returns any validation errors.



# Create a quote
Source: https://developers.fireblocks.com/api-reference/trading-beta/create-a-quote

https://docs.fireblocks.com/api/v1/swagger.yaml post /trading/quotes
Generate a time-limited quote for asset conversion, providing exchange rate and amount calculations.

Note: These endpoints are currently in beta and might be subject to changes.

If you want to participate and learn more about the Fireblocks Trading, please contact your Fireblocks Customer Success Manager or send an email to CSM@fireblocks.com.

Endpoint Permission: Owner, Admin, Non-Signing Admin, Signer, Editor.

For detailed information about error codes and troubleshooting, please refer to our [API Error Codes documentation](https://developers.fireblocks.com/reference/api-error-codes).



# Create an order
Source: https://developers.fireblocks.com/api-reference/trading-beta/create-an-order

https://docs.fireblocks.com/api/v1/swagger.yaml post /trading/orders
Create an order to buy or sell an asset. If no source is given, an external source will be use.

Note: These endpoints are currently in beta and might be subject to changes.

If you want to participate and learn more about the Fireblocks Trading, please contact your Fireblocks Customer Success Manager or send an email to CSM@fireblocks.com.

Endpoint Permission: Owner, Admin, Non-Signing Admin, Signer, Editor.

For detailed information about error codes and troubleshooting, please refer to our [API Error Codes documentation](https://developers.fireblocks.com/reference/api-error-codes).



# Get order details
Source: https://developers.fireblocks.com/api-reference/trading-beta/get-order-details

https://docs.fireblocks.com/api/v1/swagger.yaml get /trading/orders/{orderId}
Retrieve detailed information about a specific order by its ID.

Note:These endpoints are currently in beta and might be subject to changes.

If you want to participate and learn more about the Fireblocks Trading, please contact your Fireblocks Customer Success Manager or send an email to CSM@fireblocks.com.

Endpoint Permission: Owner, Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.

For detailed information about error codes and troubleshooting, please refer to our [API Error Codes documentation](https://developers.fireblocks.com/reference/api-error-codes).



# Get orders
Source: https://developers.fireblocks.com/api-reference/trading-beta/get-orders

https://docs.fireblocks.com/api/v1/swagger.yaml get /trading/orders
Retrieve a paginated list of orders with optional filtering by account, provider, status, and time range.

Note:These endpoints are currently in beta and might be subject to changes.

If you want to participate and learn more about the Fireblocks Trading, please contact your Fireblocks Customer Success Manager or send an email to CSM@fireblocks.com.

Endpoint Permission: Owner, Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.

For detailed information about error codes and troubleshooting, please refer to our [API Error Codes documentation](https://developers.fireblocks.com/reference/api-error-codes).



# Get providers
Source: https://developers.fireblocks.com/api-reference/trading-beta/get-providers

https://docs.fireblocks.com/api/v1/swagger.yaml get /trading/providers
Retrieve a list of all available external providers supporting trading activities through the platform.

**Note:** These endpoints are currently in beta and might be subject to changes. If you want to participate and learn more about the Fireblocks Trading, please contact your Fireblocks Customer Success Manager or send an email to CSM@fireblocks.com.

**Endpoint Permission:** Owner, Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.

For detailed information about error codes and troubleshooting, please refer to our [API Error Codes documentation](https://developers.fireblocks.com/reference/api-error-codes).




# Get trading provider by ID
Source: https://developers.fireblocks.com/api-reference/trading-beta/get-trading-provider-by-id

https://docs.fireblocks.com/api/v1/swagger.yaml get /trading/providers/{providerId}
Retrieve a single provider by ID.

**Note:** These endpoints are currently in beta and might be subject to changes. If you want to participate and learn more about the Fireblocks Trading, please contact your Fireblocks Customer Success Manager or send an email to CSM@fireblocks.com.

**Endpoint Permission:** Owner, Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.

For detailed information about error codes and troubleshooting, please refer to our [API Error Codes documentation](https://developers.fireblocks.com/reference/api-error-codes).




# Cancel a transaction
Source: https://developers.fireblocks.com/api-reference/transactions/cancel-a-transaction

https://docs.fireblocks.com/api/v1/swagger.yaml post /transactions/{txId}/cancel
Cancels a transaction by Fireblocks Transaction ID.

Can be used only for transactions that did not get to the BROADCASTING state.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Create a new transaction
Source: https://developers.fireblocks.com/api-reference/transactions/create-a-new-transaction

https://docs.fireblocks.com/api/v1/swagger.yaml post /transactions
Creates a new transaction. This endpoint can be used for regular Transfers, Contract Calls, Raw & Typed message signing. - For Transfers, the required parameters are: `assetId`, `source`, `destination` and `amount`. - For Contract Calls, the required parameters are: `operation.CONTRACT_CALL`, `assetId` (Base Asset), `source`,



# Drop ETH (EVM) transaction by ID
Source: https://developers.fireblocks.com/api-reference/transactions/drop-eth-evm-transaction-by-id

https://docs.fireblocks.com/api/v1/swagger.yaml post /transactions/{txId}/drop
Drops a stuck ETH (EVM) transaction and creates a replacement transaction with 0 amount.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Estimate the required fee for an asset
Source: https://developers.fireblocks.com/api-reference/transactions/estimate-the-required-fee-for-an-asset

https://docs.fireblocks.com/api/v1/swagger.yaml get /estimate_network_fee
Gets the estimated required fee for an asset.
Fireblocks fetches, calculates and caches the result every 30 seconds.
Customers should query this API while taking the caching interval into consideration.
Notes:
- The `networkFee` parameter is the `gasPrice` with a given delta added, multiplied by the gasLimit plus the delta. - The estimation provided depends on the asset type.
    - For UTXO-based assets, the response contains the `feePerByte` parameter
    - For ETH-based and all EVM based assets, the response will contain `gasPrice` parameter. This is calculated by adding the `baseFee` to the `actualPriority` based on the latest 12 blocks. The response for ETH-based  contains the `baseFee`, `gasPrice`, and `priorityFee` parameters.
    - For ADA-based assets, the response will contain the parameter `networkFee` and `feePerByte` parameters.
    - For XRP and XLM, the response will contain the transaction fee.
    - For other assets, the response will contain the `networkFee` parameter.

Learn more about Fireblocks Fee Management in the following [guide](https://developers.fireblocks.com/reference/estimate-transaction-fee).
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Estimate transaction fee
Source: https://developers.fireblocks.com/api-reference/transactions/estimate-transaction-fee

https://docs.fireblocks.com/api/v1/swagger.yaml post /transactions/estimate_fee
Estimates the transaction fee for a specific transaction request.
This endpoint simulates a transaction which means that the system will expect to have the requested asset and balance in the specified wallet.
**Note**: Supports all Fireblocks assets except ZCash (ZEC).
The PROGRAM_CALL operation is not supported by this endpoint — fee estimation for Solana program calls is not available.
Learn more about Fireblocks Fee Management in the following [guide](https://developers.fireblocks.com/reference/estimate-transaction-fee).
Endpoint Permission: Admin, Signer, Approver, Editor.



# Freeze a transaction
Source: https://developers.fireblocks.com/api-reference/transactions/freeze-a-transaction

https://docs.fireblocks.com/api/v1/swagger.yaml post /transactions/{txId}/freeze
Freezes a transaction by ID.

Usually used for AML integrations when the incoming funds should be quarantined.
For account based assets - the entire amount of the transaction is frozen 
For UTXO based assets - all UTXOs of the specified transaction are frozen
Endpoint Permission: Admin, Non-Signing Admin.



# Get a specific transaction by external transaction ID
Source: https://developers.fireblocks.com/api-reference/transactions/get-a-specific-transaction-by-external-transaction-id

https://docs.fireblocks.com/api/v1/swagger.yaml get /transactions/external_tx_id/{externalTxId}
Returns transaction by external transaction ID.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.



# Get a specific transaction by Fireblocks transaction ID
Source: https://developers.fireblocks.com/api-reference/transactions/get-a-specific-transaction-by-fireblocks-transaction-id

https://docs.fireblocks.com/api/v1/swagger.yaml get /transactions/{txId}
Get a specific transaction data by Fireblocks Transaction ID
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.



# Get transaction history
Source: https://developers.fireblocks.com/api-reference/transactions/get-transaction-history

https://docs.fireblocks.com/api/v1/swagger.yaml get /transactions
Get the transaction history for your workspace.

**Endpoint Permissions:** Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.




# Set confirmation threshold by Fireblocks Transaction ID
Source: https://developers.fireblocks.com/api-reference/transactions/set-confirmation-threshold-by-fireblocks-transaction-id

https://docs.fireblocks.com/api/v1/swagger.yaml post /transactions/{txId}/set_confirmation_threshold
Overrides the required number of confirmations for transaction completion Fireblocks Transaction ID.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Set confirmation threshold by transaction hash
Source: https://developers.fireblocks.com/api-reference/transactions/set-confirmation-threshold-by-transaction-hash

https://docs.fireblocks.com/api/v1/swagger.yaml post /txHash/{txHash}/set_confirmation_threshold
Overrides the required number of confirmations for transaction completion by transaction hash.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Unfreeze a transaction
Source: https://developers.fireblocks.com/api-reference/transactions/unfreeze-a-transaction

https://docs.fireblocks.com/api/v1/swagger.yaml post /transactions/{txId}/unfreeze
Unfreezes a transaction by Fireblocks Transaction ID and makes the transaction available again.
Endpoint Permission: Admin, Non-Signing Admin.



# Validate destination address
Source: https://developers.fireblocks.com/api-reference/transactions/validate-destination-address

https://docs.fireblocks.com/api/v1/swagger.yaml get /transactions/validate_address/{assetId}/{address}
Checks if an address is valid and active (for XRP, DOT, XLM, and EOS).
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Add jsonDidKey to VASP details
Source: https://developers.fireblocks.com/api-reference/travel-rule/add-jsondidkey-to-vasp-details

https://docs.fireblocks.com/api/v1/swagger.yaml put /screening/travel_rule/vasp/update
Update VASP Details.

Updates a VASP with the provided parameters. Use this endpoint to add your public jsonDIDkey generated by Notabene.



# Assign VASP to vault
Source: https://developers.fireblocks.com/api-reference/travel-rule/assign-vasp-to-vault

https://docs.fireblocks.com/api/v1/swagger.yaml post /screening/travel_rule/vault/{vaultAccountId}/vasp
Sets the VASP Did for a specific vault. Pass empty string to remove existing one.



# Create Trust Network Proof of Address
Source: https://developers.fireblocks.com/api-reference/travel-rule/create-trust-network-proof-of-address

https://docs.fireblocks.com/api/v1/swagger.yaml post /screening/travel_rule/providers/trust/proof_of_address
Creates a cryptographic proof of address ownership for TRUST network.



# Get All VASPs
Source: https://developers.fireblocks.com/api-reference/travel-rule/get-all-vasps

https://docs.fireblocks.com/api/v1/swagger.yaml get /screening/travel_rule/vasp
Get All VASPs.

Returns a list of VASPs. VASPs can be searched and sorted.



# Get assigned VASP to vault
Source: https://developers.fireblocks.com/api-reference/travel-rule/get-assigned-vasp-to-vault

https://docs.fireblocks.com/api/v1/swagger.yaml get /screening/travel_rule/vault/{vaultAccountId}/vasp
Get assigned VASP Did for a specific vault. Returns empty string vaspDid value in response if none assigned.



# Get VASP details
Source: https://developers.fireblocks.com/api-reference/travel-rule/get-vasp-details

https://docs.fireblocks.com/api/v1/swagger.yaml get /screening/travel_rule/vasp/{did}
Get VASP Details.

Returns information about a VASP that has the specified DID.



# Retrieve Trust Network Proof of Address Signature
Source: https://developers.fireblocks.com/api-reference/travel-rule/retrieve-trust-network-proof-of-address-signature

https://docs.fireblocks.com/api/v1/swagger.yaml get /screening/travel_rule/providers/trust/proof_of_address/{transactionId}
Retrieves the TRUST-compatible encoded signature for a proof of address transaction. Send this signature directly to TRUST for verification.



# Validate Full Travel Rule Transaction
Source: https://developers.fireblocks.com/api-reference/travel-rule/validate-full-travel-rule-transaction

https://docs.fireblocks.com/api/v1/swagger.yaml post /screening/travel_rule/transaction/validate/full
Validate Full Travel Rule transactions.

Checks for all required information on the originator and beneficiary VASPs.



# Validate Travel Rule Transaction
Source: https://developers.fireblocks.com/api-reference/travel-rule/validate-travel-rule-transaction

https://docs.fireblocks.com/api/v1/swagger.yaml post /screening/travel_rule/transaction/validate
Validate Travel Rule transactions.
Checks what beneficiary VASP details are required by your jurisdiction and the beneficiary's jurisdiction.
**Deprecation Notice** This endpoint will be deprecated soon in favor of the [validate full](https://developers.fireblocks.com/reference/validatefulltravelruletransaction) endpoint. Please update your integrations to use the  [validate full](https://developers.fireblocks.com/reference/validatefulltravelruletransaction) endpoint to ensure compatibility with future releases.
Checks what beneficiary VASP details are required by your jurisdiction and the beneficiary's jurisdiction.
Learn more about Fireblocks Travel Rule management in the following [guide](https://developers.fireblocks.com/docs/define-travel-rule-policies).

Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.



# Assess Travel Rule requirement
Source: https://developers.fireblocks.com/api-reference/trlink/assess-travel-rule-requirement

https://docs.fireblocks.com/api/v1/swagger.yaml post /screening/trlink/customers/integration/{customerIntegrationId}/trm/assess
Assesses travel rule requirement for a transaction by validating stored credentials and determining whether Travel Rule compliance is required based on amount, jurisdiction, and partner thresholds.



# Cancel Travel Rule Message
Source: https://developers.fireblocks.com/api-reference/trlink/cancel-travel-rule-message

https://docs.fireblocks.com/api/v1/swagger.yaml post /screening/trlink/customers/integration/{customerIntegrationId}/trm/{trmId}/cancel
Cancels a travel rule message. The TRM status will be updated to cancelled and the partner will be notified.



# Connect customer integration
Source: https://developers.fireblocks.com/api-reference/trlink/connect-customer-integration

https://docs.fireblocks.com/api/v1/swagger.yaml put /screening/trlink/customers/integration/{customerIntegrationId}
Connects a customer integration by providing API credentials. Stores encrypted credentials and enables the integration for use.



# Create customer
Source: https://developers.fireblocks.com/api-reference/trlink/create-customer

https://docs.fireblocks.com/api/v1/swagger.yaml post /screening/trlink/customers
Creates a new customer (legal entity/VASP) for TRSupport Travel Rule compliance operations. The customer represents your organization in the Travel Rule network and contains IVMS101-compliant identity information.



# Create customer integration
Source: https://developers.fireblocks.com/api-reference/trlink/create-customer-integration

https://docs.fireblocks.com/api/v1/swagger.yaml post /screening/trlink/customers/integration
Creates a new TRSupport integration for a customer. This establishes a connection placeholder between a customer and a Travel Rule partner. Use the connect endpoint to provide credentials after creation. You may optionally supply `customerIntegrationId` in the request body when your tenant is enabled for client-provided integration ids.



# Create Travel Rule Message
Source: https://developers.fireblocks.com/api-reference/trlink/create-travel-rule-message

https://docs.fireblocks.com/api/v1/swagger.yaml post /screening/trlink/customers/integration/{customerIntegrationId}/trm
Creates a new travel rule message with IVMS101-compliant PII data. Encrypts sensitive originator and beneficiary information before sending to partner.



# Delete customer
Source: https://developers.fireblocks.com/api-reference/trlink/delete-customer

https://docs.fireblocks.com/api/v1/swagger.yaml delete /screening/trlink/customers/{customerId}
Deletes a customer and all associated integrations. This action cannot be undone.



# Disconnect customer integration
Source: https://developers.fireblocks.com/api-reference/trlink/disconnect-customer-integration

https://docs.fireblocks.com/api/v1/swagger.yaml delete /screening/trlink/customers/integration/{customerIntegrationId}
Disconnects the integration for the authenticated workspace (tenant): removes stored credentials and deletes this tenant's integration record. The operation is scoped to the caller's tenant; it does not remove partner-side state for other workspaces that reuse the same logical customer integration. The record cannot be recovered after delete.



# Get all customers
Source: https://developers.fireblocks.com/api-reference/trlink/get-all-customers

https://docs.fireblocks.com/api/v1/swagger.yaml get /screening/trlink/customers
Retrieves all customers associated with the authenticated tenant. Returns a list of legal entities configured for Travel Rule compliance.



# Get customer by ID
Source: https://developers.fireblocks.com/api-reference/trlink/get-customer-by-id

https://docs.fireblocks.com/api/v1/swagger.yaml get /screening/trlink/customers/{customerId}
Retrieves detailed information about a specific customer by their unique identifier.



# Get customer integration by ID
Source: https://developers.fireblocks.com/api-reference/trlink/get-customer-integration-by-id

https://docs.fireblocks.com/api/v1/swagger.yaml get /screening/trlink/customers/{customerId}/integrations/{customerIntegrationId}
Retrieves detailed information about a specific customer integration.



# Get customer integrations
Source: https://developers.fireblocks.com/api-reference/trlink/get-customer-integrations

https://docs.fireblocks.com/api/v1/swagger.yaml get /screening/trlink/customers/{customerId}/integrations
Retrieves all TRSupport integrations for a specific customer. Returns a list of partner integrations configured for Travel Rule compliance.



# Get public key for PII encryption
Source: https://developers.fireblocks.com/api-reference/trlink/get-public-key-for-pii-encryption

https://docs.fireblocks.com/api/v1/swagger.yaml get /screening/trlink/customers/integration/{customerIntegrationId}/public_key
Retrieves the partner's public key in JWK format for encrypting PII data in Travel Rule Messages. Use this key to encrypt sensitive originator and beneficiary information before sending Travel Rule messages.



# Get required actions for a TRM
Source: https://developers.fireblocks.com/api-reference/trlink/get-required-actions-for-a-trm

https://docs.fireblocks.com/api/v1/swagger.yaml get /screening/trlink/customers/integration/{customerIntegrationId}/trm/{trmId}/required_actions
Retrieves the list of required actions (e.g., PII fields) needed to process the Travel Rule Message.



# Get supported asset by ID
Source: https://developers.fireblocks.com/api-reference/trlink/get-supported-asset-by-id

https://docs.fireblocks.com/api/v1/swagger.yaml get /screening/trlink/customers/integration/{customerIntegrationId}/assets/{assetId}
Retrieves detailed information about a specific asset by its Fireblocks asset ID. Returns the transformed Fireblocks asset data, raw partner response, and support status.



# Get TRLink policy
Source: https://developers.fireblocks.com/api-reference/trlink/get-trlink-policy

https://docs.fireblocks.com/api/v1/swagger.yaml get /screening/trlink/policy
Retrieves the complete TRSupport policy for the authenticated tenant, including pre-screening rules, post-screening rules, and missing TRM rules. Pre-screening rules determine whether transactions should be screened. Post-screening rules determine actions based on screening results. Missing TRM rules handle cases when screening data is unavailable.



# Get TRM by ID
Source: https://developers.fireblocks.com/api-reference/trlink/get-trm-by-id

https://docs.fireblocks.com/api/v1/swagger.yaml get /screening/trlink/customers/integration/{customerIntegrationId}/trm/{trmId}
Retrieves a Travel Rule Message by its unique identifier from the partner provider. Returns full TRM details including status, IVMS101 data, and transaction information.



# Get VASP by ID
Source: https://developers.fireblocks.com/api-reference/trlink/get-vasp-by-id

https://docs.fireblocks.com/api/v1/swagger.yaml get /screening/trlink/customers/integration/{customerIntegrationId}/vasps/{vaspId}
Retrieves detailed information about a specific VASP by its unique identifier. Returns VASP details including public key if available.



# List available TRSupport partners
Source: https://developers.fireblocks.com/api-reference/trlink/list-available-trsupport-partners

https://docs.fireblocks.com/api/v1/swagger.yaml get /screening/trlink/partners
Retrieves a list of all available Travel Rule Support integration partners. Partners provide Travel Rule compliance services such as VASP discovery, TRM exchange, and PII encryption.



# List supported assets
Source: https://developers.fireblocks.com/api-reference/trlink/list-supported-assets

https://docs.fireblocks.com/api/v1/swagger.yaml get /screening/trlink/customers/integration/{customerIntegrationId}/assets
Retrieves a paginated list of assets supported by the partner integration. Includes a flag indicating whether the partner can handle assets not explicitly listed. Supports cursor-based pagination.



# List VASPs
Source: https://developers.fireblocks.com/api-reference/trlink/list-vasps

https://docs.fireblocks.com/api/v1/swagger.yaml get /screening/trlink/customers/integration/{customerIntegrationId}/vasps
Retrieves a paginated list of VASPs (Virtual Asset Service Providers) available through the partner integration. Supports cursor-based pagination.



# Manual decision for missing TRM
Source: https://developers.fireblocks.com/api-reference/trlink/manual-decision-for-missing-trm

https://docs.fireblocks.com/api/v1/swagger.yaml post /screening/trlink/customers/integration/{customerIntegrationId}/transactions/{txId}/manual_decision
Accept or reject destinations stuck in NoTRM step without waiting for TRP webhook or policy timeout.



# Redirect Travel Rule Message
Source: https://developers.fireblocks.com/api-reference/trlink/redirect-travel-rule-message

https://docs.fireblocks.com/api/v1/swagger.yaml post /screening/trlink/customers/integration/{customerIntegrationId}/trm/{trmId}/redirect
Redirects a Travel Rule Message to a subsidiary VASP. This operation requires the partner to support nested VASPs functionality.



# Resolve action for a TRM
Source: https://developers.fireblocks.com/api-reference/trlink/resolve-action-for-a-trm

https://docs.fireblocks.com/api/v1/swagger.yaml post /screening/trlink/customers/integration/{customerIntegrationId}/trm/{trmId}/resolve_action
Submits required data (e.g., beneficiary PII) to resolve a pending Travel Rule Message action.



# Set destination travel rule message ID
Source: https://developers.fireblocks.com/api-reference/trlink/set-destination-travel-rule-message-id

https://docs.fireblocks.com/api/v1/swagger.yaml post /screening/trlink/transaction/{txId}/destination/travel_rule_message_id
Associates a Travel Rule Message ID with a specific destination in a multi-destination Fireblocks transaction. Matches destinations by amount and peer path.



# Set transaction travel rule message ID
Source: https://developers.fireblocks.com/api-reference/trlink/set-transaction-travel-rule-message-id

https://docs.fireblocks.com/api/v1/swagger.yaml post /screening/trlink/transaction/{txId}/travel_rule_message_id
Associates a Travel Rule Message ID with a Fireblocks transaction. This links the TRM compliance data to the blockchain transaction.



# Test connection
Source: https://developers.fireblocks.com/api-reference/trlink/test-connection

https://docs.fireblocks.com/api/v1/swagger.yaml post /screening/trlink/customers/integration/{customerIntegrationId}/test_connection
Tests the connection to a customer integration by validating stored credentials and attempting communication with the Travel Rule partner. Returns connection status and any error messages.



# Update customer
Source: https://developers.fireblocks.com/api-reference/trlink/update-customer

https://docs.fireblocks.com/api/v1/swagger.yaml put /screening/trlink/customers/{customerId}
Updates an existing customer's information. All fields are optional - only provided fields will be updated.



# Create user group
Source: https://developers.fireblocks.com/api-reference/user-groups-beta/create-user-group

https://docs.fireblocks.com/api/v1/swagger.yaml post /management/user_groups
Create a new user group. Users with the Viewer role cannot be added to groups.
Endpoint Permission: Admin, Non-Signing Admin.



# Delete user group
Source: https://developers.fireblocks.com/api-reference/user-groups-beta/delete-user-group

https://docs.fireblocks.com/api/v1/swagger.yaml delete /management/user_groups/{groupId}
Delete a user group by ID.

**Note**:
- This endpoint is now in Beta, disabled for general availability at this time.
- Please note that this endpoint is available only for API keys with Admin permissions.




# Get user group
Source: https://developers.fireblocks.com/api-reference/user-groups-beta/get-user-group

https://docs.fireblocks.com/api/v1/swagger.yaml get /management/user_groups/{groupId}
Get a user group by ID.

**Note**:
- This endpoint is now in Beta, disabled for general availability at this time.
- Please note that this endpoint is available only for API keys with Admin permissions.




# List user groups
Source: https://developers.fireblocks.com/api-reference/user-groups-beta/list-user-groups

https://docs.fireblocks.com/api/v1/swagger.yaml get /management/user_groups
Get all user groups in your workspace

- Please note that this endpoint is available only for API keys with Admin/Non Signing Admin permissions.
Endpoint Permission: Admin, Non-Signing Admin.



# Update user group
Source: https://developers.fireblocks.com/api-reference/user-groups-beta/update-user-group

https://docs.fireblocks.com/api/v1/swagger.yaml put /management/user_groups/{groupId}
Update a user group by ID.

**Note**:
- This endpoint is now in Beta, disabled for general availability at this time.
- Please note that this endpoint is available only for API keys with Admin permissions.




# List users
Source: https://developers.fireblocks.com/api-reference/users/list-users

https://docs.fireblocks.com/api/v1/swagger.yaml get /users
List all users for the workspace.

Please note that this endpoint is available only for API keys with Admin permissions.




# Attach or detach labels to/from UTXOs
Source: https://developers.fireblocks.com/api-reference/utxo-management-beta/attach-or-detach-labels-tofrom-utxos

https://docs.fireblocks.com/api/v1/swagger.yaml patch /utxo_management/{vaultAccountId}/{assetId}/labels
Attach or detach labels to/from UTXOs in a vault account. Labels can be used for organizing and filtering UTXOs.
Labels are applied additively — `labelsToAttach` adds to the existing label set and `labelsToDetach` removes from it. Neither operation replaces the full set.
**Note:** These endpoints are currently in beta and might be subject to changes.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# List unspent outputs (UTXOs)
Source: https://developers.fireblocks.com/api-reference/utxo-management-beta/list-unspent-outputs-utxos

https://docs.fireblocks.com/api/v1/swagger.yaml get /utxo_management/{vaultAccountId}/{assetId}/unspent_outputs
Returns a paginated list of unspent transaction outputs (UTXOs) for a UTXO-based asset in a vault account, with optional filters for labels, statuses, amounts, and more.
**Note:** These endpoints are currently in beta and might be subject to changes.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.



# Activate a Circle Gateway wallet
Source: https://developers.fireblocks.com/api-reference/vaults/activate-a-circle-gateway-wallet

https://docs.fireblocks.com/api/v1/swagger.yaml post /vault/accounts/{vaultAccountId}/circle_gateway/activate
Activates the Circle Gateway wallet associated with the given vault account. If the wallet does not yet exist it is created in an activated state.

 **Note:** This endpoint is currently in beta and might be subject to changes.

</br>Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver.



# Activate a wallet in a vault account
Source: https://developers.fireblocks.com/api-reference/vaults/activate-a-wallet-in-a-vault-account

https://docs.fireblocks.com/api/v1/swagger.yaml post /vault/accounts/{vaultAccountId}/{assetId}/activate
Initiates activation for a wallet in a vault account. 
Activation is required for tokens that need an on-chain transaction for creation (XLM tokens, SOL tokens etc).
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Assign AML customer reference ID
Source: https://developers.fireblocks.com/api-reference/vaults/assign-aml-customer-reference-id

https://docs.fireblocks.com/api/v1/swagger.yaml post /vault/accounts/{vaultAccountId}/{assetId}/addresses/{addressId}/set_customer_ref_id
Sets an AML/KYT customer reference ID for a specific address.
Endpoint Permission: Admin, Non-Signing Admin.



# Attach or detach tags from vault accounts
Source: https://developers.fireblocks.com/api-reference/vaults/attach-or-detach-tags-from-vault-accounts

https://docs.fireblocks.com/api/v1/swagger.yaml post /vault/accounts/attached_tags
Attach or detach one or more tags from the requested vault accounts.
Endpoint Permission: For protected tags: Owner, Admin, Non-Signing Admin. For non protected tags: Owner, Admin, Non-Signing Admin, Signer, Editor, Approver.



# Bulk creation of new deposit addresses
Source: https://developers.fireblocks.com/api-reference/vaults/bulk-creation-of-new-deposit-addresses

https://docs.fireblocks.com/api/v1/swagger.yaml post /vault/accounts/addresses/bulk
**For UTXO blockchains only.**

Create multiple deposit addresses by running an async job.
- The target Vault account should already have a UTXO asset wallet with a permanent address.
- Limited to a maximum of 10,000 addresses per operation. Use multiple operations for the same Vault account/permanent address if needed.

**Endpoint Permissions:** Admin, Non-Signing Admin.




# Bulk creation of new vault accounts
Source: https://developers.fireblocks.com/api-reference/vaults/bulk-creation-of-new-vault-accounts

https://docs.fireblocks.com/api/v1/swagger.yaml post /vault/accounts/bulk
Create multiple vault accounts by running an async job.      
- The HBAR, TON, SUI, TERRA, ALGO, and DOT blockchains are not supported.
- These endpoints are currently in beta and might be subject to changes.
- Limited to a maximum of 10,000 accounts per operation.

**Endpoint Permissions:** Admin, Non-Signing Admin, Signer, Approver, Editor.




# Convert a segwit address to legacy format
Source: https://developers.fireblocks.com/api-reference/vaults/convert-a-segwit-address-to-legacy-format

https://docs.fireblocks.com/api/v1/swagger.yaml post /vault/accounts/{vaultAccountId}/{assetId}/addresses/{addressId}/create_legacy
Converts an existing segwit address to the legacy format.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Create a new vault account
Source: https://developers.fireblocks.com/api-reference/vaults/create-a-new-vault-account

https://docs.fireblocks.com/api/v1/swagger.yaml post /vault/accounts
Creates a new vault account with the requested name.
**Note: ** Vault account names should consist of ASCII characters only.
Learn more about Fireblocks Vault Accounts in the following [guide](https://developers.fireblocks.com/reference/create-vault-account).
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Create a new vault wallet
Source: https://developers.fireblocks.com/api-reference/vaults/create-a-new-vault-wallet

https://docs.fireblocks.com/api/v1/swagger.yaml post /vault/accounts/{vaultAccountId}/{assetId}
Creates a wallet for a specific asset in a vault account.
Learn more about Fireblocks Vault Wallets in the following [guide](https://developers.fireblocks.com/reference/create-vault-wallet).
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Create new asset deposit address
Source: https://developers.fireblocks.com/api-reference/vaults/create-new-asset-deposit-address

https://docs.fireblocks.com/api/v1/swagger.yaml post /vault/accounts/{vaultAccountId}/{assetId}/addresses
Creates a new deposit address for an asset of a vault account.
Should be used for UTXO or Tag/Memo based assets ONLY.

Requests with account based assets will fail.

Endpoint Permission: Admin, Non-Signing Admin.



# Deactivate a Circle Gateway wallet
Source: https://developers.fireblocks.com/api-reference/vaults/deactivate-a-circle-gateway-wallet

https://docs.fireblocks.com/api/v1/swagger.yaml post /vault/accounts/{vaultAccountId}/circle_gateway/deactivate
Deactivates the Circle Gateway wallet associated with the given vault account.

 **Note:** This endpoint is currently in beta and might be subject to changes.

</br>Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver.



# Get a vault account by ID
Source: https://developers.fireblocks.com/api-reference/vaults/get-a-vault-account-by-id

https://docs.fireblocks.com/api/v1/swagger.yaml get /vault/accounts/{vaultAccountId}
Get a vault account by its unique ID.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.



# Get addresses (Paginated)
Source: https://developers.fireblocks.com/api-reference/vaults/get-addresses-paginated

https://docs.fireblocks.com/api/v1/swagger.yaml get /vault/accounts/{vaultAccountId}/{assetId}/addresses_paginated
Returns a paginated response of the addresses for a given vault account and asset.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.



# Get an asset's public key
Source: https://developers.fireblocks.com/api-reference/vaults/get-an-assets-public-key

https://docs.fireblocks.com/api/v1/swagger.yaml get /vault/accounts/{vaultAccountId}/{assetId}/{change}/{addressIndex}/public_key_info
Get the public key information for a specific asset in a vault account.
Endpoint Permission: Admin, Non-Signing Admin.



# Get asset addresses
Source: https://developers.fireblocks.com/api-reference/vaults/get-asset-addresses

https://docs.fireblocks.com/api/v1/swagger.yaml get /vault/accounts/{vaultAccountId}/{assetId}/addresses
DEPRECATED!

- If your application logic or scripts rely on the deprecated endpoint, you should update to account for GET/V1/vault/accounts/{vaultAccountId}/{assetId}/addresses_paginated before Mar 31,2024.
- All workspaces created after Mar 31,2024. will have it disabled. If it is disabled for your workspace and you attempt to use it, you will receive the following error message: "This endpoint is unavailable.
- Please use the GET /v1/vault/accounts/{vaultAccountId}/{assetId}/addresses_paginated endpoint to return all the wallet addresses associated with the specified vault account and asset in a paginated list.

Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.



# Get asset balance for chosen assets
Source: https://developers.fireblocks.com/api-reference/vaults/get-asset-balance-for-chosen-assets

https://docs.fireblocks.com/api/v1/swagger.yaml get /vault/assets
Gets the assets amount summary for all accounts or filtered accounts.

Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.



# Get Circle Gateway wallet info
Source: https://developers.fireblocks.com/api-reference/vaults/get-circle-gateway-wallet-info

https://docs.fireblocks.com/api/v1/swagger.yaml get /vault/accounts/{vaultAccountId}/circle_gateway
Returns the Circle Gateway wallet information associated with the given vault account.
**Note:** This endpoint is currently in beta and might be subject to changes.
</br>Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.



# Get job status of bulk creation of new vault accounts
Source: https://developers.fireblocks.com/api-reference/vaults/get-job-status-of-bulk-creation-of-new-vault-accounts

https://docs.fireblocks.com/api/v1/swagger.yaml get /vault/accounts/bulk/{jobId}
Returns the current status of (or error for) the specified vault account bulk creation job.

**Endpoint Permissions:** Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.




# Get max spendable amount in a transaction
Source: https://developers.fireblocks.com/api-reference/vaults/get-max-spendable-amount-in-a-transaction

https://docs.fireblocks.com/api/v1/swagger.yaml get /vault/accounts/{vaultAccountId}/{assetId}/max_spendable_amount
**UTXO assets only.**

Retrieve the maximum amount of the specified asset that can be spent in a single transaction from the specified vault account.

**Endpoint Permissions:** Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.




# Get maximum BIP44 index used
Source: https://developers.fireblocks.com/api-reference/vaults/get-maximum-bip44-index-used

https://docs.fireblocks.com/api/v1/swagger.yaml get /vault/accounts/{vaultAccountId}/{assetId}/max_bip44_index_used
Retrieves the maximum BIP44 address index and change address index used for a specific asset in a vault account (BIP44 standard).



# Get the asset balance for a vault account
Source: https://developers.fireblocks.com/api-reference/vaults/get-the-asset-balance-for-a-vault-account

https://docs.fireblocks.com/api/v1/swagger.yaml get /vault/accounts/{vaultAccountId}/{assetId}
Returns a specific vault wallet balance information for a specific asset.

Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor,
  Viewer.



# Get the job status of the bulk deposit address creation
Source: https://developers.fireblocks.com/api-reference/vaults/get-the-job-status-of-the-bulk-deposit-address-creation

https://docs.fireblocks.com/api/v1/swagger.yaml get /vault/accounts/addresses/bulk/{jobId}
Returns the current status of (or an error for) the specified deposit addresss bulk creation job.

**Endpoint Permissions:** Admin, Non-Signing Admin, Signer, Approver, Editor, and Viewer.




# Get the public key for a derivation path
Source: https://developers.fireblocks.com/api-reference/vaults/get-the-public-key-for-a-derivation-path

https://docs.fireblocks.com/api/v1/swagger.yaml get /vault/public_key_info
Gets the public key information based on derivation path and signing algorithm.
Endpoint Permission: Admin, Non-Signing Admin.



# Get UTXO unspent inputs information
Source: https://developers.fireblocks.com/api-reference/vaults/get-utxo-unspent-inputs-information

https://docs.fireblocks.com/api/v1/swagger.yaml get /vault/accounts/{vaultAccountId}/{assetId}/unspent_inputs
Returns unspent inputs information of an UTXO asset in a vault account.

Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.



# Get vault accounts
Source: https://developers.fireblocks.com/api-reference/vaults/get-vault-accounts

https://docs.fireblocks.com/api/v1/swagger.yaml get /vault/accounts
DEPRECATED - Please use `/vault/accounts_paged` endpoint instead.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.



# Get vault accounts (Paginated)
Source: https://developers.fireblocks.com/api-reference/vaults/get-vault-accounts-paginated

https://docs.fireblocks.com/api/v1/swagger.yaml get /vault/accounts_paged
Gets all vault accounts in your workspace. This endpoint returns a limited amount of results with a quick response time.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.



# Get vault balance by an asset
Source: https://developers.fireblocks.com/api-reference/vaults/get-vault-balance-by-an-asset

https://docs.fireblocks.com/api/v1/swagger.yaml get /vault/assets/{assetId}
Get the total balance of an asset across all the vault accounts.

Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.



# Get vault wallets (Paginated)
Source: https://developers.fireblocks.com/api-reference/vaults/get-vault-wallets-paginated

https://docs.fireblocks.com/api/v1/swagger.yaml get /vault/asset_wallets
Get all vault wallets of the vault accounts in your workspace. 
A vault wallet is an asset in a vault account. 

This method allows fast traversal of all account balances.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor, Viewer.



# Hide a vault account in the console
Source: https://developers.fireblocks.com/api-reference/vaults/hide-a-vault-account-in-the-console

https://docs.fireblocks.com/api/v1/swagger.yaml post /vault/accounts/{vaultAccountId}/hide
Hides the requested vault account from the web console view.
This operation is required when creating thousands of vault accounts to serve your end-users.
Used for preventing the web console to be swamped with too much vault accounts.
Learn more in the following [guide](https://developers.fireblocks.com/docs/create-direct-custody-wallets#hiding-vault-accounts).
NOTE: Hiding the vault account from the web console will also hide all the related transactions to/from this vault.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Refresh asset balance data
Source: https://developers.fireblocks.com/api-reference/vaults/refresh-asset-balance-data

https://docs.fireblocks.com/api/v1/swagger.yaml post /vault/accounts/{vaultAccountId}/{assetId}/balance
Updates the balance of a specific asset in a vault account.

This API endpoint is subject to a strict rate limit.
Should be used by clients in very specific scenarios.

Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Rename a vault account
Source: https://developers.fireblocks.com/api-reference/vaults/rename-a-vault-account

https://docs.fireblocks.com/api/v1/swagger.yaml put /vault/accounts/{vaultAccountId}
Renames the requested vault account.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver.



# Set an AML/KYT ID for a vault account
Source: https://developers.fireblocks.com/api-reference/vaults/set-an-amlkyt-id-for-a-vault-account

https://docs.fireblocks.com/api/v1/swagger.yaml post /vault/accounts/{vaultAccountId}/set_customer_ref_id
Assigns an AML/KYT customer reference ID for the vault account. Learn more about Fireblocks AML management in the following [guide](https://developers.fireblocks.com/docs/define-aml-policies). Endpoint Permission: Admin, Non-Signing Admin.



# Set auto fueling to on or off
Source: https://developers.fireblocks.com/api-reference/vaults/set-auto-fueling-to-on-or-off

https://docs.fireblocks.com/api/v1/swagger.yaml post /vault/accounts/{vaultAccountId}/set_auto_fuel
Toggles the auto fueling property of the vault account to enabled or disabled.
Vault Accounts with 'autoFuel=true' are monitored and auto fueled by the Fireblocks Gas Station.
Learn more about the Fireblocks Gas Station in the following [guide](https://developers.fireblocks.com/docs/work-with-gas-station).
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Unhide a vault account in the console
Source: https://developers.fireblocks.com/api-reference/vaults/unhide-a-vault-account-in-the-console

https://docs.fireblocks.com/api/v1/swagger.yaml post /vault/accounts/{vaultAccountId}/unhide
Makes a hidden vault account visible in web console view.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Update address description
Source: https://developers.fireblocks.com/api-reference/vaults/update-address-description

https://docs.fireblocks.com/api/v1/swagger.yaml put /vault/accounts/{vaultAccountId}/{assetId}/addresses/{addressId}
Updates the description of an existing address of an asset in a vault account.
Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Create a new Web3 connection.
Source: https://developers.fireblocks.com/api-reference/web3-connections/create-a-new-web3-connection

https://docs.fireblocks.com/api/v1/swagger.yaml post /connections/wc
Initiate a new Web3 connection.

* Note: After this succeeds, make a request to `PUT /v1/connections/wc/{id}` (below) to approve or reject the new Web3 connection.



# List all open Web3 connections.
Source: https://developers.fireblocks.com/api-reference/web3-connections/list-all-open-web3-connections

https://docs.fireblocks.com/api/v1/swagger.yaml get /connections
Get open Web3 connections.



# Remove an existing Web3 connection.
Source: https://developers.fireblocks.com/api-reference/web3-connections/remove-an-existing-web3-connection

https://docs.fireblocks.com/api/v1/swagger.yaml delete /connections/wc/{id}
Remove a Web3 connection



# Respond to a pending Web3 connection request.
Source: https://developers.fireblocks.com/api-reference/web3-connections/respond-to-a-pending-web3-connection-request

https://docs.fireblocks.com/api/v1/swagger.yaml put /connections/wc/{id}
Submit a response to *approve* or *reject* an initiated Web3 connection.
* Note: This call is used to complete your `POST /v1/connections/wc/` request.

After this succeeds, your new Web3 connection is created and functioning.



# Create a new webhook
Source: https://developers.fireblocks.com/api-reference/webhooks-v2/create-a-new-webhook

https://docs.fireblocks.com/api/v1/swagger.yaml post /webhooks
Creates a new webhook, which will be triggered on the specified events

**Endpoint Permissions:** Owner, Admin, Non-Signing Admin.




# Delete webhook
Source: https://developers.fireblocks.com/api-reference/webhooks-v2/delete-webhook

https://docs.fireblocks.com/api/v1/swagger.yaml delete /webhooks/{webhookId}
Delete a webhook by its id

Endpoint Permission: Owner, Admin, Non-Signing Admin.




# Get all notifications by webhook id
Source: https://developers.fireblocks.com/api-reference/webhooks-v2/get-all-notifications-by-webhook-id

https://docs.fireblocks.com/api/v1/swagger.yaml get /webhooks/{webhookId}/notifications
Get all notifications by webhook id (paginated)




# Get all webhooks
Source: https://developers.fireblocks.com/api-reference/webhooks-v2/get-all-webhooks

https://docs.fireblocks.com/api/v1/swagger.yaml get /webhooks
Get all webhooks (paginated).




# Get notification attempts
Source: https://developers.fireblocks.com/api-reference/webhooks-v2/get-notification-attempts

https://docs.fireblocks.com/api/v1/swagger.yaml get /webhooks/{webhookId}/notifications/{notificationId}/attempts
Get notification attempts by notification id




# Get notification by id
Source: https://developers.fireblocks.com/api-reference/webhooks-v2/get-notification-by-id

https://docs.fireblocks.com/api/v1/swagger.yaml get /webhooks/{webhookId}/notifications/{notificationId}
Get notification by id




# Get resend by query job status
Source: https://developers.fireblocks.com/api-reference/webhooks-v2/get-resend-by-query-job-status

https://docs.fireblocks.com/api/v1/swagger.yaml get /webhooks/{webhookId}/notifications/resend_by_query/jobs/{jobId}
Get the status of a resend by query job




# Get resend job status
Source: https://developers.fireblocks.com/api-reference/webhooks-v2/get-resend-job-status

https://docs.fireblocks.com/api/v1/swagger.yaml get /webhooks/{webhookId}/notifications/resend_failed/jobs/{jobId}
Get the status of a resend job




# Get webhook by id
Source: https://developers.fireblocks.com/api-reference/webhooks-v2/get-webhook-by-id

https://docs.fireblocks.com/api/v1/swagger.yaml get /webhooks/{webhookId}
Retrieve a webhook by its id




# Get webhook metrics
Source: https://developers.fireblocks.com/api-reference/webhooks-v2/get-webhook-metrics

https://docs.fireblocks.com/api/v1/swagger.yaml get /webhooks/{webhookId}/metrics/{metricName}
Get webhook metrics by webhook id and metric name




# Resend failed notifications
Source: https://developers.fireblocks.com/api-reference/webhooks-v2/resend-failed-notifications

https://docs.fireblocks.com/api/v1/swagger.yaml post /webhooks/{webhookId}/notifications/resend_failed
Resend all failed notifications for a webhook in the last 24 hours

Endpoint Permission: Owner, Admin, Non-Signing Admin, Editor, Signer.




# Resend notification by id
Source: https://developers.fireblocks.com/api-reference/webhooks-v2/resend-notification-by-id

https://docs.fireblocks.com/api/v1/swagger.yaml post /webhooks/{webhookId}/notifications/{notificationId}/resend
Resend notification by ID

Endpoint Permission: Owner, Admin, Non-Signing Admin, Editor, Signer.




# Resend notifications by query
Source: https://developers.fireblocks.com/api-reference/webhooks-v2/resend-notifications-by-query

https://docs.fireblocks.com/api/v1/swagger.yaml post /webhooks/{webhookId}/notifications/resend_by_query
Resend notifications matching the given query filters (statuses, events, time range, resource ID)

Endpoint Permission: Owner, Admin, Non-Signing Admin, Editor, Signer.




# Resend notifications by resource Id
Source: https://developers.fireblocks.com/api-reference/webhooks-v2/resend-notifications-by-resource-id

https://docs.fireblocks.com/api/v1/swagger.yaml post /webhooks/{webhookId}/notifications/resend_by_resource
Resend notifications by resource Id

Endpoint Permission: Owner, Admin, Non-Signing Admin, Editor, Signer.




# Update webhook
Source: https://developers.fireblocks.com/api-reference/webhooks-v2/update-webhook

https://docs.fireblocks.com/api/v1/swagger.yaml patch /webhooks/{webhookId}
Update a webhook by its id

Endpoint Permission: Owner, Admin, Non-Signing Admin.




# Resend failed webhooks
Source: https://developers.fireblocks.com/api-reference/webhooks/resend-failed-webhooks

https://docs.fireblocks.com/api/v1/swagger.yaml post /webhooks/resend
Resends all failed webhook notifications.

Learn more about Fireblocks Webhooks in the following [guide](https://developers.fireblocks.com/docs/configure-webhooks).

Endpoint Permission: Admin, Non-Signing Admin, Signer, Approver, Editor.



# Resend webhooks for a transaction by ID
Source: https://developers.fireblocks.com/api-reference/webhooks/resend-webhooks-for-a-transaction-by-id

https://docs.fireblocks.com/api/v1/swagger.yaml post /webhooks/resend/{txId}
Resends webhook notifications for a transaction by its unique identifier.

Learn more about Fireblocks Webhooks in the following [guide](https://developers.fireblocks.com/docs/configure-webhooks).

**Endpoint Permissions:** Admin, Non-Signing Admin, Signer, Approver, Editor.




# Get whitelisted ip addresses for an API Key
Source: https://developers.fireblocks.com/api-reference/whitelist-ip-addresses/get-whitelisted-ip-addresses-for-an-api-key

https://docs.fireblocks.com/api/v1/swagger.yaml get /management/api_users/{userId}/whitelist_ip_addresses
Get a list of the whitelisted IP addresses for a specific API Key
- Please note that this endpoint is available only for API keys with Admin/Non Signing Admin permissions.
Endpoint Permission: Admin, Non-Signing Admin.



# Returns current workspace status
Source: https://developers.fireblocks.com/api-reference/workspace-status-beta/returns-current-workspace-status

https://docs.fireblocks.com/api/v1/swagger.yaml get /management/workspace_status
Returns current workspace status (Beta).
**Note**:
- This endpoint is now in Beta, disabled for general availability at this time.
- Please note that this endpoint is available only for API keys with Admin/Non Signing Admin permissions.

Endpoint Permission: Admin, Non-Signing Admin.



# Freeze
Source: https://developers.fireblocks.com/api-reference/workspace/freeze

https://docs.fireblocks.com/api/v1/swagger.yaml post /workspace/freeze
Freezes a Workspace so that ALL operations by ANY user are blocked.
You should only perform this action when the workspace faces imminent risk, such as when you have a security breach.
To unfreeze a workspace, the workspace Owner must submit a request to Fireblocks Support.
**NOTE:** 
- This operation can only be performed by the workspace Admins - Your workspace continues to receive incoming transfers during this time.
Endpoint Permission: Admin, Non-Signing Admin.



# Get workspace
Source: https://developers.fireblocks.com/api-reference/workspace/get-workspace

https://docs.fireblocks.com/api/v1/swagger.yaml get /workspace
Returns the workspace ID and name for the authenticated user.




# Changelog
Source: https://developers.fireblocks.com/changelog



<div>
  <iframe title="Fireblocks Changelog" />

  <script />
</div>


# Constructing Encrypted PII Messages for Exchanges via Fireblocks
Source: https://developers.fireblocks.com/docs/a-developers-guide-to-constructing-encrypted-pii-messages-for-binance-via-fireblocks



## Introduction

For institutions using Fireblocks to transact with major exchanges like Binance and Bitstamp, correctly constructing and transmitting Personally Identifiable Information (PII) is critical for ensuring regulatory compliance and the successful processing of transactions. Sending PII requires a robust security model that goes beyond standard transport-layer encryption.

This guide provides a practical, compliance-aware walkthrough for developers and compliance officers on how to structure the PII payload, handle the necessary encryption, and correctly format the `transaction.extraParameters` object in the Fireblocks API. It breaks down each field and explains the specific data requirements based on key global jurisdictions.

For step-by-step instructions on completing Travel Rule compliance through the Fireblocks Console UI, see [Travel Rule compliance for exchange transactions](https://support.fireblocks.io/hc/en-us/articles/20851702645404-Travel-Rule-compliance-for-exchange-transactions).

<Info>
  ### Note for Compliance Officers

  This document details the technical data structure for compliant PII transmission. The core obligation is to ensure your institution has a robust AML/CFT program that includes counterparty due diligence, risk-based transaction monitoring, and adherence to the specific data requirements of all relevant jurisdictions.
</Info>

## Core concept: End-to-end encryption of PII

It is critical to understand that you must **never** send raw, unencrypted PII in an API call. The `piiData` object detailed in this guide represents the plaintext data structure that must be encrypted *before* it is submitted to the Fireblocks API.

Fireblocks documentation indicates that PII encryption is a **manual implementation step** that developers must handle. This ensures a secure, end-to-end model where only the intended recipient (in this case, the specific exchange entity) can decrypt and access the sensitive user data.

## Exchange PII data encryption guide (RSA-only model)

### Overview

We only support **RSA-only encryption** for PII data transmission. Exchanges do not accept hybrid encryption (RSA + AES). Using hybrid encryption will result in failed Travel Rule submissions or empty compliance data.

### RSA-only encryption model

This method encrypts the **entire PII data payload directly** with the recipient's (exchange's) RSA public key, without generating a separate AES key:

**Process**:

1. **Direct RSA Encryption:** Serialize the PII data to JSON and encrypt the whole payload using RSA-OAEP with SHA-256. Each value should be encrypted (see examples below).
2. **Single Encrypted Blob:** The result is a single base64-encoded string containing the encrypted PII data.
3. **Send in API Call:** Pass this encrypted blob in the `piiData` field of the Fireblocks transaction request.

## Production usage: Encryption & Transaction creation

In a production environment, you must fetch the public key from Fireblocks to encrypt the PII data.

### Example: RSA-only encryption utility

```typescript theme={"system"}
import * as forge from 'node-forge';

/**
* EXAMPLE: Encrypts each PII field individually using RSA-only encryption
*
* This is a simplified example showing how you could implement individual field encryption.
* Each developer should customize this approach based on their specific needs.
*
* @param piiData - PII data object to encrypt field by field
* @param publicKey - RSA public key in PEM format
* @returns Promise<any> - Data with each field encrypted individually
*/
export async function encryptPiiFieldsIndividually(piiData: any, publicKey: string): Promise<any> {
 /**
  * Implementation approach:
  * 1. Takes the original piiData object
  * 2. Recursively walks through each field
  * 3. Encrypts each string value separately using RSA encryptWithRSAOnly()
  * 4. Returns the same object structure but with encrypted values
  *
  * Note: This is an EXAMPLE implementation. Developers should customize
  * this logic based on their specific requirements and data structures.
  */
  // Simple recursive function to encrypt string values
 async function encryptPrimitives(obj: any): Promise<any> {
   // Encrypt all primitive values except null/undefined
   if (obj === null || obj === undefined) {
     return obj;
   }
  
   if (typeof obj === 'string' || typeof obj === 'number' || typeof obj === 'boolean') {
     return await encryptWithRSAOnly(obj, publicKey);
   }
  
   if (Array.isArray(obj)) {
     return Promise.all(obj.map(item => encryptPrimitives(item)));
   }
  
   if (typeof obj === 'object') {
     const result: any = {};
     for (const [key, value] of Object.entries(obj)) {
       result[key] = await encryptPrimitives(value);
     }
     return result;
   }
  
   return obj;
 }

 const result = JSON.parse(JSON.stringify(piiData)); // Deep clone
  if (result.extraParameters?.piiData?.data) {
   result.extraParameters.piiData.data = await encryptStrings(result.extraParameters.piiData.data);
 } else {
   return await encryptStrings(result);
 }
  return result;
}

```

### Example: Creating an exchange Fireblocks transaction with RSA-only encryption

```typescript theme={"system"}
import { FireblocksSDK } from "fireblocks-sdk";
import { encryptWithRSAOnly } from './encryptWithRSAOnly';
import { piiData } from './piiPayload';

const fireblocksSDK = new FireblocksSDK(privateKey, apiKey, baseUrl);

async function getExchangePublicKey() {
  try {
    const credentialsResponse = await fireblocksSDK.getExchangeAccountsCredentialsPublicKey({
      // Specify exchange exchange account ID
    });
    return credentialsResponse.publicKey;
  } catch (error) {
    console.error('Failed to get exchange public key:', error);
    throw error;
  }
}

async function createExchangeTransaction() {
  // 1. Get exchange's public key from Fireblocks
  const publicKey = await getExchangePublicKey();

  // 2. RSA-only encrypt each PII field individually
  const encryptedPiiData = await encryptPiiFieldsIndividually(piiData, publicKey);

  // 3. Build the Fireblocks transaction request
  const transactionRequest = {
    operation: "TRANSFER",
    source: { type: "VAULT_ACCOUNT", id: "1" },
    destination: { type: "EXCHANGE_ACCOUNT", id: "exchange_account_id" },
    amount: "100",
    assetId: "BTC",
    extraParameters: {
      piiData: encryptedPiiData
    }
  };

  // 4. Send the transaction
  const result = await fireblocksSDK.createTransaction(transactionRequest);
  console.log('Exchange transaction created:', result.id);
  return result;
}

createExchangeTransaction()
  .then(() => console.log("PII transaction sent successfully to exchange."))
  .catch(console.error);

```

## Real-world PII data example 1: Binance - Compact French withdrawal scenario

This example demonstrates a common real-world scenario where minimal required information is provided for a withdrawal.

* **Transaction Type:** Withdrawal
* **Jurisdiction:** France (FR)
* **Relationship:** ThirdParty
* **Entity:** Individual

**Scenario:** A user is making a withdrawal from their exchange account to another beneficiary, where the user is an individual located in France.

### Example: Before encryption (Compact PII data)

```json theme={"system"}
{
  "extraParameters": {
    "piiData": {
      "type": "exchange-service-travel-rule",
      "typeVersion": "1.0.0",
      "data": {
        "beneficiary": {
          "participantRelationshipType": "ThirdParty",
          "entityType": "Individual",
          "names": [
            {
              "primaryName": "John",
              "nameType": "Latin",
              "secondaryName": "Doe"
            }
          ],
          "postalAddress": {
            "country": "BE"
          }
        },
        "beneficiaryVASP": {
          "vaspCode": "BINANCE"
        },
        "transactionData": {
          "withdraw": {
            "isAddressVerified": true
          }
        },
        "originatingVASP": {
          "vaspCountry": "FR"
        }
      }
    }
  }
}

```

### Example: After encryption (Compact encrypted data)

```json theme={"system"}
{
  "extraParameters": {
    "piiData": {
      "type": "exchange-service-travel-rule",
      "typeVersion": "1.0.0",
      "data": {
        "beneficiary": {
          "participantRelationshipType": "DkGFzfPCLi3SNl6BrrS1C4X/DmuqfVvU83iczY+pDgamI3FUTmzghoGvtjERSH6uqKo3h9gwAWQN8mYV7PGdgkV7cnSS6/H4CNJWV7BlN63RU7DmsmVdHoGbA0F7GnriQvKlnTFPU/CCXJDcsaXG7cHa5VtST8rw+acw73fnUpwUnGMLnw0QOUoYrvu6eGo+BX1aZu+Ve0hrhJTcYXXfnvekkXWCLxDu8AYltJSy4YgzsFNvHb3JyOOuPvJg3qka2NfVrzRXv+7pQy6c4eyErfBJZ6T8i/WXsu9gVZXuOC24wtZi99pP2XGz9ogW2hv9edmEUTitZXneWm26sbtwN9jBPVh4ZRLfGg9wxV1fN/g6MPVbil7Ilu6olO9gRlPj2GUyFIfNPFAziqGEw7CEFvPlQuLv5n2/Pbh98jS/sGANwjKZhXBKyy79WLs/HDVZw6E99+Vxf786HdmIc4MEyj+AELhqcdp8uF0D1/xA+hDFiDpcZjV3JASX9b8EPOaxix9P7TdPepoFoZo4fJFQtaXvAunnsYiG2bE/NareEjLZvqcHadeaCdy29sXCmxeaj1v5hL5GZJFFkBEUa9QLcle0YXQQa3ukkc1W0tChIeGwSEY/qNW/FZ5jg3Pqm8gpdwGzd0gZk/JO8YDIthtTRdgm7zjydIxVZGChTO/h4WM=",
          "entityType": "CvnHs/CzrfdTpGukJXmJH+88n2cW9C0Ezc6HtJtDzN6+e7dk+GoGrK/ia9Kptncrh7Q+6AVHR3pmrJFH10Y8kwxLoNOmJkPtNDJLoVPDSxAn4So7Jw0mA+OGXu8J1e/b1v9u4g3/2L5373MURnsrMydU0vt77YaBZgmZo0dtukLE4kGTnW2lUKexdeRs6NR99r+VQNYG38XGi2/OAjwvBPIAxfmaXBoNMCVda0JZkjlweezwIGL8theV+RMPtQBm8mUsBpbcIiBLAFA4/pQgCKVHZuUMkfaSXh6zPBga6hQu4N0fhLxTj1VwW1Mocd373ifUAn5mziMB4tunObI6jy91s0zunmIajZeHqxIvxci1sMEI6RXnuzKfbkadUzM9cyUMjnzkrQk5q5VuurxfZRqFHuw9Ikq8dNUavAetwgJipUi2aTVh0+uVgZ84QKusJ08LqD3N4k6eghZwIDUkCFXNZnK1reK+oIqGcbs8y0r+Vmr1zh5GukA55+yqRJXu/YxAlS3HIwp+HnhSvM8Wz1O5/PgCHm2iRcP3+pCYWJltkPoKPzynurAN6I1tGSak7+AiPwiJsd5sqdNylR5eFR4N28U61vYhk4nebsvvI5J+7M9+f25hs4hDloV+bmj0wzN3QnCRS3RyaPg91fdCo2iTR5PTuLvjVJ0GX/h1674=",
          "names": [
            {
              "primaryName": "SpDXvmGFXH3qe0jAVZeinBniH18VBPsAqnLz+SxidNd9Hh6XKbs10cHMPoda4Yga3dDLXSZTRMb9hJPbsYlanFgWpcIW6rq4KGeK/Q9LiN1gVSGwZrXMD2Jx/3+hPVcSUqYqGiirZpoeQqJUTzmJvglRCWDDNbE88jFcQ+XEvj0v9tC1rrHrxrowe1QaxFeOt8HMl2PjGVzUGCD9QdRsG0DbBa4To49EsvXl6qCMr11pioCWzAVgYxRJU5HlfikbsU00dxXTVVaHAFGfGgeTSBBVpNLTvUuk7Q4CW4TIa9PiDYiZsT9KW3X0tjXLs0xflrUXMXUWDC3bVfEMcFtM75YyOFrMY4IhGfyND6o+4MyeqC7LmYc09o9wmheiRS/l3J77SNc8w7tlqoSgvVVb45TDpBtf611SQ8GnCQ9rTg9rKROwPXA58micxFKrgVVYfY+E0uo90kzs/Hfw0OohrC/3vS6d3ocXAEp8FEtmCvyRxK+xgTv3obIzL6eVqI2TBDkkyjT3gGBrbS0a8GPZSKUw9W0cNnYjxZ/rxF1xBUG1gg+cE7St2yNwQ9m3gcneoB8U3AA5y/f5Zw7iz5ekAmMdrUFWf5ENNodNNv66KVNQLwpSIWeHiVkr5mqEIooAJDaFDaYKw6A2GRJzU+ZQ7ca3rOumleUq6kXfQcCmpr4=",
              "nameType": "UFvT9EbXqfGJGH3UPsXtRbwyi9VDb3JgEyGXDM6x4Pkk/R8nlfEVnKFSmt0LSU1Vnzl/k8pjMsLcap33RDENMWTRAfjasnqDK7uZCNO8m37SBZiTLmTYrX3k5V4hF0p6SQqvltPV4cye4AwALxZKtc95jzsfJUxgylaXbmuR8+W8RoHZrhid4YCFmarpC8xCz0fcrWrbRtfV/wuv4wHotkX7SQJj0pf31xsRjfDYIV6Fo0tlnhI1JTdVh+ztE9e76OcRdlpM2Fk7UM42+CXUSvvO3iP4E1ot5K7O+u+3a8pcVWNbAIycLlz79fz2LFXiQ7jc63Yg/sG/P2yQqk/ivDT/ZWjSoCNlB8oi7VDpL2ir0Xwh1+D6I9n6f1G4jc0Fkqr0DP00P93jpmBQzqPi2V7TBrnIwxPnQeEzj1SXE0ENMbj2P/PGeinGW34h6/0WFKyyOubMqLnvG5lPUusFPA7NFY7NdS/1OAU/y4J52R9YFWkW9o2jdn9G3iLbjNKx8g0yRbnT0sTXql9E+VCv2HPYS1Wuoqo/S1LhG6j0y9ugUCS1+advbxHm0/4ZD5zJ4+5FHIlH8s5+CJ7/FGFsRRN/R2jAW9GSqdzczzYm4X24l8cn4xHRWR2XO0jqlYmoH8sBMrZVgfvJnDy4KotlthZT5ooIOQJY+58x6gXnUL0=",
              "secondaryName": "KjXjKySekOb13IvuP4ainsMzGCmxK9CUeVI6VMLp3MYxz1zFbZBq95v8Ly5TBoH+RL176yioR5o4l0NHEgL8+vjjSeau/o9cHRZK16VjrGmF2MmpuFeD4NPN9IAsD8M+xeq2X06EK5ns9ebuGCADAiEGIEbBfnjZcJpUhnlllTptbuzBoeaK/k1545XMA30f6SuR+6hGxDBX6rX+vYJOvEBhSfK9km1mJ2y89it38QY2eRcDD8Li4nuLPaKrqzWGcN+Lp8KrII604D9ewUj/a9LfefrZBB5H+gL0XI2h7rVfiYNBJghXakfunS595nBNTjbxz5spuDxE7k0EqhW6t2N70FzyNVUjmxo0nFCSRViONXuiyhddZfRcIeTXJf1hXp0/cujqvOkbdrl2yPXl2pZ0/XZaCHfx76unLaLHUcFKCVpib5FXi5i7C6Gd+8QuBliUiUAdWUJGpcqQLkz7/zALdZLqISZ5WLyKENIt/Rdo/GzQ35CZVCe9TtIIIEHq0wmMArCB73KFzMrrJStefPA4tNtbWM4iwPmahoSWFYl96pIclGNdRdFNTF1jM4VgfboB27YG/6YFJMcWYJvXR5gkbeYUgRRe/q/B7iFvGKdNIrCe34iCGEZ8/hNs+ljBFmcxEbOiFjoAg3sOe3WKnpLaI5jaFyel4Jar7XkKAxg="
            }
          ],
          "postalAddress": {
            "country": "o9MZlFzz76bKfw3giyekwbhpZo3Nn1+o/NTzFQnSWaozIKa9xoAiOE8IvmU9tkT3yZLYOeaX6F6Am2hyzpers9lMHr2Ha1pOFnreQUKE9x2fEFZyAXv625Hz8Ja+ZeywlkbAok1atpc7+JC8GD7quErQwC/qgZ8yzW926JyQ38sZPHY+W0IM2sc7S0KoL77Yu5+gixQPbiUdMfYjimuRRwW+4NzsSOWUcZdQ+NB/khz/7CDc9q6tqYFuHg17sFo6QO2rQSpcgfzDrqmdCX0ZnSRBf5FZG2I0tHA2t24UuRJJGNIU66jr9b4h2pJFWpE+UwSmx8skyI+0DCk4P8gxhS6ZhQ93TGpSgpI5rWW7pJLLzlmEeVF5bm7zYQg2eu0HTUi3DEyUHfW0g/LpGEfLCudwSXRjGUUXI7tSV6BxC4EY7T5pt6RkNrnTdjSo8B4azdv06BqVjYzeJFwXL7Zo4khoaQETQf3PiTlwMQw/WQox/65IfpKfM1KhHtPFCiG1v358q2FO/S0yV6hcKNVRNfrZXG5v32DDZ8S/K8Cs0+XBEBl8OxHo581uahVKONzb2VwBGTxcXouWHVLEq928wDKnhAPvUmFMkHtkpmdSxOWr0qoMUD9WQFvkYqm9RXeczoN/RTsAqMSr1InoqfmqU9TZBCdjiMDnhe4ggAvFKkU="
          }
        },
        "beneficiaryVASP": {
          "vaspCode": "VTiePIZHqIn6q17/SWZ8fdpWga72UvaVjvwBs2PQ/R5DyN6GwDOC6msAFr3+1h/14PwFfawmWXpWu6xmKm7iyUHpMmmnnPlUKSjlNeb+k2QVTHPXYT6eboT3V8gav47mIBfv+XMm2AtXfLRGpWF5or6Q929QqxXgOOl89xwdYxRFnboSB/T9coZ2lonf15F/n+8XEMmE/g77iGwlY5pIi7VmAhi0MIJthRgxIXbuB5yzL1MtaPQr5a4tTY9J0WR6MlMjkeGODV0VyVX90aajDgTv4ocB0TLwGkC4GRTLBsdyGD3jkpp0Lion5ip+BT0MhYg2xvshef/GJ4cob2bZy+10GAdWUbid2n66HQUJjIyPuPtAZLzf/hZiL5dsgykRz/FpT291eoTeQ0V6RIYLBGSqSPkc+n56Pqum0c47Oan5078R9/k5YLpTX9DD464m5pHSPPh/sg5TeBydd31bHJy0EfwGMJPCK4yjaTlK2At6vLzhJ+BZ6au8oWoDvbCbS2bh1jJh5x/V/4HAkv/h7woGb3OY+z/GazfFEhCBAC4WdvGExHqbQhbhcOlbZr3Wt6b3Vx1U06u+acwLUwt3P9yuufAvQkjxYp60nSKKJxjj0Vnk/Qjf1vCXab8y7siEXthVO1MqTsozGtgCqzHw8aNtg7rEAykSd8AHyyjRqz8="
        },
        "transactionData": {
          "withdraw": {
            "isAddressVerified": "g6y8yN5t+5GrJfFkhqrOz5dfJjTRiIO2qYH+OXsRNaTrtoJjPwda7OOnAmuSp2yBdRFTPKxgcWzBo5fofQvOyl64RdrWmtKFkWBDAtJUzoIE5s6yk5qp+wi5+gNdo4bHmrKaJXaOsaKrO+o+kfg0ySt8K1qrsZK7AFa+yqwabUmiDwRdElromyDpACv2n2ol/1W2Oh87nAHIW8fUWsEiuI8nM83X5Do6ZlsUGjTXRhIVVuu4Yd9Jkeld1OSe2iSETFb2XEy0ml5viU5H31AJ1RQaNCvBVpzu/1fe6YgB05MQjTiL01/kn2cT3PlZ5WaKZxXQuuoNAR0y5eeJPiwfdBCCrL7Z8KJpsCRspRBXxXoUFkN56XUfBHaRwoeA4flSLfpmfKYSNcATUr13sd/fH7n6wk6mU8Zl0CJJkoWQaUCk0cM54wxWGeRtgSqPAteBsAw2olBpRrK5fIvi5YWd7ez88CtlIZwfsAI7WaMtZMTTlC8E9BdRhJVjX4neadpVfNYoiVPLiEzfo9gK5jqyeuFgYG1fAhWYvKVk+rw2Csn5iqO/AXhkEQht1riw4BnrfymFGJY8+9hrz+KTUZndG1Xw5GbFlEuitqg9yRGCUdhJVALoSeJ71YCMFIWPoq/3IRogFTqEBtzkP4N9ohUBlZVxPXZhZFc+Axe6SsaH+Wo="
          }
        },
        "originatingVASP": {
          "vaspCountry": "ppyFQ37QrH2GUityQet2+PMZdkqbgxv3tM7hiokv0TLUjZikj6TT/8jaDXumx2itIDKYr+N7zhvPtM9cm9mMWTjo2D7m3LOPNXu0uRPOCNWOQAACOlx21rC5Sc+yUazLq7e8kyi2wlF3ngH9DIjlVeQ6aGZk5q6HEWm4pvuqOaLA6h4qLsLB5VLg4ygEOw0Lqmc04Y5pKRkrB8f4MrAQtzUjwaQabUXheeAncakIKlRGYfOWYnyqKjJ+X7WD2dK95nNHahORltLeZkPVpHz7ERNqlDtRWlplbBT08PZ0pv3IVWxkFDPc1UB5NVGl0PhkdLSmCLvQe8DwmeBMZzC8o0Ks+vLlmJZbcbjYFmosaH5ZlbJh01Azs1xLaYqhNF/NwFSbYqL5vm7GsKS6wXgKCDJkikyIXG1UavKhL2HdrOIXOv07E/ox0pH7Sn8rs3p6aVM5s0fQKV5nRaM9s5ixbC3VAX5uVKG0mBSu9G//Q/RrjUXCdcaKD4lKw9hzmX1linKJCnCjEjwaDpRtPXledumNFt7CWn+dcvjG7xhOro/EeTpTcT1IqcPw+D0NnZLddNyx/xrJC5YMU3yZ7tKHLsvVZyotC6UTTjBQJUCLt0rpEvd7stZtpp/Nn5i1KeSwYbXIaEMthNZQaO63gMi8od/R0LCcYeEHInZ5qYhD1n0="
        }
      }
    }
  }
}

```

## Real-world PII data example 2: Bitstamp - Compact deposit scenario

This example demonstrates a common real-world scenario where minimal required information is provided for a withdrawal.

* **Transaction Type:** Deposit
* **Relationship:** ThirdParty
* **Entity:** Individual

**Scenario:** A user is making a withdrawal from their exchange account to another beneficiary, where the user is an individual located in France.

### Example: Before encryption (Compact PII data)

```json theme={"system"}
{
  "piiData": {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Individual",
        "names": [
          {
            "primaryName": "John",
            "nameType": "Latin",
            "secondaryName": "Doe"
          }
        ],
        "dateOfBirth": "1.1.2000.",
        "postalAddress": {
          "streetName": "Oak street",
          "buildingNumber": "23",
          "city": "Boston",
          "postalCode": "02108",
          "country": "US"
        }
      },
      "originatorVASP": {
        "vaspCode": "9bfe73a6-d38e-4d14-8089-8d5a06ac7ec0"
      }
    }
  }
}

```

### Example: After encryption (Compact encrypted data)

```json theme={"system"}
{
  "piiData": {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "UIQ+McWqzwP0DFpWd2Sm3vfduvK6N/S6lWlihgoGTE0AkBGbmqkMzgsES6rqOl5fcliHVYOh/9CdTn3tNCQXKr8yCGnBiiY9rF9ANSECbmJkm5b0h1i1Amdqna3il995Q0Lit2Zq2an5SP0vglj/3fd5F9BRehQOoBhW9+p5gYWxB3ICukdVHO0L+YLtzrR3nY0L8LESmipZ95wmJii9puiULgeEV8Xe58MyK/DHHuerzjlpvA2T18qp/p/y0aHnSFuWlGQum0BhWZ3xIOb8g/pwHszYaBzSo2tfOYg8Gc10/7emg98mlLybVdKtioKu2Jsdjj0v6BHzlp8O05UmGXecpWc0LWRCUENOV4ui+YF9dBMY/MArJNVd5E5eIuT7VmayQ7eEpsyX/ymJCPLwDUFnL9Ibl0SW4/Y17Nmz+jjTrWqXroyUgqTuYFZZNf6IRHx89/Jr7d5LlfFRHzwgDiolPRM6gfC8/5hgc1JZzk9kh1ym75SRgIVnGKADwCz8rtwfxMRIK+X91l7bn5nNb19oEoiX8hfQi+o2VSX1gUhIZQjyPz4FFdfDsyF90WQdZrCxn8irf9fNrstxQZcJicYTXnxvSFMHnqWF8P459qatcTAWpujsQnHAaXPa5Oc/fMX3Sst/t4f/onKAa/s/t0sfOwlaaGFHwMZpBgUMeDI=",
        "entityType": "c1WbvG7ievrsGv06wb7dghictBBkSJv5E76e+mXeUeO6NXOZuTzL1PiJoqUAM0h9o2fup01V+uIQWqavYmPbiooFofAGaLNhKC1kK4I39xuG7w9hEYQwh5+5J0J6yLOkVe5+pJD1d56fuV6RW7kikIpcTmINSwBMMNVfdhcFei4paBxNLuICMafMM1YzHHxa844qDpP0L0YYSz3rfJQ8Fj6UFGsg+EXqMwxSSWD9tOO8w5yfzc264BndN8byU0c7cXJtgRTkTXppCcMJtXzvRRYCQ/1mYNqcaOOgXlv4XkUfe2+/+PhSzMw7mI2rhkMwxLOpchiNDmhtglvK7kVW+3jbebzvgfhPyVWcjVweWjtgWAznfhX62U8mWWfLWMhJX++8IInh5bZfdnBAzp6hRDK7u1cxRUeBwMvdvy1rPXmUnNpsgLEXwb1WNGH3MhCbDKSo4e0J0E9/SooV4ZZJDaMcpF48rEfBy5I1GEBGzZcJBuOO1FkwqUH8Y160+1FPMe/vdy9Lee7C0r7u2ztQmU4z5m07k30mizQJly3u8bEAVpktoGuc9ujpYG35K15gybOCb7ll6+5Lzl5n4YKqM1Gfk8GSRdNlxD1MaVgKtwajIvpWTSZn416znBQWcEW1Tnezf15c5G9OM/B7LKiDhJ9OMI1fYZvGFf3Nk6A27oY=",
        "names": [
          {
            "primaryName": "JnR/jKh5u+x1BTUT5j/H6S83firFCO7gYEfVe+BBA0K7Ng3KoPA54VUt/6oXAoXQP0JZIeli3sffmnPB74XC99OTjbSyEFm2V2hGff3rAJAJ9b15PhFSDS0AbQKAV+BZeucy/nl5gOyh7mo/eEqSzEjfclj1zAYQsfDbuiMATl85vgsFqb4Nt+EwmmyiWPcUUXmsFg/eHJsNi/F0U3jsyGhD3djcloJF88GKV8dfF2XteQYMkegbLlBLPwXx5Ey+9v1fsx9FcB6oN8eu4yMISuxF86KPXMHgX59ZD2Rgd218d2gx3Fdnm0AeHq0+Sc5tJ+/URRYvMhF59+ubnIb3cIqOyslkLAngYtwK3M6aUAxpTs6tIbrBDd1QMFZDLugHgwXaTV1tRxY7bCM75VUmi0TIJnF3T5kgPtEAaiia1VbH+amxYHk7q7V1jVeevJv+TpwSZ4eiBBpx6pZEVP4iHgTnqFHgzjtX9MdQaG76LEED6HQjeIs3ikFNrpxn1YZMkaTFnuP5NiUELN823gSYVtIyUC/Z4gjxRD3X+tOrGcUq+ntYP9zj7ievPsc4JGHHF3H/tfFqbC2xHLD4cTkeLanOgpGkJkAX39EUqmxwmmyp2JRPXcly0PE++RRY6TjvX6JCbeFRrr4ycFq6sIT0p3LdfNqAjm0gyqqBwnYgEXY=",
            "nameType": "AUZXCG+yLWovnc574QwAsz3g0Yb0TnH5C41oODS2J0buSDBrdjXWoyCH3L5a+43lWBGKjqDEO5IlbNpffwRXN2yoLG6KS4z2amFDzt8wKmq5WBqZRC6RcM5AVWsqDRv+HT/44CmIXJlHDKZC3h1AGPQ0Efh6YbhTpdtIxXddzFi+PlhApnkXtyUa7KhWQQ+kQ4H+WifDFu2oSJ/2CXkpT76Sbj6O3glrBa7JRg0lIRNgV8+Xcph/8Ws3mTthkYYgac15YzO023qf3aU1N8BOyEwQuyyZUc64BTzK242uv3c170hSU2DSLAgDEJ8F4UW1w9zTp+DW/uSe7oe8l/rUSN/58QFYK+MAPAdGVA44j++sF8IuzImbXXI6ku/t8XXUFr/ToD7Vf5wgKRbujwEbiXNnGDyVDwiQWQaP20lKlhJjeYijEnWbUHslIiY4KSUQv5XYYnc7tWSt1Iy7D8XPtvO1Vp0Hg2hOGSqlwGHIN5DQY9h1QAAguSBsWf34f7J+PnSUI8mK3itmgx46/OGrYwuKwAeM15eL/afLItPJyqtvu/zAtOgo90MwK+/z2b8VJFzxyt0e1tr8c1XqfX+9y4Ohp4AMrvgaWKaNfdqVbWUjMVndWbh9SYABGyh2jC+azjlkxG3G/M8ncj9EVYs+NFCjFj878QZCovF0S409zek=",
            "secondaryName": "SJUSYKA5w5XAeS0Oz/wmhMsGqvZ2J94iJ7jXUC2BIbf+1rtzlD5B4x77fxWXGh96dDgQ6Cr+COVz7ebvSStefJDRbu65jFDcQRC0y6cnfaeU9DrERrmcbobA1LWm0/xkGhYQIEZnGaxoxYZOn8r65PD4l7Mua7g4low3lhjBGkzsNbtrp5zlGoh8QhYXpzpj0Z7oMGEcCmesx0Tq/lb4Mp7Uhc+4/njT0rFk5Ogw9G0y8VD3UEFSxhThwT8FnKwdksyNHDuTm+sJ17ozd2dN47mka8tSMEp7NWayT5rTj5CMM+P8MOV3D1EEODOaBMo6XULCsApgzDOdtXDnjCMwWJqNzYNts16fqWktzpBy6Z8iB+IDPqMbpoE1GPLSvd6RIgcjocp8uJ0wWOXxVNXV1pH0I5jOPEcM/4Q3LA/kH/3Stjdvbyx7alYkRP4shuUP9ZWUdAPwAklRrtgdSaItOhm9wuuRzTzIu8OlFBsfd53kpiYKZN3FrzeQ/XeQNwvqj5yTH7BSadyG89vXyt/JObPjK87VtY2Tk8EWOnRtCIoZ8YQXnONMaYheJgje26i/ZYI1jUTneL7OgBwkePzRBgRgsISQ7NVgIqbZInEmLuaH7dpUT5pyAB4lFQD70vR79R5+S3iEx4UbcN9CtPYlmLVXw8SsuMQ4z1SI4zIm258="
          }
        ],
        "dateOfBirth": "rvku0/k2oXk51TcqHmWJRXGNtdEtU0ruluSIOj0XytFfuQPRUomhekaGJtm2GSR9WgEa+KS4hrwtZ+87TgL45tIvEXkANurXFtIaI2thsiSfWDGqCHaFi5n/cLCUesnThU8GGvgrzlucZIWH6eQMkbVSn3HVZmuUbIDMbfieL4NI1l+T63Q6vbxRtMzfzJMDI3hiRn+7LS5BG0uLNsJ7r2cc2NR5hFht6nfKKiLn2SIL+ndoWYzVKy7vDEeNT6frbMeICCGdJVSxX+vLdhSAx29qYlQ+75iPJ4bMi5PPuJd7yp8l/14AUbYkBqjC+9tTu2zEKH0UPm1IqxHdpMpN+OJ05J+9tMOL3S/jRahqk45P/0rDuWBkyvRRsANw6Ajn/rIplw05QJA1H4k/wbT0gYU6iVF7chXA7xFS2897TtSISsKzHy3ux9sFRbeyWs2jTicuNNllECYtgs98LrAbKEewFyJ4r3vNJdNOirte1xAIUD8/BAYGKUb+74f/Yb32DlgOe8+emGtrTQZbyzqjNrnXVulONXaS0DQJ6wRMMtyOwothBZg49Jw9hjqQPMpNRU4Icpd05mmMkKkJJ8uEuDUWA5CZYHrsmYTTysxdrYUDa+BNwgL7V3zp9geZHbdoEyaPGTSFNQKiC/WL5NC4O9r+sM55QHRBRoc63+zt58U=",
        "postalAddress": {
          "streetName": "HILYP3i4FW252ELMopPjbC9t2U91+cXyfCCsaJwHkx01L/qlL8UX+h8YAuY0zsW8WEv7H9h0ZRDKqDZRdQ5zeL9hLgQUnWNoSi3ACIQR1qsa7oMoVNfhWn0tgTSKYuvkWYIuSGV5J4vwBJysNXPbtzft4bBxR2VW+nP0kxiDqslkF1mxa5phy1uoJZHauTAZIxpoatFmBTAEldSpa5IxoVrWQj4fYjQiYPAjAF46ssLVQZwK2EGnexFlc6oH2XAZtTw38XthOt7aWpPrJpLFl7iQgpVPhALfINQwgff6Y3o3XQhY2Jr/IW6P11mOUd/FrpjIo8jwrnk/5i2S52z2fotgXS7mjinm6HvqCDaUCujX+3Bo967wmm1ENAaH5Bg3OssCA+k/VXI7o7fAQ7fLUfnZcLxxKR/8108DN+Q1UrULeyk5f2IA+xTztxQHbnUCRMYfJO3nP91odKF3xkBnms/OVlNBcTRB4dBr8I0CdmmKv/3/4WU1BoHnlwMN29bPagXAVp2mHcj+J2HSoN3viC/Om0QITmD2hToX1smpBg1UQYTX3URu6uJEWiUqQZft4q9DSMgyXT6/rBskpTPGuWR1J+ULWXF2Id1ULzrRgPuszxx+a4SK8iXtWFeMGh+Y3o3SDoqXyVcigqDYJpIzuomJzVgzowrUBbwdmL3sFAM=",
          "buildingNumber": "flSWDJwwX8yDTOYbG0+D7PNQQm84plW7n12yP1gTVTL0dNt5DlWqgGCs8fXfVKH1uqCc73s7jqmX+uMej0Grb7Cm33fp330+113OnjZUnCxLRI2jXls6PFBKO/poRMyUQql/waDIfnM4bJ230cu26Ki5B0D0mDrMEkb9IIkILp+7E4lkttWmZDAez/CG4eO3PJ8NiYr15YAm4O5VCJYbgHLSHC/11+pOiinMHzySrTrDM6D/gmZ1TnqD51Y9CbgS6VWIlwOOjwSGpUEc4rUXDTedoYxr440KYLdbDpl4mBB0Fckz+UuyRxoTzyfOBYcWMdBYIm8EeMq3g2aQFfP8u326v1vmVIrKG4m+dITy/H8XZ7GJVpVm95NAtblRxQPNXSIieSQZyuKP4WHU3XlaSvP9GK519mNHPAsApOZpLLH+RPnqnCXMGcr/ZQ5tvRQWvOkO5N4HQjeVUHvrCZ5lJo8aYXFN0qKMi2T/icCm58YPHGEKj7gQM18ZtYh5SJCH+VAVbBt2c+49sCKX+A8BLeVEvfYkgIF8qCNQlal/6+LSMmMzv0MO/751CpnqpGLvEsqfx9/lgaSvxZ3RSJ2Ac1faBMAhiKP8DMoLeTNm4ooKjFBRzoP69JUPeKPZ+N7TvhoyJgL7Z/6HQ+Hs2dwsTW6W/tBwpRyxvBOjOJgwey4=",
          "city": "W8NUxiw2sMgIR5tCM75oTyaI//HTejVm/ZtYf8eec15C9J4TrUSqKKZ9By9A44nMLTQEkwF6uGNS1msS24fq48I6X2dV219icb1WR/r/+wW8HAFi0qjofqYV4hslIhF3lfVLP4R79i9uDYwMhLYcRxMFCXDMTe6zEg0b+qav/7y/6XS6DzUeHUpZhnDjQ65kNpQoAyNiw+1vXaqZCJf+fIlbSDxLGaLAZe5ue26wishv3rmqQdrALmdz5VlMG5tDrz3FakK/vup4SMMsKJHYmFCQnq+3lssB8gHsf/6swa/FMTKVEY6dOTeelcQzawfUu7O/Q1Rkb7O0ht8LquyxNgXIt2MSn3hvEucI5w/e1ZSLkf/mI+RmTsqAccR18mQRL4KAlgYtkWWBAr240k1svWfsG1F2BxcvLaqZiGOY99mjLjY3zkTWDyKHJOb5+DvdedyVaJkIoFAnuCL/iAP3U7vrmYnuFCmnlu2TsqWp2UDD59VhDo8xMl8sAuiqrRZnUDMrqMKOOAvHOvJUKWDG7iV7u8RnYO3vqMLCsIx7bVzpYs8pydCUaNesVrZYOkUGiUoCGcSQyy5O5XcfBzqo1UEY9lfkEvYDKIOOjpt4xZCc62faJv3NH0g+4w+4Fjzyozks+PgjyA0roqp+iaVSRSGeg6x/YDuvkY9W/yaOHGg=",
          "postalCode": "jycssk3S7asgoMs2mqT9HDTGQjcbEbnKWF5OFMbekXIjG98dexKySSzODLTYBfAbGcWTpA3oH+PxUzHeyZY8NJ6RNhvHjhmacsoDp+Yt9aHl9htJfwDHvkpB42sJb90suPZ3gJIOOLs2Ac1oesjKv7pdotqMZ+3YAT0xunzSAFNGrU00WW9jSZ7qavzq84QzrkhjrnlxvrKaon4C/D136kxNopcorrF3SYxRG+bD3pFbEahfnDl5pW8+uZelUIdqn95iDHWgy3Wtkh6T1jIi21rBItZ9sXmfas7x4Lp81Pw/0sid817y11pydGlK3k9rbbxPYem+zclV9QMLW4qQMZBgKaHGAvpjBdtx+OmtlibJMxKZStWCo0oJof+BZOo5LS+FKRDFCFM2sP49xnsFMjRjuPjYfAupHEoQ4rx5x9RJLED8glix+ozeyMCWN9ybW4j03qzu0hY7kk+rOCpH8C2bQaxZkDXxO+iiFhdN92/CSoQsx0dtffWe322slEuZulcXUTZ/Htk7WsQZgnqNbc77Pffrrj8ralVPY3UEnqwjtfVHkx/R1ChJNvUOHCb+VZR37iYM924iXnaZRhF0htRyNDm/VKNT8wnJgEOU0sK6QhYJTz1IOsms0M/r8/tE4EtTuIlXFHeM/ekm0a15sGDzwPmfw6y6GWhWqFVWz2A=",
          "country": "cC8LkS0FvsXXe1p04SeEqim35LDfW46Unhb6xXQbg8OBWsMSjDxA2xwOiYuRu33HfTObf3o5CHiHL96iJXp8Ou1IWs07s8kr80U1DpThBbe90a0vk0CfQLk1TYN5k/SGz8x6cyUyqPSqOGWOVFBcvqgCWJ0C8upZT1U1jYLW+um7dqiC84a32othiZkHiwyMnY6AlwG/kcIsrXxNpmoH7MH9mGxXqHg9y1reL9f8HWw9N48OBKeHHU83DiFqnR5ZvSMWRlyQko+wVh/a4gLkfWNtKcWysTnhw6dU85rXoz+CUJdjdDCYUmn40EYF/hQixj9hTOvY/aNv2Uh2IjQWDhify3iel5UGHMv0bi7amWrPkh+37rtmyteZM9oYRRusgKgTW9M2/Gm4kq/f8IarCGOcgLeXbxT1qnjAbCZXNiflC1nKVmLFqnH10SL+l/KDdIJLQZK4JX8oM22W6hP49ALqkPp5ONyNHGoJtUVgk9lbWGSMmp+U2Niye7TlC7G1XpCsJlt6zfYUsUG3tOrkJM6LsOlXHf0rrH6wLF4j7APCahQ3Ax9WvC/lFarY11tEm1mf+VwBT6LwljA1gOWmMHAI1jHDrcNaNKl7mSF4NzLaZdw7ktHqYL2wm78XKKPaI8Exi0kGrwpgdohw8FnByK/eioAr9RRfvAbFxXR+lhI="
        }
      },
      "originatorVASP": {
        "vaspCode": "Qx/d5nSqgW3i/MllXNJ/k6uaQvNZJ3r/egre0TjzsEtR8lILIe9fh3HTd5cAT68Gl5T2K+tjeMAR9hUfRe4sMtybpsUV5Z/yEclIqMg9L90Jqtmx8irLHvzaOS+3o1SoWEiFbn6p5lXPkElCHaj3ruVCXBqw0+rXUXCbVFgG6NFKJ4ZvkaJsxO2+n9h9JDEpGRqTR3KpRudfwxiC7afC03xUrkh0OYeegZ5YlrEMDrUGjKG3lFjjbGZL0JAywh/RnA6fG4dXW9VuD+0/x0XtZpG/6YSUVmQJnwAEhfGZnk2CboL34XQUpsKA+/naLP44UNjkbhsC6y4VPg5WdAv5/S4sTdKj5Wx/RUhDKissldSEdxHKSfogbESvllZxctqA68sliuiB6y8Pj10WDNruoTU5N+kwOa/9asLhDOrYykclvtNNwGUgG4yg2jSz1N/pr2J8BOqzRV6jQRjKeHgrtSnglgZS59/isjz/TjNR4AHHJbaH6wsJl0VAQMCuphv/zaVZwBU81M9uUxHyg1wV2HT6nKTf8H8U6mWuH/SwuLMYa8seS9f4yH4GbAoGLkLObVwGtbxvTH3mcgPPzQqzOujmhEO1OeftUXgnBHjns4mUnvV+TireHTMtZMv0MR8tG3Bff8pg/zymrlaLKzjfONALN2kQ+c4QO7lIO6S7WOo="
      },
      "beneficiaryVASP": {
        "vaspCountry": "fVJdps6ZNAOhABTF6lAF7hui3dGL4ijQfNinhE70UAEBVoy5r5CQ98f0iu5wjkDk8lxmskDBf2ltHVzFk90RMG5VHQASWMLXwv6NU+xp0k2tp1AFRUX3CdmsWgtoTRAMPHCmJLvwIJGkNBZDGWx84kbzIwosZ0mKfjvrm7UnHGBTSa+aisJ+DglQsBp6MxCxgQLbDx+6+MwTarrt7FQ5l5CwUEs9+3yabQWrHLjmrwHtYEGAlIjtkm0FDKskqkpysEwC7BPt5drL8UTq2GdH9UMU93a6LixJZlZpARZPWEEwPu+v0BjcIfFCBDcG+Vo+3u3lQjaJ8wm2hdIdF8Rbjg7vb1b+IFHN6Gnk4Y7zxZ/lJkKO17RxntNGXCesymKodwXKNXZt0mJMegmyXQpG1srfiRCZ7pFf3HcuKsbiXEkvd+V+//60rkGJGxFoQ4FZcbJqD4dKA3E4cVmdMDPq6EzzO/d0s4X1DyXQ8+6HuQ9Ai7YgvaPQIrYIRKWntG8tEDKCrEyQN+7WQzejmYU3sQe4+M2okH7gBoe8o3GpNmqPE/JxUO2t5tdbLieiySa+vX3T6N2DBc8003miuUMXMDfX8Jf0gi7Ynp8PXamtIj2T3ovbwTDGokdZ3PC0tsrKBHbwAiLxfk7K5S9BXObMGnHgIvpv2H1lydJjrI4XYf4="
      }
    }
  }
}

```

## Real-world PII data example 3: Bitfinex - Compact withdrawal scenario

This example demonstrates a common real-world scenario where minimal required information is provided for a withdrawal.

* **Transaction Type**: Withdrawal
* **Relationship**: ThirdParty
* **Entity**: Individual

**Scenario**: A user is making a withdrawal from their exchange account to another beneficiary, where the user is an individual located in France.

### Example: Before encryption (Compact PII data)

```json theme={"system"}
{
  "piiData": {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Individual",
        "postalAddress": {
          "streetName": "Oak street",
          "buildingNumber": "1",
          "city": "Boston",
          "postalCode": "02001",
          "country": "US"
        },
        "names": [
          {
            "primaryName": "John",
            "nameType": "Latin",
            "secondaryName": "Doe"
          }
        ]
      },
      "beneficiaryVASP": {
        "vaspCode": "did:ethr:0xf2bd35dc59cbbe3efb15a5bd411ac84e7c86d25a"
      }
    }
  }
}

```

### Example: After encryption (Compact encrypted data)

```json theme={"system"}
{
  "piiData": {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "EI4heAsEl/uBuHDmuthkAZdcERQiczkG+Lpf7K9vycAGvwMFfiXgYIxbui/7lPcUEG+LQQQKmPBlVa4CRSrIPjI+bpP1C6QoNXR2sctaP3vnIQInoUD5REvoUrcY95qd47uIvBGAIV5TIdHug2RN3QE4S7bY1jaP+ZuDi2w58rdUlMC7C/suHNLiGBX/rN1SwC/g6WiqCyoJ6HmqnTObD+s4WXmWxSqNnl2TIzE7DoaFVtSiv895QI5os3hHrxX832mRFZDlO+QDJJKA7c44dSAHo4DjOdVUKWxW0h+RMrgi3FiDuLdwVPbYPD+sRCCNmsM67TVuoOWVbnbZfolY/EsXCTcWeqJ+Ickh4Z1pNfHqm2MUC7KivhLws6D3YULoPQCkpJvF4NWXN0uFvzQ191DoG3pl/T6u2eh/rU0N3u7VwYS92uVaNHKL0OpsYDMP3zH6Gb2sNx4bZCtyJEHIQqhdK8+ISASVmrO8Jrr/RVDe7c7mFWUXFpQZBUpE87qKxk2Zk344Optfj9aoUJ6gFBQ9SqdWXo9y2iWfgpIQoFsI9amTneCG/3PfxG2bCA1qg0xwukM8rugi1OtsBUdGX8f5Eeqtbw/h79z0/3kbhnHaQOE6SzAga9Q4xhDm5USJGp6qeeFWe6WoxVKI0O1SnhEhFuxt/nNCa2pB379DLSY=",
        "entityType": "jX80pPFp9Yd71BNS3xPXvyghZT0u1z9x559uftSr0NItpPH26ZP8JNcSLsqOr7VRYQVCdaMrHFso0zDqPimaLxIj3SooElegtRrK/XltEZ7zNVR2EScuTWKDWabjzT2CzWno2/Ba+q8O5A4iZ/cNoZ688CcSzMHOSxvt9KsQar6A/wUjAG48CEj27cVL33IADF3SVH2Da+/fs1uuSdp/omUJ7Fa8dG8oX/8KdEJrYDnWHlzYLvSjEsv3TGZlbwV1fGwJ/2kvr6gcN2+8uxyh/r5+TsoX9SfuIfoa4GxHcCTcrYnXOPAqQXsCwcpq0+oLZ6nX/vO9OoW9yo74zaNLLW3ItaFYHdj9Lhrnnk7mgD1gsWxRM6DLEimKng7jzfimtfngrexqmJA+mtwD+/1NKe0PfghOxZInLbZIAktz9HFriWkol7U3fCgaF1/UGEmADMlZQayFsYSDmuA/19MsOIq3mtTX4k1DVAgHevgBubzYoEhSbhbBjfKV41GX16rkG3hVtzKJmD9SeGFRwr3c559J1/8AriRLoyMTuyYJ9agABc6fc5fpTh/OFiWXTyB2GpLeoBluf/pVEcNH6u8NE7A11B80u0wEwgboNi7pywGOX8fx1rxeEG/1LhGPy/xUvtJExmMdljoH+fiSInRjgZkgEgB095YyOZcNls+pm5U=",
        "postalAddress": {
          "streetName": "UoMYgz7bwLjd6zmBUujBLZKpvLZBczhnz/zjgZF2LgaJw/1SnTrDMACNVeGhAnVDtBNnYokvM5HwJnd6kQPp3G9UG+56dEc9uRR3WtNcIXTuxErpX62dG80ltL0H+0jUxsrJbvDeL1pOPORox5t5xEiCLHQfsFtiVSsaVkZOoJkulV4QMh4dfmm1rvAuCCVYCODrPy45+mOffbLnBkJxhlTco1XPjzrXGmGhMWazsprkGgzU9+3FkZQwmI5JPWn5Lhg+uaQDX503iKKTq9lef8KWnOzreQdSG+S9mJH+FInS3/8e5ociQ7g0YX/WLh/tTffjmSft622/lElTBS7fEVmGuJ+gN99o9K/XP2ojc7zuogHCDBTA+fDRnSzhxkiRvnyQAUp4Zm4jgbt/pZlBYGmmqWL6vbFaDJupgLUaZTEhlgVYV6m556V08yHOotukrJWZt65JOy248z8ukZoH97df0C73GuZ0rHyTimvNZSWR8nFwk4woRFyHTahJ6LwYz169HDtRbfYGzabTuLDWfbeYF6vJjo6pLdnz87Hf1nmVkOzA+oway6pZ7uHnFsgAOXJ5ReCwuufLTbQaeeWKxXIFEUxdY8fQ8u98lUIQaRRJoM9HdMuve/+hWIGE1A8mxITkdaBtbXOk7HzOAnTs+BoD+tR2VWAii3F2P+nehPE=",
          "buildingNumber": "x7pcs3x6eW02Q3LaijSPg+meS/tj3/CK1JpU0XSacaqmH3rrpXrfuW7b2l/bJJ7HeBzX3JJFM7SH9vlgqtsfcO2dHlzHuht/U01fQXqBHHndMMB74EAoIDgV47jNn67WFCd8ix1XvGBtEfhGJUmIy7Pd6TcFfN2V4A/bXKDFgAx1IYUkn+pERPBuVXiXjsjW2hnCpjjSROmie9PVG810oaWw+Jw+ZinJO3MrF1qIqLhdZwRihcNhoWOGK0S7/t4pwivMlUvcLbKSFIQpYaWAJq16OOtX1V4X93PG/IJax08JtC/K9LRYattFxNThAQC4Sl3ZGHRsKwUAF8vvH4Et+HmfvK2j03TOaW/ep8xsVEgx19fHdsUda5AQGHY48+wKYBCSvRhQTIDwJxj3XgxdVJolcWhTR9KAxJJRYLYVQqmclSUQotF0sr5wrS2gKFceA/zI+JJwSUN18Y5OhPOA1e+6/XF/Mvigde53D3dcuZKNR+Jy6R3OWRGDfAEWSVQmD1neSFpb707b/RID1Ip1My+MRJcXEuWFnGTqfHKczcZSHD4rjkzER0F4+935mcNohlz+3pv/irnrPq4mB5nu2vB1jI128NQKU61Om+rDCVruzXSHa6AcmSyZWMqgpervPCEgX13vBk8Creu+O/pEJHO+YMnMvyvJJScnnb2QjpQ=",
          "city": "dMDm/oJbonP6AWm/pfwlI7QbQspN4dzJZdpaOKDDrfIndxpiA7TfvFaheVXhJdaFumr2NE/qPAOZtUd0mZ/2vs3FUjR4JlVJWtAwnue0YcOYD+hAaLQVZ0MPNXUnefHcKkS/oZxfsBLIHXaY6KMuQ3WE1xMsc5q3IMwkCc9Pt+xouhiFS6FUIAx3O0m0lDyFQqJAk81FO5O4Dxyqcox5KvKC5PRl61ylHVNj7Nu3hgEYPlAzoRWTDv8sihQJYbrQ5mvVby4DrKZZK5Jx6t9Vni/4jJi/O8q0z/7H508/DCdkNpFM5qHVIAgzJXDN0at4Y3G6aFgd2Qor3yqNtoK3yIDVAf0oq7AuRTZmLzZO+1djD89p+thAJySs7oQoLNTetjbRqVJJRbYmJHbB04ztHKiHSUu7hr8HR1jik1Xq4Kdn5Fv/HBFdyYRVQC6INGnEvOCb2eHh9PXgPIRawlzBzfCx/v+saeqRf8LDlV9qkBjvXiQXXijj69fQ+XF4H+lqqELrzbM1RTpIYNGaws/fzXuRT0SPi9dXTzdw95b/nCLrLEVEJB+H2OHi+PCSX4NU4LkJkbP0kcuSPRTwT+AH/8FMe0NV2VHTZfdqZRIl2lwCGkz+ujOoqFFMFNXwK2do7o+B45W5tE9WQXRbOQBr1y24OgUTauRhP81vr61zPcw=",
          "postalCode": "qB0pD3xodmBVDMB++PXB7CcvDJbu3nYO+mOj2NRvgwAgMeTEJmKjC9DYEaWMHlYaqDr5rhwK7j+z5dIcVSgCCYKQBIvVMdwz3dlLkX//L78p8aoWAx3KIjTdsau9ePUpkgHTJf6G2M+h3bZb3ihPgd0F/Bk5zgpF7ec7o4q5lGR0lVyKvXzEEw5nGocs+xLvu93i0awH0xQcdglfvoEAQf9yL8UxKfPwlfhPj1EQd7djScewITE2JsycJBdUl8HkDViI3gZtJAlL5jRwRGghdEqYQQ5Kv0w8OgqT6y9GArc/0Idvx8exSa7C3z71+krsXHpDhcLcyzOb3mvCzT9HAbWupXJhumJJplHif3bQpCb69xFoVNABW9G2f/AR2iY3Dm/ZYxB1xyqlEQzsv7gNj7FtKkZ+d3jwLbYG5uSThDKgL51WFecCrpgkzVx2BCJ2/pgtz4wDqNEarF5zUu1DG3c1C04fjc7536J4s3gGvbAI0JgCGGw0SX6GfYVv0LlfTJMvI6q9Ppcz5xoGdfF4m9XwQD51BtVDRRRbcaDK/3eTuCqurCrrfGqW8TpJkn0iJ1JuTBBNcmjHqJAXd+WHug8uL+K26RTmq5J+Ah/hnnqZ39hfD1O241fDukqxpGq8gg/oZAC+VY/pUgjF6n7E6pjjkNjWWGccbOcrHwXNoJQ=",
          "country": "tG3VTkEygrYnOB/PwL6B/NI/xYe80QresfJvlNhCTUE9P2MwUp+aGFdIfGOAFbFBYZJ3WUt2Ydh+d/+x3mTczowrtjIEZGGWamO8IFrnZR0V/w0bjJB7pFWZFwdxBd/QV7QGrHKvQInMTnjNsTP1ZM6fS+42sZiUBT/mMsiFT2CJrhqeD/Tr2sLH+nfBd6qofAV942tw8LPjVGGV/i49fpePsq+2L1Ua8XKpXXfljCTCVkwoSIGLSd2a0AfxxmCp2Gq+5WeVeTBQdQMPwuRjywwcheZeko82eBcqq3A0IoujXWFDbP5CF+7NheCkT0k6T2c2wrLzEha1WCSW3xLLl8xZr06kuVNwFKgWSpxIDv05kWX9bToCwQQaDXKvu3zL+EG/hrSK6Olfd02kgtuK+HenNOKPOsGSAxdX7IKramDcKRUljxwQ+PcdF3cDeHOM0cMXjwkUZBT3bvOKwXG8sWJM2ckQPBPgQ52kcmxO6OA5Ui7vjFw2A0sXFkKBfUaIDtHbqSbwVLurzspuhaiYdL1Mfdwrx8gRXNwzIcQGqsG9EnBa68wSfk3w8Lz+OkI46VF74LW9k+owktOth7DpRHqcOANzqck9Kfbfp9CfXwIbzuKUDMYYIGC6Uo/GJ+YTXWPpW5XH8jk33S0mLl6OjON6C/Gh+wbLYj3U/G3ay5U="
        },
        "names": [
          {
            "primaryName": "IC33gNwLRw5a5Sr6OQ9WIGeTI7p42kzJj/bunWr8x300ZoNRijOGMcTcEMmRCY+7UsXtSgk4cewjfIwrxC31tJLQ+LX+u+47Vsq5Ndsspf8pd3N43Dyo3OIOjzoePsKrOLpm62B2PR9n0iYwS6OLOr72xqrx42y00b8ZJ9dejYoOW1Ri3Aj9ZsTih8m5PBdbZG/u7ZvlsRJ/agjXsfk11mrvWYxu8YWI/86OuQgOMfBjmNATHeaAmb6Mw/mFERmgrOw7XOob9xRRdAa2K1Pi4hK3yKT59ZUpwGdgobFRkVw6z+x6Tr9EkwDtXayFZ5BO5nrRsUUEdP7+fzUD06cJzLCoYXLkpyE49X1Hq4IXU3H09u540CIovYkpipKSMP3hKOxAPVukOlVRD2otpa9lsGf+ZGfL7zRIlIkDNlpKZDQaiL4d0Zmd2E/f9TTuk/s88ZOXoR1Viwk58aY+GmMfPkZv7DommfdNpzlP0emFTIQeQtGTyuTRZpBBfN3mbMb37eVmEzcgrcXnvw24ApVeC4KCWxVhZJeERMFohMqS7yH+cJuB6eYsYlJHL6Lv771CpgaeC+pPE72OU6HZ5W3RBUz2rOaoL6PafIsNndABcvnPyS1k0NulMYTDLsiGUS6kDm5qBN/SJuatTf+uAozyc8ecFHATOar6wM6I2ZfuyQQ=",
            "nameType": "cdLzkNW4sGP4T/1bo8GeWmWOsL1MpaP///kzmOpDm8DxmZ+atGSbkYIPc0LN591+5bFalKIzsYUVaORUNscw0+pr/6xXDzz6Ps/JqXoJivn+u4aj7x1+G008Ln9bqg823wqZVDlmEV9B1dGNQXwarsJazaBgojCKnGZJ9fqEOzmDYHTsYVoGLX9pr52+lQpBCWC+xvdCf0u/15PEfufP2WqFAKMd8lW7UflwVQGstBUURbsb2WQxk1OUsoMcI/v7UsAmd6SP/GoopfPuCmUfj/bT5h2UnWkffQNz1zkaXE7z+Q2AzVwUMp5SHmp/V85V2rQ1Q1Y5+JXFrgpEAkKowEcoSZaLPoshuhXAjmkcVgt3Xw9TUd4jas5+u4geXndqt6lmUOCUXR5oWTk0WNwHCb5ieA/wVGBPAjJ616q26Eytu83o3wbNaj5t7Jp4H/xRqztWlMI/0by/bf1rSnYh1l6ur/qPyurt8izh4gffeZbJe7YYAjGFVzvkT/BxUMVWWAlbwJmxgd1/IOufvOtiXy4aDuO6Vw4Ik86nByjnjeODIJueIek6ID2tAdi7mLZxTpdLA1jAdGsfqgQ0ubILsosY3XUlXLOzVJSXbajTe1WM9wK+64yYnrltWsrXtxyqITgE5Upg9BwCjyLR33tP++589X7hfgY47VG35/cJI+w=",
            "secondaryName": "SlQHE2A2wko4hFVEnl+Cj37J4HAQi62NKOflhxgZxGs6cgDjI28SYeXZ2Qgyq5v2j7HJeQq5oetJHdyDdXTk0q0vh//yQ5COyf+Fo+9vhk+reGRv/wjiNaGFp9Y2+wmE/W+mOsKNKPrnwhu0wyTEFbtgH6PPax/HgEUWm5NCL7Fier3zTwPNKqF5GczFgeSkhUXRDkDQZ00PI/IFIIRnoksemkMQVt63YHXqW+FIITasGkCQy86x3GgBaN6E39dQ+OAg+8HDQzI+9mjXDbykc+5aCFYA0Xex0TeocP9o8R1DZvGhPJ1e3qTs660WL2qzpWGZ5makStxw6aAW8pLLfhapgmM1R73lPSk5ZOk1Xtqoeij8PUmuyFALhh3wOCS34W8u5DjKcUpkhCr8Fn2mS4qbcMYA9elHvpGWlq0hOPtAB9Lg01dSpRZKqt/GPNhTGMZg/qo3nnnVMk1jAt7BuGsGHw8QIJbooyT0qGCB2JUg6QJ4lnpdcthD0mIEDrParzAvuKeaM4P9PNK+uLfhJ3GX5UUkFNDJYpS8hh51ZX8rTnzWOAvCnhqqVQVJA5h2yAQZhW6Y3fsntcrW0kFyhFYCmp++0pFGagvwnjG75u2U7DgkSZXKRD70yOnJj8LiZl/tuIHVmcZCt9KxTb5R5CD/P/0b49e73uc2hQscmGg="
          }
        ]
      },
      "beneficiaryVASP": {
        "vaspCode": "iJ/XUSCcI393qo3ztWPi2FSmOUhj/9Jp1bjjoC/H282U/KUyywFim+xnYvXL+RkpX00LHReZBvW5ppifuNOmyMMQzFcUgUj0PiTwT5BpC3T9yI1OHc85rUb9QFZzT/ylElO7DRFiSwke9lzl7bYAHTPwjNCHHLLJaQyPIPl0vIYVFoU9KvaquB/C97c3hbTlI5UbmzQ2iV268qYl6Xeq/v+bnZkR3EInJYwuw5SOcJpZeQtfFVVEtKh2ovctfueu/5UhUWh9irky8tlImHFDwyB2qKhNzimOm+IwRYctQ94U35WoQio88B2JqyG+QAqXqmuHer755pEO3RvYv5HnEfElu/nQ8S8bCu6/M0hHEqCiYBuz4HO985IN7+7uG2Ls6VS5zzh+K4xWXULYcTvQ9VDMYKrM08DJqu55ResQKVNNjD8auCRnPHh7zWP2DJcqonEB+pTFHwZMil5WASLYk/PRLHqPIU8gSBPo5BDFAPYk1FdO/5fsjsOXb2PqKks+yYWkyvVsfmWsxlFLrAgwcTyqhrGxgoPQtlzHE+Hv8ZXaAkEK5tD1IfCEOWYfyntGAPJ1g2S4DzdTjMRgWgTEgT5nrU4DaNC/VjVWOpX1fKrf20mzzuMlI/HX8F5jnSsxUBkD4y08jAyBsg5xRsYIwJ+Dqym2zuI0x1sxt89FkS0="
      }
    }
  }
}

```

## Real-world PII data example 4: TrustCo - Compact withdrawal scenario

This example demonstrates a common real-world scenario where minimal required information is provided for a withdrawal.

* **Transaction Type**: Withdrawal
* **Relationship**: ThirdParty
* **Entity**: Individual

**Scenario**: A user is making a withdrawal from their exchange account to another beneficiary.

### Example: Before encryption (Compact PII data)

```json theme={"system"}
{
  "extraParameters": {
    "piiData": {
     "type": "exchange-service-travel-rule",
     "typeVersion": "1.0.0",
     "data": {
       "beneficiary": {
         "participantRelationshipType": "ThirdParty",
         "entityType": "Individual",
         "names": [
           {
             "primaryName": "John",
             "nameType": "Latin",
             "secondaryName": "Doe"
           }
         ],
         "postalAddress": {
           "streetName": "Oak street",
           "buildingNumber": "1",
           "city": "Boston",
           "postalCode": "02001",
           "country": "US"
         },
         "externalReferenceId": "111-222-333-444"
       },
       "beneficiaryVASP": {
         "vaspName": "Prosperity Financial"
       }
     }
   }
  }
}
```

### Example: After encryption (Compact encrypted data)

```json theme={"system"}
{
  "extraParameters": {
    "piiData": {
      "type": "exchange-service-travel-rule",
      "typeVersion": "1.0.0",
      "data": {
        "beneficiary": {
          "participantRelationshipType": "XsWeoBbRRiBy3GkuZ+iLtLBsUagst5/Ah1Vf5fROP2oDiRHsCucHPXU9an0eqcEjeCIhyawNbDDByk+SJhbIGf84d8LysqpdhyNwsvictsnzKhe76GV92tGzUP+Fd3N1bGTQ3SoNKr8NMir6OmsCYbdll/Ywr++8FD1A+WTiom0JKo2xWN5oltmknPNChWo02MVfoP5VdUzaBEhZsHG2GT5WGjul3Y3z/WJJLidV1lnDdVUO8CIVegj+fp0j5fi8QtXQ+7/jYdpkCUIi6wIco+neh7z9HGJ+PlQ/tf2BjsyYnNVqm8odrCYPwvVmAWWzXq4feCMWmYQHYBDh/jIz6oCoAg1jqwbeeDedihdo+Sv+IyVlZq/UMJ5fHyzIcIdfcBT2igGyx+DoYvSY/7PPNc5zu90PlfwJmOLa0PA7jgVn7T44YGjIF60M7xU8HTNwgS339oTIrIMu0EucQYW7s5sIcBq4+GZVCdSUBRCIdsrnN2CJwGDK08LlstCg4gDtYO8kRDiVj99j+HKHi36AV6AgYL4Xe1X97TyBSZnVJigRic2RKssHwEBYH1zYIae0ttdw0BhvAuhWV48Om8ds+R+qAWVuHL69wC4emSFCN7K4Dnvz5p8vXzZSzYbLdwIg6qCX9s7bMNux+XPHylvkCDcOG92Rvew1UXgPRB3r5ms=",
          "entityType": "t7TB8+RshOk4PJlkMsClq/2EX4YsvEehiwsvhiz7uule8xgEvjmKPfng07u322F0800WurXVWcA5geI5uyV773LZz8zpWrSQOyPnYc0xl9ybg6ZC4R5yvpRBXcFHJ6Ts1ccUGXMr2KBpARxVmkQLyHGWClyYH5h5Vnb6u9ADjj3b6f8pDoybzpRKSPGplm/kUSM5Mb87cIimSTXFRhmWrdxzxx1W9tCVm0ehMPOWSvFcANbSGJIKc09+/55g/9q5s7efReU/izEMut0vlN+rf57XAsjPQ7tFAtp+LFsJC22aFtuhMnvKOlu9xOK+bxM8YafvoaI08ZeQKXXibRuVelOxRWNDucSGPlzXAdFUMPlqvOMg9EZxt1miVsU+ImXUd51K8Ix7s9MvvA4DAtBY19v3Q+15LLmrnTYdsjnVFr6UmSWjZWvFd8ivY9PY+/UFD0A+rCHtHoT9zLFBP4FccYAuXcgPktsNZsCq51bweFySnnThIT6EUAx3RG+/8twU4cS2HzXL+63DR7SXx79TQTconpnaRwYCCXgUeUReeRkLTaMi2g1ULHSxNjfYOqXA4DPTa0yXghftoy+asduphDnAqqqFfkik1F2Qt0FyRSHENAgIFBm17Ng2FXOLEspu2YR8t4Nnf+KL5c++GrJueKojNwuUu1V0SNrpLpRc7eo=",
          "names": [
            {
              "primaryName": "EMCGeR+yq0Niom+CNO3UqShEh43j/+9zt3LUcaAIBORcMo+LzgiNskHFR2w5P/f6VNke1LY03Ium47vDAFbvvTilNMTB+CcIW774E98vkUAQchscyqsUMEpPK9S+6fJtkbTOVPozekoAHD1TihEkpjiBrFcI1SL1zsuV+idemiBPCisGFvYQkPRU+iZH0AzL5aSpk1p54s+/gfofVbhrq6WWOb38VdCvYsOmMOdnIaKbk17y9VBdX3aqZrQjG3eKigPVqDaKMReYTAdRuGWZFkmfVp9ogunJ1FhxJJ8YUFJkrMEaYsu87olmf5DuuIPs44muT/7J6mr1cbpRnGp157uLn4hRnqQslsB88zcT+chN6M1ON5u4Z8HoFLLAWMoM5LD9Vg/3apSX+61Rpqqqxg8r2CINYfNmYL05LrYROBDAeq2gwxeHgWskTJBVUodJHuka95PZYRJSDMCy/13k+AdG3WZJuePDFzqKHhYKSpcI4MtPiHu2zdMeOwaqgFug9gdI77ULGkf4oDxr9sZtpq9AXtHp2VO4qowlLsXxsZIzYUXf0f1RKw9x98lR3vUfbz6n0ooSGJBRuuZljIbaZxXs7du8qgc6PDw9ykupSIfq8DvWDQtsOt6kYoX1EdkxiebO527e1TGAGK/Fgwo7M58jyF+sN9Y+vzPvfvlhqQk=",
              "nameType": "hm9/Z+c3qsx19wllgSlNO6oq6UCTdZz09Nr6lfgQl5X1FecWOlEG4YEBfYESbwFvC8rqBKwFiUYaB7S5jI4EGoyLW9XJbM5NumAH01vPmCnD5q1Gnv0gk8ijxWiOUSNOiTTJGqKzry38hRPyMGeZIrvjWQjrH3YGnJfdGzorG8GUTDLIxw6dxG0YOmMTMPRm18oLw8cpoqBC8QiPFQuMaVOn95+WB4VfNyuQ+mnbYMnts36VCpHrvgly1joh+eiDz5PA0RSGjQEBXg+zNWrR+3Pk1+OP3D1NKyJr9WvtanQJC+v1B+uYIMnjarN08UqntajIX/QPbg2yPlF6VjFxbOTLb8s/6geHKWyB5c1tbUXSuotWs1KPP/636uJspvf7oalADR2peXoK1XroX6F229xX/+H3w1/rovsp2xBorsj+fETwTm6Al1lMbkTjKg3n8Nea5MMOUCUt23TbDo4m0bFVQ2ACQ+Tt6E0SSUieJ5T+Fv0FAekjUVTUP2qyeYTRAAmpCxYcD8W3yLhvvI6E4L8akkT8AyTFEehM7Lx8/itB601IIZLy+qp3ylvZwWMrvE3l8JRm+K9PAo24Jcj0WKDmf9XZyS9MMyK/TRxqSv/SsNfWAIjkSKyOJuH+Cbf3r5d97wqkRER1NjTKsDudqBiu+mcIM9KToY3/9O/m6hk=",
              "secondaryName": "Tk2gAKBgWk+5cWenshj5yeCQUjZf8tCc+OI5Fnfevi/VJKVHGjWWYlqK7jlFUBugde7alNfedpSUHH8qNaC0kL64sOiwqf9CMIN4Fbr/GcX4ib+aOJAEG9drMtBohvy9u9VjsHeG9PkVSi9prWA5KRUSASZXU5xIqYZYIkwMeoo2WPamCk+++bL5bx5feVuPohP3gdIE5RswUaZ8NeqGZKdDcuBCtfS5GPEYZGhAxrvHRMkjSd/2yTExAhC/loO50wxAl8oSgCt4j6Ib2grvPFP4dPp2SgHrGKIxnTkXfm+KPPHIAxFjfKKnUjeVpdRPuYkHVYEYb+TYyOsZMmy5W04FYyoasl/6SMm+8m2K0jWy0nBI4zwyOTHMh4rNZHZgHgvIvFXkIbo2b+o8X4CIVF2oG6Vymvqo2fLofNtfiEb1Fom5ZNOMeeCb5vMy4EOq7OI3AZTNKnt/bp8qq1yf4UmWHyUycc/OxkMvLFto6wSvXJWoySlEx44nptGNFrmc0wVA4sgZhbN2mkBIFbSqihC90JHebvszBHv84IqT88Di66n5h5wnrYwXbpR60bVgd0mNFqXvgluViFwyp0ADOMt60yXGfC5N1snQkG5CP8Mrhj7B9Eq12U43pXVF4vdBOcQ8/4xMcsed3vncKQF2b7fJdKSPlCxKUh4H8OqTSg0="
            }
          ],
          "postalAddress": {
            "streetName": "MMx+oeWhO6z+tuVsS/GMHAxUvbFYJA3NbcFmcnO7dFcVY/WFp80a0q9i8kbA9QR33xF4qHC5Jef3COuAhL6gtPlE7AmiCgAH9AyhygkkKoPkdBogehJNwwn5+8bqJWeQ1nJYRMLBJYU6z+k21fBAbj2ERt/Vkmm7DoXLXx6tL1wxNIcclcLrd+rhlp2zEgsIIhD8gQvYX1L9iNCzORjKYntyC8/0USISBeYtqSt3SmUwL+nFHUdQV1vhtWWYO1QsIVFyPaccUm6jGlDi9G5JQQA2M5UIjKs2q6vRUiCusXMfGeowuLmThnk/87o0TM7GTJ8ORhxAzefPWAtE2neDxCCOy0VmU5DW0dK+HZEp2kEZDdxjW1hs7UfE79P2PdiNAvwyNfbCQ3ff13mXxSu/O4jTyyZgE7iciAWmzWTk4NHrma+y+4Zycw0NbQNyTHGIlCyBAoR3oFnZAs414KJK+yMdQC7TAxm6FKcf4SfWqIZH9Cc3ubNLsK15qsBIDw5k3xqGGrBsaBVwNROFuOEm46wM6XeWjvUbyRWxzSCS/xcZZc5flTp7gcRFYNEtvMvWP60MqRjSh6usyJvir1aL+l6JPdJgZid2PuCfblQaSXh3MrTrYrQMztO5FdfszMrb8I0lcNCTOTY0upfz4nO0ZCpz6KkmMCYgymZzQNxZJh8=",
            "buildingNumber": "qvknuxOfuGbd3MgXA522vIl4Uw+pq0euzZBtteTWMaiuXzLyRChJhSrcA1hy71eqG03xLCPfu6IkE4ExKfxM1Y9unjTyw5YnnHbCyxaqU1uGV0dUjAyTOFAU0Dx/8UZK0gsTopc5qi+7lNRK3aaGG86R7JgY/911aq0UKb/cO3sE7m699R6DXmi6OgFNYrPjTnFQfxmEfBenQJhocICMv4eLG6n3koFbmjAi4pYoIJc39zCtPhASNdl9TqaFypHHTubnlUgYvJPB2URisxJTgws0BsgqtciLhERHydAG8uy+574UnpdbkCDmWjvEfL/yS0T4pEGrE5FYmhcOHCTH69MaVVggVkv4uyS9z6DnvEbuj6njUDPasoS7Sz+uTSCjnr+SVN5yGc7MnRUHeX2+1q2/oWtmSa+kBkn2jSoLcZxYX0DNx+cJgk8MzL9SwHlLCsqLWDoxw8XWc0M/k5vfvf/j7GnXH+A8PTEM+uJi4Xnr2CXij5wdsjfXEX2c7wfYGIVt6CGymUPTjRbqbOGrphRFudZYxZg8weCC01IMjiMSzGnc98ywDeIm7tBaU+yHAieOQ3DEBaGPfu++ybfdfHbCYY9gexxxFqmHyxHypPvFA+vU3oWYQxm9tq6uSBEzNBYo5wIIZE90qzOAXSXh1MCekk4ShKC5Oy7S6MI6d90=",
            "city": "fm4SCZlzFdf9KO9unLxu44evTpR147KXy8X1eDbDSnVeR0ehWPvA7yCuzqoxfc/f6vRHNcJgG3RlWHVwwvBT9d8UEfmXoZVsYpH0hU16e9+Y/XZLueEeAaVqgBtTRettSv8UNMxcweSqiu62Qqb8GtlO3tJfm9ZPeZE/fR9/ysXXamyEWtMfd3cgDfrxZx2U+ccZoVtOWlxQKV1AZjpit4E2WU2jUuBTaNTBY4cziPTfjdy6wt5CA9uuh5Bkvnf3QNdZf70PJHUdzv1ukzuSaS2Uxjls6WHx14j8EEWp4kiYIA5LHa7pA5ex9gyNHL0CbRbo9w/KLwXp1UqVwsbXGhEVo11qkrSqA3bq+Fn53qamH1lEzOoHOW0INoVpEJq7TuBcor0VcVaKZffwaaiy7iCY2Xi0MJYbOcaY8JabBJWWxoMatefLOQ0i728fI8w7yA7hFeKUsCjW6pba3kdSS3mx8N8CV93cB/qRa96UcRbP1CdRYwubQRSlCg4fFM1FNWNnPT1kST1wujoTQd41YaEPX5KZ4Pv/sa6Tl1Jck3rPPUY98UtslwajEEtzwGQr6BFEUtp8DA7GKb5EBgVqEMbn+xRp6vlwoadFhuwcUXNrfCpHKwM/Jnk4wxzFY2CT9FnhSMZ8349JAuQ87/C2vKhkKVmcPAJicW0TrrUq0ZE=",
            "postalCode": "sHnDJDY3GW2bM9xQ3t2ul9O17Ahb8aG2THJwKQTeKdilj333dyVPEgnuwhS/wsUhKYcihAltCP5DpdsJzpjD2ireLc8FSfmEKHg8+EgVvnv4FeXVGPFuomesmlw85jv2gtzZDIU80poHiWSzYEZ3hfi3D5AIf2YXse/5iVLGlGBjSnjicmB2741Vq50UyP1PO4TNolm2CqsYgPssfYXfB2eGrjSbKOH4ZGTWOHvP5uorJEpSZyt2RI1xskiFzd7/6SlfSQYheHFGxvYNJatGDkWkKc7JxQYClAbbhDQxfWD7eMdtVbSxvQV9dVRnGLaLHSWKkORWVdVD0+sSdvWKwbVxs7a3o9T3LkQGo8XM/xH+IWIHiubZ5WCQWsQOoRfk7tN3QD9lDTFMnH6HgmgeE2aI+Ap1jvEADVO3Ss/Dc1t5NB7tWKNcqKzt41z6iX71sB8IOC3kKKYzgs13v02n2BQrjLqhEQK8HPcOLJOU+09b5ISjZQrVopxaoQmjBZUeL05rKynvMQ2i5GIqmzvWAEwqXOkN3ste4nBtTrzjQYO0Dg/OmlMUFtbuRjZa00dHU9/W+VU+nnyU0pYbOnH+4aSZ6V/uASBboz95LUioZgEOk/RTRIpIfVsr5U0rgwCt+xd17ryHOsilNDshI2bQtuk2REGFE47ddLIvF+P4s/Q=",
            "country": "WhcElq1vcdYOffUHkVnukKZcZjyOQG6YSYOdtz5WfAsNs049x1P3Ddzpk0ELyPl4IpDz1OYIgcRC71bI4UUJl1zlgTmjYATZYm345O8LeBOO+1QJEfKb8x/zYE7e9jID4jH6INu68uZw/sOrV1diOVBkN8SV0v3MCFI+SdIfgTRTgLZf1/iFCh3baZzrw5feNpIQFg26ZQhNyn5ViZrHbB1GmEHguWaXdb5bGyKAOUYQngetBhSDVz9LHXLaIrOLzA/t5oC/0zacvtSug1rqiIO7UMtIl5za1k6IvF7N/rwJ0PvPBIXsR6hp8uM8W7GMKzaqG+JHBZubiU67/hVBfnYx334UzV+a43sEdY//9G70V+46SLQ1DcTYsG8Ynu8swok0VOWOQeA2YWi1EF6DBkCAjpeXO3Oe9siGBxxP9qUQRgNTQW+0OAgB67jF9yTj9qKomEVKfN4+/c9GJDn84hYypJjDANWpvxqzxBOM4ouNxhWBKBTbX8ecLcW3ppphUyTUUztJ63Ud3qVk8cpjYwz0v4hS6WsgT5DZf4RTex3qwG5lsb5Zhsp3Y4yckBz2Ky07AWDPH8o5Vrk8gdbSUU+equKY1djgeg0ui85ShqoOjEJSEx/viDNIC1J6McoHyaXwycFlU4JsIM5L7LNUuwtr2piTIJVWVn+IwmGz9HI="
          },
          "externalReferenceId": "QdrlVMPrbn8HTJ1UFfI9JQ9UIsCc+/+eyU96fHMt4csCYaW14dxfdVjrjjf0jp8BdNp3w1KT6f7l7AaAr3X5Rb5MM0P4tUpaIIZIMr59SoLeu6OVIFRsFezIWIjL++z46N4CVP047VYX/Uzd8SI19Yj3JoToW7frN4UvPUA6iM+2ROEE04ro2tn7iDeEIKZBk6VPyEjDjXKB6RrFvNnsTrUr11aeCZLQw8wIFGR1ckM9xb+DVU1T1qjoyrCZHN3qxpsK5/Up1qaAEY8plrLw6V7Jwf9bvUFI3DhyFq6am0Gpcrepzkc1Kvlzel2HJda3qLJbr/5OChe96Cn1OSmVKjAFGzB9O0MfYx4bufrgliSa0N0boy5OUKXAM5el5CNmzPOQI3MnQkiI7vBOgetLmVRYrgCs1A3wB5b9kdfOAEopxnMS1p9gCYeC1Fx8PMjKYyKwRwtJgpsnWx8aQx2RJ1I5hhAKP/xvQU6nrpWScL7Z5HmcFRsypyYHRXGq7HfJapeE7CreEzhVgxVgB5p3HPz1GJg8vHmYFXPi9Yl6oN+udXa6KaAffj5SV9h+A6nfvAhGz9RPoTOV1rjJhBCHAiWo4SWzjex6S9iYkDLk7HY2/IXMbSxpRDYzg6Qh8Qfq+s5LsdX68H9ZDxSxxdZU2B0WewAVa+a+e1eZtyV+PJo="
        },
        "beneficiaryVASP": {
          "vaspName": "Vey8bhZqfcKheVSwccHKs7U7w8dvkS/5dQDtad7O8KD1B8n5z16SWiX5jfjeyha8/KI1WHcJrQV61j8Kl235fM85iBr9tmQ2qf69UlZUTgXxayh8P0C0yjIewpwE6l6wqrMEMqMKBcDm+PBKxQKe9mkUhnOZUoNBA+E0k+1xBg2l7jkEMpqRkfZQUy4VhHnaf/gO2viwGB090EMiNtdOTcVR6beqRET7PZPKfC1J9hRX9FAPrMQhhFnByircrAS8sHUG9C9dYwlWLjxR6UQsvl6IMdcHH64RJBXgaOuOV1/d3ewWHinG/MaX9RCmSkyFQYUFVbuEAgNJnjGuqr226fQg59NT9WMzw3/HKK8Z0fDB/x9tvewkxQ5N+3VyQKLYe7uMW02d/xqegSsR26Ol1dqbaRNZ1kYR7twXaOPw4S+W3UiQGhxhVrAApKiedrKNbnlhsURus1BC/lGbdJfG1g8DefkKsRgXNn7vR4N7AIwXEkp0d7v2G8xpRTYOFdRUGJVwGaGexTRcHumlZ4LmHniqCl+2zoMPwrwijr3yK09h5fVWolopp22EnNf0rYEEl+CQCsY9LSEVIku7HeBn+TiUtt+y66a/ZvqTTpBNJvUb9zLbYDOn8uHA6J6pezxImu/xx1ZwjW0rXFq/xbq4TMDrrzKfAhYUBF3TklN/3Dk="
        }
      }
    }
  }
}
```

## Real-world PII data example 5: OKex - Compact withdrawal scenario

This example demonstrates a common real-world scenario where minimal required information is provided for a withdrawal.

* **Transaction Type:** Withdrawal
* **Wallet Type:** Exchange
* **Entity:** Individual

**Scenario:** A user is making a withdrawal to a hosted wallet/exchange that belongs to an individual.

### Example: Before encryption (Compact PII data)

```json theme={"system"}
{
  "piiData": {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "isHosted": "true",
        "entityType": "Individual",
        "names": [
          {
            "primaryName": "John",
            "nameType": "Latin",
            "secondaryName": "Doe"
          }
        ],
        "postalAddress": {
          "streetName": "Oak street",
          "buildingNumber": "1",
          "city": "Boston",
          "postalCode": "11000",
          "subdivision": "Massachusetts",
          "country": "US"
        }
      },
      "beneficiaryVASP": {
        "vaspCode": "did:ethr:0xdf41ef7dcb92ab5aed72e284db3766ace5026948"
      }
    }
  }
}
```

### Example: After encryption (Compact encrypted data)

```json theme={"system"}
{
  "piiData": {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "isHosted": "odRFwGbH1U0Fbe5K7+B34qeN8eAACPPS97ORhkk5LvB2IDwmDkC2jDNyYqmy4AtzWaK6cEM+GsNvE1LIrrOkOTcKI9qFxX+3bprUbPDLSlPGmSkdCwv/xm9EGO7ZJunvBIIO0gXLK7kxkzhBT18YO3T7QQhnbJ+IKLIcb7PJi358jnkkFFMyKdDEg08IzL4a388lghqaK7uP5NWkEGdFFshFESdxQddqW745Y/arbiT6T60Kpk+ZUrapF0AcOiCmkigYyv8L572Ykzs8ev55ywrYbdrcEqfh2yIkde8C0oosbKF7r+Ko3cXVCzNDGBfpgeMmYlVs1yzqUGoShdIlBVf/neCclzXeng0bkoc0BfW52e6g4t8fOE8fBF9KS8XjNAKMpfhfCNl/5h1k6Aj1DlfzBE3ncgBtFPQ6tYu3us3LCKizfqNNiHMOw8Bo1HysplupQq4jMCsHCsRODyDmT55CCPRlvn291EGT6Mc0i9r0Pqz/bxhmapd7w3hk/kcsPgRSdqqwQmf7pMqrQStSaKBnB6pPF5NBCjGBBuIrZGaDCeLnHtTeM0BuhWzXWJltViWp/v8D5hRuG7LqbT2CFHroxTCoSy1vpd5VvjK7b/KyvGVq5jzJ4U4798g4+kVItJsbFFYtKZBCWXhqO7n/d8GVsWrWNBppRzwX4guK9Zw=",
        "entityType": "UeEaw/QcSatRbgoW4Ffku2FkkHksM9gAHVkGxRuyVHxxcU6S5eMuXeWqrRWvACWIXznRaeeCB1R0cSCxIp5e8m7trptB2uyAQ7pvots9YLczm8YIWaniHelQReaNShCsir6Dh9HhcO6gVKKKWYfI0dg09pr3SQx1ajnXm3+FaT7fjDBQCtNU96OgrF6B8D5UVaapKLNQl3PWBw0GnY8LGAUfgqnAq0FZTobAdOJ0lwwuV1jRqPjxjnAjrN6mcbjQzs/7ENyOBLtIlYm/IL1TprpCK9J9SDgBHHaiCFhClP+U8oKrFU+W995ps3vTFI1W/oj86Ye0HTX8nonESmperWGtxuIzAu7CW/hSxQCIe6/lECP5ZpOZZ9YrTw++x2CEifakc+VoIOBZufMRfOHntA8et5PWJsGtCNy1aNTqgGpEjJnBEjnb882pH4rGwAu2uqJE/H2kmswZlTjci7Pcgwuzn5vOU/D5PsbJqPrZynoujQwTelFBnyVfPvEpyFxGW5QIEFQoD9gAUdz+qAqI+AlzQdGa3DqZoALQxA2DtPysZbYGVzKIRHtzLGyhIG+wtzGMw2bTWEixvMZuR7rQXgjGpFGwFmYfT71/+u56tPnCAfLUmcg++6wBknPkdeit4xOWkfmROYgJKqxu5ZPAhpBLDQsMoEohy003iq13x74=",
        "names": [
          {
            "primaryName": "eidD4pDO6xBt8GpFymHCnJQ96bE+mqVMBdXgI+mDstmLmABzGob6JdmDcN24b4kgIpuEEGwJiJTZoVYi+lTuQdPJsA2W6WuSVYJW0Sm8jGfpva7mzg88Uf8N+nHt3yqHo8/m7OeRmd6At+lTscI0pGl6paJky9pTefF8PlSJ4IV7dA1lMNTfE/L8u5bJ/8p+7TX1O+G23UUp21G6xskC54dr6yLYRyer8JTTS2QxB42luYWC3UlIIX9dQRONx5Edr+OV8f5Na4L/+ExuD588dhcUEDjFaffoZhWJYYmfjN9lFVZE2tw6UsGxknH4dNyoc+FiMPeqL4Cw/RbQ+fhxD5otX8au/A4ByhwVMA9a4yt7+kYyNvSWpUGVj0ee43HXvxdIPyKCewaBvbNc5yvwX6X//9c27tjYM1ADRzrSSYzhVHCtlJZ2fwpnmUDcfebemvt/Vrt26BSiXrx1/G14wLhoTcCS6i9av5x82QbQVconePIbRIndIMvgx5Qeir+HU2VyCkAkBie6+NcWgdUHO3h79ZjRS5wsMC13IRX99ClXDsYoJBuOlTGxY8XrAXiTr8+CysHLXileXv+EJyoCf7HaHrXar7ym+xUCqyUnTM/PuPlUVw0D1lK7jjqSEY+0+nZuT5rC+A/n8D6UWRLAgd/V6ghFTe2171ez6hW6z2Y=",
            "nameType": "B6plx2f0k0D5O86CcY1NazOEI/EfDOhQpKR0brKgDbYx5TyY3OmKOciD7NxnV4j0EgtnKMT9vB2vNMS4/Wy9tDXnHxx9h27HkKQnJVppat+jFy1cpSwFeWCjL4w1pxnjTapalZzwWD5nAqjFvOx9IRiCvvonKuRaLQSegqVhhIQCLs9+ZMtaKVy2JNfrDR8Rk8Acof+iP/k1poSwkFBMiOWCAErMEZq+NF0jwYgnDOUoQFT5IC4HDlva9PANMGFJUvW8RpsMduYrjw0e/iBPs01UbKMtCIZ6h+31+XW6b0xfVTI7jwowPNWe5uvybaG8wzPSLVnmUi2+/OoJax8tUwlCXBHD8keocSZpaPZ1ahuJW6bI+3rFP/FRk6asg8iC4A78d7RKsvomcA3+AtXUWHR7dRQlQVwRI3SWuMP+YWXfI2lt1dT4Zq957FQSdDxAb5t83rDJGv75s9x4Bv9dBY1Lz2mQkzXROHfHQ/6W1SW8FzrSysm9QT5/nFddpzhVpGLpcTt7nXNNxs3PqsFQD14KClAjDQ44yBdDD8MV7txQmo0Gc+mmqvBs0cekpwbBJpm2fRcFzFGYidzu/qUB5vBOH0urT74mLBIKYeW6TnB9xwhaXHYDkU76zntIxQRACd+8Vol85Bb3SR8B8lorgEW9OpYw2kvdnImiKrF/yJc=",
            "secondaryName": "Nl+eig8i/WL4Fue5HMzQ/NCEQSj7std3eggvgh6NTW/2bLLlBuoeJttS6jmQA5Qs+/QrZ9k01AUXmYhWp7mYLFaCY9vZ9J1C7YThlrXjdSCH71dpJxoF25+HsGz2NPA+mDg0GWb+bwcwiKbHnaKlujeBNN1TKQabFwoOUXsYBeDhwveagHly45+t5QwlMi8R+wdXsfxTIAX6JnjPRywHb/uropU2X/cX2KUzgRUQ8BCBnOGO5uh7kFbCRNAMScA5byXBx4RZbolFIvMWJkpvoeXgIFKLqN5M6qe3GePLHTIWbs7EsNFlufKwYunmsADj5xWg+vO1s0L1fKslf2iWSaQTBTzcRLjdkFKngJoyyktXARQJxJwLyFksNyfhAp+64upqBg1eSiSBDcSUIKq2kZMyBdOYnq4ZrnEI89Gqlt50h9FpHuCZzgLzYhPThSKwtgOpEXG7CtVIbNy8EGGjnQiD3Hu4k1piwZ9FY+FBlz9h9oKsxHXho93oz2g1ZufGz64iqis3A+gAiNnBjJayzPRxcSRqRXfPBzU1g1IJttKsvYRP66ouocHWRpCGJNDnKTEZozDlm1G8Ysbh/HXRBG/41pzp3MTj53gNxJ+/PW0VA3bcdU4/aZOv8m4xAjufcSJUXXLQEvRe9s8hi4HroTKYxELDZC0tU4vGe4t5Vng="
          }
        ],
        "postalAddress": {
          "streetName": "eiFtUS4TgBrsxUbNiksZ1RsWlPrCpE/rVrfghwhoYjqdkhdlxfZV8k/Odu/pjAVhtalWfEFOj/oWLp/IhlzkAhxKUg9GxXqv1kyMQBi/qsGm0zuNW8eYkYd9DD0K0ERWAsZXvxHfDbTxzdHEmSyu1sdefX/HM2yRuUo80DAPqY36h5YoxVtGsDZ3eJ53a6HYxD7KHf/tsdPWn+GS8BsWe4HxlDh8nvRnNB/Q6+8puvo+nNRMtBV4Vum9eY60wyGBtgn19g6m8UPe3josrsxj9zUI59uAy3AH5QjaUSeYBTXDwUZl9uP9UAjx5QyGlVnZSy8d3ciWnc0fdxBJZWoE3aGNQLJq3iaoSwSnBHNbhaeNwVw6yXzW77PJEJiONFZzbyrBnWU/yAhKPsOk4xYsNMJ33yfxj2ZLbCeIS5xyNxj7QS4W+tMyfqSIAEzneXZvYmYJHUkZykyOla7drmiXByUaGKfQvKa+Pyh9daRI+tVQE/NZnGG3+p3laLSzx7LAU7Qc4BZ9Te/FLPCfcfTphn+wPLj7MDicCpvllblK+tlKW5Q/NFF9+vTzCkXtVD1ESbzTot3Hz7nrjGUqSr89N3i6vvddWLwUfpPHDi+Jd6m2X0sZgKXQZIXL1IsWJka4OWOecIfvB4QLSiXS4Bnan7dNj6v0emYzIrswoJoWC6w=",
          "buildingNumber": "JC3m27RRk8iH9HBA/lNhqTt/XnEtnDOXFIA6Tl3TPazmvAFAhd+SxHWKlVULg2rMBriy+AfHsIR9RX71+fUQBKhG0SyzuFieNFwfijDWbfVDfJYmRmiksEkepsrPNRQlC0vacP4yiIICVZqQZYt8tvkJ+3otOAtJQ9L5k/Dcf6GB0luUI8NXXglokrmWk32BUXfB/6kaLRCqSHE5fBeJDx7MdzsasQOULsavUrhjz3+XmeDoVghooYbkg47ATnAeNb3EyEFotKqeYtCsIdgk+DzjS56HAol5nmPeoJTqxhrLvQp/Qdgw8+y4Jt/W80/p/rZVMowQnt0sn+fHnn0LqeZdB3b4asbX6kQeZGHrjTO35STgs4ppvHp+YBOSoxOJsUJBHat+Yfeb0Q1vydBD2s8vQCeqUwN2EZEa7D7p6VdcSaa3fAZXrOs40qMVZDA4yjJ8unbN2egMcq64mZqfzM9IAkfN6E5AZ8L6Mgz1H8+fPQUFMwawOW6rZssaXOwjCnU9nbNcI4Rz8S07/BaY/DOPyKOPSUtG3oyplUoKPpdMPAsbokcVmJW0eb4vMT8NUIzVM0JnA+VBy49mGTNMv/N1C/9eajzj3uZjkBCxBKDOhAiYhAziZLfWqaHhCTBNyqB0e2776wDEZcGvatlz4kRffZEBh0O7YfoWGGqKGfg=",
          "city": "td6CCpM/U799g8jmbSfm4HBKCONWLuJ0FNJ5hIrRBsYa4ju2+poEsmu5dUmFNg17afhMBhbchuNY9RY0SZxNnwIloPQibdJrkY2PpxQOaytXJvdHfbCDie2IZDSZ2kqOuT/FNMQlpbkUaSGVIrTYMrXLuT7Y4lvH+nsOEL3Hpkg+sKEXgZco7UlkoZhas6oQ3RYAzDGpNomzwWfQLy75ef/vfvomSny6a8RroZscATgNKLPIBedi+Aq9egELIE5c3+JHhnhn1a23R75HzKG5RHb8HZ2ddAFG7UJWOf0mOzaKkLF89xLgSmVCOGQCBEyW67SkM4yeWZU5PTxIrmKORl8ndfQVYGsFh0UikAZ+7yVCsghlj1kKrH8vP8QuFEshW6iHTENesbEAXKu5uFh17ANcwgwTetwPjxe/EDBH69bSYt9WzPntsDs0Dk3vvUMZ2YMXyFaK/mKa7F7on4JZHcGIj0Wb6GVM+M8q0R9UyGDTz1L+ho6hgA2OsEIJ/7RKAn9KVCOXyDiH9sEHgrF9bhGGOUkkRjK5PYmIao9pEPWavcIsKvvCeFsm+tk0H1RuTp1GvojYsbyAGSKpi1a2wnqY+XCtDkUDE1mOCzzwklMIW6qCq1QmNr0NQbocH7GI9oWBTrl+A7y5NJpzBHHkHH7t06OODv0jjbkV+hj7Lj4=",
          "postalCode": "bz0BGwPFlCY5hyMkbfoxYkTq3uCFBoqG4gIDh56dz8cthPteUTRHA1MN4QJRHaDYiXkl0FxRhwY7k7FSm3+XqhPlafF1UNTE5Dq0CAQmYoTtRgLst6pREZWePMePXF3UeitfAMByZU2G5kt6hPO0ut6oBLZrT52ds8O83IjC1iJye9nSl7QU9U+Li+wRi8yqH4gSP6h+Hyf4hrYP7rqRbOehLolDfOIzxedpEPkr78ryfApv2lZaZWffMYwz5N6I2pKp6U9FGfCv3HJbIsyK0JiuFbOND9gPn7Fb98FcSL0OKgvS0H6+8DxDA84CRCjNUOKEHf4uu+5vB9rt/XR5JTPxpk0wFtwUPdt2DroG4Sl13FhjZL2nCJbe5EC9mPa2pHotaTRs/NeG5zlMGGTQA96VA1DR6ZugO0YxjCkmBbCQ75/6yKSpH4xiVaIk2mDk+SpbjpjjzJXnHrdAGwPHig/v9EIvyYTkwBBOcQ0M0HOcKPhTOxcFKET3fWkM498Oya4A7/3aN0bbdpfgIbjIX/3A8BObd+UMjYuz1fPwRIZHxDVUMuPdbrA0oGxxFZV1tVwPracgJ845cygt3HJbn6l7I+ao/VtTyhorfqFwTtpaHd/WmOw6Jr0zpRaYEyBBjS+eQD2g2OYOAEDoIqrvMr8isZ9kRqUxXXTxtcDYDSM=",
          "subdivision": "IYO7soEscFJRNL4XMrghCgLi64XywMSRSpwImiVzU0Qh7fdXqgsbkpnRdW0XxsCgdmpSjAb+7OAOMMKZFKpzTed7nSugGz0fKYZR+PH8Ca+lBGwjqIax8w2b69jZSGDNiyMMRoIEDvGK/f5exaJR408YuUShl6vGpSH6+p28d/hBbN/VEBCnFVkU/6+G62Ej7NmQ4ucn3388xTbMQyq+D0KpR4PeI3gi5SYpuKsgu8sniD0j/pqZsmGD/OY4KW90A2XqnkX4x7dMd7jvL8HDkSsL1ewOx4BiwZgbmrJjuX2eV+SRpYhj4a4i5na/2kIS2z3DgahfCkDsCxjWM2hf4IpbDvAtViYEero2yWBlwKkF6f36XO39uEIorl3RJa6saKkvg5CoiRUxEjazpn8rInJoLKo1NbtxgDyoYmEqqKcrn26Nv5ETOFDu1Y8AljPOhA4FW7N3xcBJDKfYIVW1TJiXZ1zDveFj0GccHP+RZOixuBT5gu2BWSDG9Xz7oCu4eTsQoWqeOBe2WFNQFWXQ91dp+a+asDoSCkd/KDI/8drdp3y/Yhyx7JI4nQ7IVXWcodJA/X3y6aMxGdnt1p1aDp+i8auMzfvwsEAH3ATzS1MNYoGdg05oFpDk38rXbQvdEsde+vKZmmo4u6n7i+weNaeAHeAOkhAkyBoPAZxVdrY=",
          "country": "aBDC/toz/kTpplSpTc10iV4IRqVqaT1cYoOqvpJy00Rpnnw4qB0gf29FJsaW5hG1XV4J6nPOphcgCK1tN9LGeqk2tF2SAl1cnTiEfuDTrX4D4Uj8dxlAKOuqcT9p+lhhGf7sWsS2/qSyAB/gAv2eyCs7RuVdL7kShgVFHXg5LZ/1zA26UI94lk0CLy7ASqPByvoJWLO07YQZuFhlfvsAE6Jt52qW/Nm5kGibwhhej/ayPfc+9qndVROzQ7I5O+epCBclyPG472a6Gwyl4UC4ftOYFB+S0Ex+PHolg4UTCDJs/l2WkH35+PYpel/pDel7WRryFzsb8MXThrx5lBKXzEh6s+++JVuEL8pKt/FbbBzuVr9D8wlnmhyekuo7ju5z1DbeRPSmgvTD9jWc8wp+/BQ4ptzewn8qVIRT8Zj2Tl5cNfCSrlGJOCQHKSX4WecotQ2LtcQiu6z8CKc5HWoiAdJIIOf1JNFTe/6XsURcwsdJ5OxMnKNCRe4eCeaPQqJtYQGh71F68fSRULyAzbNLD3lKOcy0J04t+57ohnhPQ9XUUqczqY0KJFWolLoCPhyYwmyrm83wlumhhU6VjJUjR2235vy5pU/b35iZrCxxRGdD10zFZBoZ+uyp1tl6cACZBYxmNqUqvq3PJngWD6UuyvyLiJ6AhJA82c6LuXpCfnM="
        }
      },
      "beneficiaryVASP": {
        "vaspCode": "NPUTGqnJs2aPOH9yAaO5W/VGfYvrILZiicUBsQkr8eaomQKawkSZQYAMo7ay/XZeLejNz2e5WNaSTUs398t+PINZ0ALqGH/ZNye+Yz1CvoGhgvyyWLrfZ38bTq81jIUYu4UXpabEw78e1GXWTHDqzRLpxjD0Z8d7EA+k5fN5pg1lDDTUldqMlvIRoYhoHeT9H4TZo/lNaNGqjVbfEcZ9G2UycPQjWrVJ+DaYVNgXzzWGqjnH/frBXSrmqBCmjZofyvQq+ETSGGY9H0o5GzZntN9NyGVD3TljIuZLechN68rspiMt6Fs6D7S1aN58/qB5rCS06uZ3fjZuWXX9ip2dSMDyjx935EIyhutqKdQqhO+v6uo++v5UDv05vIIKuUT471sY3bpcNQVII5dlBa5LdnOOta7YjZL8iwuYWBxtfOpyeWEU6Z/0+AIv6faSlJ0t7evhUb+emvVXE1kfLGi+jepHVNtGvNDraadjFU1v4+Vo79bgqBhD4FHyJzo2IoDHVmZgyAOXOFaBWfNgTGAPX88btgV+qp0CWImk3PQeaSb5b9kRTHaOCxe75EFuIAKK3+MDHPfmCXXyv2EXubFW6bPXOX5YBfD0XtvToW4JfCv3BaUxAK9ib7ZPcpWboSr7wBKQErpcI9SCEeBg1bAK5282EImv/ketjK0sOHC1W2Y="
      }
    }
  }
}
```

## Mandatory field requirements by exchange

Understanding which fields are required for each exchange ensures successful Travel Rule compliance when submitting transactions. The mandatory properties vary by exchange—some have jurisdiction-specific requirements, while others use standardized field combinations.

### Binance

Binance's mandatory properties vary by jurisdiction. To simplify mapping and usage, see the following resources:

* [Mandatory properties for Binance withdrawals](/docs/mandatory-properties-for-withdrawals)
* [Mandatory properties for Binance deposits](/docs/mandatory-properties-for-deposits)

### Bitstamp

Bitstamp does not have jurisdiction-specific requirements. Instead, Bitstamp requires specific field combinations based on transaction type and participant relationship.

**All Bitstamp transactions require:**

* Complete `postalAddress` (streetName, buildingNumber, city, postalCode, country) for all scenarios
* For Individual entities: `names`, `dateOfBirth`
* For Business entities: `company.name`

These requirements apply to both deposits and withdrawals, regardless of whether the participant relationship is FirstParty or ThirdParty.

For detailed field requirements, see:

* [Mandatory fields for Bitstamp withdrawals](/docs/mandatory-fields-for-bitstamp-withdrawals)
* [Mandatory fields for Bitstamp deposits](/docs/mandatory-fields-for-bitstamp-deposits)

### Bitfinex

Bitfinex only requires `piiData` for withdrawals. For deposits, the sending VASP transmits originator information directly to Bitfinex through Travel Rule compliance protocols, so no `piiData` is required in your Fireblocks transaction request.

**All Bitfinex withdrawals require:**

* Complete `postalAddress` (streetName, buildingNumber, city, postalCode, country)
* For Individual entities: `names`
* For Business entities: `company.name`

These requirements apply regardless of participant relationship (FirstParty or ThirdParty). Unlike Bitstamp, Bitfinex does not require `dateOfBirth` for individuals.

<Info>
  ### Note

  The Bitfinex withdrawal examples intentionally omit `transactionData` and `originatingVASP` as these fields are optional for withdrawals.
</Info>

The following example demonstrates a common real-world scenario where minimal required information is provided for a withdrawal.

* **Transaction Type:** Withdrawal
* **Wallet Type:** Exchange
* **Entity:** Individual

**Scenario:** A user is making a withdrawal to a hosted wallet/exchange that belongs to an individual.
**Before Encryption (Compact PII Data)**

```json theme={"system"}
{
  "piiData": {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "isHosted": "true",
        "entityType": "Individual",
        "names": [
          {
            "primaryName": "John",
            "nameType": "Latin",
            "secondaryName": "Doe"
          }
        ],
        "postalAddress": {
          "streetName": "Oak street",
          "buildingNumber": "1",
          "city": "Boston",
          "postalCode": "11000",
          "subdivision": "Massachusetts",
          "country": "US"
        }
      },
      "beneficiaryVASP": {
        "vaspCode": "did:ethr:0xdf41ef7dcb92ab5aed72e284db3766ace5026948"
      }
    }
  }
}

```

**After Encryption (Compact Encrypted Data)**

```json theme={"system"}
{
  "piiData": {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "isHosted": "odRFwGbH1U0Fbe5K7+B34qeN8eAACPPS97ORhkk5LvB2IDwmDkC2jDNyYqmy4AtzWaK6cEM+GsNvE1LIrrOkOTcKI9qFxX+3bprUbPDLSlPGmSkdCwv/xm9EGO7ZJunvBIIO0gXLK7kxkzhBT18YO3T7QQhnbJ+IKLIcb7PJi358jnkkFFMyKdDEg08IzL4a388lghqaK7uP5NWkEGdFFshFESdxQddqW745Y/arbiT6T60Kpk+ZUrapF0AcOiCmkigYyv8L572Ykzs8ev55ywrYbdrcEqfh2yIkde8C0oosbKF7r+Ko3cXVCzNDGBfpgeMmYlVs1yzqUGoShdIlBVf/neCclzXeng0bkoc0BfW52e6g4t8fOE8fBF9KS8XjNAKMpfhfCNl/5h1k6Aj1DlfzBE3ncgBtFPQ6tYu3us3LCKizfqNNiHMOw8Bo1HysplupQq4jMCsHCsRODyDmT55CCPRlvn291EGT6Mc0i9r0Pqz/bxhmapd7w3hk/kcsPgRSdqqwQmf7pMqrQStSaKBnB6pPF5NBCjGBBuIrZGaDCeLnHtTeM0BuhWzXWJltViWp/v8D5hRuG7LqbT2CFHroxTCoSy1vpd5VvjK7b/KyvGVq5jzJ4U4798g4+kVItJsbFFYtKZBCWXhqO7n/d8GVsWrWNBppRzwX4guK9Zw=",
        "entityType": "UeEaw/QcSatRbgoW4Ffku2FkkHksM9gAHVkGxRuyVHxxcU6S5eMuXeWqrRWvACWIXznRaeeCB1R0cSCxIp5e8m7trptB2uyAQ7pvots9YLczm8YIWaniHelQReaNShCsir6Dh9HhcO6gVKKKWYfI0dg09pr3SQx1ajnXm3+FaT7fjDBQCtNU96OgrF6B8D5UVaapKLNQl3PWBw0GnY8LGAUfgqnAq0FZTobAdOJ0lwwuV1jRqPjxjnAjrN6mcbjQzs/7ENyOBLtIlYm/IL1TprpCK9J9SDgBHHaiCFhClP+U8oKrFU+W995ps3vTFI1W/oj86Ye0HTX8nonESmperWGtxuIzAu7CW/hSxQCIe6/lECP5ZpOZZ9YrTw++x2CEifakc+VoIOBZufMRfOHntA8et5PWJsGtCNy1aNTqgGpEjJnBEjnb882pH4rGwAu2uqJE/H2kmswZlTjci7Pcgwuzn5vOU/D5PsbJqPrZynoujQwTelFBnyVfPvEpyFxGW5QIEFQoD9gAUdz+qAqI+AlzQdGa3DqZoALQxA2DtPysZbYGVzKIRHtzLGyhIG+wtzGMw2bTWEixvMZuR7rQXgjGpFGwFmYfT71/+u56tPnCAfLUmcg++6wBknPkdeit4xOWkfmROYgJKqxu5ZPAhpBLDQsMoEohy003iq13x74=",
        "names": [
          {
            "primaryName": "eidD4pDO6xBt8GpFymHCnJQ96bE+mqVMBdXgI+mDstmLmABzGob6JdmDcN24b4kgIpuEEGwJiJTZoVYi+lTuQdPJsA2W6WuSVYJW0Sm8jGfpva7mzg88Uf8N+nHt3yqHo8/m7OeRmd6At+lTscI0pGl6paJky9pTefF8PlSJ4IV7dA1lMNTfE/L8u5bJ/8p+7TX1O+G23UUp21G6xskC54dr6yLYRyer8JTTS2QxB42luYWC3UlIIX9dQRONx5Edr+OV8f5Na4L/+ExuD588dhcUEDjFaffoZhWJYYmfjN9lFVZE2tw6UsGxknH4dNyoc+FiMPeqL4Cw/RbQ+fhxD5otX8au/A4ByhwVMA9a4yt7+kYyNvSWpUGVj0ee43HXvxdIPyKCewaBvbNc5yvwX6X//9c27tjYM1ADRzrSSYzhVHCtlJZ2fwpnmUDcfebemvt/Vrt26BSiXrx1/G14wLhoTcCS6i9av5x82QbQVconePIbRIndIMvgx5Qeir+HU2VyCkAkBie6+NcWgdUHO3h79ZjRS5wsMC13IRX99ClXDsYoJBuOlTGxY8XrAXiTr8+CysHLXileXv+EJyoCf7HaHrXar7ym+xUCqyUnTM/PuPlUVw0D1lK7jjqSEY+0+nZuT5rC+A/n8D6UWRLAgd/V6ghFTe2171ez6hW6z2Y=",
            "nameType": "B6plx2f0k0D5O86CcY1NazOEI/EfDOhQpKR0brKgDbYx5TyY3OmKOciD7NxnV4j0EgtnKMT9vB2vNMS4/Wy9tDXnHxx9h27HkKQnJVppat+jFy1cpSwFeWCjL4w1pxnjTapalZzwWD5nAqjFvOx9IRiCvvonKuRaLQSegqVhhIQCLs9+ZMtaKVy2JNfrDR8Rk8Acof+iP/k1poSwkFBMiOWCAErMEZq+NF0jwYgnDOUoQFT5IC4HDlva9PANMGFJUvW8RpsMduYrjw0e/iBPs01UbKMtCIZ6h+31+XW6b0xfVTI7jwowPNWe5uvybaG8wzPSLVnmUi2+/OoJax8tUwlCXBHD8keocSZpaPZ1ahuJW6bI+3rFP/FRk6asg8iC4A78d7RKsvomcA3+AtXUWHR7dRQlQVwRI3SWuMP+YWXfI2lt1dT4Zq957FQSdDxAb5t83rDJGv75s9x4Bv9dBY1Lz2mQkzXROHfHQ/6W1SW8FzrSysm9QT5/nFddpzhVpGLpcTt7nXNNxs3PqsFQD14KClAjDQ44yBdDD8MV7txQmo0Gc+mmqvBs0cekpwbBJpm2fRcFzFGYidzu/qUB5vBOH0urT74mLBIKYeW6TnB9xwhaXHYDkU76zntIxQRACd+8Vol85Bb3SR8B8lorgEW9OpYw2kvdnImiKrF/yJc=",
            "secondaryName": "Nl+eig8i/WL4Fue5HMzQ/NCEQSj7std3eggvgh6NTW/2bLLlBuoeJttS6jmQA5Qs+/QrZ9k01AUXmYhWp7mYLFaCY9vZ9J1C7YThlrXjdSCH71dpJxoF25+HsGz2NPA+mDg0GWb+bwcwiKbHnaKlujeBNN1TKQabFwoOUXsYBeDhwveagHly45+t5QwlMi8R+wdXsfxTIAX6JnjPRywHb/uropU2X/cX2KUzgRUQ8BCBnOGO5uh7kFbCRNAMScA5byXBx4RZbolFIvMWJkpvoeXgIFKLqN5M6qe3GePLHTIWbs7EsNFlufKwYunmsADj5xWg+vO1s0L1fKslf2iWSaQTBTzcRLjdkFKngJoyyktXARQJxJwLyFksNyfhAp+64upqBg1eSiSBDcSUIKq2kZMyBdOYnq4ZrnEI89Gqlt50h9FpHuCZzgLzYhPThSKwtgOpEXG7CtVIbNy8EGGjnQiD3Hu4k1piwZ9FY+FBlz9h9oKsxHXho93oz2g1ZufGz64iqis3A+gAiNnBjJayzPRxcSRqRXfPBzU1g1IJttKsvYRP66ouocHWRpCGJNDnKTEZozDlm1G8Ysbh/HXRBG/41pzp3MTj53gNxJ+/PW0VA3bcdU4/aZOv8m4xAjufcSJUXXLQEvRe9s8hi4HroTKYxELDZC0tU4vGe4t5Vng="
          }
        ],
        "postalAddress": {
          "streetName": "eiFtUS4TgBrsxUbNiksZ1RsWlPrCpE/rVrfghwhoYjqdkhdlxfZV8k/Odu/pjAVhtalWfEFOj/oWLp/IhlzkAhxKUg9GxXqv1kyMQBi/qsGm0zuNW8eYkYd9DD0K0ERWAsZXvxHfDbTxzdHEmSyu1sdefX/HM2yRuUo80DAPqY36h5YoxVtGsDZ3eJ53a6HYxD7KHf/tsdPWn+GS8BsWe4HxlDh8nvRnNB/Q6+8puvo+nNRMtBV4Vum9eY60wyGBtgn19g6m8UPe3josrsxj9zUI59uAy3AH5QjaUSeYBTXDwUZl9uP9UAjx5QyGlVnZSy8d3ciWnc0fdxBJZWoE3aGNQLJq3iaoSwSnBHNbhaeNwVw6yXzW77PJEJiONFZzbyrBnWU/yAhKPsOk4xYsNMJ33yfxj2ZLbCeIS5xyNxj7QS4W+tMyfqSIAEzneXZvYmYJHUkZykyOla7drmiXByUaGKfQvKa+Pyh9daRI+tVQE/NZnGG3+p3laLSzx7LAU7Qc4BZ9Te/FLPCfcfTphn+wPLj7MDicCpvllblK+tlKW5Q/NFF9+vTzCkXtVD1ESbzTot3Hz7nrjGUqSr89N3i6vvddWLwUfpPHDi+Jd6m2X0sZgKXQZIXL1IsWJka4OWOecIfvB4QLSiXS4Bnan7dNj6v0emYzIrswoJoWC6w=",
          "buildingNumber": "JC3m27RRk8iH9HBA/lNhqTt/XnEtnDOXFIA6Tl3TPazmvAFAhd+SxHWKlVULg2rMBriy+AfHsIR9RX71+fUQBKhG0SyzuFieNFwfijDWbfVDfJYmRmiksEkepsrPNRQlC0vacP4yiIICVZqQZYt8tvkJ+3otOAtJQ9L5k/Dcf6GB0luUI8NXXglokrmWk32BUXfB/6kaLRCqSHE5fBeJDx7MdzsasQOULsavUrhjz3+XmeDoVghooYbkg47ATnAeNb3EyEFotKqeYtCsIdgk+DzjS56HAol5nmPeoJTqxhrLvQp/Qdgw8+y4Jt/W80/p/rZVMowQnt0sn+fHnn0LqeZdB3b4asbX6kQeZGHrjTO35STgs4ppvHp+YBOSoxOJsUJBHat+Yfeb0Q1vydBD2s8vQCeqUwN2EZEa7D7p6VdcSaa3fAZXrOs40qMVZDA4yjJ8unbN2egMcq64mZqfzM9IAkfN6E5AZ8L6Mgz1H8+fPQUFMwawOW6rZssaXOwjCnU9nbNcI4Rz8S07/BaY/DOPyKOPSUtG3oyplUoKPpdMPAsbokcVmJW0eb4vMT8NUIzVM0JnA+VBy49mGTNMv/N1C/9eajzj3uZjkBCxBKDOhAiYhAziZLfWqaHhCTBNyqB0e2776wDEZcGvatlz4kRffZEBh0O7YfoWGGqKGfg=",
          "city": "td6CCpM/U799g8jmbSfm4HBKCONWLuJ0FNJ5hIrRBsYa4ju2+poEsmu5dUmFNg17afhMBhbchuNY9RY0SZxNnwIloPQibdJrkY2PpxQOaytXJvdHfbCDie2IZDSZ2kqOuT/FNMQlpbkUaSGVIrTYMrXLuT7Y4lvH+nsOEL3Hpkg+sKEXgZco7UlkoZhas6oQ3RYAzDGpNomzwWfQLy75ef/vfvomSny6a8RroZscATgNKLPIBedi+Aq9egELIE5c3+JHhnhn1a23R75HzKG5RHb8HZ2ddAFG7UJWOf0mOzaKkLF89xLgSmVCOGQCBEyW67SkM4yeWZU5PTxIrmKORl8ndfQVYGsFh0UikAZ+7yVCsghlj1kKrH8vP8QuFEshW6iHTENesbEAXKu5uFh17ANcwgwTetwPjxe/EDBH69bSYt9WzPntsDs0Dk3vvUMZ2YMXyFaK/mKa7F7on4JZHcGIj0Wb6GVM+M8q0R9UyGDTz1L+ho6hgA2OsEIJ/7RKAn9KVCOXyDiH9sEHgrF9bhGGOUkkRjK5PYmIao9pEPWavcIsKvvCeFsm+tk0H1RuTp1GvojYsbyAGSKpi1a2wnqY+XCtDkUDE1mOCzzwklMIW6qCq1QmNr0NQbocH7GI9oWBTrl+A7y5NJpzBHHkHH7t06OODv0jjbkV+hj7Lj4=",
          "postalCode": "bz0BGwPFlCY5hyMkbfoxYkTq3uCFBoqG4gIDh56dz8cthPteUTRHA1MN4QJRHaDYiXkl0FxRhwY7k7FSm3+XqhPlafF1UNTE5Dq0CAQmYoTtRgLst6pREZWePMePXF3UeitfAMByZU2G5kt6hPO0ut6oBLZrT52ds8O83IjC1iJye9nSl7QU9U+Li+wRi8yqH4gSP6h+Hyf4hrYP7rqRbOehLolDfOIzxedpEPkr78ryfApv2lZaZWffMYwz5N6I2pKp6U9FGfCv3HJbIsyK0JiuFbOND9gPn7Fb98FcSL0OKgvS0H6+8DxDA84CRCjNUOKEHf4uu+5vB9rt/XR5JTPxpk0wFtwUPdt2DroG4Sl13FhjZL2nCJbe5EC9mPa2pHotaTRs/NeG5zlMGGTQA96VA1DR6ZugO0YxjCkmBbCQ75/6yKSpH4xiVaIk2mDk+SpbjpjjzJXnHrdAGwPHig/v9EIvyYTkwBBOcQ0M0HOcKPhTOxcFKET3fWkM498Oya4A7/3aN0bbdpfgIbjIX/3A8BObd+UMjYuz1fPwRIZHxDVUMuPdbrA0oGxxFZV1tVwPracgJ845cygt3HJbn6l7I+ao/VtTyhorfqFwTtpaHd/WmOw6Jr0zpRaYEyBBjS+eQD2g2OYOAEDoIqrvMr8isZ9kRqUxXXTxtcDYDSM=",
          "subdivision": "IYO7soEscFJRNL4XMrghCgLi64XywMSRSpwImiVzU0Qh7fdXqgsbkpnRdW0XxsCgdmpSjAb+7OAOMMKZFKpzTed7nSugGz0fKYZR+PH8Ca+lBGwjqIax8w2b69jZSGDNiyMMRoIEDvGK/f5exaJR408YuUShl6vGpSH6+p28d/hBbN/VEBCnFVkU/6+G62Ej7NmQ4ucn3388xTbMQyq+D0KpR4PeI3gi5SYpuKsgu8sniD0j/pqZsmGD/OY4KW90A2XqnkX4x7dMd7jvL8HDkSsL1ewOx4BiwZgbmrJjuX2eV+SRpYhj4a4i5na/2kIS2z3DgahfCkDsCxjWM2hf4IpbDvAtViYEero2yWBlwKkF6f36XO39uEIorl3RJa6saKkvg5CoiRUxEjazpn8rInJoLKo1NbtxgDyoYmEqqKcrn26Nv5ETOFDu1Y8AljPOhA4FW7N3xcBJDKfYIVW1TJiXZ1zDveFj0GccHP+RZOixuBT5gu2BWSDG9Xz7oCu4eTsQoWqeOBe2WFNQFWXQ91dp+a+asDoSCkd/KDI/8drdp3y/Yhyx7JI4nQ7IVXWcodJA/X3y6aMxGdnt1p1aDp+i8auMzfvwsEAH3ATzS1MNYoGdg05oFpDk38rXbQvdEsde+vKZmmo4u6n7i+weNaeAHeAOkhAkyBoPAZxVdrY=",
          "country": "aBDC/toz/kTpplSpTc10iV4IRqVqaT1cYoOqvpJy00Rpnnw4qB0gf29FJsaW5hG1XV4J6nPOphcgCK1tN9LGeqk2tF2SAl1cnTiEfuDTrX4D4Uj8dxlAKOuqcT9p+lhhGf7sWsS2/qSyAB/gAv2eyCs7RuVdL7kShgVFHXg5LZ/1zA26UI94lk0CLy7ASqPByvoJWLO07YQZuFhlfvsAE6Jt52qW/Nm5kGibwhhej/ayPfc+9qndVROzQ7I5O+epCBclyPG472a6Gwyl4UC4ftOYFB+S0Ex+PHolg4UTCDJs/l2WkH35+PYpel/pDel7WRryFzsb8MXThrx5lBKXzEh6s+++JVuEL8pKt/FbbBzuVr9D8wlnmhyekuo7ju5z1DbeRPSmgvTD9jWc8wp+/BQ4ptzewn8qVIRT8Zj2Tl5cNfCSrlGJOCQHKSX4WecotQ2LtcQiu6z8CKc5HWoiAdJIIOf1JNFTe/6XsURcwsdJ5OxMnKNCRe4eCeaPQqJtYQGh71F68fSRULyAzbNLD3lKOcy0J04t+57ohnhPQ9XUUqczqY0KJFWolLoCPhyYwmyrm83wlumhhU6VjJUjR2235vy5pU/b35iZrCxxRGdD10zFZBoZ+uyp1tl6cACZBYxmNqUqvq3PJngWD6UuyvyLiJ6AhJA82c6LuXpCfnM="
        }
      },
      "beneficiaryVASP": {
        "vaspCode": "NPUTGqnJs2aPOH9yAaO5W/VGfYvrILZiicUBsQkr8eaomQKawkSZQYAMo7ay/XZeLejNz2e5WNaSTUs398t+PINZ0ALqGH/ZNye+Yz1CvoGhgvyyWLrfZ38bTq81jIUYu4UXpabEw78e1GXWTHDqzRLpxjD0Z8d7EA+k5fN5pg1lDDTUldqMlvIRoYhoHeT9H4TZo/lNaNGqjVbfEcZ9G2UycPQjWrVJ+DaYVNgXzzWGqjnH/frBXSrmqBCmjZofyvQq+ETSGGY9H0o5GzZntN9NyGVD3TljIuZLechN68rspiMt6Fs6D7S1aN58/qB5rCS06uZ3fjZuWXX9ip2dSMDyjx935EIyhutqKdQqhO+v6uo++v5UDv05vIIKuUT471sY3bpcNQVII5dlBa5LdnOOta7YjZL8iwuYWBxtfOpyeWEU6Z/0+AIv6faSlJ0t7evhUb+emvVXE1kfLGi+jepHVNtGvNDraadjFU1v4+Vo79bgqBhD4FHyJzo2IoDHVmZgyAOXOFaBWfNgTGAPX88btgV+qp0CWImk3PQeaSb5b9kRTHaOCxe75EFuIAKK3+MDHPfmCXXyv2EXubFW6bPXOX5YBfD0XtvToW4JfCv3BaUxAK9ib7ZPcpWboSr7wBKQErpcI9SCEeBg1bAK5282EImv/ketjK0sOHC1W2Y="
      }
    }
  }
}

```

## Final checklist for developers

Before deploying your integration, ensure you have completed the following:

* [ ] **Select a cryptographic library/SDK:** Choose and integrate a library that can perform hybrid encryption (RSA-OAEP + AES-256-GCM) using a counterparty's public key.
* [ ] **Implement public key retrieval:** Implement the logic to securely fetch the recipient's public key from the Fireblocks API before each transaction.
* [ ] **Map PII fields:** Ensure your system correctly maps your customer data to the fields required by the `piiData` object structure.
* [ ] **Handle jurisdictional logic:** Implement logic to determine the required PII based on the transaction amount and the jurisdictions of both VASPs.
* [ ] **Encrypt the payload:** Confirm that all sensitive fields within the `piiData` object are correctly encrypted.
* [ ] **Test with Sandbox:** Use the sandbox environments provided by Fireblocks to test your implementation thoroughly.
* [ ] **Confirm data accuracy:** Work with your compliance team to ensure the plaintext PII being sent for encryption is accurate and matches the KYC records on file.


# Add an Exchange Account
Source: https://developers.fireblocks.com/docs/add-an-exchange-account

You can easily add your own exchange account to the Fireblocks workspace, provided it's supported by Fireblocks. Once connected, you can seamlessly transfer funds between your exchange account and Fireblocks via the console or API. This guide will explain to you how to add an exchange account via our TypeScript and Python SDK.

## Prerequisites

1. Contact your CSM to enable this feature and get access to:

   1. [Get Exchange Accounts Credentials Public Key endpoint](/reference/getexchangeaccountscredentialspublickey)
   2. [Add an Exchange Account endpoint](/reference/addexchangeaccount)

2. Make sure to prepare your workspace and perform all the steps necessary [here](/reference/quickstart).

3. Install all the prerequisites for our [TypeScript](/reference/typescript-sdk) and [Python](/reference/new-python-sdk) SDK.

## Add an Exchange Account via SDK

You can use the following code to add an exchange account

<Info>
  ### Note:

  This endpoint currently only supports the following exchanges `INDEPENDENT_RESERVE`,`BIT`, `BITHUMB`, `BITSO`, `CRYPTOCOM`, `BYBIT_V2`, `WHITEBIT` , `HITBTC`, `GEMINI`, `HUOBI`, `GATEIO`, `COINHAKO`, `BULLISH`, `BITGET`, and `LUNO`
</Info>

<CodeGroup>
  ```python Python theme={"system"}
  import base64
  import json
  from fireblocks.client import Fireblocks
  from fireblocks.client_configuration import ClientConfiguration
  from fireblocks.base_path import BasePath 
  from fireblocks.models.add_exchange_account_request import AddExchangeAccountRequest
  from cryptography.hazmat.primitives.serialization import load_pem_public_key
  from cryptography.hazmat.backends import default_backend
  from cryptography.hazmat.primitives.asymmetric import padding
  from cryptography.hazmat.primitives import hashes
  from pprint import pprint

  my_api_key="your_api_key"

  with open('your_secret_key_file_path', 'r') as file:
      secret_key_value = file.read()

  configuration = ClientConfiguration(
          api_key=my_api_key,
          secret_key=secret_key_value,
          base_path=BasePath.US #Make sure to use the correct environment. Please see the note
  )

  with Fireblocks(configuration) as fireblocks:
      tenant_id = None
      public_key = None

      try:
          # Get exchange accounts credentials public key
          api_response = fireblocks.exchange_accounts.get_exchange_accounts_credentials_public_key().result()
          tenant_id = api_response.data.tenant_id
          public_key = api_response.data.public_key
      except Exception as e:
          print("Exception when calling ExchangeAccountAPI->get_exchange_accounts_credentials_public_key: %s\n" % e)
          exit(1)

      # Credentials encryption
      exchange_api_key = "your_exchange_account_api_key"
      exchange_api_secret = 'your_exchange_account_secret_key'

      credentials = {
          "apiKey": exchange_api_key,
          "secret": exchange_api_secret,
          "tenantId": tenant_id,
      }

      pem_public_key = load_pem_public_key(bytearray(public_key, 'utf-8'), default_backend())
      credentials_str = bytes(json.dumps(credentials, separators=(',', ':')), 'utf-8')
      ciphertext = pem_public_key.encrypt(
          credentials_str,
          padding.OAEP(
              mgf=padding.MGF1(algorithm=hashes.SHA256()),
              algorithm=hashes.SHA256(),
              label=None
          )
      )
      
      encrypted_creds = bytes.decode(base64.b64encode(ciphertext))

      # Prepare add exchange account request
      add_exchange_account_request: AddExchangeAccountRequest = AddExchangeAccountRequest(            
                                      exchange_type='BIT',
                                      name='My BIT account',
                                      creds=encrypted_creds,
                                      key=exchange_api_key
      )

      try:
          # Add an exchange account
          future = fireblocks.exchange_accounts.add_exchange_account(add_exchange_account_request=add_exchange_account_request)
          api_response = future.result()  # Wait for the response
          print("The response of ExchangeAccountAPI->add_exchange_account:\n")
          pprint(api_response.data.to_json())
      except Exception as e:
          print("Exception when calling ExchangeAccountAPI->add_exchange_account: %s\n" % e)
  ```

  ```typescript TypeScript theme={"system"}
  import { readFileSync } from 'fs';
  import { Fireblocks, BasePath, ExchangeAccountsApiAddExchangeAccountRequest } from "@fireblocks/ts-sdk";
  import { webcrypto } from "crypto";
  const crypto = webcrypto;

  const EXCHANGE_API_KEY = "exchange_api_key";
  const EXCHANGE_API_SECRET = "exchange_api_secret";

  const FIREBLOCKS_API_SECRET_PATH = "./fireblocks_secret.key";

  const fireblocks = new Fireblocks({
      apiKey: "my-api-key",
      basePath: BasePath.US, //make sure to use the correct environment. Please see the note
      secretKey: readFileSync(FIREBLOCKS_API_SECRET_PATH, "utf8"),
  });

  async function getExchangeAccountsCredentialsPublicKey() {
      return (await fireblocks.exchangeAccounts.getExchangeAccountsCredentialsPublicKey()).data;
  }

  function str2ab(str: string): ArrayBuffer {
      const buf = new ArrayBuffer(str.length);
      const bufView = new Uint8Array(buf);
      for (let i = 0, strLen = str.length; i < strLen; i++) {

          bufView[i] = str.charCodeAt(i);
      }
      return buf;
  };

  function arrayBufferToBase64(buffer: ArrayBuffer): string {
      const bytes = new Uint8Array(buffer);
      let binary = '';
      for (let i = 0; i < bytes.length; i++) {
          binary += String.fromCharCode(bytes[i]);
      }
      return btoa(binary);
  }

  async function encryptCredentials(publicKey: string, payload: any) {
      const pemHeader = '-----BEGIN PUBLIC KEY-----\n';
      const pemFooter = '\n-----END PUBLIC KEY-----';
      const extractedCode = publicKey.substring(pemHeader.length, publicKey.length - pemFooter.length);
      const binaryDerString = atob(extractedCode);
      const binaryDer = str2ab(binaryDerString);

      const cryptoPublicKey = await crypto.subtle.importKey(
          'spki',
          binaryDer,
          {
              name: 'RSA-OAEP',
              hash: 'SHA-256',
          },
          true,
          ['encrypt'],
      );

      const payloadStr = JSON.stringify(payload);
      const encodedDataString = new TextEncoder().encode(payloadStr);

      const encryptedData = await crypto.subtle.encrypt(
          {
              name: 'RSA-OAEP',
          },
          cryptoPublicKey,
          encodedDataString,
      );

      const encryptedDatab64 = arrayBufferToBase64(encryptedData);

      return encryptedDatab64;
  }

  async function main() {

      try {
          const credsPublicKey = await getExchangeAccountsCredentialsPublicKey();

          let credentials_payload = {
              "apiKey": EXCHANGE_API_KEY,
              "secret": EXCHANGE_API_SECRET,
              "tenantId": credsPublicKey.tenantId,
          };

          const encryptedCredentials = await encryptCredentials(credsPublicKey.publicKey, credentials_payload);

          const request: ExchangeAccountsApiAddExchangeAccountRequest = {
              addExchangeAccountRequest: {
                  name: "My BIT account",
                  exchangeType: "BIT",
                  creds: encryptedCredentials,
                  key: EXCHANGE_API_KEY
              }
          };

          const addExchangeResponse = await fireblocks.exchangeAccounts.addExchangeAccount(request);
          console.log(addExchangeResponse);
      } catch (e) {
          console.log(e)
      }
  }

  (async () => {
      await main();
  })();
  ```
</CodeGroup>

<Info>
  ### Note:

  Make sure you're using the correct value for the API base URL for your environment:

  * `BasePath.US` - for production workspaces
  * `BasePath.Sandbox` - for sandbox workspaces\`
</Info>


# API Communication
Source: https://developers.fireblocks.com/docs/api-communication



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

<Warning>
  ### Not familiar with the API user creation and authentication?

  Visit the links below to understand how each process works:

  * [API user creation](/docs/quickstart#api-user-creation)
  * [API user authentication](/reference/signing-a-request-jwt-structure)
</Warning>

# Overview

API communication between the customer backend and the Fireblocks platform occurs over HTTP (REST). Authentication uses API users and JSON Web Tokens (JWTs) signed for each request.

**Note**: For end users accessing via the app with the Embedded Wallet SDK, authentication uses IDP tokens and pre-configured SSO OAuth, where the NCW Signer API user is configured.

# API roles

The Fireblocks EW feature requires two API roles: **EW Admin** and **EW Signer**.

## EW Admin

This role is used for administrative workspace operations, such as disable/enable a wallet.

## EW Signer

This role is used for specific wallet operations, such as creating a transaction from a specific end user wallet.

There are two ways in which this API user is used:

* Implicitly, as part of the EW SDK using the OAuth pre-configured configuration.
* Explicitly, similar to the NCW Admin API user (using signed JWT)

# Role permissions

The table below lists the different operations that can be executed by the EW Admin & EW Signer API users.

| API User Role/ Operation                          | EW Admin | EW Signer |
| ------------------------------------------------- | -------- | --------- |
| Create new EW Everywhere                          | ✅        | ❌         |
| Create new account under a specific EW Everywhere | ✅        | ✅         |
| Enable/Disable EW Everywhere                      | ✅        | ❌         |
| Get deposit address information                   | ✅        | ✅         |
| Create transaction from EW Everywhere             | ❌        | ✅         |
| Get transaction fee information                   | ✅        | ✅         |
| Cancel transaction                                | ❌        | ✅         |
| Decline transfer                                  | ❌        | ✅         |
| Enable/disable a signing device                   | ❌        | ✅         |
| Invoke RPC (relayed from the EW Everywhere SDK)   | ❌        | ✅         |
| Add asset to an account under an EW Everywhere    | ❌        | ✅         |
| Get public key                                    | ✅        | ❌         |
| Delete algorithm                                  | ✅        | ❌         |


# Associate End Clients
Source: https://developers.fireblocks.com/docs/associating-end-clients-with-transactions



# Overview

You may want to or be required to add end-client identification information to vault accounts and wallets. Depending on the purpose, you can use different endpoints and parameters to do this.

# Internal or auditing identification purposes

## Vault accounts

When an end client owns (or will own) all the wallets and addresses inside a vault account, call one of the following endpoints:

* [Create a new vault account](/reference/createvaultaccount) (for new vault accounts)
* [Rename a vault account](/api-reference/vaults/rename-a-vault-account) (for existing vault accounts)

Then, use the `name` parameter to enter their identification information (e.g., "Customer\_12345\_Vault"). This propagates the information to every transaction that uses that vault account.

<Warning>
  ### Please make sure to not pass any PII data!
</Warning>

## Wallets

When an end client owns (or will own) only one or only a few wallets inside a vault account containing many other wallets, call one of the following endpoints:

* [Create an internal wallet](/reference/createinternalwallet) (for new internal wallets)
* [Create an external wallet](/reference/createexternalwallet) (for new external wallets)

Then, use the `name` parameter to enter their identification information (e.g., "Customer\_12345\_Wallet"). This propagates the information to every transaction that uses that wallet.

<Info>
  ### Note

  Wallets cannot be renamed, so you must create new wallets for existing end client wallets.
</Info>

## Deposit Addresses

When an end client owns (or will own) only one or only a few deposit addresses inside a wallet containing many other addresses, call one of the following endpoints:

* [Create a new asset deposit address](/reference/createvaultaccountassetaddress) (for new deposit addresses)
* [Update address description](/reference/updatevaultaccountassetaddress) (for existing deposit addresses)

Then, use the `description` parameter to enter their identification information (e.g., "Customer\_12345\_Address"). This propagates the information to every transaction that uses that deposit address.

# AML/CFT identification purposes

<Warning>
  ### Warning

  The `customerRefId` parameter should be used *only* for this purpose, as AML providers use it to associate the owner of funds with transactions.
</Warning>

## Vault accounts

When an end client owns (or will own) all the wallets and addresses inside a vault account, call one of the following endpoints:

* [Create a new vault account](/reference/createvaultaccount) (for new vault accounts)
* [Set an AML/KYT customer reference ID for a vault account](/reference/setvaultaccountcustomerrefid) (for existing vault accounts)

Then, use the `customerRefId` parameter to enter their identification information (e.g., "Customer\_12345\_Vault"). This propagates the vault account's name, the wallet address, the asset name, and the end client’s information to every transaction that uses that vault account.

## Wallets

When an end client owns (or will own) only one or only a few wallets inside a vault account containing many other wallets, call one of the following endpoints:

* [Create an internal wallet](/reference/createinternalwallet) (for new internal wallets)
* [Create an external wallet](/reference/createexternalwallet) (for new external wallets)
* [Set an AML/KYT customer reference ID for an internal wallet](/reference/setcustomerrefidforinternalwallet) (for existing internal wallets)
* [Set an AML/KYT customer reference ID for an external wallet](/reference/setexternalwalletcustomerrefid) (for existing external wallets)

Then, use the `customerRefId` parameter to enter their identification information (e.g., "Customer\_12345\_Wallet"). This propagates the name of the vault account containing the wallet, the wallet address, the asset name, and the end client’s information to every transaction that uses that wallet.

## Deposit Addresses

When an end client owns (or will own) only one or only a few deposit addresses inside a wallet containing many other addresses, call one of the following endpoints:

* [Create a new asset deposit address](/reference/createvaultaccountassetaddress) (for new deposit addresses)
* [Assign AML customer reference ID](/reference/post_vault-accounts-vaultaccountid-assetid-addresses-addressid-set-customer-ref-id) (for existing deposit addresses)

Then, use the `customerRefId` parameter to enter their identification information (e.g., "Customer\_12345\_Address"). This propagates the name of the vault account containing the wallet, the wallet address, the description of the deposit address, the asset name, and the end client's information to every transaction that uses that deposit address.


# AWS Nitro API Co-signer Architecture
Source: https://developers.fireblocks.com/docs/aws-nitro-api-co-signer



<Info>
  ### Learn how to install AWS Nitro Co-signer in the [following guide](/reference/install-api-cosigner-aws)
</Info>

## AWS resources used by the Co-signer

The Fireblocks AWS Nitro API Co-signer leverages AWS Nitro Hypervisor technology and attestation mechanisms. It utilizes the following AWS resources:

* **EC2 Instance**: Nitro-capable VM, through which the enclave operates.
* **S3 Bucket**: used as the Co-signer's persistent storage and holds the encrypted database of the Co-signer.
* **KMS Customer Managed Key**: used to securely protect the Co-signer's MPC keyshares, which are stored in the Co-signer's persistent storage within an S3 bucket.
* **IAM Role**: used to tie everything together by granting only the necessary permissions to the specific resources.

<Warning>
  ### **Important**: Allocate a separate set of resources for each Co-signer to prevent conflicts and ensure isolation, enhancing security.
</Warning>

This is illustrated in the block diagram below:

<img alt="" />

## Co-signer attestation

Fireblocks uses Nitro’s Platform Configuration Register (PCR) as an attestation mechanism to ensure the enclave image file that is accessing the resources at runtime is signed by Fireblocks.

In AWS, **PCR8 (Platform Configuration Register 8)** is a part of the **Trusted Platform Module (TPM)** ecosystem and is specific to environments involving Nitro Enclaves or other secure computing contexts.

In the AWS Nitro Co-signer, **PCR8** measures specific details about the Co-signer during the secure boot process. It ensures setup integrity by validating Fireblocks' enclave image signature when accessing the Customer Managed Key (CMK).

## Secure Co-signer database encryption scheme

The following process is implemented to build and secure the Co-signer's database:

1. The user creates and configures a symmetric Customer Managed Key (CMK) in the KMS.
2. The Co-signer, upon initialization, asks KMS to generate an additional AES 128-bit CBC key: `FBKS-DB-Key`
3. The Co-signer initializes its encrypted database using the key `FBKS-DB-KEY`
4. The Co-signer encrypts `FBKS-DB-KEY` using the CMK.
5. The Co-signer saves its encrypted database and the encrypted form of `FBKS-DB-KEY` in the S3 bucket, serving as its persistent storage
6. The access to KMS, including the CMK, is restricted using a Fireblocks enclave image attestation signature and the IAM role and policies that were created by the user.

This is illustrated in the block diagram below:

<img alt="" />

## AWS Nitro installation package

The installation package contains an Enclave Image File (EIF) and a set of installation scripts. The EIF is built based on the image containing the common API Co-signer code and the AWS Nitro enclave functionality. This image is scanned for known vulnerabilities, and only then does the build process continue based on the AWS build procedure.


# Backup and Recovery Overview
Source: https://developers.fireblocks.com/docs/backup-and-recovery-overview



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

# Overview

The Fireblocks Embedded Wallet (EW) provides a backup and recovery mechanism to ensure that users can recover their keys even if their EW device is lost or damaged.

The Fireblocks EW feature allows you to create a backup of the end-user key share on the device. When initiating the backup, the customer application will generate an encryption key. The key share is then encrypted using this key and stored on Fireblocks servers. The encryption key can then be backed up in various ways, such as placing it on the user's iCloud or Google Drive using end-user authentication or simply downloading it to a file.

Upon recovery, the encrypted key share is fetched from Fireblocks' servers, and if the end-user provides the correct encryption key, the recovery will be successful.

<img alt="" />

# Key Backup Configuration

Key backups are required by default in Fireblocks workspaces. If you want to make them optional, submit a request to Fireblocks Support (requires a Fireblocks Help Center login).

Please note that when key backups are not required, end users can start using their wallets without a backup (but can create one later). Fireblocks highly recommends users create backups since it helps ensure they can access their funds.


# Boost Transactions
Source: https://developers.fireblocks.com/docs/boost-transactions-1



# Overview

ETH transactions can get stuck due to insufficient gas fees or sudden spikes in network congestion. When the gas fee provided is too low compared to the current network demand, validators may prioritize other transactions with higher fees, causing your transaction to remain unprocessed in the mempool.

This can lead to delays and a backlog of subsequent transactions, especially if they depend on the completion of the stuck transaction. Managing gas fees and monitoring network conditions are crucial to prevent transactions from getting stuck.

Replace By Fee (RBF) and Child Pays For Parent (CPFP) are mechanisms used to expedite stuck transactions on blockchain networks.

* **RBF** - commonly used in Ethereum and other EVM-based networks, allows a sender to replace a pending transaction with a new one that has a higher gas fee, increasing the likelihood of it being processed promptly.
* **Drop EVM transaction** - uses RBF to replace the original transaction with a new transaction of 0 value, and a destination identical to the source, effectively canceling the transfer.
* **CPFP** - primarily used in Bitcoin, involves creating a new transaction (the child) that pays a higher fee, incentivizing miners to also confirm the original stuck transaction (the parent) due to the combined higher fee.

Both RBF and CPFP methods aim to prioritize the processing of transactions that might otherwise remain stuck due to low fees or network congestion.

# RBF and CPFP in Fireblocks

Fireblocks customers can boost or drop their stuck transactions using the following methods:

* Clicking the "Boost" icon on the Transaction card in the Fireblocks Web Console. For more information on the process and the availability of the boosting operation, refer to this [guide](https://support.fireblocks.io/hc/en-us/articles/360018600160-Boost-or-drop-a-stuck-EVM-based-transaction).
* Using the Fireblocks API for the following scenarios:
  * [Perform RBF for a stuck EVM transaction](/reference/boost-transactions#replace-by-fee-rbf-for-evm-networks)
  * [Drop a stuck EVM transaction](/reference/boost-transactions#drop-evm-transaction)
  * [Perform CPFP for a stuck BTC transaction](/reference/boost-transactions#cpfp-child-pays-for-parent-for-btc)


# Building with AI
Source: https://developers.fireblocks.com/docs/building-with-ai

AI-assisted development is the default way to build on Fireblocks. This page explains the tools available and when to use each.

Building on Fireblocks is designed to work with AI agents. Start by connecting your agent to the docs — the Documentation MCP is the one step that applies regardless of how you build. From there, use whichever combination of SDKs, CLI, and platform tools fits your workflow.

<Card title="Get Started" icon="rocket" href="/docs/quickstart">
  The quickstart walks you through connecting your agent to the docs, setting up API authentication, and making your first Fireblocks API call — with SDK and CLI paths both covered.
</Card>

## Developer tools

These are the tools that matter most when you're writing code against the Fireblocks API.

### Fireblocks Documentation MCP

**What it is:** An MCP server that gives your coding agent (Cursor, Claude Code, Codex, or any MCP-compatible tool) real-time access to Fireblocks developer documentation. Your agent can search, read, and cross-reference docs without leaving your IDE.

**When to use it:** Always. Install this before anything else. It keeps your agent grounded in canonical, up-to-date documentation rather than training-data guesses — especially important for Fireblocks, where API behavior, authentication, and object models have specific details that general LLM training may not reflect accurately.

**How to use it:**

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={"system"}
    claude mcp add --transport http fireblocks-docs https://www.developers.fireblocks.com/mcp
    ```
  </Tab>

  <Tab title="Cursor">
    [Click here to add the Fireblocks Documentation MCP to Cursor.](https://cursor.com/en/install-mcp?name=fireblocks\&config=eyJ1cmwiOiJodHRwczovL2RldmVsb3BlcnMuZmlyZWJsb2Nrcy5jb20vZG9jcy9tY3AifQ==)

    <Tip>
      If the link doesn't open, add it manually from Cursor's MCP settings using the endpoint: `https://www.developers.fireblocks.com/mcp`
    </Tip>
  </Tab>

  <Tab title="Codex">
    ```bash theme={"system"}
    codex mcp add --transport http fireblocks-docs https://www.developers.fireblocks.com/mcp
    ```
  </Tab>

  <Tab title="Other">
    Point any MCP-compatible client at the Fireblocks Documentation MCP endpoint:

    `https://www.developers.fireblocks.com/mcp`
  </Tab>
</Tabs>

Once installed, your agent can answer questions like:

* *What fields does a vault account have?*
* *How does Fireblocks JWT signing work?*
* *What webhooks fire when a transaction is confirmed?*

**Without an MCP client:** Every page on this site has a **Copy Page** button — use it to paste a page directly into Claude, ChatGPT, or any other LLM. You can also open the page URL in Claude's Projects or any tool with web access. The MCP handles search and freshness automatically, but copying a specific page works well when you need focused context on a single topic.

### llms.txt and llms-full.txt

Fireblocks publishes documentation in the [llms.txt](https://llmstxt.org/) format for tools and workflows that expect a static, crawlable text bundle:

* **[llms.txt](https://www.developers.fireblocks.com/llms.txt)** — a compact index and entry point to the docs.
* **[llms-full.txt](https://www.developers.fireblocks.com/llms-full.txt)** — a broader aggregate of documentation content for setups that load one large file.

Use these when you cannot run an MCP client, need an offline or snapshot ingest for a custom index, or are wiring a tool that only understands llms.txt URLs.

<Tip>
  For everyday coding with an AI agent, the **Fireblocks Documentation MCP** (above) is the best option: it searches and retrieves the right pages on demand, reflects the current site, and avoids pulling huge static exports into context. Treat `llms.txt` / `llms-full.txt` as a fallback or supplement, not a replacement for the docs MCP.
</Tip>

***

### Fireblocks CLI

**What it is:** An agent-first command-line tool that exposes every Fireblocks API operation as a typed, JWT-signed command. The `help-index` command returns a compact JSON index of all commands sized to fit in an LLM context window.

**When to use it:** When you want to explore your workspace, prototype API calls, run scripts or CI jobs, or let your agent propose exact commands you can review before running. The CLI is the fastest path from "I want to do X" to a working, reviewable command — use it alongside an SDK in production, or on its own for operator and agent workflows.

**How to use it:**

<Tabs>
  <Tab title="npm">
    ```bash theme={"system"}
    npm install -g @fireblocks/fireblocks-cli
    ```
  </Tab>

  <Tab title="Homebrew (macOS)">
    ```bash theme={"system"}
    brew tap fireblocks/fireblocks-cli
    brew install fireblocks-cli
    ```
  </Tab>

  <Tab title="Standalone / other">
    Download a pre-built binary from [GitHub Releases](https://github.com/fireblocks/fireblocks-cli/releases), or install via yarn/pnpm. See [Fireblocks CLI](/docs/fireblocks-cli) for all options.
  </Tab>
</Tabs>

Connect it to your workspace, then verify:

```bash theme={"system"}
fireblocks configure
fireblocks whoami
```

Key agent-friendly features:

* `fireblocks help-index` — compact JSON command catalogue for LLM context
* `--dry-run` — preview a request before it executes
* `--no-confirm` — skip interactive prompts in automated pipelines
* Structured JSON errors on stderr with distinct exit codes

<Tip>
  For any operation that creates or modifies data, ask your agent to show the `fireblocks` command first and use `--dry-run` where available. Review before running.
</Tip>

Full reference: [Fireblocks CLI](/docs/fireblocks-cli)

***

## Platform AI tools

These tools extend AI capabilities to the Fireblocks Console and broader operations workflows.

### Fireblocks AI Link

**What it is:** An MCP server that connects your AI tools (Claude, ChatGPT, Cursor) directly to your Fireblocks workspace data. Where the Documentation MCP gives your agent access to docs, AI Link gives it access to your live Fireblocks environment — balances, transactions, addresses, and workspace state.

**When to use it:** When you want to query live workspace data in natural language, build dashboards, or run operational queries without writing API code. AI Link is oriented towards operations and treasury workflows rather than code generation.

**Two deployment modes:**

| Mode           | Capabilities                | Deployment               | Best for                                                      |
| -------------- | --------------------------- | ------------------------ | ------------------------------------------------------------- |
| **Remote MCP** | Read-only                   | Fireblocks-hosted        | Connecting to ChatGPT, Claude, or other external AI platforms |
| **Local MCP**  | Read + write (transactions) | Self-hosted, open-source | Custom workflows with full data control                       |

Example queries AI Link enables:

* *What percentage of my holdings are in stablecoins?*
* *Summarize fees paid across all vaults this month.*
* *What is the current balance of vault account 42?*

Available via [Fireblocks Labs](https://www.fireblocks.com/fireblocks-labs/) for early access. The Local MCP server is open-source on GitHub.

***

### Fireblocks Genie

**What it is:** A native AI assistant built directly into the Fireblocks Console — no external integrations required. Genie answers treasury and operations questions in real time using your workspace data, and can explain complex DeFi contract calls in plain language via the AI Transaction Summary feature.

**When to use it:** When you're in the Console and want fast answers about your workspace state, holdings, or a specific transaction — without switching context to another tool. Genie is not a developer tool; it's built for treasury, finance, and operations teams who work in the Console.

**Capabilities:**

* Answer natural-language questions about balances, fees, and holdings
* AI Transaction Summary: explains complex smart contract calls in human-readable terms
* Respects your workspace policies, approval quorums, and user roles

Available via [Fireblocks Labs](https://www.fireblocks.com/fireblocks-labs/) for early access.

***

## How the tools fit together

| Tool                  | Primary user          | Primary context    | Needs live workspace data    |
| --------------------- | --------------------- | ------------------ | ---------------------------- |
| **Documentation MCP** | Developer / agent     | IDE / coding agent | No — reads docs only         |
| **Fireblocks CLI**    | Developer / agent     | Terminal / scripts | Yes — calls the API          |
| **AI Link**           | Developer / operator  | External AI tools  | Yes — reads/writes workspace |
| **Genie**             | Operations / treasury | Fireblocks Console | Yes — console-native         |

The **Documentation MCP** is the one tool that applies to every workflow — install it first. After that, use the SDK, CLI, or both depending on what you're building. Add AI Link when you want natural-language access to live workspace data from your own AI tools. Genie is available in the Console for non-developer users on your team.


# Fireblocks Key Features & Capabilities
Source: https://developers.fireblocks.com/docs/capabilities



### Hot, warm, and cold MPC-CMP wallets

Fireblocks wallets can be hot, warm, or cold. What separates these types of wallets is where the third MPC key share is held, and how transaction approvals are conducted.

* With a **hot wallet**, the third MPC key share is held by an API user on an API co-signer, and transaction approvals can be automated.
* With a **warm wallet**, the third MPC key share is held on your internet-connected mobile device, and approvals occur on the Fireblocks mobile app.
* With a **cold wallet**, the third MPC key share is held on your air-gapped (offline) mobile device. Approvals for transactions require bi-directional QR code scanning.

<Info>
  ### Workspace compatibility

  A Fireblocks workspace can be hot & warm, or cold wallet-only, but not both.
</Info>

### Workspaces

The **Fireblocks workspace** is a unique feature of the Fireblocks platform with a broad range of capabilities that allows you to manage your various accounts, digital assets, transactions, and more.

Each workspace is a unique BIP32-HD wallet structure with unique security and transaction policies.

[Learn more about different types of Fireblocks workspace environments.](doc:workspace-environments)

### Role-based access control

Fireblocks has extensive role-based access control capabilities for various user roles. These access roles grant them permissions related to:

* Parts of the platform they can access
* Types of actions they can perform
* MPC key shares that they hold and can use to sign transactions

These roles can range from admin-level users like 'Owner' of the workspace, to a read-only 'Viewer’. An API user can be assigned any user role (except 'Owner').

[Learn more about each role's access and capabilities.](doc:quickstart#creating-an-api-user)

### Admin Quorum

The **Admin Quorum**is the minimum number of workspace admins required to approve sensitive workspace changes, such as adding or removing users, adding whitelisted addresses, or approving network connections. This is set via an Admin Quorum threshold.

If an admin attempts to perform malicious actions, such as attempting to steal funds via a personal wallet, the multiple approvals required by the admin quorum prevent and mitigate damage. This would work the same for an admin that has their account compromised.

[Learn more about adjusting your workspace's Admin Quorum threshold.](https://support.fireblocks.io/hc/en-us/articles/360017665119-Admin-Quorum)

### Accounts

**Accounts** compile all types of accounts that Fireblocks supports, including; vault accounts, exchange accounts, and fiat accounts.

* A**Vault account** is a unique on-chain wallet, with your private key secured by our MPC-CMP architecture, that enables you to securely store and transfer your digital assets.
* A **Exchange account** allows you to leverage your exchange's API credentials to securely transfer assets between exchanges and other Fireblocks accounts.
* A **Fiat account** enables you to transfer fiat to any other account within your Fireblocks workspace or network connections that support that specific fiat provider.

### Vaults

The Fireblocks Vault is your secure MPC-CMP solution for wallet and address management. The Vault allows you to create and manage multiple vault accounts, which contain your asset wallets.

Depending on the asset type, you may or may not be able to have multiple deposit addresses or accounts within a single vault account.

[Learn how to create vaults and wallets using the Fireblocks API.](/docs/create-direct-custody-wallets)

### Assets

Asset wallets are used to manage internal deposit addresses for different asset types. Each asset wallet contains at least one deposit address for its asset type. Fireblocks supports over 1,200 assets and our asset support is continuously growing.

[Learn how to return a list of supported assets using the Fireblocks API.](/docs/list-supported-assets-1)

### Policies

Policies are a set of rules that set the limits and boundaries of the transactions in your Fireblocks workspace.

With Policies, you control who can move funds, how much can be transferred in a single transaction or a certain time period, and how transactions are authorized.

Policy rules can be applied to virtually any parameter within a transaction, including smart contract-specific transactions such as deploying, upgrading, and performing ongoing operations.

[Learn how to set up rules for your Policies.](/docs/set-transaction-authorization-policy)

### Transactions API

All transactions are routed through the [Create a new transaction](ref:post_transactions) API call. Users can only issue transactions based on their access roles and the workspace’s Policy settings. This includes both console and API users.

When issuing a transaction through this endpoint, the `OPERATION` parameter specifies what type of transaction this may be. It could be a generic transfer, a token mint or burn, a contract call, a typed message, or a raw message.

[Learn how to build a transaction using the Fireblocks API.](/reference/create-transactions)

### Whitelisted addresses

**Whitelisted addresses** are deposit addresses that exist outside of your Fireblocks Vault. You can perform transactions from your workspace by whitelisting an address for any supported blockchain.

Whitelisted addresses (also called "wallets") can be categorized as:

* **Internal wallet** - a deposit address existing inside your organization.
* **External wallet** - a deposit address existing outside your organization.
* **Contract wallet** - a deposit address of an on-chain smart contract.

[Learn to whitelist new addresses for transactions and deposits.](/docs/whitelist-addresses)

### Fireblocks Network

The Fireblocks Network is a settlement workflow allowing you to quickly transfer with your network counterparties without the need to manually whitelist their addresses.

Streamline settlement using the Fireblocks Network by automatically authenticating addresses with your network counterparties while automatically rotating secure addresses for supported assets. It also maps transactions to counterparties for accurate reporting.

[Learn how to create and manage network connections using the Fireblocks API.](/docs/connect-to-the-fireblocks-network)

### Tokenization

Deploy, manage, mint, and burn custom tokenized assets on-chain. Enforce governance and rules for who is able to perform sensitive operations such as minting new tokens.

[Learn how to deploy, manage, mint, and burn tokenized assets using the Fireblocks API.](/docs/issue-new-tokens)

### Web3 / DeFi access

Fireblocks lets you securely connect to and operate seamlessly within the Web3 and DeFi ecosystem.

* Connect easily to Web3 dApps using our WalletConnect integration or browser extension.
* Interact directly and programmatically with smart contracts using our smart contract API.

[Learn how to connect to Web3 dApps using our WalletConnect integration.](https://support.fireblocks.io/hc/en-us/articles/5403817784732-Connecting-to-Web3-using-WalletConnect)

### Securely develop and operate smart contracts

Securely develop, deploy, and operate your on-chain smart contracts using Fireblocks' industry-leading security layers.

Provide granular role-based access control for managing which developer is allowed to deploy smart contracts, perform upgrades, or call sensitive smart contracts operations, such as pausing or updating contract data.

[Learn how to deploy and operate smart contracts using the Fireblocks API.](/docs/interact-with-smart-contracts)

### Fireblocks Gas Station

The *FireblocksGas Station* service automates gas replenishment for token transaction fees on EVM-based networks such as Ethereum, BNB Chain, and others. This eliminates monitoring and manually transferring funds to these vault accounts to cover future transaction fees.

[Learn how to set up your Gas Station using the Fireblocks API.](/docs/work-with-gas-station)

### Transaction screening (AML/KYT)

*Transaction screening* allows you to automate real-time monitoring of your crypto transactions in order to ensure compliance with Anti-Money Laundering/Counter Financing of Terrorism (AML/CFT) regulations, prevent interactions with sanctioned entities and identify customer behavior.

[Learn more about our AML screening engine and the KYT capabilities of our Chainalysis and Elliptic integrations.](/docs/define-aml-policies)


# CLI Authentication
Source: https://developers.fireblocks.com/docs/cli-authentication

Configure credentials for the Fireblocks CLI.

The CLI authenticates to the Fireblocks API using the same JWT-signing mechanism as the official SDKs: each request is signed with your RSA private key and identified by your API key.

## Prerequisites

You need:

* A **Fireblocks API key** — obtained from the Fireblocks Console under **Developer Center > API Users**
* An **RSA private key** — the `.key` file generated when creating the API user

See [Quickstart](/docs/quickstart) for instructions on creating an API user and generating a key pair.

## Credential Resolution Order

The CLI resolves credentials in priority order:

1. **CLI flags** — `--api-key` and `--secret-key` passed directly on the command line
2. **Environment variables** — `FIREBLOCKS_API_KEY` and `FIREBLOCKS_SECRET_KEY` (or `FIREBLOCKS_SECRET_KEY_PATH`)
3. **Config file profile** — stored in `~/.config/fireblocks/config.json`

If no credentials are found, the CLI exits with an error and instructions for how to configure them.

## Interactive Setup

The easiest way to configure credentials is the interactive `configure` command:

```bash theme={"system"}
fireblocks configure
```

This prompts for your API key, the path to your private key file, and optionally a base URL override. Credentials are written to `~/.config/fireblocks/config.json` with file permissions `0600`.

To configure a named profile:

```bash theme={"system"}
fireblocks configure --profile staging
```

To switch the default profile:

```bash theme={"system"}
fireblocks configure --set-default=staging
```

### Config File Format

```json theme={"system"}
{
  "defaultProfile": "default",
  "profiles": {
    "default": {
      "apiKey": "your-api-key",
      "privateKeyPath": "/path/to/fireblocks_secret.key"
    },
    "staging": {
      "apiKey": "staging-api-key",
      "privateKeyPath": "/path/to/staging_secret.key",
      "baseUrl": "https://sandbox-api.fireblocks.io"
    }
  }
}
```

## Environment Variables

For CI/CD pipelines and non-interactive environments, set credentials as environment variables:

| Variable                     | Description                                                                |
| ---------------------------- | -------------------------------------------------------------------------- |
| `FIREBLOCKS_API_KEY`         | Your Fireblocks API key                                                    |
| `FIREBLOCKS_SECRET_KEY`      | RSA private key — inline PEM content or a file path                        |
| `FIREBLOCKS_SECRET_KEY_PATH` | File path to your RSA private key (alternative to `FIREBLOCKS_SECRET_KEY`) |
| `FIREBLOCKS_BASE_URL`        | Base URL override (default: `https://api.fireblocks.io`)                   |

```bash theme={"system"}
export FIREBLOCKS_API_KEY="your-api-key"
export FIREBLOCKS_SECRET_KEY_PATH="/path/to/fireblocks_secret.key"

fireblocks vaults get-paged-vault-accounts
```

You can also pass inline PEM content directly — useful when pulling key material from a secrets manager:

```bash theme={"system"}
export FIREBLOCKS_SECRET_KEY="-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAK...
-----END RSA PRIVATE KEY-----"
```

## CLI Flags

Pass credentials directly on the command line to override environment variables and the config file:

```bash theme={"system"}
fireblocks vaults get-paged-vault-accounts \
  --api-key "your-api-key" \
  --secret-key "/path/to/fireblocks_secret.key"
```

`--secret-key` accepts either a file path or an inline PEM string.

## Multiple Profiles

Use profiles to manage multiple workspaces or environments:

```bash theme={"system"}
# Configure a sandbox profile
fireblocks configure --profile sandbox

# Use the sandbox profile for a command
fireblocks vaults get-paged-vault-accounts --profile sandbox
```

## API Base URL

The default base URL is `https://api.fireblocks.io`. Override it per command, in a profile, or via `FIREBLOCKS_BASE_URL`.

| Environment           | Base URL                              |
| --------------------- | ------------------------------------- |
| US Mainnet / Testnet  | `https://api.fireblocks.io` (default) |
| US Sandbox            | `https://sandbox-api.fireblocks.io`   |
| EU Mainnet / Testnet  | `https://eu-api.fireblocks.io`        |
| EU2 Mainnet / Testnet | `https://eu2-api.fireblocks.io`       |

```bash theme={"system"}
fireblocks vaults get-paged-vault-accounts \
  --base-url https://sandbox-api.fireblocks.io
```

## Verify Your Setup

Run `whoami` to confirm credentials are configured correctly and that the API key can authenticate:

```bash theme={"system"}
fireblocks whoami
```

This calls `GET /v1/users/me` and returns the masked API key, base URL, and user details on success.

To preview the resolved auth context without making a network call:

```bash theme={"system"}
fireblocks whoami --dry-run
```


# CLI Usage Guide
Source: https://developers.fireblocks.com/docs/cli-usage

Commands, flags, examples, and error handling for the Fireblocks CLI.

## Command Pattern

Every Fireblocks API operation is available as a command organized under a namespace:

```bash theme={"system"}
fireblocks <namespace> <action> [flags]
```

Namespaces correspond to Fireblocks API resource groups (e.g. `vaults`, `transactions`, `assets`, `staking`). Examples:

```bash theme={"system"}
fireblocks vaults get-paged-vault-accounts
fireblocks transactions create-transaction --data '...' --no-confirm
fireblocks staking get-chains
```

## Discover Commands

### Full Command Index

```bash theme={"system"}
fireblocks help-index
```

### List Actions in a Namespace

```bash theme={"system"}
fireblocks vaults --help
```

### Show All Flags for a Command

```bash theme={"system"}
fireblocks vaults get-vault-account --help
```

### Preview a Request

Use `--dry-run` on any command to see the exact request that would be sent — without executing it:

```bash theme={"system"}
fireblocks transactions create-transaction \
  --data '{"assetId":"BTC","amount":"0.001"}' \
  --dry-run
```

Output:

```json theme={"system"}
{
  "method": "POST",
  "url": "https://api.fireblocks.io/v1/transactions",
  "body": { "assetId": "BTC", "amount": "0.001" }
}
```

## Flags

### Path Parameters

OpenAPI path parameters (e.g. `{vaultAccountId}`) become required flags with kebab-case names:

```bash theme={"system"}
# GET /v1/vault/accounts/{vaultAccountId}
fireblocks vaults get-vault-account --vault-account-id 0
```

### Query Parameters

Query parameters become optional flags with the same kebab-case conversion:

```bash theme={"system"}
# GET /v1/vault/accounts/paged?limit=50&namePrefix=hot
fireblocks vaults get-paged-vault-accounts --limit 50 --name-prefix hot
```

### Request Body

Write operations (POST/PUT/PATCH/DELETE) accept a JSON request body via `--data`:

```bash theme={"system"}
fireblocks transactions create-transaction \
  --data '{"assetId":"ETH","amount":"0.1","source":{"type":"VAULT_ACCOUNT","id":"0"},"destination":{"type":"VAULT_ACCOUNT","id":"1"}}' \
  --no-confirm
```

### Global Flags

These flags are available on every command:

| Flag           | Env Var                                                | Description                                |
| -------------- | ------------------------------------------------------ | ------------------------------------------ |
| `--api-key`    | `FIREBLOCKS_API_KEY`                                   | Fireblocks API key                         |
| `--secret-key` | `FIREBLOCKS_SECRET_KEY` / `FIREBLOCKS_SECRET_KEY_PATH` | RSA private key — PEM content or file path |
| `--base-url`   | `FIREBLOCKS_BASE_URL`                                  | Override the API base URL                  |
| `--profile`    |                                                        | Use a named credential profile             |
| `--dry-run`    |                                                        | Preview the request without executing it   |
| `--no-confirm` |                                                        | Skip write-operation confirmation prompts  |
| `--debug`      |                                                        | Log request and response details to stderr |
| `-o, --output` |                                                        | Output format: `json` (default) or `yaml`  |

## Write Operations

POST, PUT, PATCH, and DELETE commands prompt for confirmation before executing:

```text theme={"system"}
About to execute POST /v1/transactions. Continue? (y/N)
```

Skip the prompt for scripting and automation — either pass `--no-confirm` or pipe stdin from a non-TTY source:

```bash theme={"system"}
fireblocks transactions create-transaction --data '...' --no-confirm
```

### Idempotency Keys

Endpoints that support idempotency accept `--idempotency-key`. Use this for safe retries on write operations to guarantee at-most-once execution:

```bash theme={"system"}
fireblocks transactions create-transaction \
  --data '{"assetId":"ETH","amount":"1.0","source":{"type":"VAULT_ACCOUNT","id":"0"},"destination":{"type":"ONE_TIME_ADDRESS","oneTimeAddress":{"address":"0xABC"}}}' \
  --idempotency-key "$(uuidgen)" \
  --no-confirm
```

## Output

* **stdout** — JSON response data only
* **stderr** — warnings, beta notices, errors, and debug logs

### Debug Logging

Pass `--debug` to log request and response details to stderr:

```bash theme={"system"}
fireblocks vaults get-vault-account --vault-account-id 0 --debug
```

```text theme={"system"}
[DEBUG] GET https://api.fireblocks.io/v1/vault/accounts/0
[DEBUG] Response: 200
[DEBUG] Request-ID: a1b2c3d4-...
```

### Beta Commands

Some commands are marked as beta. They print a warning to stderr before executing:

```text theme={"system"}
Warning: This command is in beta and may change in future releases.
```

This is informational — the command still runs and produces output on stdout.

## Exit Codes

| Code | Meaning                               | Recovery                                                   |
| ---- | ------------------------------------- | ---------------------------------------------------------- |
| `0`  | Success                               |                                                            |
| `1`  | Client error (400 / 409 / 422)        | Check request body or parameters                           |
| `2`  | Usage error (missing or invalid flag) | Check flag names and types                                 |
| `3`  | Auth error (401 / 403)                | Verify credentials with `fireblocks whoami`                |
| `4`  | Not found (404)                       | Verify the resource ID exists                              |
| `5`  | Rate limited (429)                    | Wait `retry_after` seconds from the error JSON, then retry |
| `6`  | Server error (5xx)                    | Retry after a brief delay                                  |
| `7`  | Timeout (30s)                         | Retry; the timeout is not configurable                     |

## Error Format

Errors are written as JSON to **stderr**:

```json theme={"system"}
{
  "code": 5,
  "status": 429,
  "message": "Rate limit exceeded",
  "request_id": "a1b2c3d4-5678-...",
  "retry_after": 30
}
```

`request_id` and `retry_after` are included only when applicable.

## Examples

```bash theme={"system"}
# List vault accounts
fireblocks vaults get-paged-vault-accounts

# Get a specific vault
fireblocks vaults get-vault-account --vault-account-id 0

# Create a transaction
fireblocks transactions create-transaction \
  --data '{"assetId":"BTC","amount":"0.001","source":{"type":"VAULT_ACCOUNT","id":"0"},"destination":{"type":"VAULT_ACCOUNT","id":"1"}}' \
  --no-confirm

# Idempotent transaction with retry safety
fireblocks transactions create-transaction \
  --data '{"assetId":"ETH","amount":"1.0","source":{"type":"VAULT_ACCOUNT","id":"0"},"destination":{"type":"ONE_TIME_ADDRESS","oneTimeAddress":{"address":"0xABC"}}}' \
  --idempotency-key "$(uuidgen)" --no-confirm

# Preview a request without executing
fireblocks transactions create-transaction \
  --data '{"assetId":"BTC","amount":"0.001"}' \
  --dry-run

# Use the sandbox environment
fireblocks vaults get-paged-vault-accounts \
  --base-url https://sandbox-api.fireblocks.io

# Debug a failing request
fireblocks vaults get-vault-account --vault-account-id 0 --debug

# Pipe output to jq
fireblocks vaults get-paged-vault-accounts | jq '.accounts[].name'
```

## Shell Autocomplete

The CLI supports tab completion for Bash and Zsh. Run the autocomplete command for your shell and follow the printed setup instructions:

```bash theme={"system"}
# Bash
fireblocks autocomplete bash

# Zsh
fireblocks autocomplete zsh
```


# API Co-signer Security Checklist and Recommended Defense and Monitoring Systems
Source: https://developers.fireblocks.com/docs/co-signer-security-checklist-defense-monitoring



## Co-signer security checklist

* Only **authorized personnel** with **high-level privileges** and **full trust** from your organization may perform the Co-signers installation.
* Use a clean, hardened machine for the Callback Handler server, restricting access exclusively to authorized personnel or service accounts.
* Configure your network rules, cloud resources, and required policies according to the instructions provided in each API Co-signer installation guide.
* Use the Callback Handler to log all approval requests, and consider utilizing it to implement additional programmatic protection logic against malicious withdrawals.
* Create Policy rules that prevent API users from initiating transfers above a specific amount threshold within a certain timeframe, and require additional manual approval. These rules should apply globally to all withdrawals and withdrawals from specific external user wallets.
* Fireblocks advises against disabling Linux UEFI secure boot on your API Co-signer virtual machine, as this goes beyond the security risks introduced by not validating kernel code. We recommend working around any issues you have instead. Using TrendMicro Deep Security agent on Ubuntu 20.04 is one option for secure boot support.

## Co-signer recommended defense and monitoring systems

Although a quorum can be configured to approve requests, and a single MPC key share cannot be used to compromise the system, we recommend adding multiple defense and monitoring systems on Fireblocks API Co-signer instances.

Implementing the recommended defense and monitoring systems can significantly improve the security of the Fireblocks API Co-Signer and reduce the risk of security incidents.

* **Cloud Workload Protection**: A solution that actively monitors the instance running on the Fireblocks AWS API Co-Signer and provides real-time protection against known and unknown threats.
* **Event Detection and Response (EDR)** or **Extended Detection and Response (XDR)**: A solution that actively monitors the instance running on the Fireblocks AWS API Co-Signer and detects and responds to potential security threats in real-time.
* **Security Information and Event Management (SIEM)**: A solution to collect all login attempts to the instance running on the Fireblocks AWS API Co-Signer and provides real-time alerting and reporting on potential security incidents.
* **Privileged Access Management (PAM)**: A solution that actively controls and monitors access to privileged accounts, such as root access to the instance running on the Fireblocks AWS API Co-Signer. A PAM solution can also provide real-time monitoring and alerting on privileged account activity, and enforce security policies, such as password management and least privilege access.
* **Multi-Factor Authentication (MFA)**: An MFA solution can enforce secure authentication and access control to the instance running on the Fireblocks AWS API Co-Signer. An MFA solution can also help prevent unauthorized access and reduce the risk of account compromise.

## AWS Nitro Recommendations

* **EC2 - EBS Volume Encryption**\
  Enabling encryption for all EBS volumes is strongly recommended to ensure data security and compliance with best practices. While Fireblocks uses AWS Nitro to safeguard sensitive workloads, customers are advised to configure EBS encryption based on their organization’s compliance requirements and data protection policies. Encryption can be managed seamlessly through AWS Key Management Service (KMS).
* **CloudTrail - Enabling Service for all Regions**\
  Fireblocks utilizes an organizational structure incorporating AWS Control Tower, a dedicated log-archive account, and automated processes to ensure comprehensive multi-region coverage for CloudTrail. While this approach is recommended, customers retain the flexibility to operate in single or multi-region modes based on their operational and regulatory requirements. Enabling CloudTrail for all applicable regions is crucial, however, to maintain visibility into account activities and meet audit requirements.
* **S3 - Enabling MFA Delete**\
  MFA Delete for S3 buckets is a security best practice for protecting against accidental or unauthorized data deletion. However, Fireblocks does not enforce specific bucket policies, which must align with each customer’s internal security frameworks. Customers are encouraged to evaluate and implement MFA Delete which supports their risk management strategy.
* **S3 - Enabling Versioning**\
  S3 versioning provides added protection for data backup and replication. However, Fireblocks' Co-Signer architecture does not require backup or replication of data stored in S3. Customers should assess the need for versioning based on their internal data resilience and disaster recovery policies.
* **S3 - Enabling Access Logging**\
  Enabling S3 access logging requires a dedicated logging bucket. Fireblocks recognizes that customers often have centralized logging infrastructures, forwarding logs to SIEM platforms for analysis and archiving. In such cases, enabling S3 access logging may result in redundancy. Customers must ensure their existing logging solutions sufficiently cover S3 access patterns for security monitoring and compliance.
* **VPC - Enabling Subnet Flow Logs**\
  While VPC Flow Logs are a valuable tool for monitoring network traffic, they can incur significant costs. Customers should evaluate the necessity of enabling VPC subnet flow logs based on their security posture, budgetary considerations, and compliance obligations. Fireblocks recommends allowing this feature to where granular network activity monitoring is required.

## GCP Confidential Space Recommendations

* **Enabling Cloud Audit Logging**\
  Cloud Audit Logging is critical for tracking administrative and data-access operations at the project level. As Fireblocks’ Co-Signer is deployed within customer-managed environments, customers are responsible for enabling and managing Cloud Audit Logging to meet their governance and monitoring needs.
* **Cloud IAM - Service Account with Admin Privileges**\
  GCP creates a default administrative service account during the initial setup. To reduce the attack surface and adhere to the principle of least privilege, customers should delete this service account after installation unless explicitly required for operational purposes.
* **Cloud Storage - Enabling Buckets with Versioning**\
  Versioning is primarily designed for backup and replication use cases. Fireblocks’ Co-Signer solution does not require this feature, and this configuration has no associated security risk. Customers may enable versioning based on their organizational backup and recovery strategies.
* **VPC Enabling Subnet Flow Logs**\
  As with AWS, enabling VPC subnet flow logs in GCP provides visibility into network traffic but may incur additional costs. Customers should consider enabling this feature if their security or compliance policies necessitate detailed network traffic analysis.
* **API Event Monitoring**\
  The Fireblocks Co-Signer is hosted within customer environments, and customers are responsible for implementing and managing API event monitoring. Fireblocks recommends monitoring API activity to detect anomalies and ensure compliance with security standards.
* **Firewall Rules**\
  GCP creates default firewall rules during project setup, which may not align with security best practices. Customers are strongly encouraged to delete these default rules and implement custom firewall rules that adhere to the principle of least privilege and align with their security requirements.


# Configure Gas Station Values
Source: https://developers.fireblocks.com/docs/configure-gas-station-values

You can configure the Fireblocks Gas Station with a gas threshold, a gas cap, and a maximum gas price for each blockchain network according to its base asset by using the Fireblocks API.

* **Gas threshold (gasThreshold):** The gas threshold represents the minimum balance allowed in the Gas Station account. If the balance is below the minimum gas threshold, the Gas Station fuels the vault account automatically with the set maximum gas cap.
* **Gas cap (gasCap):** The gas cap represents the maximum balance allowed in the Gas Station account.
* **Maximum gas price (maxGasPrice):** The maximum gas price allows you to limit the maximum transaction fee for Gas Station transactions. The funding transaction will be sent in gwei with this maximum value gas price or less. A null value for the maximum gas price means the fee will be paid at any cost, without limitations. If you changed the maximum gas price settings and want to revert to the default settings of null, you can enter an empty string as `""`.

When an incoming token deposit or an outgoing token withdrawal is detected, the Gas Station checks the gas balance of the vault account. If the balance is below the minimum gas threshold, it automatically fuels the vault account with the set maximum gas cap.

<Info>
  ### Learn more about Gas Station configuration in the Fireblocks Gas Station [developer guide](/reference/set-the-gas-station-values)
</Info>


# Connect to Exchanges and Fiat Providers
Source: https://developers.fireblocks.com/docs/connect-to-exchanges-and-fiat-providers

Fireblocks enables clients to connect their own (supported by Fireblocks) exchange and fiat accounts directly within the workspace.

Customers can bring their API credentials from the supported exchange or fiat account and integrate them into the Fireblocks workspace. Once connected, clients can seamlessly transfer funds to and from the connected exchange account via the Fireblocks console or the API.

Additionally, clients can view the balances of their connected exchange accounts and set Policies and automated processes around these accounts, enhancing both control and efficiency in managing their assets.

<Info>
  ### Learn more about connecting Exchange or Fiat accounts in the following guides:

  1. [Supported Exchange Accounts and configuration guides](https://support.fireblocks.io/hc/en-us/articles/13430566220572-Enabling-withdrawals-from-your-exchange-accounts)
  2. [Supported FIAT Accounts and configuration guides](https://support.fireblocks.io/hc/en-us/articles/360018286760-Fiat-accounts)
</Info>

<Info>
  ### Check out the [Exchange Accounts](/reference/getexchangeaccounts) and [Fiat Accounts](/reference/getfiataccounts) management APIs in the Firebocks API Reference
</Info>

<Info>
  ### Check out the Exchange and Fiat Accounts Developer Guide [here](/reference/connect-to-exchanges-fiat-providers)
</Info>


# Connect to the Fireblocks Network
Source: https://developers.fireblocks.com/docs/connect-to-the-fireblocks-network

The Fireblocks Network is a peer-to-peer, institutional liquidity and transfer network of 1,500+ liquidity providers, lending desks, and trading counterparties. Members can discover, connect, and settle with other Fireblocks Network members quickly, easily, and securely using features available only to Network members.

# Fireblocks Network features

To use Fireblocks Network features with a counterparty, connect to each other on the Network. Whether you prefer to make your Network profile discoverable or not, you can connect with other members in several ways.

Discoverable members show up in searches for connections. You can then request to add them as a connection from the search results. To connect with non-discoverable Network members you need to know their unique Network ID. If your profile is not discoverable, you can still search for other discoverable members and request to connect with them. Both your Admin Quorum as well as your counterparty’s Admin Quorum must approve new Network connections.

When you make transfers on the Fireblocks Network, you benefit from these Network features:

## Automated Address Authentication (AAA)

All Fireblocks Network transfers route through an encrypted tunnel within a secure hardware enclave. With AAA, you never have to store or share deposit addresses in poorly secured and error-prone ways, such as messenger apps or copying and pasting, which means you can:

* **Transfer faster:** Avoid time-consuming processes like manually whitelisting new deposit addresses, sending test transfers, and finding, copying, and pasting deposit addresses to send or receive a digital asset transfer.
* **Prevent errors:** Avoid manual, error-prone processes like tracking and copying and pasting addresses that can cause your assets or your counterparty’s assets to go to the wrong address.
* **Secure transfers:** Prevent Man-in-the-Middle and Address Spoofing attacks, where hackers use malware to replace addresses on infected devices, and intercept and replace addresses while you share them over messenger apps or copy and paste them. With AAA, you don’t need to manually manage or share deposit addresses.
* **Future-proof connections:** With AAA, connected counterparties stay connected even if your deposit address changes. AAA will automatically remap it without resharing or reconnecting.

## Flexible Network Routing

When you add new Network connections, you can define how incoming deposits are routed. You can tailor routing for Network deposits of both crypto and fiat in two ways

* **Route by Network profile:** Send all deposits from connections to your Network profile to a designated vault account, exchange account, or fiat account in your workspace.
* **Route by connection:** Tailor routing per connection. Each connection’s deposits can go to their own specific designated vault account, exchange account, or fiat account.

You can also execute all Flexible Network Routing configuration actions using the Fireblocks API. With maximum flexibility for routing and managing deposit addresses for Network transfers, you can capitalize on more opportunities faster and more easily using the Fireblocks Network.

## Automatic Address Rotation

When you transfer Bitcoin or other UTXO-based tokens with Fireblocks Network connections, your deposit addresses can rotate automatically for every incoming transfer. For certain tokens, a different unique identifier is rotated on every Network transfer instead of rotating addresses.

* For Ripple transfers on the Network, the deposit address stays the same, but the unique XRP tag is rotated every transfer.
* For EOS, Hedera, and Stellar transfers on the Network, the deposit address stays the same, but the unique memo ID is rotated every transfer.

For Network transfers on account-based blockchains like Ethereum, Automatic Address Rotation isn’t supported and there is no other unique identifier. You can transfer account-based assets on the Fireblocks Network. However, you can’t create unique identifiers like a deposit address, tag, or memo ID for each transfer for pseudo-anonymity on the blockchain.

Since Network transfers also use Automated Address Authentication, you don’t have to track or share the new addresses. This enables you to:

* Preserve privacy on the blockchain by preventing your transaction history from being easily discovered by someone searching for a deposit address.
* Avoid errors from manual address rotation, like forgetting to update a connection with your new address or a copy-and-paste error while tracking or sharing.

<Info>
  ### Learn how to connect over the Fireblocks Network in the Web Console [here](https://support.fireblocks.io/hc/en-us/articles/6107078528540-Configuring-your-Fireblocks-Network-profile)
</Info>

<Info>
  ### Check out the [Fireblocks Network APIs](/reference/getnetworkconnections)  in the Fireblocks API reference
</Info>


# API Co-signers Architecture Overview
Source: https://developers.fireblocks.com/docs/cosigner-architecture-overview



## How automated MPC signing works

### Overview

Similar to how the MPC-CMP algorithm is used to sign transactions and approve workspace configuration requests via a mobile device, the API Co-signer participates in a multi-signer MPC process. This process involves a set of independent Co-signers operated by Fireblocks, known as Cloud Co-signers, each of which holds a private key share. Refer to [this MPC-CMP article](https://support.fireblocks.io/hc/en-us/articles/6984668676124-MPC-CMP) to learn more about the API Co-signer's role in implementing the Fireblocks MPC signing algorithm.

The Co-signer eliminates the need for manual user input through the Fireblocks mobile application by automatically signing transactions and approving requests. By hosting the Co-signer in your environment and connecting it to your workspace using API users, you can configure the [Policies](https://support.fireblocks.io/hc/en-us/articles/7354983580316-About-the-TAP) to [designate the API user](https://support.fireblocks.io/hc/en-us/articles/7365877039004-Rule-parameters#h_01HGBN9QQ0T42NR8XT4Y96V7YH) that is paired with the Co-signer to automatically sign transactions that meet the criteria defined in the policy.

To automate transaction signing, host the API Co-signer in your environment on a machine or virtual machine (VM) that supports enclaves. Fireblocks API Co-signers operate on Intel SGX, AWS Nitro, or Google Cloud Confidential Spaces enclaves. They can be deployed on major cloud platforms such as Azure, AWS, Google Cloud, IBM Cloud, and Alibaba Cloud, as well as on-premises with Intel SGX-capable servers.

> Fireblocks has fully integrated AWS Nitro Enclave technology. If you are currently using KMS-based AWS API Co-signers, it is recommended to upgrade to the latest Nitro version for enhanced security and performance.

Observe the diagram below, which illustrates the relationship between the customer's API Co-signer, mobile device, API users, and the Fireblocks Cloud Co-signers #1 and #2.

<img alt="" />

Refer to the articles below for detailed information on the specific architecture of each type of enclaved Co-signer:

* [Intel SGX Co-signer architecture running in Azure, IBM Cloud or Alibaba Cloud](/docs/intel-sgx-api-co-signer)
* [Nitro Co-signer architecture running in AWS](/docs/aws-nitro-api-co-signer)
* [Confidential Space Co-signer architecture running in Google Cloud](/docs/gcp-confidential-space-api-co-signer)

### Using API users to connect the Co-signer to your workspace

To connect a new or existing Co-signer to your workspace, pair it with an API user from the workspace. Existing Co-signers are typically associated with another workspace within your organization.

Pairing the Co-signer is performed using a JWT-encoded Pairing Token obtained from the Console for a specific API user. This token is used during Co-signer installation to pair the initial API key, enabling communication with Fireblocks' SaaS. The Co-signer is identified exclusively by the workspace and the API user used to establish the connection.

The pairing process for the first API user requires admin-level access to the Fireblocks Console and root access to the Co-signer’s VM. During this process, you will provide the Co-signer with a pairing token linked to the API user, enabling the platform to recognize the Co-signer and associate it with the Workspace.

You can pair multiple API users to a single Co-signer. Additionally, API users from different Workspaces can be paired with the same API Co-signer, except when using the GCP Confidential Space Co-signer.

### Connecting your business logic to the Co-signer

You can optionally connect your business logic to the Co-signer through a feature called a Callback Handler, configured per API user. The Callback Handler is an HTTPS server that receives requests from the Co-signer at a designated endpoint whenever a transaction signing or configuration approval is triggered for an API user. The Callback Handler responds with an action, such as approving or denying the request. If no Callback Handler is configured, the Co-signer will automatically sign or approve all requests for that API user.

Within a single Co-signer, some API users can operate with a configured Callback Handler, while others can function without it. When configuring a Callback Handler for a paired API user, you specify the URL of the Callback Handler server and select a secure communication method to establish a secure channel.

Refer to [Setup API Co-signer Callback Handler](/docs/create-api-co-signer-callback-handler) to learn more about it.

### Callback best practices

When a signing or authorization request reaches the API Co-Signer, a callback is invoked with the transaction details. We recommend closely monitoring this communication to ensure the callback responds quickly and reliably, as MPC signing will not begin until the callback approves the request.

## Installing an API Co-signer

### Available API Co-signer types

Fireblocks provides multiple deployment options for API Co-signers, available in both cloud environments and on-premises, in regions that meet the necessary enclave technology requirements. These deployment options leverage various enclave technologies to safeguard your MPC key shares, allowing you to select the solution that aligns best with your production environment requirements.

For detailed step-by-step installation guides for each Co-signer type, refer to the articles below:

* [Installing an SGX API Co-signer in Azure](/reference/install-api-cosigner-azure)
* [Installing an SGX API Co-signer via Azure Marketplace](/reference/install-api-cosigner-azure-marketplace)
* [Installing an SGX API Co-signer in IBM Cloud](/reference/install-api-cosigner-ibm)
* [Installing an SGX API Co-signer in Alibaba Cloud](/reference/install-api-cosigner-alibaba)
* [Installing an SGX API Co-signer on-prem](/reference/install-api-cosigner-onprem)
* [Installing a Nitro API Co-signer in AWS](/reference/install-api-cosigner-aws)
* [Installing a Confidential Space API Co-signer in Google Cloud](/reference/install-api-cosigner-gcp)

### High-throughput workspaces

For high-throughput workspaces, we recommend setting up more than one API Co-Signer. This setup enables both high availability and load balancing between Co-Signers, allowing for higher overall throughput.

The required number of Co-Signers is determined by the number of in-flight transactions in the signing phase. As a rule of thumb, maintain one Co-Signer (with a single vCPU) per every 2.5 TPS.

<Callout icon="📘">
  **Learn more**

  * [Configuring Multiple API Co-signers in High Availability](/docs/multiple-cosigners-high-availability)
  * [API Co-signers Architecture Overview](/reference/api-cosigner-installation-flow)
</Callout>

### Host type recommendations

We recommend using at least a **Standard\_D4\_v3** instance on Azure. AWS and GCP instance recommendations are TBD. In addition, we recommend using Co-signer **version 3.7.1 or newer**.

The table below summarizes key considerations per cloud provider:

| Provider              | Key Considerations                                                                                                                                                                                                                                                      |
| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Azure (SGX-based)** | Provides hardware security at the highest security level, relying only on Fireblocks and Intel. Because SGX is CPU-based, it has performance limitations including reduced speed, limited memory, and a fixed number of threads. As a result, it is the slowest option. |
| **AWS Nitro**         | Requires trust in AWS for both hardware and security. This is still a confidential computing solution, but the cloud provider is part of the threat model. AWS is a highly reputable, publicly traded company with strong engineering practices.                        |
| **GCP**               | Recommended only if you are required to use Google Cloud. This version has the fewest deployments and the least field experience.                                                                                                                                       |

<Callout icon="👍">
  **Best practices**

  * For **maximum security:** select Azure + SGX
  * For **best performance:** select AWS + Nitro
</Callout>

### Available enclave types

Learn more about the enclave technologies Fireblocks uses by referring to the following resources:

* [Microsoft Azure SGX Enclave-capable Confidential Compute VM](https://learn.microsoft.com/en-us/azure/confidential-computing/confidential-computing-enclaves)
* On-Premise [Intel SGX-enabled Processors](https://www.intel.com/content/www/us/en/architecture-and-technology/software-guard-extensions-processors.html)
* [AWS Nitro Enclave-capable EC2 instance](https://aws.amazon.com/ec2/nitro/nitro-enclaves/)
* [Google Cloud Confidential Space workload container](https://cloud.google.com/confidential-computing/confidential-space/docs/confidential-space-overview)
* [IBM Cloud Bare Metal Servers SGX-capable machine](https://cloud.ibm.com/docs/bare-metal?topic=bare-metal-bm-server-provision-sgx)
* [Alibaba Cloud Intel SGX-capable Elastic Compute Service (ECS) instance](https://www.alibabacloud.com/help/en/ecs/user-guide/build-an-sgx-encrypted-computing-environment)

## Configuring your workspace to sign using an API Co-signer

To enable the API Co-signer to participate in MPC signing and configuration change approvals, it must be paired with an API user from your workspace. Once the pairing process is completed successfully, a unique set of MPC key shares and workspace configuration keys is generated for the API user. These keys are securely stored within your Co-signer and Cloud Co-signers #1 and #2. The key shares facilitate automatic signing for transactions initiated by you.

> Note that it must be an API user with the role of [Signer](https://support.fireblocks.io/hc/en-us/articles/360012832959-User-roles#h_01H9P4D2W1436XZYXESPTQE2J7) or [Admin](https://support.fireblocks.io/hc/en-us/articles/360012832959-User-roles#h_01H9P4D2W138W3F36TX45S8WFX), so it will have MPC key shares and be able to sign.

To activate automatic signing through the Co-signer, configure the [Policies](https://support.fireblocks.io/hc/en-us/articles/7354983580316-About-the-TAP) to [designate the API user](https://support.fireblocks.io/hc/en-us/articles/7365877039004-Rule-parameters#h_01HGBN9QQ0T42NR8XT4Y96V7YH) paired with the Co-signer as the signer. When a transaction you initiate meets the criteria defined in the policy, it will be automatically signed by the Co-signer associated with the configured API user.

The process of generating and signing a Fireblocks transaction using the Fireblocks REST API, the API Co-signer, and the optional Callback Handler proceeds as follows:

1. A new transaction is initiated using the Fireblocks API and generated on the backend.
2. The transaction is evaluated against your Policies to determine if it is authorized.
3. If an API user paired with the API Co-signer is configured in the Policy as a designated signer, the transaction will be sent to the API Co-signer associated with that API user.
4. The API Co-signer, hosted in your secure environment, polls the Fireblocks SaaS for transactions requiring signing. If a transaction is available, the SaaS immediately provides the transaction details.
5. If a Callback Handler is configured for the API user designated as the signer, the API Co-signer sends a secure approval request to the Callback Handler.
6. If the Callback Handler responds with "approved," the transaction is signed in coordination with Fireblocks' Cloud Co-signers. If the response is "rejected," the transaction is declined. If the Callback Handler does not respond within 30 seconds or returns "retry," the request fails. Refer to [Setup API Co-signer Callback Handler](/docs/create-api-co-signer-callback-handler) to learn more about it.

## Manage the Co-signer's paired API users and Callback Handlers

### Configuring the Co-signer from the Console and Fireblocks API

Once the Co-signer is connected to the workspace, it can be managed through the [Co-signers Management tab](https://support.fireblocks.io/hc/en-us/articles/14492251068060-The-Co-signer-management-tab) located in the **Developer Center** of the Fireblocks Console.

You can also use the [Co-signer APIs (beta)](https://docs.fireblocks.com/api/swagger-ui/#/Cosigners%20\(Beta\)) for that.

Common Co-signer operations:

* **Pair an additional API User** - requires the workspace owner approval
* **Configure the Callback Handler of an API user** - requires the workspace owner approval
* **Unpair an API User** (formerly known as re-enroll API user) - requires admin approval
* **Rename the Co-signer**
* **Retrieve information about the Co-signer**

<Info>
  ### The **Pair an additional API User** and **Configure the Callback Handler of an API user** are available from the Console and APIs only for users who installed the latest Co-signer versions.

  Refer to [API Co-signers versions](/reference/api-cosigner-versions) for more details
</Info>

### Configuring the Co-signer from its host machine

The AWS Nitro Co-signer and all types of SGX Co-signers can also be configured locally from the host machine using CLI commands. Refer to the [Operating the Co-signer](/reference/api-cosigner-operate) article for more details.

Due to Google Cloud's Workload container architecture, the GCP Confidential Space Co-signer can only be managed through Fireblocks' SaaS. Configuration operations must be performed within the workspace to which the Co-signer is connected, using either the Console or APIs. Consequently, the GCP Confidential Space Co-signer is restricted to a single workspace.

## Using the Communal Test Co-signer

> Due to legal regulations, Fireblocks can not take custodial responsibility for Mainnet workspaces. Therefore, this option is available only to Testnet workspaces.

Setting up a new Co-signer from scratch can be time-consuming. To accelerate development and prepare your workspace for automation and API-driven workflows, Fireblocks offers the option to use a Communal Test Co-signer before installing and configuring your own.

The Communal Test Co-signer is hosted and managed by Fireblocks and serves all customers with Testnet workspaces. Any workspace owner can approve pairing API users with it, generate MPC key share sets, and use it to sign transactions. Please refer to [this guide](/reference/use-communal-cosigner) to learn how to use the Communal Test Co-signer.

When you start testing and verifying your signing or approval automation workflows, we recommend setting up your self-hosted API Co-signer instance and replacing the Communal Test Co-signer as soon as your instance is ready. To stop using the Communal Test Co-signer, unpair or delete the API users that are paired with it.

Once an API user is created in a Sandbox workspace, it is automatically paired to the Fireblocks Communal Test Co-signer, which holds the MPC key shares of all the API users in the Sandbox environment across all the workspaces.


# Setup API Co-signer Callback Handler
Source: https://developers.fireblocks.com/docs/create-api-co-signer-callback-handler



## Overview

<Info>
  ### The API Co-signer Callback Handler is an optional feature

  If a Callback Handler is not configured for an API user, the Co-signer will automatically sign or approve all requests it receives for that API user.
</Info>

The Fireblocks API Co-signer can connect to a user-hosted web server called the API Co-signer Callback Handler. This handler plays a critical role by receiving signing or approval requests from the Co-signer.

An optional connection to a Callback Handler can be configured for each API user paired with the Co-signer. This enables the application of custom business or security logic before transactions associated with the paired API user are automatically signed or approved.

Implementing the Callback Handler provides several benefits:

* **Enhanced control**: integrate your specific business rules and security protocols.
* **Improved compliance**: transactions are vetted to meet internal compliance standards.
* **Increased security**: the additional validation layer reduces the risk of unauthorized transactions.

This integration ensures secure, compliant and customized transaction management.

## Establishing a secure communication between the Co-signer and the Callback Handler

When configuring the Callback Handler server for an API user that is paired with the Co-signer, you can select one of the following options to secure the communication between the Co-signer (which acts as a client) and the Callback Handler server.

### Option 1: Public key authentication

In this option, the Co-signer and the Callback Handler exchange JSON Web Token (JWT) encoded messages, each signed with their respective private keys. The Co-signer's POST request to the Callback Handler server and the Callback Handler's response to the Co-signer are authenticated using their corresponding public keys.

While you can retrieve the Co-signer's public key directly from the Co-signer, you should provide the Callback Handler public key to the Co-signer during installation or while configuring the Callback Handler for an API user. This public key corresponds to the private key used by the Callback Handler to sign JWT-encoded response messages.

For development and testing purposes, the Callback Handler can be run over HTTP. However, for production environments, we strongly recommend using HTTPS with a valid TLS certificate from a trusted Certificate Authority (CA) to ensure secure communication between the Co-signer and the Callback Handler.

### Option 2: Certificate-based communication

In this option, a self-signed certificate or a certificate signed by a trusted Certificate Authority (CA) is used to establish certificate-pinning-based secure communication between the Co-signer and the Callback Handler. TLS certificate authentication occurs during SSL negotiation and is based on the certificate you provide to the Co-signer.

You provide the certificate to the Co-signer during installation or when configuring the Callback Handler for a specific API user. In this setup, both the Co-signer's POST request to the Callback Handler server and the server's response uses JSON format instead of signed JWTs.

<Info>
  ### Learn more about setting the API Co-signer Callback Handler in the [following Developer Guide](/reference/cosigner-callbackhandler-secure-communication-authentication).
</Info>


# Create Direct Custody Wallets
Source: https://developers.fireblocks.com/docs/create-direct-custody-wallets



# Overview

The Fireblocks platform consists of workspaces, vault accounts, asset wallets, and deposit addresses. This diagram shows the overall account structure in Fireblocks and the underlying wallet structure.

<img alt="" />

At the top level, your various Fireblocks workspaces are contained within the logical group called the Customer Domain. These workspaces may be "hot" (online) or "cold" (offline).

In your Fireblocks workspace, you can create and manage multiple vault accounts. These vault accounts contain your asset wallets. Each vault account can have a single wallet per base asset (e.g., BTC, ETH, SOL), but each wallet can have one or more deposit addresses.

For UTXO-based assets, such as Bitcoin, a single wallet may generate one or more deposit addresses. For account-based assets, there are two options:

* Account-based assets without tag/memo support, such as ETH, can only generate one deposit address.
* Account-based assets with tag/memo support, such as XRP, can generate one or more deposit addresses. Each deposit address has the same on-chain address. However, they differ by their tag/memo.

<img alt="" />

## Automatically generated asset wallets

### EVM

* On EVM chains, a single deposit address is shared across all EVM asset wallets in the vault account, regardless of chain or token.
* Asset wallets are auto-created when an asset is transferred to a deposit address in a vault account that doesn't yet contain that asset wallet. Applies to all globally listed EVM assets.
* For non-globally-listed assets: user must first add the asset via the Add Asset API endpoint, after which auto-creation applies.

### Solana

* Each token requires its own on-chain token account in addition to the Fireblocks asset wallet.
* The vault account uses the base Solana address as deposit address.
* When a token wallet is created via API or Console, Fireblocks creates an internal representation only; there is no on-chain transaction at that point. This saves rent expenses and follows common Solana practices in which the sender of a token creates the address.
* Token account is created on-chain on the first incoming transaction; sender covers the rent cost.
* When the asset wallet is created due to an incoming transfer, the token account already exists on-chain.
* Asset wallets are auto-created when an asset is transferred to a deposit address in a vault account that doesn't yet contain that asset wallet. Applies to all globally listed Solana assets.
* For non-globally-listed assets: user must first add the asset via the Add Asset API endpoint, after which auto-creation applies.

# Types of vault structures

Fireblocks recommends structuring your vault accounts using one of two methods: omnibus or segregated. The diagram below describes the advantages and disadvantages of each structure.

<img alt="" />

## Omnibus structure

The omnibus structure consists of a central vault account, deposits vault account for UTXO and Tag/Memo based assets and vault accounts for each end-client for account based assets.

Funds are deposited into the individual vault accounts or to the deposits vault account, depending on the asset type, and then swept to the central vault account, where the funds can be invested.

### Address creation flows

For extended documentation, see [Best Practices for Structuring Your Fireblocks Vault](https://support.fireblocks.io/hc/en-us/articles/5253421857564-Fireblocks-Vault-structure-best-practices) . Some notes on the information presented in the Help Center article:

* Omnibus and segregated account structures are independent of whether you have a hot or cold workspace. Both account structures can be implemented in either workspace type.
* Workspaces can contain both an omnibus and segregated account models. There is no limitation for a workspace to contain one specific account model.

#### Omnibus address creation (UTXO)

<img alt="" />

* The end user, Alice, asks to deposit a UTXO asset, such as Bitcoin (BTC).
* The customer's application creates a new deposit address in the Omnibus vault account.
* This deposit address is assigned to Alice and mapped accordingly within the customer’s private ledger.
* Alice receives a notification from the application with her assigned deposit address, where she can start depositing funds.

#### Omnibus address creation (account-based with tag/memo support)

<img alt="" />

* The end user, Alice, asks to deposit an account-based asset that supports tag/memo fields, such as Ripple (XRP).
* The customer's application creates a new deposit address in the Omnibus vault account.
* This deposit address is assigned to Alice and mapped accordingly within the customer’s private ledger.
* Alice receives a notification from the application with her assigned deposit address, where she can start depositing funds.

#### Omnibus address Creation (account-based)

<img alt="" />

* The end user, Alice, asks to deposit an account-based asset, such as Ethereum (ETH).
* The customer's application creates a new intermediate vault account and a wallet with a deposit address within it.
* This deposit address is assigned to Alice and mapped accordingly within the customer’s private ledger.
* Once mapped and credited, Alice receives a notification from the application with her assigned deposit address, where she can start depositing funds.

## Segregated structure

The segregated structure consists of individual vault accounts for each end client. Funds are stored in and invested from these individual accounts.

### Address creation flows

There’s no difference between UTXO and account-based assets when dealing with the segregated account structure. For both, the process is as follows:

<img alt="" />

* The end user, Alice, asks to deposit some assets.
* The customer's application creates or reuses a vault account dedicated to Alice, then creates at least one asset wallet to generate a deposit address (if one doesn't already exist). After that, Fireblocks automatically creates an asset wallet for any globally listed asset sent to that address.
* Alice receives a notification from the application with her assigned deposit address, where she can start depositing funds.

# Hiding vault accounts

When you create intermediate vault accounts for end users, your workspace can quickly accumulate a large number of them. Sometimes tens of thousands, sometimes millions.

Having all of these accounts visible in the Fireblocks Console creates two problems. First, it degrades console performance. Second, every transaction to or from these accounts appears in the Recent activity panel, which can flood the interface with notifications when deposits are frequent. Since intermediate vault accounts are managed through the API anyway, it makes sense to hide them from the Console.

You have two ways to do this, both through the Fireblocks API:

* **Hide a vault account at creation.** Pass the optional `hiddenOnUI` parameter when calling the [Create a new vault account](/reference/createvaultaccount)a endpoint.
* **Hide an existing vault account.** Use the [Hide a vault account in the Console](/reference/hidevaultaccount) endpoint for any account that wasn't hidden at creation.

Hidden vault accounts are not gone. All transactions and balances remain fully accessible through the API.


# Overview
Source: https://developers.fireblocks.com/docs/create-payouts



<Info>
  ### Note

  Fireblocks provides technology infrastructure only. All payment and financial services described on this page are delivered by our customers under their own regulatory licenses. Fireblocks does not provide regulated services in the EEA.
</Info>

# Overview

The Payout Service API allows you to create and execute payout instruction sets.

A payout instruction set describes how to distribute payments from a payment account to multiple payee accounts.

* **Payment account:** Any valid Fireblocks-supported vault account, exchange account, or fiat account.
* **Payee account:** A valid address in Fireblocks for receiving funds. This can be a vault account, exchange account, whitelisted address, fiat account, or merchant account.

The payout process can only be executed if the payment account has a sufficient balance for the entire payout instruction set. If the payout account doesn't have a sufficient balance, the payout remains in an Insufficient Balance state until the payment account has a sufficient balance to perform the payout instructions. Payouts in an Insufficient Balance state expire at midnight UTC and are moved to Failed status.

A payout instruction set can only be executed once. Re-executing a payout instruction set results in an error.

<img alt="" />

# Payouts Flow

When a user wants to send a payment to one or more of their merchants, they can use the Payout Service API to send the payout from their exchange account.

The flow consists of 3 main steps:

1. [Creating a payout instruction set](/reference/executing-payouts#creating-a-payout-instruction-set)
2. [Executing a payout instruction set](/reference/executing-payouts#executing-a-payout-instruction-set)
3. [Monitoring Payouts](/reference/executing-payouts#executing-a-payout-instruction-set)


# Data Model
Source: https://developers.fireblocks.com/docs/data-model



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

# Overview

Fireblocks end user wallets (EUWs) are hierarchical deterministic (HD) wallets. With our REST API, customers can easily create new wallets for their end users and add multiple accounts under them. Each account can contain different assets, and all transactions are signed using the end-user key generated for a specific wallet.

# Data Model

<img alt="" />

* **User:** Represents the end user of your application. Kindly note that this entity is external to Fireblocks and is reflected only on the customer's side.
* **Device:** A logical identifier representing an entity that stores an end-user key share and can participate in MPC operations for a given wallet.
* **Wallet:** Represents an end user wallet created via the Fireblocks API.
* **Transaction:** Represents the transactions created in Fireblocks.
* **Account:** Represents the different accounts under a single end user wallet.
* **Asset:** Represents the different assets under a single account.

# Relationships

* User > Device: **One to Many** relation
* Wallet > Device: **One to Many** relation
* Wallet > Account: **One to Many** relation
* Wallet > Transaction: **Many to Many** relation
* Device > Message: **One to Many** relation
* Account > Asset: **One to Many** relation

<Info>
  ### Device ID and wallet correlation

  Each user can have multiple `deviceId` values, each correlating to a different end user wallet in Fireblocks. Each `deviceId` represents an entity that stores an end-user key share.
</Info>


# Data Privacy and Protection
Source: https://developers.fireblocks.com/docs/data-privacy-and-protection

Fireblocks does not store or process any client Personal Identifiable Information (PII). To achieve this, the customer is required to strictly use anonymized tokens, such as  (UUID) to reflect client data. These anonymous tokens are mapped internally by the customer to actual client identifiers stored on the customer's end.

Since the customer processes and manages its wallet infrastructure using the Fireblocks Console or Fireblocks API, these anonymous tokens should be used when using the Fireblocks REST API endpoints. The following table lists the relevant fields that allow persistent information to be stored in Fireblocks–for which the anonymous tokens should be used.

| API Endpoint    | Method                                                                                                                                                 | Parameter     |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
| Vault           | [Create a new vault account](/api-reference/vaults/create-a-new-vault-account)                                                                         | name          |
| Vault           | [Create a new asset deposit address](/reference/createvaultaccountassetaddress)                                                                        | description   |
| Vault           | [Rename a vault account](/api-reference/vaults/rename-a-vault-account)                                                                                 | description   |
| Internal Wallet | [Create an internal wallet](/api-reference/internal-wallets/create-an-internal-wallet)                                                                 | name          |
| Internal Wallet | [Set an AML/KYT customer reference ID for an internal wallet](/api-reference/internal-wallets/set-an-amlkyt-customer-reference-id-for-internal-wallet) | customerRefId |
| External Wallet | [Create an external wallet](/api-reference/external-wallets/create-an-external-wallet)                                                                 | name          |
| External Wallet | [Set an AML customer reference ID for an external wallet](/api-reference/external-wallets/set-an-aml-customer-reference-id-for-an-external-wallet)     | customerRefId |
| Contracts       | [Create a contract](/api-reference/contracts/add-a-contract)                                                                                           | name          |
| Transactions    | [Create a new transaction](/api-reference/transactions/create-a-new-transaction)                                                                       | note          |
| Transactions    | [Estimate a transaction fee](/api-reference/transactions/estimate-transaction-fee)                                                                     | note          |


# Overview
Source: https://developers.fireblocks.com/docs/define-aml-policies

Since privacy is a key principle of blockchain technology, transactions on the blockchain do not contain any information about the people or organizations involved. However, criminals may try to use this anonymity to hide illicit fund transfers. To prevent funds from being sent to criminals or sanctioned parties, regulators in many jurisdictions have begun mandating the collection of personal data for users transacting on the blockchain.

The Fireblocks AML feature allows you to automate real-time monitoring of your crypto transactions in order to ensure compliance with Anti-Money Laundering/Counter Financing of Terrorism (AML/CFT) regulations, prevent interactions with sanctioned entities, and identify customer behavior. You can integrate your Fireblocks account with Chainalysis or Elliptic, our third-party transaction monitoring providers, to retrieve AML/CFT information on your incoming and outgoing transactions. You can also implement your own custom screening logic for AML providers that are not natively supported.

In either case, your AML provider analyzes your transactions in real time and screens them based on the policy you create. The provider then returns a risk profile based on the transaction details (including addresses). You can approve, reject, or receive alerts for transactions in response to the provided risk information.

You, the transaction owner, are responsible for compliance reporting. Fireblocks and the AML provider make reporting easy with auditable risk information available for export. In the event of a risky transaction in a jurisdiction that requires reporting, your compliance officer will need to file any regulatory requirements with the appropriate authorities.

# Transaction Screening Flow

## Outgoing

<img alt="" />

1. You initiate a transaction in your Fireblocks workspace.
2. The transaction passes through your AML Transaction Screening Policy to determine whether it should then be sent to your AML provider for screening.
3. If the transaction should be screened according to your policy, Fireblocks sends the transaction’s details to the provider to receive the transaction’s risk information and to be registered for further monitoring. Fireblocks shares the following transaction information with your AML provider:
   1. Asset
   2. Amount
   3. Origin address
   4. Beneficiary address
   5. Blockchain hash
4. Your AML provider determines the transaction’s risk score and sends the result to your Fireblocks workspace. [Learn how Fireblocks handles outgoing transactions when risk scores are not available immediately](https://support.fireblocks.io/hc/en-us/articles/8332157003676-AML-Advanced-Configuration-settings#h_01H825711H0J4DQR4M53YMVY0Z) .
5. The integration approves or rejects the transaction based on its risk information and your Post-Screening Policy.

You can configure your Post-Screening Policy so that you receive alerts when the transaction’s risk information becomes available from your AML provider. After the screening, recorded information can be viewed in your Transaction History, the Audit Log, and your provider’s interface for auditing by your compliance team.

## Incoming

<img alt="" />

1. Fireblocks detects an incoming transaction to your workspace.
2. The transaction passes through your AML Transaction Screening Policy to determine whether it should then be sent to your AML provider for screening.
3. If the transaction should be screened according to your policy, Fireblocks sends the transaction’s details to the provider to receive the transaction’s risk information and to be registered for further monitoring. Fireblocks shares the following transaction information with your AML provider:
   1. Asset
   2. Amount
   3. Origin address
   4. Beneficiary address
   5. Blockchain hash
4. Your AML provider determines the transaction’s risk score and sends the result to your Fireblocks workspace. [Learn how Fireblocks handles incoming transactions when risk scores are not available immediately](https://support.fireblocks.io/hc/en-us/articles/8332157003676-AML-Advanced-Configuration-settings#h_01H8256NXQ4HW6ERG72686CF30) .
5. The integration approves or rejects the transaction based on its risk information and your Post-Screening Policy.

You can configure your Post-Screening Policy so that you receive alerts when the transaction’s risk information becomes available from your AML provider. After the screening, recorded information can be viewed in the Transaction History, the Audit Log, and your provider’s interface for auditing by your compliance team.

<Info>
  ### Learn more about AML:

  1. Check out the [following guide](https://support.fireblocks.io/hc/en-us/articles/360014290380-AML-Transaction-Screening-Monitoring)  for more information about Fireblocks AML integration
  2. Check out the [AML API endpoints](/reference/updateamlscreeningconfiguration)  in the API Reference
</Info>

# Best Practices

Fireblocks supports native integrations with AML providers such as Chainalysis and Elliptic. Alternatively, you can use your own integration. Regardless of your provider, the following recommendations will help you configure a reliable and effective AML setup.

* **Keep your policies as simple as possible.** Overly complicated rules can make it difficult to understand what is being screened.
* **Configure AML provider risk rating parameters to align with your compliance needs.** Be aware that risk ratings vary by provider.
  * For example, a risk rating of 4 might be considered high risk by one provider, but only moderate risk by another.
  * Some providers also allow the option to ignore risk rating entirely and focus only on categories.
* **Use the "Skip on failure" option** to control the screening process when an AML provider service is down or unreachable.

## Screening Timeouts

Fireblocks applies different timeout windows depending on the direction of the transaction:

* **Incoming transactions:** 10 minutes
* **Outgoing transactions:** 1 minute

This difference exists because AML providers need time to index transactions. Incoming transactions are resolved by transaction hash, while outgoing transactions are resolved by address. The indexing process only begins after a [certain number of blockchain confirmations](https://docs.chainalysis.com/api/kyt/guides/#polling-the-summary-endpoints-transfers-without-confirmation) is completed, which means incoming transactions require more time before a risk score can be returned.

# Custom 3rd party AML Providers

Fireblocks offers direct integrations with AML providers Chainalysis and Elliptic. If you prefer to use a different provider, we recommend setting up workflows for integrating third parties with your workspace as described in the [following guide](/docs/integrating-third-party-aml-providers).

# Freeze & Unfreeze Transactions

Auto Freeze allows you to set rules to automatically freeze an incoming transaction’s assets in your workspace for further review upon receiving funds from a suspicious sender. Fireblocks allows you to automatically freeze incoming transactions based on the default policy or a custom policy. You can also manually freeze an incoming transaction using the Freeze Transaction API endpoint.

* For UTXO-based assets, Fireblocks marks the specific transaction's inputs as unspendable.
* For account-based assets, Fireblocks marks the transaction's balance as unspendable. This means you can still use the rest of your wallet or vault account's balance for other transactions.

Once Auto Freeze takes place, the transaction does not continue to other steps in transaction screening. For example, if you have both AML and Travel Rule enabled and an incoming transaction is automatically frozen during the AML Transaction Screening Policy, the transaction does not proceed to Travel Rule transaction screening.

Users assigned an Owner or Admin role can unfreeze these funds using the Fireblocks Console or the Fireblocks API.

<Info>
  ### Check out the [Unfreeze Transaction API](/reference/freezetransaction)  in the Fireblocks API Reference
</Info>


# Define Approval Quorums
Source: https://developers.fireblocks.com/docs/define-approval-quorums



# Admin Quorum

The Admin Quorum lists all users with Admin privileges (users assigned to either an Owner, Admin, or Non-Signing Admin role).

The Admin Quorum threshold defines the number of Admins required to approve new workspace connections and changes. Any Admin can deny a request to reject it before the threshold is met. Requests have different expiration times depending on the action.

Activities that require Admin Quorum approval include:

* Whitelisting addresses
* New Fireblocks Network connections
* New exchange accounts
* Other external destination addresses
* Adding new workspace users
* Changes to Policies
* Configuring approval groups
* Other workspace configuration changes

<Info>
  ### Learn more about setting Admin Quorum in the [following guide](https://support.fireblocks.io/hc/en-us/articles/360017665119-Admin-Quorum)
</Info>

## Admin Quorum API

Check the Admin Quorum API reference [here](/reference/setadminquorumthreshold)

# Approval Groups

Approval groups consist of users from a designated user group. They are designed to facilitate the approval of various workspace configuration changes within different workspace domains, such as security and compliance, user management, the Fireblocks Network, and external accounts.\
These groups operate similarly to the Admin Quorum and can be used in its place for approving specific actions of your choice.

<Info>
  ### Learn more about defining Approval Groups in the [following guide](https://support.fireblocks.io/hc/en-us/articles/11500062124188-Approval-groups)
</Info>

This feature allows you to designate a specific group of people to approve tasks, regardless of their roles or permissions. Approval groups provide the flexibility to segregate and delegate responsibilities, which is crucial for scaling and accelerating your business operations while maintaining security.

Here are a few tips for setting up your approval groups:

* Approval groups are distinct from regular user groups and are not related to Policies
* While you can remove owner approval from certain actions, key changes in your workspace will still require owner involvement
* A threshold for the chosen group is required


# Overview
Source: https://developers.fireblocks.com/docs/define-confirmation-policy

Blockchain confirmations are crucial for maintaining the security and integrity of the blockchain. This process ensures that transactions are securely verified, thereby preventing fraud and double-spending. However, the number of confirmations also directly impacts the time it takes for a transaction to complete and for the funds to become available in your wallet. The higher the number of required confirmations, the longer it takes for the transferred amount to be accessible.

Whether you aim to speed up transaction flow by reducing the number of confirmations or enhance security by increasing them, follow the recommendations below for an effective setup.

## When to reduce the number of confirmations

A low number of blockchain confirmations should only be set for transactions coming from well-known and trusted sources. This is advisable when the origin of the transaction is your connected exchange account, a trusted counterparty, or even a transaction between two vault accounts within your workspace.

## When to increase the number of confirmations

A low number of blockchain confirmations should *not* be set for transactions arriving from unknown external addresses, or from addresses that you do not control or do not have a well-established, trusted business relationship with.

## Fireblocks Deposit Control & Confirmation Policy

The Deposit Control and Confirmation Policy allows you to specify the number of blockchain network confirmations required for incoming and outgoing transactions to clear, ensuring that their funds are credited to a wallet.

After the transaction clears, its deposit amount is accounted for in the wallet’s currently available balance. Additionally, for UTXO-based blockchain networks, the transaction's outputs become immediately spendable.

### Default Confirmation Policy

Each workspace in Fireblocks has a default configuration policy that specifies the number of confirmations required for each blockchain to complete transactions and make the funds available in the wallet.

To learn about the default values for each supported blockchain, refer to this [Help Center article](https://support.fireblocks.io/hc/en-us/articles/10883496786204-Default-Deposit-Control-and-Confirmation-Policy)

### Custom Confirmation Policy

You can define your own confirmation policy based on your organization’s business needs. Learn more about the Custom Confirmation Policy in this [Help Center article](https://support.fireblocks.io/hc/en-us/articles/10883650908572-Build-a-custom-Deposit-Control-and-Confirmation-Policy).

## Dynamically overriding the required number of confirmations

Fireblocks allows you to manually/dynamically confirm transactions and override your workspace's confirmation policy for specific transactions. This immediately updates the transaction status to Completed in your Fireblocks workspace.

* To do so manually via the Console, refer to this [Help Center article](https://support.fireblocks.io/hc/en-us/articles/360015491419-Confirming-transactions-manually).
* To do so via the API, refer to this [guide](/reference/settransactionconfirmationthreshold).


# Define Travel Rule Policies
Source: https://developers.fireblocks.com/docs/define-travel-rule-policies

The  recommended the Travel Rule in order to combat money laundering and terrorist trafficking activity. The rule states that Virtual Asset Service Providers (VASPs), which include businesses that exchange virtual assets, must provide additional data on the senders and recipients of certain transactions. Each jurisdiction decides which transactions must adhere to the Travel Rule and what data must be included.

<Warning>
  ### Fireblocks does not permanently store any transaction data needed specifically for the Travel Rule.

  All Travel Rule data is encrypted and stored with Notabene if needed. Fireblocks does not hold the keys for decrypting the information.
</Warning>

To help you comply with the Travel Rule, Fireblocks provides integration with Travel Rule provider [Notabene](https://notabene.id/). Notabene analyzes your incoming and outgoing transactions in real time and screens them based on your workspace’s Travel Rule policy. After Notabene screens a transaction and determines its compliance with the Travel Rule, the appropriate action can be taken automatically.

After integrating Notabene with your Fireblocks workspace, you can configure and manage various settings and policies. In your Notabene dashboard, you can configure settings related to your Notabene account. In your Fireblocks workspace, you can create a Travel Rule policy to determine which transactions should be screened and what post-screening actions should be taken based on the screening status.

[You can read Notabene's documentation for more information on how they integrate with Fireblocks.](https://devx.notabene.id/docs/using-notabene-and-fireblocks)

<Info>
  ### Learn more about Travel Rule Integration in the following [guide](https://support.fireblocks.io/hc/en-us/articles/8271611252764-Setting-up-Travel-Rule-integration)
</Info>

<Info>
  ### Check out the [Travel Rule APIs](/reference/validatetravelruletransaction) in the Fireblocks API Reference
</Info>


# Developer Center
Source: https://developers.fireblocks.com/docs/developer-center



# Overview

The Developer Center page lets your organization view and monitor your workspace's API activity in the Fireblocks Console.

<img alt="" />

The **Overview** tab lets you view a bar graph showing the distribution of your workspace's API requests. The default view is a seven-day distribution, but you can toggle it to view the last 24 hours of activity in one-hour windows.

Below the graph, you can view the category of each API request and what percentage that category makes up of the total distribution. Next to the percentage is the actual number of requests made within each category.

# API monitoring

The **API monitoring** tab lets you view a line graph of the types of requests made over the last seven days. Like on the Overview tab, you can switch the view to a 24-hour format divided into one-hour windows.

<img alt="" />

Below the graph, a table shows a breakdown of each request by date and time, method, category, endpoint, response code, and the number of requests made. If your workspace has numerous requests, you can search the table using the search bar above it or filter the graph and the table using the Filters tree list on the left side of the page. You can filter by response code, method, and category.

<Info>
  ### Response code 429

  Response code 429, typically reserved for rate limited responses, is an upcoming feature that is not currently available to view or filter by.
</Info>

# API users

<Warning>
  ### Only available to Admin-level workspace users

  The **API users** tab is only available to Admin-level workspace users such as the Owner, Admins, and Non-Signing Admins. The tab does not appear to any other user roles.
</Warning>

The **API users** tab lets you create and manage your workspace's API users. A table shows a list of the workspace's API users by name, role, API key, what user group (or groups) they're in, and their current status.

<img alt="" />

Visit our Help Center to learn more about:

* [Adding API users](https://support.fireblocks.io/hc/en-us/articles/4407823826194-Adding-new-API-users)
* [Re-enrolling API users](https://support.fireblocks.io/hc/en-us/articles/4412016177554-Re-enrolling-API-users)
* [Deleting users](https://support.fireblocks.io/hc/en-us/articles/4404971260050-Deleting-Users) (Owner only)


# Overview
Source: https://developers.fireblocks.com/docs/dynamic-embedded-wallets

Fireblocks has acquired Dynamic, a developer platform powering millions of onchain user accounts across web, iOS, and Android.

Dynamic's non-custodial embedded wallets enable users to tap into stablecoin rails, earn yield, spend from cards, and access DeFi protocols directly within your application.

With sub-second signing, extensive cross-chain support, and flexible recovery options, Dynamic's infrastructure integrates seamlessly alongside Fireblocks to deliver the most complete production-grade wallet experiences at scale.

Try the [live demo](https://demo.dynamic.xyz/) and [contact us](https://fireblocks.com/dynamic) for a detailed walkthrough.

## Looking for more?

* For an overview of Dynamic embedded wallets, visit [here](https://www.dynamic.xyz/docs/overview/introduction/welcome).
* For migration guides, visit [here](https://www.dynamic.xyz/docs/overview/migrations/migration-guide).


# Overview
Source: https://developers.fireblocks.com/docs/embedded-wallet-android-core-sdk



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

# What's new in 2.9.14

* Added ability to control console logging when needed, particularly for network call logging. This provides better flexibility for debugging while maintaining production performance.
* Enhanced data masking with new patterns for encryptedKey and iv fields in MaskSensitiveData functionality, providing better protection of sensitive cryptographic information.
* Enhanced error handling in WalletRepo registration process, providing more reliable wallet initialization and better error reporting.

# What's new in 2.9.9

* Android 15+ Page Size Support: Native libraries now support Android's 16 KB page sizes, fulfilling a requirement for new apps and updates targeting Android 15 and above. (Refer to the [Android Developers documentation](https://developer.android.com/guide/practices/page-sizes) for more details.)

# What's new in 2.9.8

* Improved request join wallet flow for multiple algorithms.

# What's new in 2.9.7

* Fixed an issue that prevented key generation on Android devices with non-English locales.

# What's new in 2.9.6

* Improved transaction's signature timeouts handling on wallets with multiple devices.

# What's new in 2.9.5

* We now have more accurate error events for scenarios where functionality fails due to incomplete device setup or involving invalid physical device IDs.

# What's new in 2.9.4

* We've improved how we handle failed requests by adding a short delay, ensuring faster issue resolution and reducing unnecessary retries.

# What's new in 2.9.3

* In cases where a signature verification error is detected, the system will now proactively check the integrity and status of its downloaded certificates. If these certificates are found to be outdated or invalid, they will be refreshed to ensure that signature verification can proceed correctly.

# What's new in 2.9.2

* Added `FireblocksError` `MaxDevicesPerWalletReached` (111) when the maximum number of devices in a wallet is reached while trying to add a new device. This ensures users are informed about the limit and can take appropriate actions.
* Enhanced the stability of the native code involved in Multi-Party Computation (MPC) flows. This update aims to provide a more reliable and robust experience during MPC operations.

# What's new in 2.9.1

* Added a new `internalErrorCode` field in the `FireblocksError` class to provide additional information on specific errors.

# What's new in 2.9.0

* Resolved an issue that occurred during key generation when a device setup was incomplete.
* Resolved a concurrency issue that arose when attempting to join a wallet containing multiple keys.
* Implemented a restriction to prevent the usage of internal classes, enhancing security and code integrity.

# What's new in 2.8.2

* Fixed an issue where key generation could fail if initiated immediately after SDK initialization.

# What's new in 2.8.1

* Resolved an issue when verifying certificates concurrently.

# What's new in 2.8.0

* Resolved a minor issue in the MPC code.

# What's new in 2.7.0

In version 2.7.0, we've introduced a few enhancements:

* Improved log collection.
* Resolved an issue when trying to sign a transaction that has failed or will fail before it can even be signed.
* Improved error visibility: wrong passphrase in the recovery process is now explicitly mentioned in the returned error as `WRONG_RECOVERY_PASSPHRASE` (603)
* The SDK is now being built with Android 14 (API Level 34). For more information please see [here](https://developer.android.com/google/play/requirements/target-sdk).

# What's new in 2.6.0

In version 2.6.0, we've introduced a few major enhancements.

1. Direct reporting of errors to Fireblocks. This will ease the process of supporting and debugging issues in the future. More information can be found [here](https://ncw-developers.fireblocks.com/docs/ncw-sdk-telemetry-collection).
2. Our MPC ceremony processes have been enhanced for greater robustness. MPC messages will now undergo multiple retry attempts before failing.
3. Unexpected device errors, as seen in [Common Errors](/reference/common-errors) will now result in the expected messaging, and not in a timeout.
4. You can now dynamically extend wallets! Expand the range of algorithms available in a wallet by adding, for instance, EdDSA alongside ECDSA. Learn more [here](https://ncw-developers.fireblocks.com/docs/multiple-algorithms).

# What's new in 2.5.0

In version 2.5.0, we've introduced several enhancements and additions to the SDK functionality:

1. New Functionality: We've added a new function called `stopSignTransaction` to the SDK interfaces. This function enables users to stop and cancel transactions that were initiated for signing by the SDK.
2. Enhanced error handling for quick transaction signing failures caused by invalid messages from the backend, such as schema changes in the message response from the backend.
3. We've addressed a few edge cases in the mpcKeyGeneration process that could potentially result in key generation failures. These improvements enhance the overall stability and reliability of the SDK.

## Upgrade guidelines

1. In case of an exception, GenerateMPCKeys is no longer returning an empty Set, but a Set with keys and their appropriate statuses. You will need to validate that the keys are all in status Ready in order to verify that the setup is complete. Please See the following example for [clarifications.](https://github.com/fireblocks/ncw-ios-demo/commit/5a1f3318974a28aee7cd9cbf92406cf31f2ebb0a#diff-3ae2d84b992c8e9c9fd4f787b4c0fa44c9e601083e7d1ee0892acd8fb913ef14L90)
2. All `KeyRecovery` properties are now optional. This may come into effect in a similar code to this [one](https://github.com/fireblocks/ncw-ios-demo/commit/5a1f3318974a28aee7cd9cbf92406cf31f2ebb0a#diff-3ae2d84b992c8e9c9fd4f787b4c0fa44c9e601083e7d1ee0892acd8fb913ef14L162).
3. All `KeyDescriptor` properties are now optional. This may come into effect in a similar code to this [one](https://github.com/fireblocks/ncw-ios-demo/commit/5a1f3318974a28aee7cd9cbf92406cf31f2ebb0a#diff-3ae2d84b992c8e9c9fd4f787b4c0fa44c9e601083e7d1ee0892acd8fb913ef14L162).

# What's new in 2.4.0

In version 2.4.0, we've expanded the capabilities of the NCW SDK to support Solana and Algorand, now including the EdDSA algorithm alongside our existing ECDSA support. This enhancement enables a single wallet to seamlessly interact with Bitcoin, various EVMs, and Solana.

More information about the supported NCW networks may be found [here](https://ncw-developers.fireblocks.com/docs/supported-networks) .

Additionally, we're excited to announce that support for more blockchains, including Stellar, is on the horizon. Stay tuned for further updates!

## Upgrade guidelines

To successfully utilize the generateMPCKeys function with MPC\_EDDSA\_ED25519, it's essential that your workspace supports EdDSA. Learn more about supporting multiple algorithms within a single wallet [here](https://ncw-developers.fireblocks.com/docs/multiple-algorithms).

# What's new in 2.3.0

In version 2.3.0, we made significant performance improvements in transaction signing.

For additional tips on enhancing overall performance, refer to our documentation [here](https://ncw-developers.fireblocks.com/docs/boosting-ncw-client-performance).

# What's new in 2.2.8

In version 2.2.8, we made significant performance improvements in key generation and transactions.

For additional tips on enhancing overall performance, refer to our documentation [here](https://ncw-developers.fireblocks.com/docs/boosting-ncw-client-performance).

# What's new in 2.2.5

In version 2.2.5, we have added the ability to work with multiple devices in a single wallet.

For more information about multiple devices, refer to our documentation [here](https://ncw-developers.fireblocks.com/docs/multiple-devices).

# What's new in 2.1

In version 2.1, we added a safer backup and recovery mechanism.

## Breaking change

Version 2.1 introduces a breaking change since the following two functions in the interface will receive different parameters:

* `backupKeys`
* `recoverKeys`

You can find details about the implementation in our [android-ncw-demo repo](https://github.com/fireblocks/android-ncw-demo/) and more information about the backup procedure [here](https://ncw-developers.fireblocks.com/v4.0/docs/backup-recovery).

## Upgrade guidelines

When upgrading to version 2.1 and later, you should require the user to run another backup procedure so that the new encrypted backup share on the Fireblocks servers will be associated with a `passphraseId`.


# Embedded Wallet SDK
Source: https://developers.fireblocks.com/docs/embedded-wallet-android-sdk



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

# What's new in 1.0.2

* Improved error reporting and logging capabilities


# Asset Management
Source: https://developers.fireblocks.com/docs/embedded-wallet-asset-management



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

# Getting the asset list

Call the [Retreive supported assets endpoint](/reference/getsupportedassets) to view the list of assets available to your workspace. The response includes the Fireblocks assetId which is used when you add assets.

If you're looking into quickly viewing the supported asset list, you can view the [Supported Networks](doc:supported-networks) page.

# Adding assets

You add assets via the Fireblocks SDK. Unless your Fireblocks Customer Success Manager and Fireblocks Support allow an exception, Fireblocks requires you to complete the backup procedure for each wallet before you can add any assets.

### A note on Backup Enforcement

If your workspace is already running in a Production environment, key backup enforcement is enabled by default. However, it is not enabled by default in Sandbox environments to allow for an easier integration process.

Due to the above, when you attempt to call the [Active a wallet in a vault account endpoint](/api-reference/vaults/activate-a-wallet-in-a-vault-account), you must first go through [this backup flow](https://ncw-developers.fireblocks.com/docs/backup-recovery-1#backup-procedure).

# Example

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  const address = await ew.addAsset(accountId, assetId);
  ```

  ```bash Shell theme={"system"}
  curl --request POST \
       --url https://sandbox-api.fireblocks.io/v1/ncw/wallets/walletId/accounts/accountId/assets/assetId \
       --header 'accept: application/json'
  ```
</CodeGroup>

Note in the code example above that the `accountId` parameter runs an index created by the `await ew.createAccount()` function. In our demo, we always use **accountId 0** for simplicity.

## Adding Solana Tokens

On the Solana blockchain, receiving tokens requires creating a dedicated token account derived from your main account. This is usually handled automatically when someone sends you tokens, but your customer can pre-create the account if needed.

In order to create the dedicated token account, you can still invoke the [add asset](/reference/addasset) endpoint which in turn will create a transaction on behalf of the customer, for signing.

Within the response of the request, or later on, using the [retrieve asset](/reference/getasset) endpoint you can query for the `state` of the asset.

* `PENDING_ACTIVATION`
* `ACTIVATION_FAILED`
* `READY`

In case the asset is under `PENDING_ACTIVATION`, a pending transaction still awaits the end user for signing. Once he signs the transaction, the asset status should now appear as `READY`.

In case the end user failed to sign the transaction, the status will appear as `ACTIVATION_FAILED` and the asset will require adding it again.


# Backup and Recovery
Source: https://developers.fireblocks.com/docs/embedded-wallet-backup-and-recovery



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

# Overview

As outlined in the [Backup and Recovery Overview](https://ncw-developers.fireblocks.com/docs/backup-recovery), the backup and recovery features enable the creation of an encrypted copy of the end-user key share, which is then sent to Fireblocks for safekeeping. This process becomes essential when a user may lose access to their device or need to transition to a new one.

The application or the user must generate the recovery passphrase for AES encryption of the end-user key share. The end user *must* securely preserve this passphrase. This precaution ensures that the private key share can be decrypted in a recovery situation, granting the user access to their key and enabling them to operate as usual.

Backing up the passphrase can be accomplished through various methods, and Fireblocks does not mandate any specific approach. For example, the end user can store the recovery passphrase in their iCloud account or Google Drive, or they may download and keep it locally on their device.

## Terms to know

* **`passphrase`:** The chosen passphrase for the backup. MPC key share #2 is encrypted using this passphrase and saved/encrypted along with the `passphraseId` from the Fireblocks cloud servers.
* **`passphraseId`:** The UUID created by the application.
* **`passphraseResolver`:** A callback that knows how to fetch the passphrase from its saved location when given a `passphraseId` value. For example, if you saved the passphrase on the end user's iCloud account, then when given the `passphraseId` value, the `passphraseResolver` callback fetches the passphrase from the iCloud account so that the `recoverKeys` function can decrypt the MPC key share.

# Backup procedure

<Warning>
  ### Prerequisites

  Before running a backup procedure, you will need to have an MPC key share on the device.

  This can be obtained by either:

  * Generating an MPC key share (new wallet scenarios) as shown [here](https://ncw-developers.fireblocks.com/docs/mpc-key-generation).
  * Running a recovery flow, as later described in this article.
</Warning>

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  await ewCore.backupKeys(passphrase, passphraseId);
  ```

  ```kotlin Kotlin theme={"system"}
  // create a symmetric key for the encryption of the backup
  var backupEncryptionKey = fireblocksSdk.generateRandomPassPhrase();

  // store the backupEncryptionKey somewhere (user’s iCloud/Google, d/l, convert to seed phrase or other)

  // backup the keys (including encryption)
  fireblocks.backupKeys(passphrase, passphraseId) {
    Timber.d("Backup keys result: $it")
    callback.invoke(it)
  }
  ```

  ```swift Swift theme={"system"}
  func backupKeys() async throws -> Set<KeyBackup> {
      //Initialize and create the Core SDK instance
    let instance = try getCore()
    return try await instance.backupKeys(passphrase: <passphrase>, passphraseId: <passphraseId>)
  }
  ```
</CodeGroup>

Please note that steps 1 and 2 are under your implementation, while step 3 calls the Fireblocks SDK backup.

1. Store the `passphrase` and `passphraseId` in your preferred user cloud (e.g., iCloud, Google Drive). The `passphraseId` must be a UUID, as required by Fireblocks.

2. Ensure the app can retrieve the `passphrase` during recovery on a different device. This is done via the `passphraseResolver` callback (supplied when calling `recoverKeys`): the SDK provides the `passphraseId`, and your implementation must return the corresponding `passphrase`.

   * One approach is to deterministically calculate the path to the stored passphrase in the user's cloud.
   * Alternatively, you can store and retrieve this data from another location of your choice.

3. Call the Fireblocks implementation for backup together with the `passphrase` and the `passphraseId`.

<Warning>
  ### Backing up your keys post extension

  In case you have extended your key set, as elaborated [here](https://ncw-developers.fireblocks.com/docs/multiple-algorithms#extending-your-key-set), you must repeat the above steps again, in order to back up your new, extended key set, as well.
</Warning>

# Recovery procedure

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  await ewCore.recoverKeys(passphraseResolver);
  ```

  ```kotlin Kotlin theme={"system"}
  // recover the backed up keys. We will use the given backupEncryptionKey to decrypt the keys
  Fireblocks.getInstance(deviceId).recoverKeys(passphraseResolver = passphraseResolver) {
  	Timber.d("Recover keys result: $it")
    callback.invoke(it)
  }
  ```

  ```swift Swift theme={"system"}
  //Initialize and create the Core SDK instance
  let instance = try getCore()
  let keySet = try await instance.recoverKeys(passphraseResolver: passphraseResolver)
  ```
</CodeGroup>

1. Call the Fireblocks SDK's `recoverKeys` function with a callback that implements a function that, when given a `passphraseId`, will fetch the associated `passphrase` for the user.
2. The Fireblocks SDK fetches the last encrypted key share with the associated `passphraseId` and then uses your callback to decrypt the private key share locally.

## Get the Device ID

The encrypted backup is associated with the end user's `deviceId`. Therefore, to recover and decrypt the key share saved on the Fireblocks cloud servers, the NCW SDK must be initialized with the same `deviceId` that created the backup. The NCW SDK cannot recover a key share of a different `deviceId`.

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  await ew.getLatestBackup();
  ```

  ```bash Shell theme={"system"}
  curl --request GET \
       --url https://sandbox-api.fireblocks.io/v1/ncw/wallets/walletId/backup/latest \
       --header 'accept: application/json'
  ```
</CodeGroup>

If you want to let your end users go into recovery mode, you need to determine the `deviceId` that will run the recovery procedure. To support this, Fireblocks has provided a function within the Fireblocks SDK that fetches the latest details about the backup of the specified `walletId`.

Note: If no backup is found for the specified wallet, a 404 status will be returned.

# Post-Recovery Behavior

Following recovery, the previously associated device is invalidated and loses the ability to perform MPC-related operations such as signing transactions, creating backups, adding devices, or takeovers. **The new device that successfully performed the recovery becomes the active device**.

<Warning>
  ### Special Case: Same Device Recovery

  Recovery may be performed on the same physical device that is still active and holds the key share. While this is technically redundant, it is supported. In this case, the device performing the recovery will remain active.
</Warning>


# Boosting Embedded Wallet Performance
Source: https://developers.fireblocks.com/docs/embedded-wallet-boosting-embedded-wallet-performance



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

# Overview

At the heart of Fireblocks' security lies the MPC protocol, providing robust security while heavily relying on the network due to multiple rounds between your end-user client and Fireblocks. This implies that every enhancement between the end-user and Fireblocks is then multiplied by the number of rounds (when optimizing steps that are called during the MPC process). You can find more information about the MPC protocol here:

* [What is MPC?](https://www.fireblocks.com/what-is-mpc/)
* [Key generation explained](https://ncw-developers.fireblocks.com/docs/mpc-key-generation)

# Boosting Client Performance

During SDK initialization, the client will fetch a few certificates required to make calls to Fireblocks endpoints if it was not previously called. This process may take a few moments; therefore, it is highly suggested to initialize the SDK as early as possible. The initializations don't have to be adjacent to the call to `generateMPCKeys`.

On mobile, it is recommended to use a connection pool and maintain some connections. You can view an example of a connection pool in our [Android demo](https://github.com/fireblocks/android-ncw-demo/blob/6fdf025c7cc42c92bc36be5a97a3bf0b167cea26/app/src/main/java/com/fireblocks/sdkdemo/bl/core/server/Api.kt#L26).


# Create Transaction
Source: https://developers.fireblocks.com/docs/embedded-wallet-create-transaction



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

# Overview

The transaction process is initiated with the Customer Application, where the end-user initiates the transaction via their user interface. Subsequently, the application must trigger a call to the customer backend, which invokes the Fireblocks API with all the necessary parameters to generate a new transaction. [Learn how to initiate the create transaction API call to Fireblocks](/reference/create-transactions).

Following this, the Fireblocks API will provide a unique transaction ID for the newly established transaction. As the transaction is submitted, its lifecycle begins, and its status updates based on its phase within the system. Fireblocks will dispatch a webhook notification for each transaction status update.

The most important status for this step is the **Pending Signature** status, which signifies that the transaction requires the end-user's signature. The client application needs to be notified for any transaction in the **Pending Signature** status. The most efficient way to achieve this is sending push notification to the client.

Once the application receives a transaction that requires signing, along with the transaction details, including the transaction identifier (**txId**), it should invoke the `signTransaction(txId)` method provided by the EW SDK to initiate the signing process.

It's important to note that the MPC signing process is asynchronous and involves multiple rounds of communication between Fireblocks and the end user. Therefore, the same protocol for managing outgoing and incoming messages should also be applied in this context.

# Example

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  const txArgs: TransactionArguments = {
    source: {
      type: PeerType.END_USER_WALLET,
      walletId: '<my_user_wallet_id>,
      id: '0',
    },
    destination: {
      PeerType.ONE_TIME_ADDRESS,
      oneTimeAddress: {
        address: '<some_ETH_address>'
      }
    },
    assetId: 'ETH',
    amount: '<amount>',
    note: "My First EW Transaction"
  };

  const txId = await ew.createTransaction(txArgs);
  ```

  ```kotlin Kotlin theme={"system"}
  // createOneTimeAddressTransaction
  suspend fun createOneTimeAddressTransaction(assetId: String, destAddress: String, amount: String, feeLevel: FeeLevel): Result<CreateTransactionResponse> {
    val transactionRequest = TransactionRequest(
      assetId = assetId,
      source = SourceTransferPeerPath(id = accountId.toString()),
      destination = DestinationTransferPeerPath(type = TransferPeerPathType.ONE_TIME_ADDRESS, oneTimeAddress = OneTimeAddress(address = destAddress)),
      amount = amount,
      feeLevel = feeLevel)
    return embeddedWallet.createTransaction(transactionRequest)
  }
  ```

  ```swift Swift theme={"system"}
  //createOneTimeAddressTransaction

  //initialize EmbeddedWallet instance
  let instance = try initialize()
  let request = TransactionRequest(
    assetId: assetId,
    source: SourceTransferPeerPath(id: String(accountId)),
    destination: DestinationTransferPeerPath(type: .oneTimeAddress, oneTimeAddress: OneTimeAddress(address: destAddress)),
      amount: amount,
        feeLevel: feeLevel
        )
  return try await instance.createTransaction(transactionRequest: request)
  ```
</CodeGroup>

The transaction signing itself is done by calling `signTransaction(txId)` EW Core SDK method:

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  // Transaction is in PENDING_SIGNATURE status, can be signed now:
  await ewCore.signTransaction(txId);
  ```

  ```kotlin Kotlin theme={"system"}
  Fireblocks.getInstance(deviceId).signTransaction(txId)
  ```

  ```swift Swift theme={"system"}
  //Initialize and create the Core SDK instance
  let instance = try getCore()
  let result = try await instance.signTransaction(txId: transactionId)
  ```
</CodeGroup>


# Data Objects
Source: https://developers.fireblocks.com/docs/embedded-wallet-data-objects



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

## NcwAssetBalanceUpdate

| Parameter    | Type   | Description                                                      |
| ------------ | ------ | ---------------------------------------------------------------- |
| walletId     | string | The wallet's unique ID                                           |
| accountId    | number | The ID of the account                                            |
| assetId      | string | The ID of the asset                                              |
| total        | string | Total balance of the asset                                       |
| pending      | string | The cumulative balance of all pending transactions to be cleared |
| staked       | string | Staked funds; returned only for DOT                              |
| frozen       | string | Frozen by your workspace's AML policies                          |
| lockedAmount | string | Funds in outgoing transactions not yet published to the network  |
| blockHeight  | string | The height (number) of the block of the balance                  |
| blockHash    | string | The hash of the block of the balance                             |


# Disaster Recovery
Source: https://developers.fireblocks.com/docs/embedded-wallet-disaster-recovery



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

<Info>
  ### Note about the DR kit

  The Disaster Recovery kit is designed specifically for the key share located exclusively on Fireblocks servers (Key Share #1).

  In the event that Fireblocks ceases to exist and the customer wishes to empower the end-user to perform a full key takeover, the customer must establish an endpoint on their own system.

  This endpoint will provide Key Share #1 (generated from the Disaster Recovery kit) to the SDK, enabling the reconstruction of the complete private key.
</Info>

# Overview

The Fireblocks Non-Custodial Wallet (NCW) solution provides a disaster recovery feature to help businesses ensure continuity and minimize disruption to their operations. This feature allows businesses to regenerate the shares that Fireblocks manages, ensuring their operations continue uninterrupted.

The disaster recovery feature includes a toolkit that lets you provide your end users with access to their funds, even if something happens to the original shares.

# Initial Key Generation

Fireblocks NCW employs a 2-of-2 MPC signature scheme. The user's device generates one key share (Key Share #2 in the diagram below), and Fireblocks generates the other (Key Share #1).

Every Fireblocks workspace has a randomly generated master key that functions as a seed. When a new NCW is created, Fireblocks utilizes the master key alongside the freshly generated wallet identifier to calculate the corresponding key share for that specific wallet.

Key Share #1 and Key Share #2 combine to form the fundamental master key for the given NCW.

<Info>
  ### Key Reconstruction

  MPC technology relies on the absence of a single point in time when the complete master key of the NCW exists in its entirety. The only situation when the entire master key of a NCW consolidates into a complete key is when the end user chooses to initiate the Full Key Takeover process.
</Info>

<img alt="" />

# Disaster Recovery Kit Generation

After the customer onboarding process with Fireblocks is complete, Fireblocks generates a recovery kit. This kit comprises the master key of the workspace (seed) and is subsequently transmitted to the customer.

The initiation of this procedure involves the customer generating an RSA4096 private and public key pair. The public component of this pair is shared with Fireblocks. Fireblocks then assembles a kit containing the master key for each workspace (seed).

Then, this kit is encrypted using the provided public key and dispatched to the customer. Fireblocks recommends securely storing this encrypted kit independently from the corresponding RSA private key, preferably on an offline, air-gapped machine.

<img alt="" />

# Disaster Recovery Process

The customer must set up the [Fireblocks Recovery Tool](https://github.com/fireblocks/fireblocks-key-recovery-tool) on an isolated offline machine. Once the tool is installed and a real-world situation demands its use, the customer must furnish the Fireblocks Recovery Tool with the recovery kit, the associated RSA private key, and the targeted wallet identifiers for recovery.

The Fireblocks Recovery Tool will decrypt the kit, leverage the specified wallet identifier, and generate the corresponding Key Share #1 as the output.

<img alt="" />


# Events Handler
Source: https://developers.fireblocks.com/docs/embedded-wallet-events-handler

You can choose whether to provide an events handler during the mobile and web Software Development Kits (SDKs) setup for the Fireblocks Embedded Wallet (EW). The events handler activates during different operations within the SDK and keeps you in the loop about significant occurrences, such as key generation, backup and recovery, and transaction signing.

<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

The events handler can be tailored to match your application's needs. It can be designed to execute various actions, such as refreshing the user interface, recording events, dispatching notifications, or initiating other behaviors specific to your application's functionality.

The events handler object should be provided when initializing the EW SDK. It must implement the following method (following a defined interface):

`handleEvent(event: Event): void`: The method invoked whenever there's a new event.

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  export interface IEventsHandler {  
    handleEvent(event: TEvent): void;  
  }
  ```

  ```kotlin Kotlin theme={"system"}
  interface FireblocksEventHandler {

      /**
       * Listens to various Fireblocks events see [Event]. Each event has relevant information.
       * In addition, in case of an error we will add the [FireblocksError] with the relevant error code
       */
      fun onEvent(event: Event)
  }
  ```

  ```swift Swift theme={"system"}
  public protocol EventHandlerDelegate: AnyObject {
      /// Listens to various Fireblocks events [FireblocksEvent]. Each event has relevant information.
      /// In addition, in case of an error we will add the FireblocksError with the relevant error code
      /// - Parameter event: FireblocksEvent
       func onEvent(event: FireblocksEvent)
  }
  ```
</CodeGroup>


# Overview
Source: https://developers.fireblocks.com/docs/embedded-wallet-faq



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

## How do I know which Asset ID to provide when creating a new asset in a non-custodial wallet?

Any asset supported by Fireblocks has a unique identifier. This identifier is used when creating a new asset in a non-custodial wallet (NCW) or vault account via the Fireblocks API.

The Fireblocks NCW supports Bitcoin and any EVM-based network, including ERC-20, ERC-721, and ERC-1155 tokens. For a list of supported assets in Fireblocks, including their unique identifiers, use the [Get Supported Assets](/api-reference/blockchains-&-assets/list-assets-legacy) API endpoint.

## What can and cannot be done with a disabled non-custodial wallet?

A disabled non-custodial wallet (NCW) is available for read-only operations. Once the wallet is disabled [using the API](/reference/enablewallet), none of the following operations are available:

* Signing outgoing transactions
* MPC keys setup
* MPC keys backup
* Full key takeover
* Creating new accounts
* Creating new assets

The following operations still apply to a disabled wallet:

* Incoming transactions will show up in the Fireblocks Console and Transaction History
* Balance updates
* Fetching balance via the Fireblocks API
* AML rules

## Can we import full private keys created outside of Fireblocks?

Fireblocks does not support importing private keys generated outside of our platform, and this decision is rooted in security considerations.

The primary reason behind this limitation is that when a private key exists as a complete, standalone entity, it poses a heightened risk of potential compromise.

In contrast, Fireblocks employs Multi-Party Computation (MPC) technology in our wallets. With MPC, your private key is never in its entirety at any given moment. Instead, it is divided into multiple components that are securely distributed across different entities or parties. This design significantly reduces the risk associated with a single point of compromise.


# Overview
Source: https://developers.fireblocks.com/docs/embedded-wallet-full-key-takeover-export-private-key



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

<Warning>
  ### Takeover security considerations

  While the Full Key Takeover feature provides end users with complete control over their funds, it also introduces some potential security risks. Once the private key is exported, Fireblocks no longer has control over the security of the key material. This means that the end user must take full responsibility for securing the private key and ensuring it is not lost or stolen.
</Warning>

# Overview

The Fireblocks Embedded Wallet solution provides a unique Full Key Takeover feature, which enables end users to export the entire private key. This optional feature makes the solution censorship-resistant since end users always have control over their private key. This is especially useful if Fireblocks or the customer goes out of business or discontinues the service. In this scenario, the end user can still access their funds and transact on the blockchain network.

The Full Key Takeover feature is optional, and not all businesses may want to implement it. For those who do, it is crucial to take all necessary precautions to ensure the security of the private key.

# What happens after the takeover?

Following the takeover, the app developer can decide how the app reacts to the new situation. For example, the app can function as usual afterward, or this action can change the overall end-user experience.

The complete private key that has been exported can be brought into any third-party wallet application that supports private key imports, such as MetaMask for Ethereum and Electrum Wallet for Bitcoin.

<img alt="" />

# Importing the Exported Keys

The SDKs expose a takeover function. This function returns the keys facilitated by the wallet, which can be ECDSA, EdDSA, or both. The result of the takeover includes extended public and private keys.

## ECDSA Extended Keys

The public and private ECDSA keys can be derived for each asset in the wallet. Our GitHub demos demonstrate how to derive the keys. After you derive them:

* You can import EVM keys to Metamask.
* You can import Bitcoin keys to [Electrum](https://electrum.org/) using the WIF format.

Note there is a slight difference in the exported formats between EVM and Bitcoin. Our demos show how to export the keys into the appropriate formats for Metamask and Electrum.

## EdDSA Extended Keys

There isn't a direct method to derive keys for EdDSA. To use the extended EdDSA keys, you must derive them for each asset and execute blockchain actions through your application.

We have an [Open Source guide](https://github.com/fireblocks/ncw-eddsa-signing) that shows how to use EdDSA keys with each of the assets currently supported by Fireblocks.


# Handling Returning End Users
Source: https://developers.fireblocks.com/docs/embedded-wallet-handling-returning-end-users



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

# Overview

Let's say that your end user opens your web or mobile app, and you recognize after they log in that they have completed your onboarding (which included MPC key generation) and that their `walletId` is **walletId1** and their `deviceId` is **deviceId1**. What's next?

* Did they previously complete the MPC key generation process with this device?
* Does this device need to run the recovery process now?
* Does this device need to ask to join an existing wallet?

# How to find the status of a user's keys

After you initialize the EW SDK, you can call the `getKeysStatus` function. This function returns a `keyDescriptor`object that contains the status of every ECDSA and EdDSA key associated with that user.

* The **READY** status indicates that the user completed their onboarding and generated their MPC key shares, and their device is ready to perform all MPC-related actions.
* Any other status (e.g., **INITIATED**, **REQUESTED\_SETUP**, **SETUP**, **SETUP\_COMPLETE**) indicates that the user never completed MPC key share generation and that the `generateMPCKeys` function should be called again.

If the `keyDescriptor` object returns as empty, this means the user's mobile device doesn't have a key share and was never in the process of creating a key share for the specified `deviceId`. This indicates that the current device may need to go into recovery mode or join an existing wallet.


# High-Level Architecture
Source: https://developers.fireblocks.com/docs/embedded-wallet-high-level-architecture



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

# Overview

The Fireblocks Embedded Wallet (EW), formerly Non-Custodial Wallet (NCW), architecture is designed with a minimalistic approach to provide maximum flexibility and ease of use.

Fireblocks provides Android, iOS, and Web SDKs for easily integrating EW functionality into your mobile and web applications. The mobile and web SDKs focus solely on MPC key provisioning, signing, and backup/recovery.

# Integration Components

There are two main components required for integrating the Fireblocks EW feature:

1. **Client-side application:** A mobile or web app with the EW SDK implemented.
2. **Fireblocks:** An EW-enabled workspace.

The current architecture uses a client-only approach, where the SDK communicates directly with Fireblocks APIs — no backend server is required.

<img alt="" />

# Optional: Backend Proxy Server

In the current architecture, a backend server is not required. However, some customers may choose to implement a backend proxy server for advanced use cases like request validation, rate limiting, or additional business logic.

## Example of EW creation

1. create a wallet (assign) -> `ew.assignWallet()`

* The client SDK calls the `assignWallet()` method, which communicates directly with Fireblocks to create the wallet if it doesn't exist yet.
* The client application can store the wallet ID and continue with other wallet operations.


# Initializing the SDKs
Source: https://developers.fireblocks.com/docs/embedded-wallet-initializing-the-sdks



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

# Initialize the EW SDK

1. Initialize a new `EmbeddedWallet` SDK instance
2. Call `ew.assignWallet()` - the wallet is created if doesn't exist yet.

When creating a new instance, provide the following parameters:

* **`authClientId`:** Your OAuth client ID configured in the Fireblocks Console
* **`authTokenRetriever`:** Provides a method to fetch the end user’s IDP token (via `getAuthToken()`).
* **`reporting`(optional):** When enabled, the SDK sends error reports to Fireblocks to help diagnose failures.

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  const ew = new EmbeddedWallet({
    env: ENV_CONFIG.NCW_SDK_ENV,
    logLevel: 'INFO',
    logger,
    authClientId: ENV_CONFIG.AUTH_CLIENT_ID,
    authTokenRetriever: {
      getAuthToken: () => this._rootStore.userStore.getAccessToken(),
    },
    reporting: {
      enabled: true,
    },
  });

  const wallet = await ew.assignWallet();
  ```

  ```kotlin Kotlin theme={"system"}
  val embeddedWallet = EmbeddedWallet(
                  context,
                  authClientId = authClientId,
                  authTokenRetriever = object : AuthTokenRetriever {
                      override suspend fun getAuthToken(): Result<String> {
                          val idToken = runBlocking {
                              SignInUtil.getInstance().getIdTokenBlocking(context)
                          }
                          return idToken?.let {
                              Result.success(it)
                          } ?: Result.failure(Exception("Failed to get auth token"))
                      }
                  },
                  options = EmbeddedWalletOptions.Builder().build()
  )
    
  ```

  ```swift Swift theme={"system"}
  //EnvironmentConstants.ewEnv - default environment is .production
  let options = EmbeddedWalletOptions(env: EnvironmentConstants.ewEnv, logLevel: .info, logToConsole: true, logNetwork: true, eventHandlerDelegate: nil, reporting: .init(enabled: true))

  func initialize() throws -> EmbeddedWallet {
    guard instance == nil else {
      return instance!
    }

    return try EmbeddedWallet(authClientId: authClientId, authTokenRetriever: self, options: options)
  }
  ```
</CodeGroup>

# Initialize the EW Core SDK

Generate a `deviceId`. This value is unique per SDK instance.

Each embedded wallet (EW) `walletId` correlates to one or more `deviceId`:

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  // generate a device Id, do it only once per SDK instance

  const deviceId = FireblocksNCW.generateDeviceId()
  ```

  ```kotlin Kotlin theme={"system"}
  // generate a device ID, do it only once per SDK instance
  val deviceId = Fireblocks.generateDeviceId()
  ```

  ```swift Swift theme={"system"}
  // generate a device Id, do it only once per SDK instance

  let deviceId = Fireblocks.generateDeviceId()
  ```
</CodeGroup>

When creating a new SDK instance, provide the following parameters:

* **`deviceId`:** The device ID associated with the end user and the Embedded Wallet.
* **`messagesHandler`:** The [outgoing message handler](https://ncw-developers.fireblocks.com/docs/outgoingincoming-message-handling).
* **`keyStorage`:** The [key storage handler](https://ncw-developers.fireblocks.com/docs/key-handler).
* **`eventsHandler`(optional):** The [events handler](https://ncw-developers.fireblocks.com/docs/event-handler).

## Example

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  const coreOptions: ICoreOptions = {
    deviceId,
    eventsHandler,
    secureStorageProvider,
    storageProvider,
  };

  const ewCore =
        getFireblocksNCWInstance(coreOptions.deviceId) ?? (await ew.initializeCore(coreOptions));
  ```

  ```kotlin Kotlin theme={"system"}
  val coreOptions = CoreOptions.Builder()
    .setEventHandler(object : FireblocksEventHandler {
      override fun onEvent(event: Event) {
  				//handle events or just log them if needed
        }
    }).build()
  embeddedWallet.initializeCore(deviceId, keyStorage, coreOptions)
  ```

  ```swift Swift theme={"system"}
  func initializeCore() throws -> Fireblocks {
    guard !deviceId.isEmpty else {
      throw CustomError.deviceId
    }

    //Initialize the EW SDK 
    let ewInstance = try getInstance()

    do {
      return try Fireblocks.getInstance(deviceId: deviceId)
    } catch {
      //keyStorageDelegate is a host app implementation
      self.keyStorageDelegate = KeyStorageProvider(deviceId: deviceId)
      return try ewInstance.initializeCore(deviceId: deviceId, keyStorage: keyStorageDelegate!)
    }
  }
  ```
</CodeGroup>

<Info>
  ### Note

  All SDKs (JS, Android, iOS) can be initialized with one of the following environments: sandbox, production.

  The environment initialization value will affect the selection of the correct root certificate in the SDK. If your tenant resides in the production environment (whether it be testnet or mainnet), then choose production. If you are exploring NCW using the sandbox, then simply choose sandbox.
</Info>

# Device ID

A `deviceId` is a UUID you generate to uniquely identify a client device. It must be provided when initializing the EW Core SDK. Store the `deviceId` locally and reuse it on every SDK initialization for that device.

When to generate a new `deviceId`:

* New wallet on a new device.
* Adding a new device to an existing wallet.

When to reuse an existing `deviceId`:

* Same device and wallet — retrieve from local storage.
* Recovering a lost device using the last backup.

To recover keys from a lost device, initialize the SDK with the same `deviceId` used during the last backup. You can retrieve this info via `ew.getLatestBackup()`.

<Info>
  ### Note

  If a wallet is fully initialized with a given `deviceId`, its key share can only be transferred to a new device via the [recovery procedure](https://ncw-developers.fireblocks.com/v5.0/docs/backup-recovery-1#recovery-procedure). After recovery, the original device will no longer be able to participate in MPC operations.
</Info>


# Fireblocks Embedded Wallets
Source: https://developers.fireblocks.com/docs/embedded-wallet-introduction



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

<Check>
  ### **Exciting news!**

  Fireblocks acquires [Dynamic](/docs/dynamic-embedded-wallets) , a developer platform powering millions of on-chain user accounts.

  While **Fireblocks' Embedded Wallet solution remains fully supported**, you may want to explore Dynamic’s expanded capabilities including seamless embedded wallets creation and user onboarding, flexible authentication, deeper customization, wallet connections and funding integrations across all major chains, as well as simplified fiat on/off ramps, DeFi yield and stablecoin rails. Dynamic gives developers everything needed to embed digital asset experiences seamlessly into any application.

  [See it live](https://demo.dynamic.xyz/) and [contact us](https://fireblocks.com/dynamic) for a detailed walkthrough.
</Check>

## Overview

Fireblocks offers a range of applications for handling digital asset operations and a comprehensive development platform for building your business on the blockchain.

The Fireblocks Embedded Wallet (EW) solution, formerly Non-Custodial Wallet (NCW), allows you to manage digital assets securely and effectively by granting end users full control over their funds or tokens without reliance on a third-party custodian. The Fireblocks EW comes with native web and mobile Software Development Kits (SDKs), which businesses can seamlessly integrate into their existing applications. This integration provides a secure, smooth method for storing and managing digital assets.

Employing multi-party computation (MPC) technology, the Fireblocks EW prioritizes the security and privacy of users' funds. Through MPC, end users maintain control over their private keys and benefit from an uncomplicated backup and recovery process.

The Fireblocks EW can be customized to meet your business needs, preferences, and requirements. The solution equips developers with foundational building blocks for completing key tasks, such as generating keys, signing transactions, and managing wallet balances. These building blocks give developers the flexibility to create custom product flows that integrate with their application's existing design and user interface. This adaptability empowers businesses to differentiate their product offerings, deliver unique experiences for their users, and maintain competitiveness in the market.

The Fireblocks EW doesn't require users to remember long seed phrases or mnemonics. All they have to do is create a passphrase for the recovery process, and they can save it wherever they prefer, like on Google Drive, iCloud, and more.

The Fireblocks EW solution comes with an Application Programming Interface (API) that allows developers to programmatically oversee wallet functionality and enhance their authority over the user experience.

## Why EW?

In the past year, we have seen a change in customers' preference for web3 wallet implementation, moving from the Custodial model, where the company controls its end user's assets, to the Non-Custodial Embedded model, in which the assets are controlled by the end user. This change is driven by three major aspects:

### Regulation and business risk

The Fireblocks EW provides solutions for a variety of regulatory issues applicable to both financial and non-financial enterprises.

Financial entities that provide self-custodial services must adhere to changing regulations. This limits the range of services they can extend to customers and also slows their pace of product development.

For non-financial entities, EW helps reduce the business risk associated with entering the web3 space. Businesses can concentrate on creating attractive product offerings while eliminating the responsibility and business risk associated with being the custodian of their customers' assets.

### User trust

The saying "not your keys, not your coins" encapsulates the idea that investors can't be certain about their cryptocurrency holdings unless they control the keys to their wallets.

In a surprising move in June 2022, the Celsius Network, a major player in crypto lending with assets surpassing \$20 billion, sent shockwaves through the crypto industry by announcing a temporary halt on all withdrawals from its platform.

Later the same year, the dramatic downfall of the FTX crypto exchange had a profound impact on the industry, prompting critical discussions about the nature of speculative investments. This turn of events left a considerable number of frustrated individuals unable to access their invested funds, as FTX temporarily suspended user cash withdrawals, citing liquidity challenges, shortly before declaring bankruptcy.

Presently, the market sentiment strongly favors embedded wallets.

### Retention

Customer retention was one of the initial motivations that drove financial businesses toward exploring embedded wallets. A significant portion of their customers were leaving due to their inability to access Decentralized Finance (DeFi). In response, those customers withdrew funds to engage with the DeFi landscape through external wallets.

By providing these users with an embedded solution with access to Web3 decentralized applications (dApps), these businesses can better retain customers.


# Overview
Source: https://developers.fireblocks.com/docs/embedded-wallet-ios-core-sdk



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

# What's new in 2.9.14

* Improved error handling and logging with console output control.

# What's new in 2.9.8

* Improve logging capabilities by writing logs to the same file without additional folders.

# What's new in 2.9.2

* Added validations to the RPC messages received

# What's new in 2.9.1

* Introduced additional logging

# What's new in 2.9.0

Major Enhancements:

* **Join Device Flow Stability**: Fixed a rare crash that could occur when stopping the Join Device Flow, improving overall reliability.
* **SDK Logging**: Enhanced SDK logging to provide more detailed and structured logs, making it easier to debug and track issues.
* **Error Handling**: Standardized error handling across all platforms, ensuring consistent behavior and improved error reporting. Also added  `FireblocksError`  `MaxDevicesPerWalletReached` (111) when the maximum number of devices in a wallet is reached while trying to add a new device. This ensures users are informed about the limit and can take appropriate actions.

# What's new in 2.8.2

* Enhanced the MPC ceremony process to improve overall robustness and reliability.

# What's new in 2.8.1

* Introduced additional logging to provide better insights and troubleshooting.

# What's new in 2.8.0

Major Enhancements:

* Enhanced Performance Optimization:
  * Improved execution speed and reduced latency for high-demand operations.
  * Refined memory management for better stability and efficiency.
* Advanced Data Processing:
  * Optimized algorithms for reduced computational overhead.

New Features:

* Improved Error Handling:
  * More detailed error messages and diagnostics to facilitate quicker debugging.
  * Added support for custom error handlers and logging mechanisms.

Bug Fixes:

* Addressed stability issues reported in previous versions.

# What's new in 2.7.1

* Resolved an issue when trying to sign transactions in the main thread.

# What's new in 2.7.0

In version 2.7.0, we've introduced a few enhancements:

* Improved log collection.
* Resolved an issue when trying to sign a transaction that has failed or will fail before it can even be signed.
* Improved error visibility: wrong passphrase in the recovery process is now explicitly mentioned in the returned error as `WRONG_RECOVERY_PASSPHRASE` (603)

# What's new in 2.6.0

In version 2.6.0, we've introduced a few major enhancements.

1. Direct reporting of errors to Fireblocks. This will ease the process of supporting and debugging issues in the future. More information can be found [here](https://ncw-developers.fireblocks.com/docs/ncw-sdk-telemetry-collection).
2. Our MPC ceremony processes have been enhanced for greater robustness. MPC messages will now undergo multiple retry attempts before failing.
3. Unexpected device errors, as seen in [Common Errors](/reference/common-errors) will now result in the expected messaging, and not in a timeout.
4. You can now dynamically extend wallets! Expand the range of algorithms available in a wallet by adding, for instance, EdDSA alongside ECDSA. Learn more [here](https://ncw-developers.fireblocks.com/docs/multiple-algorithms).

# What's new in v2.5.1

We introduced several enhancements and additions to the SDK functionality:

1. **Canceling Transactions**: Added a new function called `stopSignTransaction` to the SDK interfaces. This function enables your app to cancel transactions the end-user initiated for signing.
2. **Improved Error Handling**: Enhanced error handling for quick transaction signing failures caused by invalid messages from the backend, such as schema changes in the response. This improvement helps identify and resolve issues faster.
3. **MPC Key Generation**: Addressed a few edge cases in the MPC Key Generation process that could potentially result in key generation failures.
4. **EdDSA Signing Performance**: Drastically improved EdDSA Blockchains *signing* speed.
5. **Logging**: Added a new parameter, logToConsole, to FireblocksOptions. This parameter allows you to push logs to the Xcode console when running the host app, which can be helpful for debugging purposes.
6. **Minor Interface Changes**: There were some small changes to the SDK interface. Please read the guidelines in the following section for more details.

## Upgrade guidelines

1. `GenerateMPCKeys` Behavior Change: In case of an exception, GenerateMPCKeys now returns a Set containing keys and their corresponding statuses, instead of an empty Set. You will need to check that all keys have a "Ready" status to ensure successful setup. Please see the following example for [clarification](https://github.com/fireblocks/ncw-ios-demo/commit/5a1f3318974a28aee7cd9cbf92406cf31f2ebb0a#diff-3ae2d84b992c8e9c9fd4f787b4c0fa44c9e601083e7d1ee0892acd8fb913ef14L90).
2. Optional `KeyRecovery` Properties: All KeyRecovery properties are now optional. This may affect your code if you were previously relying on default values. See the following example for a similar [code change](https://github.com/fireblocks/ncw-ios-demo/commit/5a1f3318974a28aee7cd9cbf92406cf31f2ebb0a#diff-3ae2d84b992c8e9c9fd4f787b4c0fa44c9e601083e7d1ee0892acd8fb913ef14L162).
3. Optional `KeyDescriptor` Properties: All KeyDescriptor properties are now optional. This may affect your code if you were previously relying on default values. See the following example for a similar [code change](https://github.com/fireblocks/ncw-ios-demo/commit/5a1f3318974a28aee7cd9cbf92406cf31f2ebb0a#diff-3ae2d84b992c8e9c9fd4f787b4c0fa44c9e601083e7d1ee0892acd8fb913ef14L162).

# What's new in v2.4.0

We expanded the capabilities of the NCW SDK to support Solana and Algorand, now including the EdDSA algorithm alongside our existing ECDSA support. This enhancement enables a single wallet to seamlessly interact with Bitcoin, various EVMs, and Solana.

More information about the supported NCW networks may be found [here](https://ncw-developers.fireblocks.com/docs/supported-networks) .

Additionally, we're excited to announce that support for more blockchains, including Stellar, is on the horizon. Stay tuned for further updates!

## Upgrade guidelines

To successfully utilize the generateMPCKeys function with MPC\_EDDSA\_ED25519, your workspace must support EdDSA. Learn more about supporting multiple algorithms within a single wallet [here](https://ncw-developers.fireblocks.com/docs/multiple-algorithms).

# What's new in v2.3.2

We resolved a bug that occurred during transaction signing, leading to intermittent failures after a few transactions. The root cause was identified within the MPC process, where the SDK did not handle a specific use case that emerged during performance improvement efforts.

It's important to note that although a transaction may have failed initially, it was possible to retry the transaction signing with success on subsequent attempts.

# What's new in v2.3.1

We addressed and resolved a potential race condition that could occur during the `generateMPCKeys` process. This fix ensures that the operation no longer fails due to the identified race condition.

# What's new in v2.3.0

We made significant performance improvements in key generation and transactions signing.

For additional tips on enhancing overall performance, refer to our documentation [here](https://ncw-developers.fireblocks.com/docs/boosting-ncw-client-performance).

# What's new in v2.2.0

We added the ability to work with multiple devices in a single wallet.

For more information about multiple devices, refer to our documentation [here](https://ncw-developers.fireblocks.com/docs/multiple-devices).

# What's new in v2.1

We added a safer backup and recovery mechanism.

## Breaking change

We made a significant breakthrough since the following two functions in the interface will receive different parameters:

* `backupKeys`
* `recoverKeys`

You can find details about the implementation in our [ios-ncw-demo repo](https://github.com/fireblocks/ncw-ios-demo) and more information about the backup procedure [here](https://ncw-developers.fireblocks.com/v4.0/docs/backup-recovery).

## Upgrade guidelines

When upgrading to version 2.1 and later, you should require the user to run another backup procedure so that the new encrypted backup share on the Fireblocks servers will be associated with a `passphraseId`.


# Embedded Wallet SDK
Source: https://developers.fireblocks.com/docs/embedded-wallet-ios-sdk



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

# What's new in 1.0.10

* Improved authentication token handling.
* Added comprehensive network logging for both success and error responses
* Enhanced error handling for network logging operations
* Improved debugging capabilities with better network request/response visibility

# What's new in 1.0.3

* Enhanced Logging: Logs are now written to a single, unified file (within the NCW Core log structure), ensuring a clearer, sequential flow of events. This improves traceability and debugging.


# Overview
Source: https://developers.fireblocks.com/docs/embedded-wallet-js-core-sdk

https://www.npmjs.com/package/@fireblocks/ncw-js-sdk

<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

# What's new in 12.5.6

* Added new validation to `IMessagesHandler` responses to prevent crashes from non-conforming or malformed data.

# What's new in 12.5.5

* Fixed an issue where `STARTED` event was fired twice in the case of multiple devices for the given wallet.
* Fixed an issue where reporting of errors with empty strings was missing.
* Added a new error code, `INCOMPLETE_BACKUP` (706) when trying to backup keys, while one or more of the required algorithms is missing for backup.

# What's new in 12.5.3

* Fixed an issue where timeout was not properly stopping internal polling processes, ensuring more reliable performance.
* Added a new error code, `FireblocksError`  `MaxDevicesPerWalletReached` (111) when the maximum number of devices in a wallet is reached while trying to add a new device. This ensures users are informed about the limit and can take appropriate actions.

# What's new in 12.5.2

Enhanced the robustness of event dispatching to handle cases where client callbacks throw exceptions

# What's new in 12.5.1

Resolved an issue when trying to re-use an instance after calling `dispose`

# What's new in 12.5.0

* Resolved a minor issue in the MPC code.

## Breaking change

Version 12.5.0 introduces a small breaking change:

* It is not possible anymore to create **multiple instances** of the SDK **for the same device id**.
* If trying to do it, a `FireblocksError` exception will be thrown with error code  `INSTANCE_ALREADY_INITIALIZED (109)`
* Instead, you must re-use the instance you already created.
* This is done by calling `getFireblocksNCWInstance(deviceId)` before creating an instance with `FireblocksNCWFactory(options)`.

We recommend visiting our [ncw-web-demo repo](https://github.com/fireblocks/ncw-web-demo) to understand how to adapt your app to the SDK changes. Specifically, you can always jump to this [commit](https://github.com/fireblocks/ncw-web-demo/pull/35/files) and see the changes we added to the web demo.

# What's new in 12.4.1

* Resolved an issue when dealing with multiple concurrent calls to `generateMPCKeys`
* Improved error visibility: wrong passphrase in the recovery process is now explicitly mentioned in the returned error as `WRONG_RECOVERY_PASSPHRASE (603)`

# What's new in 12.3.1

* Resolved an issue when trying to sign a transaction that has failed or will fail before it can even be signed.

# What's new in 12.2.1

* Resolved an issue in the MPC ceremony process that previously caused exceptions in cases of poor connectivity.
* Enhanced the robustness of the MPC ceremony process by extending the retry mechanism.

# What's new in 12.2.0

In version 12.2.0, we've introduced a few major enhancements.

* Direct reporting of errors to Fireblocks. This will ease the process of supporting and debugging issues in the future. More information can be found [here](https://ncw-developers.fireblocks.com/docs/ncw-sdk-telemetry-collection).
* Our MPC ceremony processes have been enhanced for greater robustness. MPC messages will now undergo multiple retry attempts before failing.
* You can now dynamically extend wallets! Expand the range of algorithms available in a wallet by adding, for instance, EdDSA alongside ECDSA. Learn more [here](https://ncw-developers.fireblocks.com/docs/multiple-algorithms).

# What's new in 12.1.0

In version 12.1.0, we've expanded the capabilities of the NCW SDK to support Solana and Algorand, now including the EdDSA algorithm alongside our existing ECDSA support. This enhancement enables a single wallet to seamlessly interact with Bitcoin, various EVMs, and Solana.

More information about the supported NCW networks may be found [here](https://ncw-developers.fireblocks.com/docs/supported-networks) .

Additionally, we're excited to announce that support for more blockchains, including Stellar, is on the horizon. Stay tuned for further updates!

## Upgrade guidelines

To successfully utilize the generateMPCKeys function with MPC\_EDDSA\_ED25519, it's essential that your workspace supports EdDSA. Learn more about supporting multiple algorithms within a single wallet [here](https://ncw-developers.fireblocks.com/docs/multiple-algorithms).

# What's new in 12.0.0

In version 12.0.0, we introduced a more structured approach to error handling in our JavaScript SDK. With the inclusion of an exported `FireblocksError` class, developers can now access detailed error information using the new **FireblocksError.message** and **FireblocksError.key** properties.

If issues arise during SDK activities, these structured error responses aim to provide you with better insights, enabling efficient debugging or informed inquiries to our support team.

## Upgrade guidelines

If your previous code relied on specific error responses from the NCW SDK, incorporating these new error codes may improve the accuracy of your try/catch flows. Refer to this [PR](https://github.com/fireblocks/ncw-web-demo/pull/26/files) to see how we handled the SDK upgrade in our web demo.

# What's new in 11.0.2

In version 11.0.2, fixed a bug that may occur during a call to `generateMPCKeys`.

# What's new in 11.0.1

In version 11.0.1, we have implemented significant performance improvements in key generation and transactions. For additional tips on enhancing overall performance, refer to our documentation [here](https://ncw-developers.fireblocks.com/docs/boosting-ncw-client-performance).

# What's new in 11.0.0

In version 11.0.0, we upgraded some of our JavaScript SDK infrastructure in preparation for upcoming versions, which include performance improvements in MPC key creation and transactions.

We also added these features and made these changes:

* The SDK logger utility lets you choose to keep historical data of all NCW SDK activity.
* The fetch log utility can now fetch SDK logs from your app.
* Reduced package size for faster loading times.

## Breaking change

Version 11.0.0 introduces a breaking change since we renamed the following interfaces:

* Instead of initializing via the `FireblocksNCW.initialize(options)` class function, call `FireblocksNCWFactory(options)`.
* Do not declare variables with type `FireblocksNCW` but refer to it via the `IFireblocksNCW` interface.
* Instead of initializing the logger via the `new ConsoleLogger()` function, call `ConsoleLoggerFactory()`.
* Instead of calling the `FireblocksNCW.version` function, call `version` directly.
* Instead of calling the `FireblocksNCW.generateDeviceId()` function, call `generateDeviceId()` directly.

We recommend visiting our [ncw-web-demo repo](https://github.com/fireblocks/ncw-web-demo) to understand how to adapt your app to the SDK changes. Specifically, you can always jump to this [commit](https://github.com/fireblocks/ncw-web-demo/pull/22/files#diff-bf5c0e301a4690ed37b7b89cd8479ddfd3660cb4e567b446cb12b7852c3f8f27R27) and see the changes we added to the web demo.

# What's new in 10.0.7

In version 10.0.7, we added the ability to work with multiple devices in a single wallet. You can find more information about implementing multiple devices [here](https://ncw-developers.fireblocks.com/docs/multiple-devices).

# What's new in 10.0

In version 10.0, we added a safer backup and recovery mechanism.

## Breaking change

Version 10.0 introduces a breaking change since the following two functions in the interface will receive different parameters:

* `backupKeys`
* `recoverKeys`

You can find more details about the implementation in our [ncw-web-demo repo](https://github.com/fireblocks/ncw-web-demo) and the backup procedure [here](https://ncw-developers.fireblocks.com/v4.0/docs/backup-recovery).

## Upgrade guidelines

When upgrading to version 10.0 and later, you should require the user to run another backup procedure so that the new encrypted backup share on the Fireblocks servers will be associated with a `passphraseId`.


# Embedded Wallet SDK
Source: https://developers.fireblocks.com/docs/embedded-wallet-js-sdk

https://www.npmjs.com/package/@fireblocks/embedded-wallet-sdk

<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>


# Key Storage
Source: https://developers.fireblocks.com/docs/embedded-wallet-key-storage



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

# Overview

The Fireblocks Embedded Wallet (EW) feature offers a flexible key storage mechanism that allows you to customize the implementation of key loading and saving processes outside the mobile Software Development Kit (SDK) itself.

This approach allows you to incorporate various security measures, such as mobile enclaves, biometric authentication, and two-factor authentication (2FA). The EW SDK is agnostic to the precise methodology employed for key storage, with the implementation being supplied to the SDK during the initialization process.

# Web vs. Mobile

When integrating with the EW Web SDK, the key storage approach differs from that of Android and iOS. Unlike these platforms, where storage mechanisms are provided, JavaScript applications can run in various environments such as web browsers, Node.js, or Electron. This variability means you can't rely on platform-specific storage capabilities. Instead, customers using our EW Web SDK are tasked with supplying a suitable storage solution.

Our SDK incorporates a secure storage feature involving a process of *locking* and *unlocking*. Before any data retrieval or storage operation, the SDK triggers the *unlock* function, and just before finalizing the operation, it invokes the *lock* function.

Distinct from Android and iOS paradigms involving data removal or targeted checks, the web-based approach revolves around managing data stored and loaded with each SDK usage.

One option for key storage involves encrypting the secret key material with a password and storing it in the local browser storage. However, this implies that users switching to a different machine would lose access to this data. Alternatively, storing the encrypted data on the server allocates each user a secure section on the server, accessible post-login.

The key storage provider has to be provided upon SDK initialization and must implement the following interface:

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  export interface IStorageProvider {
    get(key: string): Promise<string | null>;
    set(key: string, data: string): Promise<void>;
  }

  export interface ISecureStorageProvider extends IStorageProvider {
    getAccess(): Promise<void>;
  }
  ```

  ```kotlin Kotlin theme={"system"}
  interface FireblocksKeyStorage {

      /**
       * Store raw keys data
       * @param keys map of keyId and raw [ByteArray] of data.
       * @param callback result is a map of store keys operation result
       */
      fun store(keys: Map<String, ByteArray>, callback: (result: Map<String, Boolean>) -> Unit)

      /**
       * Load raw keys data
       * @param keyIds a set of key ids to load
       * @param callback result is a map of key id and raw key data as [ByteArray]
       */
      fun load(keyIds: Set<String>, callback: (result: Map<String, ByteArray>) -> Unit)

      fun remove(keyIds: Set<String>, callback: (result: Map<String, Boolean>) -> Unit)

      fun contains(keyIds: Set<String>, callback: (result: Map<String, Boolean>) -> Unit)
  }
  ```

  ```swift Swift theme={"system"}
  public protocol KeyStorageDelegate: AnyObject {
       
       /// Store raw keys data
       /// - Parameters:
       ///   - keys: map of keyId and Data
       ///   - callback: result is a map of store keys and operation result
      func store(keys: [String: Data], callback: @escaping ([String: Bool]) -> ())
       
       
       /// Load raw keys data
       /// - Parameters:
       ///   - keyIds: a set of key ids to load
       ///   - callback: result is a map of key id and raw key data as Data
      func load(keyIds: Set<String>, callback: @escaping ([String: Data]) -> ())
       
       /// Remove raw data from your storage
       /// - Parameter keyId: key id to remove
      func remove(keyId: String)
       
       /// Check if Set of key ids is stored on your storage
       /// - Parameters:
       ///   - keyIds: a set of key ids to verify
       ///   - callback: result is a map of keys and operation result
      func contains(keyIds: Set<String>, callback: @escaping ([String : Bool]) -> ())
  ```
</CodeGroup>

* `store`/`set`: Called to store the MPC key share on the end-user device
* `load`/`get`: Called to get the MPC key share from the end-user device
* `remove` (**Android and iOS only**): Called to remove the MPC key share from the user device
* `contains` (**Android and iOS only**): Called to check if the set of MPC key shares is stored on the device
* `getAccess` (**Web only**): Called to lock or unlock the secure key storage upon every NCW SDK execution


# Embedded Wallet Keys Explained
Source: https://developers.fireblocks.com/docs/embedded-wallet-keys-explained



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

# Overview

Embedded wallets reside in a Fireblocks workspace that includes custodial Vault Accounts assigned to the customer.

Each embedded wallet has its separate keys. Also, the workspace includes one master key to serve the customer's vault accounts (not connected to the end user wallets).

Fireblocks embedded wallets use a 2-of-2 MPC signature scheme. One key share resides in an Intel SGX-enabled server managed by Fireblocks, and the other resides on the end user's device.

# Structure

The Fireblocks workspace can include an unlimited number of embedded wallets and an unlimited number of wallet accounts inside each embedded wallet. Each wallet account can hold as many asset wallets as you need. However, you can only have one type of wallet asset per wallet account.

<img alt="" />

You can also use our non-custodial embedded wallets in parallel with self-custodial wallets. One workspace can support both structures.

# Secret key management and wallet derivation

<img alt="" />

The derivation for non-custodial embedded wallets is almost the same as for self-custodial wallets. Each asset in an embedded wallet is derived according to the following structure:

**`m/purpose/coinType/account/change/index`**, where:

* **m** is the master private key
* **purpose** is the derivation standard (BIP-44 in our example)
* **coinType** is the unique identifier of an asset (0 for BTC, 60 for ETH, etc.)
* **account** is the vault account ID
* **change** is always 0
* **index** is the address index (always 0 except for UTXO-based assets)

<Info>
  ### Note

  In Non-Custodial Wallets, Bitcoin wallets can only have one deposit address per account, unlike self-custodial wallets that can have more that one deposit address within the same account.

  This means that for any account, the derivation path for the BTC asset in it will always be `m/44/0/accountId/0/0`.
</Info>

# Unsure about which custody model is best for you?

Read our [Guide to Digital Asset Wallets and Service Providers](https://www.fireblocks.com/a-guide-to-digital-asset-wallets-and-service-providers) for insights into evaluating digital asset wallets and service providers for your business.


# MPC Key Generation
Source: https://developers.fireblocks.com/docs/embedded-wallet-mpc-key-generation



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

# Overview

The creation of multi-party computation (MPC) keys involves a dynamic, step-by-step procedure that involves several rounds of communication between the end user's device and Fireblocks. This process operates asynchronously, meaning that it takes place over multiple interactions rather than a single continuous operation.

# Key Generation

Let's break down the process for better clarity:

1. Your application calls the `generateMPCKeys` method in our SDK to initiate the generation of MPC keys. This step triggers the process and sets everything in motion.
2. `generateMPCKeys` can be called with the algorithms you wish to create under the wallet. Currently, it is `MPC_EDDSA_ED25519` or `MPC_ECDSA_SECP256K1`. More information about it can be found [here](https://ncw-developers.fireblocks.com/docs/multiple-algorithms)
3. The crucial part of the whole process lies in the communication rounds between the end user's device and Fireblocks. These rounds are essential for securely creating the keys.
4. The process unfolds repeatedly, with each round building upon the previous one. Your application exchange messages, refining the communication until the process is complete.
5. After successfully generating MPC keys, the final step involves securely storing these keys to ensure protection for your end users. You can tailor this process to your preferences through various options, such as mobile enclaves, biometric authentication, two-factor authentication (2FA), and more. You retain total control over the implementation that best suits your security needs.

# Key Generation

First, create a new EW using the EW SDK:

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  // Assign (or create) the EW wallet
  const wallet = await ew.assignWallet();
  ```

  ```kotlin Kotlin theme={"system"}
  embeddedWallet.assignWallet()
  ```

  ```kotlin Kotlin theme={"system"}
  embeddedWallet.assignWallet()
  ```
</CodeGroup>

Next, create a new account in the newly created EW (needed once)

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  // Create account under wallet
  const newAccount = await ew.createAccount();
  ```

  ```kotlin Kotlin theme={"system"}
  embeddedWallet.createAccount()
  ```

  ```kotlin Kotlin theme={"system"}
  embeddedWallet.createAccount()
  ```
</CodeGroup>

Lastly, start the MPC key generation from your application. You can add the below to your customer application.

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  import { IKeyDescriptor } from "@fireblocks/ncw-js-sdk";

  // Generate MPC Keys
  const algorithms = new Set(["MPC_CMP_ECDSA_SECP256K1"]);
  const keyDescriptor: Set<IKeyDescriptor> = await ewCore.generateMPCKeys(algorithms);
  ```

  ```kotlin Kotlin theme={"system"}
  val algorithms = setOf(Algorithm.MPC_ECDSA_SECP256K1)
  fireblocksSdk.generateMPCKeys(algorithms = algorithms){ result ->
      Timber.i("generateMPCKeys result: $result")
  }
  ```

  ```swift Swift theme={"system"}
  func generateKeys(algorithms: Set<Algorithm>) async throws -> Set<KeyDescriptor> {
    //Initialize and create the Core SDK instance
    let instance = try getCore()
    return try await instance.generateMPCKeys(algorithms: algorithms)
  }
  ```
</CodeGroup>

If the device storage has generated keys once (e.g., the EW Core SDK already initialized with a specific `deviceId` that was called successfully with the `generateMPCKeys` function), you do not need to call this function. This scenario relates to a situation in which an end-user is logging in to an already set-up device.

<Info>
  ### Note

  If you use a `deviceId` or `walletId` that previously had keys generated—but those keys are no longer present on the current device (e.g., after an app reinstall or using a new browser)—calling `generateMPCKeys` will fail. Fireblocks only allows key generation once per walletId–deviceId pair. In this case, you must recover the key share using the `recoverKeys` method.
</Info>


# Multi-Device Implementation
Source: https://developers.fireblocks.com/docs/embedded-wallet-multi-device-implementation



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

<Warning>
  ### Device number limit

  To help maintain a wallet performance, each wallet is limited to 10 devices. If you reach this limit, you can disable old or unused devices using this [endpoint](/reference/enabledevice).
</Warning>

# Overview

The Fireblocks Embedded Wallet (EW) solution allows multiple devices to perform actions using the same wallet, such as signing transactions and running takeovers. This lets you support a multi-device, multi-platform seamless digital experience and enables an end user to use their account on any of their devices.

## Definitions

Let us define the following two types of devices for a multiple-device wallet:

* **Requesting device:** A new device that wants to join the wallet.
* **Approving device:** The device in the wallet that can already run operations, like signing transactions; for example, the device you generated key shares with.

## Supported functions

Two functions in the EW SDK interface support multiple devices:

* **`requestJoinExistingWallet`:** A function in the requesting device that receives a handler that emits events according to the progression of the process. Specifically, the function emits `requestId`, the UUID used to approve the request.
* **`approveJoinWalletRequest`:** A function in the approving device that receives a `requestId` and will allow the processing of the approval to start.

# Implementing multiple devices

## Requesting to join a wallet

First, using your authentication solution, verify that the end user's requesting device is trying to join a wallet that has already generated key shares and that that device is currently associated with such a wallet.

<Info>
  ### Note

  You can check on the device's key status via the EW SDK by calling  `getKeysStatus()` to verify that the keys are in the `READY` status.
</Info>

Next, initialize the Fireblocks SDK through the requesting device with a new `deviceId`. Make sure you know which wallet you want to associate this device with, according to the authentication your end user went through.

Then, use the requesting device to call the `requestJoinExistingWallet` function with a handler. This handler emits events that notify your application of the progress of the `requestJoinExistingWallet` procedure.

```javascript Web theme={"system"}
await ewCore.requestJoinExistingWallet({
  onRequestId(requestId) {
    // your code here
    set((state) => ({ ...state, addDeviceRequestId: requestId }));
  },
  onProvisionerFound() { // -> optional
    // your code here
  },
});
```

```kotlin Android theme={"system"}
val joinWalletHandler: FireblocksJoinWalletHandler = object : FireblocksJoinWalletHandler {
    override fun onRequestId(requestId: String) {
        // use this requestId to approve the request from the source device, e.g. using a QR code or a push notification
        // the requestId will be used in approveJoinWalletRequest method
    }

    override fun onProvisionerFound() {
        // use this indication the provisioner device was found and the join process continues, e.g. show a spinner/progress bar
    }
}

Fireblocks.getInstance(deviceId).requestJoinExistingWallet(joinWalletHandler) { result ->
    Timber.i("joinExistingWallet result: $result")
}
```

```swift iOS theme={"system"}
  //Initialize and create the Core SDK instance
  let instance = try getCore()
//joinWalletHandler: FireblocksJoinWalletHandler
let result = try await instance.requestJoinExistingWallet(joinWalletHandler: joinWalletHandler)

```

After you call the `requestJoinExistingWallet` function, it yields a `requestId` in three ways:

1. Via the events handler submitted with the EW SDK's initialization.
2. Via the `joinWalletResolver` callback associated with the function itself.
3. Via a webhook notification. For example:

```javascript Web (JavaScript) theme={"system"}
{
	 type: "NCW_ADD_DEVICE_SETUP_REQUESTED",
	 tenantId: string,
	 timestamp: number,
	 data: {
	     walletId: string,
	     deviceId: string,
	     requestId: string,
	 },
};
```

## Approving a new device

The approving device calls the `approveJoinWalletRequest` function with the corresponding `requestId` to approve or reject the new device.

```javascript Web (JavaScript) theme={"system"}
const result = await ewCore.approveJoinWalletRequest(requestId);
console.log("approveJoinWallet result:", result);
```

```kotlin Android (Kotlin) theme={"system"}
Fireblocks.getInstance(deviceId).approveJoinWalletRequest(requestId) { result ->
    Timber.i("approveJoinWallet result: $result")
}
```

```swift iOS theme={"system"}
//Initialize and create the Core SDK instance
let instance = try getCore()
return try await instance.approveJoinWalletRequest(requestId: requestId)

```

When a new device is approved, the process of adding the requesting device begins and takes a few seconds to send multiple MPC messages.

On the existing device, we will then see additional MPC messages until the key material is ready to be stored.

Eventually, the requesting device will join the wallet and be able to run all MPC-related actions.

# Multiple device scenarios

In a multi-device scenario, all devices see the same balance, can initiate and sign transactions, approve adding a new device to the wallet, or perform any other action, such as takeover.

When performing a transaction, once a device is approved and your wallet has multiple devices, you can create a transaction from one device and sign that transaction from any other device associated with the wallet.

However, remember that only one device in a wallet can sign a specific transaction. If multiple devices "race" to sign the same transaction, only one device will succeed, and the other devices' sign transaction command will eventually time out.

# Multiple device events

The `approveJoinWalletRequest` and `requestJoinExistingWallet` functions can yield the following events emitted by the events handler.

## Approving device

* PROVISION\_INITIATED
* PROVISION\_ADD\_DEVICE\_SETUP\_REQUESTED
* PROVISION\_KEYS\_SETUP\_STARTED
* PROVISION\_SETUP\_STARTED
* PROVISION\_SETUP\_COMPLETED
* STOPPED
* TIMEOUT

## Requesting device

* JOIN\_INITIATED
* ADD\_DEVICE\_SETUP\_REQUESTED
* PROVISIONER\_FOUND
* STOPPED
* TIMEOUT

# Troubleshooting

## Request timeout

There is a three-minute timeout before the Fireblocks and EW SDKs terminate the `requestJoinExistingWallet` and `approveJoinWalletRequest` functions. This means that you should guide the user to open the existing device to approve the action before they initiate this flow. However, you can call the `stopJoinWallet` function if you want or need to implement a different timeout configuration, or simply kill the process. Then, you can retry the process by calling the appropriate function again.

## Procedure didn't work

If a procedure with a `deviceId` did not work as expected, try to join the wallet with a new `deviceId`. There is no limit to the number of new devices an approving device can approve.

# Multiple devices FAQ

## What type of devices are supported?

The end user can add any combination of devices supported by our SDKs.

## How many devices can an end user add to a single wallet?

An end user can add up to 10 devices to a single wallet.

## How do I implement multiple devices for my app?

You can achieve this in various ways, depending on your implementation. Below you can view an example flow of a requesting device and an example flow of an approving device.

### Requesting device example

<img alt="" />

The end user enters the app on a new device after passing the authorization stage. The app recognizes that the user has a wallet with keys on another device and that the current device doesn't contain any keys. The app then presents the user with the following options:

1. Add a new device; if the user has another device, they can use it to onboard the new device.
2. Recover a device if the user does not have another device.
3. Skip, which continues to the app without creating a wallet.

### Approving device example

<img alt="" />

Depending on the guidance the user receives from the requesting device, they should typically open an approving device's Settings page and initiate the Add New Device flow.

## Is adding a device always tied to the device onboarding flow?

No. Adding a device can also be initiated anywhere within the app based on the app's objectives. For example, the Add New Device flow can be triggered when the user enters a specific part of the app, when they perform a specific action within the app, or initiated directly from the app's Settings page.


# Setup
Source: https://developers.fireblocks.com/docs/embedded-wallet-setup



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

<Warning>
  Fireblocks no longer supports the **Reactive Native SDK** and **Flutter SDK**.
</Warning>

# Web SDK Installation

Install the Fireblocks "EW SDK" and "EW Core SDK" using `npm`:

<CodeGroup>
  ```bash Shell theme={"system"}
  npm i @fireblocks/ncw-js-sdk
  npm i @fireblocks/embedded-wallet-sdk
  ```
</CodeGroup>

Or `yarn`:

<CodeGroup>
  ```bash Shell theme={"system"}
  yarn add @fireblocks/ncw-js-sdk
  yarn add @fireblocks/embedded-wallet-sdk
  ```
</CodeGroup>

You can find the web demo code [here](https://github.com/fireblocks/ncw-web-demo-v2).

# Android SDK Installation

First, add our maven repository configuration to your `settings.gradle` file:

<CodeGroup>
  ```groovy Gradle theme={"system"}
  repositories {
         maven {
              url "https://maven.fireblocks.io/android-sdk/maven"
              name = "android-sdk"
              credentials(HttpHeaderCredentials) {
                  name = "Deploy-Token"
                  value = "-fU8ijmuPohHaqDBgpaT"
              }
              authentication {
                  header(HttpHeaderAuthentication)
              }
          }
      }
  ```
</CodeGroup>

Then, add the Fireblocks SDKs dependency to your application's `build.gradle` file using the most updated bom version:

<CodeGroup>
  ```groovy Gradle theme={"system"}
  implementation "com.fireblocks.sdk:bom:1.0.2"
  implementation "com.fireblocks.sdk:ew"  
  implementation "com.fireblocks.sdk:ncw"
  ```
</CodeGroup>

* You can find the Android Demo code [here](https://github.com/fireblocks/android-ncw-demo).
* You can find the Android SDKs documentation [here](https://fireblocks.github.io/ncw-docs/android/).

# iOS SDK Installation

First, in your iOS Project, add the [Fireblocks Embedded Wallet SDK](https://github.com/fireblocks/ew-ios-sdk) package:

<img alt="" />

Now add the the [Fireblocks NCW iOS SDK](https://github.com/fireblocks/ncw-ios-sdk) package:

Then, after the SDK packages are added to the project, you should see them under the **Package Dependencies** section in the Project Navigator:

<img alt="" />

Lastly, import the SDK libraries:

<CodeGroup>
  ```swift Swift theme={"system"}
  import EmbeddedWalletSDK 
  import FireblocksSDK
  ```
</CodeGroup>

* You can find the iOS demo code [here](https://github.com/fireblocks/ncw-ios-demo).
* You can find the iOS SDKs Docs [here](https://fireblocks.github.io/ncw-docs/ios/).


# Using ECDSA and EdDSA
Source: https://developers.fireblocks.com/docs/embedded-wallet-using-ecdsa-and-eddsa



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

# Overview

Fireblocks workspaces support non-custodial wallets with two algorithms: `MPC_ECDSA_SECP256K1` (ECDSA) and `MPC_EDDSA_ED25519` (EdDSA).

Each algorithm allows the addition of different assets. For example, generating an ECDSA key set will let you add asset such as Bitcoin, or Ethereum, while generating an EdDSA key set will let you add Solana, or Algorand, for example.

A wallet can meet one of the following states:

* Generate ECDSA keys only.
* Generate EdDSA keys only.
* Generate ECDSA & EdDSA keys.
* Add EdDSA keys to an already existing ECDSA key set.
* Add ECDSA keys to an already existing EdDSA key set.

<Warning>
  ### Version Compatibility

  To fully utilize an expandable wallet with your preferred algorithms, ensure that you are using Web SDK version >=12.2.0 and Mobile SDK version >=2.6.0.
</Warning>

# Extending Your Key Set

<Warning>
  ### Post Extension Backup

  It is **crucial** to perform **another** backup after you have extended your key set. Please refer to the first point below, and make sure you follow the instructions there.
</Warning>

Should you face a situation where you already have an existing key set, you can generate another key set for the different algorithm, as shown in [MPC Key Generation](doc:mpc-key-generation).

Assuming you have generated an ECDSA key set, you should now trigger the key generation function with the EdDSA algorithm (`MPC_EDDSA_ED25519`) only.

In cases of extending your key set, you are required to make sure you have performed the same flows you have implemented for your already existing key set, that is:

1. Backup and Recovery, as seen [here](https://ncw-developers.fireblocks.com/docs/backup-recovery-1). Make sure you back up the new key set after generating the keys. By default, backup enforcement is enabled and you won't be able to add assets to your newly extended key set (e.g. Solana for EdDSA) until you have backed up your key set.
2. Multiple Devices, as seen [here](https://ncw-developers.fireblocks.com/docs/multiple-devices). In case there are multiple devices for the same wallet, and one of them has extended its key set, you are required to run the join wallet operation again, for your newly extended key set.

# Retrieving the Device Keys Status

The [MPC Keys Generation ](https://ncw-developers.fireblocks.com/docs/mpc-key-generation#key-generation)process is a multi-step operation that can fail or stop in the middle for various reasons, such as a network error or the end user leaving the application midway through the process. If a failure or stoppage occurs, you end up with a device and a `deviceId` that cannot be used until you complete the MPC key generation process.

To check the current key status for a device, there are two methods you can use:

1. Call the `getKeysStatus` function on the web SDK or mobile SDK. When `keyStatus` returns **READY**, the MPC key generation process has been completed. Note that **READY** is the only valid final status for the key.

2. Call the [Get device key setup state endpoint](/reference/getdevicesetupstate). This endpoint returns the device's current status and includes some additional response parameters:

   1. **SetupStatus:** Returns as **COMPLETE** or **INCOMPLETE** per key that started creation on the device.
   2. **Algorithm name:** Returns as `MPC_ECDSA_SECP256K1` or `MPC_EDDSA_ED25519`.
   3. **backedUp:** This boolean flag indicates whether the keys were [backed up ](https://ncw-developers.fireblocks.com/docs/backup-recovery-1)by any of the wallet's devices. Remember, a wallet can have [multiple devices](https://ncw-developers.fireblocks.com/docs/multiple-devices) associated with it.

Note that a device's status will only return as **COMPLETE** when all the keys declared in its workspace have reached the **COMPLETE** status and the device's backup flag is set to **true**.

# Retrieving the Wallet Key Status

You can also query a wallet's status by calling the [Get wallet key setup state endpoint](/reference/getwalletsetupstate). The response includes the current status of all devices associated with the wallet. Note that a wallet is considered **COMPLETE** as long as at least one of its devices also has the **COMPLETE** status.

If you send a request to an incomplete wallet or device, your request will fail and Fireblocks may return [error codes ](https://ncw-developers.fireblocks.com/docs/api-errors)to provide context for the request's failure.

# Removing Keys After Irrecoverable Loss

In **rare** cases, a wallet may become unusable if a new key set is added but **not backed up** before the device is lost. For example, if a wallet originally had *ECDSA* keys that were backed up, and *EdDSA* keys were later added but never backed up, losing the device now will leave the wallet in an incomplete state. This will cause most wallet operations to fail across all devices.

To resolve this and regain control of the backed-up *ECDSA* keys, you need to perform an administrative operation to explicitly remove the *EdDSA* algorithm from the wallet’s algorithm set. This is done using the Fireblocks SDK initialized with the EW Admin API user's private key:

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  const response = await fireblocksAdmin.deleteSigningAlgorithm(walletId, [SigningAlgorithm.MPC_EDDSA_ED25519])
  ```
</CodeGroup>

This will allow the wallet to operate again using the remaining *ECDSA* key set.

## Re-generating the Key Set

Once the wallet is operational again, you can re-generate a new *EdDSA* keys set from your client application, as mentioned in [MPC Key Generation](https://ncw-developers.fireblocks.com/docs/mpc-key-generation):

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  import { IKeyDescriptor } from "@fireblocks/ncw-js-sdk";

  // Generate MPC Keys
  const algorithms = new Set(["MPC_CMP_EDDSA_ED25519"]);
  const keyDescriptor: Set<IKeyDescriptor> = await ewCore.generateMPCKeys(algorithms);
  ```

  ```kotlin Kotlin theme={"system"}
  val algorithms = setOf(Algorithm.MPC_EDDSA_ED25519)
  fireblocksSdk.generateMPCKeys(algorithms = algorithms){ result ->
      Timber.i("generateMPCKeys result: $result")
  }
  ```

  ```swift Swift theme={"system"}
  func generateKeys(algorithms: Set<Algorithm>) async throws -> Set<KeyDescriptor> {
    //Initialize and create the Core SDK instance
    let instance = try getCore()
    return try await instance.generateMPCKeys(algorithms: algorithms)
  }
  ```
</CodeGroup>

**Note**: This example assumes the *ECDSA* keys were backed up and the *EdDSA* keys were lost. The same approach applies to any algorithm type.

<Info>
  ### Important Considerations

  1. This API only removes a signing algorithm. To add algorithms, see [Extending Your Key Set](doc:multiple-algorithms#extending-your-key-set).

  2. A signing algorithm cannot be removed if any of the following apply:

     1. Assets already exist under that algorithm.
     2. The public key was retrieved using `getPublicKey`.
     3. A takeover has been performed for the wallet.
</Info>


# Wallet
Source: https://developers.fireblocks.com/docs/embedded-wallet-wallet



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

# Overview

A wallet is an object you manage on Fireblocks' servers for your end-users. Wallets can have multiple keys (ECDSA and [EdDSA](https://ncw-developers.fireblocks.com/docs/multiple-algorithms)) and an unlimited number of wallet accounts. Each wallet account has a single asset type under it. For instance:

* `walletId-1`

  * `walletAccount-1`

    * `BTC`
    * `ETH`

  * `walletAccount-2`

    * `FTM`
    * `TRON`

In the new architecture wallet creation is done automatically (if needed) as part of the `assignWallet()` EW SDK method.

## Multiple wallets and wallet accounts

Theoretically, your end-user can have multiple wallets, but that does not matter in the Fireblocks view since Fireblocks does not hold any personally identifiable information (PII) about your end-users. However, for simplicity in our demos, we assume a one-to-one relationship between an end-user and a wallet.


# Web3 Wallet Link
Source: https://developers.fireblocks.com/docs/embedded-wallet-web3-wallet-link



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

# About the Fireblocks Web3 Wallet Link

As the demand for Web3 accessibility and usage grows, more users want to use dApps directly to manage their NFTs, get rewards, and more. The Fireblocks Web3 Wallet Link lets your users connect their Fireblocks Embedded Wallet addresses directly to Web3 applications without needing a wallet or any other application, offering your users one-stop shopping for anything related to crypto and Web3.

# Creating a Web3 connection

The Web3 Wallet Link currently supports WalletConnect connections. WalletConnect is a well-established standard for connecting wallets and Web3 applications and is supported by all of the leading dApps today.

When someone wants to connect to a dApp, they scan a QR code provided by WalletConnect inside the dApp. This QR code contains a URI representing the connection session to be established between the dApp and the wallet. Passing this URI onto Fireblocks using the API allows the connection to be successful.

# Examples

For Web3 Wallet Link code examples, follow [this guide](/docs/web3-wallet-link).


# Webhook Configuration
Source: https://developers.fireblocks.com/docs/embedded-wallet-webhook-configuration



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

<Info>
  ### Note

  This page focuses on setting up webhook notifications for the Fireblocks Non-Custodial Wallet (NCW). For more information about additional events sent by the Fireblocks webhook service, [visit our Developer Portal's API Reference](/reference/webhooks-notifications-1).
</Info>

# Overview

Multi-party computation (MPC) operations involve communication between several participants. This collaboration occurs over multiple rounds of communication, creating an asynchronous process.

To facilitate this communication, your system needs to expose the `POST /api/webhook` REST API endpoint to receive webhook notifications generated by Fireblocks. Each notification carries essential data to the Software Development Kit (SDK), which handles the asynchronous process.

In addition to managing these aspects, the Fireblocks webhook service also delivers notifications about events occurring within your workspace. This provides you with timely updates about relevant activities.

# Configuring Webhook URLs

To configure URLs for webhook notifications:

1. In the Fireblocks Console, go to **Settings** > **General**, then scroll down to the Configure Webhook URL heading and select **Manage URLs**.
2. On the Configure Webhook URL window, enter a URL to define the HTTPS endpoint, then press **Enter**. Each webhook URL must be a complete, globally available HTTPS address, such as [https://example.com](https://example.com).
3. Select **Save**.

Once your webhook is connected to your Fireblocks workspace, you will start receiving notifications for events in that workspace.

# Receiving Webhook Notifications

## Validation

You can validate Fireblocks webhook events by validating the signature attached in the request header:

**Fireblocks-Signature:** `Base64(RSA512(_WEBHOOK_PRIVATE_KEY_, SHA512(eventBody)))`

Copy this public key to validate the above signature in Sandbox workspaces:

```pem theme={"system"}
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw+fZuC+0vDYTf8fYnCN6
71iHg98lPHBmafmqZqb+TUexn9sH6qNIBZ5SgYFxFK6dYXIuJ5uoORzihREvZVZP
8DphdeKOMUrMr6b+Cchb2qS8qz8WS7xtyLU9GnBn6M5mWfjkjQr1jbilH15Zvcpz
ECC8aPUAy2EbHpnr10if2IHkIAWLYD+0khpCjpWtsfuX+LxqzlqQVW9xc6z7tshK
eCSEa6Oh8+ia7Zlu0b+2xmy2Arb6xGl+s+Rnof4lsq9tZS6f03huc+XVTmd6H2We
WxFMfGyDCX2akEg2aAvx7231/6S0vBFGiX0C+3GbXlieHDplLGoODHUt5hxbPJnK
IwIDAQAB
-----END PUBLIC KEY-----
```

## Response

The Fireblocks server will look for a response to confirm the webhook notification was received. All webhook events should receive an HTTP-200 (OK) response.

If no response is received, Fireblocks will resend the request several times. The retry schedule is 15, 45, 105, 225, 465, 945, 1905, 3825, 7665, and 15345 seconds.

# Code Examples

<Warning>
  ### Warning

  These examples are not production-ready and are used only for reference. Please follow our [security guidelines](/docs/secure-api-configuration) for secure API interaction.
</Warning>

<CodeGroup>
  ```javascript JavaScript theme={"system"}
  const crypto = require("crypto");
  const express = require("express");
  const bodyParser = require('body-parser')

  const port = 3000;

  const publicKey = `-----BEGIN PUBLIC KEY-----
  MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw+fZuC+0vDYTf8fYnCN6
  71iHg98lPHBmafmqZqb+TUexn9sH6qNIBZ5SgYFxFK6dYXIuJ5uoORzihREvZVZP
  8DphdeKOMUrMr6b+Cchb2qS8qz8WS7xtyLU9GnBn6M5mWfjkjQr1jbilH15Zvcpz
  ECC8aPUAy2EbHpnr10if2IHkIAWLYD+0khpCjpWtsfuX+LxqzlqQVW9xc6z7tshK
  eCSEa6Oh8+ia7Zlu0b+2xmy2Arb6xGl+s+Rnof4lsq9tZS6f03huc+XVTmd6H2We
  WxFMfGyDCX2akEg2aAvx7231/6S0vBFGiX0C+3GbXlieHDplLGoODHUt5hxbPJnK
  IwIDAQAB
  -----END PUBLIC KEY-----`.replace(/\\n/g, "\n");

  const app = express();

  app.use(bodyParser.json());

  app.post("/webhook", (req, res) => {
      const message = JSON.stringify(req.body);
      const signature = req.headers["fireblocks-signature"];

      const verifier = crypto.createVerify('RSA-SHA512');
      verifier.write(message);
      verifier.end();

      const isVerified = verifier.verify(publicKey, signature, "base64");
      console.log("Verified:", isVerified);

      res.send("ok");
  });

  app.listen(port, () => {
      console.log(`Webhook running at http://localhost:${port}`);
  });
  ```

  ```python Python theme={"system"}
  import falcon
  import json
  import rsa
  import base64

  FIREBLOCKS_PUBLIC_KEY = """
  -----BEGIN PUBLIC KEY-----
  MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw+fZuC+0vDYTf8fYnCN6
  71iHg98lPHBmafmqZqb+TUexn9sH6qNIBZ5SgYFxFK6dYXIuJ5uoORzihREvZVZP
  8DphdeKOMUrMr6b+Cchb2qS8qz8WS7xtyLU9GnBn6M5mWfjkjQr1jbilH15Zvcpz
  ECC8aPUAy2EbHpnr10if2IHkIAWLYD+0khpCjpWtsfuX+LxqzlqQVW9xc6z7tshK
  eCSEa6Oh8+ia7Zlu0b+2xmy2Arb6xGl+s+Rnof4lsq9tZS6f03huc+XVTmd6H2We
  WxFMfGyDCX2akEg2aAvx7231/6S0vBFGiX0C+3GbXlieHDplLGoODHUt5hxbPJnK
  IwIDAQAB
  -----END PUBLIC KEY-----
  """

  signature_pub_key = rsa.PublicKey.load_pkcs1_openssl_pem(FIREBLOCKS_PUBLIC_KEY)

  class RequestBodyMiddleware(object):
      def process_request(self, req, resp):
          req.body = req.bounded_stream.read()

  class AuthMiddleware(object):
      def process_request(self, req, resp):
          signature = req.get_header('Fireblocks-Signature')

          if signature is None:
              raise falcon.HTTPUnauthorized('Signature required')

          if not self._signature_is_valid(req.body, signature):
              raise falcon.HTTPUnauthorized('Invalid signature')

      def _signature_is_valid(self,  body, signature):
          try:
              hashing_alg = rsa.verify(body, base64.b64decode(signature), signature_pub_key)
              return hashing_alg == "SHA-512"
          except rsa.pkcs1.VerificationError:
              return False

  class DummyRequest(object):
      def on_post(self, req, resp):
          obj = json.loads(req.body.decode("utf-8"))
          print(obj)
          resp.status = falcon.HTTP_201

  # Create falcon app
  app = falcon.API(
      middleware=[
          RequestBodyMiddleware(),
          AuthMiddleware()
      ]
  )

  app.add_route('/webhook', DummyRequest())

  if __name__ == '__main__':
      from wsgiref import simple_server  # NOQA
      httpd = simple_server.make_server('127.0.0.1', 8000, app)
      httpd.serve_forever()
  ```
</CodeGroup>

# Immediate Webhooks

In order to send the transaction statuses in a chronological order, some transactions updates may be shortly delayed by a few seconds.

In order to deliver a great user experience, Fireblocks also provides the `NCW_TRANSACTION_STATUS_UPDATED` webhook type, which is being sent immediately, without any delays.

Although these may not be received in a chronological order, it will provide you with a notification that a transaction is `PENDING_SIGNATURE` immediately without any delays, allowing you to start the signing ceremony as soon as possible.


# Webhooks
Source: https://developers.fireblocks.com/docs/embedded-wallet-webhooks



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

## Transaction Created

A notification is sent when any new transaction is identified in the workspace.

| Parameter | Type                                                                     | Description                          |
| --------- | ------------------------------------------------------------------------ | ------------------------------------ |
| type      | string                                                                   | TRANSACTION\_CREATED                 |
| tenantId  | string                                                                   | The Fireblocks workspace's unique ID |
| timestamp | number                                                                   | Timestamp in milliseconds            |
| data      | [TransactionDetails](/reference/transaction-webhooks#transactiondetails) | All the transaction information      |

## Transaction Status Updated

A notification is sent when there is any change in a transaction's status or when the number of confirmations is updated.

| Parameter | Type                                                                     | Description                          |
| :-------- | :----------------------------------------------------------------------- | :----------------------------------- |
| type      | string                                                                   | TRANSACTION\_STATUS\_UPDATED         |
| tenantId  | string                                                                   | The Fireblocks workspace's unique ID |
| timestamp | number                                                                   | Timestamp in milliseconds            |
| data      | [TransactionDetails](/reference/transaction-webhooks#transactiondetails) | All the transaction informati        |

## NCW Transaction Status Updated (Immediate)

<Warning>
  ### In Early Access

  This webhook is currently part of an early access program. If you're interested in participating in the program, please [contact your Customer Success Manager](https://support.fireblocks.io/hc/en-us/requests/new?ticket_form_id=6947882197532) (requires a Help Center login).
</Warning>

In addition to the transaction status updates which are being sent in a chronological order (and not immediately), NCW transaction status updates are being sent right away. This is mainly to allow your backend to receive a notification that a transaction is pending signature as fast as possible.

**Note**: It will only be sent for outgoing transactions (withdrawals) with the following statuses:\
`PENDING_SIGNATURE`, `COMPLETED`, `CANCELLED`, `FAILED`, `BLOCKED`, `REJECTED`

| Parameter | Type                                                                     | Description                          |
| :-------- | :----------------------------------------------------------------------- | :----------------------------------- |
| type      | string                                                                   | NCW\_TRANSACTION\_STATUS\_UPDATED    |
| tenantId  | string                                                                   | The Fireblocks workspace's unique ID |
| timestamp | number                                                                   | Timestamp in milliseconds            |
| data      | [TransactionDetails](/reference/transaction-webhooks#transactiondetails) | All the transaction information      |

## Multi-Device Request ID

| Parameter      | type   | Description                                                               |
| :------------- | :----- | :------------------------------------------------------------------------ |
| type           | string | NCW\_ADD\_DEVICE\_SETUP\_REQUESTED                                        |
| tenantId       | string | The Fireblocks workspace's unique ID                                      |
| timestamp      | number | Timestamp in milliseconds                                                 |
| data.walletId  | string | The wallet's unique ID                                                    |
| data.deviceId  | string | The device's unique ID                                                    |
| data.requestId | string | The join wallet request's unique ID; is delegated to the approving device |

<Info>
  ### Note

  The structure of `data.fieldName` comes to describe a payload with values under a key data.
</Info>

## Non-Custodial Wallet Created

| Parameter     | type    | Description                             |
| :------------ | :------ | :-------------------------------------- |
| type          | string  | NCW\_CREATED                            |
| tenantId      | string  | The Fireblocks workspace's unique ID    |
| timestamp     | number  | Timestamp in milliseconds               |
| data.walletId | string  | The wallet's unique ID                  |
| data.enabled  | boolean | Indicates whether the wallet is enabled |

## Non-Custodial Wallet Account Created

| Parameter      | type   | Description                              |
| :------------- | :----- | :--------------------------------------- |
| type           | string | NCW\_ACCOUNT\_CREATED                    |
| tenantId       | string | The Fireblocks workspace's unique ID     |
| timestamp      | number | Timestamp in milliseconds                |
| data.walletId  | string | The wallet's unique ID                   |
| data.accountId | string | The account's ID in the specified wallet |

## Non-Custodial Wallet Asset Created

| Parameter      | type   | Description                                              |
| :------------- | :----- | :------------------------------------------------------- |
| type           | string | NCW\_ASSET\_CREATED                                      |
| tenantId       | string | The Fireblocks workspace's unique ID                     |
| timestamp      | number | Timestamp in milliseconds                                |
| data.walletId  | string | The wallet's unique ID                                   |
| data.accountId | string | The account's ID in the specified wallet                 |
| data.asset     | string | The asset's ID as defined in Fireblocks (BTC, ETH, etc.) |

## Non-Custodial Wallet Asset balance changed

<Warning>
  ### In Early Access

  This webhook is currently part of an early access program. If you're interested in participating in the program, please [contact your Customer Success Manager](https://support.fireblocks.io/hc/en-us/requests/new?ticket_form_id=6947882197532) (requires a Help Center login).
</Warning>

Notification is sent when an asset's balance changes.

| Parameter     | type                                                                                                   | Description                          |
| :------------ | :----------------------------------------------------------------------------------------------------- | :----------------------------------- |
| type          | string                                                                                                 | END\_USER\_WALLET\_BALANCE\_UPDATE   |
| tenantId      | string                                                                                                 | The Fireblocks workspace's unique ID |
| timestamp     | number                                                                                                 | Timestamp in milliseconds            |
| data.walletId | string                                                                                                 | The wallet's unique ID               |
| data          | [NcwAssetBalanceUpdate](https://ncw-developers.fireblocks.com/docs/data-objects#ncwassetbalanceupdate) | NCW asset details                    |


# Enable the Gas Station
Source: https://developers.fireblocks.com/docs/enabling-the-gas-station-1



<Info>
  ### Gas Station is only available to Pro and Enterprise customers

  Contact your Customer Success Manager for more information.
</Info>

## Gas Station 1.0

[Contact Fireblocks Support to enable the Gas Station in your workspace](https://support.fireblocks.io/hc/en-us/requests/new?ticket_form_id=360003372200). After they enable it, verify the following in your workspace:

1. On the Network page, you should have a new Network Connection named **Fireblocks Gas Station**.
2. On the Whitelisted Addresses page, you should have a new internal wallet called **Gas Station Wallet**. This internal wallet holds asset addresses reflecting EVM-based assets supported by the Gas Station that exist on each of the vaults on which you enable the Gas Station.

## Gas Station 2.0

The Fireblocks Gas Station 2.0 now offers a self-service auto-fueling solution. You can designate a single vault account in your workspace as the auto-fuel Gas Station, and activate the auto-fueling option on other vault accounts. This allows for a self-managed, self-custody Gas Station service and helps eliminate friction.

Learn more about the Fireblocks Gas Station 2.0 enablement [here](https://support.fireblocks.io/hc/en-us/articles/11602800877596-Setup-for-Gas-Station-2-0).


# EW SDK Event Collection
Source: https://developers.fireblocks.com/docs/ew-sdk-event-collection



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

# Overview

During day-to-day operations, end users are triggering countless actions within your application.

As part of your provided user experience, end users will generate keys, sign transactions and perform additional actions such as connecting their wallet to a dApp or export their private key material. Due to the complexity and variety of actions an end user may perform, different issues or errors may arise.

In order to proactively monitor and treat such problems that may appear, the EW SDK lets you toggle whether events and logs will be automatically sent to Fireblocks, through your backend.

Thus, Fireblocks may be able to proactively suggest and point onto issues or problems that your user base is facing, providing you with the ability to resolve it before any major impact.

It's important to note Fireblocks does not retrieve any PII regarding the end user. Please review the Shared Data section to validate the data that is shared with Fireblocks.

# Configuration

As part of the `FireblocksOptions` object, you will now have a new flag, `reporting`.

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  // First you need to initialize the NCW SDK with an implementation of the looger 
  const logger: IndexedDBLogger = await IndexedDBLoggerFactory({ deviceId, logger: ConsoleLoggerFactory() });

  const fireblocksNCW = await FireblocksNCWFactory({
            env: ENV_CONFIG.NCW_SDK_ENV,
            logLevel: "INFO",
            deviceId,
            messagesHandler,
            eventsHandler,
            secureStorageProvider,
            logger,
  		      reporting = { enabled: true },
          });

  // Number of logs collected
  const numberOfLogs = await logger.count();

  // Collect 10 logs 
  const logs = await logger.collect(10);

  // Clears the oldest 10 logs
  await logger.clear(10);
  ```

  ```swift Swift theme={"system"}
  var fireblocksOptions = FireblocksOptions(
    env: EnvironmentConstants.env,
    eventHandlerDelegate: self,
    logLevel: .info,
    logToConsole: true,
    reporting: ReportingOptions(enabled: true)
  )
  ```

  ```kotlin Kotlin theme={"system"}
  val fireblocksOptions = FireblocksOptions.Builder()
    .setLogLevel(getNCWLogLevel())
    .setLogToConsole(true)
    .setReportingOptions(ReportingOptions(enabled = false))
    .setEventHandler(object : FireblocksEventHandler {
                     override fun onEvent(event: Event) {
    // handle events
  }
  })
    .setEnv(environment)
      .build()
  ```
</CodeGroup>

**By default,`reporting` is enabled**. If you do not want to share telemetry logs with Fireblocks, just set `reporting` to false.

# Shared Data

When reporting on errors, the SDK will collect a few fields:

* type
* message
* code
* level
* method
* logs

All of these are fields that are related to the EW SDK itself, and **do not expose** any personal identifiable information (**PII**) regarding the end user.

In addition, the below items are the only metadata fields regarding the device that are transferred to Fireblocks:

* navigator\_appCodeName (e.g. Mozilla)
* navigator\_appName
* navigator\_language
* navigator\_platform
* navigator\_product
* navigator\_userAgent
* navigator\_vendor
* timezoneOffset

You may find an example payload here:

<CodeGroup>
  ```text Log theme={"system"}
  completedMPC:true
  device:iPhone14,3
  deviceId:b0550946-3d70-4e6b-949d-247549bd775f
  environment:dev9
  hasCMPKey:true
  iosVersion:16.4
  onboardedRecovery:false
  timezone:GMT+3
  uptime:timeval(tv_sec: 1716876653, tv_usec: 488161)
  ```

  ```text Log theme={"system"}
  VersionIncremental=S.17acc52_1-1, 
  completedMPC=false, 
  Uptime= 18h29m3.942s, 
  keyStatus=ERROR, 
  Device=OnePlus/OP516FL1/NE2213/NE2213, 
  SdkVersion=2.5.0_1, 
  keyId=0743117c-f737-4f38-b5bc-2c5a0cb17209, 
  AndroidVersion=34, 
  deviceId=3ac62b9b-5bb6-4756-96ef-85015ee5f345, 
  hasCMPKey=Yes, 
  environment=dev9, 
  TimeZone=GMT+03:00, 
  onboardedRecovery=null, 
  OSVersion=5.10.198-android12-9-o-g4b6fa3fb4a9f, 
  VersionRelease=14, 
  algorithm=MPC_EDDSA_ED25519
  ```
</CodeGroup>


# EW SDK Manual Log Retrieval
Source: https://developers.fireblocks.com/docs/ew-sdk-manual-log-retrieval



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

# Overview

If you experience issues during your application's development phase or with end users, you may need to retrieve EW SDK logs to troubleshoot those issues. To facilitate this, the EW SDK exposes methods that enable you to fetch logs. You can then send the collected logs to your designated servers.

* For our mobile SDKs, a designated interface guides you to a zipped file that you can retrieve from your end-user clients and then upload to your servers.
* The web SDK offers an interface that lets you write and fetch logs. Refer to the web demo for an example of writing logs to your browser's indexed database.

# Example

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  // First you need to initialize the NCW SDK with an implementation of the looger 
  const logger: IndexedDBLogger = await IndexedDBLoggerFactory({ deviceId, logger: ConsoleLoggerFactory() });

  const fireblocksNCW = await FireblocksNCWFactory({
            env: ENV_CONFIG.NCW_SDK_ENV,
            logLevel: "INFO",
            deviceId,
            messagesHandler,
            eventsHandler,
            secureStorageProvider,
            logger,
          });

  // Number of logs collected
  const numberOfLogs = await logger.count();

  // Collect 10 logs 
  const logs = await logger.collect(10);

  // Clears the oldest 10 logs
  await logger.clear(10);
  ```

  ```swift Swift theme={"system"}
  guard let url = FireblocksManager.shared.getSdkInstance()?.getURLForLogFiles() else {
              print("Can't get file log url")
              return
  }
  ```

  ```kotlin Kotlin theme={"system"}

  val sdkUri = Fireblocks.getUriForLogFiles(context)
  ```
</CodeGroup>

# Need help?

Contact Fireblocks Support and include your logs as an attachment.


# Execute Smart Transfers
Source: https://developers.fireblocks.com/docs/execute-smart-transfers



# Overview

As you can open a regular Smart Transfer ticket [via these API endpoints](/reference/createticket), an intermediary can open a Smart Transfer ticket for two third-parties only via our API as well, and follow its life cycle. In order for you, as an intermediary, to open such a ticket for your third-parties, all three of you need to be connected to each other with the same network profiles on the Fireblocks Network.

# Smart Transfer flow

To create Smart Transfer tickets an established network connection must exist. In the intermediary case, all sides (intermediary and counterparties settling the tickets) should be connected via the same Network Profile.

The flow of executing a Smart Transfer ticket consists of the following steps:

1. [Create a Smart Transfer ticket](/reference/createticket)
2. [Fund Smart Transfer ticket](/reference/fulfillticket)
3. [Cancel Smart Transfer ticket](/reference/cancelticket)

<Info>
  ### Check out the [Smart Transfers Developer Guide](/reference/execute-smart-transfers-1)  for more information
</Info>


# Fetching Transaction Receipt
Source: https://developers.fireblocks.com/docs/fetching-transaction-receipt

This guide outlines the procedure for retrieving a transaction receipt via the  endpoint, utilizing the  function in the Fireblocks SDK.

By employing the `getTransactionReceipt` function of the Fireblocks SDK, you can obtain the receipt of any transaction that has been confirmed by the blockchain. This function takes in the `baseAssetId` (indicating the blockchain) and the `txHash` (indicating the transaction hash). It manages the process of querying the blockchain and returning the transaction receipt.

<Info>
  ### Note:

  This functionality is exclusively available for EVM (Ethereum Virtual Machine) compatible chains.
</Info>

## Prerequisites

Before fetching a transaction receipt, ensure you have the following information:

1. **Base Asset ID**: The `baseAssetId` of the blockchain where the transaction was executed (e.g., ETH for Ethereum). This is the Fireblocks ID of the blockchain's gas token. (To obtain the asset ID, refer to this [assetId list](https://support.fireblocks.io/hc/en-us/articles/8993656344092-Supported-blockchain-networks)).
2. **Transaction Hash**: The `txHash` of the transaction for which you wish to fetch the receipt. This is the unique identifier of the transaction on the blockchain and is a hex string (i.e. prefixed with 0x). You can obtain the transaction hash from the transaction details or the blockchain explorer.

## Example: Fetching a Transaction Receipt

Below is an example of how to fetch a transaction receipt using the Fireblocks SDK:

### 1. Initialize the Fireblocks SDK

First, import the Fireblocks SDK and initialize it with your Fireblocks API key and private key:

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  import { Fireblocks, BasePath } from '@fireblocks/ts-sdk';

  const privateKey = '...'; // Your Fireblocks API private key
  const apiKey = '...'; // Your Fireblocks API key

  const fireblocksSdk = new Fireblocks({
  	apiKey,
  	basePath: BasePath.US, // Use BasePath.EU for the EU region
  	secretKey: privateKey,
  });
  ```
</CodeGroup>

### 2. Fetch the Transaction Receipt

To fetch the transaction receipt, utilize the `getTransactionReceipt` function of the Contract Interactions Controller:

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  const baseAssetId = 'ETH'; // The base asset ID for Ethereum
  const txHash = '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'; // The transaction hash

  const receipt = await fireblocks.getTransactionReceipt(baseAssetId, txHash);

  console.log(receipt);
  ```
</CodeGroup>

The response will be a transaction receipt object containing details about the transaction, such as the status, gas used, logs, and more.

<Info>
  ### Note:

  For further information about the transaction receipt object, refer to the [Endpoint Model](#endpoint-model) section.
</Info>

## Endpoint Model

### Transaction Receipt

The transaction receipt response object includes the following fields:

* `status`: The status of the transaction (e.g., success or failure).
* `gasUsed`: The amount of gas consumed by the transaction.
* `logs`: The logs generated by the transaction (if any).
* `transactionHash`: The hash of the transaction.
* `blockHash`: The hash of the block containing the transaction.
* `blockNumber`: The number of the block containing the transaction.
* `contractAddress`: The address of the contract created (if any).
* `cumulativeGasUsed`: The cumulative gas used by the transaction.
* `from`: The address of the sender.
* `to`: The address of the receiver.
* `effectiveGasPrice`: The actual price per unit of gas paid.
* `type`: The type of the transaction.
* `logs`: The logs generated by the transaction (if any).
* `logsBloom`: The bloom filter for the logs of the transaction.
* `transactionIndex`: The index of the transaction in the block.

<Info>
  ### Note:

  The `logs` field contains an array of log objects, each representing a log generated by the transaction. Each log object includes the following fields:

  * `address`: The address of the contract that generated the log.
  * `topics`: An array of topics associated with the log.
  * `data`: The data contained in the log.
  * `blockNumber`: The number of the block containing the log.
  * `transactionHash`: The hash of the transaction that generated the log.
  * `transactionIndex`: The index of the transaction in the block.
  * `blockHash`: The hash of the block containing the log.
  * `logIndex`: The index of the log in the block.
  * `removed`: Indicates whether the log was removed.
</Info>

<Info>
  ### Note:

  Some fields may be empty in the response if the transaction has not been executed or if the blockchain does not support them.
</Info>


# Fireblocks CLI
Source: https://developers.fireblocks.com/docs/fireblocks-cli

Execute any Fireblocks API operation from the command line.

# Overview

The Fireblocks CLI (`@fireblocks/fireblocks-cli`) is an agent-first command-line tool that exposes every Fireblocks API operation as a typed command. Commands are organized by API namespace (e.g. `vaults`, `transactions`, `embedded-wallets`) and use JWT-signed requests identical to the Fireblocks SDKs.

The CLI is built for:

* **Scripting and automation** — run API calls from shell scripts, CI pipelines, or cron jobs
* **Exploration** — inspect vault balances, transaction status, or workspace state without writing code
* **AI agent integration** — the `help-index` command returns a compact JSON index of all commands that fits in an LLM context window

## Features

* Every Fireblocks API endpoint as a typed command
* JWT-signed requests using the same signing approach as the TypeScript SDK
* Credential management — store profiles in `~/.config/fireblocks/config.json`
* `--dry-run` — preview any request before executing it
* `--debug` — log request and response details to stderr
* Write-operation confirmation prompts (skippable with `--no-confirm`)
* Structured JSON errors on stderr with distinct exit codes
* Shell autocomplete for Bash and Zsh

## Installation

The CLI is available as an npm package and requires Node.js 18 or later.

* **npm package**: `https://www.npmjs.com/package/@fireblocks/fireblocks-cli`
* **GitHub repo**: `https://github.com/fireblocks/fireblocks-cli`
* **GitHub release (latest)**: `https://github.com/fireblocks/fireblocks-cli/releases/latest`

### npm (recommended)

```bash theme={"system"}
npm install -g @fireblocks/fireblocks-cli
```

### Standalone installers (macOS, Windows, Linux)

Standalone installers for each OS are available in the GitHub Releases assets.

### Tarballs

Tarballs are also available in the GitHub Releases assets.

### Homebrew (macOS)

```bash theme={"system"}
brew tap fireblocks/fireblocks-cli
brew install fireblocks-cli
```

### Other package managers

```bash theme={"system"}
# yarn
yarn global add @fireblocks/fireblocks-cli

# pnpm
pnpm add -g @fireblocks/fireblocks-cli
```

The `fireblocks` command will be available immediately after installation.

## Verify Installation

```bash theme={"system"}
fireblocks --version
```

## Quick Start

```bash theme={"system"}
# 1. Set up credentials interactively
fireblocks configure

# 2. Verify credentials
fireblocks whoami

# 3. List vault accounts
fireblocks vaults get-paged-vault-accounts

# 4. Discover all available commands
fireblocks help-index
```

## Next Steps

* [Authentication](./cli-authentication) — configure credentials, environment variables, and profiles
* [Usage Guide](./cli-usage) — commands, flags, examples, and exit codes


# Google Cloud Confidential Space API Co-signer Architecture
Source: https://developers.fireblocks.com/docs/gcp-confidential-space-api-co-signer



<Info>
  ### Learn how to install GCP Confidential Space Co-signer in the [following guide](/reference/install-api-cosigner-gcp)
</Info>

## GCP Co-signer can only connect to one workspace at a time

Like other Co-signers, the Google Cloud Confidential Space Co-signer is installed and connected to the workspace through an API user. Once installation is complete, you can manage it via the Console or APIs to add additional API users, configure their Callback Handlers, etc.

Due to Google Cloud's Confidential Space container architecture, the Co-signer can only be commanded through Fireblocks' SaaS. As a result, it is restricted to a single workspace connected to the Co-signer. All operations must be performed within this workspace using the Console or APIs.

## Google Cloud resources used by the Co-signer

The Fireblocks GCP Confidential Space API Co-signer leverages Google's Confidential Space technology. It utilizes the following Google Cloud's resources:

* **Workload Container**: used to run the enclave.
* **Bucket**: used as the Co-signer's persistent storage and holds the encrypted database of the Co-signer.
* **KMS Customer Managed Key**: used to securely protect the Co-signer's MPC keyshares, which are stored in the Co-signer's persistent storage within a bucket.
* **IAM/WIP**: enables associating identities with Google Cloud's IAM roles to grant only essential permissions to specific resources in use.

<Warning>
  ### **Important**: Allocate a separate set of resources for each Co-signer to prevent conflicts and ensure isolation, enhancing security.

  The "project" can be common between different Co-signers.
</Warning>

This is illustrated in the block diagram below:

<img alt="" />

## Secure Co-signer database encryption scheme

The following process is implemented to build and secure the Co-signer's database:

1. The user creates and configures a symmetric Customer Managed Key (CMK) in the KMS.
2. The Co-signer, upon initialization, asks KMS to generate an additional AES 128-bit CBC key: `FBKS-DB-Key`
3. The Co-signer initializes its encrypted database using the key `FBKS-DB-KEY`
4. The Co-signer encrypts `FBKS-DB-KEY` using the CMK.
5. The Co-signer saves its encrypted database and the encrypted form of `FBKS-DB-KEY` in the GCS bucket, serving as its persistent storage.
6. Access to KMS, including the CMK, is restricted using a Fireblocks enclave image attestation signature and the IAM role and policies that were created by the user.

This is illustrated in the block diagram below:

<img alt="" />


# Create a CSR for an API user
Source: https://developers.fireblocks.com/docs/generate-a-csr-for-an-api-user



# What is a CSR?

A Certificate Signing Request (CSR) is a file that contains your public key and some identifying information. Fireblocks uses the CSR to generate your API user's public key, which Fireblocks then uses to verify and authenticate your API calls.

# Before you begin

Make sure you have the following:

* Access to a machine where you can run OpenSSL or similar tooling
* A secure location to store your private key

# Step 1: Create the private key & CSR files

## Using OpenSSL (recommended for most users)

Open your terminal or command line and run the following command to generate a private key and CSR:

<CodeGroup>
  ```bash Shell theme={"system"}
  openssl req -new -newkey rsa:4096 -nodes -keyout api_private.key -out api_user.csr
  ```
</CodeGroup>

### What this does

* Creates a private key file: **api\_private.key**
* Creates a CSR file: **api\_user.csr**

<Warning>
  ### Security reminder

  *Never* upload or share the **api\_private.key** file. Store it securely using a Key Management System (KMS), HSM, or encrypted file storage.
</Warning>

# Step 2: Fill in the CSR details

When prompted, complete the following fields:

| Field                    | Description                                                  |
| ------------------------ | ------------------------------------------------------------ |
| Common Name (CN)         | Your name or the API user's name (e.g., John\_the\_API\_Guy) |
| Organization (O)         | Your organization's name                                     |
| Organizational Unit (OU) | Optional field (e.g., API Team)                              |
| Country (C)              | Two-letter country code (e.g., US)                           |
| State (ST)               | Your state or province                                       |
| Locality (L)             | Your city                                                    |

# Step 3: Upload the CSR file

* In the Fireblocks Console, [follow these steps to create an API user](https://support.fireblocks.io/hc/en-us/articles/4407823826194-Adding-new-API-Users#h_01HHHT468Y7RFAP3E5DNJYHHZZ). Note that only Admin-level workspace users (Owner, Admin, and Non-Signing Admin) can create API users.
* Upload the **api\_user.csr** file in the **CSR File** field.

<Warning>
  ### Warning

  Do *not* upload your private key! Keep the **api\_private.key** file secure for signing API requests later.
</Warning>


# Getting Started
Source: https://developers.fireblocks.com/docs/getting-started-with-embedded-wallets



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

# Before you begin

Before starting your Fireblocks Embedded Wallet (EW) implementation, it’s important to distinguish between the SDKs involved:

* The **Fireblocks EW client SDKs** (also referred to as the **EW SDK** and the **EW Core SDK**).
* The **Fireblocks SDK**.

Each serves a different purpose:

* The **EW SDKs** consist of platform-specific SDKs used in your *client app implementation*
* The **Fireblocks SDK** can be used for administrative EW operations and is initialized with an API user's private key. It can be used with one of two roles: [EW Admin and EW Signer](https://ncw-developers.fireblocks.com/docs/api-communication).

## Embedded Wallet glossary

* **EW:** Embedded Wallet.
* **Customer:** A business entity using Fireblocks' services.
* **Backend:** Optional server-side logic operated by the customer. Not required in the current architecture. [Learn more about backend use cases](/docs/embedded-wallet-high-level-architecture).
* **End User:** Fireblocks customers' end-user (i.e., the consumer).
* **Device ID:** A logical identifier representing an entity that stores a user key share and can participate in MPC operations for a given wallet. There is a unique identifier per SDK instance.
* **Physical Device ID:** A logical identifier representing a single mobile or web device.
* **Passphrase:** An end-user passphrase created for backup encryption.
* **Master Key:** A unique master key used for key share derivation.
* **Key Share:** One-half of the master key. Key Share #1 is at Fireblocks servers, and Key Share #2 is on the client side.

# Minimum requirements

## Android

* 64-bit mobile device (usually devices with at least 6GB of RAM)
* Android API version 27 (Android 8.0.1)

### Distribution ABI filters

<Warning>
  ### Pay attention

  The SDK ABI Filter does not limit your app distribution to 64-bit. You must ensure that your app's `build.grade` file imposes this limitation. For additional information, refer to the [Android official guidelines](https://developer.android.com/ndk/guides/abis).
</Warning>

The SDK requires a minimum of 64-bit devices. The `build.gradle` file includes the following ABI Filters:

```groovy theme={"system"}
ndk {
  abiFilters 'arm64-v8a', 'x86_64'
}
```

## iOS

* iOS 14 or later

## Web

Fireblocks recommends using the latest versions of the following web browsers:

* Google Chrome (Web, iOS, Android)
* Safari
* Microsoft Edge
* Firefox (Web, Android)
* Opera
* Android Browser
* Opera Mobile
* Samsung Internet

# Step-by-step process

The process of implementing the Fireblocks Embedded Wallet (EW) involves the following step-by-step sequence:

1. Complete the onboarding process to establish and configure your workspace.
2. Ensure comprehensive disaster readiness by completing the setup process for the disaster recovery kit.
3. Create the EW Signer and EW Admin API users.
4. Configure the webhook URL to enable communication between your application and Fireblocks.
5. Verify that you have at least one Transaction Authorization Policy (TAP) rule to govern your EW transactions (relevant to the production environment and not sandbox).
6. Set up your OAuth (SSO) configuration using your chosen Identity Provider (IDP), which will be used to authenticate end users.
7. (Optional) Implement a webhook listener (e.g., for transaction updates) and notify end-user devices using push notifications or other relevant channels.
8. Construct your mobile or web application and integrate the EW Software Development Kit (SDK).
9. Enroll your users into the application.
10. Generate MPC keys for each user with an EW.
11. Execute a key share backup procedure for each user to guarantee access in case of contingencies.
12. If allowed, provide the option to initiate a full key takeover and enhance control over their assets.

## EW TAP rules for Production workspaces

If you're a [Fireblocks Sandbox](/docs/quickstart) user, your sandbox workspace's TAP automatically has a rule that allows any end-user wallet to transfer any amount to any destination.

However, if you're a new or existing Fireblocks customer using a production workspace, you must [create a TAP rule](https://support.fireblocks.io/hc/en-us/articles/10394124789020-Create-a-TAP-rule) that governs end-user wallet transactions. Use the Fireblocks Console's TAP Editor to edit this rule or create additional rules as necessary.

<img alt="" />

## Flow chart

The following flow chart shows the successful workflow of a non-custodial embedded wallet system.

<img alt="" />

<img alt="" />

<img alt="" />

# Setting up OAuth configuration (SSO)

To enable user authentication in Embedded Wallet (EW), configure your Identity Provider (IDP) using the OAuth setup in the Fireblocks Console.

Once configured, Fireblocks will generate an **OAuth Client ID**. This ID is used to initialize the EW SDK on the client side.

> ⚠️ Note
>
> The EW SDK does not validate the IDP tokens itself. Instead, this setup enables Fireblocks to verify the tokens attached to end-user requests, ensuring secure authentication for all subsequent operations.

## Prerequisites

* Access to your OAuth-compatible IDP.
* The **EW Signer** API user created in your Fireblocks workspace. For more details, see [API Roles](https://ncw-developers.fireblocks.com/docs/api-communication#api-roles).

## Supported Identity Providers (IDPs)

The following OAuth-compatible IDPs are supported for use with Fireblocks Embedded Wallets. Use the provided JWKS URI when configuring your OAuth setup.

| Identity Provider      | JWKS URI                                                                                    |
| ---------------------- | ------------------------------------------------------------------------------------------- |
| **Google**             | `https://www.googleapis.com/oauth2/v3/certs`                                                |
| **Firebase**           | `https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com` |
| **Microsoft Azure AD** | `https://login.microsoftonline.com/common/discovery/v2.0/keys`                              |
| **AWS Cognito**        | `https://cognito-idp.{REGION}.amazonaws.com/{USER_POOL_ID}/.well-known/jwks.json`           |
| **Salesforce**         | `https://login.salesforce.com/id/keys`                                                      |

## Required Configuration Fields

<img alt="" />

When setting up OAuth in the Console, you'll need to provide:

* **API User** – Select an API user with the "**EW Signer**" role.
* **JWKS URI** – The JWKS (JSON Web Key Set) endpoint from which Fireblocks retrieves your IDP’s public keys for token validation. see [Supported Identity Providers (IDPs)](https://ncw-developers.fireblocks.com/docs/setting-up-oauth-sso#supported-identity-providers-idps)
* **Issuer** – The expected `iss` claim in the token (must match your IDP’s value).
* **Audience** – The expected `aud` claim in the token (typically your OAuth client ID).
* **Custom wallet ID field name** *(optional)* – Specify the name of a custom claim in your IDP token (e.g., a Firebase [custom claim](https://firebase.google.com/docs/auth/admin/custom-claims)) that contains the wallet ID for the user. Then if presented in the token, Fireblocks will use this claim to override the default, deterministic wallet ID calculation for this user.

<Info>
  ### Usage in the SDK

  Once a configuration is added, the **OAuth Client ID** will appear in the Console.

  Use this ID when initializing the SDK.
</Info>

## User token generation in clients

For token generation and login UI, you are free to use your IDP's standard login flows and SDKs.

<Callout icon="🚧">
  Fireblocks no longer supports the **Reactive Native SDK** and **Flutter SDK**.
</Callout>

# SDK installation

## Web SDK Installation

Install the Fireblocks "EW SDK" and "EW Core SDK" using `npm`:

```bash Shell theme={"system"}
npm i @fireblocks/ncw-js-sdk
npm i @fireblocks/embedded-wallet-sdk
```

Or `yarn`:

```bash Shell theme={"system"}
yarn add @fireblocks/ncw-js-sdk
yarn add @fireblocks/embedded-wallet-sdk
```

You can find the web demo code [here](https://github.com/fireblocks/ncw-web-demo-v2).

## Android SDK Installation

First, add our maven repository configuration to your `settings.gradle` file:

```groovy Android theme={"system"}
repositories {
       maven {
            url "https://maven.fireblocks.io/android-sdk/maven"
            name = "android-sdk"
            credentials(HttpHeaderCredentials) {
                name = "Deploy-Token"
                value = "-fU8ijmuPohHaqDBgpaT"
            }
            authentication {
                header(HttpHeaderAuthentication)
            }
        }
    }
```

Then, add the Fireblocks SDKs dependency to your application's `build.gradle` file using the most updated bom version:

```groovy Android theme={"system"}
implementation "com.fireblocks.sdk:bom:1.0.2"
implementation "com.fireblocks.sdk:ew"  
implementation "com.fireblocks.sdk:ncw"
```

* You can find the Android Demo code [here](https://github.com/fireblocks/android-ncw-demo).
* You can find the Android SDKs documentation [here](https://fireblocks.github.io/ncw-docs/android/).

## iOS SDK Installation

First, in your iOS Project, add the [Fireblocks Embedded Wallet SDK](https://github.com/fireblocks/ew-ios-sdk) package:

<img alt="" />

Now add the [Fireblocks NCW iOS SDK](https://github.com/fireblocks/ncw-ios-sdk) package:

Then, after the SDK packages are added to the project, you should see them under the **Package Dependencies** section in the Project Navigator:

<img alt="" />

Lastly, import the SDK libraries:

```swift iOS theme={"system"}
import EmbeddedWalletSDK 
import FireblocksSDK
```

* You can find the iOS demo code [here](https://github.com/fireblocks/ncw-ios-demo).
* You can find the iOS SDKs Docs [here](https://fireblocks.github.io/ncw-docs/ios/).


# Integrate Fireblocks with Third-Party Service Providers
Source: https://developers.fireblocks.com/docs/integrate-fireblocks-with-third-party-service-providers



# Overview

Many organizations utilizing Fireblocks seek to integrate their workspace with third-party service providers such as accounting solutions, portfolio aggregation tools, trading platforms, and more. These providers can offer valuable insights, operational efficiencies, and additional functionality by integrating directly with a Fireblocks environment.

However, since Fireblocks might not have native integrations with all these services, it is crucial to follow best practices to ensure that assets and data remain secure while maximizing the integration's effectiveness.

This guide is structured into two main sections:

* **For Fireblocks Clients**: Provides step-by-step recommendations for securely integrating third-party service providers with your Fireblocks workspace, focusing on access control, API key management, and other security practices.
* **For Third-Party Service Providers**: Offers guidance on how to securely connect with a client’s Fireblocks environment, emphasizing API key management, efficient data synchronization, and ensuring the client’s security requirements are met.

By addressing the specific concerns of both clients and providers, this guide aims to facilitate a smooth and secure integration process that benefits both parties.

# Fireblocks Clients

## Best Practices for Integration

### 1. Limit Access Levels

Ensure third-party providers are granted **Viewer** or **Editor** roles only—never **Signer** or **Admin** access. This principle applies to both API-based and UI-based integrations. Providing limited access minimizes risk exposure to your Fireblocks environment.

### 2. Secure API Key Management

If a third-party provider requires API access, the provider should handle key generation securely:

* The provider should create their own RSA private key and a Certificate Signing Request (CSR). Only the CSR should be shared with you.
* **Never accept private keys over the internet**.

<Warning>
  ### Always ensure that the third-party provider generates their own RSA private key and shares only the Certificate Signing Request (CSR) with you. Never share your private key with the provider.
</Warning>

Refer to the [Fireblocks API Key Management Documentation](/docs/manage-api-keys) for details on secure key management.

### 3. Use Dedicated API Keys

Always generate a new API key specific to the third-party provider. Avoid reusing API keys from internal operations to mitigate risks and facilitate easier access management.

### 4. Whitelist Provider IP Addresses

To enhance security, whitelist the provider’s server IP addresses for the specific API key. This additional security measure helps ensure only authorized servers have access.

More information can be found in the [IP Whitelisting Documentation](/docs/whitelist-ips-for-api-keys).

### 5. Initial Data Synchronization

For the first data sync, it's best to manually share balance and address reports from the Fireblocks Console to avoid overloading the API and hitting rate limits.

### 6. Enable Webhook Notifications

To keep data synchronized without excessive API polling, enable webhooks to push real-time updates from Fireblocks to the provider.

Visit the [Webhook Configuration Guide](/reference/configure-webhook-urls) for setup instructions.

### 7. Signing Transactions

If transaction signing is required, do not grant signing privileges directly to third-party providers. Use the **Designated Signer** feature and define a **Policy**. This approach maintains security by requiring your approval before any transaction is signed by the provider.

# Third-Party Service Providers (Partners)

## Best Practices for Integration

### 1. Understand Access Roles

When integrating with a Fireblocks client, expect to receive **Viewer** or **Editor** access only. **Signer** and **Admin** roles are not granted to maintain the client's security. These roles should be sufficient for most integrations to view data and perform necessary actions. Learn more about Fireblocks user roles in the ["Manage Users](/docs/manage-users)" guide.

### 2. Secure API Key Management

As a provider, you are responsible for securely generating and managing API keys:

* Generate an RSA private key and CSR, sharing only the CSR with the Fireblocks client.
* **Never share private keys with clients or transmit them over the internet**.

Consult the [Fireblocks API Key Management Documentation](/docs/manage-api-keys) for specific details on managing API keys securely.

<Warning>
  ### Always generate the RSA private key yourself and share the Certificate Signing Request (CSR) with the client. Never request the client to provide their private key!
</Warning>

### 3. Request a Dedicated API Key

For every new client integration, request a separate API key. This practice allows clear separation of access per client and aids in efficient management and troubleshooting.

### 4. Provide IP Addresses for Whitelisting

To ensure your integration is secure, supply the client with your server's IP addresses for whitelisting. This step helps secure API communication and restricts access to trusted IPs.

### 5. Efficient Data Synchronization

To avoid overloading the client's Fireblocks API and ensure a smooth initial data sync, it's recommended to start with balance and address reports shared directly from the Fireblocks Console. Coordinate with the client for a safe and efficient data transfer process.

### 6. Use Webhook Notifications

Reduce the need for frequent API polling by configuring webhooks that allow real-time updates from the Fireblocks client. This setup improves efficiency and ensures up-to-date data synchronization.

Check the [Webhook Configuration Guide](/reference/configure-webhook-urls) for configuration steps.

### 7. Transaction Initiation Without Signing

If your integration requires initiating transactions, ask the client to configure your access according to their **Policies**. This will ensure that your API key can initiate transactions, but any signing or approval must be performed by the designated signer configured in the Policy. This designated signer should be the customer themselves!


# Integrating third-party AML providers
Source: https://developers.fireblocks.com/docs/integrating-third-party-aml-providers

Fireblocks offers direct integrations with AML providers Chainalysis and Elliptic. If you prefer to use a different provider, you can use the workflows below to integrate a third-party service into your workspace.

<Info>
  ### **Note**

  AML screening policies within Fireblocks, including our [Autofreeze](https://support.fireblocks.io/hc/en-us/articles/6878328090780-Autofreeze-assets-from-incoming-transactions) functionality, are only supported by our direct integrations. These policies will not apply to third-party providers.
</Info>

# Outgoing transactions

There are two methods for screening outgoing transactions: manual pre-screening and automated screening.

## Method 1: Manual pre-screening

You can manually send transaction details to your AML provider before sending the transaction to the blockchain. In this scenario, one of your users initiates the transaction and sends the details to your AML provider for screening.

Once you receive the screening results, you can either reject the transaction (if the risk profile is high) or accept it and send it to Fireblocks. You can also set up alerts to notify interested parties about the transaction.

<img alt="" />

## Method 2: Automated screening using the Callback Handler

You can automate third-party AML screening for outgoing transactions using:

* **Fireblocks API**: the endpoints used for initiating the transaction.
* **API Co-Signer**: a Fireblocks-provided component that automates transaction signing and must be installed on an Intel SGX-enabled server you provide.
* **Callback Handler**: an HTTPS server that receives the transaction details and automatically sends the details to your AML provider.

You must also develop a custom logic that determines whether to accept or reject transactions based on the AML screening result, as follows:

1. You initiate a transaction using the Fireblocks API.

2. The transaction goes through your [Policies](/docs/capabilities#transaction-authorization-policy-tap). If authorized, it is then sent to the co-signer gateway for signing.

3. The API Co-Signer (located in your secure environment) long-polls and fetches the transaction details from the co-signer gateway.

4. The API Co-Signer sends a request to the Callback Handler with the transaction details.

5. The Callback Handler sends the transaction details to your third-party AML provider for screening.

6. The AML provider responds with the screening result.

7. According to your custom logic, the Callback Handler accepts or rejects the transaction based on the screening result.

   * If the risk profile is high, the Callback Handler responds to the API Co-Signer with Reject. The API Co-Signer does not sign the transaction, and the transaction is canceled.
   * If the risk profile is acceptable, the Callback Handler responds to the API Co-Signer with Accept. The API Co-Signer signs the transaction and sends it back to the co-signer gateway for broadcasting to the blockchain.

<Info>
  ### **Note**

  The API Co-Signer expects a response within 30 seconds of sending the initial request. If the Callback Handler does not respond within 30 seconds, the transaction is not signed and is canceled.
</Info>

<img alt="" />

# Incoming transactions

For incoming transactions, you have two options for managing the compliance status of your transactions: automated screening or manual review.

<Warning>
  ### **Important**

  The automated and manual methods cannot be used together. You must choose one method for screening incoming transactions.
</Warning>

## Method 1: Automated Screening

You can use a custom workflow to send incoming transaction details to your AML provider for automated screening. To do this, you must [configure a webhook](/docs/webhooks-notifications) that notifies you when a new transaction is received. The webhook also contains the transaction's details, which you can then send to your AML provider.

Once you receive the screening results, you have two options:

1. You can [freeze](/reference/freezetransaction) the transaction if the risk profile is high. An Admin can later [unfreeze](/reference/unfreezetransaction) it.
2. You can do nothing if the risk profile is acceptable, and the funds remain immediately spendable within your wallet.

You can also set up alerts to notify interested parties about the transaction.

<img alt="" />

## Method 2: Manual Screening Verdict

<Info>
  ### **Note**

  This feature is currently available to a limited group of customers. To enable it, contact your [Fireblocks Customer Success Manager](https://support.fireblocks.io/hc/en-us/requests/new?ticket_form_id=6947882197532).
</Info>

The Manual Screening Verdict feature provides a simplified, manual process for managing the compliance status of incoming transactions. Instead of relying on automated screening, it gives you full control to manually review and decide on transactions using your own internal tools and procedures. How it works:

1. **Pending Screening State**: All incoming transactions are automatically flagged and placed in a `PENDING_SCREENING`state. In this state, the transaction is paused until your compliance team reviews it.

2. **Manual Review**: Your compliance team reviews the transaction using your internal procedures (e.g., AML checks or other risk controls).

3. **Submit a Verdict**: Once the review is complete, you submit your decision via the dedicated API endpoint: `POST /aml/verdict/manual`.

   1. **ACCEPT**: This releases the transaction from its pending state, allowing it to be processed.
   2. **REJECT**: This flags the transaction as rejected for AML reasons. Rejected transactions are automatically frozen in Fireblocks.

4. **Timeout**: If no verdict is provided within the timeout window (default: one hour), Fireblocks will automatically **REJECT** the transaction.

<Info>
  ### **Note**

  Manual Screening Verdict applies only to incoming transactions. Outgoing transactions bypass this workflow and are not affected.
</Info>


# Intel SGX Co-signer Architecture
Source: https://developers.fireblocks.com/docs/intel-sgx-api-co-signer



<Info>
  ### Learn how to install SGX Co-signer in Azure in the [following guide](/reference/install-api-cosigner-azure)
</Info>

## Resources used by the SGX Co-signer

The Fireblocks SGX Co-signer utilizes Intel's SGX enclave and attestation mechanisms. It can be deployed either in cloud service providers that support compatible SGX servers or on-premise using a bare-metal server. Also, an SGX driver must be loaded into the machine. This is the only resource that is required to install and operate the Co-signer on the host machine.

The Co-signer's database is encrypted and stored on the host machine's disk, serving as the Co-signer's persistent storage.

<Warning>
  ### **Important**: Allocate a separate machine for each Co-signer to prevent conflicts and ensure isolation, enhancing security.
</Warning>

This is illustrated in the block diagram below:

<img alt="" />

## Secure Co-signer database encryption scheme

The following process is implemented to build and secure the Co-signer's database:

1. The Co-signer, upon initialization, connects to the [Intel-SGX Remote Attestation server](https://www.intel.com/content/www/us/en/developer/tools/software-guard-extensions/attestation-services.html) that belongs to the Fireblocks SaaS and retrieves the key that encrypts its database: `FBKS-DB-Key`
2. The Co-signer initializes its encrypted database using the key `FBKS-DB-KEY`
3. The Co-signer encrypts `FBKS-DB-KEY` using the SGX hardware key of the host machine.
4. The Co-signer saves its encrypted database and the encrypted form of `FBKS-DB-KEY` in the host machine, serving as its persistent storage
5. The Co-signer cannot operate unless it is attested against Fireblocks' Remote Attestation server.

This is illustrated in the block diagram below:

<img alt="" />

## Installation artifacts

The SGX Co-signer is comprised of several components:

1. Installation script: This is the CLI interface for installing and managing the Co-signer. You can retrieve the installation script from the Console. The script includes the path to a Docker image registry for downloading the Co-signer Docker image. It supports downloading images of various versions, with default versions specified if none are explicitly provided. See the [SGX Co-signer version history](/reference/api-cosigner-versions-sgx) for details on the image version.
2. Docker image: The Co-Signer's executable is wrapped in a Docker image to provide safe, versioned, and consistent installation across different platforms. The Docker image provides all the libraries and dependencies of the main executable.
3. Main loading executable: A slim binary that downloads and verifies the enclave and exposes command line interfaces.
4. Secure SGX enclave: This component contains most of the Co-Signer's code and logic. It is both encrypted and signed by Fireblocks, and it can be downloaded from the Fireblocks server during setup.

* **Q: Should I verify the executable's signature?**\
  If you are using the correct Docker image, as specified by the script, there is no need for any other verification, as it is embedded in the image.
* **Q: Why is the enclave encrypted?**\
  SGX allows for saving the enclave encrypted on disk with a hardware key only available to the specific CPU where the enclave would be executed. Secured enclaves prevent the risk of modification, make it impossible to reverse engineer, and hide any potential secrets embedded within them. This enclave alone is capable of reading the secrets stored by the Co-Signer.
* **Q: Should I verify the enclave's signature?**\
  There is no need for that. The Fireblocks signing key is embedded within the loading executable, which verifies the enclave's signature whenever it is loaded.
* **Q: Where do I find the enclave in the docker image?**\
  The enclave is only downloaded when the Co-signer goes through a setup or upgrade process, so it is omitted from the Docker image. The name of the file is `enclave.signed.so`.

The chain of trust follows the sequence: **script > image > executable > enclave**, with Fireblocks ensuring compatibility between these components. During setup or upgrade, the Co-signer downloads the latest enclave version from Fireblocks servers, which is guaranteed to be compatible with the installed executable. To ensure the enclave uses the latest published version, always use the most recent Co-signer Docker image. The safest approach is to install the Co-signer using the latest installation script.


# Interact With Smart Contracts
Source: https://developers.fireblocks.com/docs/interact-with-smart-contracts



## Interaction with Smart Contracts

Interacting with a smart contract involves calling read or write methods on a specific contract. These functions can range from simple standard ERC-20 methods to complex smart contract logic invocations. Fireblocks offers several ways to interact with smart contracts:

1. **Interact with a Deployed Smart Contract via the Fireblocks Console** - Learn more [here](https://support.fireblocks.io/hc/en-us/articles/12265198149660-Managing-smart-contracts-for-tokenization).
2. **Use the Fireblocks EVM Web3 Provider or Local JSON RPC Tools**.
3. **Use the Fireblocks REST API**.

## Using the Web3 Provider and Local JSON RPC Tools

These tools allow you to seamlessly integrate Fireblocks into your codebase.

### EVM Web3 Provider

The EVM Web3 Provider is an EIP1193 compatible provider that can be integrated into your EVM client library (such as ethers, web3, viem) with a simple configuration.

<Info>
  ### Learn more about the Web3 Provider in the [following developer guide](/reference/evm-web3-provider).
</Info>

### Local JSON RPC

Local JSON RPC provides the same functionality as the Web3 provider but is designed for customers who do not use JavaScript-based tools for their smart contract development and integration.

<Info>
  ### Learn more about the Local JSON RPC in the [following developer guide](/reference/evm-local-json-rpc).
</Info>

## Using the Fireblocks REST API

Direct interaction with smart contracts via the Fireblocks API can be achieved by calling the Create Transaction API endpoint. To perform a contract call, set the `operation` parameter to `CONTRACT_CALL` and include the `contractCallData` parameter in the `extraParams` object of the POST request body.

The `contractCallData` value should be the hex-encoded data you want to pass to the contract. This can be structured using well-known libraries such as web3.js, ethers.js, or similar.

<Info>
  ### Check out the [Create Transactions Developer Guide](/reference/create-transactions#contract-call-transaction).
</Info>

# Approve Amount Cap

In the ERC20 standard, the `approve` operation is a crucial function that allows a token owner to authorize another address (usually a smart contract) to spend a specified amount of tokens on their behalf. This function is commonly used in DeFi applications, token swaps, and other scenarios where tokens need to be managed by smart contracts.

### How It Works

When you call the `approve` function, you specify two parameters:

* **spender**: The address that will be allowed to spend the tokens.
* **amount**: The maximum number of tokens that the `spender` is allowed to spend.

The `approve` function updates the allowance, which is the amount of tokens that the `spender` can use. This is recorded in the token contract’s internal mapping.

### Example Use Case

Suppose you want to use a DeFi platform to lend your tokens. You would first call the `approve` function to allow the platform’s smart contract to transfer tokens from your address. Once approved, the platform can transfer the specified amount of tokens from your address to the lending pool.

The **Amount Cap** limits the amount smart contracts and third-party dApps may withdraw on your behalf. This reduces the risk associated with granting an unlimited approval amount. Transaction amounts are then automatically changed from the maximum amount to the user-specified limit for all Approve transactions created with dApps.

Learn more about limiting the [Amount Cap for Approve transactions](https://support.fireblocks.io/hc/en-us/articles/4404616097426-Amount-Cap-for-Approve-transactions)  via the Fireblocks Console.


# Interact with TRUST
Source: https://developers.fireblocks.com/docs/interact-with-trust

The  platform can be used to securely send information required by the Travel Rule.

To interact with TRUST from your Fireblocks workspace, you must use an appropriate format of Typed Message Signing when publishing a proof of address on the TRUST internal bulletin. This signing method is safer than (and preferred over) Raw Signing because it helps mitigate the risk of users signing a valid but malicious transaction.

<Info>
  ### Learn more about [Typed Message Signing](/docs/typed-message-signing-1#what-are-the-use-cases-for-typed-message-signing)
</Info>


# Fireblocks Developer Docs
Source: https://developers.fireblocks.com/docs/introduction



Welcome to the Fireblocks Developer Portal. Whether you're building a crypto exchange, a DeFi application, or an embedded wallet experience, you'll find everything you need to integrate Fireblocks into your product.

<CardGroup>
  <Card title="Getting Started" icon="rocket" href="/docs/quickstart">
    Connect your AI agent, set up your API key, and make your first call with the SDK or CLI.
  </Card>

  <Card title="API Reference" icon="code" href="/reference/api-overview">
    Explore all Fireblocks REST API endpoints with interactive examples and code snippets.
  </Card>

  <Card title="What Is Fireblocks?" icon="shield-check" href="/docs/what-is-fireblocks">
    Understand the platform architecture, security model, and core concepts.
  </Card>

  <Card title="SDKs & Dev Tools" icon="wrench" href="/reference/typescript-sdk">
    Official SDKs for TypeScript, Python, and Java, Fireblocks CLI plus Postman collections and dev tooling.
  </Card>
</CardGroup>

## Explore by Use Case

Choose the integration pattern that matches what you're building.

<CardGroup>
  <Card title="Wallet as a Service" icon="wallet" href="/docs/wallet-as-a-service">
    Embed non-custodial wallets into your application with Fireblocks MPC technology.
  </Card>

  <Card title="Treasury Management" icon="building-columns" href="/docs/treasury-management">
    Manage institutional digital asset operations across exchanges, DeFi, and staking.
  </Card>

  <Card title="Tokenization" icon="coins" href="/docs/tokenization">
    Issue, manage, and distribute digital tokens using smart contract templates.
  </Card>

  <Card title="Self-Custody Infrastructure" icon="lock" href="/docs/self-custody-infrastructure">
    Build self-custody solutions with enterprise-grade MPC key management.
  </Card>
</CardGroup>

## Platform Overview

Fireblocks provides a unified platform for building on blockchain with enterprise-grade security.

## Key Capabilities

<CardGroup>
  <Card title="Vault Accounts" icon="vault" href="/docs/overview">
    Create and manage direct custody wallets for secure asset storage.
  </Card>

  <Card title="Transactions" icon="arrow-right-arrow-left" href="/reference/create-transactions">
    Transfer, swap, and manage digital assets across blockchains.
  </Card>

  <Card title="Webhooks" icon="bell" href="/reference/webhooks-overview">
    React to real-time events like deposits, withdrawals, and status changes.
  </Card>

  <Card title="Smart Contracts" icon="file-contract" href="/docs/interact-with-smart-contracts">
    Deploy and interact with smart contracts across EVM and non-EVM chains.
  </Card>

  <Card title="Staking" icon="layer-group" href="/docs/stake-assets">
    Stake assets and manage validator operations programmatically.
  </Card>

  <Card title="Compliance" icon="scale-balanced" href="/docs/define-aml-policies">
    Integrate AML screening and travel rule compliance into your workflows.
  </Card>
</CardGroup>

## Start Building

<Steps>
  <Step title="Connect your AI agent">
    Install the [Fireblocks Documentation MCP](/docs/quickstart) first so Cursor, Claude Code, Codex, or any other agent can read these docs while you build — and so your implementation stays grounded in the canonical documentation even when you're not using an agent.
  </Step>

  <Step title="Get a Sandbox Account">
    [Sign up for a free Fireblocks sandbox](https://www.fireblocks.com/developer-sandbox-sign-up) to get API access and test credentials.
  </Step>

  <Step title="Set Up Authentication">
    [Generate a CSR and API key](/docs/manage-api-keys) to authenticate your API requests using JWT signing.
  </Step>

  <Step title="Choose your track">
    Install an [SDK](/reference/typescript-sdk) for application code, or the [Fireblocks CLI](/docs/fireblocks-cli) for fast workspace operations and agent workflows. [Getting Started](/docs/quickstart) covers both.
  </Step>

  <Step title="Follow a Guide">
    Walk through our guides to [create wallets](/reference/create-vault-account), [send transactions](/reference/create-transactions), or [set up webhooks](/reference/webhooks-overview).
  </Step>
</Steps>


# Tokenize Assets
Source: https://developers.fireblocks.com/docs/issue-new-tokens



# Overview

Tokenization is the representation of an asset, which could be a real-world physical asset or a digitally native one, on a distributed ledger. Tokens represent ownership, control, claim, or a right to the underlying asset or service. With Fireblocks, you can issue and manage tokens for your specific use case, such as stablecoins, carbon credits, in-game assets, concert tickets, real estate, memorabilia, artwork, NFTs, or any other asset you want to tokenize.

# Tokenization in Fireblocks

<Info>
  ### Tokenization is a premium feature that requires an additional purchase. If you don’t have access to this feature, contact your Customer Success Manager to discuss having it enabled in your Fireblocks workspace.
</Info>

The Tokenization feature allows you to deploy and manage tokenized assets and their lifecycle via the Fireblocks Console or the Fireblocks API.

## Supported assets and blockchains

Fireblocks supports token issuance and management for the following networks and assets:

* All EVM-compatible blockchains supported by Fireblocks
* Stellar
* Ripple

## Token lifecycle management

Generally, a token's lifecycle involves:

1. Issuing new tokens or linking previously issued tokens.
2. Viewing token information on the Tokenization page.
3. Executing operations (minting, distributing, burning, etc.).

You can manage the tokens in your workspace using:

### The Fireblocks Console

<Info>
  ### Learn more about Tokenization in the Fireblocks Console [here](https://support.fireblocks.io/hc/en-us/articles/8760035076892-Tokenization-Page)
</Info>

* EVM blockchains: You can call any smart contract function, such as minting and burning, for your EVM-based tokens on the Tokenization page.
* Stellar and Ripple: You can issue, mint, burn, and transfer tokens on the Tokenization page. You can also create wallets with automatically established trustlines (an explicit opt-in to hold the token).
* All supported assets: You can link tokens on the Tokenization page, where you can view detailed information about each of them.

### The Fireblocks API

* EVM blockchains: You can mint, burn, and transfer tokens using specific API operations. For all other operations, you can use contract calls.
* Stellar and Ripple: You can issue, mint, burn, and transfer tokens. You can also create wallets with automatically established trustlines.

<Info>
  ### Explore the [Tokenization APIs](/reference/issuenewtoken)  in the Fireblocks API Reference
</Info>


# Overview
Source: https://developers.fireblocks.com/docs/list-supported-assets-1

Fireblocks supports thousands of assets across dozens of blockchain networks and frequently adds support for new assets. All supported assets share the same name and asset ID across every customer workspace where they are available.

To see all assets supported in your workspace, use the Fireblocks API as described in [List assets](/reference/listassets).

## Globally supported assets

Globally supported assets are available by default when you create new asset wallets in any workspace. Fireblocks publishes a complete [list of globally supported assets](https://support.fireblocks.io/hc/en-us/articles/6641409557532-Globally-supported-assets), which Fireblocks refreshes monthly.

## Locally supported assets

Locally supported assets only appear in workspaces that have manually added or requested them. They are available to transfer to any destination that supports them.

Before transferring a local asset to a Fireblocks Network destination, confirm that the counterparty supports it. For more information, see the following Help Center articles:

* [Adding EVM assets to a workspace](https://support.fireblocks.io/hc/en-us/articles/5601259928220-Adding-EVM-assets-to-a-workspace)
* [Adding non-EVM assets to a workspace](https://support.fireblocks.io/hc/en-us/articles/6641659764508-Adding-non-EVM-assets-to-a-workspace)


# Main Capabilities
Source: https://developers.fireblocks.com/docs/main-capabilities



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

## 2-of-2 MPC signature scheme

The Fireblocks Embedded Wallet (EW) feature uses a 2-of-2 multi-party computation (MPC) signature scheme to enhance the security of digital signatures. This cryptographic technique involves two parties collaborating to generate a signature. This reduces the risk of single-party compromise and enhances the overall integrity of transactions.

One key share resides on the end-user's device (mobile or web), and the second key share is securely maintained within an Intel SGX-enabled server managed by Fireblocks.

Intel SGX technology ensures that the key material stored in the SGX enclave is isolated, protected, and resistant to unauthorized access.

<img alt="" />

<Info>
  ### End-user key share management

  Fireblocks provides web and mobile SDKs to customize how you configure your key loading and key saving process. This enables you to implement security measures, such as mobile enclave, biometric authentication, two-factor authentication (2FA), and more.

  The SDK itself is agnostic to the specific implementation of key storage, which is passed to it upon initialization.
</Info>

## Web and mobile integrations

Fireblocks provides comprehensive software development kits (SDKs) for iOS, Android, and web platforms. These SDKs allow developers to seamlessly integrate Fireblocks cryptographic and security functions into their applications.

## Multi-device support

The Fireblocks Embedded Wallet (EW) solution allows multiple devices to perform actions using the same wallet, such as signing transactions and running takeovers. This lets you support a multi-device, multi-platform seamless digital experience and enables an end user to use their account on any of their devices.

## Backup and recovery

We also offer a variety of options for securely backing up and recovering cryptographic assets. Users can choose to store backups in the cloud, employ social logins for recovery purposes, or opt to download backups locally.

## User Takeover Ability (Export Private Key)

Our User Takeover Ability enables users to export their full cryptographic keys, providing them with the autonomy to move their assets to different wallets or services. This feature emphasizes user control while requiring careful consideration of potential security implications.

## Transaction Authorization Policy

With our [Transaction Authorization Policy (TAP)](https://support.fireblocks.io/hc/en-us/articles/7354983580316), users can define and enforce specific transaction approval rules. These rules can include requirements for predetermined approval workflows, transaction limits, and more. This feature empowers users to customize transaction security based on their unique preferences and risk tolerance.

## Web3 Wallet Link

Our Web3 Wallet Link feature facilitates interaction between decentralized applications (dApps) and various wallets using the WalletConnect v2 protocol. This allows users to securely access and manage their cryptocurrency assets across different platforms and services.

## Supported Networks

### Bitcoin, EVM-based networks, Cosmos, and TRON (private and public)

The Fireblocks EW solution supports many blockchain networks, such as the Bitcoin blockchain and various networks based on the Ethereum Virtual Machine (EVM), Cosmos, and TRON. Users can securely interact with and manage their Bitcoin and EVM-based assets using our platform.

Currently, Fireblocks provides support for more than 30 EVM-based public blockchains, including several well-known ones such as Polygon, Base, BNB Smart Chain, Evmos, Moonriver, Optimism, Arbitrum One, Moonbeam, and many more. Additionally, the Fireblocks EW provides instant support for any EVM-based blockchain that becomes integrated with the Fireblocks platform. This includes private and public networks that are within our supported ecosystem.

### ERC-20, ERC-1155, and ERC-721 Tokens

The Fireblocks EW extends its support to Ethereum's token standards, namely ERC-20, ERC-1155, and ERC-721. This allows users to manage a wide array of digital assets, including fungible tokens (ERC-20), semi-fungible tokens (ERC-1155), and non-fungible tokens (ERC-721) through our platform.

Whether you're dealing with Bitcoin or participating in various EVM-based ecosystems, the Fireblocks EW allows you to seamlessly integrate and securely manage assets. Additionally, our support for Ethereum's token standards allows you to handle a wide range of tokens.


# Manage API Access
Source: https://developers.fireblocks.com/docs/manage-api-keys



# API Authentication

The Fireblocks API uses an API key and a request-signing process to provide a highly secure communication protocol. You can create API keys through the Fireblocks Console or the API.

## Create an API key in the Console

To create your first API key:

1. Generate an RSA 4096 private key and CSR file:
   <CodeGroup>
     ```bash Shell theme={"system"}
     openssl req -new -newkey rsa:4096 -nodes -keyout fireblocks_secret.key -out fireblocks.csr -subj '/O=<your_organization>'
     ```
   </CodeGroup>

2. In the Fireblocks Console, go to the [Developer center's API users page](https://console.fireblocks.io/v2/developer/api-users).

3. Select **Add API user**.

4. Enter a display name for the API key (up to 30 characters) and select the appropriate role. Permissions follow the same [user roles](/docs/manage-users) used for Console users.

5. Upload the CSR file you generated in step 1.

6. Select whether a Co-signer setup is required.

   1. If you're in a testnet workspace, you can connect to the [Fireblocks Communal Test Co-signer](/reference/use-communal-cosigner).
   2. Only select **First user on this machine** if you're using the API user to install a new SGX Co-signer.

7. Select **Add user**.

After the required approval quorum is reached, the API key appears in the API users list. You can copy the API key from there by hovering your pointer over the value in the **API User (ID)** column.

Every request using this API key must follow the [Fireblocks API authentication scheme](/reference/signing-a-request-jwt-structure).

## Create an API key via the Fireblocks API

Complete step 1 from the Console procedure above to generate your RSA key and CSR file, then call the [Create API Key](/reference/createapiuser) endpoint to complete the API key creation operation.

# API key management best practices

Your API credentials are a prime target for attackers. Fireblocks recommends following these best practices to work securely with our APIs.

## Role-based access control

Provision each API user's role according to the principle of least privilege. Fireblocks supports multiple roles for role-based access control, and an API user can hold any one of them. Create separate API users to enforce duty separation and establish clear security boundaries.

<Tip>
  ### Best practice

  Create at least two API users with distinct roles. For example, a Viewer role for read-only operations and a Signer role with transaction-signing capabilities.
</Tip>

## Policy rules for API users

API users with transaction initiation and signing capabilities can execute transactions like any Console user. Create strong Policy rules to govern what transaction types these API users can conduct and from which accounts.

<Tip>
  ### Best practice

  Limit API users to transact from a specific vault account and up to a defined amount. This blocks or flags transactions that exceed the pre-defined limits or originate from unauthorized accounts.
</Tip>

## IP address allowlisting

Each API user can restrict API calls to specific IP addresses. If no IP addresses are allowlisted, the API accepts requests from any address. Explicitly allowlist only the IP addresses you expect to call the Fireblocks API.

<Warning>
  ### Address format

  Only /32 IP addresses are accepted. Do not enter addresses as a range of values.
</Warning>

## Generating and storing RSA 4096 private keys

Each API user requires a public/private key pair to sign requests. Keep your `fireblocks_secret.key` file safe and secure at all times.

To protect your key pair:

* Generate a unique CSR file and key pair for each API user. This limits the blast radius if one user's keys are compromised.
* Generate the CSR file and key pair in an offline (air-gapped) environment for added security.
* Store `fireblocks_secret.key` in a hardened environment with advanced security controls such as multi-factor authentication and endpoint protection.

## Storing API keys outside your codebase

Never embed API keys directly in code or commit them to your source tree. Keys embedded in code can be accidentally exposed, especially if you use a public source control system such as GitHub. Instead, store API keys in environment variables or in files outside your application's source tree.

## Rotating secrets

Rotation works differently depending on the API user type:

* **Fireblocks API users:** Because authentication relies on a CSR and associated secret key, create a new API user to rotate credentials.
* **Co-signers:** Re-enroll the API user to obtain a new pairing token, then complete the pairing process to receive a new refresh token.
* **Fireblocks Agent for KeyLink:** Uses the pairing token, access token, and device. This user type does not hold MPC keys.

<Tip>
  ### Best practice

  Before rotating, use the [Get all API keys](/reference/getapikeys) endpoint to list all API keys paired to a specific API Co-Signer.
</Tip>


# Manage Deposits at Scale
Source: https://developers.fireblocks.com/docs/manage-deposits-at-scale



## Overview

One of the most important processes for a business is the ability to handle deposits made by clients. To facilitate this, each client needs their own wallet for the asset they want to deposit.

This requirement applies to both scenarios: deposits made by clients from external sources and on-ramp processes such as purchasing crypto and storing it in their address. Both flows result in the creation of a new wallet for the specific user.

Businesses serving hundreds of thousands or even millions of users need to create and manage these addresses and the deposited funds in the most operationally and cost-effective ways.

In this guide, we will outline the recommended workflows for Fireblocks clients to achieve an efficient setup for processing user deposits. The topics covered include:

* Setting up the correct wallet structure for your use case
* Receiving notifications on incoming transfers
* Processing UTXO and Tag/Memo-based asset deposits
* Processing account-based asset deposits
* Best practices for generating deposit addresses
* Validating wallet balances
* Maintaining an internal ledger

## Setup the Wallet Structure

The wallet structure, or as we call it in Fireblocks, the vault structure, that you set up will directly impact the capabilities, efficiency, and operational load of your business. Fireblocks recommends one of the following two setups, depending on the type of your operation:

* **Segregated Vault Structure**: Ideal for customers running a B2B business. This setup is recommended for those who want full segregation of their clients' funds.
* **Omnibus Vault Structure**: Ideal for customers running a B2C business. This setup is recommended for those who want to create a dedicated wallet for each user and then sweep the funds into a single Treasury wallet.

<Info>
  ### Learn more about the Fireblocks [Vault Structure types](/docs/create-direct-custody-wallets#types-of-vault-structures)
</Info>

## Get Notifications for Incoming Transactions

To receive notifications about incoming transactions to your Fireblocks wallets, we recommend using the Webhook service.

Webhooks are push notifications sent by Fireblocks to a URL specified by the customer. This service sends notifications about various events in your Workspace, including incoming funds. Each incoming transaction triggers a series of events, starting with an alert that a new transaction has been identified, followed by subsequent notifications about the transaction's completion status.

<Info>
  ### Learn more about the Fireblocks [Webhook service](/reference/configure-webhook-urls)
</Info>

## Process UTXO and Tag/Memo Based Assets Deposits

Customers who find the Omnibus structure suitable for their business needs and work with UTXO-based assets will notice that all such assets (e.g., BTC, BCH, LTC, DOGE, ADA) are deposited into a single "Deposit" vault account. Each user has their own deposit address identified by the `description` parameter.

Processing these funds is straightforward in terms of address generation and management, but it introduces some potential challenges that should be considered during the integration phase. When running a retail-facing business and processing a large volume of UTXO-based asset deposits, customers may find that their deposit vault account accumulates a significant number of unspent transaction outputs (UTXOs) for a specific asset. Efficiently managing these UTXOs is crucial for the following reasons:

1. **Creating Outgoing Transactions**: Customers might want to move deposited funds (or part of them) to different venues such as exchange accounts, withdrawal vaults, or even a cold wallet. The number of UTXOs that can be selected for a transaction is limited to 250 UTXOs per transaction. This limitation could prevent customers from moving the desired amount if the selected 250 UTXOs do not add up to the intended amount. This depends on the UTXO selection mechanism in your Fireblocks wallet, which by default chooses the **smallest confirmed UTXOs first**. The selection mechanism can be adjusted to select the largest confirmed UTXOs first, based on customer preference.

2. **Fee Efficiency**: If a wallet has many small UTXOs, creating outgoing transactions will require selecting more UTXOs to reach the required amount. This results in larger transaction sizes and higher fees, making the transaction more attractive to miners/validators.

To overcome the mentioned in the above, customer should implement a UTXO consolidation logic as described in the following section.

### Unique deposit addresses via shared wallets

For UTXO-based chains, we recommend a similar approach to memo-based chains. Calling the [Create a new deposit address](/reference/createvaultaccountassetaddress) endpoint generates a new deposit address under the same wallet. Each end user receives a unique deposit address while funds are still received into a shared wallet. End-user deposits are identified by the receiving address included in the transaction notification, eliminating the need to create separate wallets per user.

### UTXO Consolidation

UTXO-based transactions in Fireblocks have a limit of 250 inputs (UTXOs) per transaction. Additionally, there must be a logic to select the inputs for a transaction, which Fireblocks implements as follows:

1. **DEFAULT Selection Mechanism**: By default, Fireblocks selects the first 250 smallest confirmed inputs available for a specified vault account. This helps customers use up small UTXOs and reduce the number of available UTXOs in their vault account.
2. **Configurable Selection Mechanism**: Fireblocks can be configured to select the 250 largest confirmed inputs first. This configuration requires opening a request with our support team.

This consolidation transaction is typically made from the Deposits vault account to one of the Withdrawals vault accounts to maintain a sufficient asset balance for user withdrawals. However, the transaction can also be executed with multiple destinations, such as different vault accounts, exchange accounts, external addresses, or even a cold wallet.

The trigger for the consolidation process can be based on the number of deposits made into the Deposits vault account. For instance, customers can decide that after every 250 deposits (tracked by an internal counting logic), the system will automatically create the consolidation transaction. Others may choose to execute this transaction based on current network fees to save on transaction costs.

Fireblocks provides two important endpoints to help clients build their UTXO consolidation logic:

1. [Get Maximum Spendable Amount in a Single Transaction](/reference/getmaxspendableamount): This endpoint returns the maximum amount of a particular asset that can be spent in a single transaction from a specified vault account.
2. [Create Transaction](/reference/createtransaction): This endpoint creates a transaction with the specified amount returned from the endpoint above.

Additionally, clients who want to trigger the consolidation transaction based on the number of deposits made into their Deposits vault account can use the Fireblocks [Webhook service](/reference/configure-webhook-urls) to get notifications on completed incoming transfers.

<Info>
  ### Check out the UTXO Consolidation [Developer Guide](/reference/consolidate-utxos)
</Info>

## Process Account Based Asset Deposits

Customers who want to generate a unique address for each of their end-users need to create a new intermediary vault account for each user and then the required vault wallet within this newly generated vault account. This is necessary because account-based assets do not support the generation of multiple addresses under the same wallet.

Once the generated address is shared with the end-user and the end-user makes a deposit into that vault account, most customers will want to perform a sweeping operation. This operation consolidates all deposited funds from the intermediary vault accounts into a single treasury management vault account for various business purposes.

Sweeping funds involves moving assets from address A to address B. It is important to note that this is an on-chain operation and includes transaction fee payments.

<Info>
  ### Learn more about the [Sweeping Mechanism](/docs/sweep-funds)
</Info>

While sweeping base assets like ETH is straightforward, sweeping deposited ERC20 tokens presents a challenge. This is because the transaction fee must be paid in the network's base asset, which end-users might not have in their wallets. To address this issue, Fireblocks recommends using the Fireblocks Gas Station feature.

<Info>
  ### Learn more about the Fireblocks [Gas Station](/docs/work-with-gas-station)
</Info>

### Memo and tag-based deposit identification

For account-based chains, we recommend creating a dedicated vault account for each end user and managing all of their associated wallets within that account.

Some chains, such as Stellar and Ripple, support deposit identification using a memo or tag (see the full list [here](/reference/vault-objects#createaddressresponse)). On these chains, you can assign each end user a unique memo or tag to identify their deposits using the [Create a new deposit address](/reference/createvaultaccountassetaddress) endpoint. This allows multiple users to deposit into a shared wallet without needing a separate vault account or wallet per end user. Deposits are credited by matching the memo or tag field included in the transaction.

This shared-wallet approach reduces operational overhead and fees by eliminating the need for sweeping funds and allowing reconciliation through a single or small number of transactions. However, it is still considered good practice to separate vault accounts by function. For example, cold storage, warm wallets, deposits, withdrawals, and treasury.

<Callout icon="❗️">
  **Important**

  The main disadvantage of this approach is that you must manage internal credits and balances based solely on transactions, because there is no on-chain balance to validate. Your internal system becomes the source of truth.
</Callout>

## Create Deposit Addresses Best Practices

Customers serving hundreds of thousands or even millions of users will eventually need to create a corresponding number of deposit addresses within a single vault account (for UTXO deposits) and/or intermediate vault accounts (for Account Based assets) in their workspace. A basic implementation is to create a new deposit address or vault account for the end-user whenever the user registers for the service or requests a deposit address for a specific coin.

In this setup, customers make a real-time API call to Fireblocks to generate a new deposit address or create a new vault account with a vault wallet for the requested asset, triggered by the end-user request.

While this approach is acceptable, the best practice we recommend is to create these deposit addresses or intermediate vault accounts proactively. Fireblocks customers should run a service that continuously creates addresses, vault accounts, and vault wallets, regardless of user requests.

This proactive approach means maintaining a pool of pre-generated vault accounts and addresses. When a user requests a new deposit address, customers can quickly assign a pre-generated address instead of making a real-time API call to Fireblocks. This reduces the risk of encountering API errors in real-time and significantly decreases the waiting time for users to receive a new address, thereby enhancing the user experience and providing a near real-time service.

### Pre-creating vault accounts

We recommend pre-creating vault accounts in advance. When an end user requests access, you can create the required wallets later and assign them to one of the pre-created vault accounts. To manage scale efficiently, you can maintain either high or low vault account thresholds — once the number of available accounts reaches a low threshold, resume creating accounts until the required threshold is met.

When a wallet is created for an end user, assign it to the appropriate pre-created vault account and update the assignment in your internal systems.

### Resource identification

To map resources to the correct end users, we recommend using the following fields:

* **Vault account:** use the `name` field
* **Wallet:** use the `description` field

Assign these fields at resource creation time and use them internally for end-user assignment.

<Callout icon="❗️">
  **Important**

  Do not store personally identifiable information (PII) in these fields.
</Callout>

### Vault account visibility

When creating deposit vault accounts, set the `hiddenOnUi` flag to `true`. This helps ensure proper management of important vault accounts in the Fireblocks Console.

### Wallets requiring on-chain creation

Some wallets require an on-chain operation to be created, including:

* SPL tokens (Solana)
* Ripple tokens
* Stellar tokens
* HBAR
* EOS

For SPL tokens, Associated Token Accounts (ATAs) can be created by receiving a token transfer from an external source. The account creation fee is included as part of that transfer.

While SPL, Ripple, and Stellar tokens use fees taken from the wallet itself, EOS wallets are currently funded by Fireblocks treasury and are expected to be used reasonably. In the future, the funding for these wallets will transition to a self-bootstrapped model.

To associate the pre-generated address with the end-user, during the assigning process on the customer's side, the following APIs should be called to synchronize both Fireblocks and the customer's internal system with the user reference:

1. **UTXO and Tag/Memo Based Assets**: When assigning a new UTXO-based asset deposit address within your Deposit vault account for a new user, call the [Update Address Description API endpoint](/reference/updatevaultaccountassetaddress) with the newly assigned user reference as the description.

2. **Account-Based Assets**: When assigning a new intermediate vault account for an end-user, call the [Rename a Vault Account API endpoint](/reference/updatevaultaccount) with the newly assigned user reference as the vault account name. Ensure that the vault account name does not contain any PII data.

## Validate Balances

Fireblocks allows you to receive notifications about incoming transactions to your Fireblocks vault accounts. A common setup for Fireblocks customers is to subscribe to the webhook service and get notified whenever a new deposit is made into a vault account. When an event for an incoming transaction is triggered, followed by an event confirming the deposit's completion, the typical setup on the customer's end will automatically update the internal ledger and adjust the balance of the user associated with the deposited vault account.

While this approach is generally correct, Fireblocks recommends implementing additional validation steps before crediting the end user with the deposited amount to avoid potential loss of funds.

<Warning>
  ### Validating Incoming Balances is crucial!

  Learn more about the best practices for validating balances and performing reconciliation processes in the following [guide](/docs/validate-balances)
</Warning>

## Maintain an Internal Ledger

An internal ledger is a fundamental component to consider when building a retail-facing solution. Essentially, it records incoming transfers and balances for your users.

Maintaining this ledger is crucial because funds deposited by users into their accounts are often swept or moved to a different account, as described in the sweeping mechanism section. You need to accurately track how much each user has deposited and what balance should be displayed in your system.

Fireblocks does not provide a built-in component or feature for this specific need, so customers can implement it in any way they see fit. However, Fireblocks offers all the necessary utility tools and features to effectively maintain such a ledger. This includes APIs for validation and reconciliation processes and a webhook service that allows you to create an event-driven system triggered by various events in your Fireblocks workspace.


# Overview
Source: https://developers.fireblocks.com/docs/manage-users

Fireblocks users can be added either via the web console or via the API:

* For adding users via the console please refer to [this guide](https://support.fireblocks.io/hc/en-us/articles/360012832959-User-roles)
* For adding users via the API please refer to the following [API endpoints](/reference/createconsoleuser) Generally, there are different user roles that can be assigned to a specific user, please see the user role table below:

There are different API Key types. Each type contains other capabilities in addition to transaction permissions.

| API Key Type          | Role        | Transaction Permissions                                   | Environment          |
| --------------------- | ----------- | --------------------------------------------------------- | -------------------- |
| **Admin**             | Signing     | Can sign transactions.                                    | Production           |
| **Non-Signing Admin** | Non-Signing | Can't sign transactions.                                  | Production + Sandbox |
| **Signer**            | Signing     | Can sign transactions.                                    | Production           |
| **Approver**          | Non-Signing | Can't sign transactions.                                  | Production           |
| **Editor**            | Non-Signing | Can't sign transactions.                                  | Production + Sandbox |
| **Viewer**            | View-Only   | Can only view transaction history.                        | Production + Sandbox |
| **Security Auditor**  | View-Only   | Can only view transaction history and workspace elements. | Production + Sandbox |
| **NCW\_ADMIN**        | Non-Signing | Can only manage Non Custodial Wallets.                    | Production + Sandbox |
| **NCW\_SIGNER**       | Signing     | Can only sign transaction from Non Custodial Wallets.     | Production + Sandbox |

Defining users in your workspace may seem straightforward, but it requires careful alignment with the supported roles.

Whether your goal is maximum security or optimal work efficiency, the right approach depends on your specific business use cases.

Before getting started, familiarize yourself with [user groups](https://support.fireblocks.io/hc/en-us/articles/7249202090396-User-group-management-and-best-practices) and [approval groups](https://support.fireblocks.io/hc/en-us/articles/11500062124188-Approval-groups) . These two features are crucial for defining user roles and actions in your Fireblocks workspace and can significantly enhance your operational efficiency and security.

* Segregate users into two categories: those responsible for managerial decisions and changes, and those handling day-to-day operations. Differentiating between users who can make changes in the workspace and those who can only initiate or sign transactions will enhance security. For more details, refer to [this guide](/docs/segregate-duties) .
* Always consider the admin quorum approval. The more approvals required for a workspace change, the longer and more complex the implementation process will be.
* Start by defining groups and their tasks. Based on these tasks, identify the roles that match and add individual users accordingly. Managing your operations with the correct setup of groups will enhance the performance of regular operations and facilitate general workspace changes.

Follow the general best practices when choosing users and roles as outlined [here](https://support.fireblocks.io/hc/en-us/articles/5254222799900-Best-practices-for-choosing-user-roles) .

## API Users Use Cases

API users can be used either to access Fireblocks API or to be paired with a cosigner (one can be both at the same time, but this is not the best practice).

In the case of an API user used to access the API, it has API key and API Secret that are required for authentication.

In the case of an API user paired with a cosigner, it has MPC key shares if it's a Signer or Admin, a One-time pairing token, and Device in case it's an API user that is paired with a device.

In the case of an API user used for KeyLink, it does not have MPC keys, but it has the pairing token, the access token, and the device.


# Manage Withdrawals at Scale
Source: https://developers.fireblocks.com/docs/manage-withdrawals-at-scale



# Withdrawal Flow

Withdrawals are one of the most critical and active functions in any retail-facing crypto business. Users depend on the withdrawal process to move funds quickly and securely. Designing an efficient, secure withdrawal flow is essential to delivering a reliable platform.

## Automate the withdrawal flow

### Setup

Automation is essential for ensuring a smooth, uninterrupted 24/7 withdrawal service. Relying on manual transaction signing is not scalable and introduces significant security risks. To address these challenges, implement a [Fireblocks Co-Signer](/reference/api-cosigner-management) component. This approach guarantees continuous operation and enhances the overall security of your withdrawal process.

### Highly available setup

One best practice for automation is setting up a highly available system by implementing the Co-signer in active/active mode. In this configuration, systems can take over from one another without downtime, ensuring that failover capability is always in place. For more information, see [Fireblocks Co-signer High Availability setup](/docs/multiple-cosigners-high-availability).

### Co-Signer logging and monitoring

Comprehensive monitoring and alerting are vital for maintaining a secure and reliable automated signing process. Setting up these systems lets you track transaction status in real time and detect anomalies that may indicate potential issues. Configure alerts to notify relevant personnel immediately when transactions are stuck or suspicious activity is detected, enabling prompt intervention.

For more information, see [API Co-signer Maintenance](/reference/api-cosigner-maintenance).

## Implementing multiple withdrawal wallets

### Withdrawal pool

Using multiple withdrawal vault accounts can help reduce the impact of stuck transactions and enable higher throughput. Distribute user withdrawal requests across several withdrawal vault accounts using a round-robin mechanism (a circular execution pattern between wallets) to reduce the risk of transaction queues.

While multiple withdrawal vault accounts offer clear throughput benefits, they also introduce operational complexity. Keep the following in mind:

* **Balance monitoring:** Regularly monitor the balance of each wallet to ensure sufficient liquidity.
* **Automated refills:** Implement automated refill mechanisms to transfer funds between wallets as needed.

Multiple withdrawal wallets are particularly beneficial for Ethereum, which uses the nonce mechanism and therefore processes transactions sequentially, and for UTXO-based assets like Bitcoin. In the UTXO model, an unconfirmed output from a previous transaction can be used as input for a new one. This can result in a chain of stuck transactions if the first is not confirmed.

Although mechanisms like [Replace By Fee (RBF)](/docs/boost-transactions-1#rbf-and-cpfp-in-fireblocks) and [Child Pays For Parent (CPFP)](/docs/boost-transactions-1#rbf-and-cpfp-in-fireblocks) exist to release stuck transactions, relying on them is not ideal. The Bitcoin protocol also has a built-in mechanism that rejects transactions using an unconfirmed output from a transaction with more than 25 predecessors. This can create a queue of withdrawals and, in some cases, cause withdrawal failures.

### Number of withdrawal wallets

A typical ECDSA-based chain transaction takes 6–7 seconds from initiation to broadcast. EdDSA-based chain transactions are slightly faster by about a second. On chains other than Solana and Tron (where parallel processing is not supported), Fireblocks serializes and signs transactions only after observing the previous transaction on the chain or node (TAP evaluation is still performed in parallel). In some cases, there is an additional delay of approximately 2 seconds before the transaction or its artifact is observed after submission.

For each sustained 1 TPS, we recommend using 5–6 withdrawal wallets and routing each new withdrawal to the next wallet in round-robin order. This guidance applies to steady-state throughput rather than short-term peaks. Queued transactions are acceptable as long as the queue continues to clear.

<Warning>
  ### Pay close attention to transaction queues

  Rapid growth may indicate that the Co-Signer is not signing transactions fast enough — this can be caused by slow callbacks, underpowered machines, or insufficient Co-Signers. If transactions remain queued for more than two hours, cancel and resubmit them, as they are likely to fail due to a timeout.
</Warning>

For wallets that support parallel processing (specifically Solana and Tron), enable parallel processing for up to four transactions. This configuration typically requires two withdrawal wallets per 1 TPS.

| Chain type        | Recommended withdrawal wallets | Notes                                                         |
| ----------------- | ------------------------------ | ------------------------------------------------------------- |
| EVM / ECDSA-based | 5–6 per 1 TPS                  | Round-robin routing; monitor for stuck nonce chains           |
| Bitcoin (UTXO)    | 2–3 per 1 TPS                  | Batch in 30-second windows; stay under 25-tx chain limit      |
| Solana / Tron     | 2 per 1 TPS                    | Enable parallel processing (up to 4 concurrent tx per wallet) |
| Stellar           | \~10 per 1 TPS                 | One tx per account per ledger (5s intervals)                  |

## Blockchain-specific guidance

### EVMs

Fireblocks supports advanced nonce management for EVMs to improve transaction latency and throughput. If a transaction fails and is not mined, its nonce can be reused by the next transaction from the same wallet, preventing the transaction chain from getting blocked.

Monitor transactions closely and identify any stuck in a confirming state from the same wallet. This is usually caused by a stuck low-fee transaction. Boosting or replacing the transaction via RBF allows the next transaction to be pushed to the chain. Identifying such situations early is critical; otherwise, you may submit multiple transactions with low fees, causing a backlog.

<Warning>
  ### Watch for delays due to fee spikes

  Some node implementations enforce per-address submission limits when transactions have low fees, long nonce chains, or unconfirmed dependencies. Although the Fireblocks framework can retry dropped transactions, delays during fee spikes can cause low fees and additional stuck transactions.
</Warning>

We recommend having several withdrawal accounts and routing withdrawals uniformly across them. Using five to six wallets enables approximately 1 TPS throughput.

### UTXOs

Under the current design, a UTXO wallet can serialize a single transaction at a time. In some cases, unconfirmed change outputs are reused in subsequent transactions, which can result in a stuck wallet if:

* A transaction is not mined due to low fees.
* The dependency chain reaches the maximum chain length of 25 unconfirmed transactions (common in Bitcoin nodes), causing new transactions to be rejected.

To avoid this situation, use one or more of the following methods:

* Batch withdrawals using multi-destination transactions. Creating a batch every 30 seconds results in 20 transactions over 10 minutes, staying below the 25-transaction limit.
* Schedule sweeping or funding to withdrawal wallets to obtain multiple confirmed UTXOs, reducing reliance on unconfirmed change outputs.
* Use CPFP to release transactions stuck due to low fees. Apply CPFP before reaching the 25-transaction chain limit. (RBF support is planned for the future.)
* Use multiple withdrawal wallets, as described earlier.

In general, aim to balance the number of UTXOs. Too many UTXOs are harder to reconcile; too few can cause mempool congestion and unconfirmed transactions.

For Bitcoin, we recommend holding two to three withdrawal wallets and batching withdrawals in 30-second windows.

For additional details on UTXO selection logic and filtering, see [Select UTXOs](/reference/select-utxos-for-a-transaction).

### Solana and Tron

On Solana, Fireblocks supports parallel transaction serialization per wallet using durable nonces, with up to 1,000 concurrent transactions in non-finalized states. Fee payer transactions and support for transactions without durable nonces are planned for the future.

For Tron, parallel serialization of transactions per wallet is planned by EOQ2, with support for up to 600 concurrent non-finalized transactions.

<Warning>
  ### You need multiple Co-signers for high-throughput setups

  High-throughput setups require multiple Co-signers that can handle parallel traffic. Additional Co-signers can be configured as needed.
</Warning>

### Stellar

Stellar uses sequence numbers and allows only one transaction per account per ledger (created every 5 seconds). As a result, throughput from a single wallet is limited. We recommend creating approximately 10 Stellar withdrawal wallets per 1 TPS. Fireblocks is considering support for channel accounts to enable better throughput and latency.

## Confirmation policy

Blockchain confirmations verify transactions while preventing fraud and double-spending. However, the confirmation threshold directly affects how quickly funds become available: the higher the threshold, the longer the delay.

For internal operations like sweeping or reconciliation, you can define a low confirmation requirement. Setting confirmations to `0` means:

* On **Bitcoin-based chains and EVMs**: the transaction is considered complete once it enters the mempool.
* On **other chains**: the transaction is considered complete immediately once included in a block.

On Bitcoin-based UTXO chains, setting confirmations to `0` also allows the resulting UTXOs to be immediately used in subsequent transactions.

For more information, see [Deposit Control & Confirmation Policy](/docs/define-confirmation-policy).

## Transaction batching

Transaction batching lets you consolidate multiple withdrawal requests into a single transaction with multiple destinations, minimizing fees. Because a batched transaction carries a single set of metadata, it is more cost-effective than multiple individual transactions. Fireblocks supports transaction batching for UTXO-based assets, Solana, and SPL20 tokens.

Batching does require collecting multiple user requests over a set period (for example, every X minutes) before processing them together. This approach reduces fees but may introduce slight delays for users expecting immediate withdrawals. The right batching interval depends on your withdrawal volume and user experience requirements.

Fireblocks supports creating a single transaction with multiple destinations using the [Create a new transaction](/reference/createtransaction) endpoint by passing the `destinations` array, which contains separate `destination` objects. For more information, see [Multiple destination transfer](/reference/create-transactions#multiple-destination-transfer).

## Working with One-Time Addresses

By default, outgoing transactions in Fireblocks can only be made to whitelisted addresses approved by the Workspace's Admin Approval Quorum. For businesses looking to scale their withdrawal flows and eliminate manual processes, this can become cumbersome.

To address this, Fireblocks introduced the One-Time Address (OTA) feature. OTA allows you to interact with non-whitelisted addresses, streamlining the withdrawal process. For more information, including security considerations, see [Work with One-Time Addresses](/docs/whitelist-addresses#work-with-one-time-addresses).

## Idempotent transactions

In RESTful APIs, idempotency means that making the same API call multiple times produces the same result as making it once. For financial operations like withdrawals, this is critical; without it, repeated requests can result in duplicate transactions and cause significant discrepancies.

Fireblocks provides idempotency for transaction creation through the `externalTxId` parameter. When you include `externalTxId` in a [Create a new transaction](/reference/createtransaction) request, Fireblocks rejects any subsequent request using the same value with an HTTP 400 error:

```json theme={"system"}
{
  "message": "The external tx id that was provided in the request, already exists",
  "code": 1438
}
```

Unlike the `Idempotency-Key` header (which expires after 24 hours), `externalTxId` is stored permanently. Fireblocks rejects duplicate values even if the follow-up request is made more than 24 hours after the original.

For more information, see [externalTxId](/reference/create-transactions#externaltxid) and [API Idempotency](/reference/api-idempotency).


# Mandatory fields for Bitstamp deposits
Source: https://developers.fireblocks.com/docs/mandatory-fields-for-bitstamp-deposits



## Originator: Myself (Individual)

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "piiData": {
      "type": "exchange-service-travel-rule",
      "typeVersion": "1.0.0",
      "data": {
        "originator": {
          "participantRelationshipType": "FirstParty",
          "entityType": "Individual",
          "names": [
            {
              "primaryName": "John",
              "nameType": "Latin",
              "secondaryName": "Doe"
            }
          ],
          "dateOfBirth": "2000-01-01",
          "postalAddress": {
            "streetName": "Oak street",
            "buildingNumber": "1",
            "city": "Boston",
            "postalCode": "02001",
            "country": "US"
          }
        },
        "originatingVASP": {
          "vaspCode": "914a9dae-4234-45d1-be83-fd40e818e381"
        }
      }
    }
  }
  ```
</CodeGroup>

## Originator: Myself (Corporate)

<CodeGroup>
  ```json Business theme={"system"}
  {
    "piiData": {
      "type": "exchange-service-travel-rule",
      "typeVersion": "1.0.0",
      "data": {
        "originator": {
          "participantRelationshipType": "FirstParty",
          "entityType": "Business",
          "postalAddress": {
            "streetName": "Oak street",
            "buildingNumber": "1",
            "city": "Boston",
            "postalCode": "02001",
            "country": "US"
          },
          "company": {
            "name": "ACME Inc"
          }
        },
        "originatingVASP": {
          "vaspCode": "914a9dae-4234-45d1-be83-fd40e818e381"
        }
      }
    }
  }
  ```
</CodeGroup>

## Originator: Third party (Individual)

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "piiData": {
      "type": "exchange-service-travel-rule",
      "typeVersion": "1.0.0",
      "data": {
        "originator": {
          "participantRelationshipType": "ThirdParty",
          "entityType": "Individual",
          "postalAddress": {
            "streetName": "Oak street",
            "buildingNumber": "1",
            "city": "Boston",
            "postalCode": "02001",
            "country": "US"
          },
          "names": [
            {
              "primaryName": "John",
              "nameType": "Latin",
              "secondaryName": "Doe"
            }
          ],
          "dateOfBirth": "2000-01-01"
        },
        "originatingVASP": {
          "vaspCode": "914a9dae-4234-45d1-be83-fd40e818e381"
        }
      }
    }
  }
  ```
</CodeGroup>

## Originator: Third party (Corporate)

<CodeGroup>
  ```json Third party theme={"system"}
  {
    "piiData": {
      "type": "exchange-service-travel-rule",
      "typeVersion": "1.0.0",
      "data": {
        "originator": {
          "participantRelationshipType": "ThirdParty",
          "entityType": "Business",
          "postalAddress": {
            "streetName": "Oak street",
            "buildingNumber": "1",
            "city": "Boston",
            "postalCode": "02001",
            "country": "US"
          },
          "company": {
            "name": "ACME Inc"
          }
        },
        "originatingVASP": {
          "vaspCode": "914a9dae-4234-45d1-be83-fd40e818e381"
        }
      }
    }
  }
  ```
</CodeGroup>


# Mandatory fields for Bitstamp withdrawals
Source: https://developers.fireblocks.com/docs/mandatory-fields-for-bitstamp-withdrawals



## Sending to myself (Individual)

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "piiData": {
      "type": "exchange-service-travel-rule",
      "typeVersion": "1.0.0",
      "data": {
        "beneficiary": {
          "participantRelationshipType": "FirstParty",
          "entityType": "Individual",
          "names": [
            {
              "primaryName": "John",
              "nameType": "Latin",
              "secondaryName": "Doe"
            }
          ],
          "dateOfBirth": "2000-01-01",
          "postalAddress": {
            "streetName": "Oak street",
            "buildingNumber": "1",
            "city": "Boston",
            "postalCode": "02001",
            "country": "US"
          }
        },
        "beneficiaryVASP": {
          "vaspCode": "914a9dae-4234-45d1-be83-fd40e818e381"
        }
      }
    }
  }
  ```
</CodeGroup>

## Sending to myself (Corporate)

<CodeGroup>
  ```json Business theme={"system"}
  {
    "piiData": {
      "type": "exchange-service-travel-rule",
      "typeVersion": "1.0.0",
      "data": {
        "beneficiary": {
          "participantRelationshipType": "FirstParty",
          "entityType": "Business",
          "postalAddress": {
            "streetName": "Oak street",
            "buildingNumber": "1",
            "city": "Boston",
            "postalCode": "02001",
            "country": "US"
          },
          "company": {
            "name": "ACME Inc"
          }
        },
        "beneficiaryVASP": {
          "vaspCode": "914a9dae-4234-45d1-be83-fd40e818e381"
        }
      }
    }
  }
  ```
</CodeGroup>

## Sending to another beneficiary (Individual)

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "piiData": {
      "type": "exchange-service-travel-rule",
      "typeVersion": "1.0.0",
      "data": {
        "beneficiary": {
          "participantRelationshipType": "ThirdParty",
          "entityType": "Individual",
          "postalAddress": {
            "streetName": "Oak street",
            "buildingNumber": "1",
            "city": "Boston",
            "postalCode": "02001",
            "country": "US"
          },
          "names": [
            {
              "primaryName": "John",
              "nameType": "Latin",
              "secondaryName": "Doe"
            }
          ],
          "dateOfBirth": "2000-01-01"
        },
        "beneficiaryVASP": {
          "vaspCode": "914a9dae-4234-45d1-be83-fd40e818e381"
        }
      }
    }
  }
  ```
</CodeGroup>

## Sending to another beneficiary (Corporate)

<CodeGroup>
  ```json Third party theme={"system"}
  {
    "piiData": {
      "type": "exchange-service-travel-rule",
      "typeVersion": "1.0.0",
      "data": {
        "beneficiary": {
          "participantRelationshipType": "ThirdParty",
          "entityType": "Business",
          "postalAddress": {
            "streetName": "Oak street",
            "buildingNumber": "1",
            "city": "Boston",
            "postalCode": "02001",
            "country": "US"
          },
          "company": {
            "name": "ACME Inc"
          }
        },
        "beneficiaryVASP": {
          "vaspCode": "914a9dae-4234-45d1-be83-fd40e818e381"
        }
      }
    }
  }
  ```
</CodeGroup>


# Mandatory fields for OKex withdrawals
Source: https://developers.fireblocks.com/docs/mandatory-fields-for-okex-withdrawals



## Private wallet (Individual)

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "piiData": {
      "type": "exchange-service-travel-rule",
      "typeVersion": "1.0.0",
      "data": {
        "beneficiary": {
          "isHosted": "false",
          "entityType": "Individual"
        }
      }
    }
  }
  ```
</CodeGroup>

## Private wallet (Corporate)

<CodeGroup>
  ```json Business theme={"system"}
  {
    "piiData": {
      "type": "exchange-service-travel-rule",
      "typeVersion": "1.0.0",
      "data": {
        "beneficiary": {
          "isHosted": "false",
          "entityType": "Business"
        }
      }
    }
  }
  ```
</CodeGroup>

## Hosted wallet/Exchange (Individual) - VASP exists

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "piiData": {
      "type": "exchange-service-travel-rule",
      "typeVersion": "1.0.0",
      "data": {
        "beneficiary": {
          "isHosted": "true",
          "entityType": "Individual",
          "names": [
            {
              "primaryName": "John",
              "nameType": "Latin",
              "secondaryName": "Doe"
            }
          ],
          "postalAddress": {
            "streetName": "Oak",
            "buildingNumber": "1",
            "city": "Boston",
            "postalCode": "11000",
            "subdivision": "Massachusetts",
            "country": "US"
          }
        },
        "beneficiaryVASP": {
          "vaspCode": "did:ethr:0xf2bd35dc59cbbe3efb15a5bd411ac84e7c86d25a"
        }
      }
    }
  }
  ```
</CodeGroup>

## Hosted wallet/Exchange (Individual) - Custom VASP

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "piiData": {
      "type": "exchange-service-travel-rule",
      "typeVersion": "1.0.0",
      "data": {
        "beneficiary": {
          "isHosted": "true",
          "entityType": "Individual",
          "names": [
            {
              "primaryName": "John",
              "nameType": "Latin",
              "secondaryName": "Doe"
            }
          ],
          "postalAddress": {
            "streetName": "Oak",
            "buildingNumber": "1",
            "city": "Boston",
            "postalCode": "11000",
            "subdivision": "Massachusetts",
            "country": "US"
          }
        },
        "beneficiaryVASP": {
          "vaspCode": "-2",
          "vaspName": "ACME VASP"
        }
      }
    }
  }
  ```
</CodeGroup>

## Hosted wallet/Exchange (Corporate) - VASP exists

<CodeGroup>
  ```json Third party theme={"system"}
  {
    "piiData": {
      "type": "exchange-service-travel-rule",
      "typeVersion": "1.0.0",
      "data": {
        "beneficiary": {
          "isHosted": "true",
          "entityType": "Business",
          "postalAddress": {
            "streetName": "Oak",
            "buildingNumber": "1",
            "city": "Boston",
            "postalCode": "11000",
            "subdivision": "Massachusetts",
            "country": "US"
          },
          "company": {
            "name": "ACME Inc"
          }
        },
        "beneficiaryVASP": {
          "vaspCode": "did:ethr:0xfeb4f99829a9acdf52979abee87e83addf22a7e1"
        }
      }
    }
  }
  ```
</CodeGroup>

## Hosted wallet/Exchange (Corporate) - Custom VASP

<CodeGroup>
  ```json Third party theme={"system"}
  {
    "piiData": {
      "type": "exchange-service-travel-rule",
      "typeVersion": "1.0.0",
      "data": {
        "beneficiary": {
          "isHosted": "true",
          "entityType": "Business",
          "postalAddress": {
            "streetName": "Oak",
            "buildingNumber": "1",
            "city": "Boston",
            "postalCode": "11000",
            "subdivision": "Massachusetts",
            "country": "US"
          },
          "company": {
            "name": "ACME Inc"
          }
        },
        "beneficiaryVASP": {
          "vaspCode": "-2",
          "vaspName": "ACME VASP"
        }
      }
    }
  }
  ```
</CodeGroup>


# Mandatory fields for TrustCo withdrawals
Source: https://developers.fireblocks.com/docs/mandatory-fields-for-trustco-withdrawals



## Sending to myself (Individual)

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "piiData": {
      "type": "exchange-service-travel-rule",
      "typeVersion": "1.0.0",
      "data": {
        "beneficiary": {
          "participantRelationshipType": "FirstParty",
          "entityType": "Individual",
          "names": [
            {
              "primaryName": "John",
              "nameType": "Latin",
              "secondaryName": "Doe"
            }
          ],
          "postalAddress": {
            "streetName": "Oak street",
            "buildingNumber": "1",
            "city": "Boston",
            "postalCode": "02001",
            "country": "US"
          },
          "externalReferenceId": "111-222-333-444"
        },
        "beneficiaryVASP": {
          "vaspName": "Prosperity Financial"
        }
      }
    }
  }
  ```
</CodeGroup>

## Sending to myself (Corporate)

<CodeGroup>
  ```json Business theme={"system"}
  {
    "piiData": {
      "type": "exchange-service-travel-rule",
      "typeVersion": "1.0.0",
      "data": {
        "beneficiary": {
          "participantRelationshipType": "FirstParty",
          "entityType": "Business",
          "postalAddress": {
            "streetName": "Oak street",
            "buildingNumber": "1",
            "city": "Boston",
            "postalCode": "02001",
            "country": "US"
          },
          "externalReferenceId": "111-222-333-444",
          "company": {
            "name": "ACME Inc"
          }
        },
        "beneficiaryVASP": {
          "vaspName": "Prosperity Financial"
        }
      }
    }
  }
  ```
</CodeGroup>

## Sending to another beneficiary (Individual)

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "piiData": {
      "type": "exchange-service-travel-rule",
      "typeVersion": "1.0.0",
      "data": {
        "beneficiary": {
          "participantRelationshipType": "ThirdParty",
          "entityType": "Individual",
          "names": [
            {
              "primaryName": "John",
              "nameType": "Latin",
              "secondaryName": "Doe"
            }
          ],
          "postalAddress": {
            "streetName": "Oak street",
            "buildingNumber": "1",
            "city": "Boston",
            "postalCode": "02001",
            "country": "US"
          },
          "externalReferenceId": "111-222-333-444"
        },
        "beneficiaryVASP": {
          "vaspName": "Prosperity Financial"
        }
      }
    }
  }
  ```
</CodeGroup>

## Sending to another beneficiary (Corporate)

<CodeGroup>
  ```json Third party theme={"system"}
  {
    "piiData": {
      "type": "exchange-service-travel-rule",
      "typeVersion": "1.0.0",
      "data": {
        "beneficiary": {
          "participantRelationshipType": "ThirdParty",
          "entityType": "Business",
          "postalAddress": {
            "streetName": "Oak street",
            "buildingNumber": "1",
            "city": "Boston",
            "postalCode": "02001",
            "country": "US"
          },
          "externalReferenceId": "111-222-333-444",
          "company": {
            "name": "ACME Inc"
          }
        },
        "beneficiaryVASP": {
          "vaspName": "Prosperity Financial"
        }
      }
    }
  }
  ```
</CodeGroup>


# Mandatory properties for Binance deposits
Source: https://developers.fireblocks.com/docs/mandatory-properties-for-deposits



# Overview

For incoming deposits to Binance, the Travel Rule mandates the submission of specific PII. This page outlines the necessary data fields and their formats, varying by jurisdiction, to ensure your deposits are compliant and processed without delay.

Developers should review these requirements carefully, alongside the provided country-specific descriptions and examples, to correctly structure PII messages for all deposit transactions.

## Bahrain

### Originator: Myself

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Individual"
      },
      "originatingVASP": {
        "vaspName": "Binance"
      },
      "beneficiaryVASP": {
        "vaspCountry": "BH"
      }
    }
  }
  ```

  ```json Business theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Business"
      },
      "originatingVASP": {
        "vaspName": "Binance"
      },
      "beneficiaryVASP": {
        "vaspCountry": "BH"
      }
    }
  }
  ```
</CodeGroup>

### Originator: Not myself

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Individual",
        "names": [
          {
            "primaryName": "John",
            "nameType": "Latin",
            "secondaryName": "Doe"
          }
        ],
        "postalAddress": {
          "country": "AU",
          "city": "Perth"
        }
      },
      "originatingVASP": {
        "vaspName": "Binance"
      },
      "beneficiaryVASP": {
        "vaspCountry": "BH"
      }
    }
  }
  ```

  ```json Third party theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Business",
        "postalAddress": {
          "country": "AU",
          "city": "Perth"
        },
        "company": {
          "name": "ACME Inc"
        }
      },
      "originatingVASP": {
        "vaspName": "Binance"
      },
      "beneficiaryVASP": {
        "vaspCountry": "BH"
      }
    }
  }
  ```
</CodeGroup>

## France

### Originator: Myself

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Individual"
      },
      "originatingVASP": {
        "vaspName": "Binance"
      },
      "transactionData": {
        "deposit": {
          "isAddressVerified": true
        }
      },
      "beneficiaryVASP": {
        "vaspCountry": "FR"
      }
    }
  }
  ```

  ```json Business theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Business"
      },
      "originatingVASP": {
        "vaspName": "Binance"
      },
      "transactionData": {
        "deposit": {
          "isAddressVerified": true
        }
      },
      "beneficiaryVASP": {
        "vaspCountry": "FR"
      }
    }
  }
  ```
</CodeGroup>

### Originator: Not myself

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Individual",
        "names": [
          {
            "primaryName": "John",
            "nameType": "Latin",
            "secondaryName": "Doe"
          }
        ],
        "postalAddress": {
          "country": "AO"
        }
      },
      "originatingVASP": {
        "vaspName": "Binance"
      },
      "transactionData": {
        "deposit": {
          "isAddressVerified": true
        }
      },
      "beneficiaryVASP": {
        "vaspCountry": "FR"
      }
    }
  }
  ```

  ```json Third party theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Business",
        "company": {
          "name": "ACME Inc"
        },
        "postalAddress": {
          "country": "AR"
        }
      },
      "originatingVASP": {
        "vaspName": "Binance"
      },
      "transactionData": {
        "deposit": {
          "isAddressVerified": true
        }
      },
      "beneficiaryVASP": {
        "vaspCountry": "FR"
      }
    }
  }
  ```
</CodeGroup>

## India

### Originator: Myself

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Individual"
      },
      "originatingVASP": {
        "vaspName": "Binance"
      },
      "beneficiaryVASP": {
        "vaspCountry": "IN"
      }
    }
  }
  ```

  ```json Business theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Business"
      },
      "originatingVASP": {
        "vaspName": "Binance"
      },
      "beneficiaryVASP": {
        "vaspCountry": "IN"
      }
    }
  }
  ```
</CodeGroup>

### Originator: Not myself

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Individual",
        "names": [
          {
            "primaryName": "John",
            "nameType": "Latin",
            "secondaryName": "Doe"
          }
        ],
        "nationalIdentification": {
          "nationalIdentifier": "12345xyz"
        },
        "postalAddress": {
          "country": "AR",
          "subdivision": "State",
          "city": "Buenos Aires",
          "postalCode": "123123123",
          "streetName": "Oak street 123"
        }
      },
      "originatingVASP": {
        "vaspName": "Binance"
      },
      "beneficiaryVASP": {
        "vaspCountry": "IN"
      }
    }
  }
  ```

  ```json Third party theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Business",
        "postalAddress": {
          "country": "AR",
          "subdivision": "State",
          "city": "Buenos Aires",
          "postalCode": "123123123",
          "streetName": "Oak street 123"
        },
        "company": {
          "name": "ACME Inc"
        },
        "registrationNumber": "pan1234"
      },
      "originatingVASP": {
        "vaspName": "Binance"
      },
      "beneficiaryVASP": {
        "vaspCountry": "IN"
      }
    }
  }
  ```
</CodeGroup>

## Japan

### Originator: Myself

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Individual"
      },
      "originatingVASP": {
        "vaspName": "BINANCE"
      },
      "transactionData": {
        "deposit": {
          "isAddressVerified": true
        }
      },
      "beneficiaryVASP": {
        "vaspCountry": "JP"
      }
    }
  }
  ```

  ```json Business theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Business"
      },
      "originatingVASP": {
        "vaspName": "BINANCE"
      },
      "transactionData": {
        "deposit": {
          "isAddressVerified": true
        }
      },
      "beneficiaryVASP": {
        "vaspCountry": "JP"
      }
    }
  }
  ```
</CodeGroup>

### Originator: Not myself

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Individual",
        "postalAddress": {
          "country": "AU",
          "city": "Perth"
        },
        "names": [
          {
            "primaryName": "Kanji name",
            "nameType": "Kanji"
          },
          {
            "primaryName": "Kana name",
            "nameType": "Kana"
          },
          {
            "primaryName": "John",
            "nameType": "Latin",
            "secondaryName": "Doe"
          }
        ]
      },
      "originatingVASP": {
        "vaspName": "BINANCE"
      },
      "transactionData": {
        "deposit": {
          "isAddressVerified": true
        }
      },
      "beneficiaryVASP": {
        "vaspCountry": "JP"
      }
    }
  }
  ```

  ```json Third party theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Business",
        "postalAddress": {
          "country": "AU",
          "city": "Perth"
        },
        "names": [
          {
            "primaryName": "Kanji name",
            "nameType": "Kanji"
          },
          {
            "primaryName": "Kana name",
            "nameType": "Kana"
          },
          {
            "primaryName": "John",
            "nameType": "Latin",
            "secondaryName": "Doe"
          }
        ]
      },
      "originatingVASP": {
        "vaspName": "BINANCE"
      },
      "transactionData": {
        "deposit": {
          "isAddressVerified": true
        }
      },
      "beneficiaryVASP": {
        "vaspCountry": "JP"
      }
    }
  }
  ```
</CodeGroup>

## Kazakhstan

### Originator: Myself

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Individual",
        "names": [
          {
            "primaryName": "John",
            "nameType": "Latin",
            "secondaryName": "Doe"
          }
        ],
        "postalAddress": {
          "country": "AT",
          "city": "Vienna"
        }
      },
      "transactionData": {
        "deposit": {
          "txPurpose": "service"
        }
      },
      "beneficiaryVASP": {
        "vaspCountry": "KZ"
      }
    }
  }
  ```

  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "ThirdParty",
        "postalAddress": {
          "country": "AT",
          "city": "Vienna"
        },
        "entityType": "Individual",
        "names": [
          {
            "primaryName": "John",
            "nameType": "Latin",
            "secondaryName": "Doe"
          }
        ]
      },
      "transactionData": {
        "deposit": {
          "txPurpose": "service"
        }
      },
      "beneficiaryVASP": {
        "vaspCountry": "KZ"
      }
    }
  }
  ```
</CodeGroup>

### Originator: Not myself

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Individual",
        "names": [
          {
            "primaryName": "John",
            "nameType": "Latin",
            "secondaryName": "Doe"
          }
        ],
        "postalAddress": {
          "country": "AT",
          "city": "Vienna"
        }
      },
      "transactionData": {
        "deposit": {
          "txPurpose": "service"
        }
      },
      "beneficiaryVASP": {
        "vaspCountry": "KZ"
      }
    }
  }
  ```

  ```json Third party theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "ThirdParty",
        "postalAddress": {
          "country": "AT",
          "city": "Vienna"
        },
        "entityType": "Business",
        "company": {
          "name": "ACME Inc"
        }
      },
      "transactionData": {
        "deposit": {
          "txPurpose": "service"
        }
      },
      "beneficiaryVASP": {
        "vaspCountry": "KZ"
      }
    }
  }
  ```
</CodeGroup>

## Poland

### Originator: Myself

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Individual"
      },
      "originatingVASP": {
        "vaspName": "Binance"
      },
      "transactionData": {
        "deposit": {
          "isAddressVerified": true
        }
      },
      "beneficiaryVASP": {
        "vaspCountry": "PL"
      }
    }
  }
  ```

  ```json Business theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Business"
      },
      "originatingVASP": {
        "vaspName": "Binance"
      },
      "transactionData": {
        "deposit": {
          "isAddressVerified": true
        }
      },
      "beneficiaryVASP": {
        "vaspCountry": "PL"
      }
    }
  }
  ```
</CodeGroup>

### Originator: Not myself

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Individual",
        "names": [
          {
            "primaryName": "John",
            "nameType": "Latin",
            "secondaryName": "Doe"
          }
        ],
        "postalAddress": {
          "country": "AT"
        }
      },
      "originatingVASP": {
        "vaspName": "Binance"
      },
      "transactionData": {
        "deposit": {
          "isAddressVerified": true
        }
      },
      "beneficiaryVASP": {
        "vaspCountry": "PL"
      }
    }
  }
  ```

  ```json Third party theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Business",
        "company": {
          "name": "ACME Inc"
        },
        "postalAddress": {
          "country": "AR"
        }
      },
      "originatingVASP": {
        "vaspName": "Binance"
      },
      "transactionData": {
        "deposit": {
          "isAddressVerified": true
        }
      },
      "beneficiaryVASP": {
        "vaspCountry": "PL"
      }
    }
  }
  ```
</CodeGroup>

## South Africa

### Originator: Myself

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Individual"
      },
      "deposit": {
        "receiveFrom": "1"
      },
      "transactionData": {
        "deposit": {
          "isAddressVerified": true
        }
      },
      "beneficiaryVASP": {
        "vaspCountry": "ZA"
      }
    }
  }
  ```

  ```json Business theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Business"
      },
      "deposit": {
        "receiveFrom": "1"
      },
      "transactionData": {
        "deposit": {
          "isAddressVerified": true
        }
      },
      "beneficiaryVASP": {
        "vaspCountry": "ZA"
      }
    }
  }
  ```
</CodeGroup>

### Originator: Not myself

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Individual",
        "names": [
          {
            "primaryName": "John",
            "nameType": "Latin",
            "secondaryName": "Doe"
          }
        ],
        "postalAddress": {
          "country": "AR"
        }
      },
      "deposit": {
        "receiveFrom": "1"
      },
      "transactionData": {
        "deposit": {
          "isAddressVerified": true
        }
      },
      "beneficiaryVASP": {
        "vaspCountry": "ZA"
      }
    }
  }
  ```

  ```json Third party theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Business",
        "company": {
          "name": "ACME Inc"
        },
        "postalAddress": {
          "country": "AU"
        }
      },
      "deposit": {
        "receiveFrom": "1"
      },
      "transactionData": {
        "deposit": {
          "isAddressVerified": true
        }
      },
      "beneficiaryVASP": {
        "vaspCountry": "ZA"
      }
    }
  }
  ```
</CodeGroup>

## United Arab Emirates (UAE)

### Originator: Myself

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Individual"
      },
      "originatingVASP": {
        "vaspName": "Binance"
      },
      "beneficiaryVASP": {
        "vaspCountry": "AE"
      }
    }
  }
  ```

  ```json Business theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Business"
      },
      "originatingVASP": {
        "vaspName": "Binance"
      },
      "beneficiaryVASP": {
        "vaspCountry": "AE"
      }
    }
  }
  ```
</CodeGroup>

### Originator: Not myself

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Individual",
        "names": [
          {
            "primaryName": "John",
            "nameType": "Latin",
            "secondaryName": "Doe"
          }
        ],
        "postalAddress": {
          "country": "AT",
          "city": "Vienna"
        }
      },
      "originatingVASP": {
        "vaspName": "Binance"
      },
      "beneficiaryVASP": {
        "vaspCountry": "AE"
      }
    }
  }
  ```

  ```json Third party theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "originator": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Business",
        "postalAddress": {
          "country": "AT",
          "city": "Vienna"
        },
        "company": {
          "name": "ACME Inc"
        }
      },
      "originatingVASP": {
        "vaspName": "Binance"
      },
      "beneficiaryVASP": {
        "vaspCountry": "AE"
      }
    }
  }
  ```
</CodeGroup>


# Mandatory properties for Binance withdrawals
Source: https://developers.fireblocks.com/docs/mandatory-properties-for-withdrawals



# Overview

To ensure compliance with Binance's Travel Rule requirements for withdrawals, it's crucial to understand the specific Personally Identifiable Information (PII) that must accompany these transactions.

This section details the mandatory properties for successful withdrawals, providing country-specific information and practical examples to guide your implementation. Adhering to these guidelines is essential for seamless and compliant asset transfers.

## Bahrain

### Sending to myself

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Individual"
      },
      "beneficiaryVASP": {
        "vaspCode": "BINANCE"
      },
      "originatingVASP": {
        "vaspCountry": "BH"
      }
    }
  }
  ```

  ```json Business theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Business"
      },
      "beneficiaryVASP": {
        "vaspCode": "BINANCE"
      },
      "originatingVASP": {
        "vaspCountry": "BH"
      }
    }
  }
  ```
</CodeGroup>

### Sending to another beneficiary

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Individual",
        "names": [
          {
            "primaryName": "John",
            "nameType": "Latin",
            "secondaryName": "Doe"
          }
        ],
        "postalAddress": {
          "country": "AT",
          "city": "Vienna"
        }
      },
      "beneficiaryVASP": {
        "vaspCode": "BINANCE"
      },
      "originatingVASP": {
        "vaspCountry": "BH"
      }
    }
  }
  ```

  ```json Third party theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Business",
        "postalAddress": {
          "country": "AT",
          "city": "Vienna"
        },
        "company": {
          "name": "Acme INC"
        }
      },
      "beneficiaryVASP": {
        "vaspCode": "BINANCE"
      },
      "originatingVASP": {
        "vaspCountry": "BH"
      }
    }
  }
  ```
</CodeGroup>

## France

### Sending to myself

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Individual"
      },
      "transactionData": {
        "withdraw": {
          "isAddressVerified": true
        }
      },
      "originatingVASP": {
        "vaspCountry": "FR"
      }
    }
  }
  ```

  ```json Business theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Business"
      },
      "transactionData": {
        "withdraw": {
          "isAddressVerified": true
        }
      },
      "beneficiaryVASP": {
        "vaspCode": "BINANCE"
      },
      "originatingVASP": {
        "vaspCountry": "FR"
      }
    }
  }
  ```
</CodeGroup>

### Sending to another beneficiary

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Individual",
        "names": [
          {
            "primaryName": "John",
            "nameType": "Latin",
            "secondaryName": "Doe"
          }
        ],
        "postalAddress": {
          "country": "AT"
        }
      },
      "transactionData": {
        "withdraw": {
          "isAddressVerified": true
        }
      },
      "beneficiaryVASP": {
        "vaspCode": "BINANCE"
      },
      "originatingVASP": {
        "vaspCountry": "FR"
      }
    }
  }
  ```

  ```json Third party theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Business",
        "postalAddress": {
          "country": "AT",
          "city": "Vienna"
        },
        "company": {
          "name": "Acme INC"
        }
      },
      "beneficiaryVASP": {
        "vaspCode": "BINANCE"
      },
      "originatingVASP": {
        "vaspCountry": "BH"
      }
    }
  } 
  ```
</CodeGroup>

## India

### Sending to myself

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Individual"
      },
      "beneficiaryVASP": {
        "vaspCode": "BINANCE"
      },
      "originatingVASP": {
        "vaspCountry": "IN"
      }
    }
  }
  ```

  ```json Business theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Business"
      },
      "beneficiaryVASP": {
        "vaspCode": "BINANCE"
      },
      "originatingVASP": {
        "vaspCountry": "IN"
      }
    }
  }
  ```
</CodeGroup>

### Sending to another beneficiary

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Individual",
        "names": [
          {
            "primaryName": "John",
            "nameType": "Latin",
            "secondaryName": "Doe"
          }
        ],
        "postalAddress": {
          "country": "AR",
          "city": "Buenos Aires"
        }
      },
      "beneficiaryVASP": {
        "vaspCode": "BINANCE"
      },
      "originatingVASP": {
        "vaspCountry": "IN"
      }
    }
  }
  ```

  ```json Third party theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Business",
        "postalAddress": {
          "country": "AR",
          "city": "Buenos Aires"
        },
        "company": {
          "name": "ACME Inc"
        }
      },
      "beneficiaryVASP": {
        "vaspCode": "BINANCE"
      },
      "originatingVASP": {
        "vaspCountry": "IN"
      }
    }
  }
  ```
</CodeGroup>

## Japan

### Sending to myself

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Individual",
        "postalAddress": {
          "country": "AR",
          "city": "Buenos Aires"
        }
      },
      "beneficiaryVASP": {
        "vaspCode": "BINANCE",
        "vaspName": "CN"
      },
      "transactionData": {
        "withdraw": {
          "txPurpose": "goods",
          "isAddressVerified": true
        }
      },
      "originatingVASP": {
        "vaspCountry": "JP"
      }
    }
  }
  ```

  ```json Business theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Business",
        "postalAddress": {
          "country": "AR",
          "city": "Buenos Aires"
        }
      },
      "beneficiaryVASP": {
        "vaspCode": "BINANCE",
        "vaspName": "CN"
      },
      "transactionData": {
        "withdraw": {
          "txPurpose": "goods",
          "isAddressVerified": true
        }
      },
      "originatingVASP": {
        "vaspCountry": "JP"
      }
    }
  }
  ```
</CodeGroup>

### Sending to another beneficiary

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "ThirdParty",
        "postalAddress": {
          "country": "AR",
          "city": "Buenos Aires"
        },
        "entityType": "Individual",
        "names": [
          {
            "primaryName": "Kanji name",
            "nameType": "Kanji"
          },
          {
            "primaryName": "Kana name",
            "nameType": "Kana"
          },
          {
            "primaryName": "John",
            "nameType": "Latin",
            "secondaryName": "Doe"
          }
        ]
      },
      "beneficiaryVASP": {
        "vaspCode": "BINANCE",
        "vaspName": "CN"
      },
      "transactionData": {
        "withdraw": {
          "txPurpose": "goods",
          "isAddressVerified": true
        }
      },
      "originatingVASP": {
        "vaspCountry": "JP"
      }
    }
  }
  ```

  ```json Third party theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "ThirdParty",
        "postalAddress": {
          "country": "AR",
          "city": "Buenos Aires"
        },
        "entityType": "Business",
        "names": [
          {
            "primaryName": "Kanji name",
            "nameType": "Kanji"
          },
          {
            "primaryName": "Kana name",
            "nameType": "Kana"
          },
          {
            "primaryName": "John",
            "nameType": "Latin",
            "secondaryName": "Doe"
          }
        ]
      },
      "beneficiaryVASP": {
        "vaspCode": "BINANCE",
        "vaspName": "CN"
      },
      "transactionData": {
        "withdraw": {
          "txPurpose": "goods",
          "isAddressVerified": true
        }
      },
      "originatingVASP": {
        "vaspCountry": "JP"
      }
    }
  }
  ```
</CodeGroup>

## Kazakhstan

### Sending to myself

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Individual",
        "postalAddress": {
          "country": "AT",
          "city": "Vienna"
        }
      },
      "withdraw": {
        "txnPurpose": "service"
      },
      "beneficiaryVASP": {
        "vaspCode": "BINANCE"
      },
      "transactionData": {
        "withdraw": {
          "isAddressVerified": true
        }
      },
      "originatingVASP": {
        "vaspCountry": "KZ"
      }
    }
  }
  ```

  ```json Business theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Business",
        "postalAddress": {
          "country": "AT",
          "city": "Vienna"
        }
      },
      "withdraw": {
        "txnPurpose": "service"
      },
      "beneficiaryVASP": {
        "vaspCode": "BINANCE"
      },
      "transactionData": {
        "withdraw": {
          "isAddressVerified": true
        }
      },
      "originatingVASP": {
        "vaspCountry": "KZ"
      }
    }
  }
  ```
</CodeGroup>

### Sending to another beneficiary

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "ThirdParty",
        "postalAddress": {
          "country": "AT",
          "city": "Vienna"
        },
        "entityType": "Individual",
        "names": [
          {
            "primaryName": "John",
            "nameType": "Latin",
            "secondaryName": "Doe"
          }
        ]
      },
      "withdraw": {
        "txnPurpose": "service"
      },
      "beneficiaryVASP": {
        "vaspCode": "BINANCE"
      },
      "transactionData": {
        "withdraw": {
          "isAddressVerified": true
        }
      },
      "originatingVASP": {
        "vaspCountry": "KZ"
      }
    }
  }
  ```

  ```json Third party theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "ThirdParty",
        "postalAddress": {
          "country": "AT",
          "city": "Vienna"
        },
        "entityType": "Business",
        "company": {
          "name": "ACME Inc"
        }
      },
      "withdraw": {
        "txnPurpose": "service"
      },
      "beneficiaryVASP": {
        "vaspCode": "BINANCE"
      },
      "transactionData": {
        "withdraw": {
          "isAddressVerified": true
        }
      },
      "originatingVASP": {
        "vaspCountry": "KZ"
      }
    }
  }
  ```
</CodeGroup>

## New Zealand

### Sending to myself

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Individual"
      },
      "beneficiaryVASP": {
        "vaspCode": "others",
        "vaspName": "SomeVASP"
      },
      "transactionData": {
        "withdraw": {
          "isAddressVerified": true
        }
      },
      "originatingVASP": {
        "vaspCountry": "NZ"
      }
    }
  }
  ```

  ```json Business theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Business"
      },
      "beneficiaryVASP": {
        "vaspCode": "others",
        "vaspName": "SomeVASP"
      },
      "transactionData": {
        "withdraw": {
          "isAddressVerified": true
        }
      },
      "originatingVASP": {
        "vaspCountry": "NZ"
      }
    }
  }
  ```
</CodeGroup>

### Sending to another beneficiary

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Individual",
        "names": [
          {
            "primaryName": "John",
            "nameType": "Latin",
            "secondaryName": "Doe"
          }
        ],
        "postalAddress": {
          "country": "DZ"
        }
      },
      "beneficiaryVASP": {
        "vaspCode": "others",
        "vaspName": "SomeVASP"
      },
      "transactionData": {
        "withdraw": {
          "isAddressVerified": true
        }
      },
      "originatingVASP": {
        "vaspCountry": "NZ"
      }
    }
  }
  ```

  ```json Third party theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Business",
        "company": {
          "name": "ACME Inc"
        },
        "postalAddress": {
          "country": "DZ"
        }
      },
      "beneficiaryVASP": {
        "vaspCode": "others",
        "vaspName": "SomeVASP"
      },
      "transactionData": {
        "withdraw": {
          "isAddressVerified": true
        }
      },
      "originatingVASP": {
        "vaspCountry": "NZ"
      }
    }
  }
  ```
</CodeGroup>

## Poland

### Sending to myself

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Individual"
      },
      "beneficiaryVASP": {
        "vaspCode": "BINANCE"
      },
      "transactionData": {
        "withdraw": {
          "isAddressVerified": true
        }
      },
      "originatingVASP": {
        "vaspCountry": "PL"
      }
    }
  }
  ```

  ```json Business theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Business"
      },
      "beneficiaryVASP": {
        "vaspCode": "BINANCE"
      },
      "transactionData": {
        "withdraw": {
          "isAddressVerified": true
        }
      },
      "originatingVASP": {
        "vaspCountry": "PL"
      }
    }
  }
  ```
</CodeGroup>

### Sending to another beneficiary

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Individual",
        "names": [
          {
            "primaryName": "John",
            "nameType": "Latin",
            "secondaryName": "Doe"
          }
        ],
        "postalAddress": {
          "country": "AR"
        }
      },
      "beneficiaryVASP": {
        "vaspCode": "BINANCE"
      },
      "transactionData": {
        "withdraw": {
          "isAddressVerified": true
        }
      },
      "originatingVASP": {
        "vaspCountry": "PL"
      }
    }
  }
  ```

  ```json Third party theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Business",
        "company": {
          "name": "ACME Inc"
        },
        "postalAddress": {
          "country": "DZ"
        }
      },
      "beneficiaryVASP": {
        "vaspCode": "BINANCE"
      },
      "transactionData": {
        "withdraw": {
          "isAddressVerified": true
        }
      },
      "originatingVASP": {
        "vaspCountry": "PL"
      }
    }
  }
  ```
</CodeGroup>

## South Africa

### Sending to myself

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Individual"
      },
      "beneficiaryVASP": {
        "vaspCode": "others",
        "vaspName": "Some VASP"
      },
      "transactionData": {
        "withdraw": {
          "isAddressVerified": true
        }
      },
      "originatingVASP": {
        "vaspCountry": "ZA"
      }
    }
  }
  ```

  ```json Business theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Business"
      },
      "beneficiaryVASP": {
        "vaspCode": "others",
        "vaspName": "Some VASP"
      },
      "transactionData": {
        "withdraw": {
          "isAddressVerified": true
        }
      },
      "originatingVASP": {
        "vaspCountry": "ZA"
      }
    }
  }
  ```
</CodeGroup>

### Sending to another beneficiary

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Individual",
        "names": [
          {
            "primaryName": "John",
            "nameType": "Latin",
            "secondaryName": "Doe"
          }
        ],
        "postalAddress": {
          "country": "DZ"
        }
      },
      "beneficiaryVASP": {
        "vaspCode": "others",
        "vaspName": "Some VASP"
      },
      "transactionData": {
        "withdraw": {
          "isAddressVerified": true
        }
      },
      "originatingVASP": {
        "vaspCountry": "ZA"
      }
    }
  }
  ```

  ```json Third party theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Business",
        "company": {
          "name": "ACME Inc"
        },
        "postalAddress": {
          "country": "AU"
        }
      },
      "beneficiaryVASP": {
        "vaspCode": "others",
        "vaspName": "Some VASP"
      },
      "transactionData": {
        "withdraw": {
          "isAddressVerified": true
        }
      },
      "originatingVASP": {
        "vaspCountry": "ZA"
      }
    }
  }
  ```
</CodeGroup>

## United Arab Emirates (UAE)

### Sending to myself

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Individual"
      },
      "beneficiaryVASP": {
        "vaspCode": "BINANCE"
      },
      "originatingVASP": {
        "vaspCountry": "AE"
      }
    }
  }
  ```

  ```json Business theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "FirstParty",
        "entityType": "Business"
      },
      "beneficiaryVASP": {
        "vaspCode": "BINANCE"
      },
      "originatingVASP": {
        "vaspCountry": "AE"
      }
    }
  }
  ```
</CodeGroup>

### Sending to another beneficiary

<CodeGroup>
  ```json Individual theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Individual",
        "names": [
          {
            "primaryName": "John",
            "nameType": "Latin",
            "secondaryName": "Doe"
          }
        ],
        "postalAddress": {
          "country": "AU",
          "city": "Perth"
        }
      },
      "beneficiaryVASP": {
        "vaspCode": "BINANCE"
      },
      "originatingVASP": {
        "vaspCountry": "AE"
      }
    }
  }
  ```

  ```json Third party theme={"system"}
  {
    "type": "exchange-service-travel-rule",
    "typeVersion": "1.0.0",
    "data": {
      "beneficiary": {
        "participantRelationshipType": "ThirdParty",
        "entityType": "Business",
        "postalAddress": {
          "country": "AU",
          "city": "Perth"
        },
        "company": {
          "name": "ACME Inc"
        }
      },
      "beneficiaryVASP": {
        "vaspCode": "BINANCE"
      },
      "originatingVASP": {
        "vaspCountry": "AE"
      }
    }
  }
  ```
</CodeGroup>


# Configuring Multiple API Co-signers in High Availability
Source: https://developers.fireblocks.com/docs/multiple-cosigners-high-availability



## Overview

You can configure multiple API Co-signers to operate in an active-active state, ensuring transaction operations align with your business continuity requirements. If one API Co-signer fails or becomes impaired, the remaining Co-signer(s) will continue signing transactions seamlessly.

## Configuring multiple Co-Signers to work in parallel

Upon completing the Co-signer's setup and configuration, you can configure them to work in parallel using the Policies.

Each API Co-signer must have at least one API user assigned the Signer role. These API users should be added to the **Designated Signers / Groups** field in the Policy for the transaction types the Co-signers are authorized to sign. You can add API users individually or as part of a user group. All designated signers for the rule must be API users. A combination of API users and Fireblocks Console users is not permitted. Refer to the [following article](https://support.fireblocks.io/hc/en-us/articles/19156998685980-About-Policies) to learn more about creating and modifying your Policies.

Once the Owner and Admin Quorum approve the Policy update, multiple Co-signers operate in parallel. Now, the transaction signing process follows these steps:

1. A transaction is initiated using the Console or APIs.
2. Fireblocks evaluates the transaction against the workspace's Policy to match it with the appropriate rule. The rule includes API users in the Designated Signers/Groups field.
3. Fireblocks calls all the Co-signers that are paired with the API users listed in the Policy rule's Designated Signers/Groups field to confirm their availability for signing.
4. Fireblocks identifies the first available API user with a paired Co-signer and sends the transaction to that Co-signer for signing.
5. If a Callback Handler is configured for the API Co-signer, it determines whether the transaction is signed or rejected based on the defined callback logic. If no Callback Handler is configured, the API user signs the transaction automatically.

## Configuring Policy rules for a group of API Co-signers

### Exchange or fiat accounts

You cannot add multiple API users or a user group to the Designated Signers/Groups field in rules in which the Source field contains an exchange or fiat account. Doing so causes transactions that match that rule to fail automatically. You must assign a single API user in Policy rules for exchange and fiat accounts.

### Policy Configuration

Depending on how you want to customize the Policy (i.e., whether you create inclusionary or exclusionary rules), you can use different methods to ensure transactions match the correct rule. In the following examples, Group 1 members are the API Co-Signers.

#### Method 1: Including API Co-Signers only for supported sources

| Rule | Initiator | Type | Source | Dest. | Whitelisted / OTA | Amount | Time Period | Asset | Action      | Approved By | Designated Signers / Group |
| :--- | :-------- | :--- | :----- | :---- | :---------------- | :----- | :---------- | :---- | :---------- | :---------- | :------------------------- |
| 1    | Any       | Tx   | Any VA | Any   | Whitelisted + OTA | \$0    | Single Tx   | Any   | Allow       | -           | Group 1                    |
| 2    | Any       | Tx   | Any    | Any   | Whitelisted + OTA | \$0    | Single Tx   | Any   | Approved By | Tywin       | -                          |

The rules in the table above state:

* Rule 1: This rule allows any single transaction from any vault account to any whitelisted destination or one-time address with an amount greater than \$0 from any asset. However, all transactions that match this rule must be signed by one of the Group 1 members.
* Rule 2: This rule allows any single transaction from any source to any whitelisted destination or one-time address with an amount greater than \$0 from any asset. However, all transactions that match this rule must be approved by Tywin.

Therefore, according to the first match principle, the API Co-signers only sign single transactions in which the source is a vault account.

#### Method 2: Excluding API Co-Signers from unsupported sources

| Rule | Initiator | Type | Source                 | Dest. | Whitelisted / OTA | Amount | Time Period | Asset | Action      | Approved By | Designated Signers / Group |
| :--- | :-------- | :--- | :--------------------- | :---- | :---------------- | :----- | :---------- | :---- | :---------- | :---------- | :------------------------- |
| 1    | Any       | Tx   | Any Exchange, Any Fiat | Any   | Whitelisted + OTA | \$0    | Single Tx   | Any   | Approved By | Tywin       | -                          |
| 2    | Any       | Tx   | Any                    | Any   | Whitelisted + OTA | \$0    | Single Tx   | Any   | Approved By | Tywin       | Group 1                    |

The rules in the table above state:

* Rule 1: This rule allows any single transaction from any exchange or any fiat account to any whitelisted destination or one-time address with an amount greater than \$0 from any asset. However, all transactions that match this rule must be approved by Tywin.
* Rule 2: This rule allows any single transaction from any source to any whitelisted destination or one-time address with an amount greater than \$0 from any asset. However, all transactions that match this rule must be approved by Tywin and then signed by one of the members from Group 1.

Therefore, according to the first match principle, the API Co-Signers only sign single transactions in which the source is not an exchange or a fiat account.

## Multiple API Co-signers deployment options

Co-signers can be deployed either in the cloud or on-premise, depending on your requirements. For example, you can implement a cluster with three Co-signers in an active-active-passive architecture as follows:

* **Active-Active Co-signers:** Two API Co-signers are deployed in separate availability zones within a cloud service provider. This configuration eliminates a single point of failure and ensures continuous operation without downtime.
* **Passive Co-signer:** A third API Co-signer is deployed on-premise as a failover. This on-premise Co-signer ensures redundancy, allowing for uninterrupted operation during updates or maintenance of the cloud-based Co-signers.

## Backup & Recovery

Backing up the API Co-signer server and data is highly recommended for streamlining machine updates or replacement processes. This backup can also be used for disaster recovery (DR), however, it is recommended to set up an additional API Co-signer in high availability (active-active) and use it if something goes wrong. You can learn more about backing up and restoring the API Co-signer by referring to one of the articles below:

* [SGX API Co-Signer Backup & Recovery](/reference/api-cosigner-maintenance-sgx#migrate-to-a-new-machine)
* [AWS Nitro API Co-Signer Backup & Recovery](/reference/api-cosigner-maintenance-aws-nitro#migrate-to-a-new-machine)

## Best practices

To ensure business continuity, install the API Co-signers in high availability using both on-prem data centers (when possible) and cloud service providers.

If only one infrastructure provider is available for hosting all the API Co-signers, follow the best practices for each cloud service provider for setting up cross-region replication and multiple API Co-signer instances on different data centers when deploying on-prem.


# Overview
Source: https://developers.fireblocks.com/docs/network-link-integration-guide-for-provider-connectivity



<Info>
  ### Want to know more about the Provider Network and commercial prerequisites?

  Visit [our Help Center article about the Provider Network](https://support.fireblocks.io/hc/en-us/articles/22144765384348) to learn more.

  See the [Fireblocks Provider Connectivity API v2 documentation](https://fireblocks.github.io/fireblocks-network-link/v2/docs.html) on GitHub to learn how to connect your service to Fireblocks.
</Info>

# Registering as a service provider

<Info>
  ### Note on the supported testing scope

  As a best practice, we recommend that your onboarding should cover only up to three stages: **Dev** → **Staging** → **Production**. Additional testing setups for supporting multiple internal environments are not supported by default and require explicit approval.
</Info>

Once your license agreement for listing your service with Fireblocks is signed, the Fireblocks technical team will request the following connected account registration settings:

1. Display name (e.g., "My Exchange" or "My Exchange Sandbox")

2. Icon (a 32x32 .svg file)

3. Step-by-step guide for generating an API key for your platform
   1. A public link to your knowledge base is preferred. A shareable document or PDF is also acceptable.

4. Base URL for your API endpoints (e.g., "[https://my-service.com/fireblocks"](https://my-service.com/fireblocks%22))

5. Will your service provide a sandbox environment?

6. For Off-Exchange capabilities, please provide your CSR file.

7. User credentials for testing

8. Which signing method will your server use for all requests? Please choose one of the supported options by specifying the pre-encoding function, signing algorithm, and post-encoding function during the server onboarding process.

   1. **Pre-encoding options:**

      1. `URL encoded`
      2. `Base64`
      3. `HexStr`
      4. `Base58`
      5. `Base32`

   2. **Signing algorithms & possible hash functions:**

      1. `HMAC (SHA512, SHA3_256, or SHA256)`
      2. `RSA PKCS1v15 (SHA512, SHA3_256, or SHA256)`
      3. `ECDSA prime256v1/secp256k1 (SHA256 only)`

   3. **Post-encoding options:** (URL encoding not supported)

      1. `Base64`
      2. `HexStr`
      3. `Base58`
      4. `Base32`

9. [Validation tool results](https://github.com/fireblocks/fireblocks-network-link/tree/main/v2/api-validator)

# Asset Mapping in Network Link v2

For Network Link v2 integrations, asset mapping is based on the provider's response to `GET/capabilities/assets`. The required fields are:

* ID (on the provider's side)
* Name (on the provider's side)
* Symbol (on the provider's side)
* Decimal places (number of decimals for the asset on the provider's side)
* Test asset (true/false)
* Type (BucketAsset, ERC20Token, BEP20Token, StellarToken, Jetton, SPLToken)

# IP allowlisting

All API calls from Fireblocks to your service are sent from a fixed set of IP addresses, grouped by geographical region. Your service should allowlist these addresses to allow Fireblocks communication with your servers.

| Singapore                                                                                                                                                                     | Europe                                                                                                                                                                                                                                                                                                                                                                                                                                                              | USA                                                                                                                                                                                     |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 18.99.36.0<br />18.99.36.1<br />18.99.36.2<br />18.99.36.3<br />18.99.36.4<br />18.99.36.5<br />18.99.36.6<br />18.99.36.7<br />18.99.36.8<br />18.99.36.9<br />52.76.208.129 | 18.98.161.0<br />18.98.161.1<br />18.98.161.2<br />18.98.161.3<br />18.98.161.4<br />18.98.161.5<br />18.98.161.6<br />18.98.161.7<br />18.98.161.8<br />18.98.161.9<br />18.98.161.10<br />18.98.161.11<br />18.98.161.12<br />18.98.161.13<br />18.98.161.14<br />18.98.161.15<br />18.98.161.16<br />18.98.161.17<br />18.98.161.18<br />18.98.161.19<br />18.133.153.74<br />3.10.68.107<br />3.64.123.47<br />18.158.242.74<br />3.10.103.242<br />3.67.233.15 | 18.97.132.0<br />18.97.132.1<br />18.97.132.2<br />18.97.132.3<br />18.97.132.4<br />18.97.132.5<br />18.97.132.6<br />18.97.132.7<br />18.97.132.8<br />18.97.132.9<br />40.117.39.160 |

# Mandatory endpoints implementation per user flow

## Minimum viable provider

* **Required`GET /capabilities` response:** "accounts": \["\*"]
* **Required endpoints:**
  * `GET /capabilities`
  * `GET /capabilities/assets`
  * `GET /accounts`
  * `GET /accounts/{accountId}`

## Balance support

* **Required`GET /capabilities` response:** "accounts": \["*"], "balances": \["*"]
* **Required endpoints:**
  * `GET /accounts/{accountId}/balances`

## Transfer support

* **Required`GET /capabilities` response:** "accounts": \["*"], "balances": \["*"], "transfers": \["\*"]
* **Required endpoints:**
  * `GET /accounts/{accountId}/capabilities/transfers/deposits`
  * `GET /accounts/{accountId}/capabilities/transfers/withdrawals`
  * `GET /accounts/{accountId}/transfers/deposits`
  * `GET /accounts/{accountId}/transfers/deposits/{id}`
  * `GET /accounts/{accountId}/transfers/withdrawals`
  * `GET /accounts/{accountId}/transfers/withdrawals/{id}`

## Blockchain transfer

* **Required`GET /capabilities` response:** "accounts": \["*"], "balances": \["*"], "transfers": \["*"], "transfersBlockchain": \["*"]
* **Required endpoints:**
  * `GET /accounts/{accountId}/capabilities/transfers/deposits`
  * `GET /accounts/{accountId}/capabilities/transfers/withdrawals`
  * `GET /accounts/{accountId}/transfers/deposits`
  * `GET /accounts/{accountId}/transfers/deposits/{id}`
  * `GET /accounts/{accountId}/transfers/withdrawals`
  * `GET /accounts/{accountId}/transfers/withdrawals/{id}`
  * `POST /accounts/{accountId}/transfers/deposits/addresses`
  * `GET /accounts/{accountId]/transfers/deposits/addresses`
  * `GET /accounts/{accountId}/transfers/deposits/addresses/{id}`
  * `POST /accounts/{accountId}/transfers/withdrawals/blockchain`

## Peer transfer

* **Required`GET /capabilities` response:** "accounts": \["*"], "balances": \["*"], "transfers": \["*"], "transfersPeerAccounts": \["*"]
  * For fiat assets, add "transfersFiat": \["\*"] to the response.
* **Required endpoints:**
  * `GET /accounts/{accountId}/capabilities/transfers/deposits`
  * `GET /accounts/{accountId}/capabilities/transfers/withdrawals`
  * `GET /accounts/{accountId}/transfers/deposits`
  * `GET /accounts/{accountId}/transfers/deposits/{id}`
  * `GET /accounts/{accountId}/transfers/withdrawals`
  * `GET /accounts/{accountId}/transfers/withdrawals/{id}`
  * `POST /accounts/{accountId}/transfers/withdrawals/peeraccount`

## Internal transfer

* **Required`GET /capabilities` response:** "accounts": \["*"], "balances": \["*"], "transfers": \["*"], "transfersInternal": \["*"]
  * For fiat assets, add "transfersFiat": \["\*"] to the response.
* **Required endpoints:**
  * `GET /accounts/{accountId}/capabilities/transfers/deposits`
  * `GET /accounts/{accountId}/capabilities/transfers/withdrawals`
  * `GET /accounts/{accountId}/transfers/deposits`
  * `GET /accounts/{accountId}/transfers/deposits/{id}`
  * `GET /accounts/{accountId}/transfers/withdrawals`
  * `GET /accounts/{accountId}/transfers/withdrawals/{id}`
  * `POST /accounts/{accountId}/transfers/withdrawals/subaccount`

## Fiat transfer

* **Required`GET /capabilities` response:** "accounts": \["*"], "balances": \["*"], "transfers": \["*"], "transfersFiat": \["*"]
* **Required endpoints:**
  * `GET /accounts/{accountId}/capabilities/transfers/deposits`
  * `GET /accounts/{accountId}/capabilities/transfers/withdrawals`
  * `GET /accounts/{accountId}/transfers/deposits`
  * `GET /accounts/{accountId}/transfers/deposits/{id}`
  * `GET /accounts/{accountId}/transfers/withdrawals`
  * `GET /accounts/{accountId}/transfers/withdrawals/{id}`
  * `POST /accounts/{accountId}/transfers/withdrawals/fiat`

## Liquidity/RFQ support

* **Required`GET /capabilities` response:** "accounts": \["*"], "balances": \["*"], "liquidity": \["\*"]
* **Required endpoints:**
  * `GET /capabilities/liquidity/quotes`
  * `POST /accounts/{accountId}/liquidity/quotes`
  * `GET /accounts/{accountId}/liquidity/quotes`
  * `GET /accounts/{accountId}/liquidity/quotes/{id}`
  * `POST /accounts/{accountId}/liquidity/quotes/{id}/execute`

## On-/Off-Ramp & Bridging

* **Required`GET /capabilities` response:** "accounts": \["*"], "ramps": \["*"], "balances": \["\*"]
  * For prefunded flows, "balances": \["\*"] must be returned with `GET` account API. See below.
* **Required endpoints:**
  * `GET /accounts/{accountId}/capabilities/ramps`
  * `POST /accounts/{accountId}/ramps`
  * `GET /accounts/{accountId}/ramps`
  * `GET /accounts/{accountId}/ramps/{id}`
  * `GET /accounts/{accountId}/balances` (only for prefunded flows)
  * `GET /accounts/{accountId}/rate`
    * Your service should implement the `rate` endpoint to ensure Fireblocks customers see your service's real-time rates for asset pairs. Otherwise, Fireblocks defaults to quotes or its internal rating service.

## Collateral

<Info>
  ### **Note:**

  In addition to implementing the endpoints below, providers supporting Collateral/Off-Exchange flows must also integrate with the Fireblocks Off-Exchange API. This is required for reporting events from the provider back to Fireblocks (e.g., confirming deposits or settlements).

  Technical Reference: [Fireblocks Off-Exchange - Exchange to Fireblocks](https://fireblocks.github.io/fireblocks-off-exchange/#tag/Exchange-to-Fireblocks)
</Info>

The provider should also use this [endpoint](https://fireblocks.github.io/fireblocks-off-exchange/#tag/Exchange-to-Fireblocks).

* **Required`GET /capabilities` response:** "accounts": \["*"], "balances": \["*"], "transfers": \["*"], "transfersBlockchain": \["*"], "collateral": \["\*"]
* **Required endpoints:**
  * `GET /accounts/{accountId}/balances`
  * `GET /accounts/{accountId}/capabilities/transfers/deposits`
  * `GET /accounts/{accountId}/capabilities/transfers/withdrawals`
  * `GET /accounts/{accountId}/transfers/deposits`
  * `GET /accounts/{accountId}/transfers/deposits/{id}`
  * `GET /accounts/{accountId}/transfers/withdrawals`
  * `GET /accounts/{accountId}/transfers/withdrawals/{id}`
  * `POST /accounts/{accountId}/transfers/deposits/addresses`
  * `GET /accounts/{accountId}/transfers/deposits/addresses`
  * `GET /accounts/{accountId}/transfers/deposits/addresses/{id}`
  * `POST /accounts/{accountId}/transfers/withdrawals/blockchain`
* **Collateral endpoints:**
  * `POST accounts/{accountId}/collateral/link`
  * `GET accounts/{accountId}/collateral/link`
  * `POST accounts/{accountId}/collateral/{collateralId}/addresses`
  * `GET accounts/{accountId}/collateral/{collateralId}/addresses`
  * `GET accounts/{accountId}/collateral/{collateralId}/addresses/{id}`
  * `POST accounts/{accountId}/collateral/{collateralId}/intents/deposits`
  * `POST accounts/{accountId}/collateral/{collateralId}/deposits`
  * `GET accounts/{accountId}/collateral/{collateralId}/deposits`
  * `GET accounts/{accountId}/collateral/{collateralId}/deposits/{collateralTxId}`
  * `POST accounts/{accountId}/collateral/{collateralId}/intents/withdrawals`
  * `POST accounts/{accountId}/collateral/{collateralId}/withdrawals`
  * `GET accounts/{accountId}/collateral/{collateralId}/withdrawals`
  * `GET accounts/{accountId}/collateral/{collateralId}/withdrawals/{collateralTxId}`
  * `POST accounts/{accountId}/collateral/{collateralId}/settlement`
  * `GET accounts/{accountId}/collateral/{collateralId}/settlement`
  * `GET accounts/{accountId}/collateral/{collateralId}/settlements/{settlementVersion}`


# Fireblocks Object Model
Source: https://developers.fireblocks.com/docs/object-model

The Fireblocks platform can be viewed as consisting of the following components:

<img alt="" />

### Fireblocks Workspace

Each unique instance of Fireblocks is called a *workspace*.

### Vault accounts

A Vault account is an easy way to separate and maintain security boundaries across assets.

Vault accounts store your asset wallets on the Fireblocks platform. Any user with the appropriate permissions can create a vault account since that is not a workspace action that requires approval.

The Vault structure for your application you're building on top of Fireblocks can either be 'Segregated' or 'Omnibus'.

#### **Segregated**

With this vault structure, each user of your application is assigned individual vault accounts.

* For example, you may have vault accounts labeled as **User #1, User #2, User #3, etc...** each of which maps to a user of the application you are building on top of Fireblocks.

#### **Omnibus**

With this vault structure, all users of your application are assigned one, or several, centralized vault accounts.

* For example, you may have a single vault account labeled as **Omnibus**, where all of your user's funds and assets are swept for a single withdrawal.

### Vault wallets

Vault wallets are used to manage internal deposit addresses. Each vault wallet contains at least one deposit address for its asset type.

Each vault account can hold any number of assets supported by Fireblocks, including multiple deposit addresses for blockchains that support it, such as UTXO-based chains like BTC. Depending on the asset type, different wallets may support multiple address types or formats. Each vault wallet is assigned to a single digital asset supported by Fireblocks.

Your workspace contains multiple assets from different blockchains. You can use one of the existing assets or add a new asset to your workspace and use it as an vault wallet.

[Learn how to create vault accounts and vault wallets using the Fireblocks API.](/docs/create-direct-custody-wallets)

### Exchange accounts

To transfer funds securely to/from exchanges, you'll need to integrate an exchange account by adding your API credentials for those exchanges.

### Fiat accounts

To transfer fiat through one of our integrated fiat providers, you need to explicitly add your fiat provider's API credentials within your desired workspace fiat account.

### Whitelisted/Unmanaged wallets

<Info>
  ### Note:

  The terms "**whitelisted wallets**" and "**unmanaged wallets**" are used interchangeably to describe wallets that are external and not under Fireblocks' management. In certain areas of the system, such as the API and Webhooks, these wallets are referred to as unmanaged wallets.
</Info>

Whitelisted or unmanaged wallets are an additional security measure for interacting with various blockchain addresses. They can be named how you prefer and marked as either 'internal', 'external', or 'contract'.

* **Internal wallet** - a deposit address existing inside your organization.
* **External wallet** - a deposit address existing outside your organization.
* **Contract wallet** - a deposit address of an on-chain smart contract.

  <Info>
    ### Note:

    This only applies to smart contracts on EVM-compatible blockchains.
  </Info>


# Off Exchange
Source: https://developers.fireblocks.com/docs/off-exchange



# Overview

Fireblocks is the digital asset management infrastructure for the leading trading desks, hedge funds, brokerages, custodians, and banks. Through the Fireblocks Console, users connect and trade on over 30 exchanges. As part of an important initiative, making sure that the end user still has complete control over his own asset Fireblocks offers the Off Exchange solution. This way ,the end user can enjoy the various benefits of the exchange while avoiding the risk of a centralized malfunction.

Benefits:

* Complete end user control
* Provide a trustable relationship, where the customer safely continues his work with the exchange
* Control rate limits and response codes
* Manage the supported assets
* Optimize the platform load for requests from Fireblocks

[Read the Fireblocks Off-Exchange official documentation](https://fireblocks.github.io/fireblocks-off-exchange/)

# Official Public Keys

Use the following key(s) to validate requests received from Fireblocks on Off-Exchange:

## Development Testing

```yaml theme={"system"}
-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAtug0j82+C1WCcqCPEzEm
sao1kH4gIDHewI06SsiB1aIdZ/v+I/PTRTYhKC0JVtsio+KeF/YDWI3c1RZrMa9/
7yOoQ8QNNG0U65q2//LoSz3He6E9/7b5V+BrQwvCHPOv4kp+un9bZ23BqvX+jgJQ
aKTvjEeBUW6fOh2oupRGH51teBcQpmgPFP1b26BGFSiGBdyB1OX6qYchIv5C/XW/
d3NoOUD96kEMEsDUKCvXwPp5gelqZQoaGZZatE5AllFdJJQKXU8DWDXTJMSyxIIY
rzx6S5RToDDK/Z7SKG4k8q1pd6pViNe88DJYV6kJdSgiYThl07sATWo+6Ev6nFSo
z69Jx+BWx5v2aLJfc6ghuN7j5dOBtex+tklHMw0s1XCiE14Pyi6px9dNNJApp6wM
LIDmMeKTZ65ar22q5ySgrNQHvVOy66zRZhfOu5fueSPa4C3CBoarCpiUIQTVNzf5
AA3qBKfunIUqHYNzdvPt/MwQErW1G9XPxGC+az0Cc4qEmICUSlYiFC1BLD6YKpjP
MsPkuj2d9MYfDUQktt1IKsWOTE6NNVzmYpbZkA7TD6hcqd7rV6Zf5TcK9vvEB1V5
F0jJYUdNXygdzKOwY/OlQ0eoF5vb6XU46y24cCnKgJ23ZfdLJJrFOdpbEaooErhn
37BWbAWH9EpcHM9pFNUYOhkCAwEAAQ==
-----END PUBLIC KEY-----
```

## Production Testing

```yaml theme={"system"}
-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA9JxE/VqDSCnUD5030Ufm
CoTiOtbLGRGZ6XK1KNhtD1c0MQUtiHoCCcAmmyOlTuemaPjrscGFOdITeubEPoO1
+smHziM2LkzSgtOwdgTXA+pYxnMe9lDXCtgD5mRRUQB6IqsqZN8bJcG+VuF/mMZy
qkuUIskrjJ+kn0ZfiR0PHVYkaUzvHhmyB8ZxrQTOWLB7H+62g7ZBI1U1cOcyHnSH
HVh0TpZ573fztqQS3ECGeCnpo6jQEfBeCvwx5sBkum+3iWl9VDwXIlyjcodlYqD1
YmrYrSPJwpQlxv9zUw2LarwJU+uv3EmIRKyQdxsHO8tcXGDy6WWl/zUNw1nu6uLd
kCteOJUT/SX0QlxizLFE02AAEW0hBNT0KHhD5GVN0QRkWfAJTxLSajqKEeg7M2KO
0xfh+PMEeEOzIc3GC5xv/oJ3tFt7ZawbU19WpifUcBiU2r4HLPaijxN7K9bZIfUt
K5maCIATuqn1U05G0zXUvkgZ64fHBzwtMl3grp5t6++QiH3fShBD+hUQmPoTV9p3
vgPtigK2+USPyJVwa22YplY96XckkBToOcrvYZc710gpTRwFjQdJ/DfrUYqh4UaV
7k/n9sCDRM3sM353tMAmr6dFYHKN5OwviKD2t9RNMa3j67wqHAeLimFvAM8fMe5I
aNSwkiUjHhlLPOqPhhXl3U8CAwEAAQ==
-----END PUBLIC KEY-----
```


# On/Off-Ramp, and cross-chain Swap via CeFi
Source: https://developers.fireblocks.com/docs/on-ramp-off-ramp-and-bridgeswap-via-account-based-providers-cefi



<Info>
  ### **Beta Feature**

  The Trading API is currently in beta and subject to change. For participation details, contact your Fireblocks Customer Success Manager or email [CSM@fireblocks.com](mailto:CSM@fireblocks.com).
</Info>

This guide provides step-by-step examples of how to execute various order operations using the Fireblocks Trading API via account-based providers. These require you to connect an account before trading. For instructions on how to connect accounts, see [Fireblocks Connected Accounts](https://support.fireblocks.io/hc/en-us/articles/360017435399-Fireblocks-connected-accounts). This guide covers multiple use cases including on-ramp (fiat to crypto), off-ramp (crypto to fiat), and bridging (crypto-to-crypto).

## Prerequisites

Before you begin, ensure you have completed the prerequisites outlined in the [Trading API Overview](/docs/trading-api-overview#/):

* ✅ Fireblocks API credentials configured
* ✅ Fireblocks TypeScript SDK installed (`@fireblocks/version 13.x or later`)
* ✅ Connected account(s) set up with your chosen provider(s) via the Fireblocks Console (see [Fireblocks Connected Accounts](https://support.fireblocks.io/hc/en-us/articles/360017435399-Fireblocks-connected-accounts) for setup instructions)

## SDK Setup

First, set up your Fireblocks SDK client:

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  import { Fireblocks } from '@fireblocks/ts-sdk';
  import * as fs from 'fs';

  // Initialize the Fireblocks SDK
  const fireblocks = new Fireblocks({
    apiKey: 'your-api-key',
    secretKey: fs.readFileSync('/path/to/your/secret.key', 'utf8'),
    basePath: 'https://api.fireblocks.io',
  });
  ```
</CodeGroup>

## Provider and account discovery

Before trading with account-based providers, find out which providers are available and which accounts you have connected. If you haven't connected any accounts yet, see [Fireblocks Connected Accounts](https://support.fireblocks.io/hc/en-us/articles/360017435399-Fireblocks-connected-accounts) for setup instructions.

### Step 1: Get Providers and Connected Accounts

Retrieve all trading providers. For account-based providers, the response includes provider information and connected accounts, allowing you to extract both `providerId` and `accountId` in a single call.

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  // Get all trading providers
  const response = await fireblocks.trading.getTradingProviders({ pageSize: 20 });

  // Filter for account-based providers
  const accountBasedProviders = response.data.data.filter(p => p.accountBased);

  // Access provider and account information
  for (const provider of accountBasedProviders) {
    console.log(`Provider: ${provider.id} (${provider.name})`);
    provider.accounts?.forEach(account => {
      console.log(`  Account: ${account.id} (${account.name})`);
    });
  }
  ```
</CodeGroup>

### Response Example

<CodeGroup>
  ```json JSON theme={"system"}
  {
    "data": [
      {
        "id": "ALFREDPAY",
        "name": "Alfred Pay",
        "accountBased": true,
        "connected": true,
        "accounts": [
          {
            "id": "acc_5e9a2d1c4b7f3e8a",
            "name": "My Alfred Pay Account"
          }
        ],
        "manifest": {
          "assetTypes": ["FIAT", "DIGITAL"],
          "capabilities": ["TRADING"]
        }
      },
      {
        "id": "YELLOWCARD",
        "name": "Yellow Card",
        "accountBased": true,
        "connected": true,
        "accounts": [
          {
            "id": "acc_9f4e2d8b1c6a5e73",
            "name": "Yellow Card Main Account"
          }
        ],
        "manifest": {
          "assetTypes": ["FIAT", "DIGITAL"],
          "capabilities": ["TRADING"]
        }
      }
    ],
    "total": 2,
    "next": null
  }
  ```
</CodeGroup>

### Key Fields Explained

| Field          | Description                                                                                                                     |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `id`           | Unique identifier for the provider (use as `providerId` in subsequent API calls)                                                |
| `name`         | Display name of the provider                                                                                                    |
| `accountBased` | `true` for account-based providers, `false` for direct access providers                                                         |
| `connected`    | Whether you have at least one connected account with this provider                                                              |
| `accounts`     | Array of connected accounts for this provider. Each account has an `id` (use as `accountId` in subsequent API calls) and `name` |

<Info>
  ### For more details about this endpoint, see the [Get Providers API Reference](/reference/gettradingproviders).
</Info>

### Step 2: Get Supported Trading Pairs

For each connected account, discover which trading pairs are supported:

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  // Get supported trading pairs for a specific connected account
  const response = await fireblocks.trading.getTradingPairs({
    accountId: 'acc_9f4e2d8b1c6a5e73',
  });

  // Response data
  const tradingPairs = response.data;
  // tradingPairs = [
  //   {
  //     "id": "7c9e8f2a-4b5d-4e1c-9a3b-6f8d2e5c7a1b",
  //     "toAsset": "USDC",
  //     "fromAsset": "USD",
  //     "prefunded": false,
  //     "fromAssetRail": "ACH"
  //   }
  // ]
  ```
</CodeGroup>

### Step 3: Get Indicative Rates

Get indicative rates for price preview (these are not executable quotes):

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  // Get indicative rates
  const response = await fireblocks.trading.getRates({
    accountId: 'acc_9f4e2d8b1c6a5e73',
    baseAssetId: 'USD',
    quoteAssetId: 'BTC',
  });
  const rates = response.data;
  ```
</CodeGroup>

<Info>
  ### **Note:** Rates provide indicative prices for preview, while quotes return committed rates that can be executed until expiration.
</Info>

## Clarification on how to translating user intent into baseAssetId, quoteAssetId, side, and baseAmount

When creating a **Quote** or an **Order**, you express the trade using:

* `baseAssetId`: the asset you **receive** on **BUY** / **give** on **SELL**
* `quoteAssetId`: the counter asset used to **pay**/**receive**
* `side`:
  * `BUY`: receive base / pay quote
  * `SELL`: give base / receive quote
* `baseAmount`: amount in `baseAssetId`
  * `BUY`: base amount to receive
  * `SELL`: base amount to sell

### Examples

| Intent                  | baseAssetId | quoteAssetId | side | baseAmount |
| ----------------------- | ----------- | ------------ | ---- | ---------- |
| Buying 100 BTC with USD | BTC         | USD          | BUY  | 100        |
| Buying 100 USD with BTC | USD         | BTC          | BUY  | 100        |
| Selling 100 BTC for USD | BTC         | USD          | SELL | 100        |
| Selling 100 USD for BTC | USD         | BTC          | SELL | 100        |

## Participants & compliance

Participant details vary by provider and rail. The `participantsIdentification` object defines the originator and beneficiary involved in an order.

### Example structure

```json theme={"system"}
{
  "participantsIdentification": {
    "originator": {
      "externalReferenceId": "user_123",
      "participantRelationshipType": "FirstParty",
      "entityType": "INDIVIDUAL"
    },
    "beneficiary": {
      "participantRelationshipType": "ThirdParty",
      "fullName": {
        "firstName": "Alice",
        "lastName": "Lee"
      }
    }
  }
}
```

### Key concepts

* **First-party**: Acting for self — provider already holds KYC; minimal data required.
* **Third-party**: Acting for another — provider may require full PII.

The level of PII data required depends on the provider and the relationship type (first-party vs. third-party).

## Use Case Examples

The following sections demonstrate different trading use cases with account-based providers:

## Use Case 1: On-Ramp - DVP Settlement with Market Execution

**Use Case:** Convert fiat to crypto at the market rate. The user creates the order, receives payment instructions from the provider, deposits the funds, and once payment is confirmed, the provider executes and settles the crypto, ensuring delivery versus payment (DVP).

**Settlement Type:** DVP (Delivery vs Payment)\
**Execution Type:** Market

<Callout icon="📖">
  ### **Note:** The `baseAssetId`, `baseAssetRail`, `quoteAssetId`, and `quoteAssetRail` values used in the order must match a supported trading pair returned from the `getTradingPairs` endpoint (see Step 2 in Getting Started). This ensures the provider supports the specific asset and rail combination you're requesting.
</Callout>

### Step 1: Create the Order

```typescript theme={"system"}
// Create on-ramp order with DVP settlement and market execution
const response = await fireblocks.trading.createOrder({
  createOrderRequest: {
    via: {
      type: 'PROVIDER_ACCOUNT',
      providerId: 'bridge-provider-001',
      accountId: 'acc_9f4e2d8b1c6a5e73',
    },
    executionRequestDetails: {
      type: 'MARKET',
      side: 'BUY',
      baseAmount: '1000',
      baseAssetId: 'USD',
      baseAssetRail: 'ACH',
      quoteAssetId: 'USDC',
      quoteAssetRail: 'BLOCKCHAIN',
    },
    settlement: {
      type: 'DVP',
      sourceAccount: {
        type: 'EXTERNAL',
      },
      destinationAccount: {
        type: 'ONE_TIME_ADDRESS',
        address: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa',
      },
    },
    participantsIdentification: {
      originator: {
        entityType: 'BUSINESS',
        participantRelationshipType: 'FirstParty',
      },
      beneficiary: {
        entityType: 'INDIVIDUAL',
        participantRelationshipType: 'ThirdParty',
        fullName: {
          lastName: 'Johnson',
          firstName: 'Alexander',
        },
        postalAddress: {
          streetName: 'Fifth Avenue',
          buildingNumber: '350',
          postalCode: '10118',
          city: 'New York',
          subdivision: 'NY',
          district: 'Manhattan',
          country: 'US',
        },
        externalReferenceId: 'person_ref_7f3e2d1c4b8a5e9f',
        dateOfBirth: '1985-03-15',
      },
    },
    customerInternalReferenceId: '32e423',
  },
  idempotencyKey: `order-${Date.now()}`,
});

const order = response.data;
```

### Step 2: Handle Payment Instructions

Since the settlement type is DVP and the source type is EXTERNAL, the funds will move from outside Fireblocks. The order creation response will include payment instructions for the rail which you select (e.g., ACH, SEPA, Wire):

```json theme={"system"}
{
  "paymentInstructions": {
    "referenceId": "REF-ACH-001",
    "type": "ACH",
    "address": {
      "accountHolder": {
        "name": "Bridge Provider Ltd.",
        "address": "123 Main Street",
        "city": "New York",
        "country": "US",
        "subdivision": "NY",
        "postalCode": "10001"
      },
      "bankName": "JPMorgan Chase Bank N.A.",
      "bankAccountNumber": "9876543210",
      "routingNumber": "021000021",
      "accountType": "CHECKING"
    }
  }
}
```

### Considerations

* For third-party payouts, like the one in the example, the provider must receive the beneficiary details (PII as required by the provider). In this case, you are the originator — acting as a first party, already KYC'd with the provider. Therefore, the only data needed is to set the `beneficiary.participantRelationshipType = "FirstParty"`.
* Since the settlement type is DVP and the source type is EXTERNAL, the funds will move from outside Fireblocks. As a result, the order creation response will include payment instructions for the rail which you select (e.g., ACH, SEPA, Wire).

## Use Case 2: On-Ramp - Prefunded settlement with quote execution

**Use Case:** Convert fiat to crypto at a locked rate from a committed quote. Funds are already held in the account; no payment instructions are returned in the response, and the provider will execute and settle the request immediately.

**Settlement Type:** Prefunded\
**Execution Type:** Quote

### Step 1: Create a Quote

```typescript theme={"system"}
// Create a quote for on-ramp
const quoteResponse = await fireblocks.trading.createQuote({
  createQuote: {
    scope: [
      {
        providerId: 'SCRYPT',
        accountId: 'scrypt_acc_5e9a2d1c4b7f3e8a',
      },
    ],
    side: 'BUY',
    baseAssetId: 'USDT_ERC20',
    quoteAssetId: 'TRX_USDT_S2UZ',
    baseAmount: '15000',
  },
  idempotencyKey: `quote-${Date.now()}`,
});

const quote = quoteResponse.data.quotes[0];
```

In the quote response, you will receive all related metadata, including the quote ID (`id`) and expiration time (`expiresAt`). The quote ID is then used in the next step to create an order and execute the trade.

### Step 2: Execute order with quote

```typescript theme={"system"}
// Execute order using the quote from Step 1
const response = await fireblocks.trading.createOrder({
  createOrderRequest: {
    via: {
      type: 'PROVIDER_ACCOUNT',
      accountId: 'acc_5e9a2d1c4b7f3e8a',
      providerId: 'ALFREDPAY',
    },
    executionRequestDetails: {
      type: 'QUOTE',
      reQuote: {
        type: 'MARKET',
      },
      quoteId: 'quote_8f2e4d1a9c5b7e3f',
    },
    settlement: {
      type: 'PREFUNDED',
      destinationAccount: {
        type: 'VAULT_ACCOUNT',
        accountId: 'vault_acc_9f3e2d1c4b8a7e5f',
      },
    },
    participantsIdentification: {
      originator: {
        entityType: 'INDIVIDUAL',
        participantRelationshipType: 'FirstParty',
      },
      beneficiary: {
        entityType: 'INDIVIDUAL',
        participantRelationshipType: 'FirstParty',
      },
    },
  },
  idempotencyKey: `order-${Date.now()}`,
});

const order = response.data;
```

### Considerations

* In this example, you perform an on-ramp for yourself, not for a third-party recipient. Therefore, both the originator and beneficiary use `"participantRelationshipType": "FirstParty"`, and no additional PII data is required.
* The `quoteId` used in the order request is the same ID returned in the response from the `POST /trading/quotes` call.

## Use Case 3: Off-Ramp - DVP settlement with market execution

**Use Case:** Convert crypto to fiat at the market rate. The provider waits for confirmation of the crypto deposits before finalizing the settlement, ensuring delivery versus payment (DVP).

**Settlement Type:** DVP\
**Execution Type:** Market

<Callout icon="📖">
  ### **Note:** The `baseAssetId`, `baseAssetRail`, `quoteAssetId`, and `quoteAssetRail` values used in the order must match a supported trading pair returned from the `getTradingPairs` endpoint (see Step 2 in Getting Started). This ensures the provider supports the specific asset and rail combination you're requesting.
</Callout>

### Step 1: Create the Order

```typescript theme={"system"}
// Create off-ramp order with DVP settlement and market execution
const response = await fireblocks.trading.createOrder({
  createOrderRequest: {
    via: {
      type: 'PROVIDER_ACCOUNT',
      providerId: 'YELLOWCARD',
      accountId: 'acc_9f4e2d8b1c6a5e73',
    },
    executionRequestDetails: {
      type: 'MARKET',
      side: 'BUY',
      baseAmount: '250',
      baseAssetId: 'XOF',
      baseAssetRail: 'LOCAL_BANK_TRANSFER_AFRICA',
      quoteAssetId: 'USDT_ERC20',
      quoteAssetRail: 'BLOCKCHAIN',
    },
    settlement: {
      type: 'DVP',
      sourceAccount: {
        type: 'VAULT_ACCOUNT',
        accountId: 'vault_acc_5e9a2d1c4b7f3e8a',
      },
      destinationAccount: {
        type: 'EXTERNAL_WALLET',
        accountId: 'fiat_whitelisted_acc_9f3e2d1c4b8a7e5f',
      },
    },
    participantsIdentification: {
      originator: {
        entityType: 'INDIVIDUAL',
        participantRelationshipType: 'FirstParty',
      },
      beneficiary: {
        entityType: 'INDIVIDUAL',
        participantRelationshipType: 'FirstParty',
      },
    },
  },
  idempotencyKey: `order-${Date.now()}`,
});

const order = response.data;
```

### Considerations

* In this example, you perform an off-ramp for yourself, not for a third-party recipient. Therefore, both the originator and beneficiary use `"participantRelationshipType": "FirstParty"`, and no additional PII data is required.
* In this example, you chose to use a whitelisted account as the destination fiat account type. This allows you to register and manage external bank accounts (and also crypto addresses) directly within Fireblocks, ensuring secure, verified destinations that can be safely reused for future orders and transactions.
* Since the source of this order is a Vault Account, once the provider receives the order request, a transfer request will be automatically created from your vault to the provider. You will then need to approve and sign this transfer in accordance with the workspace's policy rules before the order can be executed.

## Use Case 4: Bridging (Crypto-to-Crypto) - DVP settlement with quote execution

**Use Case:** Execute a cross-chain bridging operation through the provider's connected accounts. In this flow, the user swaps USDT on Ethereum for USDT on Tron using their Scrypt provider account.

**Settlement Type:** DVP\
**Execution Type:** Quote

### Step 1: Create a Quote

```typescript theme={"system"}
// Create a quote for crypto-to-crypto bridging
const quoteResponse = await fireblocks.trading.createQuote({
  createQuote: {
    scope: [
      {
        providerId: 'SCRYPT',
        accountId: 'scrypt_acc_5e9a2d1c4b7f3e8a',
      },
    ],
    side: 'BUY',
    baseAssetId: 'USDT_ERC20',
    quoteAssetId: 'TRX_USDT_S2UZ',
    baseAmount: '15000',
  },
  idempotencyKey: `quote-${Date.now()}`,
});

const quote = quoteResponse.data.quotes[0];
```

In the quote response, you will receive all related metadata, including the quote ID (`id`) and expiration time (`expiresAt`). The quote ID is then used in the next step to create an order and execute the trade.

### Step 2: Execute Order with Quote

```typescript theme={"system"}
// Execute bridging order using the quote from Step 1
const response = await fireblocks.trading.createOrder({
  createOrderRequest: {
    via: {
      type: 'PROVIDER_ACCOUNT',
      providerId: 'SCRYPT',
      accountId: 'scrypt_acc_5e9a2d1c4b7f3e8a',
    },
    executionRequestDetails: {
      type: 'QUOTE',
      reQuote: {
        type: 'MARKET',
      },
      quoteId: 'quote_khge4d1a9c5bmvby',
    },
    settlement: {
      type: 'DVP',
      sourceAccount: {
        type: 'VAULT_ACCOUNT',
        accountId: 'vault_acc_5e9a2d1c4b7f3e8a',
      },
      destinationAccount: {
        type: 'VAULT_ACCOUNT',
        accountId: 'vault_acc_5e9a2d1c4b7f3e8a',
      },
    },
    participantsIdentification: {
      originator: {
        entityType: 'INDIVIDUAL',
        participantRelationshipType: 'FirstParty',
      },
      beneficiary: {
        entityType: 'INDIVIDUAL',
        participantRelationshipType: 'FirstParty',
      },
    },
  },
  idempotencyKey: `order-${Date.now()}`,
});

const order = response.data;
```

### Considerations

* In this example, you perform bridging via a connected account for yourself, not for a third-party recipient. Therefore, both the originator and beneficiary use `"participantRelationshipType": "FirstParty"`, and no additional PII data is required.
* The `quoteId` used in the order request is the same ID returned in the response from the `POST /trading/quotes`call.
* Since the source of this order is a Vault Account, once the provider receives the order request, a transfer will automatically be initiated from your Vault Account to the provider's connected account on Scrypt. This transfer is governed by the workspace's Transfer Policy, just like any other transfer in Fireblocks.
* **ReQuote Option:** Instead of `"type": "MARKET"`, you can use `"type": "RETRY"` with `count` (1-10 retry attempts) and optional `slippageBps` (slippage tolerance in basis points) to automatically retry quote generation if the original quote expires, giving you more control over price execution.

## Order Tracking & Monitoring

After creating an order, monitor its execution status to track completion.

### Polling for order status

```typescript theme={"system"}
// Get order status and details
const response = await fireblocks.trading.getOrder({
  orderId: 'order_id_here',
});

const order = response.data;
// Check: order.status, order.executionSteps, order.createdAt, etc.
```

### Order Status Values

| Status                | Description                                      |
| --------------------- | ------------------------------------------------ |
| `CREATED`             | Order has been created and is being processed    |
| `AWAITING_PAYMENT`    | Waiting for payment to be received               |
| `PENDING_USER_ACTION` | Requires user action (e.g., approval in console) |
| `PROCESSING`          | Order is being executed                          |
| `COMPLETED`           | Order has been successfully completed            |
| `FAILED`              | Order execution failed                           |
| `CANCELED`            | Order was canceled                               |

<Callout icon="📖">
  ### **Note:** FAILED, COMPLETED and CANCELED are terminal states.
</Callout>

### Webhooks

Subscribe to order-update events through the Fireblocks Webhooks API. See the [Fireblocks Webhooks API documentation](/) for more details.

## Additional Resources

* [Trading API Overview](/docs/trading-api-overview)
* [Bridging via Direct Access Providers (DeFi)](/docs/swap-via-direct-access-providers-defi) - For crypto-to-crypto bridging using direct access providers like Uniswap
* Fireblocks SDKs: [Python](https://pypi.org/project/fireblocks/) | [TypeScript](https://www.npmjs.com/package/@fireblocks/ts-sdk) | [Java](https://central.sonatype.com/artifact/com.fireblocks.sdk/fireblocks-sdk/overview)
* [Fireblocks Developer Portal](/)

## Support

For questions or issues with the Trading API:

* Contact your Fireblocks [Customer Success Manager](https://support.fireblocks.io/hc/en-us/requests/new?ticket_form_id=6947882197532)
* Email: [CSM@fireblocks.com](mailto:CSM@fireblocks.com)
* Check the [Fireblocks Developer Portal](/) for updates


# Overview
Source: https://developers.fireblocks.com/docs/overview



<Info>
  ### Unsure about which custody model is right for you?

  Read our “[Guide to Digital Asset Wallets and Service Providers](https://www.fireblocks.com/a-guide-to-digital-asset-wallets-and-service-providers)” for insights into evaluating digital asset wallet and service providers for your business
</Info>

# Overview

Fireblocks provides customers with an option to choose what custody model works best for their use case. In this guide we will outline the main technical and conceptual differences between Embedded Wallets and Direct Custody wallets.

Following are the main differences between direct custody and Embedded Wallets wallets in Fireblocks.

1. Direct custody wallets use a 3-of-3 multi-party computation (MPC) signature scheme while Embedded Wallets wallets use a 2-of-2 signature scheme.
2. There is only one master key per workspace for direct custody wallets, while each Embedded Wallets wallet has its own master key.
3. UTXO-based assets, such as BTC, can have multiple deposit addresses per wallet per vault account for direct custody wallets. For Embedded Wallets wallets, one wallet can have multiple accounts while each account can hold only 1 BTC address.
4. The Fireblocks Network and exchange integrations are supported for direct custody wallets only.

# Direct Custody Wallets

## Structure

<img alt="" />

* The main section of the workspace is the Fireblocks Vault which holds all MPC wallets.
* Inside the Vault, an unlimited number of vault accounts can be created. This allows to segregate between distinct clients and various use cases.
* Each vault account can hold as many asset wallets as you need. However, you can only have one wallet per asset.
* In a vault account, asset wallets can accommodate numerous deposit addresses for UTXO-based assets, while account-based assets are assigned with a single address.

## Secret key management and wallet derivation

<img alt="" />

Each vault account is identified by its *vault account ID*. This identifier is used for derivation of the asset wallets in a specific vault account.

Using one master key (split into three key shards) for the entire workspace, you can create an unlimited number of vault accounts. The vault account ID acts as the account value of the derivation path.

Each asset within this specific Vault would be derived according to the following structure: m/purpose/coinType/account/change/index.

* **m**: master private key
* **purpose**: the derivation standard (BIP44 in our example)
* **coinType**: the unique identifier of an asset (0 for BTC, 60 for ETH, etc.)
* **account**: the vault account ID
* **change**: always 0
* **index**: the address index (always 0 except for UTXO based assets such as Bitcoin)

# Embedded Wallets

## Structure

<img alt="" />

Fireblocks Embedded Wallets wallets can be used in parallel with direct custody wallets. One workspace can support both structures. However, Fireblocks strongly recommends splitting the direct custody and the Embedded Wallets parts of your business into two different workspaces due to some settings that are shared by both types of wallets in the same workspace.

Fireblocks Embedded Wallets wallets use 2-of-2 MPC signature scheme. One key share is stored within an Intel SGX-enabled server managed by Fireblocks, and the second key share is stored on the end user's device.

## Secret key management and wallet derivation

<img alt="" />

The derivation for Embedded Wallets wallets is almost the exact same as the derivation for direct custody wallets. The main difference is that each Embedded Wallets wallet will have its own master key, which is split into two key shards. In a single Embedded Wallets wallet, you can create an unlimited number of accounts while each account can have only one supported asset per asset type.


# Define Payment Flows
Source: https://developers.fireblocks.com/docs/payment-flows-copy



# What are Payment Flows?

Fireblocks empowers you to leverage blockchains and digital rails for efficient, dependable, and predictable payments. The Payments feature in Fireblocks enables the creation of secure, dynamic payment flows that consist of various actions within a single solution.

Payment flows allow you to streamline and automate your payment transactions. By configuring and executing payments directly from the Payments page in the Fireblocks Console or via the [Fireblocks API](/reference/createflowconfiguration) , you can manage various types of financial operations with ease and precision.

# How does it work?

The Payments API involves two resources.

* **Workflow Configuration (WC):** This resource acts as a template for your payment flow. It contains the types of operations and each operation’s schema of parameters. Each operation under a WC is referred to as a workflow configuration operation (WCO).
* **Workflow Execution (WE):** This resource allows you to validate, preview, and launch your payment flow based on a specific WC. Each operation within a WE is referred to as a workflow execution operation (WEO).

Generally, the payment workflow consists of the following three steps:

* [Create a WC](/reference/createflowconfiguration).
  * The WC completes the validation process and moves to `READY_FOR_EXECUTION` state.
* [Create a WE based on the WC](/reference/createflowexecution).
  * The WE completes the validation process and the preview process and moves to `READY_FOR_LAUNCH` state.
* [Launch the WE](/reference/launchflowexecution).

The validation and preview processes are not instantaneous. Before continuing to the next step, the WC or WE should be in a ready state.

The validation process is required again when creating the WE because:

* Changes may have occurred during the time between creating a WC and creating a WE. For example, the account could have been removed from the workspace.
* New parameters may have been added when creating the WE and should be verified.


# Overview
Source: https://developers.fireblocks.com/docs/perform-drs-process



# Overview

Fireblocks provides a comprehensive backup and recovery solution to ensure that you always have access to your assets, even if you lose access to your signing devices or in the unlikely event that Fireblocks suspends operations.

Your Fireblocks Vault is a secure multi-party computation (MPC) based wallet that prevents your private key from being a single point of failure when you sign transactions. With Fireblocks MPC, one key share is stored on your company’s hardware, either in each user with signing privileges’ Fireblocks mobile app or on a server that hosts your API Co-Signer. You have two corresponding key shares, which Fireblocks stores at top-tier cloud providers. Your three key shares are never together in one place to expose your full private key.

# Recovery Tools

Fireblocks recommends using our [native self-serve recovery tool](https://support.fireblocks.io/hc/en-us/articles/12023480536732-Introduction-to-in-house-key-backup-and-recovery). Alternatively, you can use [one of our DRS partners](https://support.fireblocks.io/hc/en-us/articles/17211307086364-Third-Party-Disaster-Recovery-Services).


# Getting Started
Source: https://developers.fireblocks.com/docs/quickstart

Install the Fireblocks Documentation MCP, then use an SDK or the Fireblocks CLI to make your first Fireblocks API calls.

By the end of this guide, you will have:

* Connected your agent to the Fireblocks docs
* Created and approved an API user
* Initialized the Fireblocks SDK or CLI
* Created a vault account
* Sent your first transaction

## Step 0: Connect your AI agent to Fireblocks docs

Before you start, install the **Fireblocks Documentation MCP** so your agent (Cursor, Claude Code, Codex, or other) can access docs in real time to ensure up to date, accurate implementation context.

<Tabs>
  <Tab title="Cursor">
    [Click here to add the Fireblocks Documentation MCP to Cursor.](https://cursor.com/en/install-mcp?name=fireblocks\&config=eyJ1cmwiOiJodHRwczovL2RldmVsb3BlcnMuZmlyZWJsb2Nrcy5jb20vZG9jcy9tY3AifQ==)

    <Tip>
      If the install link doesn't open in your environment, open Cursor's MCP installer manually and point it at `https://www.developers.fireblocks.com/mcp`.
    </Tip>
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={"system"}
    claude mcp add --transport http fireblocks-docs https://www.developers.fireblocks.com/mcp
    ```
  </Tab>

  <Tab title="Codex">
    ```bash theme={"system"}
    codex mcp add --transport http fireblocks-docs https://www.developers.fireblocks.com/mcp
    ```
  </Tab>

  <Tab title="Other">
    Use the Fireblocks Documentation MCP endpoint:

    `https://www.developers.fireblocks.com/mcp`
  </Tab>
</Tabs>

## Step 1: Set up API authentication

Fireblocks authenticates API requests with **JWT signatures**. Each request is signed with an **API secret key** (RSA private key) that stays in your environment. Fireblocks stores only the matching **public key**, which you register when you create the API user by uploading a **Certificate Signing Request (CSR)**.

### How signing works

| Component                        | Location              | Purpose                                               |
| -------------------------------- | --------------------- | ----------------------------------------------------- |
| **API secret key** (private key) | Your environment only | Signs every API request to prove it came from you     |
| **Public key**                   | Fireblocks            | Verifies that requests were signed by your secret key |

Your API secret **never** leaves your environment. Fireblocks only receives your public key. We cannot sign requests on your behalf, and a compromised Fireblocks system would not expose your credentials.

### Generate a CSR and secret key

You will create:

* A **secret key** file that stays in your environment and signs requests
* A **CSR** file containing the corresponding public key, which you upload in the Console

1. (Windows users) Install **Win32OpenSSL** using the default settings.
2. (Windows users) Open OpenSSL Command Prompt.
3. In your CLI, run:

<CodeGroup>
  ```bash Shell theme={"system"}
  openssl req -new -newkey rsa:4096 -nodes -keyout fireblocks_secret.key -out fireblocks.csr -subj '/O=<your_organization>'
  ```
</CodeGroup>

This command creates:

* **fireblocks\_secret.key** — your RSA 4096 private key (API secret)
* **fireblocks.csr** — the CSR you upload when creating the API user

4. Store the secret key file securely.

### Create an API user (API key)

<Info>
  If you’re using a Sandbox environment, you can skip this subsection. Sandboxes come with an API user already created and access to the [Communal Test Co-signer](/reference/use-communal-cosigner#/).
</Info>

To create an API key with a signing role:

1. In the Fireblocks Console, go to **Developer Center** > **API Users**.
2. Select **Add API user**.
3. Name the API user, select the appropriate workspace role for it (e.g., Signer if you want it to sign transactions), and upload the `fireblocks.csr` file you generated above.
4. Select **Add user**.

After the request to add the API user is approved, it will appear in the API users list. You'll receive an **API Key** (API User ID), a unique identifier for the API user that you'll use alongside your secret key.

## Choose your path: SDK or CLI

From **Step 2** onward, the guide splits into two tracks that share the same API credentials. Pick the one that matches what you're building:

* **SDK** — for application code (apps, services, backends) where you ship typed, maintainable Fireblocks integrations. **Recommended for production.**
* **Fireblocks CLI** — for fast workspace operations, exploration, scripts, CI, and operator/agent workflows. Lets your AI agent propose exact commands you can review and run.

Steps **3 through 5** each use two synced tabs. Pick **SDK** or **CLI** once and the choice carries through the rest of the guide. The SDK and CLI are not mutually exclusive; you can use both in the same workspace.

## Step 2: Initialize the SDK or CLI

Pick the tab that matches your track. The same choice will apply to Steps 3–5.

<Tabs>
  <Tab title="SDK">
    Fireblocks provides official SDKs for multiple languages:

    * [TypeScript SDK](https://github.com/fireblocks/ts-sdk)
    * [Python SDK](https://github.com/fireblocks/py-sdk)
    * [Java SDK](/reference/java-sdk#/)

    Install the appropriate SDK for your environment:

    <CodeGroup>
      ```bash npm theme={"system"}
      npm install fireblocks-sdk
      ```

      ```bash pip theme={"system"}
      pip install fireblocks-sdk
      ```

      ```java Java theme={"system"}
      // Follow Java SDK instructions on the documentation link above
      ```
    </CodeGroup>

    After installing the SDK, initialize the client with:

    * Your **API Key** (obtained from the Fireblocks Console after creating the API user)
    * Your **API secret key** (the `fireblocks_secret.key` file from Step 1)

    The SDK uses your secret key to sign each API request automatically.

    <CodeGroup>
      ```typescript TypeScript theme={"system"}
      import { FireblocksSDK } from "fireblocks-sdk";
      import fs from "fs";

      const apiKey = "<YOUR_API_KEY>";
      const privateKey = fs.readFileSync("fireblocks_secret.key", "utf8");

      const fireblocks = new FireblocksSDK(privateKey, apiKey);
      ```

      ```python Python theme={"system"}
      from fireblocks_sdk import FireblocksSDK

      api_key = "<YOUR_API_KEY>"
      with open("fireblocks_secret.key", "r") as f:
          private_key = f.read()

      fireblocks = FireblocksSDK(private_key, api_key)
      ```

      ```java Java theme={"system"}
      import com.fireblocks.sdk.FireblocksSDK;
      import java.nio.file.Files;
      import java.nio.file.Paths;

      String apiKey = "<YOUR_API_KEY>";
      String privateKey = new String(Files.readAllBytes(Paths.get("fireblocks_secret.key")));

      FireblocksSDK fireblocks = new FireblocksSDK(privateKey, apiKey);
      ```
    </CodeGroup>

    Replace `<YOUR_API_KEY>` with your API Key from the Fireblocks Console.
  </Tab>

  <Tab title="CLI">
    Install the Fireblocks CLI (Node.js 18+ required), then connect it to your workspace:

    ```bash theme={"system"}
    npm install -g @fireblocks/fireblocks-cli
    fireblocks --version

    fireblocks configure        # paste API key + path to fireblocks_secret.key
    fireblocks whoami           # verify credentials resolve and authenticate
    ```

    Other installers (Homebrew, standalone binaries, yarn/pnpm) are documented on the [Fireblocks CLI](/docs/fireblocks-cli) page.

    <Tip>
      For agent workflows, your agent should run `fireblocks help-index` once to discover commands, and use `--dry-run` and `--idempotency-key` on writes.
    </Tip>
  </Tab>
</Tabs>

## Step 3: Create a Vault Account

A Vault Account is where your assets are securely stored.

<Tabs>
  <Tab title="SDK">
    <CodeGroup>
      ```typescript TypeScript theme={"system"}
      const vault = await fireblocks.createVaultAccount('My First Vault');
      console.log(vault);
      ```

      ```python Python theme={"system"}
      vault = fireblocks.create_vault_account("My First Vault")
      print(vault)
      ```

      ```java Java theme={"system"}
      var vault = fireblocks.createVaultAccount("My First Vault");
      System.out.println(vault);
      ```
    </CodeGroup>
  </Tab>

  <Tab title="CLI">
    ```bash theme={"system"}
    fireblocks vaults create-vault-account \
      --data '{"name":"My First Vault"}' \
      --no-confirm
    ```
  </Tab>
</Tabs>

You can view the new Vault account in the Console under **Accounts** > **Vault**.

<Tip>
  If you’re using a Sandbox, your account should come pre-funded. If you need additional funds, see [Receiving funds into your Fireblocks account](https://support.fireblocks.io/hc/en-us/articles/4414266562450-Receiving-funds-into-your-Fireblocks-accounts) for more information.
</Tip>

## Step 4: Create a Transaction

Now that your vault has funds, you can create your first transaction.

<Tabs>
  <Tab title="SDK">
    <CodeGroup>
      ```typescript TypeScript theme={"system"}
      const transaction = await fireblocks.createTransaction({
        assetId: 'ETH_TEST',
        source: { type: 'VAULT_ACCOUNT', id: vault.id },
        destination: { type: 'EXTERNAL_WALLET', id: '<YOUR_WALLET_ID>' },
        amount: '0.01',
      });
      console.log(transaction);
      ```

      ```python Python theme={"system"}
      transaction = fireblocks.create_transaction({
          "assetId": "ETH_TEST",
          "source": { "type": "VAULT_ACCOUNT", "id": vault["id"] },
          "destination": { "type": "EXTERNAL_WALLET", "id": "<YOUR_WALLET_ID>" },
          "amount": "0.01"
      })
      print(transaction)
      ```

      ```java Java theme={"system"}
      var txRequest = new TransactionRequest();
      txRequest.setAssetId("ETH_TEST");
      txRequest.setSource(new Source("VAULT_ACCOUNT", vault.getId()));
      txRequest.setDestination(new Destination("EXTERNAL_WALLET", "<YOUR_WALLET_ID>"));
      txRequest.setAmount("0.01");

      var tx = fireblocks.createTransaction(txRequest);
      System.out.println(tx);
      ```
    </CodeGroup>
  </Tab>

  <Tab title="CLI">
    Preview the request first with `--dry-run`, then execute with an idempotency key so safe retries don't create duplicate transactions:

    ```bash theme={"system"}
    # Preview
    fireblocks transactions create-transaction \
      --data '{"assetId":"ETH_TEST","amount":"0.01","source":{"type":"VAULT_ACCOUNT","id":"0"},"destination":{"type":"EXTERNAL_WALLET","id":"<YOUR_WALLET_ID>"}}' \
      --dry-run

    # Execute
    fireblocks transactions create-transaction \
      --data '{"assetId":"ETH_TEST","amount":"0.01","source":{"type":"VAULT_ACCOUNT","id":"0"},"destination":{"type":"EXTERNAL_WALLET","id":"<YOUR_WALLET_ID>"}}' \
      --idempotency-key "$(uuidgen)" \
      --no-confirm
    ```
  </Tab>
</Tabs>

## Step 5: Verify Transactions

To verify your transaction status, use the following.

<Tabs>
  <Tab title="SDK">
    For Fireblocks transactions:

    <CodeGroup>
      ```typescript TypeScript theme={"system"}
      const tx = await fireblocks.getTransactionById(txId);
      ```

      ```python Python theme={"system"}
      tx = fireblocks.get_transaction_by_id(txId)
      ```

      ```java Java theme={"system"}
      var tx = getTransactionById(String txId);
      ```
    </CodeGroup>

    For external transactions:

    <CodeGroup>
      ```typescript TypeScript theme={"system"}
      const tx = await fireblocks.getTransactionByExternalTxId(externalTxId);
      ```

      ```python Python theme={"system"}
      tx = fireblocks.get_transaction_by_external_tx_id(externalTxId)
      ```

      ```java Java theme={"system"}
      var tx = getTransactionByExternalTxId(String externalTxId);
      ```
    </CodeGroup>
  </Tab>

  <Tab title="CLI">
    ```bash theme={"system"}
    # By Fireblocks transaction ID
    fireblocks transactions get-transaction --tx-id <TX_ID> --json

    # By external transaction ID
    fireblocks transactions get-transaction-by-external-id \
      --external-tx-id <EXTERNAL_TX_ID> --json
    ```
  </Tab>
</Tabs>

## Next Steps

**CLI**

* [Fireblocks CLI](/docs/fireblocks-cli) — install, overview, and quick start
* [CLI Authentication](/docs/cli-authentication) — credentials, profiles, and environment variables
* [CLI Usage](/docs/cli-usage) — commands, flags, exit codes, and examples

**SDKs**

* [TypeScript SDK](/reference/typescript-sdk)
* [Python SDK](/reference/new-python-sdk)
* [Java SDK](/reference/java-sdk)

**API and platform**

* [API Reference](/reference/api-overview) — REST endpoints and request bodies
* [Manage API keys](/docs/manage-api-keys) — CSR flow, roles, and rotation
* Automate transaction signing with [API co-signers](/docs/use-cosigners-for-signing-automation#/)
* Real-time updates with [webhooks](/reference/webhooks-gettingstarted-configuringwebhooks#/)


# Overview
Source: https://developers.fireblocks.com/docs/raw-signing



<Warning>
  ### Warning

  Raw Signing is an insecure signing method and is not generally recommended. Bad actors can trick someone into signing a valid transaction message and use it to steal funds.

  For this reason, Raw Signing is a premium feature that requires an additional purchase and is not available in workspaces by default.

  If you're interested in this feature and want to see if your use case is eligible for it, please contact your Customer Success Manager.

  Fireblocks Sandbox workspaces have Raw Signing enabled by default to allow for testing purposes.
</Warning>

# Overview

Raw Signing is a powerful feature within Fireblocks. As the Web3 world continues to evolve rapidly, Fireblocks provides the option to support additional chains and actions by signing an arbitrary message using the Fireblocks infrastructure.

Our WalletConnect integration and the Fireblocks Chrome Extension sometimes use Raw Signing to sign transactions initiated by dApps. You will need to add Policy rules for these dApp-initiated raw transactions to go through.

<Info>
  ### Check out the Raw Signing Developer Guide [here](/reference/structure-the-api-call)
</Info>

# What are the use cases for Raw Message Signing?

Typically, Raw Message Signing is used in the following scenarios:

* When you want to sign a transaction on a blockchain that Fireblocks doesn’t currently support
* When you want to perform an operation that we don’t currently support on a blockchain that we do support (e.g., staking on a lesser-known blockchain)
* When you want to use cryptography to prove and validate messages that are not supported by [Typed Message Signing](/docs/typed-message-signing-1)  (e.g., Proof of Assets, Proof of Addresses)
* When someone sends funds to your address over a blockchain that we don’t currently support, and you want to recover the funds

# Enabling Raw Signing

By default, Raw Signing is not available in production workspaces. Contact your Customer Success Manager to enable Raw Signing.

If Raw Signing is disabled in your workspace and you attempt to create a raw transaction, it will fail and show the **BLOCKED\_BY\_POLICY** substatus.

# Policy rules for Raw Signing

Policies reject all raw transactions by default. After enabling the Raw Signing feature in your production workspace, you must add Policy rules that allow users to initiate, approve, and sign raw transactions from specific vault accounts.

You can also use your Policy rules to limit the range of derivation paths, vault accounts, and assets available for raw transactions. Unless explicitly defined otherwise in the rule, the rule matches all derivation paths. When creating the rule, select Groups and accounts as your source and enter Any vault. Then you can enter a derivation path.

The derivation path used in signing can be passed along with the signing request in one of two ways:

* **Explicitly:** By passing the signing algorithm and the full derivation path
* **Implicitly:** By passing the vault account ID, the asset ID, and (optionally) the change and the address index

These properties together comprise a full BIP44-like derivation path. Typically, this approach is used to create custom transactions on supported protocols.


# Segregate Duties
Source: https://developers.fireblocks.com/docs/segregate-duties

To ensure the security of your workspace operations, it is crucial to segregate duties and delegate responsibilities appropriately. The first and most important step is to distinguish between users handling critical managerial tasks and those managing regular operations.

For the former, it is important to understand the permission level of an administrator and the influence they will have with any changes made to the workspace. Please review this [article](https://support.fireblocks.io/hc/en-us/articles/360012832959-User-roles) for more information.

For day-to-day operations, consider three key roles in the transaction process when assigning responsibilities:

* Who will initiate transactions?
* Who will approve transactions?
* Who will sign off on transactions?

Once you have defined these responsibilities, review the following use cases to help you segregate duties properly:

**Manual Process:** Typically used for operations involving a large amount of assets. This involves 100% human intervention. A transaction will be initiated via the Fireblocks console UI, approved manually by certain people (user or group) on their mobile devices, and signed by either the same people or someone else. Note that approvers are not required to have an MPC key to approve transactions.

**Semi-Automated Process:** Used for operations that are not large in value but still significant enough to require human verification. Transactions can be initiated by a person via the UI or an API user and signed by either one of them.

**Fully Automated Process:** Commonly used for internal transactions (between Fireblocks VA) or withdrawals of small amounts. API users initiating transactions must have the relevant permissions. If the same user is linked with the API-cosigner machine, ensure they are assigned a signer permission role.


# Self-Custody Infrastructure
Source: https://developers.fireblocks.com/docs/self-custody-infrastructure

Be the owner of your funds without compromising speed and security using Fireblocks' self-custody infrastructure

# What is Self-Custody Infrastructure?

Fireblocks Self-Custody Infrastructure is a secure and reliable way to store your digital assets. With our robust APIs and multi-layer security, MPC, and Intel SGX, you can be sure that your funds are safe and accessible instead of handling the security work yourself.

[Start developing on Fireblocks today](https://www.fireblocks.com/developer-sandbox-sign-up/?gl=1*19mlzew*_ga*MTY4ODc5Mjc3Ni\[%E2%80%A6]_ga_D39L1D2ZX2*MTY4Nzg2MTQwOS4xNi4xLjE2ODc4Njc3OTMuMjcuMC4w).

# Set up and store your funds through Fireblocks Self-Custody Infrastructure

Using our self-custody technology, you can harness your funds to hold them securely and safely:

* **API Co-Signer:** Automate the approval and signing of transactions and maintain custody with our API Co-Signer.
* **MPC technology:** With MPC, the corresponding private key shares are created and encrypted in isolated environments among multiple parties. To sign transactions, the key shares are used to perform multiple rounds of computation without ever being brought into the same environment. Because of this, MPC eliminates the single point of compromise of private key creation and signing.
* **Secure Hardware Enclaves:** Self-custody your private keys in secure hardware enclaves to keep your keys safe from malicious software or unauthorized users.
* **Key backups:** Get a backup copy of all your signing keys and have full control over your funds.

Learn more about [our Custody Infrastructure](https://www.fireblocks.com/digital-asset-custody/).

# Guides

## Raw Message Signing

Support more chains and actions. Generate ECDSA and EdDSA signatures to [sign any transaction type or message](/docs/raw-signing).

## Typed Message Signing

Allows you to [sign messages using specific standard formats](/docs/typed-message-signing-1) that prefix the message with a magic string. For ETH\_MESSAGE and EIP712 messages.

## Custodial Services

Flexible MPC-based wallet infrastructure enables both [segregated vault structures and omnibus vault structures](/docs/custodial-services) based on your business needs.

## UTXO Consolidation

Leverage automation to [consolidate your unspent UTXO balances across UTXO wallets](/reference/consolidate-utxos) through special transactions that merge them into a single output.

## UTXO Manual Selection

Use dedicated API calls to [manually select specific UTXO asset wallet balances](/reference/select-utxos-for-a-transaction) to consolidate into a single transaction to send to your omnibus account.

## Creating an Omnibus Vault Structure

Use API keys to [generate intermediate vault accounts, identify incoming transactions, and sweep funds](/reference/create-omnibus-structure) to the Omnibus Deposits vault accounts.

## Sweep to Omnibus

How to [automate moving funds from intermediate vault accounts, assigned to your end-users](/reference/sweep-to-omnibus-1) for their deposits to your omnibus account.

## Validating Travel Rule transactions with Fireblocks and Notabene

Using the Fireblocks SDK to [submit transactions to Notabene for validation that they comply with the Travel Rule](/reference/validate-travel-rule) while keeping PII data encrypted.

# Developer Community

Want to learn more from Fireblocks knowledge experts and other developers? [Join our developer community today](https://community.fireblocks.com/)!


# Set Auto Fueling Property
Source: https://developers.fireblocks.com/docs/set-auto-fueling-property



# Overview

Vault account auto-fueling is always available for API users with the Gas Station enabled, and any vault account with the Gas Station badge in the Console participates in the Gas Station service.

* When an incoming token transaction to an auto-fueling vault account completes, Fireblocks automatically transfers the appropriate base asset from the Gas Station to the vault account. This is because the auto-fueled vault account must have a token with a non-zero balance on the relevant network where you are expecting an auto-fueling transaction.
* When an outgoing transaction from an auto-fueling vault account completes, Fireblocks checks the token and gas balance. The vault account is refueled if the token balance is above 0.00001 and the base asset is below the set threshold. Token transfers from this vault account to any destination will then have sufficient gas to cover transaction fees.

## Enabling auto-fueling in the Console

For new vault accounts, select **Auto-fuel with gas after an incoming transaction completes** when you create the account.

For existing vault accounts, go to **My Funds** > **Accounts**, find the appropriate vault account, and then select **More Actions** (**...**) > **Enable Auto-Fueling** > **Enable**. The Gas Station badge appears next to the name of the vault account when you're done.

## Disabling auto-fueling in the Console

In the Fireblocks Console, go to **My Funds** > **Accounts**, find the appropriate vault account, and then select **More Actions** (**...**) > **Disable Auto-Fueling** > **Disable**. The Gas Station badge is removed when you're done.

## Enabling auto-fueling via the API

For new vault accounts, call the [Create a new vault account endpoint](/reference/createvaultaccount) and set the **autoFuel** field to **true**.

For existing vault accounts:

1. Call the [List vault accounts (paginated) endpoint](/reference/getpagedvaultaccounts) to find the vault account's ID.
2. Call the [Turn auto-fueling on or off endpoint](/reference/setvaultaccountautofuel), enter the vault account's ID in the **vaultAccountId** field, and then set the **autoFuel** field to **true**.

## Disabling auto-fueling via the API

1. Call the [List vault accounts (paginated) endpoint](/reference/getpagedvaultaccounts) to find the ID of the vault account.
2. Call the [Turn auto-fueling on or off endpoint](/reference/setvaultaccountautofuel), enter the vault account's ID in the **vaultAccountId** field, and then set the **autoFuel** field to **false**.

<Info>
  ### Check the Gas Station [developer guide](/reference/enable-auto-fueling) for API code examples.
</Info>


# Set Policies
Source: https://developers.fireblocks.com/docs/set-transaction-authorization-policy

Policies define which actions are allowed or blocked in your Fireblocks workspace: controlling who can initiate transactions, from which sources, to which destinations, and under what conditions. You can manage Policies directly in the Fireblocks Console using the Policy Editor, or programmatically via the API.

## Managing policies via the API

The Fireblocks API gives you two ways to manage your Policy: publish changes directly, or work with a draft before publishing.

### Publish directly

To retrieve your active Policy or publish a new one without a review step, use these endpoints:

* [Get the active policy](/reference/getactivepolicy)
* [Publish a new set of policy rules](/reference/publishdraft)

### Work with drafts

If your workflow requires reviewing or validating Policy changes before they go live, use Policy Drafts:

* [Get the active draft](/reference/getdraft)
* [Update the draft with a new set of rules](/reference/updatedraft)
* [Publish a draft by ID](/reference/publishpolicyrules)

## Best practices

Policy rules are evaluated in the order they are defined, so rule ordering matters. Place the most restrictive rules first, and order rules by likelihood of a match. This ensures high-risk or tightly scoped rules are evaluated before broader, more permissive ones, reducing the chance of a transaction being incorrectly approved.

## Learn more

* [About Policies](https://support.fireblocks.io/hc/en-us/articles/19156998685980-About-Policies): Help Center overview of how Policies work
* [Policies developer guide](/reference/configure-transaction-authorization-policy): How to work with Policies programmatically


# Stake Assets
Source: https://developers.fireblocks.com/docs/stake-assets



# Overview

You can stake to various networks from your Vault using the Fireblocks API. When staking, you select a third-party staking provider to operate the validators associated with your staked funds. Typically, the staked amount is locked for a certain period of time.

Staked assets become eligible to receive rewards after the network's activation period. Staking rewards are calculated over a period of time usually known as an epoch. This is the period of time in which validators and their staked amount are accounted for. Depending on the network, an epoch may be anywhere from a few minutes to several days. Typically, staking rewards are calculated and distributed after each epoch ends.

When you unstake your assets, you no longer generate staking rewards, but you're able to use those assets for other transactions.

# Staking via Fireblocks API

To stake, you must fund a vault account with the asset you want to stake and create Policy rules for staking. Then create staking transactions using the dedicated [staking API endpoints](/reference/getchains).

Staking with the Fireblocks API allows you to:

* Easily and securely stake assets through native API calls.
* Create dedicated Policy rules for staking using the **Stake** operation type.
* Track the status and rewards for your staked funds.
* Initiate staking transactions without the need for SDKs, scripts, or Raw Signing.
* Select validators to oversee your staked funds.

## Supported assets

* Ethereum
* Solana
* MATIC

<Info>
  ### Check out the Staking developer guide [here](/reference/stake-assets-1)
</Info>


# Supported Networks
Source: https://developers.fireblocks.com/docs/supported-networks

The following table contains the blockchain networks supported by the Fireblocks Embedded Wallet (EW) service.

<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

<Warning>
  ### Missing something?

  Fireblocks is always looking towards improving its vast chain offering. If you're missing a blockchain or a token on this list, contact your customer success manager and let us know!
</Warning>

| Network Name              | Asset Symbol | Network Protocol | API Asset ID   |
| ------------------------- | ------------ | ---------------- | -------------- |
| Arbitrum                  | ETH          | ETH              | ETH-AETH       |
| Astar                     | ASTR         | ETH              | ASTR\_ASTR     |
| Aurora\_dev               | AURORA       | ETH              | AURORA\_DEV    |
| Avalanche (C-Chain)       | AVAX         | ETH              | AVAX           |
| Axelar                    | AXL          | COSMOS           | AXL            |
| Base                      | ETH          | ETH              | BASECHAIN\_ETH |
| Bitcoin                   | BTC          | BTC              | BTC            |
| BNB Smart Chain           | BNB          | ETH              | BNB\_BSC       |
| Canto                     | CANTO        | ETH              | CANTO          |
| Celestia                  | TIA          | COSMOS           | CELESTIA       |
| Celo                      | CELO         | ETH              | CELO           |
| Chiliz                    | CHZ          | ETH              | CHZ            |
| Chiliz (\$CHZ)            | CHZ          | ETH              | CHZ\_CHZ2      |
| Cosmos Hub                | ATOM         | COSMOS           | ATOM\_COS      |
| dYdX                      | DYDX         | COSMOS           | DYDX           |
| Ethereum                  | ETH          | ETH              | ETH            |
| Ethereum Proof-of-Work    | ETHW         | ETH              | ETHW           |
| Evmos                     | EVMOS        | ETH              | EVMOS          |
| Fantom                    | FTM          | ETH              | FYM            |
| Gnosis Chain (EVM)        | xDAI         | ETH              | xDAI           |
| HT Chain                  | HT           | ETH              | HT\_CHAIN      |
| KAVA                      | KAVA         | ETH              | KAVA           |
| Linea                     | ETH          | ETH              | LINEA          |
| Matic Gas Token (Polygon) | MATIC        | ETH              | MATIC\_POLYGON |
| Moonbeam                  | GLMR         | ETH              | GLMR\_GLMR     |
| Moonriver                 | MOVR         | ETH              | MOVR\_MOVR     |
| Oasys                     | OAS          | ETH              | OAS            |
| Optimistic Ethereum       | ETH          | ETH              | ETH-OPT        |
| Osmosis                   | OSMO         | COSMOS           | OSMO           |
| Ronin                     | RON          | ETH              | RON            |
| RSK Smart Bitcoin         | RBTC         | ETH              | RBTC           |
| Shimmer                   | SMR          | ETH              | SMR\_SMR       |
| SmartBCH                  | BCH          | ETH              | SMARTBCH       |
| Songbird                  | SGB          | ETH              | SGB            |
| Songbird (Legacy)         | SGB          | ETH              | SGB\_LEGACY    |
| TokenX                    | TKX          | ETH              | TKX            |
| TRON                      | TRX          | TRX              | TRX            |
| Velas                     | VLX          | ETH              | VLX\_VLX       |
| XDC Network               | XDC          | ETH              | XDC            |
| zkEVM                     | ETH          | ETH              | ETH\_ZKEVM     |
| Solana                    | SOL          | SOL              | SOL            |
| Algorand\*                | ALGO         | ALGO             | ALGO           |
| Stellar\*                 | XLM          | XLM              | XLM            |
| Ripple                    | XRP          | XRP              | XRP            |
| TON\*                     | TON          | TON              | TON            |
| LTC                       | LTC          | BTC              | LTC            |

\*Asset is not supported for takeover.

<Info>
  ### Additional Assets

  Additional testnets and tokens we support might not appear in the list above.

  In order to query the full list of assets supported by our offering, please use the [Retrieve supported assets endpoint](/reference/wallets-getsupportedassets).
</Info>


# Supported Platforms
Source: https://developers.fireblocks.com/docs/supported-platforms

The Fireblocks Embedded Wallets (EW) SDK offers tools to build on multiple platforms.

<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

## Web

We offer a [web SDK](https://www.npmjs.com/package/@fireblocks/ncw-js-sdk) for your web development. You can also use our [Embedded Wallets API](/reference/create-1#/) to build your apps.

Refer to our [React Demo App](doc:react-demo-application) or look at our [open source code](https://github.com/fireblocks/ncw-web-demo-v2) .

## Mobile

#### iOS Swift SDK

Refer to [iOS Native Demo App](doc:ios-native-demo-app) to learn how you can use our iOS SDK.

#### Android Kotlin SDK

Refer to [Android Native Demo App](doc:android-demo-application) to learn how you can use our Android SDK.


# Swap examples via DeFi
Source: https://developers.fireblocks.com/docs/swap-via-direct-access-providers-defi



<Info>
  ### **Beta Feature**

  The Trading API is currently in beta and subject to change. For participation details, contact your Fireblocks Customer Success Manager or email [CSM@fireblocks.com](mailto:CSM@fireblocks.com).
</Info>

This guide provides a step-by-step example of how to execute a swap using the Fireblocks Trading API via direct access providers, such as Uniswap. A swap is the process of exchanging one cryptocurrency for another on the same network. The guide demonstrates swapping ETH for USDC on Ethereum using Uniswap as the direct access provider.

## Prerequisites

Before you begin, ensure you have completed the prerequisites outlined in the [Trading API Overview](/docs/trading-api-overview#/):

* ✅ Fireblocks API credentials configured
* ✅ Vault accounts with sufficient assets
* ✅ Fireblocks TypeScript SDK installed (`@fireblocks/[email protected]`)

## SDK Setup

First, set up your Fireblocks SDK client:

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  import { Fireblocks } from "@fireblocks/ts-sdk";
  import * as fs from "fs";

  // Initialize the Fireblocks SDK
  const fireblocks = new Fireblocks({
   apiKey: "your-api-key",
   secretKey: fs.readFileSync("/path/to/your/secret.key", "utf8"),
   basePath: "https://api.fireblocks.io"
  });
  ```
</CodeGroup>

## Swap Flow Overview

The following steps outline the process for executing a swap via direct access providers:

```text theme={"system"}
1. List Providers 
2. Approve Terms (executed once per workspace and ONLY via the Fireblocks console)
3. Create Quote 
4. Execute Order 
5. Monitor Order
```

## Step 1: List Available Providers

Before trading, retrieve the list of available providers and use the response to identify the `id` of your desired provider.

### API Call

```typescript theme={"system"}
// List all available trading providers
const providersResponse = await fireblocks.tradingBeta.getTradingProviders({
  pageSize: 20
});

// Filter for direct access providers only (accountBased: false)
const directAccessProviders = providersResponse.data.data.filter(provider => !provider.accountBased);
```

### Response Example

```json theme={"system"}
{
 "data": [
   {
     "id": "UNISWAP_CLASSIC",
     "name": "Uniswap Classic",
     "logo": "https://example.com/logos/uniswap.png",
     "accountBased": false,
     "approved": false,
     "hasTermsOfService": true,
     "termsOfServiceUrl": "https://uniswap.org/terms"
   }
 ],
 "total": 1,
 "next": null
}
```

### Key Fields Explained

| Field               | Description                                                                   |
| ------------------- | ----------------------------------------------------------------------------- |
| `id`                | Unique identifier for the provider (use this in subsequent API calls)         |
| `name`              | Display name of the trading platform                                          |
| `accountBased`      | `false` for direct access providers, `true` for account-based providers       |
| `hasTermsOfService` | Whether the provider requires Terms of Service approval                       |
| `termsOfServiceUrl` | URL to review the Terms of Service                                            |
| `approved`          | For direct access providers: indicates if Terms of Service have been approved |

Direct access providers may require one-time Terms of Service approval. The fields hasTermsOfService and approved indicate whether approval is required and whether your workspace already approved it. Approval must be done once per workspace via the Fireblocks Console.

<Callout icon="📖">
  ### For more details about this endpoint, see the [Get Providers API Reference](/reference/gettradingproviders).
</Callout>

## Step 2: Approve Terms of Service (Direct Access Providers Only)

Direct access providers require one-time Terms of Service approval before trading. **Approval must be done in the Fireblocks Console** (not available via SDK).

### Check Approval Status

```typescript theme={"system"}
// Get provider details to check approval status
const provider: DirectAccessProvider = providersResponse.data.data.find(
  p => p.id === "UNISWAP_CLASSIC"
);

if (provider?.hasTermsOfService && !provider.approved) {
  throw new Error("Approve Terms of Service in Fireblocks Console before proceeding");
}
```

## Clarification on how to translating user intent into baseAssetId, quoteAssetId, side, and baseAmount

When creating a **Quote** or an **Order**, you express the trade using:

* `baseAssetId`: the asset you **receive** on **BUY** / **give** on **SELL**
* `quoteAssetId`: the counter asset used to **pay**/**receive**
* `side`:
  * `BUY`: receive base / pay quote
  * `SELL`: give base / receive quote
* `baseAmount`: amount in `baseAssetId`
  * `BUY`: base amount to receive
  * `SELL`: base amount to sell

### Examples

| Intent                  | baseAssetId | quoteAssetId | side | baseAmount |
| ----------------------- | ----------- | ------------ | ---- | ---------- |
| Buying 100 BTC with USD | BTC         | USD          | BUY  | 100        |
| Buying 100 USD with BTC | USD         | BTC          | BUY  | 100        |
| Selling 100 BTC for USD | BTC         | USD          | SELL | 100        |
| Selling 100 USD for BTC | USD         | BTC          | SELL | 100        |

## Step 3: Create a Quote for the Swap

Creating a quote is required before executing a swap via direct access providers. A quote provides you with the exact exchange rate, expected amounts, fees, and price impact for the swap.

### API Call

```typescript theme={"system"}
// Create a quote for swapping ETH to USDC on Ethereum with Uniswap
const quoteResponse = await fireblocks.tradingBeta.createQuote({
  createQuote: {
    scope: [{ providerId: "UNISWAP_CLASSIC" }],  // Direct access provider (no accountId)
    baseAssetId: "ETH",                         // Asset you're selling
    quoteAssetId: "USDC",                       // Asset you're receiving
    baseAmount: "0.5",                          // Amount of ETH to sell
    side: "SELL",                               // Direct access provider quotes support SELL only
    slippageBps: 50,                            // Optional - Defaults to 50 BPS (0.5%)
    settlement: {                               // Required for direct access provider quotes
      type: "DVP",
      sourceAccount: {
        type: "VAULT_ACCOUNT",
        accountId: "0"
      },
      destinationAccount: {
        type: "VAULT_ACCOUNT",
        accountId: "0"
      }
    }
  },
  idempotencyKey: `quote-${Date.now()}`
});

const quote = quoteResponse.data.quotes[0];
```

### Quote Response Example

```json theme={"system"}
{
 "quotes": [
   {
     "id": "quote_8f2e4d1a9c5b7e3f",
     "via": {
       "type": "PROVIDER",
       "providerId": "UNISWAP_CLASSIC"
     },
     "type": "COMMITTED",
     "baseAssetId": "ETH",
     "quoteAssetId": "USDC",
     "baseAmount": "0.5",
     "quoteAmount": "1247.50",
     "quoteMinAmount": "1241.25",
     "priceImpact": 0.005,
     "expiresAt": "2024-01-15T10:35:00.000Z",
     "generalFees": [
       {
         "feeType": "NETWORK",
         "assetId": "ETH",
         "amountType": "FIXED",
         "amount": "0.01"
       }
     ],
     "executionSteps": [
       {
         "type": "APPROVE",
         "fee": {
           "feeType": "NETWORK",
           "assetId": "ETH",
           "amountType": "FIXED",
           "amount": "0.005"
         }
       },
       {
         "type": "CONTRACT_CALL",
         "fee": {
           "feeType": "NETWORK",
           "assetId": "ETH",
           "amountType": "FIXED",
           "amount": "0.005"
         }
       }
     ]
   }
 ]
}
```

### Understanding Quote Fields

| Field            | Description                                                                                                                                                                                                                                                                                                                               |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`             | Unique quote identifier (use when creating order)                                                                                                                                                                                                                                                                                         |
| `type`           | Quote type: `COMMITTED` - the provider commits to the quote rates (guaranteed execution at the quoted price with respect to slippage boundaries), `INDICATIVE` - an indication of expected prices (rates may vary at execution time)                                                                                                      |
| `baseAmount`     | Amount you're spending/selling                                                                                                                                                                                                                                                                                                            |
| `quoteAmount`    | Expected amount you'll receive                                                                                                                                                                                                                                                                                                            |
| `quoteMinAmount` | Minimum amount guaranteed (accounting for slippage)                                                                                                                                                                                                                                                                                       |
| `priceImpact`    | Deviation from market price and execution price due to trade size or limited liquidity (as a decimal, e.g., 0.005 = 0.5%). A high price impact means your transaction will result in a substantial loss of funds                                                                                                                          |
| `expiresAt`      | Quote expiration time (typically 1-5 minutes)                                                                                                                                                                                                                                                                                             |
| `generalFees`    | Provider fees for the trade                                                                                                                                                                                                                                                                                                               |
| `executionSteps` | Array of steps required to complete the trade, each containing a `type` field that can be `APPROVE` (token approval), `PERMIT` (permit signature), `CONTRACT_CALL` (smart contract interaction), `EXECUTE` (main swap execution), `SETTLEMENT` (settling funds), or `DELIVERY` (delivering assets). Each step may include associated fees |

> **Note:** Quotes expire quickly (typically within 1-5 minutes). Create your order promptly after receiving a quote.

<Callout icon="📖">
  ### For more details about this endpoint, see the [Create Quote API Reference](/reference/createquote).
</Callout>

## Step 4: Execute the Swap Order

Once you have a quote, execute the swap using that quote. Direct access providers like Uniswap require a quote to ensure you get the expected rate and protection against price slippage.

### Execute Order with Quote

```typescript theme={"system"}
// Execute swap order using the quote from Step 3
const orderResponse = await fireblocks.tradingBeta.createOrder({
  createOrderRequest: {
    via: {
      type: "PROVIDER",                         // Direct access provider execution
      providerId: "UNISWAP_CLASSIC"
    },
    executionRequestDetails: {
      type: "QUOTE",
      quoteId: quote.id                         // Quote ID from Step 3
    },
    settlement: {
      type: "DVP",                              // Direct access swaps always use DVP
      sourceAccount: {
        type: "VAULT_ACCOUNT",
        accountId: "0"
      },
      destinationAccount: {
        type: "VAULT_ACCOUNT",
        accountId: "0"
      }
    }
  },
  idempotencyKey: `order-${Date.now()}`
});

const order = orderResponse.data;
```

> **Why direct access providers require quotes:** Unlike some account-based providers, direct access providers (like Uniswap) through Fireblocks require creating a quote first. This ensures you know the exact exchange rate, fees, and slippage protection before the transaction executes on-chain.

<Callout icon="📖">
  ### For more details about this endpoint, see the [Create Order API Reference](/reference/createorder).
</Callout>

## Step 5: Monitor Order Status

After creating an order, monitor its execution status to track completion.

### Get Order Details

```typescript theme={"system"}
// Get order status and details
const orderStatusResponse = await fireblocks.tradingBeta.getOrder({
  orderId: order.id
});

console.log("Order status:", orderStatusResponse.data.status);
```

<Callout icon="📖">
  ### For more details about this endpoint, see the [Get Order Details API Reference](/reference/getorder).
</Callout>

### List All Orders

```typescript theme={"system"}
// List orders with optional filters
const ordersResponse = await fireblocks.tradingBeta.getOrders({
  pageSize: 20,
  order: "ASC",                      // Order by createdAt
  providerId: ["UNISWAP_CLASSIC"],   // Filter by provider
  statuses: ["COMPLETED"]            // Filter by status
});

console.log("Orders:", ordersResponse.data.data);
```

<Callout icon="📖">
  ### For more details about this endpoint, see the [Get Orders (List) API Reference](/reference/getorders).
</Callout>

### Order Status Values

| Status                | Description                                      |
| --------------------- | ------------------------------------------------ |
| `CREATED`             | Order has been created and is being processed    |
| `AWAITING_PAYMENT`    | Waiting for payment to be received               |
| `PENDING_USER_ACTION` | Requires user action (e.g., approval in console) |
| `PROCESSING`          | Order is being executed                          |
| `COMPLETED`           | Order has been successfully completed            |
| `FAILED`              | Order execution failed                           |
| `CANCELED`            | Order was canceled                               |

## Additional Resources

* [Trading API Overview](/docs/trading-api-overview#/)
* [On-Ramp, Off-Ramp, and Bridge/Swap via Account-Based Providers (CeFi)](/docs/on-ramp-off-ramp-and-bridgeswap-via-account-based-providers-cefi#/) - For on-ramp, off-ramp, and other account-based provider use cases
* Fireblocks SDKs: [Python](https://pypi.org/project/fireblocks/) | [TypeScript](https://www.npmjs.com/package/@fireblocks/ts-sdk) | [Java](https://central.sonatype.com/artifact/com.fireblocks.sdk/fireblocks-sdk/overview)
* [Fireblocks Developer Portal](/)

## Support

For questions or issues with the Trading API:

* Contact your Fireblocks Customer Success Manager
* Email: [CSM@fireblocks.com](mailto:CSM@fireblocks.com)
* Check the [Fireblocks Developer Portal](/) for updates


# Sweep Funds
Source: https://developers.fireblocks.com/docs/sweep-funds



## Overview

Once your client, aka the end-user, deposits into an intermediary vault account, most customers will want to perform a sweeping operation. This operation consolidates all deposited funds from the intermediary vault accounts into a single treasury management vault account for various business purposes.

Sweeping funds involves moving assets from address A to address B. It is important to note that this is an on-chain operation and includes **transaction fee payments**.

## Trigger the Sweeping Operation

The trigger for the sweeping operation varies from customer to customer, depending on specific strategies, business needs, and regulatory requirements.

For instance, some customers may choose to sweep the funds immediately after the deposit is completed. In contrast, others may trigger the sweeping mechanism only after a certain amount of deposits (either by total balance or number of deposits). Since sweeping is an on-chain operation that incurs transaction fees, some customers opt to execute the sweeping operation only when the current network fee is below a predefined acceptable threshold. Fireblocks enables customers to monitor current network fees/gas prices using the `GET /estimate_network_fee` [endpoint](/reference/estimatenetworkfee).

There is no right or wrong approach; customers should determine what works best for their business needs.

### Sweep timing strategies

You can sweep deposits from deposit accounts immediately after each deposit, or batch them over time. As deposits accumulate or network fees change, you can use logic-based triggers based on time, balance, or fee conditions.

For example, to minimize fees, you may choose to sweep when the network is less congested or when gas prices fall below a defined threshold. If you want to sweep promptly, sweeping can occur immediately after a deposit or once Gas Station fueling is complete.

### Gas Station

The Gas Station feature allows you to maintain a wallet fueled with relevant base tokens. When a deposit account receives tokens, this wallet can fuel (transfer) base tokens to the deposit account to cover fees and enable sweeping. You can configure this behavior, including when the transfer occurs and how much is transferred.

## Automate Sweeping

To create sweeping transactions, Fireblocks customers can use the `POST /transactions` [endpoint](/reference/createtransaction). First, identify the vault account from which you want to initiate the sweeping operation and then send the sweeping transaction request to the Fireblocks API. This process should be executed for every vault account from which sweeping is desired.

Automating sweeping transactions involves not only creating the transactions in a fully automated manner but also automating the entire signing process. We recommend using an [API Co-Signer](/reference/api-cosigner-installation-flow) to automatically sweep funds according to your organization's logic and fee prices.

When sweeping funds, you also pay a fee in the base asset of the deposited token's blockchain. To ensure you always have enough funds for the sweeping transaction, we introduced the [Fireblocks Gas Station](/docs/work-with-gas-station) feature, which automatically identifies incoming transactions to your predefined vault accounts and deposits enough of the base asset to cover fees for sweeping funds to your main treasury.

### Automation rules

Fireblocks is rolling out an automation feature that allows you to define rules to trigger transactions. In the future, this will include automatic sweeping and reconciliation rules across groups of wallets. Currently, rules can only be applied to specific vault accounts as the source.

For more information, see [About Automation](https://support.fireblocks.io/hc/en-us/articles/14873112741660-About-Automation).

## Reconciliation Processes

Because memo-based wallets function as omnibus wallets, funds can be reconciled to withdrawal wallets or to cold and treasury management workspaces as needed.

UTXO-based wallets also operate as omnibus wallets, allowing multiple deposited UTXOs to be reconciled to target destinations. However, transaction size limits and MPC restrictions apply:

* For Bitcoin-based wallets, a single transaction is limited to 250 UTXOs.
* For Cardano transactions, the overall size is capped at 16 KB.

To determine the maximum spendable amount before initiating a sweep, call the [Get max spendable amount in a transaction](/reference/getmaxspendableamount) endpoint.

UTXO-based chains support multiple destinations, allowing funds to be moved to different targets (for example, cold storage and withdrawal wallets) within a single transaction. For account-based chains, sweeping is done per deposit wallet.

## Fees

Because sweeping is normally less time-sensitive, transaction fees can be set lower than the prevailing network fees required for immediate confirmation.

## Sweeping Tokens

When sweeping tokens, the wallet should have enough native asset balance to cover the transaction fees. However, some chains support models where another account can pay the fee:

* EVM chains: Gasless transactions (currently in development and supported for a limited set of tokens)
* Universal: Gasless transactions once EIP-7702 support is obtained
* Solana: Fee payer model


# Tokenization
Source: https://developers.fireblocks.com/docs/tokenization

Deploy, manage, mint, and burn custom tokenized on-chain assets securely using the Fireblocks API

# What is Tokenization?

The Fireblocks asset tokenization platform is a secure and compliant way to digitalize assets and build blockchain-based applications. Our REST API provides powerful capabilities for automating tasks like creating, redeeming, managing, and issuing tokens, such as stablecoins or security tokens.

[Start developing on Fireblocks today](https://www.fireblocks.com/developer-sandbox-sign-up/?gl=1*19mlzew*_ga*MTY4ODc5Mjc3Ni\[%E2%80%A6]_ga_D39L1D2ZX2*MTY4Nzg2MTQwOS4xNi4xLjE2ODc4Njc3OTMuMjcuMC4w).

# Launch your tokenization project with Fireblocks API

You can use our Fireblocks API for tokenization in different ways:

* Tokenize any asset, including fiat currencies, securities, and other illiquid assets
* Mint new tokens
* Manage smart contracts and whitelisting approval
* Execute any smart contract function
* Secure custody of your tokens
* Trade your tokens on exchanges or through peer-to-peer (P2P) transactions
* Burn tokens that are no longer needed to manage the token supply
* Integrate with other DeFi applications

With the Fireblocks asset tokenization platform, you can use our API to automate minting and token issuance 24/7. You can also manage your daily token operations using our easy-to-use dashboard.

Learn about [our turnkey solution](https://www.fireblocks.com/platforms/tokenization/).

# Guides

## Raw Message Signing

Support more chains and actions. Generate ECDSA and EdDSA signatures to [sign any transaction type or message](/docs/raw-signing).

## Typed Message Signing

Allows you to [sign messages using specific standard formats](/docs/typed-message-signing-1) that prefix the message with a magic string. For ETH\_MESSAGE and EIP712 messages.

## Creating Vaults and Wallets

[Generate Fireblocks vault accounts and asset wallets](/docs/creating-vaults-and-wallets) at scale for both account-based and UTXO asset wallet types using the Fireblocks API and SDKs.

## Whitelisting External Wallets

Use API calls and endpoints that [whitelist external wallet addresses](/docs/whitelisting-external-wallets) so that you can send transactions from wallets that exist outside your Fireblocks Vault.

## Minting an NFT

[Mint and verify Non-Fungible Tokens (NFT)](/reference/mint-an-nft) for your NFT collection using the Fireblocks Hardhat Plugin or Web3 Provider.

## Ethereum Smart Contract Development

Smart contract development frameworks to [develop, test, and deploy smart contracts on EVM-based blockchains](/reference/hardhat-plugin) easily. Four different ways to deploy your contracts.

# Developer Community

Want to learn more from Fireblocks knowledge experts and other developers? [Join our developer community today](https://community.fireblocks.com/)!


# Overview
Source: https://developers.fireblocks.com/docs/trading-api-overview



## Introduction

The Fireblocks Trading API enables several use cases related to liquidity and conversions, executing trades directly from your Fireblocks workspace, integrating dApps and centralized providers. With it, you can create Orders for the following use cases:

* Swap one asset to another on decentralized and centralized providers, over the same network. For example, swap USDC over Ethereum to USDT over Ethereum from one of your vaults via dApps like Uniswap or connected accounts like Scrypt
* On/off ramp via connected accounts with one of the providers. For example, on-ramp MXN to USDC over Polygon via your connected account with Alfred Pay
* Bridge assets between different chains via account-based providers (see [On-Ramp, Off-Ramp, and Bridge/Swap via Account-Based Providers (CeFi)](/docs/on-ramp-off-ramp-and-bridgeswap-via-account-based-providers-cefi))

**Additional use cases:**

* Convert one asset to another within your connected account with account-based providers - to be added in the near future

This guide outlines the process for executing Orders using the Fireblocks API, including prerequisites, a detailed workflow, and necessary code examples for successful operations utilizing the different use cases mentioned above.

## Core Terminology

| Term                            | Description                                                                                                                                                                                                                                                                                        |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Order**                       | An instruction created through the trading API that defines what asset to buy or sell, at what price (market or quote), and how to settle it (DVP or prefunded). Each order has a unique ID and a lifecycle status that remains until it is completed or fails.                                    |
| **Quote**                       | A temporary price offer from a provider that defines the exchange rate and expiry time. Quotes can be Indicative (for price preview only) or Committed (locked and executable until expiration).                                                                                                   |
| **Provider**                    | External trading provider or exchange venue. For example, Bridge or AlfredPay for account-based providers, and Uniswap for direct access providers are commonly used in DeFi.                                                                                                                      |
| **Settlement Type**             | Defines how and when funds move during a trade.- **DVP**: The provider waits for the user's fund deposit before executing the order, ensuring delivery occurs only after payment is received.- **Prefunded**: Executes instantly using the user's existing balance already held with the provider. |
| **Execution Type**              | Defines how the order price is determined.- **Market**: Executes immediately at the best available rate from the provider.- **Quote**: Executes at a locked rate from a committed quote created beforehand using the Quote endpoint.                                                               |
| **Participants Identification** | Defines the originator and beneficiary involved in an order. Used to determine who initiates and who receives the transaction, and what level of PII data is required by the provider (e.g., first-party vs third-party).                                                                          |

## Understanding Trading Providers

The Fireblocks Trading API supports two types of providers:

### Direct Access Providers

DeFi platforms that provide direct access to decentralized protocols without requiring account management, such as Uniswap.

**Key Characteristics:**

* **Access Type**: Direct - no account credentials needed
* **Approval**: One-time Terms of Service acceptance

### Account-Based Providers

Centralized providers that require users to open an account with them. Account-based access requires credentials (API keys).

**Key Characteristics:**

* **Access Type**: Account-based - customers need to open an account with the provider before they can use the API to create Orders via Fireblocks. After creating the account, the customer needs to generate API keys within their account in the provider console, and then connect the account via the connected-account page in the Fireblocks console. For detailed instructions, see [Fireblocks Connected Accounts](https://support.fireblocks.io/hc/en-us/articles/360017435399-Fireblocks-connected-accounts)

## Prerequisites

### 1. Fireblocks API Credentials

* Obtain API and Secret Keys from Fireblocks.
* Ensure the credentials have sufficient permissions for trading operations.

### 2. SDK Installation

Install or update the Fireblocks SDK with trading support before proceeding.

### 3. Other Requirements

Different providers have specific requirements:

**For direct access providers:**

* Trades execute on-chain, requiring gas fees in the native blockchain asset. For example, Ethereum-based swap orders via Uniswap will require you to have ETH for gas
* The execution of direct access orders is done via smart contracts. Ensure you have policy rules that allow smart contract calls within your policy

**For account-based orders:**

* Minimum trade amounts vary by platform
* Execution and settlement are handled through connected accounts
* Ensure you have both Orders and Transfer policy rules inside your policy

## High-Level Trading Flow

```text theme={"system"}
1. List Providers
   │
   ├─→ GET /providers
   │   └─→ Returns available providers
   │
2. Approve Terms (For direct access only)
   │
   ├─→ One-time approval for direct access providers - Approved only from the console
   │
3. Create Quote (optional - some providers allow creating Market orders without creating a quote beforehand)
   │
   ├─→ POST /trading/quotes
   │   └─→ Get exchange rate, amounts, and fees
   │
4. Create Order
   │
   ├─→ POST /trading/orders
   │   ├─→ Using quote (quote-based execution)
   │   └─→ Direct market order
   │
5. Monitor Order
   │
   └─→ GET /trading/orders/{orderId}
       └─→ Track execution status and completion
```

## Next Steps

See the following guides for implementation examples:

* [Swap via Direct Access Providers (DeFi)](/docs/swap-via-direct-access-providers-defi#/) - Step-by-step guide for executing swaps using direct access providers like Uniswap
* [On-Ramp, Off-Ramp, and Bridge/Swap via Account-Based Providers (CeFi)](/docs/on-ramp-off-ramp-and-bridgeswap-via-account-based-providers-cefi#/) - Step-by-step guide for on-ramp, off-ramp, and swap operations using account-based providers


# Transaction Flows
Source: https://developers.fireblocks.com/docs/transaction-flows



<Note>
  For Fireblocks' recommended embedded wallet solution, see [Dynamic Embedded Wallets](/docs/dynamic-embedded-wallets). The documentation below covers the legacy Embedded Wallet APIs and SDKs.
</Note>

## Deposits

* External -> Fireblocks Embedded Wallet (EW)
* External -> Self-Custodial (vault account)

## Withdrawals

* EW -> One-Time Address
* EW -> Whitelisted Address
* Self-Custodial (vault account) -> One-Time Address
* Self-Custodial (vault account) -> Whitelisted Address

Learn more about [one-time addresses](https://support.fireblocks.io/hc/en-us/articles/4409104568338-One-Time-Address-feature) and [whitelisted addresses](https://support.fireblocks.io/hc/en-us/articles/360017819439-Whitelisting-new-addresses).

## Transfers between peers

* EW -> Self-Custodial (vault account)
* Self-Custodial (vault account) -> EW
* Self-Custodial (vault account) -> Exchange account
* Self-Custodial (vault account) -> Fiat account
* Self-Custodial (vault account) -> Fireblocks Network

Learn more about [exchange accounts](https://support.fireblocks.io/hc/en-us/articles/360017435399-Fireblocks-exchange-connectivity), [fiat accounts](https://support.fireblocks.io/hc/en-us/articles/360018286760-Fiat-accounts), and the [Fireblocks Network](https://support.fireblocks.io/hc/en-us/articles/6107038882460-Overview-of-the-Fireblocks-Network).

<img alt="" />

## Transfers between Embedded Wallets

The Fireblocks EW feature allows you to transfer funds between your embedded wallets (including self-transfers) forming your exclusive "Fireblocks Network." There's no need to handle destination addresses. You can use wallet IDs for simplified and secure internal transactions.


# Treasury Management
Source: https://developers.fireblocks.com/docs/treasury-management

Store your funds securely in hot and cold wallets, manage your fund operations, and connect to exchanges, DeFi, and trading counterparties with Fireblocks Treasury Management

# What is Treasury Management?

Fireblocks Treasury Management helps maintain a holistic view of your firms’ assets across wallets, connected venues, and fiat providers with a view to managing operational risk and liquidity.

[Start developing on Fireblocks today](https://www.fireblocks.com/developer-sandbox-sign-up/?gl=1*19mlzew*_ga*MTY4ODc5Mjc3Ni\[%E2%80%A6]_ga_D39L1D2ZX2*MTY4Nzg2MTQwOS4xNi4xLjE2ODc4Njc3OTMuMjcuMC4w).

# Set up, maintain, and scale your fund operations through Fireblocks Treasury Management

Using Fireblocks Treasury Management, you can streamline the functionality of your operations, enabling you to grow and scale securely:

* **Protect fund operations:** Safely store tokens and NFTs and securely access exchanges or fiat accounts with our multi-layer security.
* **Set up governance rules:** Use transaction authorization policy rules to create automated preferences catered around specific business requirements. Configure different roles and approval levels for stakeholders, and automate approval workflows to save time and maintain efficiency.
* **Operationalize treasury management:** Use our services to view all treasury assets across hot or cold wallets and track and report the movement of internal funds.
* **Easily move assets around:** Use Treasury Funds in DeFi, Staking, or Tokenized Funds. Use our Gas Station for seamless gas management as you move assets.
* **Make secure transfers:** Connect with counterparties across the Fireblocks Network and transact in a secure channel taking advantage of address resolution while preventing human errors or man-in-the-middle attacks.
* **Trading:** Automate, rebalance, and transfer between exchange accounts while minimizing counterparty risk to exchanges using our treasury management offering.

Learn more about [our Treasury Management](https://www.fireblocks.com/blog/the-4-pillars-of-great-treasury-management-in-web3/).

# Guides

## Raw Message Signing

Support more chains and actions. Generate ECDSA and EdDSA signatures to [sign any transaction type or message](/docs/raw-signing).

## Typed Message Signing

Allows you to [sign messages using specific standard formats](/docs/typed-message-signing-1) that prefix the message with a magic string. For ETH\_MESSAGE and EIP712 messages.

## Creating Vaults and Wallets

[Generate Fireblocks vault accounts and asset wallets](/docs/creating-vaults-and-wallets) at scale for account-based and UTXO asset wallet types using the Fireblocks API and SDKs.

## Whitelisting External Wallets

Use API calls and endpoints that [whitelist external wallet addresses](/docs/whitelisting-external-wallets) so that you can send transactions from wallet types using the Fireblocks API and SDKs.

## Gas Station Setup and Usage

[Auto-fuel a vault account to fund transaction fees](/docs/enabling-the-gas-station-1) with the base asset for EVM-based blockchains to automate and simplify your omnibus vault operations.

## Creating a Transaction

Use transaction API calls to [initiate any Fireblocks transaction operation](/reference/create-transactions), such as transfer, mint, burn, contract call, raw, and more.

## Monitoring Transaction Statuses

Set up automated webhook notifications to [monitor the progression of your transactions](/reference/monitoring-transaction-status) via transaction statuses and sub-status messages.

## Exchange Transfers

Use the `Create a new transaction` endpoint call to [manage external transfers to and from your linked exchange accounts](/docs/exchange-transfers).

# Developer Community

Want to learn more from Fireblocks knowledge experts and other developers? [Join our developer community today](https://community.fireblocks.com/)!


# Sign Typed Messages
Source: https://developers.fireblocks.com/docs/typed-message-signing-1



## What is Typed Message Signing?

Typed Message Signing is a crucial function in the blockchain ecosystem, designed to ensure security, transparency, and user trust when interacting with various blockchain applications.

Typed Message Signing refers to the process of creating and signing structured data that both machines and humans can understand and verify.

Unlike traditional message signing that deals with arbitrary data, Typed Message Signing structures the data according to predefined formats, making it readable and understandable before it is signed. This process ensures that the signer fully comprehends what they are agreeing to, thereby enhancing the security and clarity of blockchain transactions.

## What are the use cases for Typed Message Signing?

* **Proof of Ownership:** Users can sign messages to demonstrate ownership of a particular blockchain address or asset without making any on-chain transaction, crucial for identity verification processes.
* **Proof of Reserves:** Financial institutions can use typed message signing to prove possession of sufficient funds or assets transparently, enhancing trust among users or regulators.
* **Compliance with Regulations:** In scenarios like the Travel Rule and [TRUST Platform](https://www.coinbase.com/blog/introducing-the-travel-rule-universal-solution-technology-trust) in the cryptocurrency space, businesses must share certain transaction details with regulatory bodies. Typed message signing ensures that this information is exchanged securely and verifiably.
* **Smart Contracts and Legal Agreements:** In complex agreements or smart contracts, typed message signing can be used to confirm terms, conditions, and any other contractual obligations clearly and securely.
* **Meta-Transactions:** Typed message signing enables meta-transactions, where users sign transactions that someone else submits to the network. This is particularly useful in dApps that aim to reduce the gas cost burden on users.
* **Authentication:** Users can sign a typed message to prove ownership of a blockchain address without making a transaction. This method can be used for logging into decentralized applications (dApps) securely.

## How does Typed Message Signing work?

* **Data Structuring:** Initially, the data to be signed is structured into a predefined format. This structure includes defining types, fields, and the order in which the fields appear. This data format is often defined in a smart contract or a protocol specification.
* **User Confirmation:** Before signing, the structured data is presented to the user in a human-readable form. This step is vital as it allows the user to verify the details of the data they are about to sign, ensuring transparency and informed consent.
* **Signing:** The user signs the data with their private key. This signature process involves cryptographic algorithms that securely associate the signer's identity with the data they approved.
* **Verification:** The signature can then be verified by anyone who has access to the signer’s public key, confirming that the specific data was signed by the owner of the private key and that it has not been tampered with since signing.

## Typed Message Signing in Fireblocks

### How to enable Typed Message Signing

To sign a Typed Message, [create a Typed Message Policy rule](https://support.fireblocks.io/hc/en-us/articles/19158869149596-Policies-for-EVM-DeFi-operations#h_01JQ1MDMDGZY9C831P67762GCQ).

### Supported assets and methods

Typed message signing in Fireblocks is supported for several assets and can be implemented through various methods:

**Supported Assets:**

* [EVM-based blockchains (EIP191 & EIP712)](/reference/sign-typed-messages-for-ethereum-and-evm-networks)
* [Bitcoin](/reference/signing-typed-messages-in-bitcoin)
* [Tron (TIP191)](/reference/signing-typed-messages-in-tron)

**Creation Methods for Typed Message Signing Requests:**

* By decentralized applications (dApps) using the [Fireblocks Browser Extension](https://support.fireblocks.io/hc/en-us/articles/5403962226332-Connecting-to-Web3-using-the-Fireblocks-Chrome-Extension) or [Wallet Connect integration](https://support.fireblocks.io/hc/en-us/articles/5403817784732-Connecting-to-Web3-using-WalletConnect)
* Through the Fireblocks API, using the [Create Transaction](/reference/createtransaction) API call

### Via the Browser Extension or Wallet Connect

Typed Message Signing requests are created by Decentralized Applications (dApps) when connected via Fireblocks Browser Extension or Wallet Connect integration, for various purposes such as (but not limited to):

* **Session Authentication:** Similar to traditional web applications, dApps can use message signing to manage sessions. Once a user signs a message to prove ownership of an address, the dApp can create a session for the user without requiring them to sign in through traditional methods like username and password
* **Proving Ownership:** dApps often need to verify that a user controls a specific blockchain address. Typed message signing enables users to prove ownership without having to conduct a transaction, which can save on transaction fees
* **Meta-transactions:** Users can sign transactions that are paid for and submitted by another party (like a dApp). This can be used to improve user experience by allowing users to interact with the blockchain without needing to spend Ether for gas

<Frame>
  <img />
</Frame>

### Via the Fireblocks API

Typed Message Signing requests can also be initiated through the API by using the Create Transaction API. These requests are typically generated for scenarios such as (but not limited to):

* **Proof of Ownership:** Users can sign messages to demonstrate ownership of a particular blockchain address or asset without making any on-chain transaction, crucial for identity verification processes
* **Compliance with Regulations:** In scenarios like the Travel Rule and [TRUST Platform](https://www.coinbase.com/blog/introducing-the-travel-rule-universal-solution-technology-trust) in the cryptocurrency space, businesses must share certain transaction details and regulatory bodies. Typed message signing ensures that this information is exchanged securely and verifiably
* **Proof of Reserves:** Financial institutions can use typed message signing to prove possession of sufficient funds or assets transparently, enhancing trust among users or regulators

<Info>
  ### Learn more on Typed Message Signing via API in the following [guide](/reference/typed-message-signing-2)!
</Info>


# Explore Use Cases
Source: https://developers.fireblocks.com/docs/use-cases



# What can you build with Fireblocks?

Virtually anything! Fireblocks supports a range of use cases, from centralizing treasury management to building a fintech application. Here are some of the use cases we support:

* NFT Marketplaces and Platforms
* Treasury Management
* Digital Asset Custody
* CeFi and DeFi Trading
* Cross Border Payments
* Web3 Gaming
* Tokenization
* Staking
* Smart Contract Security and Management
* Wallets for Retail Applications

# What types of businesses are built on Fireblocks?

Fireblocks enables your business to access the digital asset ecosystem quickly and securely. From Web3 to financial services, almost every type of business is building on Fireblocks.

| Industry               | Type                                                                                                                       |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Financial Institutions | Banks, Hedge Funds, Asset Managers, Lending Desks, OTC Desks, Prime Brokers, Market Makers, Family Offices                 |
| Web3 Companies         | NFT Marketplaces, DAOs, DeFi Protocols, GameFi, Web3 Infrastructure Providers, Protocol Foundations, and B2B Web3 Services |
| Retail Services        | Exchanges, Corporates, Fintechs, Neobanks, Challenger Banks, Investment Platforms                                          |
| B2B Services           | Payment Service Providers, Banking-as-a-Service Providers                                                                  |

# Fireblocks Feature Landscape

* [Wallet-as-a-Service](/docs/wallet-as-a-service)
* [Self-Custody Infrastructure](/docs/self-custody-infrastructure)
* [Tokenization](/docs/tokenization)
* [Treasury Management](/docs/treasury-management)


# Use API Co-signers for Signing and Approval Automation
Source: https://developers.fireblocks.com/docs/use-cosigners-for-signing-automation



## Overview

The API Co-signer automates transaction signing and workspace configuration approvals, complementing the default manual process performed via a mobile device using the Fireblocks mobile application. It is ideal for workspaces with high transaction volumes or frequent activity.

The Co-signer is a component installed and hosted in your environment on a machine with enclave support. Enclaves create a secure runtime environment that isolates and protects data and code, even from privileged users. This trusted execution environment safeguards sensitive processes from unauthorized access and tampering.

## Available API Co-signer types

Fireblocks offers multiple deployment options for API Co-signers. These options are available in cloud environments and on-premises, provided the region supports the required enclave technology. Each deployment utilizes enclave technologies to protect your MPC key shares. This allows you to choose a solution that fits your production environment.

API Co-signers are supported on Intel SGX, AWS Nitro, and Google Cloud Confidential Spaces enclaves. Deployments can be made on popular cloud platforms like Azure, AWS, Google Cloud, IBM Cloud, and Alibaba Cloud. On-premises deployments are also supported using Intel SGX-capable servers.

For detailed step-by-step installation guides for each Co-signer type, refer to the articles below:

* [Installing an SGX API Co-signer in Azure](/reference/install-api-cosigner-azure)
* [Installing an SGX API Co-signer via Azure Marketplace](/reference/install-api-cosigner-azure-marketplace)
* [Installing an SGX API Co-signer in IBM Cloud](/reference/install-api-cosigner-ibm)
* [Installing an SGX API Co-signer in Alibaba Cloud](/reference/install-api-cosigner-alibaba)
* [Installing an SGX API Co-signer on-prem](/reference/install-api-cosigner-onprem)
* [Installing a Nitro API Co-signer in AWS](/reference/install-api-cosigner-aws)
* [Installing a Confidential Space API Co-signer in Google Cloud](/reference/install-api-cosigner-gcp)

## Additional resources

Use the articles below to learn more about the Co-signer's architecture and configuration:

* [API Co-signers Architecture Overview](/docs/cosigner-architecture-overview)
* [Intel SGX Co-signer Architecture](/docs/intel-sgx-api-co-signer)
* [AWS Nitro Co-signer Architecture](/docs/aws-nitro-api-co-signer)
* [Google Cloud Confidential Space API Co-signer Architecture](/docs/gcp-confidential-space-api-co-signer)
* [Set up an API Co-signer Callback Handler](/docs/create-api-co-signer-callback-handler)
* [API Co-signer Security Checklist and Recommended Defense and Monitoring Systems](/docs/co-signer-security-checklist-defense-monitoring)
* [Configuring Multiple API Co-Signers in High Availability](/docs/multiple-cosigners-high-availability)


# Validate Balances
Source: https://developers.fireblocks.com/docs/validate-balances

Fireblocks customers can create automated mechanisms to notify their organization about incoming transactions using the following methods:

* Webhook notifications
* Pulling the transaction history log using the Fireblocks API

When monitoring notifications through these methods, only consider incoming transactions for reconciliation after receiving a notification that the transaction’s status has been updated to `COMPLETED` and the `VAULT_BALANCE_UPDATE` webhook has been received.

Fireblocks provides additional information to help clients validate and reconcile their balances according to the blockchain state. This information includes:

* The [`TRANSACTION_STATUS_UPDATED`](/reference/transaction-webhooks#transaction-status-updated) webhook event contains the `blockInfo` object, which includes:

  * `blockHeight`: The block height where the transaction was included
  * `blockHash`: The block hash where the transaction was included

* The `VAULT_BALANCE_UPDATE` webhook event and the `GET /vault/accounts/{vaultAccountId}/{assetId}` endpoint both include `blockHeight` and `blockHash` properties.
  * For UTXO-based assets (e.g., BTC, LTC, BCH, DOGE), `blockHash` is not currently populated in `VAULT_BALANCE_UPDATE` responses. Only `blockHeight` is available. To retrieve `blockHash` for UTXO-based transactions, use `blockInfo.blockHash` from the `TRANSACTION_STATUS_UPDATED` webhook or the `GET /transactions/{txId}` endpoint.

* The [`GET /transactions/{txId}`](/reference/gettransaction) endpoint returns the transaction by its Fireblocks ID and includes the `blockInfo` object with the `blockHeight` and `blockHash` properties

Before crediting the end-user, customers need to run a reconciliation process to ensure that the incoming balance is accurately reflected and up to date according to the same `blockHeight` provided in the transaction notification object. If the balance is not up to date with the network state and the same height value, customers should not credit their clients until the issue is inspected and resolved.

Fireblocks strongly recommends checking the wallet’s balance using the Fireblocks API to verify that the deposit is included and the balance is up to date. This is crucial to prevent potential loss of funds from crediting end-clients before the balance is truly updated. While Fireblocks takes extensive measures to ensure the accuracy and reliability of its services, it is important for customers to implement all necessary validations and follow best practices to avoid any potential issues.

Below is a sequence diagram for additional reference:

<img alt="" />


# Estimate Transaction Fees
Source: https://developers.fireblocks.com/docs/verify-fee-effeciency

Fireblocks provides clients with two API endpoints to estimate transaction fees:

1. **Estimate Transaction Fee** - [Documentation](/reference/estimatetransactionfee)
2. **Estimate Network Fee** - [Documentation](/reference/estimatenetworkfee)

# Estimate Transaction Fee

The [`Estimate Transaction Fee` endpoint](/reference/estimatetransactionfee) is designed to simulate a real transaction and calculate its potential fee. This process considers factors such as the source and destination amounts, the number of inputs and outputs, and other relevant transaction details. Essentially, it mimics the actual transaction to determine what the fee would be if executed.

When using this endpoint, clients should be aware that it follows the same rules as creating a transaction. This includes requiring the relevant vault wallet in the vault account, ensuring the estimated transaction's balance is in the wallet, and providing a valid destination.

While many clients implement logic to estimate the transaction fee before each execution, it is crucial not to call this endpoint for every minor transaction change. For example, in EVM-based transactions, the gas limit for transferring the base asset or a specific token usually remains the same (barring sudden surges in network fees). The main variable is the current network fee, which can be obtained using the second endpoint.

# Estimate Network Fee

The [`Estimate Network Fee` endpoint](/reference/estimatenetworkfee) returns the current network fee for a specified network. This allows clients to calculate transaction fees or display the current network fee to their users. For instance, it provides the current gas price for ETH, which is part of the entire transaction fee formula, alongside the gas limit and other parameters.

The network fee response is cached for 30 seconds on the Fireblocks side. Clients should consider this interval when using this endpoint, as querying it more frequently than every 30 seconds does not provide additional value and the fee level value would remain the same.

# Fee Levels

Both endpoints return estimated fees or network fees in three levels: LOW, MEDIUM, and HIGH. Here’s how these are determined for different transaction types:

## EVM-Based Transactions

To simplify the gas calculation for each transaction, Fireblocks offers preset fees for both the Console (slow, medium, and fast) and the API (low, medium, and high). These fee calculations are based on recent blocks and a certain percentile of the data collected.

Fireblocks retrieves the latest block data every minute, inspecting the gas prices of recent blocks to determine the fee rate and automatically set the gas limit. In addition to verifying the latest data, Fireblocks also simulates the desired transactions to estimate the fee. The transaction parameters are sent to an API endpoint on the node, which returns an estimated transaction fee.

## UTXO-Based Transactions

* **High**: Fees are based on the previous block’s fee.
* **Medium**: Fees are based on the average of the previous two blocks.
* **Low**: Fees are based on the average of the last four blocks.

Fireblocks' API endpoints for estimating transaction fees provide clients with robust tools to ensure they can accurately predict and manage transaction costs. By using these endpoints, clients can maintain efficient and cost-effective operations while offering transparency and predictability in transaction fees to their users. Whether you are dealing with EVM-based, UTXO-based transactions or any other type of blockchain, understanding and utilizing these endpoints can significantly enhance your transaction management strategy.

# Best Practices

## Calling the Fee Estimation Endpoint

In some workflows, customers call the fee estimation endpoint for every transaction. However, this is not required for chains with relatively constant per-transaction fees, where fees depend mainly on network congestion and number of operations. In such cases, you can explicitly state the network fee instead (for example, on Stellar).

In these flows, the network fee can be cached for several seconds, accounting for differences between chains.

<Warning>
  **Fee Estimation Accuracy**

  Fee estimation endpoints return the estimated fee at the time of the call. The actual fee may change when the transaction is created due to factors such as network congestion or different UTXO selection caused by newer deposits.
</Warning>

# Learn more about Fees

1. [EVM Networks](https://support.fireblocks.io/hc/en-us/articles/10615179965596-EVM-fees-Overview)
2. [UTXO Based Assets](https://support.fireblocks.io/hc/en-us/articles/10616193193756-UTXO-fees-Overview)
3. [Unique Calculations](https://support.fireblocks.io/hc/en-us/articles/13995244288412-Solana-priority-fee)

<Info>
  ### Check out the [Fee Management Developer Guide](/reference/estimate-transaction-fee)
</Info>


# Wallet-as-a-Service
Source: https://developers.fireblocks.com/docs/wallet-as-a-service

Easily build and integrate custom, secure wallets into your application with Fireblocks' Wallet-as-a-Service API

# What is Wallet-as-a-Service?

Fireblocks Wallet-as-a-Service (WaaS) is an API-based solution that includes the most secure MPC wallets by design. Our APIs generate ECDSA and EdDSA signatures to sign any transaction. It enables anyone to create, manage, and secure wallets for any number of users without performing the security work themselves.

[Start developing on Fireblocks today](https://www.fireblocks.com/developer-sandbox-sign-up/?gl=1*19mlzew*_ga*MTY4ODc5Mjc3Ni\[%E2%80%A6]_ga_D39L1D2ZX2*MTY4Nzg2MTQwOS4xNi4xLjE2ODc4Njc3OTMuMjcuMC4w).

# Manage your digital assets with Fireblocks WaaS

You can easily plug and play Fireblocks Wallet-as-a-Service into your app — allowing your users to own and store digital assets — or facilitate your users to buy, sell, and trade cryptocurrencies, all with our self-custody solutions:

* **Scale without sacrificing security:** With our secure MPC wallets, you can create, manage, and secure deposits for any number of end-users in a compliant and reliable manner.
* **Supports businesses of all sizes:** Our WaaS product is compatible with various industries, including retail service, web3 companies, financial services and banking, exchanges, and financial market infrastructures.
* **Native support for 40+ blockchains:** Store your assets on the blockchain of your choice. And even if we don't support your blockchain, we offer raw signing so you can securely manage assets.
* **Monitor statuses of your transactions:** Using our tools like transaction status API, webhooks, and transaction history, you can stay up-to-date on the progress of your transactions and take action as needed.
* **Policy Engine:** Protect your custody from internal collusion, human error, and external attacks.

With the Fireblocks API, you can manage your workspace, automate your transaction flow, or use webhooks to receive push notifications on what's happening in your workspace. And in addition to the APIs, our Console can help monitor transactions and audits securely and reliably.

Learn more about [Fireblocks Wallet-as-a-Service](https://www.fireblocks.com/platforms/mpc-wallet/).

# Guides

## Deploying an NFT collection

Create an NFT collection using the ERC-721 standard and [deploy it with Fireblocks Hardhat Plugin](/reference/deploy-an-nft-collection).

## Creating Vaults and Wallets

[Generate Fireblocks vault accounts and asset wallets](/docs/creating-vaults-and-wallets) at scale for both account-based and UTXO asset wallet types using the Fireblocks API and SDKs.

## Minting an NFT

[Mint and verify Non-Fungible Tokens (NFT)](/reference/mint-an-nft) for your NFT collection using the Fireblocks Hardhat Plugin or Web3 Provider.

## Raw Message Signing

Support more chains and actions. Generate ECDSA and EdDSA signatures to [sign any transaction type or message](/docs/raw-signing).

## Typed Message Signing

Allows you to [sign messages using specific standard formats](/docs/typed-message-signing-1) that prefix the message with a magic string. For ETH\_MESSAGE and EIP712 messages.

## Creating a Transaction

Use transaction API calls to [initiate any Fireblocks transaction operation type](/reference/create-transactions), such as transfer, mint, burn, contract call, RAW, and more.

# Developer Community

Want to learn more from Fireblocks knowledge experts and other developers? [Join our developer community today](https://community.fireblocks.com/)!


# Wallet Link
Source: https://developers.fireblocks.com/docs/web3-wallet-link



# About the Fireblocks Wallet Link

As the demand for Web3 accessibility and usage grows, more users want to use dApps directly to manage their NFTs, get rewards, and more. The Fireblocks Wallet Link allows your users to connect their Fireblocks wallet addresses directly to Web3 applications (dApps), without your users needing to use their own wallet or any other application. This enables you to offer your users one-stop shopping for anything related to crypto and Web3.

# Creating a Wallet Link connection

The Wallet Link currently supports [WalletConnect](https://walletconnect.com/) connections. WalletConnect is a well-established standard for connecting wallets and Web3 applications and is supported by all of the leading dApps today.

When a user wants to connect to a dApp, they scan a QR code provided by WalletConnect inside the dApp. This QR code contains a URI that represents the connection session to be established between the dApp and the wallet. Passing this URI onto Fireblocks using the API allows the connection to be successful.

To initiate a new connection, pass the URI as follows.

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  const examplePayload = {  
  	feeLevel: "MEDIUM", 
  	vaultAccountId: 0,   
  	uri: "wc:f61647f4-7f98-4cb7-95d2-1db8e58fb0bb@1?bridge=https%3A%2F%2Fv.bridge.walletconnect.org&key=d145d64bda22f2be8fb23c251116b0cd8e3613f6971d193ff89b24e6735aaa6c" // The WalletConnect QR code  
  }

  const connectionResponse: CreateWeb3ConnectionResponse = await fireblocks.createWeb3Connection("WalletConnect", payload);
  ```
</CodeGroup>

<Info>
  ### For Web3 connections from a Non Custodial Wallet, please use the payload below:

  JavaScript

  ```javascript theme={"system"}
    const examplePayload = {  
      feeLevel: "MEDIUM", 
      ncwId: "b8337f1d-bd61-4d6c-afc1-4c9d60aa2132",
      ncwAccountId: 0, // or any other account in the NCW
      uri: "wc:f61647f4-7f98-4cb7-95d2-1db8e58fb0bb@1?bridge=https%3A%2F%2Fv.bridge.walletconnect.org&key=d145d64bda22f2be8fb23c251116b0cd8e3613f6971d193ff89b24e6735aaa6c" // The WalletConnect QR code  
    }
  ```
</Info>

The response from Fireblocks includes the relevant data about the connection, such as connection ID, dApp URL, and so on.

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  connectionResponse === {  
      id: "f3ca1e41-378e-4718-b8d3-51dddb3777d3",  
      sessionMetadata: { // Provided by the dApp  
          "appUrl": "https://www.someDapp.com",  
          "appName": "SomeDapp",  
          "appDescription": "SomeDapp is the best example dapp",  
          "appIcon": "https://static.fireblocks.io/prod/wcs/dappIcon/abc123"  
      }  
  }
  ```
</CodeGroup>

# Approving a Web3 connection request

You can approve or reject the Web3 connection request based on the data in the connection response.

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  const approve = true;  
  const result = await fireblocks.submitWeb3Connection("WalletConnect", connectionResponse.id, approve);
  ```
</CodeGroup>

<Info>
  ### Note

  If you want to limit your users to only some dApps, simply reject connection requests from any unapproved dApp.
</Info>

# Listing connections

To list all your existing Web3 connections, run the following command:

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  const examplePayload = {  
      pageCursor: "SomePageCursor" // undefined for first page,  
      pageSize: 10,  
      filter: {  
          vaultAccountId: 0,  
          connectionMethod: "API"  
      },  
      sort: "createdAt",  
      order: "DESC"  
  }

  const response = await fireblocks.getWeb3Connections(examplePayload);

  response.paging === { next:  "NextPageCursor" }  
  const exampleSession: Session = response.data[0];

  exampleSession === {  
      id: "f3ca1e41-378e-4718-b8d3-51dddb3777d3",  
      userId: "abc-123-456-def",  
      vaultAccountId: 0,  
      chainIds: ["ETH"],  
      feeLevel: "MEDIUM",  
      creationDate: "2023-03-08T11:20:13.823Z",  
      connectionType: "WalletConnect",  
      connectionMethod:"API",  
      sessionMetadata: {  
          "appUrl": "https://www.someDapp.com",  
          "appName": "SomeDapp",  
          "appDescription": "SomeDapp is the best example dapp",  
          "appIcon": "https://static.fireblocks.io/prod/wcs/dappIcon/abc123"  
      }  
  }
  ```
</CodeGroup>

# Removing a connection

To remove a connection, run the following command:

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  const result = await fireblocks.removeWeb3Connection("WalletConnect", exampleSession.id);
  ```
</CodeGroup>

# Signing a dApp-originated transaction

Once connected to a dApp, the user can perform an action that will result in a signing operation by Fireblocks. This operation is created by the API user that created the Web3 connection and is subject to the [Policies](https://support.fireblocks.io/hc/en-us/articles/4401998390546-TAP-for-DeFi-operations) like any other operation.

In most cases, a transaction created by a dApp translates into a Contract Call transaction in Fireblocks. Some other operations that require signing on an [off-chain message](https://support.fireblocks.io/hc/en-us/articles/4413379762450-Off-chain-message-signing) will result in a Typed message in Fireblocks, such as signing a registration message when logging into OpenSea.

Make sure to adjust your Policy rules accordingly. You can use the Policy as another layer of limitation by whitelisting the relevant contract addresses of any dApp you want to allow while preventing contract calls to any other contract to go through.

When working with an [API Co-Signer machine](https://support.fireblocks.io/hc/en-us/articles/12006018592156-API-Co-Signer-Overview), you can use the Callback Handler to let the user approve the transaction on their device before it is signed and broadcasted.


# What Is Fireblocks?
Source: https://developers.fireblocks.com/docs/what-is-fireblocks

Fireblocks is a user-friendly platform that uses direct custody to build new blockchain-based products and manage your digital asset operations. Direct custody is a type of self-custody that seamlessly blends high performance, zero counterparty risk, and multiple layers of security. With Fireblocks, you're always the owner and controller of your assets.

The Fireblocks direct custody model follows five core Custody & Risk Principles:

1. Provide an environment with zero counterparty risk.
2. Eliminate external and internal attack vectors.
3. Guarantee business continuity.
4. Ensure granular control and visibility of every transaction.
5. Deliver high-performance products and services with ease of use.

[Learn more about Fireblocks’ Custody & Risk Principles.](https://www.fireblocks.com/principles/)

The Fireblocks platform is comprised of three core components:

### Digital Asset Wallets

Secure, and scalable MPC-based wallets with robust key management to custody digital assets. The Fireblocks MPC-CMP protocol redefines private key security, never gathering a private key as one whole, eliminating risk. Fireblocks customers use our wallets for a range of operations, such as treasury, trading, cold storage, royalties, NFTs, smart contracts, and user wallets.

### Platform Governance

The Policy Engine automates governance policies for transaction rules and admin approvals. It enables you to configure a list of rules that dictate how transactions are handled and approved. A rule can set whether a transaction is blocked, approved, or requires additional signers using filters.

Policy Engine rules for various destinations, such as internal wallets, network connections, exchanges, fiat providers, whitelisted addresses, and contract wallets.

### Treasury Management

Fireblocks' single platform centralizes wallet and address management to simplify crypto and NFT treasury operations. Wallets are organized into Vault accounts (segregated or omnibus) where you can set specific transaction policies to protect the movement of funds.

The Fireblocks Network ensures transfers from Fireblocks wallets are simple and secure. The Network automatically authenticates deposit addresses to avoid manual deposit address entry and the need for test transfers.

Over 30 exchanges and fiat providers are connected to the Fireblocks Network, enabling you to securely deposit and withdraw from their exchange accounts. Thousands of businesses are also connected to the Fireblocks Network for secure peer-to-peer transfers.

# Fireblocks Multi-layer Security

Fireblocks has created a multi-layer security matrix that layers MPC, secure enclaves, our signature Policy Engine, and an asset transfer network to provide the strongest software and hardware defense available against evolving attack vectors.

Because we understand that no security technology alone is unbreakable, our approach to security protects all attack surfaces in a redundant structure to provide multiple fail-safes, in the event one security control fails.

Our security structure provides a truly secure environment for storing, transferring, and issuing digital assets. This ensures that your assets are protected from cyberattacks, internal colluders, and human errors. As a result, Fireblocks serves as the foundation for 1,000s of digital asset businesses and has securely transferred over \$3T in digital assets.

## Multi-Layer Security In-Depth

### Layer 1: MPC-CMP

MPC (multi-party computation) is a cryptographic technology that stores secret information with each party, then solves a problem that requires the unshared, decentralized input of all these parties' secret information. Fireblocks uses MPC over other technologies such as Multisig because MPC is protocol agnostic, operationally flexible, and less costly as signing occurs off-chain.

Fireblocks developed the MPC-CMP protocol that applies this concept to blockchain-based ECDSA and EdDSA signatures (used by all blockchains). The Fireblocks MPC-CMP protocol redefines private key security, never gathering a private key as one whole. MPC-CMP also requires fewer transaction rounds for signing (8x faster than standard MPC) and is available with cold storage signing where key shares are stored offline.

Fireblocks distributes the cryptographic MPC shares across multiple tier-1 cloud environments to ensure an extra layer of security even if one of the physical data centers is compromised. You can also store MPC shares across on-prem data centers or configure a hybrid scenario.

### Layer 2: Secure Enclaves

Fireblocks utilizes Intel SGX, a hardware-level enclave that isolates selected code and data within a system. It is designed to protect the cryptographic material, the cryptographic algorithm (MPC and ZKPs), and the execution of sensitive parts of the software from both insiders (such as rogue admins) and hackers.

As the MPC key shares are stored in SGX, they cannot be extracted even if malware or a hacker has control over the server’s OS – as the memory space and the data in the SGX enclave are encrypted. We also utilize SGX to secure API keys. In the trusted execution environments (TEEs) where we store these exchange credentials, the information cannot be retrieved by hackers, inside colluders, or even Fireblocks employees.

### Layer 3: Policy Engine

Fireblocks’ Policy Engine allows you to configure a list of rules that affect how transactions are handled and approved. A rule can set whether a transaction is blocked, approved, or requires additional signers using filters such as source, destination, asset, and amount.

Fireblocks secures the Policy Engine itself using SGX and distributes policy verification across several MPC servers. Policy rules are signed by a quorum of admins and encrypted within SGX; the engine is implemented inside of the SGX enclave and the code cannot be modified. This prevents both hackers and even insiders from modifying the implemented rules or the logic of the policy engine.

### Layer 4: Fireblocks Network

The Fireblocks Network is an institutional asset transfer network that completely mitigates the risks associated with deposit addresses by automating deposit address authentication and rotation. The Fireblocks Network entirely removes the need to copy and paste deposit addresses, then authenticate them using test transfers and whitelisting procedures.

Without an authentication network, it’s possible for assets to be lost through deposit address spoofing or human errors (such as entering a deposit address for a counterparty that they’ve already rotated out).

## Additional Security Measures

### Admin Quorum

The Admin Quorum defines the minimum number of administrators required to approve connections and workspace changes. This includes whitelisting addresses, approving network connections, exchange accounts, external destination addresses, approving new users, and approving other workspace configuration changes. The admin quorum prevents insider attacks, such as an administrator trying to whitelist their personal wallet address to steal funds.

### Multi-factor Authentication

Two-factor authentication is required at a minimum for all Fireblocks users. Any authenticator app may be used such as apps from Google, Microsoft, LastPass, or Yubico.

### Logging

All activity within the Fireblocks workspace, including administrative changes, and transactions are securely logged for auditing purposes. These logs can be viewed natively within the Fireblocks console, or exported to any log aggregation system, such as a SIEM.


# Overview
Source: https://developers.fireblocks.com/docs/whitelist-addresses



# Overview

To improve the security of transactions from your workspace, we recommend whitelisting destination addresses.

Whitelisting addresses is a general security best practice that helps prevent potential loss of funds. It protects against issues such as malicious address manipulation or human error, like copying and pasting the wrong address and inadvertently sending funds to an unintended recipient.

Each whitelisting request needs approval from the Admin Quorum before funds can be transferred to that address. If any admin rejects the request, the address will not be whitelisted. However, you can submit a new request to whitelist the same address, which can be approved by the Admin Quorum at any time.

In Fireblocks, there are three types of whitelisted address entities, each capable of holding different asset addresses:

* **External Wallets**
* **Internal Wallets**
* **Contracts**

<Check>
  ### Best Practice

  If you interact with a specific address multiple times, it should be added to the whitelisted addresses in your workspace.
</Check>

<Warning>
  ### Default Behavior

  By default, to send funds to an address outside of Fireblocks, the address must first be whitelisted. If you want to permit transactions to non-whitelisted addresses, you should enable the [One Time Address (OTA) feature](/docs/whitelist-addresses#work-with-one-time-addresses) in your workspace.
</Warning>

# Whitelisted Addresses Types

## External Wallets

External Wallets are entities that hold addresses external to your Fireblocks workspace and are not under your ownership. These addresses belong to your clients or counterparties. If you intend to whitelist an address that is not under your control, it should be added to the External Wallet entity. Note that External Wallet addresses do not display the on-chain balance of the whitelisted address.

## Internal Wallets

Internal Wallets are entities that hold addresses external to your Fireblocks workspace but are under your ownership. These addresses belong to your other wallets outside of Fireblocks. If you intend to whitelist a wallet address under your control that is outside of Fireblocks, it should be added to the Internal Wallet entity.

## Contracts

Contract Wallets are entities that hold whitelisted contract addresses. If you interact with smart contracts and want to restrict the approved list of contracts, you should whitelist the contract addresses under the Contract Wallet entity.

# Whitelisting at Scale

For businesses with a high volume of outgoing transactions in their fully automated workflows, whitelisting every external address can be cumbersome and disrupt the automation. To address this while maintaining high security standards, you can use one of the following approaches:

1. **API Key with Admin Permissions:** Create an API Key with admin permissions and set the required [approval group](https://support.fireblocks.io/hc/en-us/articles/11500062124188-Approval-groups) for the whitelisting operation to **1**.\
   Pair the API Key with an API Cosigner and create a Cosigner Callback Handler server on your end, connecting it to your Cosigner.\
   In this setup, you can call the whitelisting address APIs before each transaction while the approval will be fully automated by the API Key acting as part of the admin quorum.\
   Additionally, each request will be sent to your callback handler, allowing you to programmatically decide whether the address should be whitelisted.

2. **Fireblocks One Time Address Feature:** Utilize the Fireblocks One Time Address (OTA) feature to send funds to a non-whitelisted address. This can be done by combining the appropriate Policy rules and potentially implementing internal validations on your callback handler.

# Work with One Time Addresses

The One Time Address (OTA) feature lets you transfer assets to non-whitelisted addresses in your Fireblocks workspace.

Unlike whitelisted addresses, one-time addresses do not require approval by the Admin Quorum to transfer funds to them. However, enabling the OTA feature requires approval by the workspace Owner and the Admin Quorum.

You can enable the OTA feature [via the Fireblocks Console](https://support.fireblocks.io/hc/en-us/articles/4409104568338-One-Time-Address-OTA-feature) or the [Fireblocks API](/reference/setotastatus).

<Warning>
  ### This feature poses security risks!

  We recommend [setting up a strict Policy](https://support.fireblocks.io/hc/en-us/articles/7361652234524-TAP-best-practices) before enabling it. You can set a variety of such Policy protective limitations, such as:

  * Restricting one-time address transfers only to certain preselected users or groups
  * Requiring approval for one-time address transfers above a certain threshold
</Warning>


# Whitelist IPs for API Keys
Source: https://developers.fireblocks.com/docs/whitelist-ips-for-api-keys

The IP allowlist (whitelist) enables you to restrict API calls to only accept specific IP addresses for each API key. Only allowing access to a select number of IP addresses can lower the chances of a security threat or malicious attack.

If you have workspace owner permissions, you can follow [these instructions](https://support.fireblocks.io/hc/en-us/articles/4405980040210-Whitelisting-API-IP-Addresses) on the Help Center to add IP addresses to the allowlist.

Alternatively, you can also submit a ticket to Fireblocks Support with the IP addresses of the machines running your API client(s) and their matching API key(s).


# Work with Fireblocks Gas Station
Source: https://developers.fireblocks.com/docs/work-with-gas-station



# Overview

Most Ethereum Virtual Machine (EVM)-based blockchains require a fee, called *gas*, to be paid in their base asset to execute transactions of both the base asset and other tokens. Gas is deducted from the account that initiated the transaction.

The Fireblocks Gas Station auto-fuels a vault account with the required base asset when it is enabled for them. Using the Gas Station helps cases of Fireblocks customers who choose to use the omnibus account vault structure or similar.

All transfers on Fireblocks, including those between vault accounts, occur on the blockchain. Therefore, you must pay gas fees when transferring funds from the deposit accounts to your omnibus vault account.

The auto-fuel transaction is triggered whenever a withdrawal or deposit is detected to or from that vault account. Fireblocks checks the balance of the vault and transfers gas according to the [Gas Station parameters](/docs/enabling-the-gas-station-1#gas-station-parameters).

The Gas Station removes the need to monitor your base asset levels and manually transfer funds to your vault accounts to cover future transaction fees when funds are swept to your central vault (omnibus) account, where they can be invested.

# Supported networks

Ethereum and all EVM-based networks available in your Fireblocks workspace are supported.

[See a complete list of Fireblocks Gas Station's supported networks with additional information](https://support.fireblocks.io/hc/en-us/articles/360016557960-Fireblocks-Gas-Station).

# Common use cases for Gas Station

Many retail businesses use the omnibus structure, making the Gas Station a helpful feature when many vault accounts are required to receive individual direct deposits from end clients.

1. In this case, you'd [monitor the Transaction status using webhooks](/reference/monitoring-transaction-status).
2. Then, upon receiving the `COMPLETED` transaction status, [trigger a sweep from the end-client vault account to your omnibus deposits vault account](/docs/sweep-funds).

Other business types using the Gas Station include exchanges, lending desks, neobanks, and commercial and investment banks.


# Workspace Comparison
Source: https://developers.fireblocks.com/docs/workspace-environments



# Overview

Fireblocks has three types of workspaces. The workspace type you use will determine your capabilities, so knowing which type you're working in is important.

* Developer Sandbox environments and Testnet workspaces are used for development and testing.
* Mainnet workspaces are used to deploy into production (with real funds).

Even though each workspace type has different capabilities, they all utilize similar APIs and SDKs, allowing you to develop and test your code against "lower" environments before deploying to your live production environment.

# Workspace Types

|                           | Developer Sandbox                                                                                                                                              | Testnet                                                                                                                                                                                                         | Mainnet                                                                                                                                                                                        |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Purpose**               | The [Fireblocks Developer Sandbox](/docs/quickstart) is a unique workspace built for developers to quickly start using Fireblocks APIs and SDKs.               | Recommended for API testing. Before you go live, we recommend performing a test transaction on the Mainnet using both the Console UI and the API.                                                               | This is a full-production workspace.                                                                                                                                                           |
| **Workflow testing**      | Quick experimentation                                                                                                                                          | Pre-production development & testing                                                                                                                                                                            | Staging & production                                                                                                                                                                           |
| **Console URL**           | sandbox.fireblocks.io                                                                                                                                          | console.fireblocks.io                                                                                                                                                                                           | console.fireblocks.io                                                                                                                                                                          |
| **API URL**               | sandbox-api.fireblocks.io                                                                                                                                      | api.fireblocks.io/v1                                                                                                                                                                                            | api.fireblocks.io/v1                                                                                                                                                                           |
| **Derivation paths**      | [Sandbox workspace exceptions](https://support.fireblocks.io/hc/en-us/articles/16097541672732-Path-differences-between-Sandbox-Testnet-and-Mainnet-workspaces) | [Testnet workspace exceptions](https://support.fireblocks.io/hc/en-us/articles/16097541672732-Path-differences-between-Sandbox-Testnet-and-Mainnet-workspaces)                                                  | [Fireblocks vault HD derivation paths](https://support.fireblocks.io/hc/en-us/articles/360014330819-Fireblocks-Vault-HD-derivation-paths)                                                      |
| **Assets**                | Testnet assets that are independent of Mainnet assets and operate on their own Testnet blockchains.                                                            | Testnet assets that are independent of Mainnet assets and operate on their own Testnet blockchains.                                                                                                             | Mainnet / Real assets.                                                                                                                                                                         |
| **API**                   | Full API access with the most limited rate limits. Used for testing the API.                                                                                   | Full API access with limited rate limits. Used for testing the API.                                                                                                                                             | Full API access with increased rate limits. Used for implementing the tested API configuration. Requires a separate API key from a Testnet workspace; this can be done with the same CSR file. |
| **Policies**              | Non-editable                                                                                                                                                   | [Fully editable](/docs/set-transaction-authorization-policy)                                                                                                                                                    | [Fully editable](/docs/set-transaction-authorization-policy)                                                                                                                                   |
| **API Co-Signer**         | Only [Fireblocks-provided API Co-Signer](/reference/use-communal-cosigner).                                                                                    | Fireblocks-provided or self-hosted API Co-Signer.                                                                                                                                                               | Self-hosted API Co-Signer.                                                                                                                                                                     |
| **API user limit**        | Up to 5 users                                                                                                                                                  | Limited to the client setting                                                                                                                                                                                   | Limited to the client setting                                                                                                                                                                  |
| **Webhooks**              | Available for testing                                                                                                                                          | Available for testing                                                                                                                                                                                           | Available                                                                                                                                                                                      |
| **Mobile access**         | N/A                                                                                                                                                            | Fireblocks mobile app (iOS and Android) to sign and authorize transactions, approve external connections, and workspace changes.                                                                                | Fireblocks mobile app (iOS and Android) to sign and authorize transactions, approve external connections, and workspace changes.                                                               |
| **Fireblocks Network**    | N/A                                                                                                                                                            | N/A                                                                                                                                                                                                             | All Fireblocks Network connections are available.                                                                                                                                              |
| **Exchanges**             | Limited exchange integration support (only testnets).                                                                                                          | Limited exchange integration support (only testnets). We recommend setting Policy rules that apply to transactions on exchanges to accommodate test transactions that are processed approximately once per day. | All Fireblocks exchange connectivity is available.                                                                                                                                             |
| **Fiat**                  | Testnet only                                                                                                                                                   | Testnet only                                                                                                                                                                                                    | All Fireblocks fiat integrations                                                                                                                                                               |
| **DeFi/Web3**             | Testnet protocols with WalletConnect Desktop integration.                                                                                                      | Testnet protocols with WalletConnect Mobile and Desktop integrations.                                                                                                                                           | Full support. Requires a specific policy implementation to enable.                                                                                                                             |
| **AML**                   | N/A                                                                                                                                                            | N/A                                                                                                                                                                                                             | Most assets are supported via Chainalysis or Elliptic.                                                                                                                                         |
| **Raw Signing enabled**   | Yes                                                                                                                                                            | Requires a signed commercial agreement + Support enablement                                                                                                                                                     | Requires a signed commercial agreement + Support enablement                                                                                                                                    |
| **Support & Help Center** | [Developer Community support](https://community.fireblocks.com/) with Help Center access                                                                       | Full Support with Help Center access                                                                                                                                                                            | Full Support with Help Center access                                                                                                                                                           |

# Mainnet

Mainnet is a production-level blockchain network with cryptocurrency transactions being broadcast, verified, and recorded. Mainnets have a base asset that can be used as funds in transactions or to pay network fees. All assets on Mainnets have real-world monetary value.

A Mainnet workspace is a fully developed and deployed environment that allows you and your organization to conduct your real-world financial operations on the Fireblocks platform.

In Mainnet workspaces, you can securely:

* Transfer digital assets
* Add users
* Create a Vault account or multiple
* Whitelist new addresses
* Connect to supported exchanges
* Connect to other Fireblocks Network members
* Configure MPC-CMP devices
* Establish network connections

<Warning>
  ### Moving to Mainnet workspaces

  When you’re ready to use your Mainnet workspace, there are a few things to keep in mind before you get started.

  * When testing new functions in Mainnet (production) environments, use small amounts first to confirm intended functionality before upscaling to larger amounts.
  * Other than the users you add to both, your Mainnet and testnet workspaces are completely different workspaces. Your Mainnet workspace will require its own vault accounts and asset wallets, exchange and fiat account connections, policies, users, and more.
  * You must define the Mainnet workspace’s Policy rules to work in accordance with the Mainnet workspace’s various users, user groups, sources, destinations, and assets. These parameters will likely be different from what you used in your testnet workspace.
  * You must configure your Mainnet workspace to work with any API integrations and third-party accounts you want to carry over from your testnet workspace. This includes creating a new API key for and provisioning your API Co-Signer. Note that you can add Fireblocks Console users, adjust the Admin Quorum, and connect to exchange accounts, fiat accounts, and Fireblocks Network members before or after you configure your API integrations.
</Warning>

# Testnet

Testnet is a blockchain test network used by developers to run tests with the blockchain. Testnets operate on blockchains separate from their associated Mainnet. Testnet assets have no monetary value, and many of them reset periodically.

A Testnet workspace is a testing-level environment that only allows you to use Testnet assets for integration and testing purposes. You can also perform many of the same actions you can in a Mainnet workspace without incurring real-world fees.

In the Fireblocks Console, the "**Testnet Environment**" badge appears at the top of the page to help you identify your Testnet workspace.

## Limitations of Testnet workspaces

The Testnet workspace will have certain conditions to protect you from losing real assets and compromising security while you test, such as:

* Only Testnet assets and Testnet blockchains are supported (e.g., Ethereum Sepolia Testnet)
* Simplified signing process that removes many security features in favor of simple setup and testing, such as no mobile signing application support and no client co-signer support
* Limited exchange integrations since not all exchanges support Testnet blockchains and may not work as they would on Mainnet
* Fiat integrations will only work on fiat test networks
* DeFi and Web3 have limited blockchain and Web3 dApp test network support
* The Fireblocks Network is not available
* Transaction screening AML/KYT integrations are not available
* Reduced API rate limits (production-level load testing is not available)

# Developer Sandbox

Sandbox workspaces are freely available to sign up for. These workspaces are geared towards quick development and experimentation. Here are some of the highlights of Sandbox environments:

* When creating API users, the CSR certificate required to generate the private key is automatically created in the browser.
* Access to the Developer Area API Monitoring feature that displays the workspace's API calls and errors over 24-hour and 7-day periods.
* No mobile signing devices are needed since all transactions are auto-approved, reducing the complexity of trying out the Fireblocks API.

## Differences in Sandbox User Roles

When creating new Console or API users in Developer Sandbox workspaces, there are only three workspace roles available:

* Non-Signing Admin
* Editor
* Viewer

In Sandbox workspaces, the Owner role is taken up by a backend service that manages auto-approvals to make experimentation and development easier. Therefore, the Non-Signing Admin replaces this role type and has the highest level of permissions, which are not present in Mainnet/Testnet workspaces, such as:

* Creating and deleting users
* Resetting 2FA for workspace users
* Signing transactions (despite the "non-signing" in the role's name)

For more information about workspace roles and permissions in production Mainnet and Testnet workspaces, [visit our Help Center](https://support.fireblocks.io/hc/en-us/articles/360012832959-User-roles).

# Supported Mainnets, Testnets, and Assets

Visit the [Supported blockchain networks](https://support.fireblocks.io/hc/en-us/articles/8993656344092-Supported-blockchain-networks) page in our Help Center to learn more about supported Mainnets, Testnets, and assets.


# Add Tokens
Source: https://developers.fireblocks.com/reference/add-your-tokens



Fireblocks allows clients to add tokens across various blockchains via the Fireblocks API. To register a new token, use the [Register a New Asset](/reference/registernewasset) endpoint with the appropriate parameters for the supported blockchain.

The blockchains supported for self-token addition via the API include:

* EVM-based chains
* Algorand
* NEAR
* Solana
* Stellar
* Sui
* TON
* TRON

The API requires a `POST` request with the following parameters:

* **blockchainId:** The unique network identifier (e.g., `ETH`).
* **address:** The asset address:
  * **EVM-based chains:** Token contract address
  * **Algorand (ALGO):** Asset ID
  * **NEAR:** Token address
  * **Solana:** Token's mint account address
  * **Stellar (XLM):** Issuer address
  * **Sui:** The token's type
  * **TON:** Token address
  * **TRON (TRX):** Token contract address
* **symbol:** Required for XLM tokens only

## Code example

Below is a code example for adding a new token to your workspace:

```javascript theme={"system"}
import { readFileSync } from 'fs';
import { Fireblocks, BasePath } from "@fireblocks/ts-sdk";

const FIREBLOCKS_API_SECRET_PATH = "<PATH_TO_YOUR_SECRET>";

// Initialize a Fireblocks API instance with local variables
const fireblocks = new Fireblocks({
    apiKey: "<YOUR_API_KEY>",
    basePath: BasePath.US,
    secretKey: readFileSync(FIREBLOCKS_API_SECRET_PATH, "utf8"),
});

(async() => {

  const addTokenRes = await fireblocks.blockchainsAssets.registerNewAsset({
    registerNewAssetRequest: {
      blockchainId: "ETH",
      address: "0xdBA8e8021FE321af91FC3A08e223EF15908cB2bB"
    }
  })

  console.log(JSON.stringify(addTokenRes, null, 2))

})();
```

In this example, we are adding the`0xdBA8e8021FE321af91FC3A08e223EF15908cB2bB` token (Smart Contract address) on the Ethereum network.


# Address Registry
Source: https://developers.fireblocks.com/reference/address-registry



# Overview

Address Registry lets you verify the legal entity controlling a blockchain address before sending or receiving a transaction. When enabled, Address Registry allows you to query blockchain addresses and receive certain legal entity information about the institution controlling the associated vault. The Address Registry is designed solely to facilitate counterparty discovery and verification in connection with digital asset transactions.

Address Registry is a free capability available to all Fireblocks customers and enabled by default. Coverage is currently limited to addresses within the Fireblocks network.

<Note>
  **Early access**

  This feature is currently in Early Access (a Beta Service). To request access, enable it in [Settings > Labs](https://console.fireblocks.io/v2/settings/labs) or contact your Fireblocks Customer Success Manager. Early Access features are subject to the beta terms under [Product Specific Terms](https://www.fireblocks.com/product-specific-terms#beta-services).
</Note>

## Look up an address

Query a blockchain address to retrieve the legal entity information associated with it.

### Request

```http theme={"system"}
GET /v1/address_registry/legal_entities/{address}
```

| Parameter | Type   | Required? | Description                        |
| --------- | ------ | --------- | ---------------------------------- |
| `address` | string | Yes       | The blockchain address to look up. |

### Response

If the address resolves to an opted-in Fireblocks customer:

```json theme={"system"}
{
  "verified": true,
  "entityName": "ACME Corporation",
  "jurisdiction": "US",
  "lei": "254900GC33RBE6FQA817",
  "travelRuleProviders": [
    "TRAVEL_RULE_PROVIDER_NOTABENE",
    "TRAVEL_RULE_PROVIDER_SYGNA"
  ],
  "email": "compliance@example.com"
}
```

| Field                 | Type    | Description                                                                                                                                                |
| --------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `verified`            | boolean | `true` if entity data is sourced from an approved LEI and validated by Fireblocks. `false` if sourced from Fireblocks data without independent validation. |
| `entityName`          | string  | Legal entity name associated with the vault controlling the address.                                                                                       |
| `jurisdiction`        | string  | ISO country code of the legal entity.                                                                                                                      |
| `lei`                 | string  | Legal Entity Identifier (LEI) of the counterparty, if available.                                                                                           |
| `travelRuleProviders` | array   | Travel Rule providers the counterparty supports, if declared.                                                                                              |
| `email`               | string  | Counterparty's Travel Rule contact email, if declared.                                                                                                     |

If the address is not found — because the counterparty is not a Fireblocks customer, has opted out, or is on an unsupported environment — the response returns HTTP 404:

```json theme={"system"}
{
  "code": "2142",
  "message": "Address could not be resolved"
}
```

<Note>
  **Notes about the Address Registry lookup**

  * A `not_found` result does not indicate that the address is unhosted, illicit, or non-compliant.
  * The registry is designed to prevent bulk data extraction or misuse. We put in place various controls like query authentication, API rate limiting, daily request caps, and alerts to ensure the number of queries remains proportional to the number of transactions. See [the FAQ](https://support.fireblocks.io/hc/en-us/articles/26105830582940-Address-Registry#h_01KP5Z8EQMTNW36W3RSNQJV9C9) for more details.
</Note>

## Register a legal entity

To appear as a verified entity when counterparties look up your addresses, register your Legal Entity Identifier (LEI) with Fireblocks. This step is optional if you only want to query addresses, but required to return verified data and to use Address Registry in compliance workflows.

Each workspace can register multiple legal entities.

### Request

```http theme={"system"}
POST /v1/legal_entities
```

```json theme={"system"}
{
  "lei": "529900HNOAA1KXQJUQ27",
  "travelRuleProviders": [
    "MY_OWN"
  ],
  "travelRuleContactEmail": "compliance@example.com"
}
```

| Parameter                | Type   | Required? | Description                                                                                                                                                                 |
| ------------------------ | ------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `lei`                    | string | Yes       | A valid 20-character LEI present in the GLEIF registry.                                                                                                                     |
| `travelRuleProviders`    | array  | No        | Travel Rule providers to associate with this entity. Enum: `CODE`, `GTR`, `MY_OWN`, `NOTABENE`, `SYGNA`, `SUMSUB`, `TRISA`, `TRUST`, `TWENTY_ONE_ANALYTICS`, `VERIFY_VASP`. |
| `travelRuleContactEmail` | string | No        | Contact email for Travel Rule communications.                                                                                                                               |

### Response (success)

```json theme={"system"}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "lei": "529900HNOAA1KXQJUQ27",
  "status": "PENDING",
  "isDefault": false,
  "travelRuleProviders": [
    "MY_OWN"
  ],
  "travelRuleContactEmail": "compliance@example.com",
  "gleifData": {
    "lei": "529900HNOAA1KXQJUQ27",
    "legalName": "Example Corporation Ltd.",
    "otherNames": [
      "ExCorp",
      "Example Corp"
    ],
    "legalAddressRegion": "NY",
    "legalAddressCountry": "US",
    "nextRenewalDate": "2025-12-31T00:00:00Z"
  },
  "createdAt": "1700000000000",
  "updatedAt": "1700000000000"
}
```

### Error responses

| Code     | Meaning                                                               |
| -------- | --------------------------------------------------------------------- |
| HTTP 400 | Invalid LEI or request parameters.                                    |
| HTTP 404 | LEI not found in the GLEIF registry.                                  |
| HTTP 409 | A legal entity with this LEI is already registered for the workspace. |

### LEI states

After you submit an LEI, it moves through the following states:

| State      | Description                                                                                                    |
| ---------- | -------------------------------------------------------------------------------------------------------------- |
| `Pending`  | Submitted and under Fireblocks review. Your addresses appear as unverified to counterparties during this time. |
| `Approved` | Verified by Fireblocks. Queries against your addresses return your legal entity name, jurisdiction, and LEI.   |
| `Denied`   | Rejected by Fireblocks. You can view the reason and resubmit.                                                  |
| `Revoked`  | Previously approved, then revoked due to an expired or invalid LEI.                                            |

### Map vault accounts to legal entities

After Fireblocks approves your first LEI, all vault accounts map to that entity by default. If you register additional legal entities and want to map specific vault accounts to them, refer to the [legal entity endpoints in the API reference](https://docs.fireblocks.com/api/swagger-ui/#/Compliance/assignVaultsToLegalEntity). Each vault account supports a maximum of one legal entity.

## Opt out of Address Registry

You can opt out your entire workspace or individual vault accounts. When you opt out, lookups against your addresses return `not_found`. You can disable and re-enable at any time.

<Note>
  **Notes about opting out**

  * Opting out prevents you from querying addresses or using compliance workflows that depend on Address Registry.
  * Opting out disables all compliance workflows built on Address Registry. Re-enabling restores them.
</Note>

### Opt out an entire workspace

```sql theme={"system"}
DELETE /v1/address_registry/tenant
```

No request body is required. A successful response returns a status of `OPTED_OUT` using the same JSON structure as the [GET participation status endpoint](https://docs.fireblocks.com/api/swagger-ui/#/Compliance/getAddressRegistryTenantParticipationStatus).

### Opt out individual vault accounts

Add vault account IDs to the opt-out list:

```http theme={"system"}
POST /v1/address_registry/vaults
```

```json theme={"system"}
{
  "vaultAccountIds": [
    10001,
    "10002"
  ]
}
```

| Parameter         | Type  | Required? | Description                                                                      |
| ----------------- | ----- | --------- | -------------------------------------------------------------------------------- |
| `vaultAccountIds` | array | Yes       | Vault account IDs to add to the opt-out list. Accepts both integers and strings. |

## Use Address Registry in compliance workflows

You can use Address Registry inside your transaction screening policy to automate compliance decisions based on counterparty identity. The workflow has two parts: define counterparty groups, then apply rules to those groups in a screening policy.

<Note>
  **Feature coming soon**

  Compliance workflows are not yet available but will be added during the Early Access phase.
</Note>

### Define counterparty groups

A *counterparty group* is a named set of counterparties that share specific attributes. You can create as many groups as you need. Jurisdiction is the only available grouping attribute initially. Additional attributes such as business type and license type are planned.

**API endpoints:**

```http theme={"system"}
POST   /v1/counterparty-groups          # Create a group
GET    /v1/counterparty-groups          # List all groups
PUT    /v1/counterparty-groups/{id}     # Update a group
DELETE /v1/counterparty-groups/{id}     # Delete a group
```

### Set a screening policy

The screening policy consists of two parts:

* **Transaction screening policy**: Defines which transactions trigger a counterparty check. Build rules using source, destination, asset, and amount. Rules evaluate from top to bottom, and the first match wins. A catch-all default rule is required as the last entry. You also configure timeout behavior separately to define what happens if the registry check times out during a transaction (accept or reject).
* **Post-screening policy**: Defines the action to take based on the counterparty check result.

| Condition                       | Action           |
| ------------------------------- | ---------------- |
| Counterparty is in \[Group]     | Accept or Reject |
| Counterparty is not in \[Group] | Accept or Reject |
| Address not found in registry   | Accept or Reject |

**API endpoints:**

```http theme={"system"}
PUT    /v1/counterparty-groups/policy   # Configure screening policy
GET    /v1/counterparty-groups/policy   # Get current policy
GET    /v1/counterparty-groups/address  # Get group context for an address
```

## Availability and limitations

Fireblocks does not currently support Address Registry for workspaces hosted on European or Swiss environments due to infrastructure isolation between production instances. We plan to add support for these environments shortly after the initial release. In the meantime, queries against addresses from European or Swiss-hosted workspaces return `not_found`.

Address Registry is not available in Developer Sandbox workspaces.


# Android SDK errors
Source: https://developers.fireblocks.com/reference/android-sdk-errors



| Error Code | Error Message                                                                    | Description                                                                                                                                                                                                                  |
| ---------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 102        | Invalid Certificate                                                              | Invalid Certificate, it might be expired or the device clock is out of sync                                                                                                                                                  |
| 106        | Missing algorithms                                                               | Indicates that `com.fireblocks.sdk.Fireblocks.generateMPCKeys` was called with an empty set of algorithms.                                                                                                                   |
| 108        | Incomplete device setup                                                          | Indicates that our device setup is incomplete. For example if we generated a key but we didn't perform backup                                                                                                                |
| 107        | Missing private keys                                                             | The client failed to load the keys' content provided by the `com.fireblocks.sdk.keys.FireblocksKeyStorage` implementation. This implementation is provided to `com.fireblocks.sdk.Fireblocks` via the initialization method. |
| 110        | Invalid physical device id                                                       | Indicates that we have an invalid physical device id. Please check if your device was recovered from a different physical device                                                                                             |
| 111        | Max devices per wallet reached                                                   | The maximum number of devices in a wallet is reached while trying to add a new device.                                                                                                                                       |
| 200        | Timeout during key creation, didn't get startup message                          | During key creation, several messages from the backend are handled. The first message did not arrive in the expected amount of time.                                                                                         |
| 201        | Unknown algorithm                                                                | Indicates that `com.fireblocks.sdk.Fireblocks.generateMPCKeys` was called with an invalid algorithm.                                                                                                                         |
| 202        | Failed to generate key, key exists in server but not on the device               | The metadata of the key was previously sent to the backend, but the key is no longer on the client.                                                                                                                          |
| 203        | Timeout during key creation                                                      | During key creation, several messages from the backend are handled. One of the second-to-last messages did not arrive in the expected amount of time.                                                                        |
| 204        | Failed to send public key                                                        | The public key failed to back up with the backend after key creation.                                                                                                                                                        |
| 205        | Failed to request key                                                            | One or more of the key requests failed to initiate.                                                                                                                                                                          |
| 206        | Failed to enroll player                                                          | The process to register the `deviceId` with the backend failed.                                                                                                                                                              |
| 207        | Failed to create key                                                             | During key creation, several messages from the backend are handled. One of the messages failed to process on the device.                                                                                                     |
| 208        | Failed to confirm key                                                            | Used in `com.fireblocks.sdk.Fireblocks.generateMPCKeys` during key creation, a key was not fully confirmed in the backend                                                                                                    |
| 300        | Failed to request end-user takeover                                              | A failure to receive keys for takeover from the backend.                                                                                                                                                                     |
| 301        | Failed to takeover keys                                                          | There was an error while processing the takeover request on all keys.                                                                                                                                                        |
| 302        | Timeout during key takeover                                                      | A failure to receive keys for takeover from the backend in the expected amount of time.                                                                                                                                      |
| 400        | Failed to export keys                                                            | The client failed to export all the available keys.                                                                                                                                                                          |
| 401        | Missing public keys                                                              | Some of the data needed to export the key is unavailable.                                                                                                                                                                    |
| 402        | Missing public key                                                               | The client failed to load the keys provided by the `com.fireblocks.sdk.keys.FireblocksKeyStorage` implementation. This implementation is provided to `com.fireblocks.sdk.Fireblocks` via the initialization method.          |
| 403        | Failed to derive asset key                                                       | Deriving the asset key failed.                                                                                                                                                                                               |
| 404        | Missing cloud private keys                                                       | The cloud key share is not the full key share.                                                                                                                                                                               |
| 405        | Missing chain code                                                               | The relevant chain code is missing.                                                                                                                                                                                          |
| 406        | Missing private key                                                              | The client failed to load the keys provided by the `com.fireblocks.sdk.keys.FireblocksKeyStorage` implementation. This implementation is provided to `com.fireblocks.sdk.Fireblocks` via the initialization method.          |
| 407        | Failed to export key, recovered PublicKey is not equal to the original PublicKey | The recovered key is not equal to the original key.                                                                                                                                                                          |
| 408        | Failed to export key                                                             | The key export failed. The reason for failure may be located in the logs.                                                                                                                                                    |
| 500        | Failed to sign transaction, unknown txId                                         | Indicates that `com.fireblocks.sdk.Fireblocks.signTransaction` was called with an invalid transaction ID.                                                                                                                    |
| 501        | Error during transaction signing creation, didn't get start signing message      | During transaction signing, several messages from the backend are handled. The first message failed to arrive in the expected amount of time.                                                                                |
| 502        | Failed to sign transaction                                                       | The message processing failed.                                                                                                                                                                                               |
| 503        | Timeout during transaction signing                                               | During transaction signing, several messages from the backend are handled. One of the second-to-last messages failed to arrive in the expected amount of time.                                                               |
| 504        | Transaction signing was stopped                                                  | Used in `com.fireblocks.sdk.Fireblocks.signTransaction` Indicates that the transaction signing was stopped                                                                                                                   |
| 600        | Backup not available                                                             | There are no keys to recover from the backend.                                                                                                                                                                               |
| 601        | Failed to recover keys                                                           | The key recovery process failed.                                                                                                                                                                                             |
| 603        | Wrong passphrase                                                                 | The provided passphrase is wrong                                                                                                                                                                                             |
| 700        | Failed to get key IDs                                                            | The client failed to fetch the key's metadata from the backend.                                                                                                                                                              |
| 701        | Missing key IDs in server for backup                                             | The client failed to fetch the key's metadata from the backend.                                                                                                                                                              |
| 702        | We have a discrepancy between valid key IDs between server and client            | A discrepancy exists between the `keyId` parameters stored on the client and the backend.                                                                                                                                    |
| 703        | Failed to backup keys, missing keys                                              | The client failed to fetch the key's metadata from the backend.                                                                                                                                                              |
| 704        | Failed to backup key                                                             | The key backup process with the backend failed.                                                                                                                                                                              |
| 705        | Invalid passphrase error                                                         | The used passphrase is invalid.                                                                                                                                                                                              |
| 800        | Invalid add device setup data                                                    | The request to add a device failed due to invalid data.                                                                                                                                                                      |
| 900        | Failed to join wallet                                                            | The request to join an existing wallet failed.                                                                                                                                                                               |
| 901        | Timeout during join wallet                                                       | The request to join an existing wallet timed out.                                                                                                                                                                            |
| 902        | Join wallet was stopped                                                          | The request to join an existing wallet was stopped.                                                                                                                                                                          |
| 1000       | Failed to approve join wallet                                                    | The request to approve a new device joining an existing wallet failed.                                                                                                                                                       |
| 1001       | Timeout during approve join wallet                                               | The request to approve a new device joining an existing wallet timed out.                                                                                                                                                    |
| 1002       | No keys to provision                                                             | Indicates that `com.fireblocks.sdk.Fireblocks.approveJoinWalletRequest` was called with an empty set of algorithms.                                                                                                          |
| 1003       | Approve join wallet was stopped                                                  | The request to approve a new device joining an existing wallet was stopped.                                                                                                                                                  |

<br />


# API Co-signer Deployment Options and Installation Flow
Source: https://developers.fireblocks.com/reference/api-cosigner-installation-flow



This article outlines the available deployment options and the process for setting up a Co-signer to enable automatic transaction signing and approval of workspace configuration changes.

## API Co-signer installation flow

After installing the Co-signer, configure the [Policy](https://support.fireblocks.io/hc/en-us/articles/7354983580316-About-the-TAP) to [designate the API user](https://support.fireblocks.io/hc/en-us/articles/7365877039004-Rule-parameters#h_01HGBN9QQ0T42NR8XT4Y96V7YH) paired with the Co-signer as the signer. This ensures that when a transaction meets the criteria defined in the policy, it will be automatically signed by the Co-signer that is paired to the specified API user.

### Step 1: Setup and configure your deployment environment

Setup and configure the resources needed for the Co-signer to function within your environment. Additionally, configure your network and security services to allow access to the domains required for the Co-signer's installation and operation.

### Step 2: Add a new Co-signer to the workspace using an API user

Using the Fireblocks Console or APIs, create an API user and use it to add a new Co-signer to the workspace.

### Step 3: Install and connect the Co-signer to the workspace

After preparing and configuring all necessary resources, download and run the installation script that matches your Co-signer type. Please select to deployment options below depending on which environment you have.

## API Co-signer deployment options

> **The environment setup and Co-signer installation process vary based on the chosen Co-signer type and deployment environment.**
>
> Click on the links below for detailed step-by-step setup and installation instructions

<CardGroup>
  <Card title="Azure SGX" href="/reference/install-api-cosigner-azure">
    Install in Microsoft Azure
  </Card>

  <Card title="On-Prem SGX" href="/reference/install-api-cosigner-onprem">
    Install On-Premise
  </Card>

  <Card title="AWS Nitro" href="/reference/install-api-cosigner-aws">
    Install in Amazon Web Services
  </Card>

  <Card title="GCP Confidential Space" href="/reference/install-api-cosigner-gcp">
    Install in Google Cloud
  </Card>

  <Card title="Alibaba Cloud SGX" href="/reference/install-api-cosigner-alibaba">
    Install in Alibaba Cloud
  </Card>

  <Card title="IBM Cloud SGX" href="/reference/install-api-cosigner-ibm">
    Install in IBM Cloud
  </Card>
</CardGroup>


# API Co-signer Maintenance
Source: https://developers.fireblocks.com/reference/api-cosigner-maintenance



This article outlines the most common maintenance operations for Co-signers. Since each Co-signer type has a unique architecture and is installed in a specific environment, refer to the relevant article for detailed maintenance instructions for your Co-signer type.

> **Note**: Due to the enclave architecture of the Google Cloud Confidential Space Co-signer, maintenance operations can only be performed through Google Cloud's portal or using `gcloud`.

Co-signer maintenance include:

* View the logs
* Observe the status
* List the paired API users
* Retrieve the public key (used for the Callback Handler JWT authentication)
* Stop the Co-signer
* Restart the Co-signer
* Retrieve the running version
* Update the Co-signer
* Migrate to a new machine
* Configure a proxy server
* Configure the communication protocol

Use the [Co-signer management tab](https://support.fireblocks.io/hc/en-us/articles/17923671680540-The-Co-signer-management-tab) to observe the Co-signer's online / offline status and the list of paired API users and refer to the following guides to learn about platform-specific Co-signer maintenance:

\[<img alt="AWS" />

## AWS Nitro

AWS Nitro Co-signer maintenance]\(/reference/api-cosigner-maintenance-aws-nitro)
\[<img alt="GCP" />

## GCP Confidential Space

Google Cloud Confidential Space Co-signer maintenance]\(/reference/api-cosigner-maintenance-gcp-confspace)
\[<img alt="SGX" />

## Intel SGX

SGX-based Co-signer maintenance on Azure, On-Premise, IBM Cloud, or Alibaba Cloud]\(/reference/api-cosigner-maintenance-sgx)


# AWS Nitro API Co-signer Maintenance
Source: https://developers.fireblocks.com/reference/api-cosigner-maintenance-aws-nitro



> **Note:** You must have root privileges on the Co-signer machine to perform maintenance operations. Ensure you are logged in as a root user or use `sudo` to execute the commands.

## View the logs

You can export the logs to a file in the local directory, tagged with the current date and time, by running the following command:

```bash theme={"system"}
./fireblocks/cosigner logs
```

Append a number to the command to retrieve the specified most recent amount of lines.

The Co-signer's logs are saved on the EC2 instance in the following file location: `/var/log/customer_cosigner.log`

The log policy is as follows:

```xml theme={"system"}
 <appender name="log_file" class="org.apache.log4j.RollingFileAppender">
   <rollingPolicy class="org.apache.log4j.rolling.TimeBasedRollingPolicy">
     <param name="FileNamePattern"
     value="log/customer_cosigner-%d{dd-MM-yyyy}.log"/>
     <param name="activeFileName" value="log/customer_cosigner.log"/>
   `</rollingPolicy>`
   <param name="File" value="log/customer_cosigner.log"/>
   <param name="Fppend" value="true"/>
   <param name="MaxFileSize" value="4MB"/>
   <param name="MaxBackupIndex" value="2"/>
   <layout class="org.apache.log4j.PatternLayout">
   <param name="ConversionPattern" value="%X{proc}:%X{tid} %p
   %d{dd/MM/yyyy HH:mm:ss,SSS} %l %C::%M- %m Context=%X{context}%n" />
   `</layout>`
 `</appender>`
```

***

## Observe the status

You can observe the Co-signer's status by running the following command from the EC2 instance:

```bash theme={"system"}
./fireblocks/cosigner get-status
```

It should return an output similar to the following:

```json theme={"system"}
[root@ip-x-x-x-x ~]# ./fireblocks/cosigner get-status
 ========= Cosigner Status =========
 Enclave Name: cosigner
 Enclave ID: i-0b11aeabc7d3bee3d-enc190641e6f0ce80a
 Process ID: 377331
 Enclave State: RUNNING
 Service State: ACTIVE
 ===================================
 Latest Service Messages:------------------------
 Jun 29 13:10:41 ip-x-x-x-x.us-east-2.compute.internal start_service.sh[377329]:
 Jun 29 13:10:41 ip-x-x-x-x.us-east-2.compute.internal start_service.sh[377329]:
 1,
 3
 Jun 29 13:10:41 ip-x-x-x-x.us-east-2.compute.internal start_service.sh[377329]: ],
 Jun 29 13:10:41 ip-x-x-x-x.us-east-2.compute.internal start_service.sh[377329]:
 "MemoryMiB": 4096
 Jun 29 13:10:41 ip-x-x-x-x.us-east-2.compute.internal start_service.sh[377329]: }
 ===================================
```

If you get anything other than `ACTIVE` in the "Service State" field, there’s a problem. Contact Fireblocks support and **attach the Co-signer’s logs so we can investigate**.

***

## List the paired API users

You can list all API users paired with the Co-signer across the connected workspaces by running the following command:

```bash theme={"system"}
./fireblocks/cosigner list-users
```

The output will display a list of all API users paired with your Co-Signer, including the workspace name they are connected to, the API user's ID (its API key), and the associated Callback Handler server URL (if applicable).

***

## Retrieve the public key

You can retrieve the Co-signer's public key, used by your optional Callback Handler server to authenticate requests from the Co-signer, by running the following command:

```bash theme={"system"}
./fireblocks/cosigner print-public-key
```

***

## Stop the Co-signer

You can stop the Co-signer by running the command:

```bash theme={"system"}
./fireblocks/cosigner stop
```

***

## Start the Co-Signer

You can Start the Co-signer by running the command:

```bash theme={"system"}
./fireblocks/cosigner start
```

***

## Restart the Co-Signer

You can restart the Co-signer by running the command:

```bash theme={"system"}
./fireblocks/cosigner restart
```

***

## Update the Co-signer

Retrieve the URL of the AWS Nitro installation package from the Console and use the `wget` command to download the package directly to the EC2 machine. Paste the appropriate URL into the following command:

```bash theme={"system"}
wget -O nitro-cosigner.tar.gz "URL"
```

> **Note:** If you have any issues with finding the installation package URL, please contact [Fireblocks Support](https://support.fireblocks.io/hc/en-us/requests/new?ticket_form_id=360003372200\&tf_360023089139=global_settings\&tf_360023089159=get_api_co-signer_installation_script).

Unpack the installation package by running the following command:

```bash theme={"system"}
tar -xzf nitro-cosigner.tar.gz
```

Now stop the Co-signer run the following commands to stop the Co-signer service and update it by forcing a new installation, overwriting the existing one:

```bash theme={"system"}
systemctl stop cosigner
./install.sh --force
```

The script will prompt for the following parameters:

* Pairing token
* S3 bucket
* ARN of the CMK

Use the same settings that were used to install the existing running version. These settings can be found in the file `/opt/fireblocks/env.txt`, where they are labeled as follows:

* PAIRING\_TOKEN
* BUCKET\_NAME
* KEY\_ARN

It will take about a minute to reinstall, and then the Co-signer will load using the new version.

***

## Migrate to a new machine

> **Note:** Since the logs are saved to the EC2 instance, you might want to save them before terminating the machine.

Throughout the migration process, refer to the [AWS Nitro Co-signer installation guide](/reference/install-api-cosigner-aws), as some operations are identical.

Follow these steps to migrate the Co-signer to a new EC2 machine:

1. Set up a new EC2 Nitro-capable instance.
2. Download the installation package to the new instance.
3. Create a new API user that will be used to connect to the new Co-signer instance.
4. Stop the running Co-signer operation by executing the command `systemctl stop cosigner` on the existing EC2.
5. Run the installation script and provide the same S3 bucket and CMK values when prompted to enter parameters during the installation.

***

## Configure a proxy server

By default, the Co-signer is configured to communicate directly with Fireblocks SaaS without using a proxy server. Since the Co-signer uses certificate pinning for secure communication with Fireblocks SaaS, **only a transparent proxy can be used** between the Co-signer and Fireblocks SaaS.

To configure a proxy server, add the key value `HTTPS_PROXY="URL"` as an environment variable to the following file:

`/opt/fireblocks/env.txt`

```bash theme={"system"}
 HTTPS_PROXY="URL" # Replace URL with your transparent proxy server
```

Changing the proxy server settings requires restarting the Co-signer. Run this command to restart it:

```bash theme={"system"}
systemctl restart cosigner
```

***

## Configure the communication protocol

By default, the Co-signer is configured to use WebSocket to communicate with Fireblocks SaaS. You can switch to HTTPS Long Polling by turning WebSocket off.

To turn WebSocket off, add the key value `WEBSOCKET=0` as an environment variable to the following file:

`/opt/fireblocks/env.txt`

```bash theme={"system"}
 WEBSOCKET=1 # Use WebSocket
 WEBSOCKET=0 # Use HTTPS Long Polling
```

Switching between the communication modes requires restarting the Co-signer. Run this command to restart it:

```bash theme={"system"}
systemctl restart cosigner
```


# GCP Confidential Space API Co-signer Maintenance
Source: https://developers.fireblocks.com/reference/api-cosigner-maintenance-gcp-confspace



> **Note:** You must have the necessary privileges to your Google Cloud account to perform maintenance operations.

## View the logs

To view the Co-Signer's logs, go to the [GCP's VM instances page](https://console.cloud.google.com/compute/instances) and validate that you see the right project (for example, "GCP-Customer-Cosigner-Dev"). After that, click on the relevant VM name and then press "logging" (which appears under "Logs"). This will open a new window with the customer Co-signer's logs.

## Observe the status

To check the Co-signer's health, run the following command:

```bash theme={"system"}
gcloud compute instances describe <vm-name> --zone=<vm-zone> | grep status
```

Search for the `status` field of the VM in the output and confirm it is set to `RUNNING`. However, this does not guarantee the health of the Co-signer. To verify its functionality, monitor the transaction activity passing through it.

Also, use the [Co-signers management tab](https://support.fireblocks.io/hc/en-us/articles/14492251068060-The-Co-signer-management-tab) to observe the online / offline status.

## List the paired API users

Use the [Co-signers management tab](https://support.fireblocks.io/hc/en-us/articles/17923671680540-The-Co-signer-management-tab) to observe the paired API users.

## Retrieve the public key

You can view the Co-signer's logs in Google Cloud's console to find the public key used by the Callback Handler's server for JWT-encoded signed message authentication. Search for `public key` in the logs, as shown in the example below.

<img alt="" />

## Stop the Co-signer

You can stop the Co-signer by running:

```bash theme={"system"}
gcloud compute instances stop <vm-name> --zone=<vm-zone>
```

> **Note**: This operation will not delete the VM.

You can also stop the VM from the GCP console.

## Restart the Co-Signer

In case the Co-signer's VM is down, given the Co-signer was already created, you can restart the Co-signer by running:

```bash theme={"system"}
gcloud compute instances start <vm-name> --zone=<vm-zone>
```

When you restart the Co-signer after installing it, it will use the same configuration (metadata), so you don't need to enter all the parameters again.

## Retrieve the running version

Use Google Cloud's console to check the Co-signer's running image version by observing the `tee-image-reference` field in `Custom metadata` in the `Details` section.

Alternatively, you can search for `Initializing CustomerCosignerGCPConfidentialSpace, commit sha` within the instance logs.

## **Update proxy settings**

You can update or remove proxy settings on a running Co-signer without performing a full upgrade. The `--update-proxy` flag on the install/upgrade script handles this. It updates the VM's instance metadata in place and resets the VM to apply the change. No new VM is created.

The operation causes approximately 2 minutes of downtime while the VM restarts.

### **Run the update**

```bash theme={"system"}
./client_install_upgrade_api_cosigner_script.sh --update-proxy cloud-resources-<timestamp>.yaml
```

Replace `cloud-resources-<timestamp>.yaml` with the resources file generated during your installation.

#### **What the script does**

1. Loads your current configuration from the resources YAML file and displays a summary, including whether a proxy is currently configured.
2. Prompts you for the new proxy URL. To remove an existing proxy, press **Enter** without entering a value.
3. If a proxy URL is provided, encrypts it using your Cloud KMS key (credentials are never stored in plaintext), then prompts for `NO_PROXY` patterns. The current `NO_PROXY` value is shown as the default; press **Enter** to keep it.
4. Displays a summary of the changes and asks for confirmation before touching the running VM.
5. Updates the VM's instance metadata with the new configuration and resets the VM.
6. Writes the updated proxy settings to your resources YAML file.

#### **Proxy URL format**

```http theme={"system"}
http://proxy.example.com:8080
```

To authenticate to the proxy, include credentials in the URL:

```http theme={"system"}
http://username:password@proxy.example.com:8080
```

#### **Effect on WebSocket vs. long-polling**

When a proxy is configured, the Co-signer uses long-polling (REST) for communication with Fireblocks. WebSocket connections cannot reliably traverse proxies. When you remove a proxy, the Co-signer reverts to the WebSocket setting that was active before the proxy was added.

#### **Verify the update**

Once the VM is back online (approximately 2 minutes after the reset), proxy activity appears in Cloud Logging. To stream recent logs:

```bash theme={"system"}
gcloud logging read 'resource.type=gce_instance AND labels.instance_name=YOUR_VM_NAME' \
  --limit=50 \
  --order=desc
```

Replace `YOUR_VM_NAME` with your Co-signer VM name (visible in the summary the script prints before confirmation).

## Update the Co-signer

You can update the Co-signer by running the following script:

```bash theme={"system"}
client_stop_and_update_gcp_api_cosigner_script.sh
```

This script performs the following:

* Stops the existing VM running the current Co-signer.
* Updates the OIDC workload identity pool provider's attestation verification with the new image's SHA of the new version.
* Create a new VM that runs the new image.

The new Co-Signer VM utilizes the same database, keys, and cloud resources as the previous one.

> **Important notes:**
>
> * **Delete the old VM once the new one is fully operational.** Because the policy is configured to protect the VM from deletion, use the GCP console to disable the deletion protection under `VM > Edit > UNtag "Enable deletion protection"` and save the new settings before deleting the VM.
> * If a proxy was configured when the Co-signer was installed, the upgrade carries that configuration forward automatically. No additional input is required. To change or remove proxy settings on a running Co-signer, use the `--update-proxy` flag instead of performing an upgrade. See the [<u>Update proxy settings</u>](https://fireblocks.atlassian.net/browse/DOC-3350# "#") section.
> * Please make sure to refer this [doc](/reference/api-cosigner-versions-gcp) to get the Image SHA number.

## Migrate to a new machine

Stop the current Co-signer VM and set up a new one using the same resources besides the VM.

## Configure the communication protocol

WebSocket is the default protocol the Co-signer uses to communicate with the Fireblocks SaaS. You can switch to HTTP Long Polling by configuring the `client_install_gcp_api_cosigner_script.sh` script.

To configure the Co-signer to use HTTP long polling, you can create a new VM that will use the same resources, but ensure you remove the `\"--websocket\"` parameter from the `create_vm_cmd` line so that it will look like this:

```bash theme={"system"}
--metadata
^~^tee-image-reference=$image_ref~tee-container-log-redirect=true~tee-cmd='[\"--initial-config\", \"$initial_config\", \"$bucket\", \"$key_path\"]'"
```

Instead of:

```bash theme={"system"}
--metadata
^~^tee-image-reference=$image_ref~tee-container-log-redirect=true~tee-cmd='[\"--initial-config\", \"$initial_config\", \"$bucket\", \"$key_path\",\"--websocket\"]'"
```

If you don't want to create a new VM, you can edit the VM's metadata and instruct it to restart in HTTP Long Polling.

* Stop the Co-signer0 VM
* From the GCP console, locate `VM > Edit > Metadata`
* Remove "`--websocket`" from the "`Value 1`" matching Key 1 which is "`tee-cmd`"
* Click Save and restart the VM to apply the changes to the Co-signer


# SGX API Co-signer Maintenance
Source: https://developers.fireblocks.com/reference/api-cosigner-maintenance-sgx



> **Note:** You must have root privileges on the Co-signer machine to perform maintenance operations. Ensure you are logged in as a root user or use `sudo` to execute the commands.

## View the logs

You can export the logs to a file in the local directory, tagged with the current date and time, by running the following command:

```bash theme={"system"}
./cosigner logs
```

Append a number to the command to retrieve the specified most recent amount of lines.

By default, the Co-signer uses the Docker logging container. However, for better monitoring, the logs can be streamed to an external log delivery service, such as ELK, Splunk, or Datadog.

The SGX Co-signer generates two different types of logs for troubleshooting and auditing:

* `run.log` is an automatically generated log containing all of your Co-signer setup and configuration history.
* `customer_cosigner.log` contains workspace operation data, such as the workspace's transaction approving and signing history and new connection approvals. These log files are separated into 10 files limited to 4.1MB each. They are automatically overwritten in chronological order.

Your API Co-signer logs are structured using the following Regular Expression (RegEx):

```bash theme={"system"}
${AppName}:${Line} ${LogLevel} ${dd/MM/yyyy} ${HH:mm:ss,fff} ${ClassName} ::${MethodName} - ${LogMessage}
```

These logs are collected by the Docker container’s `STDOUT` stream and written into a log file on the container’s host machine at the location specified below. These log files are rotated with a max file size of 4MB for each log file.

```text theme={"system"}
/databases/cosigner/log/customer_cosigner.log
/databases/cosigner/log/customer_cosigner.log.1
/databases/cosigner/log/customer_cosigner.log.2
...
```

> **Note:** The Co-signer is Docker-based and uses the Docker JSON file driver for logging. By default, the driver uses a standard logging output but can be configured to support other logging mechanisms. Refer to the official Docker documentation for more detailed information.

***

## Verify SGX is enabled on the machine

After completing your server creation or installation, verify that SGX is enabled on the server. The Fireblocks API Co-Signers can only run on SGX-enabled servers with the latest patches, and verifying your configuration helps ensure you do not run into any potential issues later on.

1. Run the following commands on the server:

```bash theme={"system"}
sudo apt update
sudo apt upgrade
sudo apt install cpuid
cpuid -1 | grep -i sgx
```

2. Verify the following:
   1. SGX: Software Guard Extensions supported is `true`.
   2. SGX\_LC: SGX launch config supported is `true`.

<img alt="" />

> Note: Azure Standard\_DC\*\_v2 instances do not support SGX2, but it is not necessary to run the signer.

***

## List the paired API users

You can list all API users paired with the Co-signer across the connected workspaces by running the following command:

```bash theme={"system"}
./cosigner list-users
```

The output will display a list of all API users paired with your Co-Signer, including the workspace name they are connected to, the API user's ID (its API key), and the associated Callback Handler server URL (if applicable).

***

## Retrieve the public key

You can retrieve the Co-signer's public key, used by your optional Callback Handler server to authenticate requests from the Co-signer, by running the following command:

```bash theme={"system"}
./cosigner print-public-key
```

***

## Stop the Co-signer

You can stop the Co-signer by running the following command:

```bash theme={"system"}
./cosigner stop
```

***

## Start the Co-signer

You can Start the Co-signer by running the following command:

```bash theme={"system"}
./cosigner start
```

***

## Restart the Co-Signer

You can restart the Co-signer by running the following command:

```bash theme={"system"}
./cosigner restart
```

***

## Retrieve the running image version

You can retrieve your running Co-Signer version by running the following command:

```bash theme={"system"}
docker inspect cosigner | jq -r '.[0].Config.Image' + " " + '.[0].Image'
```

***

## Retrieve the script version

You can retrieve your current Co-Signer script version by running the following command:

```bash theme={"system"}
head cosigner -n 3 | grep -i ver
```

***

## Update the Co-signer

Retrieve the URL of the SGX installation script from the Console and use the `curl` command to download the script to the path where the existing Co-Signer script is present. Paste the appropriate URL into the following command:

```bash theme={"system"}
curl -o cosigner "URL Download Link"
```

> **Note:** If you have any issues with finding the installation script URL, please contact [Fireblocks Support](https://support.fireblocks.io/hc/en-us/requests/new?ticket_form_id=360003372200\&tf_360023089139=global_settings\&tf_360023089159=get_api_co-signer_installation_script).

After downloading the installation script, navigate to the directory containing the script and modify the script's permissions to make it executable:

```bash theme={"system"}
chmod +x cosigner
```

Stop the Co-signer container by running the following command:

```bash theme={"system"}
./cosigner stop
```

Run `docker ps -a` and check the output. There should be no Co-signer container running.

Backup the Co-signer's database by running the following command:

```bash theme={"system"}
mv /databases/cosigner/enclave/enclave.signed.so /databases/cosigner/enclave/enclave.signed.so_old
```

Remove the current revision file:

```bash theme={"system"}
sudo rm -f .revision
```

You can now update the Co-signer to the latest version by running the following command:

```bash theme={"system"}
./cosigner start
```

You can update to a specific image version by replacing the `<image_version>` :

```bash theme={"system"}
./cosigner start <image_version>
```

Run `docker ps -a` and check the output. You should see the Co-signer container running.

If the update process did not succeed, try re-installing the Co-signer using the same version, but first remove the current version of the Co-Signer by running the following commands:

```bash theme={"system"}
sudo rm -rf /databases
sudo rm -f .local_config .revision
```

and then run:

```bash theme={"system"}
./cosigner setup
```

If that still doesn't work, refer to [API Co-signer Troubleshooting](/reference/api-cosigner-troubleshooting).

***

## Migrate to a new machine

Begin by setting up a new SGX-capable machine in your cloud or on-premises environment.

Migrating the SGX Co-Signer to a new machine is most effectively performed using backup data from the existing machine. This approach minimizes downtime and reduces the risk of interruptions to your workspace operations.

The following files and folders are generated automatically during the SGX Co-signer setup and are essential for backup and recovery purposes:

1. `/databases/cosigner/db`: The Co-signer DB folder stores the `secrets.db` file, the Co-Signer's secrets database. This file is encrypted with a key generated in a secure SGX enclave.
2. `/databases/cosigner/backup`: The backup folder maintained by the Co-Signer stores the backup upon any change to the database. The files are formatted using the following timestamp: `%Y%m%d%H%M%S.db` (e.g. `20220710184350.db`) based on the backup's date.
3. `/databases/cosigner/enclave/ra_loader_enclave.signed.so` - The enclave loader.

Backup the files `secrets.db` and `ra_loader_enclave.signed.so` and copy them to the same folder locations on the new server:

* `/databases/cosigner/db/secrets.db`
* `/databases/cosigner/enclave/ra_loader_enclave.signed.so`

After the above files have been copied to the new server, run `./cosigner start`.

If you don't have backups of either `secrets.db` or `ra_loader_enclave.signed.so` files, unpair (re-enroll) the API users that are associated with the Co-signer and set up a new Co-signer on the new machine. Refer to the [API Co-signer Installation Flow and Deployment Options](/reference/api-cosigner-installation-flow) article to find the specific SGX Co-signer environment you have.


# API Co-signer Management
Source: https://developers.fireblocks.com/reference/api-cosigner-management



In addition to manual transaction signing and Workspace configuration approvals using a mobile device, you can automate signing and approvals with an API Co-signer. This is ideal for workspaces that handle high transaction volumes or frequent activity.

A Co-signer is connected to a workspace by pairing it with an [API user](https://support.fireblocks.io/hc/en-us/articles/4407823826194-Adding-new-API-Users). Once connected, assuming the API user has a [Signer](https://support.fireblocks.io/hc/en-us/articles/360012832959-User-roles#h_01H9P4D2W1436XZYXESPTQE2J7) or [Admin](https://support.fireblocks.io/hc/en-us/articles/360012832959-User-roles#h_01H9P4D2W138W3F36TX45S8WFX) role, you will be asked to approve MPC key shares for that API user.

To activate automatic signing through the Co-signer, configure the [Policy](https://support.fireblocks.io/hc/en-us/articles/7354983580316-About-the-TAP) to [designate the API user](https://support.fireblocks.io/hc/en-us/articles/7365877039004-Rule-parameters#h_01HGBN9QQ0T42NR8XT4Y96V7YH) paired with the Co-signer as the signer. When a transaction you initiate meets the criteria defined in the policy, it will be automatically signed by the Co-signer associated with the configured API user.

At that point, you can add multiple API users to the Co-signer and configure the Callback Handler for each API user paired with it.

Use the articles below for detailed guides and information.

***

## CO-SIGNER INSTALLATION

[Co-signer installation flow](/reference/api-cosigner-installation-flow)

[Install AWS Nitro](/reference/install-api-cosigner-aws)
[Install GCP Confidential Space](/reference/install-api-cosigner-gcp)
[Install SGX on Microsoft Azure](/reference/install-api-cosigner-azure)
[Install SGX via Azure Marketplace](/reference/install-api-cosigner-azure-marketplace)
[Install SGX on IBM Cloud](/reference/install-api-cosigner-ibm)
[Install SGX on Alibaba Cloud](/reference/install-api-cosigner-alibaba)

[Install SGX On-Premise](/reference/install-api-cosigner-onprem)

## SETUP AND TESTING

[Using the Communal Test Co-signer](/reference/use-communal-cosigner)

[Establishing Secure Communication Between the Co-signer and the Callback Handler](/reference/cosigner-callbackhandler-secure-communication-authentication)
[Callback Handler Response Object](/reference/response-object)
[Approve Transactions](/reference/approve-transactions)
[Approve Configuration Changes](/reference/approve-configuration-changes)

[Callback Handler Code Example](/reference/basic-code-example)
[Use the Plugin-based Callback Handler](/reference/plugin-based-callback-handler)
[Validate ETH Raw Transactions](/reference/validate-eth-raw-transactions)

MAINTENANCE

[Overview](/reference/api-cosigner-maintenance)
[SGX Co-signer Maintenance](/reference/api-cosigner-maintenance-sgx)
[AWS Co-signer Maintenance](/reference/api-cosigner-maintenance-aws-nitro)
[GCP Co-signer Maintenance](/reference/api-cosigner-maintenance-gcp-confspace)

## CO-SIGNER OPERATION

[Using APIs, Console and Command-Line Interface to Operate the Co-signer](/reference/api-cosigner-operate)

## VERSIONS

[Overview](/reference/api-cosigner-versions)
[SGX Co-signer Version History](/reference/api-cosigner-versions-sgx)
[AWS Co-signer Version History](/reference/api-cosigner-versions-aws)
[GCP Co-signer Version History](/reference/api-cosigner-versions-gcp)

## SUPPORT

[Troubleshooting](/reference/api-cosigner-troubleshooting)


# Operating the API Co-signer
Source: https://developers.fireblocks.com/reference/api-cosigner-operate



Once the Co-signer is connected to your workspace, you can manage it through the Console or APIs. This includes sending commands such as pairing additional API users or configuring the Callback Handler for a paired API user.

For all types of SGX Co-signers and the AWS Nitro Co-signer, all operations can also be performed via the command-line interface (CLI) on the Co-signer's host machine.

However, due to the enclave architecture of the Google Cloud Confidential Space Co-signer, all operations on this type of Co-signer must be performed exclusively through the Console or APIs.

## Co-signer API operations

Refer to [Fireblocks Cosigners API](/reference/getcosigners) for the list of Co-signer operations you can do using Fireblocks APIs.

The operations include:

* Get all the Co-signers that are connected to the workspace
* Get the details of a specific Co-signer that is connected to the workspace
* Rename the Co-signer
* Get a list of all the API users that are paired with the Co-signer
* Get the details of a specific API user that is paired with the Co-signer
* Add a Co-signer to the workspace
* ❗ Pair an additional API user with a Co-signer
* Unpair an API user from a Co-signer
* ❗Update the callback handler of a paired API user

> **The operations that are marked with ❗ will only work with Co-signers with the following versions:**
>
> * SGX Co-signer: version 3.7.1 or later
> * AWS Nitro Co-signer: version 2.0.5 or later
> * Google Cloud Confidential Space Co-signer: version 0.9.4 or later

***

## Co-signer Console operations

For a detailed description of the Co-signer operations available through the Console, visit the [Co-signer Management tab](https://support.fireblocks.io/hc/en-us/articles/17923671680540-The-Co-signers-management-tab) in the Help Center.

***

## Co-signer command-line operations

This section covers operations related to Co-signer management, including adding and configuring API users. For maintenance operations such as viewing logs, updating the Co-signer, and more, refer to the [API Co-signer maintenance](/reference/api-cosigner-maintenance) article.

### List the paired API users

You can list all API users paired with the Co-signer across the connected workspaces by running the following command:

```bash theme={"system"}
./cosigner list-users
```

The output will display a list of all API users paired with your Co-Signer, including the workspace name they are connected to, the API user's ID (its API key), and the associated Callback Handler server URL (if applicable).

### Add API user

You can pair an additional API user with your Co-Signer instance by running the following command:

```bash theme={"system"}
./cosigner add-user
```

> **Note:** This command works only after the first API user has been paired during the Co-Signer installation.

You will be prompted to provide the API user's pairing token, which can be retrieved from the Console. If you opt to connect this API user with a Callback Handler, you must also provide the Callback Handler's URL and its public key or certificate. For more information, refer to the **Setup API Co-Signer Callback Handler** article.

### Setup and update Callback Handler for API user

You can setup the Callback Handler for an API user paired with the Co-signer, provided it does not already have a configured Callback Handler, by running the following command:

```bash theme={"system"}
./cosigner callback-update [API user ID]
```

If only one API user is paired with your Co-Signer, you don't have to specify the `API user ID` , which is its API key.

If you want to configure the URL of the Callback Handler of an API user that is paired with the Co-signer, run the following command:

```bash theme={"system"}
./cosigner callback-update [API user ID]
```

You will be prompted to enter the URL and public key or certificate parameters, but **only the URL you provide will be updated**. To change the Callback Handler's public key or the certificate through the CLI, you must unpair (re-enroll) the API user and pair it again with the Co-Signer using the `add-user` CLI command.

Note that if only one API user is paired with your Co-Signer, unpairing (re-enrolling) the API user results in a full Co-signer setup to initialize the API user and pair it with the new Callback Handler.

Alternatively, instead of unpairing the API user and pairing it again, you can configure the Callback Handler's public key or certificate of an API user that is paired with the Co-signer using APIs or through the Console.

> Note: To configure the Callback Handler's public key or certificate using APIs or through the Console, your Co-signer should meet the requirements for Co-signer platform commands, as described in the [Co-signer API operations section](/reference/api-cosigner-operate#co-signer-api-operations) within this article,


# API Co-signer Troubleshooting
Source: https://developers.fireblocks.com/reference/api-cosigner-troubleshooting



## Contacting Fireblocks API Co-signer Support

If you have a question or need assistance, [contact Fireblocks Support](https://support.fireblocks.io/hc/en-us/requests/new) and include the following information in your request:

* Your workspace name
* The first four characters of the API key associated with the API user used to connect the Co-signer to the workspace.
* Indicate whether the API user is paired with an active Co-signer or is in the process of completing the initial setup.

Copy the logs from the API Co-signer and include them in the support ticket. Refer to [the Co-signer maintenance documentation](/reference/api-cosigner-maintenance) to locate the logs for your specific type of Co-signer.

***

## Error codes

| Error Code      | Description  | Possible Cause                                          |
| --------------- | ------------ | ------------------------------------------------------- |
| 401             | Unauthorized | User account-related issue.                             |
| 403             | Forbidden    | Your firewall, proxy, or WAF is blocking communication. |
| 500 / 502 / 504 | Server error | Temporary server-side issue.                            |

***

## Error messages

### Error message "MPC setup not completed"

This error message indicates that the workspace Owner must still approve the API user's MPC key shares.

#### Resolution

Check the Owner's device for pending MPC key share approval notifications.

* If the notification is less than 12 hours old, the Owner can still approve the key shares, and the API user will be ready to sign transactions. Once the owner approves your new MPC keys on their Fireblocks mobile app. You have 6 hours to complete the MPC registration.
* If the Owner is unable to approve the request due to [Error 52](https://support.fireblocks.io/hc/en-us/articles/9108149928092-Error-52), deny the pending request and [submit a request to Fireblocks Support](https://support.fireblocks.io/hc/en-us/requests/new).
* If there is no notification or another error, unpair the API user and then pair it with the Co-signer again to resend the approval request.

### API Co-signer does not sign transactions

The API Co-signer may not sign transactions if its transaction queue is full. In this case, the API logs will include an error stating that the "**queue is full**". This means the API Co-signer's internal queue is overloaded and must be restarted. This is separate from your workspace transaction queue.

#### Resolution

To resolve a full Co-signer queue:

1. Cancel all the pending transactions.
2. Make sure there are no pending requests on the Co-signer.
3. Restart the Co-signer.
4. Wait a few minutes to confirm that the queue is empty.
5. Submit a new transaction.
6. Confirm the transaction is signed by the Co-signer as expected.

> **Confirm your Co-signer meets minimum hardware requirements**
>
> The root cause of the full queue may be server CPU capabilities. Confirm that your Co-signer server meets the recommended hardware requirements.

### API Co-signer does not sign raw-signing transactions

When this issue occurs, the API Co-Signer signs some raw signing transactions but not others. This usually results from [signature caching for off-chain messages](https://support.fireblocks.io/hc/en-us/articles/4413379762450).

> **Signature caching enabled by default**
>
> Signature caching for raw signing is enabled by default. [Submit a request to Fireblocks Support](https://support.fireblocks.io/hc/en-us/requests/new?ticket_form_id=5129187878556\&tf_5465594782876=api_co-signer_setup_and_configuration__what_are_you_trying_to_do___other) if you want this feature disabled.

### IO Exception: status code = 28

This error is a generic Linux filesystem error. It indicates that the disk is full, and your infrastructure and DevOps teams need to add additional disk space.

### SGX Co-signer: failed attestation to Fireblocks, try to perform microcode update

This error indicates that the OS or BIOS microcode version is outdated and can’t perform the SGX attestation with the Fireblocks server.

#### Resolution

Make sure the threads/processor, and hyperthreading (HT) are disabled and that SGX, DCAP, and FLC are enabled.

To verify whether HT is enabled, run the following command:

```bash theme={"system"}
hostname# lscpu | grep Thread
```

This command should output:

```text theme={"system"}
Thread(s) per core: 1
```

To verify the microcode version, run the following command:

```bash theme={"system"}
# cat /proc/cpuinfo | grep -E "model name|microcode"

# dmesg | grep microcode

# dpkg -l | grep intel-microcode
```

### SGX Co-signer: migration options when an Azure region outage occurs

When Azure region issues occur where an API Co-signer instance is running, it can have the following effects:

* Connectivity issues
* An instance crashing, becoming unavailable, or being damaged and irrecoverable
* Withdrawals are not being processed and are getting stuck in the `PENDING_SIGNATURE` or `QUEUED` statuses due to the API Co-signer being unable to sign transactions.

> **Check your Azure region status**
>
> To check your Azure region's status, visit the [Azure status page](https://status.azure.com/en-us/status).

#### Workarounds

During an Azure region outage, you can use one of the following workarounds to ensure your financial operations continue uninterrupted. After the outage is resolved, you can return to your normal setup and resume operations.

#### Step 1: Install a new API Co-signer instance in another region

After doing that, you can unpair your existing API user and pair it with your new Co-signer.

#### Step 2: Define a user's mobile device as a designated signer on your Policy

You can define a user's mobile device as the designated signer for Policy rules that previously required your Co-signer to sign. However, this solution may not be ideal for some customers since it requires you to manually cancel all already submitted transactions, resubmit them, and then have them signed manually.

If you decide to change your Policy rules, [contact Fireblocks Support](https://support.fireblocks.io/hc/en-us/articles/4808588554396).

#### Step 3: Migrate an existing Co-signer instance to an unaffected region

Follow the [official guide from Microsoft](https://learn.microsoft.com/en-us/azure/site-recovery/azure-to-azure-move-overview). If you require any additional clarification, contact Azure for technical assistance. Note that this operation might take a considerable amount of time.

#### Checking the instance's health post-migration

To verify the Co-signer is healthy after the maintenance reboot, run `docker ps -a` and check the output. You should be able to confirm that the `cosigner-init` container is not running and the `cosigner` container is not restarting.

Also, cancel any transactions that are stuck in the `PENDING_SIGNATURE` status and verify that the status of your `QUEUED` transactions have changed to `PENDING_SIGNATURE`, meaning that the Co-signer can process them.

### SGX Co-signer: setup fails with error "Failed to download loader enclave"

This error typically occurs during the initial setup process of an API Co-signer.

During the initial setup process, the First user on this machine checkbox must be selected when the first API user to be added to the Co-signer machine is created. If the API user is created and the checkbox is not selected, the error below appears in the `date_time_run.log` file (located in the same directory in which the API Co-signer script runs):

```text theme={"system"}
customer_cosigner:24 ERROR 31/12/2000 20:03:21,462
untrusted/ra_loader.cpp(457)fireblocks::common::ra_loader::download_loader_with_access_token - Failed to download loader enclave file, http status 401

customer_cosigner:24 FATAL 31/12/2000 20:03:21,463
main.cpp(490) ::init - Failed to download ra loader
```

#### Resolution

There are two resolutions for this issue.

#### Resolution 1: Start over with a new API user

1. Delete the API user that you attempted to pair with the Co-signer.
2. Create another API user. Make sure to select the **first user in this machine** checkbox.
3. Run the following command on the Co-signer instance:

```bash theme={"system"}
./cosigner stop
docker kill $(docker ps -q)
docker rm $(docker ps -aq)
docker rmi $(docker images -q)
```

4. Run the following command to begin the setup process again:

```bash theme={"system"}
./cosigner setup
```

#### Resolution 2: Contact Fireblocks Support

If you cannot create an API user or require the setup to be completed with the existing API user, contact Fireblocks Support.

### SGX Co-signer: syntax error near unexpected token: “newline” or “ `<?xmlversion="1.0" encoding="UTF-8"?>` ”

This error indicates that the link for downloading the Co-signer script has expired. To confirm, run the following command:

```bash theme={"system"}
head cosigner
```

If the link has expired, you should get the following response:

```xml theme={"system"}
`<?xml version="1.0" encoding="UTF-8"?>`
<Error><Code>SignatureDoesNotMatch`</Code>`
<Message>The request signature we calculated does not match the signature you provided. Check your key and signing method.`</Message>`
<AWSAccessKeyId>AKIA5QO5IU7PYPUJ7AU6`</AWSAccessKeyId>`
<StringToSign>AWS4-HMAC-SHA256
```

#### Resolution

To resolve this issue, download a new SGX Co-signer install script from the Console and run it again.

### SGX Co-signer: setup fails with the error "gathering device information while adding custom device, "/dev/sgx\_enclave", or unable to find file or directory"

This error indicates that the target instance doesn't support SGX or its SGX is not enabled, or that other machine specs don't match or are missing. For example, the correct size should be `DC4s_V3`.

#### Resolution

* You can find a list of SGX-supported instance types [here](https://docs.microsoft.com/en-us/azure/confidential-computing/quick-create-portal).
* For product availability in different regions, see [here](https://azure.microsoft.com/en-us/global-infrastructure/services/?products=virtual-machines\&regions=all).

### SGX Co-signer: invalid reference format

This error indicates that you upgraded an existing Azure instance with an older version installed, and the older version files are stored in your temp files (.local\_config / .revision).

#### Resolution

To resolve this issue:

1. Make sure to keep the docker-compose files and the script in the correct directory

   (`.local_config` / `.revision`) before performing the API Co-signer setup.

2. Remove all files in the directory except the docker-compose files and the script.

3. Run the following command:

```bash theme={"system"}
./cosigner setup
```

4. When you are prompted to pair the token, exit that installation but continue with the docker installation.

### SGX Co-singer: curl command to [https://mobileapi.fireblocks.io/broadcast\\\_mpc\\\_m](https://mobileapi.fireblocks.io/broadcast\\_mpc\\_m) failed with error "Couldn't resolve host 'mobile-api.fireblocks.io'"

> **Warning**
>
> This error is not common, so we recommend contacting Fireblocks Support before you take action.

This error indicates that the request failed to send a message for the signed transaction and will remain in the **Pending** status until it is canceled. This is typically due to a network issue. However, in one case, we found that the DNS prevented the message from reaching the signing phase.

#### Resolution

To resolve this issue:

1. Go to the `vi/etc/systemd/resolved.conf` directory.
2. Under the Resolve heading, change the DNS value to **8.8.8.8 8.8.4.4**.
3. Run the following command:

```bash theme={"system"}
systemctl restart systemd-resolved.service
```


# API Co-signers Versions
Source: https://developers.fireblocks.com/reference/api-cosigner-versions



Below are the version details for each of the Co-signer types:

* [SGX Co-signer version history](/reference/api-cosigner-versions-sgx)
* [AWS Nitro Co-signer version history](/reference/api-cosigner-versions-aws)
* [Google Cloud Confidential Space Co-signer version history](/reference/api-cosigner-versions-gcp)


# AWS Nitro API Co-signer Version History
Source: https://developers.fireblocks.com/reference/api-cosigner-versions-aws



Fireblocks updates the API Co-signer software to include stability enhancements and new features. This article details the most recent AWS Nitro Co-signer versions. Always use the latest version listed here for optimal performance.

## Latest version

### **Version 2026.04.27 (April 2026)**

**Version hash:** `1d5b48eeef`

* Performance improvements and bug fixes

***

## Version history

### Version 2026.03.02 (March 2026)

**Version hash:** 95a317d3c7

* Added support for POLICY\_CHANGE approval request type (the customer co-signer can now approve policy changes via Policy Service v2)
* Performance improvements and bug fixes

### Version 2026.01.29 (January 2026)

**Version hash:** 340d9f6057

* Bug fixes and performance improvements

### Version 2025.12.30 (December 2025)

**Version hash:** a294449c1b

* Added support for "Protected Tags" approval requests

### Version 2025.12.11 (December 2025)

**Version hash:** c44604398e

* The callback can now return a “retry” response in an exchange withdraw operation

### Version 2025.11.20 (November 2025)

**Version hash:** 82a5cc0078

* Fixed a bug that may cause the Co-signer not to load correctly after a graceful shutdown

### Version 2025.10.09 (October 2025)

**Version hash:** 4e34888c01

* Fixed bug parsing messages after websocket reconnect
* Fixed bug sending messages on half closed websocket connections

### Version 2025.08.12 (August 2025; US environments only)

**Version hash:** 19c07421dc

* Fixed WebSocket bug causing performance issues

### Version 2025.07.16 (July 2025)

**Version hash:** bb61e507

* Fixed bugs and increased performance
* Better support for web sockets

### Version 2.1.1 (April 2025)

**Version hash:** 7160d7b833

* Bug fixes and performance improvements

### Version 2.0.5 (September 2024)

**Version hash:** d177e696c3

* Decreased signing latency along with general performance increases
* Extended filtering of environment variables
* Improvements to key handling within the enclave
* Bug fixes

### Version 2.0.4 (August 2024)

**Version hash:** 41d1888dc8

* Fixed the issue when setting AWS region using environment variables
* Removed unnecessary testing artifacts

### Version 2.0.2 (August 2024)

* Modified KMS CMK ARN prompt
* Added start, stop and restart commands
* Added echo to show where logs are saved to
* Fixed AWS NTP sync issue
* Fixed Callback Handler public key issue on install
* Removed unnecessary testing artifacts

### Version 2.0.1 (July 2024)

* Added check for force flag and existence of destination before the user is prompted for details
* Added route DNS queries to the DNS server defined on the host EC2 instance

### Version 2.0.0 (June 2024)

* Initial release


# GCP Confidential Space API Co-signer Version History
Source: https://developers.fireblocks.com/reference/api-cosigner-versions-gcp



Fireblocks updates the API Co-signer software to include stability enhancements and new features. This article details the most recent Google Cloud Confidential Space Co-signer versions. Always use the latest version listed here for optimal performance.

***

## Latest version

### **Version 2026.04.27 (April 2026)**

**Version hash:** `1d5b48eeef`

* The cosigner can now connect through a proxy. User/password authentication and no\_proxy values are also supported.
* Performance improvements and bug fixes

***

## Version history

### Version 2026.03.02 (March 2026)

**Version hash:** `95a317d3c7`

* Added support for POLICY\_CHANGE approval request type (the customer co-signer can now approve policy changes via Policy Service v2)
* Performance improvements and bug fixes

### Version 2026.01.29 (January 2026)

**Version hash:** 340d9f6057

* Bug fixes and performance improvements

### Version 2025.12.30 (December 2025)

**Version hash:** a294449c1b

* Added support for "Protected Tags" approval requests

### Version 2025.12.11 (December 2025)

**Version hash:** c44604398e

* The callback can now return a “retry” response in an exchange withdraw operation

### Version 2025.08.12 (August 2025; US environments only)

**Version hash:** 19c07421dc

* Fixed WebSocket bug causing performance issues
* Image digest SHA (US): sha256:61f951f0b8a66e906ab3ef742a3aa6b0312b279190c3e6478feae6d4b002be3f
* Image path (US): us-docker.pkg.dev/fireblocks-customer-cosigner/fireblocks-customer-cosigner-repository/gcp-cosigner:2025.08.12

### Version 2025.07.16 (July 2025)

**Version hash:** bb61e507

* Fixed bugs and increased performance
* Better support for web sockets
* Image digest SHA (US): sha256:19b651f855f697ffc67ba97c33639f5a4c6db717019412df62e3ee5994ea6c44
* Image Path (US): us-docker.pkg.dev/fireblocks-customer-cosigner/fireblocks-customer-cosigner-repository/gcp-cosigner:2025.07.16
* Image details for EU:
  Digest SHA - sha256:4318bf2b9c0eccf8fd2cda2291366a6cf406e426c8a97b3d754a3d9bcc4e1d13 Path - us-docker.pkg.dev/fireblocks-customer-cosigner/fireblocks-customer-cosigner-repository/gcp-cosigner:2025.07.16.eu
* Image details for EU2:
  Digest SHA - sha256:1f11be136216311532d1277d7fe9e4aba3e4394c6f699904f8969aca097c3dc0 Path - us-docker.pkg.dev/fireblocks-customer-cosigner/fireblocks-customer-cosigner-repository/gcp-cosigner:2025.07.16.eu2
* Image details for Sandbox:
  Digest SHA - sha256:5155a2258fba75b7321ca3136aab47f2af0a14dd0cdf29e0132ab06da1ab6086 Path - us-docker.pkg.dev/fireblocks-customer-cosigner/fireblocks-customer-cosigner-repository/gcp-cosigner:2025.07.16.sandbox

### Version 1.1.1 (April 2025)

**Version hash:** 7160d7b833

* Bug fixes and performance improvements

### Version 1.1.0 (March 2025)

**Version hash:** 2584ed02d1

* Image SHA (US): sha256:40893bdf713df66f4cfa857420989b583c0011c84fee0b8f92acd182d37a7f81
* Image Path (US): us-docker.pkg.dev/fireblocks-customer-cosigner/fireblocks-customer-cosigner-repository/gcp-cosigner:1.1.0
* Image SHA (EU): sha256:2e4f02f5c90e92819111fd93822cf557ab1ffd5a8faed919bd3144ce0563e6cc
* Image Path (EU): us-docker.pkg.dev/fireblocks-customer-cosigner/fireblocks-customer-cosigner-repository/gcp-cosigner:1.1.0.eu
* Image SHA (EU2): sha256:af2178f2f80a64107b04d7627e3e0e2483c745f999fdf30f60c2808900ae40ff
* Image Path (EU2): us-docker.pkg.dev/fireblocks-customer-cosigner/fireblocks-customer-cosigner-repository/gcp-cosigner:1.1.0.eu2
* Bug fixes and performance improvements

### Version 1.0.0 (January 2025)

**Version hash:** 27de90bb6f

* Image SHA (US): sha256:af6b7e6276af09e20e389ec2f63299bca293f646154e48b8144a2a9179c0b06e
* Added helper script for updating an existing GCP Customer Co-Signer to a newer image
* Validated + handled if missing physicalDeviceId in the Co-Signer’s config (relevant to all Co-Signers)
* Added default image path and image SHA to GCP Customer Co-Signer scripts
* Image SHA (US): sha256:af6b7e6276af09e20e389ec2f63299bca293f646154e48b8144a2a9179c0b06e
  Image Path (US): us-docker.pkg.dev/fireblocks-customer-cosigner/fireblocks-customer-cosigner-repository/gcp-cosigner:1.0.0
* Image SHA (EU): sha256:5c456aa3e5953e0fedfa80717d8cc977e9d9ee94eb561cbabe69379baa587386
* Image Path (EU): us-docker.pkg.dev/fireblocks-customer-cosigner/fireblocks-customer-cosigner-repository/gcp-cosigner:1.0.0.eu
* Image SHA (EU2): sha256:861c5d90fdb345a794cea4a8ce2c886c2cb3a9d531b825da38cc27848b978a0c
* Image Path (EU2): us-docker.pkg.dev/fireblocks-customer-cosigner/fireblocks-customer-cosigner-repository/gcp-cosigner:1.0.0.eu2
* Image SHA (Sandbox): sha256:18018d945f1bf7f8cd82273798d997c0bdef56db67a1c101c87d8e12aaf6df79
* Image Path (Sandbox): us-docker.pkg.dev/fireblocks-customer-cosigner/fireblocks-customer-cosigner-repository/gcp-cosigner:1.0.0.sandbox

### Version 0.9.5 (October 2024)

**Version hash:** 121b4c2775

* Image SHA: sha256:894c4e573b52e785cf7b2ad2e10f73d766b4a88cb1078daf087ce8ab8703f928
* Security policy enhancements
* Bug fixes

### Version 0.9.4 (November 2024; EU version)

**Version hash:** d177e696c3

* Image SHA: sha256:30aca13b7dcb7db41a4138066ca3bc6e601ad1cdc417484f8c6a7433851eba62
* Added support for platform remote commands
* Performance optimizations
* Security policy enhancements
* Bug fixes

### Version 0.9.4 (October 2024; non-EU version)

**Version hash:** d177e696c3

* Image SHA: sha256:7ecfc480ccb65613db0f2b1cedfcd765be944bbadb5da1e0e098fa0ccb0876cb (Prod, not EU)
* Added support for platform remote commands
* Performance optimizations
* Security policy enhancements
* Bug fixes

### Version 0.9.3 (August 2024)

**Version hash:** 6647aa5291

* Image SHA: sha256:ed12b926a7d46e98be9943791c4e350dd193a4bc5f7c222ce1c765715b11bf9e
* Added printing the Co-signer Public Key to the logs

### Version 0.9.2 (July 2024)

**Version hash:** 257b33246b

* Image SHA: sha256:5bd371e9a877bcf7cc662ecaae5791b3b5c8b797348e1540faaf272cc153cb39
* Initial release


# SGX API Co-signer Version History
Source: https://developers.fireblocks.com/reference/api-cosigner-versions-sgx



Fireblocks updates the API Co-signer software to include stability enhancements and new features. This article provides details about the most recent SGX Co-signer versions. Always use the latest version listed here for optimal performance.

## Latest SGX Co-signer image version

### **Version 2026.04.27 (April 2026)**

**Version hash:** `1d5b48eeef`

* Performance improvements and bug fixes

***

## SGX Co-signer image version history

### Version 2026.03.02 (March 2026)

**Version hash:** 95a317d3c7

* Added support for POLICY\_CHANGE approval request type (the customer co-signer can now approve policy changes via Policy Service v2)
* Performance improvements and bug fixes

### Version 2026.01.29 (January 2026)

**Version hash:** 340d9f6057

* Bug fixes and performance improvements

### Version 2025.12.30 (December 2025)

**Version hash:** a294449c1b

* Added support for "Protected Tags" approval requests

### Version 2025.12.11 (December 2025)

**Version hash:** c44604398e

* The callback handler can now authenticate using a certificate signed by a root CA certificate preloaded to the Co-signer
* The callback handler can now authenticate using both JWT and a certificate provided directly to the Co-signer (or signed by a root CA certificate provided to the Co-signer)
* The callback can now return a "retry" response on exchange withdraw operation

### Version 2025.10.09 (October 2025)

**Version hash:** 4e34888c01

* Fixed bug parsing messages after websocket reconnect.
* Fixed bug sending messages on half-closed websocket connections.

### Version 2025.08.12 (August 2025; US environments only)

**Version hash:** 19c07421dc

* Fixed WebSocket bug causing performance issues

### Version 2025.07.16 (July 2025)

**Version hash:** bb61e507

* Fixed bugs and increased performance
* Better support for web sockets

### Version 3.10.1 (April 2025)

**Version hash:** 7160d7b833

* Bug fixes and performance improvements

### Version 3.7.1 (October 2024)

**Version hash:** 4ec196aec5

* Decreased signing latency, along with general performance increases
* Remote management capabilities through Fireblocks Console
* Support for more types of approval requests
* Various fixed and improved handling of internal errors
* Timing details are logged after every outgoing network request
* The cosigner version will be reflected in the HTTP User-Agent header

### Version 3.6.5 (February 2024)

**Version hash:** 3b807e2af7

* Improved logging for easier problem-solving
* Improved stability, security, and performance
* Enhanced deployment flexibility
* Added support for the Callback Handler retry mechanism, enabling the Callback Handler to respond asynchronously
* Updated major and minor dependencies
* Preliminary support for upcoming features
* Bug fixes

### Version 3.5.0 (August 2023)

* [MPC-CMP security enhancements](https://support.fireblocks.io/hc/en-us/articles/10167020461596-MPC-CMP-security-enhancements-version-update-August-2023)
* Bug fixes

### Version 3.3.0 (January 2022)

* Added support for HTTP network proxy on outbound requests
* Bug fixes

***

## Latest SGX Co-signer script version

### Version 2025.10.11 (December 2025)

* New default Docker image: 2025.10.11

## SGX Co-Signer script version history

### Version 2025.10.09 (October 2025)

* New default Docker image: 2025.10.09
* Switched to Calendar Versioning to align script versions with default image versions

### Version 1.1.13 (August 2025)

* New default Docker image 2025.08.12

### Version 1.1.11 (April 2025)

* New default Docker image 3.10.1

### Version 1.1.10 (January 2025)

* New default Docker image 3.7.1

### Version 1.1.9 (February 2024)

* New default Docker image 3.6.5

### Version 1.1.8 (January 2024)

* Added support for Callback Handler configuration via Azure Marketplace
* Same default Docker image as in image version 3.5.0 and used as in script version 1.1.7

### Version 1.1.7 (August 2023)

* New default Docker image 3.5.0

### Version 1.1.6 (February 2023)

* Added support for Docker version 1.29.2
* Added validation for microcode:
  * Additional information about the microcode version appears in the logs
  * Relevant only to customers with SGX Co-signers installed on-prem
* Added validation to make sure Hyper-Threading is disabled
  * If Hyper-Threading is enabled, additional information appears in the logs
  * Relevant only to customers with SGX Co-signers installed on-prem

### Version 1.1.5 (February 2022)

* New default Docker image 3.3.0
* Added support for Co-signers in high-availability
* Updated authentication model
* Added support for HTTP network proxy on outbound requests

***

## Checking SGX Co-signer versions

### How do I check the version of my running SGX Co-signer image?

To check your running SGX Co-signer image version, run the following command on your VM:

```bash theme={"system"}
 docker inspect cosigner | jq -r '.[0].Config.Image +" " + . [0].Image'
```

### How do I check the version of my running SGX Co-signer script?

To check your running SGX Co-signer script version, run the following command on your VM:

```bash theme={"system"}
 head cosigner -n 3 | grep -i ver
```


# API Endpoints Overview
Source: https://developers.fireblocks.com/reference/api-endpoints-overview



The **API Endpoints** section lists every REST endpoint in the Fireblocks API. Each endpoint page includes:

* **Description** — What the endpoint does and when to use it
* **Parameters and request body** — Required and optional fields
* **Response schema** — Response shape and status codes
* **Playground** — Try the request with your credentials (when enabled)

The reference is generated from our [OpenAPI 3.0 specification](https://docs.fireblocks.com/api/v1/swagger.yaml). You can import the spec into Swagger UI, ReDoc, Postman, or use it to generate client libraries.

## Before you call the API

* **[Authentication](/reference/signing-a-request-jwt-structure)** — Sign requests with JWT using your API key and secret
* **[Rate limiting](/reference/rate-limiting)** — Request limits and best practices

## Testing your calls

Each endpoint page has a **playground** where you can try requests with your credentials. If you prefer to test from Postman instead, use the [Postman Guide](/reference/explore-postman-collection).

## Next steps

Use the sidebar to browse endpoints by category, or search for a specific operation. For high-level concepts and SDKs, see the [API Overview](/reference/api-overview).


# API responses and error codes
Source: https://developers.fireblocks.com/reference/api-error-codes



# HTTP status code summary

| HTTP Status Code Summary |                   |                                                                                                                                |
| ------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| 200                      | OK                | The request was processed as expected.                                                                                         |
| 400                      | Bad Request       | The request is not well-formed, violates the schema, or has incorrect fields.                                                  |
| 401                      | Unauthorized      | The API key doesn't match the signature or have the necessary permissions to perform the request.                              |
| 403                      | Forbidden         | The API key doesn't have the necessary permissions to complete the request.                                                    |
| 404                      | Not Found         | The requested resource doesn't exist.                                                                                          |
| 429                      | Too Many Requests | Too many requests hit the API too quickly. Blocked due to rate limiting. We recommend an exponential backoff of your requests. |
| 5XX                      | Server Errors     | Something went wrong on Fireblocks' end. (These are rare.)                                                                     |

# API error codes

The tables below contain all error codes (along with their corresponding HTTP status codes) for the Fireblocks API. We recommend reviewing the codes related to the features you want to implement for your workspace and customers.

## 4XX Error Codes

| Error Code | HTTP Status Code | Relevant Features               | Issue and Remediation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ---------- | ---------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| -1         | 401              | All                             | **Invalid signature** If you receive this error message, ensure the private key you used is correct.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| -2         | 401              | All                             | **Missing API Key in the JWT** Verify that you specify the API key                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| -3         | 401              | All                             | **The entire JWT is missing**   - Uncommon\_ - Potential code change, or bad parameters passed to Fireblocks SDK constructor                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -4         | 401              | All                             | **Wrong URL in the JWT**   - Uncommon\_ - Potential code change to the Fireblocks SDK source code on your device                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| -5         | 401              | All                             | **Unauthorized: Invalid token format** This error code typically indicates the certificate associated with the API user making the call has expired.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| -6         | 401              | All                             | **Wrong User in the JWT** The user being used as part of the request is incorrect. Verify that the correct user is being used                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -7         | 401              | All                             | **Unauthorized: Token was not accepted** This error code typically indicates that the JSON Web Token (JWT) supplied with the API user’s request was not accepted. API requests to Fireblocks are authenticated using the provided JWT. If the JWT is invalid, you will receive the error code. The cause of the error is likely either the wrong API key being used or the wrong baseURL being used.  For SDK users, this typically means an incorrect API key was used to create the client. For users with native API client implementations, this typically indicates an error with your JWT creation logic. |
| -8         | 401              | All                             | **Insufficient permissions** This error code typically indicates that the API user initiating this request does not have access to the requested operation based on their user role                                                                                                                                                                                                                                                                                                                                                                                                                             |
| -10        | 401              | All                             | **The request has expired** This error typically indicates the JSON Web Token (JWT) supplied with the API user’s request has timed out.  Please note:   - For Fireblocks SDK users, the JWT expiration time is defined based on the system time. - For users with their own API client implementations, the JWT data is defined by the user’s implementation.                                                                                                                                                                                                                                                   |
| -12        | 401              | All                             | **The request is with a future issuance timestamp (iat)** This error code typically indicates the JSON Web Token (JWT) supplied with the API user’s request is not yet valid for processing.   - For SDK users, the JWT “initiated–at” time is defined based on the system time. - For users with their own API client implementations, the JWT data is defined by the user’s implementation.                                                                                                                                                                                                                   |
| 1000       | 400              | Vault                           | **GetVaultAccounts request has invalid values** Check that you pass a valid `minAmountThreshold` (if you pass it) and only one of `namePrefix`, `nameSuffix` if you pass it                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 1002       | 400              | Vault                           | **Create Vault Account failed** Verify that the values provided to the create vault account request are valid and conform to the types specified in the API Docs                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| 1004       | 404              | Vault                           | **Vault account ID was not found** Verify that the vault account you're trying to query is valid and exists                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 1006       | 404              | Asset, Balance                  | **Asset doesn't exist** The asset requested for the given vault account does not exist. Verify that the vault account contains the asset you're requesting.                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 1008       | 400              | Wallet, Asset (EOS Specific)    | **EOS Wallet Creation failed** The eosAccountName parameter is invalid                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 1010       | 400              | Wallet                          | **Renaming a deposit address failed** You're trying to add an address to a blockchain that does not support more than 1 address (such as ETH)                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 1013       | 400              | Vault                           | **Vault account renaming failed** Verify that the parameters passed to the vault account renaming operation are valid                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| 1015       | 400              | Wallet                          | **Rename a deposit address failed** Verify that the parameters that were passed are valid and that the asset you're trying to rename exists                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 1016       | 400              | Wallet                          | **Rename a deposit address failed** The rename operation failed due to a backend issue - open a ticket to support                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| 1017       | 400              | Vault                           | **Hide vault account failed** The vault account you requested to hide does not exist. Please verify you're using the correct vault account ID                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 1019       | 400              | Vault                           | **Hide on a hidden vault account request** You're requesting to hide a vault account that is already hidden. Please verify you're using the correct vault account ID                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 1020       | 400              | Vault                           | **Unhide vault account failed** The vault account you requested to unhide does not exist. Please verify you're using the correct vault account ID                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| 1022       | 400              | Vault                           | **Unhide on a visible vault account request** You're requesting to unhide a vault account that is not hidden. Please verify you're using the correct vault account ID                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| 1023       | 400, 404         | Wallet                          | **Get legacy address failed** There is no legacy address used for this specific asset                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| 1024       | 400, 404         | Wallet                          | **Get legacy address for an asset without one** The asset you're trying to get the legacy address for does not have one (for example, ETH)                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| 1025       | 400              | Asset, Vault, Wallet            | **Usage of an unsupported asset** The asset you specified in your request is invalid. Please check it against the supported asset list                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 1026       | 400              | Asset, Vault, Wallet            | **Creation of a wallet that already exists** You've requested to create a wallet for an asset that already has a wallet in the vault account. Please check whether you're using the correct vault account and the correct asset                                                                                                                                                                                                                                                                                                                                                                                 |
| 1027       | 400              | Asset, Balance                  | **Requested max spendable amount for asset that doesn't support that request** You've requested to know the max spendable amount for an asset, which does not support this request. Verify you're using one of the assets according to the API docs                                                                                                                                                                                                                                                                                                                                                             |
| 1028       | 400              | Asset, Balance                  | **Max Spendable Amount invalid value** The parameters you provided for the request are invalid. Please verify you provided the correct type of values, as well as a valid asset and vault account ID                                                                                                                                                                                                                                                                                                                                                                                                            |
| 1031       | 400              | Asset, Balance                  | **Get balance by assets** The request to balance of assets in all vault accounts is invalid, only one of `accountNamePrefix` and `accountNameSuffix` can be provided                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 1032       | 400, 404         | Asset, Balance                  | **Get balances by assets or get balance for asset failed** The asset requested does not exist in the vault account                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| 1034       | 400              | Wallet                          | **Create testnet asset failed** You're requested to create a testnet asset on a workspace that does not have testnet support                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 1035       | 400              | Asset                           | **Activate wallet failed** The request to activate the wallet failed. Please open a ticket to support                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| 1037       | 400              | Vault                           | **Get vault accounts endpoint is disabled** Workspaces created after May 2022 do not support the get vault accounts endpoint; use the paged request                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 1038       | 400              | Wallet, Asset                   | **Adding a token without base asset** Before adding a token to the vault account, please create a base asset wallet                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 1039       | 400              | Wallet, Asset                   | **Insufficient base asset for token wallet** Before creating a token asset, make sure you have sufficient base asset to cover token transactions                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| 1040       | 401              | Vault                           | **Unauthorized user to create vault account** The user who is trying to add a vault account does not have the proper permissions needed to create a vault account. Make sure you use the correct user                                                                                                                                                                                                                                                                                                                                                                                                           |
| 1048       | 400              | Vault                           | **The vault account type is not supported by the workspace** You attempted to create/use a vault account with a type that isn’t enabled or recognized for your tenant (plan/feature flag/environment). Use a supported type (or omit it to use the default), or contact Fireblocks to enable the feature.                                                                                                                                                                                                                                                                                                       |
| 1103       | 400              | Exchange, Fiat                  | **No such exchange/fiat account ID** The exchange or fiat account ID does not exist. Make sure you're using the correct one                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 1105       | 400              | Exchange                        | **Exchange account for asset by ID does not exist** The exchange account's asset does not exist for the specified exchange account ID. Make sure you're using the correct exchange account ID and asset                                                                                                                                                                                                                                                                                                                                                                                                         |
| 1106       | 400              | Exchange Transfers              | **No such exchange account ID** The exchange account ID specified does not exist                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| 1108       | 408              | Exchange                        | **Exchange timeout when adding an account** We faced an internal timeout when trying to add the exchange account                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| 1111       | 400              | Exchange Transfers              | **Exchange convert failed** Failed to perform a convert operation. Please check the message reply to understand the issue                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
|            |                  |                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 1202       | 400              | Internal Wallets                | **Create internal wallet failed** Internal wallet name must be specified, not empty, and to not already exist in a different wallet                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 1204       | 400              | Internal Wallets                | **Get internal wallet by id failed** The internal wallet specified does not exist. Make sure you're querying the correct internal wallet ID                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 1206       | 400              | Internal Wallets                | **Delete internal wallet failed** Failed to delete the internal wallet. Please make sure you've specified the correct internal wallet parameters                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| 1208       | 400              | Internal Wallets                | **Create an internal wallet failed** Failed to create an internal wallet. Please verify you've provided the correct parameters for the creation as per the API docs                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 1209       | 400              | Internal Wallets                | **Getting the wallet's asset failed** The internal wallet based on the ID and asset specified does not exist. Please make sure you're using the correct asset and wallet ID                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 1212       | 400              | Internal Wallets                | **Deleting specific asset from wallet failed** Please verify that you specified the correct wallet ID and asset ID for deletion                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 1213       | 400              | Internal Wallets                | **Create an unsupported asset address in a wallet** The asset you're trying to add to the wallet is not supported. Verify the asset you're trying to use                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| 1214       | 400              | Internal Wallets                | **Create an asset from a different network in the wallet** The asset you're trying to add to the wallet is in a different network (mainnet or testnet), and your workspace does not support this network. Please verify the network of the asset and that your workspace correlates                                                                                                                                                                                                                                                                                                                             |
| 1215       | 400              | Internal Wallets                | **Add an asset in a wallet that already has it** You're trying to add an asset to the internal wallet, but it already has this asset. Please make sure you're adding a new asset and not one that already exists                                                                                                                                                                                                                                                                                                                                                                                                |
| 1216       | 400              | Internal Wallets                | **Add an asset with an invalid address to the wallet** You're trying to add an asset to the internal wallet, but the address does not match the asset's conventions. Please check the address you're trying to add                                                                                                                                                                                                                                                                                                                                                                                              |
|            |                  |                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 1302       | 400              | External Wallets                | **Create external wallet failed** External wallet name must be specified, not empty, and to not already exist in a different wallet                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 1304       | 400              | External Wallets                | **Get external wallet by Id failed** The external wallet requested does not exist. Please make sure you're using the correct wallet ID                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 1306       | 400              | External Wallets                | **Delete external wallet failed** Failed to delete the external wallet. Please make sure you've specified the correct external wallet parameters                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| 1308       | 400              | External Wallets                | **Create an external wallet failed** Failed to create an external wallet. Please verify you've provided the correct parameters for the creation as per the API docs                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 1309       | 400              | External Wallets                | **Getting the wallet's asset failed** The external wallet based on the ID and asset specified does not exist. Please make sure you're using the correct asset and wallet ID                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 1312       | 400              | External Wallets                | **Deleting specific asset from wallet failed** Please verify that you specified the correct wallet ID and asset ID for deletion                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 1313       | 400              | External Wallets                | **Create an unsupported asset address in a wallet** The asset you're trying to add to the wallet is not supported. Verify the asset you're trying to use                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| 1314       | 400              | External Wallets                | **Create an asset from a different network in the wallet** The asset you're trying to add to the wallet is in a different network (mainnet or testnet), and your workspace does not support this network. Please verify the network of the asset and that your workspace correlates                                                                                                                                                                                                                                                                                                                             |
| 1315       | 400              | External Wallets                | **Add an asset in a wallet that already has it** You're trying to add an asset to the external wallet, but it already has this asset. Please make sure you're adding a new asset and not one that already exists                                                                                                                                                                                                                                                                                                                                                                                                |
| 1316       | 400              | External Wallets                | **Add an asset with an invalid address to the wallet** You're trying to add an asset to the external wallet, but the address does not match the asset's conventions. Please check the address you're trying to add                                                                                                                                                                                                                                                                                                                                                                                              |
|            |                  |                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 1351       | 400              | Contract Wallets                | **Create contract wallet failed** Contract wallet name must be specified, not empty, and to not already exist in a different wallet                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 1354       | 400              | Contract Wallets                | **Get contract wallet by Id failed** The contract wallet requested does not exist. Please make sure you're using the correct wallet ID                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 1356       | 400              | Contract Wallets                | **Delete contract wallet failed** Failed to delete the contract wallet. Please make sure you've specified the correct contract wallet parameters                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| 1358       | 400              | Contract Wallets                | **Create an contract wallet failed** Failed to create an contract wallet. Please verify you've provided the correct parameters for the creation as per the API docs                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 1359       | 400              | Contract Wallets                | **Getting the wallet's asset failed** The contract wallet based on the ID and asset specified does not exist. Please make sure you're using the correct asset and wallet ID                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 1362       | 400              | Contract Wallets                | **Deleting specific asset from wallet failed** Please verify that you specified the correct wallet ID and asset ID for deletion                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 1363       | 400              | Contract Wallets                | **Create an unsupported asset address in a wallet** The asset you're trying to add to the wallet is not supported. Verify the asset you're trying to use                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| 1364       | 400              | Contract Wallets                | **Create an asset from a different network in the wallet** The asset you're trying to add to the wallet is in a different network (mainnet or testnet), and your workspace does not support this network. Please verify the network of the asset and that your workspace correlates                                                                                                                                                                                                                                                                                                                             |
| 1365       | 400              | Contract Wallets                | **Add an asset in a wallet that already has it** You're trying to add an asset to the contract wallet, but it already has this asset. Please make sure you're adding a new asset and not one that already exists                                                                                                                                                                                                                                                                                                                                                                                                |
| 1366       | 400              | Contract Wallets                | **Add an asset with an invalid address to the wallet** You're trying to add an asset to the contract wallet, but the address does not match the asset's conventions. Please check the address you're trying to add                                                                                                                                                                                                                                                                                                                                                                                              |
|            |                  |                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 1401       | 400              | Transaction                     | **The operation requested is not supported** The operation argument that you provided in the create transaction is not supported. Please verify it's correct                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 1402       | 400              | Transaction                     | **Source balance insufficient** The balance of the source account is not sufficient to cover the transaction                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 1403       | 400              | Transaction                     | **Destination balance is insufficient** Some blockchains (such as NEAR) require a minimal amount of assets to be activated. You tried to pass less than the minimal amount to a vault account that does not have such a wallet, thus the wallet can't be created. Please verify you're transferring a sufficient amount, or have the destination create a wallet and deposit a sufficient amount of base asset                                                                                                                                                                                                  |
| 1404       | 400              | Transaction                     | **Invalid Peer type** When creating the transaction, verify that the type of the source and destination are valid and one of the defined enums in the API docs                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 1405       | 404              | Transaction                     | **No such transaction** The transaction ID you used to try and get the transaction object is invalid and was not found in the system. Make sure you're using the correct transaction ID                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 1406       | 400              | Transaction                     | **Failed to cancel transaction** Cancelling the transaction failed for some reason. Please open a support ticket                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| 1407       | 400              | Transaction                     | **User can't create a transaction** The user trying to create the transaction does not have sufficient permissions to do so. Please verify the user's permission level and that you're using the correct user                                                                                                                                                                                                                                                                                                                                                                                                   |
| 1408       | 400              | Transaction                     | **Paged get tried to change direction** When getting transactions in a paged fashion, you can only go in one direction (forward or backward) and can't change direction mid execution. Make sure you're only querying the information in one direction                                                                                                                                                                                                                                                                                                                                                          |
| 1409       | 400              | Transaction                     | **Transaction creation parameters are invalid** Here is a list of items to check:   1. The asset type is valid and is supported 2. You can only specify `destination` or `destinations`, not both 3. For OTA, you must specify the address 4. Typed messages only supported BTC, LTC, DASH, and ETH 5. AML Customer reference ID can only use `-_:` and alpha-numeric 6. You can not have more than 650 destinations in the `destinations` parameters 7. Invalid `nodeControls` parameters                                                                                                                      |
| 1410       | 400              | Transaction                     | **Transaction destination wallet does not exist** The destination is sending the transaction to an external/internal/contract wallet by an ID, but the ID specified does not exist. Check that the ID you're using is correct                                                                                                                                                                                                                                                                                                                                                                                   |
| 1411       | 400              | Transaction                     | **Transaction destination wallet asset does not exist** The destination is sending the transaction to an external/internal/contract wallet by an ID, but the asset used in the transaction does not exist. Check that the asset has an address in the wallet ID                                                                                                                                                                                                                                                                                                                                                 |
| 1412       | 400              | Transaction                     | **Transaction destination wallet address is suspended** The destination is an external/internal/contract wallet that has not been approved yet. Approve it and try again                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| 1421       | 400              | Transaction                     | **Confirmation number change failed** Changing the number of confirmations for the transaction failed. Please verify that the transaction exists; otherwise, open a support ticket                                                                                                                                                                                                                                                                                                                                                                                                                              |
| 1422       | 400              | Transaction                     | **Confirmation number change failed** Changing the number of confirmations for the transaction by transaction hash failed. Please make sure you're using the correct transaction hash; otherwise, open a support ticket                                                                                                                                                                                                                                                                                                                                                                                         |
| 1423       | 400, 404         | Transaction                     | **Get transaction by transaction hash failed** Couldn't find a transaction with the specified transaction hash. Please verify the transaction hash and try again                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| 1424       | 400              | Transaction, Network Connection | **Destination address invalid** Here is a list of parameters to check:   1. The address used is invalid for the asset you're using 2. The target (in case of a network transfer) does not contain a wallet for the specified asset 3. You're using the internal/external/contract wallet for a different workspace than the one you're performing the transaction on 4. You are trying to send a transaction to a network connection that you do not have 5. You're using `destinations` and one of the destinations is a network connection - this is not supported                                            |
| 1425       | 400              | Transaction                     | **Missing a tag** You're trying to send a transaction to an address that requires a tag. Please verify you're providing a tag                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 1426       | 400              | Transaction                     | **Unfreeze failed** You tried to unfreeze a transaction, but it was neither rejected nor failed by AML; therefore, it can't be unfrozen                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 1427       | 400              | Transaction                     | **Source type of transaction is invalid** You tried to send a transaction with the source being invalid. Verify that the source is one of: `VAULT_ACCOUNT`, `EXCHANGE_ACCOUNT`, `GAS_STATION` or `FIAT_ACCOUNT`                                                                                                                                                                                                                                                                                                                                                                                                 |
| 1428       | 400              | Transaction                     | **Destination of transaction is invalid** The destination type of one of the destinations is not one of the defined enums in the API docs. Verify that it is correct and try again                                                                                                                                                                                                                                                                                                                                                                                                                              |
| 1429       | 400              | Asset, Transaction              | **Validate address failed** The asset you tried to use for the `validate_address` endpoint is not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 1431       | 400              | Asset, Transaction              | **Validate address didn't find an address** The address provided to the `validate_address` endpoint is invalid.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 1432       | 400              | Transaction                     | **Invalid amount specified** The amount must be a number or a numeric string; verify it is so                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 1433       | 400              | Transaction                     | **Invalid tag specified** The tag/memo specified does not comply with the rules of the blockchain. Verify the tag/memo is valid                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 1434       | 400              | Transaction                     | **Freeze failed** or **Cannot freeze** Depending on the context of the error code, you will see one of the above responses. Typically, freezing fails because of one of the following reasons:   - The transaction is not in either the **Confirming** or the **Completed** status. - An input is not available. - There is an insufficient balance for freezing. - The transaction direction or asset type is not supported for freezing.                                                                                                                                                                      |
| 1435       | 400              | Transaction                     | **List unspent for unknown asset** You tried to get the unspent inputs (UTXO) for an asset that does not have such values, or no UTXOs exist                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 1437       | 400              | Exchange, Transaction           | **Unsupported transfer** Direct transfers (Exchange to OTA) is not supported for the Kraken exchange                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 1438       | 400              | Transaction                     | **External Tx ID Duplicate** The `externalTxId` specified in the transaction was already used in the past. Please use a different one                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| 1439       | 404              | Transaction                     | **No such External Tx ID** The external Tx ID used does not exist. Please verify the external Tx ID you're using                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| 1440       | 400              | Transaction                     | **Drop for unsupported blockchain** You're trying to run a drop transaction request for a blockchain that is not `ETC` or `ETH`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 1441       | 400              | Transaction                     | **Replace by fee too low** You're attempting to perform an RBF transaction, but the gas price you specified is too low. Please check it and submit a higher gas price                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| 1443       | 400              | Transaction                     | **Too late for RBF** You're trying to replace by fee, but the transaction was already mined                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 1445       | 403              | Transaction                     | **User can't freeze** The user who is trying to perform a freeze does not have the permissions to perform this. Check the user's permissions and that you're using the correct user                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 1446       | 403              | Transaction                     | **User can't unfreeze** The user who is trying to perform an unfreeze does not have the permissions to perform this. Check the user's permissions and that you're using the correct user                                                                                                                                                                                                                                                                                                                                                                                                                        |
| 1448       | 400              | Transaction                     | **Fee payer is not allowed for asset** You're trying to define a fee payer for an asset that does not support it. Please check whether the asset you're using allows for a fee payer configuration                                                                                                                                                                                                                                                                                                                                                                                                              |
| 1449       | 400              | Transaction                     | **Fee payer can't pay** The defined fee payer does not have a wallet with the base asset to pay the fee. Verify that you specified the correct fee payer and check that it contains a base asset wallet with a sufficient amount to pay for the transaction                                                                                                                                                                                                                                                                                                                                                     |
| 1450       | 400              | Transaction                     | **Transactions are blocked for this blockchain** We have temporarily disabled transactions for the specified blockchain. Check the  [status page](https://status.fireblocks.com)  for more details                                                                                                                                                                                                                                                                                                                                                                                                              |
| 1451       | 400              | Transaction                     | **Transaction confirmations don't match Fireblocks restrictions** Fireblocks requires a specific number or a minimum number of confirmations for some blockchains. Manually setting confirmations for a transaction must meet these requirements. For more, see  [Deposit Control & Confirmation Policy](https://support.fireblocks.io/hc/en-us/articles/360013034359)  .                                                                                                                                                                                                                                       |
| 1454       | 400              | Transaction                     | **Missing license for creating a MEV protected transaction** This feature is not enabled in your workspace, and you should contact your Customer Success Manager or the Fireblocks Support team                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 1455       | 400              | Transaction, Gasless (meta-tx)  | **Missing Gasless configuration** Gasless transactions aren’t set up for this workspace/asset. Configure Gasless (relayer/fee payer) or send a standard transaction.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 1502       | 400              | Asset, Transaction              | **Trying to use a deprecated asset** The asset specified in the transaction is deprecated and can't be used. Please check the asset and use a different one                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 1503       | 400              | Asset, Balance, Transaction     | **Unsupported asset** The asset specified is not supported. Please check the asset you've specified                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
|            |                  |                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 1601       | 404              | Network Connection              | **Network Connection Id does not exist** The network connection you're trying to query by ID does not exist. Please check the ID you're using                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 1603       | 400              | Network Connection              | **Delete Network Connection but id is not specified** The delete network connection request does not have a `connectionId` parameter specified, please make sure one is provided and exists                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 1604       | 400              | Network Connection              | **Create a network connection failed** The network connection creation failed. Check the error message for more information and open a support ticket if insufficient                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| 1605       | 404              | Network Connection              | **Get Network Connection for unknown id** The network connection ID provided could not be found. Please verify you're using the correct ID                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| 1606       | 404              | Network Connection              | **Delete network connection for unknown id** The network connection ID provided could not be found. Please verify you're using the correct ID                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 1607       | 400              | Network Connection              | **Setting the routing policy for a network connection failed** Verify that you used the proper parameters for the call                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 1608       | 404              | Network Connection              | **Set routing policy for an unknown network connection id** The ID you provided for the call was not found. Verify you're using the correct ID and it exists                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 1609       | 400              | Network Connection              | **Validating routing policy failed** The attempt to validate whether the network connection's routing will lead to a third party or not for a given asset failed. Please verify you passed the correct parameters and open a support ticket if needed                                                                                                                                                                                                                                                                                                                                                           |
| 1610       | 404              | Network Connection              | **Validating routing policy for an unknown network connection id** The ID you provided for the call was not found. Verify you're using the correct ID and it exists                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 1611       | 403              | Network Connection              | **No multiple network profiles** The workspace does not support multiple network profiles. Contact us to request support                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| 1612       | 422              | Network Connection              | **The counterparty rejected the connection request** The Counterparty has to send a connection request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 1613       | 422              | Network Connection              | **The counterparty is already an active connection** The network connection already exists                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| 1614       | 422              | Network Connection              | **The connection is pending approval** You can request approval from the workspace admins                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| 1615       | 422              | Network Connection              | **The connection is pending approval** You can request approval from your counterparty                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 1616       | 403              | Network Connection              | **Network connection cannot be deleted** There is an active Smart Transfers ticket with the connection, which must be closed before deleting the Network connection                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 9007       | 404              | Network Connection              | **The Fireblocks Network is not activated in the workspace** Reach out to Fireblocks Support to resolve this                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 9011       | 403              | Network Connection              | **Cannot delete network ID** The default ID cannot be deleted before making another ID the default                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| 9012       | 403              | Network Connection              | **Network profile cannot be deleted** It is the last remaining ID. There must be at least one Network profile per tenant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| 9013       | 403              | Network Connection              | **Network profile cannot be deleted** There is an active Smart Transfers ticket with the Network profile, which must be closed before deleting the Network profile                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| 9014       | 422              | Network Connection              | **Invalid network name** The name cant contain the `<` and `>` characters                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| 9015       | 403              | Network Connection              | **Could not add an additional network ID** Contact Fireblocks Support to activate the feature                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 9016       | 422              | Network Connection              | **The selected asset is not supported on the Fireblocks Network** Reach out to Fireblocks Support to resolve this                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| 9017       | 422              | Network Connection              | **Invalid routing policy > non-custom scheme** A routing destination type or ID is required                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 9018       | 422              | Network Connection              | **Invalid routing policy > destination ID incompatible with selected asset.** Make sure you are sending a supported asset                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| 9019       | 422              | Network Connection              | **Invalid routing policy > selected routing policy is not allowed** Select a valid  [routing policy](https://support.fireblocks.io/hc/en-us/articles/5671826748316-Flexible-Network-Routing)                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 9020       | 422              | Network Connection              | **Invalid routing policy > selected routing destination is not supported** Select one of the  [supported destination](https://support.fireblocks.io/hc/en-us/articles/5671826748316-Flexible-Network-Routing)  s                                                                                                                                                                                                                                                                                                                                                                                                |
| 9021       | 422              | Network Connection              | **Invalid routing policy > selected crypto destination is not supported** Select a vault or a connected exchange account.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| 9022       | 422              | Network Connection              | **Invalid routing policy > third-party account provided is invalid** Make sure you are adding a supported third-party destination                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| 1706       | 400              | FIAT Accounts                   | **FIAT Account id provided is unknown** The exchange account ID you provided was not found. Please verify you're using the correct account ID                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 1708       | 400              | FIAT Accounts                   | **FIAT Account id provided is unknown** The exchange account ID you provided was not found. Please verify you're using the correct account ID                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
|            |                  |                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 1901       | 400              | Asset, Transaction              | **Estimate fee for unknown asset** The asset you specified for the estimate fee call is unknown. Please make sure you're using a supported and known asset                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| 1902       | 400              | Asset, Transaction              | **Estimate fee for an invalid asset** The asset you specified does not support the estimate fee call. Please make sure you're using a supported and allowed asset                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| 1904       | 400              | Asset, Transaction              | **Estimate fee with invalid parameters** Make sure when calling the estimate fee endpoint that you do not have `destination` and `destinations` parameters both used, and that the `source` parameter is a vault account                                                                                                                                                                                                                                                                                                                                                                                        |
| 1905       | 400              | Asset, Transaction              | **Estimate fee failed due to insufficient funds** The funds you have in the source vault are not sufficient, and thus the estimate fee call failed. Make sure you have sufficient base asset in the source vault and try again                                                                                                                                                                                                                                                                                                                                                                                  |
| 1907       | 400              | Asset, Transaction              | **Estimate fee failed due to smart contract error.** The transaction reverted during its simulation as part of estimating the gas limit. There are three ways to properly handle this error:   1. Initiate the transaction again while using different parameters. 2. Try using a different vault to perform the transaction. 3. Read the contract’s source code to better understand the error.                                                                                                                                                                                                                |
| 1908       | 400              | Asset, Transaction              | **Estimate fee failed since the amount you are sending is too small** The transaction failed since the amount you tried to send was not enough to pass our balance validation and internal tx checks. Confirm the transfer amount is above the required minimum for this blockchain or more than the transaction fees necessary before resubmitting the transaction. Minimum transfer amounts vary per blockchain. Known minimums: Bitcoin (BTC) - 546 satoshi Cardano (ADA) - 1 ADA + applicable transaction fees                                                                                              |
| 1909       | 400              | Asset, Transaction              | **Estimate failed due to insufficient gas fees** The transaction failed since you didn't have enough gas fees. Make sure you have sufficient gas money and try again.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| 2002       | 400              | Public Key                      | **Public key could not be found** Make sure that the information you provided to the public key query is valid, and a wallet for this asset exists in the specified vault account                                                                                                                                                                                                                                                                                                                                                                                                                               |
|            |                  |                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 2101       | 400              | Gas Station                     | **Invalid gas station parameters** When editing the gas station configuration, make sure you provide both `gasCap` and `gasThreshold`                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| 2110       | 400              | Gas Station                     | **Invalid asset for gas station** When editing the gas station configuration, the asset you specified is not supported for this operation. Make sure you're using a supported and valid asset                                                                                                                                                                                                                                                                                                                                                                                                                   |
|            |                  |                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 2201       | 400              | Balance, Private Ledger         | **Lock/Release allocation for unsupported asset** The asset you specified in the lock or release allocation call is not supported. Make sure it is a valid and supported asset                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 2202       | 400              | Balance, Private Ledger         | **Lock/Release Allocation for unknown account** The virtual account you specified does not exist. Please make sure you're using a valid virtual account that exists                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 2204       | 400              | Private Ledger, Off-Exchange    | **Allocation not allowed** The vault account you specified does not have off-exchange set up; therefore, locking allocation is not allowed. Make sure you have off-exchange set up and then try again                                                                                                                                                                                                                                                                                                                                                                                                           |
| 2205       | 400              | Private Ledger, Balance         | **Insufficient amount for fee in allocation** The call you're trying to perform requires that a sufficient amount for the fee bank be allocated. The allocation amount you've specified does not meet this demand. Please increase the allocation amount                                                                                                                                                                                                                                                                                                                                                        |
|            |                  |                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 2501       | 400              | Webhooks                        | **Resend webhook for specific tx id failed** Make sure one of the parameters `resendCreated` and `resendUpdated` is marked as true, and try again                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
|            |                  |                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 2602       | 404              | Off-Exchange                    | **Unknown virtual account id** The virtual account ID specified does not exist. Make sure you're using a virtual account ID that exists                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 2604       | 404              | Off-Exchange                    | **Unknown virtual account id** The virtual account ID specified does not exist. Make sure you're using a virtual account ID that exists                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
|            |                  |                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 2702       | 403              | Users                           | **Insufficient permissions for operation** The user who is trying to perform this call does not have sufficient permissions for it. Make sure you're using the correct user and that they have the proper permissions to view the user list                                                                                                                                                                                                                                                                                                                                                                     |
|            |                  |                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 2814       | 400              | Fee Payer                       | **Fee Payer not configured** No fee payer was configured for this workspace. Configure one and try again                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| 2816       | 400              | Fee Payer                       | **Asset wallet does not exist** You've attempted to set a fee payer by specifying a vault account and asset; however, the specified asset does not have a wallet in the specified vault account. Please create a wallet in the specified vault account and fund it, then try again                                                                                                                                                                                                                                                                                                                              |
| 2817       | 400              | Fee Payer                       | **Non-base asset** You've specified a fee payer asset that is not the base asset. This is not allowed. Please specify the base asset and try again                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| 2818       | 400              | Fee Payer                       | **Unsupported asset** You've tried to set a fee payer for an asset that is not supported. Please verify you're using a supported asset and try again                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
|            |                  |                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 2902       | 403              | Audits                          | **Getting audits is not allowed** The user trying to get the audits is not allowed to due so due to a permissions matter. Make sure that the user has the proper permissions and that you're using the correct user                                                                                                                                                                                                                                                                                                                                                                                             |
|            |                  |                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 3001       | 404              | Smart Transfers                 | **Ticket not found** Fireblocks could not find the Smart Transfer ticket.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| 3002       | 403              | Smart Transfers                 | **Ticket should be open** The attempted action can only be performed on an open Smart Transfer ticket.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 3003       | 403              | Smart Transfers                 | **Ticket should be draft** The attempted action can only be performed on a Smart Transfer ticket draft.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 3004       | 403              | Smart Transfers                 | **Ticket should be draft or open** The attempted action can only be performed on an open Smart Transfer ticket or a Smart Transfer ticket draft.                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| 3005       | 403              | Smart Transfers                 | **Ticket action allowed for owner** Only the Smart Transfer ticket creator can perform the attempted action.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 3006       | 403              | Smart Transfers                 | **Ticket cancel can be done by payer** You cannot close the Smart Transfer ticket because the connection has already funded it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 3007       | 403              | Smart Transfers                 | **Ticket terms are missing** You must define all required terms before you can open the Smart Transfer ticket.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 3008       | 403              | Smart Transfers                 | **Ticket expiration date passed** The Smart Transfer ticket has expired.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| 3009       | 400              | Smart Transfers                 | **Term not found** No Smart Transfer ticket term matches your search criteria.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 3010       | 403              | Smart Transfers                 | **Term should be created status** The submitted or updated Smart Transfer ticket term is incorrect.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 3011       | 403              | Smart Transfers                 | **Term should be funded status** Only a funded Smart Transfer ticket can be closed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 3012       | 403              | Smart Transfers                 | **Term should be funding failed status** The attempt to fund the Smart Transfer ticket failed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 3013       | 403              | Smart Transfers                 | **Term amount required** You must enter a term amount before you can open a Smart Transfer ticket.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| 3014       | 403              | Smart Transfers                 | **Term asset required** You must select an asset before you can open a Smart Transfer ticket.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 3015       | 403              | Smart Transfers                 | **Term asset not supported** Fireblocks does not support the selected asset for Smart Transfer tickets.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 3016       | 403              | Smart Transfers                 | **Term from to should be different** The Smart Transfer ticket must include two different connections.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 3017       | 403              | Smart Transfers                 | **Term amount is different than fund amount** The entered fund amount does not match the term amount on the Smart Transfer ticket.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| 3018       | 403              | Smart Transfers                 | **Term asset is different than fund asset** The asset selected for funding does not match the term's asset on the Smart Transfer ticket.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| 3019       | 403              | Smart Transfers                 | **Counterparty not found** Fireblocks could not find the counterparty connection.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| 3020       | 403              | Smart Transfers                 | **Network does not belong to tenant** You can only open a Smart Transfer ticket using a Fireblocks Network profile belonging to you.                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 3021       | 403              | Smart Transfers                 | **Networks not connected** The selected counterparty is not a Fireblocks Network connection.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 3022       | 403              | Smart Transfers                 | **Term should be created or funding failed status** The Smart Transfer ticket has already been funded or is currently being funded.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 3023       | 403              | Smart Transfers                 | **Term transaction can be made by counterparty of term who should pay** Your Fireblocks Network profile cannot fund the Smart Transfer ticket.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 3024       | 403              | Smart Transfers                 | **Network connection does not belong to peers** The Fireblocks Network connection funding the Smart Transfer ticket does not match the connection listed on the term.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| 3025       | 403              | Smart Transfers                 | **Transaction fee and fee level defined** You cannot set a fee level (low, medium, or high) and specify a custom fee at the same time.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 3027       | 403              | Smart Transfers                 | **Tickets can have at most two terms** Smart Transfer tickets can only have two transfer terms.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 3029       | 403              | Smart Transfers                 | **Network doesn't have FF enabled** The Fireblocks Network connection does not use the Smart Transfer feature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 3030       | 400              | Smart Transfers                 | **Ticket missing expire in** You must set an expiration date before you can open a Smart Transfer ticket.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| 3031       | 403              | Smart Transfers                 | **Ticket creator must receive asset** You can only open a Smart Transfer ticket for receiving assets.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| 3101       | 404              | Trading                         | **Provider Not Found** The trading provider you requested does not exist or is not available.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 3102       | 403              | Trading                         | **Terms Approval Not Supported**  This provider does not support terms of service approval.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 3103       | 400              | Trading                         | **On-Chain Swap Required** Both assets must be on the same blockchain network for this trade.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 3104       | 400              | Trading                         | **Cross-Chain Swap Required**  Input and output assets must be on different chains.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 3105       | 400              | Trading                         | **Unsupported Input Blockchain**  The input asset blockchain is not supported by this provider.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 3106       | 400              | Trading                         | **Unsupported Output Blockchain**  The output asset blockchain is not supported by this provider.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| 3107       | 400              | Trading                         | **Unsupported Trading Pair**  Input and output assets pair is not supported with this provider.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 3108       | 400              | Trading                         | **Settlement Required**  This trade requires settlement information to be provided.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 3109       | 400              | Trading                         | **DVP Settlement Source/Destination Invalid**  Source and destination accounts must be of type vault accounts.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 3110       | 400              | Trading                         | **Settlement Pair Invalid**  The source and destination must be the same vault account.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 3111       | 400              | Trading                         | **DeFi Side Not Supported**  DeFi trades only support selling (not buying) at this time.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| 3112       | 400              | Trading                         | **Execution Type Not Supported**  This type of trade execution is not supported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| 3114       | 404              | Trading                         | **Quote Not Available**  No pricing quote is available for this trade at the moment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 3115       | 400              | Trading                         | **Quote Expired**  The price quote has expired or is no longer valid. please try creating a new quote.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 3116       | 404              | Trading                         | **Order Not Found**  The trading order you requested does not exist.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 3117       | 404              | Trading                         | **Source Account Not Found**  The account address required to extract funds was not found.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| 3118       | 404              | Trading                         | **Provider Account Not Found**  The specified provider account was not found.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 3119       | 403              | Trading                         | **Provider Account Not Active**  The specified provider account is not active                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 3120       | 403              | Trading                         | **Terms of Service Approval Required**  You must approve the terms of service before trading with this provider.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| 3121       | 400              | Trading                         | **Quotes Unsupported**  The provider does not support quote operation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 3122       | 403              | Trading                         | **Unmanaged Wallet Approval Required**  Please approve the unmanaged wallet request before sending the Order                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 3123       | 400              | Trading                         | **Rates unsupported**  The provider does not support rate operation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 9001       | 400              | Wallet                          | **Invalid customer reference id** The customer reference ID specified is invalid. Make sure it only consists of `\-\_:a-zA-Z0-9`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| 9003       | 400              | Transaction                     | **Invalid idempotency key length** The idempotency key must be no longer than 40 characters. Please verify that if you've specified one, it has a proper length  **Idempotency key used on internal error request, returning bad request** This operation doesn't support the usage of the same idempotency key after an internal error                                                                                                                                                                                                                                                                         |
| 9004       | 400              | Vault                           | **An existing vault account by the same name already exists** Please try to create a different vault account using a different name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 9005       | 400              | Transaction                     | **A transaction with the same idempotency key is in progress** Please wait until the previous transaction for this idempotency key is done before issuing a new one                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 9006       | 400              | Network Connection              | **Missing required parameter in request body** The request you've sent is missing the `isDiscoverable` parameter in the body, make sure it exists and is a boolean, then try again                                                                                                                                                                                                                                                                                                                                                                                                                              |
| 9007       | 404              | Network Connection              | **Unknown network id** The network ID specified could not be found. Please verify it exists and try again                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| 9009       | 400              | Network Connection              | **Parameters passed are invalid** The parameters passed to the `set_routing_policy` call are invalid, please make sure they are correct and conform to the API docs, then try again                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 11001      | 400              | All                             | **The specified vault account is invalid** Please make sure that the vault account you've specified is correct, valid, and exists                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| 12000      | 400              | All                             | **Cloud provider issue** There is an issue with one of our cloud providers. Please check the  [status page](https://status.fireblocks.com)  for more details                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

## 5XX Error Codes

### 10XX codes

| Error Code | Feature        | Description                                      |
| ---------- | -------------- | ------------------------------------------------ |
| 1001       | Vault          | Get Vault accounts paged failed                  |
| 1003       | Vault          | Create vault account failed                      |
| 1005       | Vault          | Get vault account failed                         |
| 1007       | Asset, Balance | Get balance for vault account and asset failed   |
| 1009       | Wallet, Asset  | Create wallet for asset failed                   |
| 1011       | Wallet         | Adding a new address failed                      |
| 1012       | Wallet         | Getting the addresses for the given asset failed |
| 1014       | Vault          | Renaming a vault account failed                  |
| 1018       | Vault          | Hide vault account failed                        |
| 1021       | Vault          | Unhide vault account failed                      |
| 1029, 1030 | Asset, Balance | Get max spendable amount failed                  |
| 1033       | Asset          | Get balance for assets or specific asset failed  |
| 1036       | Asset          | Fetching max BIP44 index used failed             |

### 11XX codes

| Error Code | Feature            | Description                                                        |
| ---------- | ------------------ | ------------------------------------------------------------------ |
| 1101       | Exchange, Fiat     | Failed to get exchange/fiat accounts                               |
| 1102       | Exchange           | Failed to get exchange account by ID                               |
| 1104       | Exchange           | Failed to get exchange account by ID and asset                     |
| 1107       | Exchange Transfers | Failed to perform an exchange account transfer (internal transfer) |
| 1110       | Exchange Transfers | Convert operation failed                                           |

### 12XX codes

| Error Code | Feature          | Description                                  |
| ---------- | ---------------- | -------------------------------------------- |
| 1201       | Internal Wallets | Failed to get internal wallets               |
| 1202       | Internal Wallets | Failed to create an internal wallet          |
| 1203       | Internal Wallets | Failed to get internal wallet by ID          |
| 1205       | Internal Wallets | Failed to delete internal wallet             |
| 1207       | Internal Wallets | Failed to create an internal wallet by asset |
| 1210       | Internal Wallets | Failed to get wallet by asset and wallet ID  |
| 1211       | Internal Wallets | Failed to delete specific asset from wallet  |

### 13XX codes

| Error Code | Feature          | Description                                  |
| ---------- | ---------------- | -------------------------------------------- |
| 1301       | External Wallets | Failed to get external wallets               |
| 1302       | External Wallets | Failed to create an external wallet          |
| 1303       | External Wallets | Failed to get external wallet by ID          |
| 1305       | External Wallets | Failed to delete an external wallet          |
| 1307       | External Wallets | Failed to create an external wallet by asset |
| 1310       | External Wallets | Failed to get wallet by asset and wallet ID  |
| 1311       | External Wallets | Failed to delete specific asset from wallet  |
| 1350       | External Wallets | Failed to get external wallets               |
| 1352       | External Wallets | Failed to create an external wallet          |
| 1353       | External Wallets | Failed to get external wallet by ID          |
| 1355       | External Wallets | Failed to delete external wallet             |
| 1357       | External Wallets | Failed to create an external wallet by asset |
| 1360       | External Wallets | Failed to get wallet by asset and wallet ID  |
| 1361       | External Wallets | failed to delete specific asset from wallet  |

### 14XX codes

| Error Code | Feature            | Description                                  |
| ---------- | ------------------ | -------------------------------------------- |
| 1404       | Transaction        | Transaction creation or get failed           |
| 1430       | Asset, Transaction | Validate destination address endpoint failed |
| 1436       | Transaction        | List unspent inputs (UTXO) failed            |
| 1444       | Transaction        | Failed to get the transactions list          |
| 1447       | Transaction        | Failed to get transaction by external Tx ID  |

### 15XX codes

| Error Code | Feature | Description                 |
| ---------- | ------- | --------------------------- |
| 1501       | Asset   | Get supported assets failed |

### 17XX codes

| Error Code | Feature       | Description                   |
| ---------- | ------------- | ----------------------------- |
| 1702       | Fiat Accounts | Get fiat account by ID failed |
| 1707       | Fiat Accounts | Redeem funds to DDA failed    |
| 1709       | Fiat Accounts | Deposit funds from DDA failed |

### 19XX codes

| Error Code | Feature            | Description                     |
| ---------- | ------------------ | ------------------------------- |
| 1903       | Asset, Transaction | Estimate fee calculation failed |

### 20XX codes

| Error Code | Feature    | Description                           |
| ---------- | ---------- | ------------------------------------- |
| 2001       | Public Key | Getting public key information failed |

### 21XX codes

| Error Code | Feature                | Description                            |
| ---------- | ---------------------- | -------------------------------------- |
| 2102       | Fireblocks Gas Station | Setting gas station information failed |

### 22XX codes

| Error Code | Feature                 | Description                 |
| ---------- | ----------------------- | --------------------------- |
| 2203       | Balance, Private Ledger | Lock allocation call failed |

### 25XX codes

| Error Code | Feature | Description           |
| ---------- | ------- | --------------------- |
| 2501       | Webhook | Resend webhook failed |

### 26XX codes

| Error Code | Feature      | Description                                                   |
| ---------- | ------------ | ------------------------------------------------------------- |
| 2601       | Off-Exchange | Get off-exchange failed                                       |
| 2603       | Off-Exchange | Couldn't settle off-exchange with provided virtual account ID |
| 2605       | Off-Exchange | Failed to get off-exchange with specified ID                  |

### 27XX codes

| Error Code | Feature | Description                       |
| ---------- | ------- | --------------------------------- |
| 2701       | Users   | Failed to get users for workspace |

### 28XX codes

| Error Code | Feature   | Description                                 |
| ---------- | --------- | ------------------------------------------- |
| 2813       | Fee Payer | Failed to get fee payer                     |
| 2815       | Fee Payer | Setting the fee payer failed                |
| 2819       | Fee Payer | Deleting the fee payer configuration failed |

### 29XX codes

| Error Code | Feature | Description          |
| ---------- | ------- | -------------------- |
| 2901       | Audits  | Failed to get audits |


# API Idempotency
Source: https://developers.fireblocks.com/reference/api-idempotency



The Fireblocks API supports idempotent requests (multiple requests which have the same result as making a single request). This is helpful when you don’t get a response or the API call isn’t completed successfully.

## Idempotency key

> **Notes**
>
> * You can use idempotency keys with **POST** requests. Using `Idempotency-Key` in your request header for **GET** and **DELETE** will not work as they are inherently idempotent.
> * The \`\` value in your idempotent request can have a maximum of 40 characters.

To submit an idempotent request, you must add `Idempotency-Key: ` to the header of your POST request.
Resubmission of the same request with the same idempotency key will not trigger the same operation, but will instead return the original response. This ensures a transaction request with the same idempotency key is not executed multiple times if you try to re-submit it due to network errors or delays experienced for a prior submission.
Fireblocks stores the responses for all requests with the `Idempotency-Key` header and resends them for every request with the same idempotency key for 24 hours. After 24 hours, you will need a new key.

## Transaction Idempotency

When creating transactions, Fireblocks strongly recommends using the `externalTxId` parameter in the [Create Transaction API](/reference/create-transactions) call. This parameter ensures that the transaction is idempotent. If another transaction request is made with the same `externalTxId` value, it will be rejected with an HTTP 400 code an [error message](/reference/api-responses#:~:text=for%20Kraken%20exchange-,1438,-400) .
Learn more about the `externalTxId` parameter [here](/docs/manage-withdrawals-at-scale#idempotent-transactions)


# API Overview
Source: https://developers.fireblocks.com/reference/api-overview



## REST API

Fireblocks offers a robust REST API that enables developers to leverage Fireblocks' capabilities programmatically. Our REST API serves as the foundation for all Fireblocks SDKs.

If you prefer to work directly with the Fireblocks API, read our [REST API Guide](/reference/rest-api-guide-1).

To practice with our API before implementing any code, read the [Postman Guide](/reference/explore-postman-collection) containing the pre-defined API endpoints.

## Language-specific SDKs & guides

Fireblocks supports and maintains SDKs in JavaScript and Python to help you interact with the Fireblocks API. We also offer guides for languages in which we don't have an active SDK.

These guides provide you with a simple example to get you started and quickly pass the first hurdles of securely signing API requests:

* [Typescript SDK](/reference/typescript-sdk)
* [Python SDK](/reference/new-python-sdk)
* [Java SDK](/reference/java-sdk)

## Need help deciding which language to use?

Use the following decision tree to help you decide which Fireblocks SDK is best for your use case.

<img alt="" />

# Web3/Smart Contract

Fireblocks offers Web3 connector SDKs for developers who use a base library as part of their tech stack and want Fireblocks to act as the underlying wallet and security layer:

* [EVM Web3 Provider](/reference/evm-web3-provider): Learn about using `ethers.js`, `web3.js` or `web3.py` with Fireblocks as the Web3 Provider.

# Additional Tools

* [Fireblocks Hardhat Plugin](https://github.com/fireblocks/hardhat-fireblocks) - An easy-to-use plugin to enable Fireblocks signing for smart contract deployment using Hardhat. More information at [Fireblocks Hardhat plugin guide](/reference/hardhat-plugin).
* [Fireblocks Local JSON RPC](https://github.com/fireblocks/fireblocks-json-rpc) - A locally running EVM JSON RPC module that uses the Web3 Provider to use Fireblocks as the signing mechanism. This allows you to plug Fireblocks into any of the tools that require a JSON RPC URL, including different development and deployment tools. More information at [Fireblocks Local JSON RPC Guide](/reference/evm-local-json-rpc).

# Webhooks

Webhook notifications allow you to get push notifications for events that happen in your Fireblocks workspace directly to an HTTP webhook URL of your choice. This saves you the need to constantly check the API for updates.

Read more at [Configure Webhooks](/reference/configure-webhook-urls).


# Approve configuration changes
Source: https://developers.fireblocks.com/reference/approve-configuration-changes



## Configuration Approval Callback

`POST /v2/config_change_sign_request`

This request expects a [CallbackResponse](/reference/response-object) object from the callback handler. If the callback handler does not respond within 30 seconds, Fireblocks fails the request. If your callback handler can't respond within 30 seconds, you can use the [retry mechanism](/reference/response-object) by responding with `RETRY`.

***

## Request parameters

| Parameter | Type   | Description                                                                                                                                                                                                                                                                                                                                         |
| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| requestId | string | A unique identifier of this request. It must be returned in the response.                                                                                                                                                                                                                                                                           |
| type      | string | The type of configuration request:  `UNMANAGED_WALLET`, `EXCHANGE`, `POLICY_APPROVAL`,`FIAT_ACCOUNT`, `ADD_USER`, `RE_ENROLL_DEVICE`, `ENABLE_ONE_TIME_ADDRESS`, `CHANGE_QUORUM_THRESHOLD`, `ADD_NETWORK_CONNECTION`, `SET_NETWORK_CONNECTION_ROUTING_POLICY`, `SET_NETWORK_ID_POLICY`, `UPDATE_APPROVAL_GROUP_MAPPING`, and `USERS_GROUP_APPROVAL` |
| extraInfo | object | Additional information about the request, depending on the type:  For `UNMANAGED_WALLET`, this is an [AddressInfo](#addressinfo) object.  For `EXCHANGE` or `FIAT_ACCOUNT`, this is a [ThirdPartyInfo](#thirdpartyinfo) object.                                                                                                                     |

***

## Type descriptions

| Type                                      | Description                                                                                        |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------- |
| UNMANAGED\_WALLET                         | An event that involves address whitelisting                                                        |
| EXCHANGE                                  | An event that involves adding an exchange to your workspace                                        |
| FIAT\_ACCOUNT                             | An event which involves adding a Fiat account to your workspace                                    |
| ADD\_USER                                 | An event that involves adding a user to your workspace                                             |
| RE\_ENROLL\_DEVICE                        | An event where an admin re-enrolls a mobile device for one of the users                            |
| ENABLE\_ONE\_TIME\_ADDRESS                | An event which involves enabling a particular transaction to a one-time address in the workspace   |
| CHANGE\_QUORUM\_THRESHOLD                 | An event where the admin updates the quorum threshold                                              |
| ADD\_NETWORK\_CONNECTION                  | An event of adding a Fireblocks Network new connection                                             |
| SET\_NETWORK\_CONNECTION\_ROUTING\_POLICY | An event where the admin configures the routing policy for each network connection                 |
| SET\_NETWORK\_ID\_POLICY                  | An event of setting up the Fireblocks Network *Network ID* in case its profile is not discoverable |
| UPDATE\_APPROVAL\_GROUP\_MAPPING          | An event involving gathering a list of approvers for a particular admin operation                  |
| USERS\_GROUP\_APPROVAL                    | An event that involves approving a new user group in your workspace                                |
| POLICY\_APPROVAL                          | An event that involves updating the Transaction Authorization Policy                               |

***

## Data objects

### AddressInfo

The AddressInfo object contains additional information for whitelisting a destination address.

| Parameter  | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ---------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| subType    | string | `INTERNAL` - Internal Wallets are addresses you control outside your Fireblocks workspace. Internal addresses display their current balance and are included in your workspace's total billable address count.  `EXTERNAL` - External Wallets are addresses managed by your clients and counterparties.  `CONTRACT` - Contract Wallets are addresses of smart contracts you want to interact with. Currently, this only applies to smart contracts on EVM-compatible blockchains. |
| walletName | string | The name of the internal, external, or contract wallet you want to approve adding an address to.                                                                                                                                                                                                                                                                                                                                                                                  |
| walletId   | string | The ID of the internal, external, or contract wallet that you want to approve adding an address to.                                                                                                                                                                                                                                                                                                                                                                               |
| asset      | string | The ID of the asset to add to this wallet. Use [GET supported assets](/api-reference/blockchains-&-assets/list-assets-legacy) request to retrieve more information about an asset.                                                                                                                                                                                                                                                                                                |
| address    | string | The asset deposit address requested to be added to the wallet.                                                                                                                                                                                                                                                                                                                                                                                                                    |
| tag        | string | Destination address tag for Ripple; destination memo for EOS, Stellar, Hedera, & DigitalBits; destination note for Algorand; bank transfer description for fiat providers.   - *Note:*\* For Stellar, the memo must be a string representation of an integer between “0” and “2147483647”. Setting the memo to other values for Stellar assets will result in a failed request with an error message.                                                                             |

### ThirdPartyInfo

| Parameter   | Type   | Description                                                                                                                                                                                                                                                        |
| ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| subType     | string | The exchange account, fiat account, or unmanaged wallet (INTERNAL, EXTERNAL).                                                                                                                                                                                      |
| accountName | string | The account's name.                                                                                                                                                                                                                                                |
| accountId   | string | The account's ID.                                                                                                                                                                                                                                                  |
| apiKey      | string | The third-party service's API key.                                                                                                                                                                                                                                 |
| addresses   | string | (Optional) A JSON-formatted "key":"value" string, where "key" is an asset symbol and "value" is its address. There can be multiple entries in the JSON. Use [supported\_assets](/api-reference/blockchains-&-assets/list-assets-legacy) to retrieve asset symbols. |

### AddNetworkConnection

| Parameter           | Type   | Description                                  |
| ------------------- | ------ | -------------------------------------------- |
| networkConnectionId | string | ID of network connection                     |
| note                | string | Connection note                              |
| localNetworkID      | string | ID of local networkId                        |
| remoteTenantID      | string | ID of remote peer tenantId                   |
| routingPolicy       | string | JSON representation of routing policy object |

### NetworkConnectionRoutingPolicy

| Parameter     | Type   | Description                                  |
| ------------- | ------ | -------------------------------------------- |
| connectionId  | string | ID of network connection                     |
| routingPolicy | string | JSON representation of routing policy object |

### NetworkIdRoutingPolicy

| Parameter     | Type   | Description                                  |
| ------------- | ------ | -------------------------------------------- |
| networkID     | string | ID of networkID                              |
| routingPolicy | string | JSON representation of routing policy object |


# Approve transactions
Source: https://developers.fireblocks.com/reference/approve-transactions



## Transaction Signing Callback Handler

`POST /v2/tx_sign_request`

This request is used for transaction signing and approval and expects a [CallbackResponse](/reference/response-object) object from the callback handler. If the callback handler does not respond within 30 seconds, Fireblocks fails the request. If your callback handler can't respond within 30 seconds, you can use the [retry mechanism](/reference/response-object) by responding with `RETRY`.

If both approval and signing are requested for a transaction, one callback handles both requests.

To differentiate whether this request is for signing, approving, or both, these parameters are included only with signing requests:

* `fee`
* `displayDstAddress` within the transaction's [destinations array](#TransactionRequestCallbackDestination)

***

## Request parameters

| Parameter                    | Type           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ---------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| txId                         | string         | The transaction's internal ID in Fireblocks.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| operation                    | string         | The [transaction operation](#transactionoperation) type. The default is `TRANSFER`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| sourceType                   | string         | The [source](/reference/transaction-sources-destinations) of the transaction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| sourceId                     | string         | The transaction’s source vault account ID or exchange account UUID.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| destType                     | string         | The transaction's destination type. The type can be VAULT, EXCHANGE, ONE\_TIME, or UNMANAGED.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| destId                       | string         | The destination's vault account ID or exchange account UUID.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| asset                        | string         | The asset ID in Fireblocks.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| amount (Deprecated)          | number         | Use the **amountStr** field for accuracy. If the transfer is a withdrawal from an exchange, the actual transfer amount. Otherwise, the requested amount.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| amountStr                    | string         | The amount of the transfer in string format.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| requestedAmount (Deprecated) | number         | Use the **requestedAmountStr** field for accuracy. The requested transfer amount. In gross transactions, transaction fees are deducted from this amount.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| requestedAmountStr           | string         | The requested transfer amount in string format. In gross transactions, transaction fees are deducted from this amount.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| fee                          | string         | (Optional) The transaction's estimated fee.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| destAddressType              | string         | The destination's address type. For one-time addresses on EVM-compatible blockchains, this is the smart contract address.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| destAddress                  | string         | The destination address of the transaction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| destinations                 | array          | An array of [TransactionRequestCallbackDestination](#transactionrequestcallbackdestination) objects with all details for all destination(s).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| players                      | array (string) | A list of the Co-signers that signed the transaction. (Two Fireblocks SaaS and at least one user device or one API Co-signer). Each signer is represented by a Device ID.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| requestId                    | string         | A unique identifier of this request is returned in the response.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| signerId                     | string         | The user that signed the transaction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| extraParameters              | object         | (Optional) Parameters that are specific to some transaction operation types and blockchain networks. Learn more [below](#transactionextraparameters).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| note                         | string         | (Optional) Custom note that describes this transaction in your Fireblocks workspace. The note isn’t sent to the blockchain.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| rawTx                        | array          | An array of [RawTX](#rawtx). Contains a list of the actual transaction payload sent to the blockchain. Note that some signing requests represent multiple transactions. When this occurs, the list contains more than one object. This parameter is not included in the CallbackResponse object when using a Fireblocks EU cloud environment.  This field is included for the following blockchains: ADA, BTC, DASH, DOGE, LTC, BSV, BCH, XEC, ZEC, EVMs, all Cosmos based chains, SOL, XLM, XTZ, TRX, NEAR, XRP and TON.  This is an opt-in feature. Please contact [Fireblocks Support](https://support.fireblocks.io/hc/en-us/requests/new) to include this feature in your workspace.  **Note:** This field appears only for the signing stage of a transaction, and not during the approval stage. |
| externalTxId                 | string         | An optional but highly recommended parameter. Fireblocks will reject future transactions with same ID.  You should set this to a unique ID representing the transaction, to avoid submitting the same transaction twice. This helps with cases where submitting the transaction responds with an error code due to Internet interruptions, but the transaction was actually sent and processed. To validate whether a transaction has been processed, Find a specific transaction by external transaction ID.  There is no specific format required for this parameter.                                                                                                                                                                                                                                 |
| action (deprecated)          | object         | Includes information about the transaction authorization policy rule that matched this transaction. This field and its contents are not officially supported or maintained. Fireblocks may delete or change the contents of this field at any time.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

***

## TransactionOperation

| Parameter | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| operation | string | `TRANSFER`: Default. Transfers funds from one account to another. UTXO blockchains allow multi-input and multi-output transfers. All other blockchains allow transfers with one source address and one destination address.  `MINT`: Mints new tokens. Supported for Stellar, Ripple, and EVM-based blockchains.  `BURN`: Burns tokens. Supported for Stellar, Ripple, and EVM-based blockchains.  `CONTRACT_CALL`: Calls a smart contract method for web3 operations on any EVM blockchain. The [Fireblocks development libraries](/reference/evm-web3-provider#convenience-libraries) are recommended for building contract call transactions.  `TYPED_MESSAGE`: An off-chain message in either Ethereum Personal Message or EIP712 format. Use it to sign specific readable messages that are not actual transactions. [Learn more about typed messages](/docs/typed-message-signing-1).  `RAW`: An off-chain message with no predefined format. Use it to sign any message with your private key, including protocols such as blockchains and custom transaction types that are not natively supported by Fireblocks. [Learn more about raw signing transactions](/docs/raw-signing).  `ENABLE_ASSET`: Algorand, DigitalBits, Solana, and Stellar require an on-chain transaction to create an asset wallet and enable the deposit address. This transaction is automatically created when adding assets on these blockchains to a vault account.  `STAKE`: Assign assets to a staking pool managed by a staking validator. [Learn more about staking transactions and supported blockchains](/reference/staking-overview). This transaction is automatically created when performing staking operations.  `UNSTAKE`: Remove assets from a staking pool managed by a staking validator. [Learn more about staking transactions and supported blockchains](/reference/staking-overview). This transaction is automatically created when performing staking operations.  `WITHDRAW`: Transfer assets from a dedicated staking vault account to another address. [Learn more about staking transactions and supported blockchains](/reference/staking-overview). This transaction is automatically created when performing staking operations.  **Note:** Fireblocks will rename `WITHDRAW` to a different name soon. There will be at minimum a 7-day notice regarding the new type name. |

### TransactionExtraParameters

| Parameter        | Type                                                                     | Description                                                                                                                                                                                                                                                                                                     |
| ---------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| inputsSelection  | [InputsSelection object](/reference/transaction-objects#inputsselection) | For UTXO-based blockchain multi-input selection, use the `inputsSelection` field with values set to the input selection structure. The inputs can be retrieved using the Retrieve Unspent Inputs endpoint.                                                                                                      |
| rawMessageData   | [RawMessageData object](/reference/raw-signing-objects#rawmessagedata)   | For `RAW` operations, use the rawMessageData field with the values set to the raw message data structure.                                                                                                                                                                                                       |
| contractCallData | string                                                                   | For `CONTRACT_CALL` operations, use the contractCallData field with the value set to the Ethereum smart contract Application Binary Interface (ABI) payload. The [Fireblocks development libraries](/reference/evm-web3-provider#convenience-libraries) are recommended for building contract call transactions |

***

## TransactionRequestCallbackDestination

| Parameter         | Type                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ----------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| amountNative      | number                   | Deprecated. The amount transferred to this destination as a number. Use the amountNativeStr parameter for accurate precision.                                                                                                                                                                                                                                                                                                                                                                                              |
| amountNativeStr   | string                   | The amount transferred to this destination represented as a string.                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| amountUSD         | number                   | The USD value of the transfer to this destination.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| dstAddressType    | WHITELISTED or ONE\_TIME | `WHITELISTED` or `ONE_TIME`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| dstId             | string                   | The ID of the destination.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| dstName           | string                   | The name of the destination.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| dstSubType        | string                   | The specific exchange, fiat account, or unmanaged wallet.  For exchange accounts: `BINANCE`, `BINANCEUS`, `BITFINEX`, `BITHUMB`, `BITMEX`, `BITSO`, `BITSTAMP`, `BITTREX`, `BYBIT`, `CIRCLE`, `COINBASEEXCHANGE`, `COINBASEPRO`, `COINMETRO`, `COINSPRO`, `CRYPTOCOM`, `DERIBIT`, `GEMINI`, `HITBTC`, `HUOBI`, `INDEPENDENTRESERVE`, `KORBIT`, `KRAKEN`, `KRAKENINTL`, `KUCOIN`, `LIQUID`, `OKCOIN`, `OKEX`, `PAXOS`, `POLONIEX`  For fiat accounts: `BLINC`  For unmanaged wallets: `INTERNAL`, `EXTERNAL`, or `CONTRACT` |
| dstType           | string                   | The destination of the transaction: `VAULT`, `EXCHANGE_ACCOUNT`, `FIAT_ACCOUNT`, or `UNMANAGED`.                                                                                                                                                                                                                                                                                                                                                                                                                           |
| displayDstAddress | string                   | The address of this specific destination                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| action            | string                   | Includes information about the Transaction Authorization Policy rule that matched this transaction.                                                                                                                                                                                                                                                                                                                                                                                                                        |

***

## RawTX

| Parameter         | Type   | Description                                                                                                                                                                                            |
| ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| rawTx             | string | Hex-encoded details of a transaction sent to the blockchain                                                                                                                                            |
| keyDerivationPath | string | Location of the encryption key within the customer’s [HD Wallet URL](https://support.fireblocks.io/hc/en-us/articles/360014330819-Fireblocks-Vault-HD-Derivation-Paths) used to sign this transaction. |

***


# Audit Log Events
Source: https://developers.fireblocks.com/reference/audit-log-events



<br />

# Overview

This page includes all Audit Log events and associated parameters. Sections are organized by Category.

# Administration

| Event ID                                                   | Subject                 | Event                        | Notification Subject                                                 |
| ---------------------------------------------------------- | ----------------------- | ---------------------------- | -------------------------------------------------------------------- |
| `EventId.ApiIpWhitelisting_ListUpdated`                    | Whitelisted IP          | List updated                 | API IP Whitelisting List Updated                                     |
| `EventId.AdminQuorum_ApprovedByAdmin`                      | Quorum                  | Approved                     | Admin Quorum Approved by admin                                       |
| `EventId.AdminQuorum_Cancelled`                            | Quorum                  | Canceled                     | Admin Quorum Cancelled                                               |
| `EventId.AdminQuorum_Rejected`                             | Quorum                  | Rejected                     | Admin Quorum Rejected                                                |
| `EventId.AdminQuorum_RequestSubmitted`                     | Quorum                  | Submitted request            | Admin Quorum Request Submitted                                       |
| `EventId.AdminQuorum_ThresholdChanged`                     | Quorum                  | Changed threshold            | Admin Quorum Threshold Changed                                       |
| `EventId.Authentication_LoginFailed`                       | Sign in                 | Failed                       | Authentication Login Failed                                          |
| `EventId.Authentication_PasswordChangeRequested`           | Sign in                 | Requested password change    | Authentication Password Change Requested                             |
| `EventId.Authentication_PasswordChanged`                   | Sign in                 | Changed password             | Authentication Password Changed                                      |
| `EventId.Authentication_2faReset`                          | Sign in                 | Reset 2FA                    | Authentication 2FA reset                                             |
| `EventId.DeviceRecover_Completed`                          | Device recovery         | Completed                    | Device Recover Completed                                             |
| `EventId.DeviceReset_ApprovedByAdmin`                      | Device reset            | Approved                     | Device Reset Approved by admin                                       |
| `EventId.DeviceReset_DeviceRecover`                        | Device reset            | Recovered                    | Device Reset Device Recover                                          |
| `EventId.DeviceReset_DeviceReset`                          | Device reset            | Completed                    | Device Reset Device Reset                                            |
| `EventId.DeviceReset_Rejected`                             | Device reset            | Rejected                     | Device Reset Rejected                                                |
| `EventId.DeviceReset_RequestSubmitted`                     | Device reset            | Submitted request            | Device Reset Request submitted                                       |
| `EventId.EditUser_ApprovedByAdmin`                         | Edit user               | Approved                     | Edit User Approved by admin                                          |
| `EventId.EditUser_Cancelled`                               | Edit user               | Canceled                     | Edit User Cancelled                                                  |
| `EventId.EditUser_EditRequestSubmitted`                    | Edit user               | Submitted request            | Edit User Edit request submitted                                     |
| `EventId.EditUser_EditRequestImplemented`                  | Edit user               | Edit request implemented     |                                                                      |
| `EventId.EditUser_Rejected`                                | Edit user               | Rejected                     | Edit User Rejected                                                   |
| `EventId.NewUserApproval_ApprovedByAdmin`                  | New user                | Approved                     | New User Approval Approved by admin                                  |
| `EventId.NewUserApproval_Cancelled`                        | New user                | Canceled                     | New User Approval Cancelled                                          |
| `EventId.NewUserApproval_Rejected`                         | New user                | Rejected                     | New User Approval Rejected                                           |
| `EventId.NewUserApproval_RequestSubmitted`                 | New user                | Submitted request            | New User Approval Request submitted                                  |
| `EventId.OneTimeAddress_ApprovedByAdmin`                   | One-time address        | Approved                     | One-time Address Approved by admin                                   |
| `EventId.OneTimeAddress_Cancelled`                         | One-time address        | Canceled                     | One-time Address Cancelled                                           |
| `EventId.OneTimeAddress_Rejected`                          | One-time address        | Rejected                     | One-time Address Rejected                                            |
| `EventId.OneTimeAddress_RequestSubmitted`                  | One-time address        | Submitted request            | One-time Address Request Submitted                                   |
| `EventId.OneTimeAddress_ToggledOff`                        | One-time address        | Turned off                   | One-time Address Toggled off                                         |
| `EventId.OneTimeAddress_ToggledOn`                         | One-time address        | Turned on                    | One-time Address Toggled on                                          |
| `EventId.ReEnrollDevice_ApprovedByAdmin`                   | Re-enroll mobile device | Approved                     | Re-enroll Device Approved by admin                                   |
| `EventId.ReEnrollDevice_Cancelled`                         | Re-enroll mobile device | Canceled                     | Re-enroll Device Cancelled                                           |
| `EventId.ReEnrollDevice_Completed`                         | Re-enroll mobile device | Completed                    | Re-enroll Device Completed                                           |
| `EventId.ReEnrollDevice_DeviceReEnrollmentCompleted`       | Re-enroll mobile device | Completed                    | Re-enroll Device Device Re-enrollment Completed                      |
| `EventId.ReEnrollDevice_DeviceRecover`                     | Re-enroll mobile device | Recovered                    | Re-enroll Device Device Recover                                      |
| `EventId.ReEnrollDevice_Rejected`                          | Re-enroll mobile device | Rejected                     | Re-enroll Device Rejected                                            |
| `EventId.ReEnrollDevice_RequestSubmitted`                  | Re-enroll mobile device | Submitted request            | Re-enroll Device Request Submitted                                   |
| `EventId.User_Deleted`                                     | User                    | Deleted                      | User Deleted                                                         |
| `EventId.User_LoggedIn`                                    | User                    | Signed in                    | User Logged In                                                       |
| `EventId.User_AccessDenied`                                | User                    | Access denied                | User Access denied                                                   |
| `EventId.UserGroups_ChangesApprovedByAdmin`                | User group              | Changes approved             | User Groups Active group changes request was approved by admin       |
| `EventId.UserGroups_ChangesRequestRejected`                | User group              | Changes rejected             | User Groups Active group changes request was rejected                |
| `EventId.UserGroups_ChangesWentIntoAffect`                 | User group              | Changes in effect            | User Groups Active group changes went into affect                    |
| `EventId.UserGroups_EditRequestImplemented`                | User group              | Edited                       | User Groups Edit request implemented                                 |
| `EventId.UserGroups_NewGroupApprovedAndCreated`            | User group              | Approved and created         | User Groups New group approved and created                           |
| `EventId.UserGroups_NewGroupRequestWasApprovedByAdmin`     | User group              | Approved                     | User Groups New group request was approved by admin                  |
| `EventId.UserGroups_NewGroupRequestWasRejected`            | User group              | Rejected                     | User Groups New group request was rejected                           |
| `EventId.UserGroups_UserCanceledActiveGroupChangesRequest` | User group              | Canceled change request      | User Groups User canceled active group changes request               |
| `EventId.UserGroups_UserDeletedAGroup`                     | User group              | Deleted                      | User Groups User deleted a group                                     |
| `EventId.UserGroups_UserDiscardedActiveGroupEditing`       | User group              | Discarded edits (DEPRECATED) | User Groups User discarded active group editing                      |
| `EventId.UserGroups_UserStartedEditingActiveGroup`         | User group              | Edited (DEPRECATED)          | User Groups User started editing active group                        |
| `EventId.UserGroups_SubmittedApprovalRequestGroupChanges`  | User group              | Requested change approval    | User Groups User submitted approval request for active group changes |
| `EventId.UserGroups_UserSubmittedNewGroupForApproval`      | User group              | Created                      | User Groups User submitted new group for approval                    |
| `EventId.UserManagement_DeviceRecover`                     | User                    | Recovered mobile device      | User Management Device Recover                                       |
| `EventId.UserManagement_DeviceReset`                       | User                    | Reset mobile device          | User Management Device Reset                                         |
| `EventId.UserManagement_Disabled`                          | User                    | Deactivated                  | User Management Disabled                                             |
| `EventId.UserManagement_RoleChanged`                       | User                    | Changed role                 | User Management Role Changed                                         |
| `EventId.LinkedUserMigration_InitiatedByUser`              | Linked user migration   | Initiated by user            | Linked user migration Initiated by user                              |
| `EventId.LinkedUserMigration_UserPairedSuccessfully`       | Linked user migration   | User paired successfully     | Linked user migration User paired successfully                       |
| `EventId.LinkedUserMigration_Activated`                    | Linked user migration   | Activated                    | Linked user migration Activated                                      |
| `EventId.LinkedUserMigration_Deactivated`                  | Linked user migration   | Deactivated                  | Linked user migration Deactivated                                    |
| `EventId.Notifications_EmailCreated`                       | Email Notification      | Created                      |                                                                      |
| `EventId.Notifications_EmailEnabled`                       | Email Notification      | Enabled                      |                                                                      |
| `EventId.Notifications_EmailDisabled`                      | Email Notification      | Disabled                     |                                                                      |
| `EventId.Notifications_EmailEdited`                        | Email Notification      | Edited                       |                                                                      |
| `EventId.Notifications_SlackCreated`                       | Slack Notification      | Created                      |                                                                      |
| `EventId.Notifications_SlackEnabled`                       | Slack Notification      | Enabled                      |                                                                      |
| `EventId.Notifications_SlackDisabled`                      | Slack Notification      | Disabled                     |                                                                      |
| `EventId.Notifications_SlackEdited`                        | Slack Notification      | Edited                       |                                                                      |
| `EventId.Notifications_WebhooksCreated`                    | Webhooks Notification   | Created                      |                                                                      |
| `EventId.Notifications_WebhooksEnabled`                    | Webhooks Notification   | Enabled                      |                                                                      |
| `EventId.Notifications_WebhooksDisabled`                   | Webhooks Notification   | Disabled                     |                                                                      |
| `EventId.Notifications_WebhooksEdited`                     | Webhooks Notification   | Edited                       |                                                                      |
| `EventId.Notifications_WebhooksDeleted`                    | Webhooks Notification   | Deleted                      |                                                                      |

# Assets

| Event ID                 | Subject | Event     | Notification Subject |
| ------------------------ | ------- | --------- | -------------------- |
| `EventId.Asset_Listed`   | Asset   | Listed    | Asset Listed         |
| `EventId.Asset_SetPrice` | Asset   | Set price | Asset Set price      |

# Automation

| Event ID                              | Event         | Subject         | Notification Subject          |
| ------------------------------------- | ------------- | --------------- | ----------------------------- |
| `EventId.AutomationRule_RuleCreated`  | Rule Created  | Automation Rule | Automation Rule Rule Created  |
| `EventId.AutomationRule_RuleEdited`   | Rule Edited   | Automation Rule | Automation Rule Rule Edited   |
| `EventId.AutomationRule_RuleEnabled`  | Rule Enabled  | Automation Rule | Automation Rule Rule Enabled  |
| `EventId.AutomationRule_RuleDisabled` | Rule Disabled | Automation Rule | Automation Rule Rule Disabled |
| `EventId.AutomationRule_RuleDeleted`  | Rule Deleted  | Automation Rule | Automation Rule Rule Deleted  |

# Compliance

| Event ID                                                 | Subject    | Event Description                      | Notification Subject                                                       |
| -------------------------------------------------------- | ---------- | -------------------------------------- | -------------------------------------------------------------------------- |
| `EventId.Transaction_AmlRegistrationComplated`           | Compliance | AML registration completed             | Transaction AML Registration complated                                     |
| `EventId.Transaction_AmlRegistrationStarted`             | Compliance | AML registration initiated             | Transaction AML Registration started                                       |
| `EventId.Transaction_AmlScreeningCompleted`              | Compliance | AML screening completed                | Transaction AML screening completed                                        |
| `EventId.Transaction_AmlScreeningFailed`                 | Compliance | AML screening failed                   | Transaction AML screening failed                                           |
| `EventId.Transaction_AmlScreeningInBackground`           | Compliance | AML screening in background            | Transaction AML screening in background                                    |
| `EventId.Transaction_AmlScreeningStarted`                | Compliance | AML screening initiated                | Transaction AML screening started                                          |
| `EventId.Transaction_ScreeningCompleted`                 | Compliance | Screening completed                    | Transaction Screening completed                                            |
| `EventId.Transaction_ScreeningStarted`                   | Compliance | Screening initiated                    | Transaction Screening Started                                              |
| `EventId.Transaction_ScreeningUpdateCompleted`           | Compliance | Screening update completed             | Transaction Screening update completed                                     |
| `EventId.Transaction_TravelRuleScreeningCompleted`       | Compliance | Travel rule screening completed        | Transaction Travel Rule screening completed                                |
| `EventId.Transaction_TravelRuleScreeningFailed`          | Compliance | Travel rule screening failed           | Transaction Travel Rule screening failed'                                  |
| `EventId.Transaction_TravelRuleScreeningStarted`         | Compliance | Travel rule screening initiated        | Transaction Travel Rule screening started', 'Travel Rule screening started |
| `EventId.Transaction_TravelRuleScreeningUpdateCompleted` | Compliance | Travel rule screening update completed | Transaction Travel Rule screening update completed                         |
| `EventId.Transaction_TravelRuleScreeningUpdateStarted`   | Compliance | Travel rule screening update initiated | Transaction Travel Rule screening update started                           |

# Developers

| Event ID                    | Subject          | Event                | Notification Subject      |
| --------------------------- | ---------------- | -------------------- | ------------------------- |
| `WebhookUrls_ListUpdated`   | Webhooks         | Updated URLs         | Webhook URLs List Updated |
| `Webhook_Added`             | Webhook endpoint | Added                |                           |
| `Webhook_Deleted`           | Webhook endpoint | Deleted              |                           |
| `Webhook_Activated`         | Webhook endpoint | Activated            |                           |
| `Webhook_Deactivated`       | Webhook endpoint | Deactivated          |                           |
| `Webhook_Updated`           | Webhook endpoint | Updated              |                           |
| `Webhook_Suspended`         | Webhook endpoint | Suspended            |                           |
| `Webhook_Suspended_Warning` | Webhook endpoint | Suspend warning sent |                           |

# Exchanges

| Event ID                                            | Subject          | Event     | Notification Subject                          |
| --------------------------------------------------- | ---------------- | --------- | --------------------------------------------- |
| `EventId.ExchangeConnection_Added`                  | Exchange account | Linked    | Exchange Connection Added                     |
| `EventId.ExchangeConnection_Removed`                | Exchange account | Unlinked  | Exchange Connection Removed                   |
| `EventId.ExchangeConnectionRequest_ApprovedByAdmin` | Exchange account | Approved  | Exchange Connection Request Approved by admin |
| `EventId.ExchangeConnectionRequest_Cancelled`       | Exchange account | Canceled  | Exchange Connection Request Cancelled         |
| `EventId.ExchangeConnectionRequest_Rejected`        | Exchange account | Rejected  | Exchange Connection Request Rejected          |
| `EventId.ExchangeConnectionRequest_Submitted`       | Exchange account | Submitted | Exchange Connection Request Submitted         |
| `EventId.FiatConnectionRequest_ApprovedByAdmin`     | Fiat account     | Approved  | FIAT Connection Request Approved by admin     |
| `EventId.FiatConnectionRequest_Rejected`            | Fiat account     | Rejected  | FIAT Connection Request Rejected              |
| `EventId.FiatConnectionRequest_Submitted`           | Fiat account     | Submitted | FIAT Connection Request Submitted             |
| `EventId.FiatConnectionRequest_Cancelled`           | Fiat account     | Canceled  | FIAT Connection Request Cancelled             |
| `EventId.FiatConnection_Added`                      | Fiat account     | Linked    | FIAT connection Added                         |
| `EventId.FiatConnection_Removed`                    | Fiat account     | Unlinked  | FIAT connection Removed                       |

# Keys

| Event ID                           | Subject        | Event                     | Notification Subject                  |
| ---------------------------------- | -------------- | ------------------------- | ------------------------------------- |
| ValidationKey\_SubmittedRequest    | Validation key | Submitted request         | Validation key Submitted request      |
| ValidationKey\_Approved            | Validation key | Approved                  | Validation key Approved               |
| ValidationKey\_Rejected            | Validation key | Rejected                  | Validation key Rejected               |
| ValidationKey\_Activated           | Validation key | Activated                 | Validation key Activated              |
| ValidationKey\_Deactivated         | Validation key | Deactivated               | Validation key Deactivated            |
| SigningKey\_SubmittedRequest       | Signing key    | Submitted request         | Signing key Submitted request         |
| SigningKey\_LinkedToUser           | Signing key    | Linked to user            | Signing key Linked to user            |
| SigningKey\_Enabled                | Signing key    | Enabled                   | Signing key Enabled                   |
| SigningKey\_AssignedToVaultAccount | Signing key    | Assigned to vault account | Signing key Assigned to vault account |
| SigningKey\_Deleted                | Signing key    | Deleted                   | Signing key Deleted                   |
| MPCKeySet\_Created                 | MPC key set    | Created                   |                                       |
| MPCKeySet\_Enabled                 | MPC key set    | Enabled                   |                                       |
| MPCKeySet\_Activated               | MPC key set    | Activated                 |                                       |

# Policies

| Event ID                                                                              | Subject                           | Event                             | Notification Subject                                                                    |
| ------------------------------------------------------------------------------------- | --------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------- |
| `EventId.Policy_PolicyReviewRejected`                                                 | TAP                               | Rejected policy                   | Policy Policy Review Rejected                                                           |
| `EventId.PolicyEditor_ASignerApprovedThePendingDraftPolicy`                           | TAP                               | Signed policy                     | Policy editor A signer approved the pending draft policy                                |
| `EventId.PolicyEditor_Deleted`                                                        | TAP                               | Deleted policy                    | Policy editor Deleted                                                                   |
| `EventId.PolicyEditor_PolicyPublished`                                                | TAP                               | Published policy                  | Policy editor Policy published                                                          |
| `EventId.PolicyEditor_TheDraftPolicyWasDiscarded`                                     | TAP                               | Discarded policy draft            | Policy editor The draft policy was discarded                                            |
| `EventId.PolicyEditor_TheDraftPolicyWasReverted`                                      | TAP                               | Reverted policy draft'            | Policy editor The draft policy was reverted                                             |
| `EventId.PolicyEditor_ThePendingPolicyWasRejected`                                    | TAP                               | Rejected policy                   | Policy editor The pending policy was rejected                                           |
| `EventId.PolicyEditor_ThePendingPolicyWasRejectedAndThePublishProcessHasBeenCanceled` | TAP                               | Rejected policy                   | Policy editor The pending policy was rejected and the publish process has been canceled |
| `EventId.PolicyEditor_ThePendingPolicyWentIntoEffect`                                 | TAP                               | Put policy into effect            | Policy editor The pending policy went into effect                                       |
| `EventId.PolicyEditor_UserMarkedTheDraftPolicyAsReadyToPublish`                       | TAP                               | Draft marked as ready to publish  | Policy editor User marked the draft policy as ready to publish                          |
| `EventId.PolicyEditor_UserRequestedToPublishTheDraftPolicy`                           | TAP                               | Requested policy draft publishing | Policy editor User requested to publish the draft policy                                |
| `EventId.PolicyEditor_UserStartedEditingTheDraftPolicy`                               | TAP                               | Edited draft                      | Policy editor User started editing the draft policy                                     |
| `EventId.PolicyEditor_PolicyReviewRejected`                                           | TAP                               | Rejected policy                   | Policy editor Policy Review Rejected                                                    |
| `EventId.IpAllowList_AllowListActivationRequestSubmitted`                             | IP address allowlist activation   | Submitted                         | Activation request submitted                                                            |
| `EventId.IpAllowList_AllowListActivationRequestApproved`                              | IP address allowlist activation   | Approved by quorum                | Activation request approved by quorum                                                   |
| `EventId.IpAllowList_AllowListActivationRequestSigned`                                | IP address allowlist activation   | Approved by user                  | Activation request approved by user                                                     |
| `EventId.IpAllowList_AllowListActivationRequestRejected`                              | IP address allowlist activation   | Rejected                          | Activation request rejected                                                             |
| `EventId.IpAllowList_AllowListActivationRequestCanceled`                              | IP address allowlist activation   | Canceled                          | Activation request canceled                                                             |
| `EventId.IpAllowList_AllowListActivationRequestFailed`                                | IP address allowlist activation   | Failed                            | Activation request failed                                                               |
| `EventId.IpAllowList_AllowListDeactivationRequestSubmitted`                           | IP address allowlist deactivation | Submitted                         | Deactivation request submitted                                                          |
| `EventId.IpAllowList_AllowListDeactivationRequestApproved`                            | IP address allowlist deactivation | Approved by quorum                | Deactivation request approved by quorum                                                 |
| `EventId.IpAllowList_AllowListDeactivationRequestSigned`                              | IP address allowlist deactivation | Approved by user                  | Deactivation request approved by user                                                   |
| `EventId.IpAllowList_AllowListDeactivationRequestRejected`                            | IP address allowlist deactivation | Rejected                          | Deactivation request rejected                                                           |
| `EventId.IpAllowList_AllowListDeactivationRequestCanceled`                            | IP address allowlist deactivation | Canceled                          | Deactivation request canceled                                                           |
| `EventId.IpAllowList_AllowListDeactivationRequestFailed`                              | IP address allowlist deactivation | Failed                            | Deactivation request failed                                                             |
| `EventId.IpAllowList_AddIpRequestSubmitted`                                           | IP address allowlist              | Approval submitted                | Add IP address request submitted                                                        |
| `EventId.IpAllowList_AddIpRequestApproved`                                            | IP address allowlist              | Approval approved by quorum       | Add IP address request approved by quorum                                               |
| `EventId.IpAllowList_AddIpRequestSigned`                                              | IP address allowlist              | Approval approved by user         | Add IP address request approved by user                                                 |
| `EventId.IpAllowList_AddIpRequestCanceled`                                            | IP address allowlist              | Approval canceled                 | Add IP address request canceled                                                         |
| `EventId.IpAllowList_AddIpRequestRejected`                                            | IP address allowlist              | Approval Rejected                 | Add IP address request rejected                                                         |
| `EventId.IpAllowList_AddIpRequestFailed`                                              | IP address allowlist              | Approval Failed                   | Add IP address request failed                                                           |
| `EventId.IpAllowList_UpdateIpRequestSubmitted`                                        | IP address allowlist              | Changes submitted                 | Update IP address request submitted                                                     |
| `EventId.IpAllowList_UpdateIpRequestApproved`                                         | IP address allowlist              | Changes approved by quorum        | Update IP address request approved by quorum                                            |
| `EventId.IpAllowList_UpdateIpRequestSigned`                                           | IP address allowlist              | Changes approved by user          | Update IP address request approved by user                                              |
| `EventId.IpAllowList_UpdateIpRequestCanceled`                                         | IP address allowlist              | Changes canceled                  | Update IP address request canceled                                                      |
| `EventId.IpAllowList_UpdateIpRequestRejected`                                         | IP address allowlist              | Changes rejected                  | Update IP address request rejected                                                      |
| `EventId.IpAllowList_UpdateIpRequestFailed`                                           | IP address allowlist              | Changes failed                    | Update IP address request failed                                                        |
| `EventId.IpAllowList_DeleteIpRequestSubmitted`                                        | IP address allowlist              | Deletion submitted                | Remove IP address request submitted                                                     |
| `EventId.IpAllowList_DeleteIpRequestSigned`                                           | IP address allowlist              | Deletion approved by user         | Remove IP address request approved by user                                              |
| `EventId.IpAllowList_DeleteIpRequestCanceled`                                         | IP address allowlist              | Deletion canceled                 | Remove IP address request canceled                                                      |
| `EventId.IpAllowList_DeleteIpRequestApproved`                                         | IP address allowlist              | Deletion approved by quorum       | Remove IP address request approved by quorum                                            |
| `EventId.IpAllowList_DeleteIpRequestRejected`                                         | IP address allowlist              | Deletion rejected                 | Remove IP address request rejected                                                      |
| `EventId.IpAllowList_DeleteIpRequestFailed`                                           | IP address allowlist              | Deletion failed                   | Remove IP address request failed                                                        |

# Security

| Event ID                      | Subject | Event            |
| :---------------------------- | :------ | :--------------- |
| EventId.Fspm\_FindingCreated  | FSPM    | Finding created  |
| EventId.Fspm\_FindingResolved | FSPM    | Finding resolved |
| EventId.Fspm\_FindingAccepted | FSPM    | Finding accepted |
| EventId.Fspm\_FindingReopened | FSPM    | Finding reopened |

# Settlements

| Event ID                                                       | Subject            | Event                             | Notification Subject                                     |
| -------------------------------------------------------------- | ------------------ | --------------------------------- | -------------------------------------------------------- |
| `EventId.NetworkConnection_Added`                              | Fireblocks network | Added connection                  | Network Connection Added                                 |
| `EventId.NetworkConnection_Created`                            | Fireblocks network | Made connection                   | Network Connection Created                               |
| `EventId.NetworkConnectionInvitation_ApprovedByAdmin`          | Fireblocks network | Approved invitation               | Network Connection Invitation Approved by admin          |
| `EventId.NetworkConnectionInvitation_Cancelled`                | Fireblocks network | Canceled invitation               | Network Connection Invitation Cancelled                  |
| `EventId.NetworkConnectionInvitation_ReceivedFromCounterparty` | Fireblocks network | Received invitation               | Network Connection Invitation Received from Counterparty |
| `EventId.NetworkConnectionRequest_ApprovedByAdmin`             | Fireblocks network | Invitation approved by connection | Network Connection Request Approved by admin             |
| `EventId.NetworkConnectionRequest_Cancelled`                   | Fireblocks network | Invitation canceled by connection | Network Connection Request Cancelled                     |
| `EventId.NetworkConnectionRequest_Rejected`                    | Fireblocks network | Invitation rejected by connection | Network Connection Request Rejected                      |
| `EventId.NetworkConnectionRoutingChange_Approved`              | Fireblocks network | Approved routing change           | Network Connection Routing Change Approved               |
| `EventId.NetworkConnectionRoutingChange_ApprovedByAdmin`       | Fireblocks network | Approved routing change (admin)   | Network Connection Routing Change Approved By Admin      |
| `EventId.NetworkConnectionRoutingChange_Rejected`              | Fireblocks network | Rejected routing change           | Network Connection Routing Change Rejected               |
| `EventId.NetworkConnectionRoutingChange_RequestSubmitted`      | Fireblocks network | Requested routing change          | Network Connection Routing Change Request Submitted      |
| `EventId.NetworkConnectionRoutingChange_RoutingChanged`        | Fireblocks network | Changed routing                   | Network Connection Routing Change Routing Changed        |
| `EventId.NetworkDiscoverability_TurnedOn`                      | Fireblocks network | Turned on discoverability'        | Network Discoverability Turned On                        |
| `EventId.NetworkDiscoverability_TurnedOff`                     | Fireblocks network | Turned off discoverability'       | Network Discoverability Turned Off                       |
| `EventId.NetworkProfile_Created`                               | Fireblocks network | Created profile'                  | Network Profile Created                                  |
| `EventId.NetworkProfileNameChange_ProfileRenamed`              | Fireblocks network | Approved profile name change      | Network Profile Name Change Profile Renamed              |
| `EventId.NetworkProfileNameChange_RequestSubmitted`            | Fireblocks network | Requested profile name change     | Network Profile Name Change Request Submitted            |
| `EventId.NetworkProfileRemoved_ProfileRemoved`                 | Fireblocks network | Removed profile                   | Network Profile Removed Profile Removed                  |
| `EventId.NetworkProfileRoutingChange_Approved`                 | Fireblocks network | Approved default routing change   | Network Profile Routing Change Approved                  |
| `EventId.NetworkProfileRoutingChange_ApprovedByAdmin`          | Fireblocks network | Approved default routing change'  | Network Profile Routing Change Approved By Admin         |
| `EventId.NetworkProfileRoutingChange_Rejected`                 | Fireblocks network | Rejected default routing change   | Network Profile Routing Change Rejected                  |
| `EventId.NetworkProfileRoutingChange_RequestSubmitted`         | Fireblocks network | Requested default routing change  | Network Profile Routing Change Request Submitted         |
| `EventId.NetworkProfileRoutingChange_RoutingChanged`           | Fireblocks network | Changed default routing           | Network Profile Routing Change Routing Changed           |
| `EventId.NetworkProfileRoutingChange_WaitingForApproval`       | Fireblocks network | Pending approval                  | Network Profile Routing Change Waiting For Approval      |
| `EventId.NetworkConnection_Removed`                            | Fireblocks network | Removed connection                | Network Connection Removed                               |
| `EventId.NetworkConnection_RemovedByCounterparty`              | Fireblocks network | Removed by connection             | Network Connection Removed by counterparty               |
| `EventId.NetworkConnectionInvitation_Rejected`                 | Fireblocks network | Rejected invitation               | Network connection invitation Rejected                   |
| `EventId.NetworkConnectionRequest_Submitted`                   | Fireblocks network | Sent invitation                   | Network connection request Submitted                     |

# Transactions

| Event ID                                                              | Subject              | Event                                   | Notification Subject                                           |
| --------------------------------------------------------------------- | -------------------- | --------------------------------------- | -------------------------------------------------------------- |
| `EventId.IncomingTransaction_AssociationFailed`                       | Incoming transaction | Failed                                  | Incoming Transaction Association Failed                        |
| `EventId.IncomingTransaction_Completed`                               | Incoming transaction | Completed                               | Incoming Transaction Completed                                 |
| `EventId.IncomingTransaction_Submitted`                               | Incoming transaction | Submitted                               | Incoming Transaction Submitted                                 |
| `EventId.IncomingTxAssociationFailed_FailedToAssociateIncomingTxHash` | Incoming transaction | Failed to associate incoming TX hash    | Incoming tx association failed FailedToAssociateIncomingTxHash |
| `EventId.InternalTransaction_Completed`                               | Internal transaction | Completed                               | Internal Transaction Completed                                 |
| `EventId.InternalTransaction_Submitted`                               | Internal transaction | Submitted                               | Internal Transaction Submitted                                 |
| `EventId.OutgoingTransaction_Completed`                               | Outgoing transaction | Completed                               | Outgoing Transaction Completed                                 |
| `EventId.OutgoingTransaction_Submitted`                               | Outgoing transaction | Submitted                               | Outgoing Transaction Submitted                                 |
| `EventId.Transaction_AlertedByAml`                                    | Transaction          | Flagged by AML                          | Transaction Alerted by AML                                     |
| `EventId.Transaction_AmlFailed`                                       | Transaction          | AML failed                              | Transaction AML Failed                                         |
| `EventId.Transaction_AmlScreeningBlockingPeriodTimedOut`              | Transaction          | AML screening blocking period timed out | Transaction AML screening blocking period timed out            |
| `EventId.Transaction_AmlResultRescreened`                             | Transaction          | AML result rescreened                   | Transaction AML Result Rescreened                              |
| `EventId.Transaction_ApprovedBy2ndTier`                               | Transaction          | Approved by 2nd tier                    | Transaction Approved by 2nd Tier                               |
| `EventId.Transaction_AuthorizationRequestInitiated`                   | Transaction          | Authorization request initiated         | Transaction Authorization Request Initiated                    |
| `EventId.Transaction_BlockedByPolicy`                                 | Transaction          | Blocked by TAP                          | Transaction Blocked by Policy                                  |
| `EventId.Transaction_BypassedAml`                                     | Transaction          | Bypassed AML                            | Transaction Bypassed AML                                       |
| `EventId.Transaction_Cancelled`                                       | Transaction          | Canceled                                | Transaction Cancelled                                          |
| `EventId.Transaction_Completed`                                       | Transaction          | Completed                               | Transaction Completed                                          |
| `EventId.Transaction_ConfirmationThresholdOverridden`                 | Transaction          | Confirmation threshold overridden       | Transaction Confirmation Threshold Overridden                  |
| `EventId.Transaction_DeclinedBy2ndTier`                               | Transaction          | Declined by 2nd tier                    | Transaction Declined by 2nd Tier                               |
| `EventId.Transaction_FundsUnfrozen`                                   | Transaction          | Funds unfrozen                          | Transaction Funds Unfrozen                                     |
| `EventId.Transaction_NoteChanged`                                     | Transaction          | Note changed                            | Transaction Note Changed                                       |
| `EventId.Transaction_Rejected`                                        | Transaction          | Rejected                                | Transaction Rejected                                           |
| `EventId.Transaction_RejectedByAml`                                   | Transaction          | Rejected by AML                         | Transaction Rejected by AML                                    |
| `EventId.Transaction_Signed`                                          | Transaction          | Signed                                  | Transaction Signed                                             |
| `EventId.Transaction_Submitted`                                       | Transaction          | Submitted                               | Transaction Submitted                                          |
| `EventId.Transaction_TransactionRejected`                             | Transaction          | Rejected                                | Transaction Transaction Rejected                               |
| `EventId.ExternalTransaction_Completed`                               | Transaction          | Completed                               | External Transaction Completed                                 |
| `EventId.ExternalTransaction_Submitted`                               | Transaction          | Submitted                               | External Transaction Submitted                                 |
| `EventId.Transaction_ScreeningIncomingStarted`                        | Transaction          | Screening incoming started              | Transaction Screening incoming started                         |
| `EventId.Transaction_AmlIncomingStarted`                              | Transaction          | AML Incoming Started                    | Transaction AML Incoming Started                               |
| `EventId.Transaction_AmlIncomingCompleted`                            | Transaction          | AML Incoming Completed                  | Transaction AML Incoming Completed                             |
| `EventId.Transaction_AmlIncomingFailed`                               | Transaction          | AML Incoming Failed                     | Transaction AML Incoming Failed                                |
| `EventId.Transaction_AmlIncomingInBackground`                         | Transaction          | AML Incoming in background              | Transaction AML Incoming in background                         |
| `EventId.Transaction_TrIncomingStarted`                               | Transaction          | TR Incoming started                     | Transaction TR Incoming started                                |
| `EventId.Transaction_TrIncomingCompleted`                             | Transaction          | TR Incoming completed                   | Transaction TR Incoming completed                              |
| `EventId.Transaction_TrIncomingFailed`                                | Transaction          | TR Incoming failed                      | Transaction TR Incoming failed                                 |
| `EventId.Transaction_ScreeningIncomingCompleted`                      | Transaction          | Screening incoming completed            | Transaction Screening incoming completed                       |

# Wallets

| Event ID                                                               | Subject           | Event                               | Notification Subject                                                    |
| ---------------------------------------------------------------------- | ----------------- | ----------------------------------- | ----------------------------------------------------------------------- |
| `EventId.ColdWallet_DeviceHasLessThan10_RemainingSignatures`           | Cold wallet       | Requires signatures                 | Cold Wallet Device has less than 10% remaining signatures               |
| `EventId.VaultAccount_Added`                                           | Vault             | Created                             | Vault Account Added                                                     |
| `EventId.VaultAccount_AddedInBulk`                                     | Vault             | Bulk created                        | Vault Account Added in Bulk                                             |
| `EventId.VaultAccount_Archived`                                        | Vault             | Archived                            | Vault Account Archived                                                  |
| `EventId.VaultAccount_DisabledAutoFueling`                             | Vault             | Turned off auto-fueling             | Vault Account Disabled Auto Fueling                                     |
| `EventId.VaultAccount_EnabledAutoFueling`                              | Vault             | Turned on auto-fueling              | Vault Account Enabled Auto Fueling                                      |
| `EventId.VaultAccount_Renamed`                                         | Vault             | Renamed                             | Vault Account Renamed                                                   |
| `EventId.VaultAccount_SetHiddenOnUi`                                   | Vault             | Hidden                              | Vault Account Set Hidden On UI                                          |
| `EventId.VaultAccount_SetVisibleOnUi`                                  | Vault             | Made visible                        | Vault Account Set Visible On UI                                         |
| `EventId.VaultAccount_Unarchived`                                      | Vault             | Unarchived                          | Vault Account Unarchived                                                |
| `EventId.VaultDepositAddress_ChangedDescription`                       | Wallet            | Changed deposit address description | Vault deposit address Changed description                               |
| `EventId.VaultWallet_Added`                                            | Wallet            | Added                               | Vault wallet Added                                                      |
| `EventId.VaultWallet_AddedInBulk`                                      | Wallet            | Bulk added                          | Vault wallet Added in Bulk                                              |
| `EventId.VaultWallet_Archived`                                         | Wallet            | Archived                            | Vault wallet Archived                                                   |
| `EventId.VaultWallet_Unarchived`                                       | Wallet            | Unarchived                          | Vault wallet Unarchived                                                 |
| `EventId.BackupAndRecovery_SentVerifyPassphraseAlert`                  | Mobile passphrase | Sent verification alert             | Backup And Recovery Sent Verify Passphrase Alert                        |
| `EventId.BackupAndRecovery_VerifiedPassphrase`                         | Mobile passphrase | Verified passphrase                 | Backup And Recovery Verified Passphrase                                 |
| `EventId.HardKeyRecoveryProcess_RequestSubmitted`                      | Key backup        | Requested                           | Hard Key Recovery Process Request Submitted                             |
| `EventId.MobileKey_BackedUp`                                           | Mobile passphrase | Backed up                           | Mobile Key Backed Up                                                    |
| `EventId.WorkspaceKeyBackup_ApprovedByAdmin`                           | Key backup        | Approved                            | Workspace key backup Approved by admin                                  |
| `EventId.WorkspaceKeyBackup_ApprovedByAdminQuorum`                     | Key backup        | Approved by quorum                  | Workspace key backup Approved by admin quorum                           |
| `EventId.WorkspaceKeyBackup_Cancelled`                                 | Key backup        | Canceled                            | Workspace key backup Cancelled                                          |
| `EventId.WorkspaceKeyBackup_InternalErrorWhenGeneratingTheBackup`      | Key backup        | Error generating key backup         | Workspace key backup Internal error when generating the backup          |
| `EventId.WorkspaceKeyBackup_RequestSubmitted`                          | Key backup        | Requested                           | Workspace key backup Request Submitted                                  |
| `EventId.WorkspaceKeyBackup_TheProcessHasBeenRejectedByOnOfTheAdmins`  | Key backup        | Rejected                            | Workspace key backup The process has been rejected by on of the admins  |
| `EventId.WorkspaceKeyBackup_TheProcessHasBeenRejectedByOneOfTheAdmins` | Key backup        | Rejected                            | Workspace key backup The process has been rejected by one of the admins |
| `EventId.WorkspaceKeyBackup_TheWorkspaceOwnerHasInitiatedTheProcess`   | Key backup        | Initiated                           | Workspace key backup The workspace owner has initiated the process      |
| `EventId.WorkspaceKeyBackup_MarkedAsIncomplete`                        | Key backup        | Marked as incomplete                | Workspace key backup Marked as incomplete                               |
| `EventId.WorkspaceKeyBackup_MarkedAsCompleted`                         | Key backup        | Marked as completed                 | Workspace key backup Marked as completed                                |
| `EventId.WorkspaceKeyBackup_PendingApproval`                           | Key backup        | Pending approval                    | Workspace key backup Pending approval                                   |
| `EventId.WorkspaceKeyBackup_BackupSent`                                | Key backup        | Backup sent                         | Workspace key backup Backup sent                                        |
| `EventId.GasStation_LowFunds`                                          | Gas station       | Low funds                           | Gas Station Low funds                                                   |
| `EventId.GasStation_VaultChanged`                                      | Gas station       | Changed vault                       | Gas Station Vault changed                                               |
| `EventId.GasStation_SweepTransactionInitiated`                         | Gas station       | Initiated sweep                     | Gas Station Sweep transaction initiated                                 |
| `EventId.GasStation_FundsDeposited`                                    | Gas station       | Deposited funds                     | Gas Station Funds deposited                                             |
| `EventId.ExternalWallet_Added`                                         | Wallet            | Added                               | External wallet Added                                                   |
| `EventId.ExternalWallet_Removed`                                       | Wallet            | Removed                             | External wallet Removed                                                 |
| `EventId.MyWallet_Added`                                               | My wallet         | Added                               | My wallet Added                                                         |
| `EventId.MyWallet_Removed`                                             | My wallet         | Removed                             | My wallet Removed                                                       |

# Web3

| Event ID                                                        | Subject                      | Event              | Notification Subject                                     |
| --------------------------------------------------------------- | ---------------------------- | ------------------ | -------------------------------------------------------- |
| `EventId.Allowance_AmountModified`                              | Allowance                    | Changed            | Allowance Amount Modified                                |
| `EventId.Contract_Added`                                        | Contract                     | Added              | Contract Added                                           |
| `EventId.Contract_Removed`                                      | Contract                     | Removed            | Contract Removed                                         |
| `EventId.FireblocksExtensionConnected_ExtensionConnected`       | Fireblocks browser extension | Connected          | Fireblocks extension connected Extension Connected       |
| `EventId.FireblocksExtensionUpdated_ExtensionUpdated`           | Fireblocks browser extension | Updated            | Fireblocks extension updated Extension Updated           |
| `EventId.FireblocksExtensionDisconnected_ExtensionDisconnected` | Fireblocks browser extension | Disconnected       | Fireblocks extension disconnected Extension Disconnected |
| `EventId.Nft_MarkedAsSpam`                                      | NFT                          | Marked as spam     | NFT Marked as spam                                       |
| `EventId.Nft_MarkedAsNotSpam`                                   | NFT                          | Marked as not spam | NFT Marked as not spam                                   |

# Whitelist

| Event ID                                       | Subject             | Event     | Notification Subject                   |
| ---------------------------------------------- | ------------------- | --------- | -------------------------------------- |
| `EventId.Address_Removed`                      | Whitelisted address | Removed   | Address Removed                        |
| `EventId.Address_Whitelisted`                  | Whitelisted address | Added     | Address Whitelisted                    |
| `EventId.AddressWhitelisting_ApprovedByAdmin`  | Whitelisted address | Approved  | Address Whitelisting Approved by admin |
| `EventId.AddressWhitelisting_Cancelled`        | Whitelisted address | Canceled  | Address Whitelisting Cancelled         |
| `EventId.AddressWhitelisting_Rejected`         | Whitelisted address | Rejected  | Address Whitelisting Rejected          |
| `EventId.AddressWhitelisting_RequestSubmitted` | Whitelisted address | Requested | Address Whitelisting Request Submitted |


# Authenticating the Callback Handler Request
Source: https://developers.fireblocks.com/reference/authenticate



> **Learn more about the API Co-Signer Callback Handler here**

## Overview

When your API Co-signer is configured with a Callback Handler, it sends a POST request to the Callback Handler. The POST request contains a JSON Web Token (JWT) encoded message signed with the API Co-Signer's private key. The Callback Handler uses the API Co-signer's public key to verify that every incoming JWT is signed correctly by the API Co-signer.

The Callback Handler's response is a JWT-encoded message signed with the Callback Handler's private key. This private key must be paired with the public key provided to the API Co-signer during the Callback Handler's setup.

***

## Keys Generation

* Generate a private key using the following command:

  `openssl genrsa -out callback_private.pem 2048`

> **Important**
>
> Fireblocks only supports RSA key 2048 bit for public key Callback Handler authentication.

* Export the public key from the previously generated private key using the following command:

  `openssl rsa -in callback_private.pem -outform PEM -pubout -out callback_public.pem`

* Write your callback logic, which should include checking that the message can be decoded using the API Co-signer public key. The API Co-signer public key can be obtained by running the command:

  `./cosigner print-public-key`
  Save the cosigner public key in a file on your Callback Handler server - `cosigner_public.pem`

* Set up an HTTPS server with a certificate signed by a trusted CA. Make sure the route has a "/v2" prefix. Your callback handler endpoints should respond to requests that include a “/v2” prefix: [https://your\_callback\_base\_url/v2/tx\_sign\_request](https://your_callback_base_url/v2/tx_sign_request) or [https://your\_callback\_base\_url/v2/config\_change\_sign\_request](https://your_callback_base_url/v2/config_change_sign_request)

> **Note:**
>
> When adding the Callback Handler URL to the Co-signer, you should pass only the base URL + custom relative path.
> The `</v2/tx\_sign\_request>` or `</v2/config\_change\_sign\_request>` relative paths will be automatically added upon each request made by the Co-signer.
>
> For example if you exposed the Callback Handler URL in the following path:
> [https://subdomain.example.com/fireblocks/callback\_handler/v2/tx\_sign\_request](https://subdomain.example.com/fireblocks/callback_handler/v2/tx_sign_request)
>
> You should configure the following URL in the Co-signer:
> [https://subdomain.example.com/fireblocks/callback\_handler](https://subdomain.example.com/fireblocks/callback_handler)


# Automation Webhooks
Source: https://developers.fireblocks.com/reference/automation-webhooks



> **Deprecation notice**
>
> Webhooks v1 will be deprecated on **June 15th, 2026**. Please use the Developer Center in the Fireblocks Console to upgrade to Webhooks V2, which offers improved reliability, performance, and observability.

This page describes all events relating to Fireblocks Automations that produce Webhook notifications, and their associated data objects.

The `type` parameter is automatically set to the description name for the data objects below.

## Automation Run

An AUTOMATION\_EXECUTION\_WEBHOOK\_UPDATE webhook is sent when an automation rule runs.

| Parameter   | Type   | Description                                                                                                                       |
| ----------- | ------ | --------------------------------------------------------------------------------------------------------------------------------- |
| ruleId      | string | Unique ID for the Automation rule as a ratio to executions (1/N)                                                                  |
| executionId | string | Number of times this rule has been executed                                                                                       |
| state       | enum   | Current status of the rule.  Available values: `CREATED`; `TRIGGERED`; `CONDITION_MET`; `CONDITION_NOT_MET`; `EXECUTED`; `FAILED` |
| trigger     | enum   | Available values: `TIME`; `TRANSACTION`                                                                                           |
| condition   | enum   | Available values: `BALANCE`; `TRANSACTION_AMOUNT`; `UNCONDITIONAL`                                                                |
| actions     | enum   | Available values: `TRANSFER`; `TOP_UP`; `REBALANCE`; `START_WORKFLOW`; `CONVERT`; `SWEEP`                                         |
| createdAt   | number | The time the rule was created, in milliseconds (epoch)                                                                            |
| createdBy   | string | ID of the user who created the rule                                                                                               |
| rule        | string | Name of the Automation Rule                                                                                                       |
| failure     | enum   | Available values: `CONDITION_CHECK_FAILED`, `ACTION_FAILED`, `EXECUTION_FAILED`                                                   |


# Introduction
Source: https://developers.fireblocks.com/reference/background-retail-demo-application



The Fireblocks Retail Demo application is designed to support Fireblocks clients by serving as a reference model for their integration processes. It embodies the best practices Fireblocks advocates for building secure, retail-facing solutions.

This demo aims to accelerate and simplify the integration of Fireblocks into your projects, ensuring that you adhere to the recommended best practices when building on the Fireblocks platform.

This article provides the necessary background on the considerations we had in mind when planning the demo application and developing its business logic.

**Vault Structure**

First, it's essential to understand how to best structure your Fireblocks workspace, vault accounts, and asset wallets to serve the requirements of a retail crypto application.

There are generally [two main approaches for vault structuring](https://support.fireblocks.io/hc/en-us/articles/5253421857564-Fireblocks-Vault-structure-best-practices): Omnibus and Segregated. The [Omnibus](https://support.fireblocks.io/hc/en-us/articles/6986895761948-Account-and-wallet-structure) vault structure is usually the more fitting selection when planning a retail-facing product, as it offers a more efficient way to handle end-user deposits, balance management, and withdrawals in fewer transactions with better fee management than using a segregated structure.

In our implementation, we have used a central Omnibus vault account to hold end-user funds. UTXO-based assets (e.g., BTC) are deposited by the end-users directly into the Omnibus vault using a dedicated deposit address for each user deposit, while account-based assets (e.g., ETH) are deposited to intermediate deposit vault accounts and later swept to the Omnibus vault.

Additionally, we are using three designated withdrawal vaults to allow high withdrawal throughput. Using multiple withdrawal vaults allows for more robust withdrawal handling, as withdrawal requests might queue up into a long backlog due to an unconfirmed transaction of a specific asset from a withdrawal wallet. Such backlog scenarios should be handled with dedicated business logic, but generally speaking, having several withdrawal vaults ensures your application can maintain a steady and robust withdrawal throughput.

The configuration of the Fireblocks workspace vaults and wallets is done by the application's [setup script](/reference/setup#setup-script)  upon running the app for the first time.

<img alt="" />

**End-user wallets**

A retail application, potentially serving millions of end-users, must be able to create and operate millions of crypto deposit addresses, assign them to the correct end-user accounts in our internal ledger, and manage their balances correctly. When planning the application, we must consider which types of assets we will support (UTXO-based / Account-based / Tag or Memo-based), as different types require different wallet creation and management approaches.

When an end-user logs in for the first time, we need to generate an account or wallet entity for that user that will hold all of their deposit addresses for the assets we support. Depending on the asset type, different business logic will occur in the backend when the user asks for a new deposit address.
For UTXO or Tag/Memo-based assets (such as BTC, ADA, etc.), we will create a new dedicated **deposit address** inside the Omnibus vault account and assign it to the user account in our database (our internal ledger).
For Account-based assets (such as ETH, SOL, etc.), we will create a new intermediate **vault account** and then create a deposit address inside this dedicated intermediate vault account whenever a user requests a new deposit address. One can improve this process by first checking if the user already has an unused vault account that doesn't yet have the requested asset's wallet. If such an account exists, we can use it to create the new deposit address instead of creating a new vault account each time the user requests a new address.
Additionally, as the process of generating a deposit address for account-based assets will usually require two API calls to Fireblocks (one for creating the new vault account and one for generating the deposit address), it will be beneficial to add a job-like service that will pre-create vault accounts in batches. Once an end-user requests a new deposit address, the backend process will use a ready vault account when creating the deposit address and assign it to the relevant end-user (rename the vault account with a user reference ID and update the internal ledger accordingly).

In our implementation, this business logic is mainly handled by the [VaultAccount service](https://github.com/fireblocks/retail-demo/blob/main/backend/src/service/fireblocks/vaultAccount.service.ts).

**Deposit Management - Sweeping and UTXO Consolidation**

Another aspect we must consider when planning a retail crypto application is the [sweeping](/reference/sweep-to-omnibus-1#sweeping) of account-based assets to the Omnibus vault account. For UTXO asset deposits, we must have a mechanism that will [consolidate](/reference/consolidate-utxos) our Omnibus wallet inputs (coming from end-user deposits) into larger UTXOs that allow more efficient processes down the line, such as internal rebalancing transactions and end-user withdrawals.

**Sweeping**

When designing the sweeping mechanism, we should take into account several considerations, such as:

* Triggering (when should we sweep the intermediate vaults?)
* Sorting (which vaults should be swept now?)
* Gas balances (gas top-ups for token sweeping)
* Asset sweeping order (sweep tokens before base assets)

In our implementation, we trigger the sweeping mechanism based on a simple [time interval](https://github.com/fireblocks/retail-demo/blob/6f3dabed7cf7cab0435462fb17d409d62839cfad/backend/src/service/sweeping.service.ts#L13), but other possible and more complex approaches might be based on a set threshold of incoming deposits of account-based assets or based on monitoring gas rates in a given network to trigger the sweeping mechanism only when gas rates are relatively low, as a more cost-effective approach. As for sorting, we are querying the database for all user wallets that have a balance higher than a set threshold of a "sweepable" asset (account-based) and mapping the balances to the relevant Fireblocks vault account IDs so we can iterate through them and trigger the sweeping transactions accordingly. Based on your logic for triggering the sweeping process, you can also change the flow for sorting and selecting which intermediate vaults to sweep.

The business logic of account-based asset sweeping is handled by the Sweeping service .

**UTXO Consolidation**

In Fireblocks, a UTXO-based asset transaction can consist of up to 250 inputs, and the default input selection mechanism selects inputs from the lowest to the highest value. These presets can lead to a situation where, in a high-volume crypto retail application that may receive numerous deposits of small amounts of tokens from end-users, the ever-growing list of small UTXOs will have the sufficient balance to support a transaction request from the Omnibus wallet with a large amount. Having a UTXO consolidation solution implemented correctly will help prevent such a situation and ensure the application's high throughput operation at all times.

In our implementation, we've created two UTXO consolidation jobs, one of which is a backup process for the first routine job.
We maintain a deposit counter for every UTXO asset the application supports in our database. Once the counter reaches 249 deposits, the routine consolidation job is triggered and will perform a consolidation transaction and reset the counter. The backup process runs every day and checks if any of the UTXO assets in the Omnibus wallet have 250 unspent inputs or more. This check is done with the [Fireblocks API](/reference/getunspentinputs) directly on the Omnibus vault account and adds another safeguard to the consolidation process. If 250 inputs or more are found, consolidation transactions will be triggered until that condition is no longer met.
A consolidation transaction will have the Omnibus vault account as both the source and the destination. This will ensure that the Omnibus wallet will have inputs with high value available for future transactions.

The business logic of UTXO consolidation is handled by the [consolidation service](https://github.com/fireblocks/retail-demo/blob/main/backend/src/service/consolidation.service.ts).

**Internal Rebalancing**

As mentioned above, a scalable retail crypto application must have several dedicated withdrawal vault accounts to support a high throughput of withdrawals. To function effectively, these vaults must maintain a sufficient balance of all supported assets at any given time. To achieve this, we need an internal rebalancing mechanism that ensures all withdrawal vaults are always funded. This mechanism can be developed programmatically using Fireblocks APIs, but in our implementation, we chose to leverage the new [automation](https://support.fireblocks.io/hc/en-us/articles/14873112741660-Automation) feature. This feature allows us to set up automatic triggers within Fireblocks if the asset's balance is lower than a set threshold after a withdrawal transaction is processed and completed.
Below is an example of such an automation we've configured in our testnet workspace.

<img alt="" />

This rebalancing approach will require you to set a minimum and a maximum threshold per asset you support. The minimum threshold will be the triggering amount of a rebalancing transaction, and the maximum threshold will be the amount the withdrawal vault will be topped up to after the rebalancing transaction is completed.

**End User Withdrawals**

End-user withdrawals are a crucial phase in the lifecycle of a retail crypto application, deeply affecting the platform's reputation. To handle a high volume of withdrawal requests efficiently, utilizing multiple dedicated withdrawal vault accounts is recommended. Besides this strategy, there are key considerations for robust withdrawal logic.

A solid withdrawal system should:

* Validate User Balances: Check that the user's available balance is sufficient to cover the withdrawal amount and any associated fees.
* Rotate Withdrawal Vaults: Incorporate a method, such as a random selection process, to alternate between different withdrawal vault accounts as transaction sources.

In our approach, we've implemented a straightforward randomization logic. The application randomly picks a number corresponding to one of the available withdrawal vault accounts (e.g., selecting between 1 and 3). This determines the vault account ID used for the transaction source. [See our code example here](https://github.com/fireblocks/retail-demo/blob/6f3dabed7cf7cab0435462fb17d409d62839cfad/backend/src/utils/vaultConfig.ts#L37).

The withdrawal flow is handled by the [transaction controller](https://github.com/fireblocks/retail-demo/blob/6f3dabed7cf7cab0435462fb17d409d62839cfad/backend/src/controller/transaction.controller.ts#L55) and the [transaction service](https://github.com/fireblocks/retail-demo/blob/6f3dabed7cf7cab0435462fb17d409d62839cfad/backend/src/service/fireblocks/transaction.service.ts).


# Balance validation
Source: https://developers.fireblocks.com/reference/balance-validation



## Method 3: Balance Validation

Balance validation verifies webhook transaction data against the Fireblocks API, protecting against stale or inconsistent data.

For our Validate Balances article, see [here](/docs/validate-balances).


# Basic Callback Handler example
Source: https://developers.fireblocks.com/reference/basic-code-example



## Request payload example

This example demonstrates the raw and decoded JWT payload sent by the Co-Signer to the Callback Handler.

Additionally, it includes a test private key that signed the payload and the corresponding public key that should be used for signature validation:

> **The provided Private Key is for example purposes only and should not be used in your production system.**

> **The provided example may contain properties that are not sent by default. Customers should ensure they DO NOT expect to receive values that are not documented in the Approve Transactions and Approve Configuration Changes sections.**

```text theme={"system"}
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eElkIjoiOWM3OTRjZWUtN2UyNy00NmM5LTllOWEtZWQ2ODI5NWZmMDZiIiwib3BlcmF0aW9uIjoiVFJBTlNGRVIiLCJzb3VyY2VUeXBlIjoiVkFVTFQiLCJzb3VyY2VJZCI6IjAiLCJkZXN0VHlwZSI6IlZBVUxUIiwiZGVzdElkIjoiMSIsImFzc2V0IjoiRVRIIiwiYW1vdW50IjowLjAxLCJhbW91bnRTdHIiOiIwLjAxMDAwMDAwMDAwMDAwMDAwMCIsInJlcXVlc3RlZEFtb3VudCI6MC4wMSwicmVxdWVzdGVkQW1vdW50U3RyIjoiMC4wMSIsImZlZSI6IjAuMDAwNTk3ODAzNzYyMjQxMDAwIiwiZGVzdEFkZHJlc3NUeXBlIjoiV0hJVEVMSVNURUQiLCJkZXN0QWRkcmVzcyI6IjB4NWRDNjlCMUZiYjEzQmFmZDA5YWY4OGE3ODJGMEYyODU3NzJBZDVmOCIsImRlc3RpbmF0aW9ucyI6W3siYW1vdW50TmF0aXZlIjowLjAxLCJhbW91bnROYXRpdmVTdHIiOiIwLjAxIiwiYW1vdW50VVNEIjoxOC43NDI5MjkzNywiZHN0QWRkcmVzc1R5cGUiOiJXSElURUxJU1RFRCIsImRzdElkIjoiMSIsImRzdFdhbGxldElkIjoiIiwiZHN0TmFtZSI6Ik5ldHdvcmsgRGVwb3NpdHMiLCJkc3RTdWJUeXBlIjoiIiwiZHN0VHlwZSI6IlZBVUxUIiwiZGlzcGxheURzdEFkZHJlc3MiOiIweDVkQzY5QjFGYmIxM0JhZmQwOWFmODhhNzgyRjBGMjg1NzcyQWQ1ZjgiLCJhY3Rpb24iOiJBTExPVyIsImFjdGlvbkluZm8iOnsiY2FwdHVyZWRSdWxlTnVtIjo1LCJydWxlc1NuYXBzaG90SWQiOjgxNjQsImJ5R2xvYmFsUG9saWN5IjpmYWxzZSwiYnlSdWxlIjp0cnVlLCJjYXB0dXJlZFJ1bGUiOiJ7XCJ0eXBlXCI6XCJUUkFOU0ZFUlwiLFwidHJhbnNhY3Rpb25UeXBlXCI6XCJUUkFOU0ZFUlwiLFwiYXNzZXRcIjpcIipcIixcImFtb3VudFwiOjAsXCJvcGVyYXRvcnNcIjp7XCJ3aWxkY2FyZFwiOlwiKlwifSxcImFwcGx5Rm9yQXBwcm92ZVwiOnRydWUsXCJhY3Rpb25cIjpcIkFMTE9XXCIsXCJzcmNcIjp7XCJpZHNcIjpbW1wiKlwiXV19LFwiZHN0XCI6e1wiaWRzXCI6W1tcIipcIl1dfSxcImRzdEFkZHJlc3NUeXBlXCI6XCIqXCIsXCJhbW91bnRDdXJyZW5jeVwiOlwiVVNEXCIsXCJhbW91bnRTY29wZVwiOlwiU0lOR0xFX1RYXCIsXCJwZXJpb2RTZWNcIjowfSJ9fV0sInJhd1R4IjpbeyJrZXlEZXJpdmF0aW9uUGF0aCI6IlsgNDQsIDYwLCAwLCAwLCAwIF0iLCJyYXdUeCI6IjAyZWYwMTA0ODQzYjlhY2EwMDg1MDZhMGMxOTg3ZDgyNTIwODk0NWRjNjliMWZiYjEzYmFmZDA5YWY4OGE3ODJmMGYyODU3NzJhZDVmODg3MjM4NmYyNmZjMTAwMDA4MGMwIiwicGF5bG9hZCI6Ijc3YjRlNzQwOTljZTkwYzA4NTAzYzBlMGJiNmU2NzJkYmUxYzVlM2UxMjdjZTMzM2JmMjJlYjU4MWNkM2Y2Y2UifV0sInBsYXllcnMiOlsiMjE5MjZlY2MtNGE4YS00NjE0LWJiYWMtN2M1OTFhYTdlZmRkIiwiMjc5MDA3MzctNDZmNi00MDk3LWExNjktZDBmZjQ1NjQ5ZWQ1IiwiZjg5Y2FjNTAtYzY1Ni00ZTc0LTg3OWYtMDQxYWZmOGQwMWI1Il0sInJlcXVlc3RJZCI6IjljNzk0Y2VlLTdlMjctNDZjOS05ZTlhLWVkNjgyOTVmZjA2YiJ9.aE1ZOSQreBU23q3e-Dx6Z76tFgURfDU8Szj1XESN1-LczwFpCXJeexOLJ4L5IoAHpp8FV8f1vg1yu_-iV1ZiPsCR8K9fcLQmTGF21Y43w18s1nvY8rqSKX64sHDWoBTUN1oJFhjzzi1ovpmcASBj3_yWJIv6-RfW20l30_f6ggMXZDE0QImCSYtRL2m5YIBr8wVe2rMleFLCQLUQTLVXyE-oxxbCfy-R_FqWv-dn7CaQSFkztm8fCn2_jnxlHs0phuOxSucwrOM7UkVr7qM8uTWhvdeTkYPjVBcj5lpgYwb8Fo2F0fnIvgcvRaz8r4LjVrj6hVwRHH809jt0ouzVeg
```

```json theme={"system"}
{
  "txId": "9c794cee-7e27-46c9-9e9a-ed68295ff06b",
  "operation": "TRANSFER",
  "sourceType": "VAULT",
  "sourceId": "0",
  "destType": "VAULT",
  "destId": "1",
  "asset": "ETH",
  "amount": 0.01,
  "amountStr": "0.010000000000000000",
  "requestedAmount": 0.01,
  "requestedAmountStr": "0.01",
  "fee": "0.000597803762241000",
  "destAddressType": "WHITELISTED",
  "destAddress": "0x5dC69B1Fbb13Bafd09af88a782F0F285772Ad5f8",
  "destinations": [
    {
      "amountNative": 0.01,
      "amountNativeStr": "0.01",
      "amountUSD": 18.74292937,
      "dstAddressType": "WHITELISTED",
      "dstId": "1",
      "dstWalletId": "",
      "dstName": "Network Deposits",
      "dstSubType": "",
      "dstType": "VAULT",
      "displayDstAddress": "0x5dC69B1Fbb13Bafd09af88a782F0F285772Ad5f8",
      "action": "ALLOW",
      "actionInfo": {
        "capturedRuleNum": 5,
        "rulesSnapshotId": 8164,
        "byGlobalPolicy": false,
        "byRule": true,
        "capturedRule": "{\"type\":\"TRANSFER\",\"transactionType\":\"TRANSFER\",\"asset\":\"*\",\"amount\":0,\"operators\":{\"wildcard\":\"*\"},\"applyForApprove\":true,\"action\":\"ALLOW\",\"src\":{\"ids\":[[\"*\"]]},\"dst\":{\"ids\":[[\"*\"]]},\"dstAddressType\":\"*\",\"amountCurrency\":\"USD\",\"amountScope\":\"SINGLE_TX\",\"periodSec\":0}"
      }
    }
  ],
  "rawTx": [
    {
      "keyDerivationPath": "[ 44, 60, 0, 0, 0 ]",
      "rawTx": "02ef0104843b9aca008506a0c1987d825208945dc69b1fbb13bafd09af88a782f0f285772ad5f8872386f26fc1000080c0",
      "payload": "77b4e74099ce90c08503c0e0bb6e672dbe1c5e3e127ce333bf22eb581cd3f6ce"
    }
  ],
  "players": [
    "21926ecc-4a8a-4614-bbac-7c591aa7efdd",
    "27900737-46f6-4097-a169-d0ff45649ed5",
    "f89cac50-c656-4e74-879f-041aff8d01b5"
  ],
  "requestId": "9c794cee-7e27-46c9-9e9a-ed68295ff06b"
}
```

```yaml theme={"system"}
-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDJtgGHPlbV5KB1
yzPslxYnFiYeogUX0w6rd9Ee+zAljQ2msEP45NCaHwPX6fsukQnw+w7hlvr52aVR
vKJKFmXnNMTSEd9v358053gJCzyVd9hKFnVO/04uwFTIwXX11VPd8XWZy6ue8meE
qztGfJJvvDtHnbmJUFgf48DBv04hUzDm7yS2CJsO0UR91WQRwlTDkMUs4b2jJ4AN
oLFaHlw+HAkKQH+O4g+WEfq+GQWnxq57L5U90TH4/+vELy54gOicojww6t/rTrjz
WRjzJxfE6Ue3Tbpf7tfVMrlCsD+q3958q+m5a6O/KmwyfMo6P/yUt66W1KhK4Wmg
v6YGY8J7AgMBAAECggEAG/rcvxNlJ+S/uLHta8n7dIQ3LnRKtjwnIp7gtGZN4++V
2gOaXNSfS7m1+/CE0Lf6w+GMy2XOPkk0DEtZIbjLUuU4Jhb87P+n4xv2mR6PaAEI
piJJDHe6sx59GZ9IYHJCi3IP3ju+fIe4gf00oDmYddpg82AMGWGP5Ss1FPXB/eTV
QT+5qwnZz2qqkzpk8QDcNjK/fsuuIaJg6RDC5NbXFuMr4NXKkXzDPkmzCgFowHAR
J5Jqf4y2YArKV7kwEgW+naUAESPLWFUCaoLmCJxw7fbqHkUHYKHfWk9M9t9C0boL
b0G9zbsAI/ip9YxuKzXi0E8lTkFH8q7Fssa5m/Gp/QKBgQD057qo2hq2zWXRXZ7W
Q9nta3uNdsxhRPeC/z9ejUIy4kC7/ZbQ04+i+Tefwz4kjSVxSobb4Y7Bh8e4/tpw
alyvTIyEys25G6vkFJh8MXojxQEgU1ImMnsFEqZVKsUilz/+aDG3POvihF4jwKbF
GJCUhFG8mFzsFQLtYKmmp5NOXQKBgQDS2VWyS3d7arZyAdCjI3pw+SV/iF/bJ7wT
NK2N6RHpfVwnnDk/AyFxQy2k53VwXASwYVsDkEZiPz1lqlV5xltcx3GDR5xhRdol
M4i0H+Qc+bYXjy+O99LYgRODzTsq8PQmUADL9xAF+Df3CW4sTZ5Izi46Hq9uMFa6
bA0IH5nWtwKBgGkuuUFZ4w1N7APelKBrpcZNWlQoiKDiEPenDp1aR+s4txrGUCbC
JjeVl6k7Ho5uPH2Kx57aIgjGeyXd9w0+8S2sz9EclPyCgPHFUrRMP6vrKY+rmWWk
WqeUGfIMG3y+vxJRx8BuHtU7in8Kd9XAth/DMKOyQH54i7hNwq87241VAoGAQax6
Oc+xxppFe5s/HiFF2Pxxhpi2qq9ksGK/EC2ha6WlV50cY5kZCItRI0UI2ld/CmU4
kRKWKbHi8NCuUQDMokho/egHOHEmcmHr2Zb5WWEaK5poyNI+NTt3FZ2OKWDl2y0e
Immw7vsSi3q/e0Mt4yV9VpMKN3sM+IIBSR92rl8CgYEAlfUVoSXRVOxh29dI65Qi
5IfJmg1mQnHWE2RfuZqtTcYisvbQejygsoyh1ZydEUSsX5rUbkc3/qqW5N4pEYVt
ZHCn7MJHot44SA3XDn2dGRQAL5UQJJK5nHRVeBuoJtnNyzhxbZH3M56sT4o5i6UC
TFalBSOqnaPpYIxV2fgCdyE=
-----END PRIVATE KEY-----
```

```yaml theme={"system"}
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAybYBhz5W1eSgdcsz7JcW
JxYmHqIFF9MOq3fRHvswJY0NprBD+OTQmh8D1+n7LpEJ8PsO4Zb6+dmlUbyiShZl
5zTE0hHfb9+fNOd4CQs8lXfYShZ1Tv9OLsBUyMF19dVT3fF1mcurnvJnhKs7RnyS
b7w7R525iVBYH+PAwb9OIVMw5u8ktgibDtFEfdVkEcJUw5DFLOG9oyeADaCxWh5c
PhwJCkB/juIPlhH6vhkFp8auey+VPdEx+P/rxC8ueIDonKI8MOrf606481kY8ycX
xOlHt026X+7X1TK5QrA/qt/efKvpuWujvypsMnzKOj/8lLeultSoSuFpoL+mBmPC
ewIDAQAB
-----END PUBLIC KEY-----
```

***

## Response payload example

This example demonstrates the raw and decoded JWT response returned from the Callback Handler to the Co-signer. The response is signed using the Callback Handler's private key. The Co-signer then verifies the signature using the predefined public key configured during the Co-signer installation phase.

For simplicity, the examples use the same private/public key pair as in the **Request Example** section:

> **Please note that the iat value is not required in the actual response and will be ignored by the Co-Signer. It is included here because the JWT signature library automatically adds this field.**

```text theme={"system"}
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY3Rpb24iOiJSRUpFQ1QiLCJyZXF1ZXN0SWQiOiI5Yzc5NGNlZS03ZTI3LTQ2YzktOWU5YS1lZDY4Mjk1ZmYwNmIiLCJyZWplY3Rpb25SZWFzb24iOiJMb2dpYyByZXR1cm5lZCBmYWxzZSIsImlhdCI6MTcyMDQ3MjU5NH0.CGJ7D0KHb2K0F0ibStAAy8MyvXIZR-sQsFRiHRebXPEVMOdjEooaDac9PZYTgmuMJANDtsDAy9bbIggaTraeGxLtHPS4TvQdOA1GX74gWlkBHktJxtGxngsSwbZ-clvCSrwQ0AQcwqCv1OozXRmt_SGberuJpVIUbNc1HWlKAbti4dIcN_irTp2Xwq9WmGRwF16rkK97JdtMbhPBF9t56kdYrHccKU9q69_4Q7zG8I9yXgYKTQ1XctJiGjg06dPR3fDEVeN_ibUXSU5h1sXnd3gvpbUNmEOYAREDKZAk_FMSdMmiC9Prp0t9g-xDtoSear6vN-ovxk_64AwMLxqsEg
```

```json theme={"system"}
{
  "action": "REJECT",
  "requestId": "9c794cee-7e27-46c9-9e9a-ed68295ff06b",
  "rejectionReason": "Logic returned false",
  "iat": 1720472594
}
```

***

## API Co-Signer basic Callback Handler server example

Here is a code example for a basic Callback Handler application. The application is designed to handle POST requests from the Co-signer at the endpoint /v2/tx\_sign\_request.

* It validates that the received payload is signed with the correct private key.
* If the verification is successful, it responds with a 200 status code, the `REJECT` action, and the `rejectionReason` in the response body.
* If the verification fails, it responds with a 401 status code.

```javascript theme={"system"}
const express = require("express");
const bodyParser = require("body-parser");
const fs = require("fs");
const jwt = require("jsonwebtoken");
const privateKey = fs.readFileSync("callback_private.pem");
const cosignerPubKey = fs.readFileSync("cosigner_public.pem");
const app = express();

app.use(
  express.urlencoded({
    extended: true
  })
);
app.use(express.json());

app.use(function (req) {
  req.rawBody = "";
  req.setEncoding("utf8");
  req.on("data", function(chunk) {
    req.rawBody += chunk;
  });
  req.on("end", function () {
   req.next();
  });
});

app.post("/v2/tx_sign_request", async (req, res) => {
  let verified;
  try {
  const tx = jwt.decode(req.rawBody);
  const { requestId } = tx;
  verified = jwt.verify(req.rawBody, cosignerPubKey);
  if (verified) {
    let action = "REJECT";
    let rejectionReason = "Logic returned false";
    const signedRes = jwt.sign(
      {
        action,
        requestId,
        rejectionReason
      },
      privateKey,
      { algorithm: "RS256" }
    );
    res.send(signedRes);
  }
  } catch (e) {
    res.sendStatus(401);
  }
});
app.listen(3000);
```

```python theme={"system"}
from pathlib import Path
from wsgiref.simple_server import make_server
import falcon
import jwt
callback_handler_prikey = None
cosigner_pubkey = None

# Load keys.
f1 = Path("callback_private.pem")
if f1.is_file(): callback_handler_prikey = f1.read_bytes()
f2 = Path("cosigner_public.pem")
if f2.is_file(): cosigner_pubkey = f2.read_bytes()

class JWTTransferRequest(object):
    def on_post(self, req, resp):
        raw_req = req.bounded_stream.read()
        req = jwt.decode(raw_req, cosigner_pubkey, algorithms=["RS256"])
        resp.body = jwt.encode({'action': 'APPROVE', 'requestId': req['requestId']}, callback_handler_prikey, algorithm="RS256")
        resp.status = falcon.HTTP_200

# Create falcon app
app = falcon.App()
app.add_route('/v2/tx_sign_request', JWTTransferRequest())
app.add_route('/v2/config_change_sign_request', JWTTransferRequest())
if __name__ == '__main__':
    with make_server('', 80, app) as httpd:
        print('Serving on port 80...')
        # Serve until process is killed
        httpd.serve_forever()
JWTTransferRequest()
```


# Bring your own screening check developer guide
Source: https://developers.fireblocks.com/reference/bring-your-own-screening-check-developer-guide



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](https://support.fireblocks.io/hc/en-us/articles/26230042914076-Bring-Your-Own-Screening-Check-Integration-Guide) (requires Help Center login).

## Quickstart

Follow these steps to set up and activate Bring Your Own Screening Check:

1. Contact your Customer Success Manager to enable the feature for your workspace.
2. Configure incoming and outgoing timeouts with `PUT /v1/screening/byork/config/timeouts`.
3. Open a support ticket to configure your pre-screening rules.
4. Set up your webhook listener for screening events.
5. Test your verdict API integration in the sandbox environment.
6. Activate the feature with `POST /v1/screening/byork/config/activate`.
7. Monitor verdict submission latency against your configured timeouts.

## Configuration

### Get current configuration

```http theme={"system"}
GET /v1/screening/byork/config
```

Returns your current configuration, including timeouts and active status.

#### Response example

```json theme={"system"}
{
  "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](#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

```http theme={"system"}
PUT /v1/screening/byork/config/timeouts
```

Include at least one of `incomingTimeoutSeconds` or `outgoingTimeoutSeconds` in the request body. The response returns the full updated configuration.

#### Response example

```json theme={"system"}
{
  "incomingTimeoutSeconds": 7200,
  "outgoingTimeoutSeconds": 3600
}
```

| Parameter                | Default | Min | Max                  |
| ------------------------ | ------- | --- | -------------------- |
| `incomingTimeoutSeconds` | 3600    | 10  | 604800 (7 days)      |
| `outgoingTimeoutSeconds` | 3600    | 10  | JWT lifetime − 1800s |

### Configure pre-screening rules

Pre-screening rules determine which transactions are held for review and which bypass the check. Rules are evaluated in order — the first match wins. Omitted fields match any value.

To configure or update your pre-screening rules, open a support ticket. See [Pre-screening rules reference](#pre-screening-rules-reference) for the full list of available rule fields.

### Activate and deactivate

Once your timeouts and rules are set, activate to start screening transactions:

```http theme={"system"}
POST /v1/screening/byork/config/activate
```

To pause screening without removing your configuration:

```http theme={"system"}
POST /v1/screening/byork/config/deactivate
```

Both endpoints return the full updated configuration. When deactivated, all transactions bypass the review step and continue to Travel Rule or completion.

## Submitting verdicts

### Submit a verdict

```http theme={"system"}
POST /v1/screening/byork/verdict
```

Use an [idempotency key](/reference/api-idempotency) on `POST verdict` to avoid duplicate submissions.

#### Request body

```json theme={"system"}
{
  "txId": "3b9cc47a-f8c2-4b09-9b1f-e12a53d9f74c",
  "verdict": "ACCEPT"
}
```

| Field     | Type   | Description               |
| --------- | ------ | ------------------------- |
| `txId`    | string | Fireblocks transaction ID |
| `verdict` | string | `ACCEPT` or `REJECT`      |

#### Response example

```json theme={"system"}
{
  "status": "COMPLETED",
  "message": "Verdict ACCEPT applied"
}
```

### Get verdict status

```http theme={"system"}
GET /v1/screening/byork/verdict?txId={txId}
```

Returns the current verdict status for a transaction.

| 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

```http theme={"system"}
POST /v1/screening/byork/verdict
```

### Response example

```json theme={"system"}
{
  "txId": "3b9cc47a-f8c2-4b09-9b1f-e12a53d9f74c",
  "verdict": "ACCEPT"
}
```

The response returns `"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](#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

```json theme={"system"}
{
  "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.


# Caching Signatures
Source: https://developers.fireblocks.com/reference/caching-signatures



Some DeFi apps expect to receive the same signature for separate consecutive messages. Signature caching allows the most recent signature to be returned based on the content and the source, including the workspace ID, Vault account, and asset, or derivation path. This signature may be returned repeatedly, skipping additional approval and signing processes.

Signature caching is enabled for all users by default using [WalletConnect](https://support.fireblocks.io/hc/en-us/articles/5403817784732-Connecting-to-Web3-using-WalletConnect) or the [Fireblocks Chrome Extension](https://fireblocks.zendesk.com/hc/en-us/articles/5403962226332). However, you can opt out by [contacting Fireblocks Support](https://support.fireblocks.io/hc/en-us/requests/new).

Signature caching also works with [Typed Messages](/docs/typed-message-signing-1) and [Raw Signing](/docs/raw-signing) via the Fireblocks API.


# Code Examples
Source: https://developers.fireblocks.com/reference/code-examples-1



> **Deprecation notice**
>
> Webhooks v1 will be deprecated on **June 15th, 2026**. Please use the Developer Center in the Fireblocks Console to upgrade to Webhooks V2, which offers improved reliability, performance, and observability.

Below are examples in Python and JavaScript demonstrating how to configure the webhook receiving endpoint on the customer's end, including the request validation mechanism:

> **Warning: For reference only**
>
> * These examples are **not production-ready** and are used only for reference.
> * These examples are configured to represent a production environment. Sandbox users should ensure they update the Public Key to the correct one, as mentioned [here](/reference/verify-requests).

```javascript theme={"system"}
const crypto = require("crypto");
const express = require("express");
const bodyParser = require('body-parser')

const port = 3000;

const publicKey = `-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA0+6wd9OJQpK60ZI7qnZG
jjQ0wNFUHfRv85Tdyek8+ahlg1Ph8uhwl4N6DZw5LwLXhNjzAbQ8LGPxt36RUZl5
YlxTru0jZNKx5lslR+H4i936A4pKBjgiMmSkVwXD9HcfKHTp70GQ812+J0Fvti/v
4nrrUpc011Wo4F6omt1QcYsi4GTI5OsEbeKQ24BtUd6Z1Nm/EP7PfPxeb4CP8KOH
clM8K7OwBUfWrip8Ptljjz9BNOZUF94iyjJ/BIzGJjyCntho64ehpUYP8UJykLVd
CGcu7sVYWnknf1ZGLuqqZQt4qt7cUUhFGielssZP9N9x7wzaAIFcT3yQ+ELDu1SZ
dE4lZsf2uMyfj58V8GDOLLE233+LRsRbJ083x+e2mW5BdAGtGgQBusFfnmv5Bxqd
HgS55hsna5725/44tvxll261TgQvjGrTxwe7e5Ia3d2Syc+e89mXQaI/+cZnylNP
SwCCvx8mOM847T0XkVRX3ZrwXtHIA25uKsPJzUtksDnAowB91j7RJkjXxJcz3Vh1
4k182UFOTPRW9jzdWNSyWQGl/vpe9oQ4c2Ly15+/toBo4YXJeDdDnZ5c/O+KKadc
IMPBpnPrH/0O97uMPuED+nI6ISGOTMLZo35xJ96gPBwyG5s2QxIkKPXIrhgcgUnk
tSM7QYNhlftT4/yVvYnk0YcCAwEAAQ==
-----END PUBLIC KEY-----`.replace(/\\n/g, "\n");

const app = express();

app.use(bodyParser.json());

app.post("/webhook", (req, res) => {
    const message = JSON.stringify(req.body);
    const signature = req.headers["fireblocks-signature"];

    const verifier = crypto.createVerify('RSA-SHA512');
    verifier.write(message);
    verifier.end();

    const isVerified = verifier.verify(publicKey, signature, "base64");
    console.log("Verified:", isVerified);

    res.send("ok");
});

app.listen(port, () => {
    console.log(`Webhook running at http://localhost:${port}`);
});
```

```python theme={"system"}
import falcon
import json
import rsa
import base64

FIREBLOCKS_PUBLIC_KEY = """
-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA0+6wd9OJQpK60ZI7qnZG
jjQ0wNFUHfRv85Tdyek8+ahlg1Ph8uhwl4N6DZw5LwLXhNjzAbQ8LGPxt36RUZl5
YlxTru0jZNKx5lslR+H4i936A4pKBjgiMmSkVwXD9HcfKHTp70GQ812+J0Fvti/v
4nrrUpc011Wo4F6omt1QcYsi4GTI5OsEbeKQ24BtUd6Z1Nm/EP7PfPxeb4CP8KOH
clM8K7OwBUfWrip8Ptljjz9BNOZUF94iyjJ/BIzGJjyCntho64ehpUYP8UJykLVd
CGcu7sVYWnknf1ZGLuqqZQt4qt7cUUhFGielssZP9N9x7wzaAIFcT3yQ+ELDu1SZ
dE4lZsf2uMyfj58V8GDOLLE233+LRsRbJ083x+e2mW5BdAGtGgQBusFfnmv5Bxqd
HgS55hsna5725/44tvxll261TgQvjGrTxwe7e5Ia3d2Syc+e89mXQaI/+cZnylNP
SwCCvx8mOM847T0XkVRX3ZrwXtHIA25uKsPJzUtksDnAowB91j7RJkjXxJcz3Vh1
4k182UFOTPRW9jzdWNSyWQGl/vpe9oQ4c2Ly15+/toBo4YXJeDdDnZ5c/O+KKadc
IMPBpnPrH/0O97uMPuED+nI6ISGOTMLZo35xJ96gPBwyG5s2QxIkKPXIrhgcgUnk
tSM7QYNhlftT4/yVvYnk0YcCAwEAAQ==
-----END PUBLIC KEY-----
"""

signature_pub_key = rsa.PublicKey.load_pkcs1_openssl_pem(FIREBLOCKS_PUBLIC_KEY)

class RequestBodyMiddleware(object):
    def process_request(self, req, resp):
        req.body = req.bounded_stream.read()

class AuthMiddleware(object):
    def process_request(self, req, resp):
        signature = req.get_header('Fireblocks-Signature')

        if signature is None:
            raise falcon.HTTPUnauthorized('Signature required')

        if not self._signature_is_valid(req.body, signature):
            raise falcon.HTTPUnauthorized('Invalid signature')

    def _signature_is_valid(self,  body, signature):
        try:
            hashing_alg = rsa.verify(body, base64.b64decode(signature), signature_pub_key)
            return hashing_alg == "SHA-512"
        except rsa.pkcs1.VerificationError:
            return False

class DummyRequest(object):
    def on_post(self, req, resp):
        obj = json.loads(req.body.decode("utf-8"))
        print(obj)
        resp.status = falcon.HTTP_201

# Create falcon app
app = falcon.API(
    middleware=[
        RequestBodyMiddleware(),
        AuthMiddleware()
    ]
)

app.add_route('/webhook', DummyRequest())

if __name__ == '__main__':
    from wsgiref import simple_server  # NOQA
    httpd = simple_server.make_server('127.0.0.1', 8000, app)
    httpd.serve_forever()
```


# Code Examples
Source: https://developers.fireblocks.com/reference/code-examples-2



# Bitcoin Arbitrary Message

> **BTC arbitrary message signing can be also performed by Typed Message signing and it is considered more secure. Check out our Typed Message guide**

The example below illustrates the use of the Raw Signing feature for Bitcoin arbitrary message signing:

```javascript theme={"system"}
import { readFileSync } from 'fs';
import {
  Fireblocks,
  BasePath,
  TransactionOperation,
  TransferPeerPathType,
  TransactionRequest,
  TransactionResponse,
  FireblocksResponse,
  TransactionStateEnum,
  CreateTransactionResponse
} from "@fireblocks/ts-sdk";
import { createHash } from "crypto";

const FIREBLOCKS_API_SECRET_PATH = "<PATH_TO_SECRET>";
const API_KEY = "<API_KEY>"

// Initialize a Fireblocks API instance with local variables
const fireblocks = new Fireblocks({
    apiKey: API_KEY,
    basePath: BasePath.US, // Basepath.Sandbox for the sandbox env
    secretKey: readFileSync(FIREBLOCKS_API_SECRET_PATH, "utf8"),
});

const transactionPayload: TransactionRequest = {
  assetId: "BTC",
  operation: TransactionOperation.Raw,
  source: {
    type: TransferPeerPathType.VaultAccount,
    id: "0",
  },
  note: ``,
  extraParameters: {
    rawMessageData: {},
  },
};

let txInfo: any;

const getTxStatus = async (txId: string): Promise<TransactionResponse> => {
  try {
    let response: FireblocksResponse<TransactionResponse> =
      await fireblocks.transactions.getTransaction({ txId });
    let tx: TransactionResponse = response.data;
    let messageToConsole: string = `Transaction ${tx.id} is currently at status - ${tx.status}`;

    console.log(messageToConsole);
    while (tx.status !== TransactionStateEnum.Completed) {
      await new Promise((resolve) => setTimeout(resolve, 3000));

      response = await fireblocks.transactions.getTransaction({ txId });
      tx = response.data;

      switch (tx.status) {
        case TransactionStateEnum.Blocked:
        case TransactionStateEnum.Cancelled:
        case TransactionStateEnum.Failed:
        case TransactionStateEnum.Rejected:
          throw new Error(
            `Signing request failed/blocked/cancelled: Transaction: ${tx.id} status is ${tx.status}`,
          );
        default:
          console.log(messageToConsole);
          break;
      }
    }
    while (tx.status !== TransactionStateEnum.Completed);
    return tx;
  } catch (error) {
    throw error;
  }
};

const rawSign = async (
  message: string,
): Promise<CreateTransactionResponse | undefined> => {
  const wrappedMessage =
    "\x18Bitcoin Signed Message:\n" +
    String.fromCharCode(message.length) +
    message;
  const hash = createHash("sha256").update(wrappedMessage, "utf8").digest();
  const content = createHash("sha256").update(hash).digest("hex");
  //@ts-ignore
  transactionPayload.extraParameters.rawMessageData = {
    messages: [
      {
        content,
        bip44addressIndex: 0,
      },
    ],
  };
  transactionPayload.note = `BTC Message: ${message}`;
  try {
    const transactionResponse = await fireblocks.transactions.createTransaction(
      {
        transactionRequest: transactionPayload,
      },
    );
    //@ts-ignore
    console.log(transactionPayload.extraParameters.rawMessageData);
    const txId = transactionResponse.data.id;
    if (!txId) {
      throw new Error("Transaction ID is undefined.");
    }
    txInfo = await getTxStatus(txId);
    console.log(JSON.stringify(txInfo, null, 2));
    const signature = txInfo.signedMessages[0].signature;

    console.log(JSON.stringify(signature));

    const encodedSig =
      Buffer.from([Number.parseInt(signature.v, 16) + 31]).toString("hex") +
      signature.fullSig;
    console.log(
      "Encoded Signature:",
      Buffer.from(encodedSig, "hex").toString("base64"),);
    return
  } catch (error) {
    console.error(error);
  }
};

rawSign("My message23");
```

```javascript theme={"system"}
import { createHash } from "crypto";
import * as fs from "fs"
import * as path from "path"
import { FireblocksSDK, PeerType, TransactionOperation, TransactionStatus } from "fireblocks-sdk";

const apiKey = "<YOUR_API_KEY>"
const apiSecretPath = "<PATH_TO_SECRET>"
const apiSecret = fs.readFileSync(path.resolve(__dirname, apiSecretPath), "utf8");
const fireblocks = new FireblocksSDK(apiSecret, apiKey);

async function signArbitraryMessage(fireblocks: FireblocksSDK, vaultAccountId: string, message: string, bip44addressIndex = 0) {
    const wrappedMessage = "\x18Bitcoin Signed Message:\n" +  String.fromCharCode(message.length) + message;

    const hash = createHash('sha256').update(wrappedMessage, 'utf8').digest();

    const content = createHash('sha256').update(hash).digest("hex");

    const { status, id } = await fireblocks.createTransaction({
        operation: TransactionOperation.RAW,
        assetId: "BTC",
        source: {
            type: PeerType.VAULT_ACCOUNT,
            id: vaultAccountId
        },
        note: `BTC Message: ${message}`,
        extraParameters: {
            rawMessageData: {
                messages: [{
                    content,
                    bip44addressIndex
                }]
            }
        }
    });

    let txInfo;
    let currentStatus = status;
  	while(currentStatus != TransactionStatus.COMPLETED && currentStatus != TransactionStatus.FAILED) {
        try {
            console.log("keep polling for tx " + id + "; status: " + currentStatus);
            txInfo = await fireblocks.getTransactionById(id);
            currentStatus = txInfo.status;
        } catch (err) {
            console.log("err", err);
        }
        await new Promise(r => setTimeout(r, 1000));
    };

    const signature = txInfo.signedMessages[0].signature;

    console.log(JSON.stringify(signature));

    const encodedSig = Buffer.from([signature.v + 31]).toString("hex") + signature.fullSig;
    console.log("Encoded Signature:", Buffer.from(encodedSig,"hex").toString("base64"));
}
 signArbitraryMessage(fireblocks, "0", "INSERT TEXT HERE");
```

```python theme={"system"}
from fireblocks.client import Fireblocks
from fireblocks.client_configuration import ClientConfiguration
from fireblocks.base_path import BasePath
from fireblocks.models.transaction_request import TransactionRequest
from fireblocks.models.destination_transfer_peer_path import DestinationTransferPeerPath
from fireblocks.models.source_transfer_peer_path import SourceTransferPeerPath
from fireblocks.models.transfer_peer_path_type import TransferPeerPathType
from fireblocks.models.transaction_request_amount import TransactionRequestAmount
from pprint import pprint

# load the secret key content from a file
with open('your_secret_key_file_path', 'r') as file:
    secret_key_value = file.read()

# build the configuration
configuration = ClientConfiguration(
        api_key="your_api_key",
        secret_key=secret_key_value,
        base_path=BasePath.Sandbox, # or set it directly to a string "https://sandbox-api.fireblocks.io/v1"
)

# Enter a context with an instance of the API client
with Fireblocks(configuration) as fireblocks:
    transaction_request: TransactionRequest = TransactionRequest(
        asset_id="BTC",
        amount=TransactionRequestAmount("0.1"),
        source=SourceTransferPeerPath(
            type=TransferPeerPathType.VAULT_ACCOUNT,
            id="0"
        ),
        destination=DestinationTransferPeerPath(
            type=TransferPeerPathType.VAULT_ACCOUNT,
            id="1"
        ),
        note="Your first transaction!"
    )
    # or you can use JSON approach:
    #
    # transaction_request: TransactionRequest = TransactionRequest.from_json(
    #     '{"note": "Your first transaction!", '
    #     '"assetId": "BTC", '
    #     '"source": {"type": "VAULT_ACCOUNT", "id": "0"}, '
    #     '"destination": {"type": "VAULT_ACCOUNT", "id": "1"}, '
    #     '"amount": "0.1"}'
    # )
    try:
        # Create a new transaction
        future = fireblocks.transactions.create_transaction(transaction_request=transaction_request)
        api_response = future.result()  # Wait for the response
        print("The response of TransactionsApi->create_transaction:\n")
        pprint(api_response)
        # to print just the data:                pprint(api_response.data)
        # to print just the data in json format: pprint(api_response.data.to_json())
    except Exception as e:
        print("Exception when calling TransactionsApi->create_transaction: %s\n" % e)
```

3. Start by creating a transaction of type **RAW**, shown under `operation` (JS) or by using `create_raw_transaction()` (PY).
4. Now, specify the source who is signing the message, which is the default vault (`Id 0`) in our case.

After sending the transaction for signing, wait for its completion so you can retrieve the signature.

The loop in the example above waits for the status of the transaction to be `COMPLETED`, or until an issue arises.

Once the transaction is complete, we print the full signature by accessing the transaction object `signedMessages`, then `signature`.


# Common errors
Source: https://developers.fireblocks.com/reference/common-errors



# Unexpected physicalDeviceId

When thrown by any SDK function, this error indicates that the `physicalDeviceId` associated with the `deviceId` in Fireblocks and the `physicalDeviceId` sent with the request are not identical.

The `physicalDeviceId` is an ID the SDK provisions when the SDK is initialized on a new web browser or mobile device. After the `generateMPCKeys` function generates key shares or an end user completes the recovery procedure, Fireblocks assigns the `deviceId` to the `physicalDeviceId`. This means that the same `deviceId` cannot issue requests (e.g., sign transactions) from any other SDK initialization.

<Note>
  **Reminder**

  The SDK initialization occurs with a specific `deviceId`.
</Note>

Below are some scenarios that may result in an **Unexpected physicalDeviceId** exception.

## Unexpected physicalDeviceId after recovery

As described [here](https://ncw-developers.fireblocks.com/docs/backup-recovery-1#additional-recovery-info), encrypted key share backups are associated with a corresponding `deviceId`. When an end-user recovers a key share from a new device (i.e., a different `physicalDeviceId` than their original device), the `deviceId` of the original device is no longer associated with the key share.

### Example

If Device A (`physicalDeviceId: pd1` and `deviceId: d1`) generates a key share, and Device B (`physicalDeviceId: pd2`) recovers Device A's key share, the NCW SDK will throw the **Unexpected physicalDeviceId** error message when Device A attempts to sign a transaction since `pd1` is no longer associated with `d1`.

## Unexpected physicalDeviceId after key generation abruptly stopped

During the key generation process, Fireblocks associates the `physicalDeviceId` with the `deviceId`. If the process is interrupted and then restarted with the same `deviceId` but a different `physicalDeviceId`, the NCW SDK will throw the **Unexpected physicalDeviceId** error message.

### Examples

* Reinstalling the app, clearing the storage, and then calling `generateMPCKeys` again
* Calling `generateMPCKeys` from another device


# Configure Policies
Source: https://developers.fireblocks.com/reference/configure-transaction-authorization-policy



# The Policy Rules structure

The Policy Rule object represents a single unit of logic that Policies enforce. Understanding the structure and constraints of this object is crucial to working with Policy Editor APIs. The same object is used when working with Policy Drafts. To publish a single rule or a set of rules, pass an array inside the request body that holds one or more Policy Rule objects. Each Policy Rule object in the array should have the following mandatory fields:

| Field          | Type   | Values                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| -------------- | ------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Action         | String | ALLOW, BLOCK, 2-TIER  | Defines what occurs when a transaction meets the rule's criteria.                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Asset          | String |                       | Defines the type of asset being transacted. Use “\*” for all assets, or specify a specific `assetID` string that can be obtained using the [List all asset types supported by Fireblocks endpoint](/api-reference/blockchains-&-assets/list-assets-legacy) .                                                                                                                                                                                                                                            |
| amountCurrency | String | USD, EURO, NATIVE     | Limits the amount of any asset users can transfer based on their NATIVE value or based on their USD or EURO equivalents.                                                                                                                                                                                                                                                                                                                                                                                |
| Src and dst    | String |                       | Defines source and destination accounts the rule allows transfers to originate from and be sent to.                                                                                                                                                                                                                                                                                                                                                                                                     |
| amountScope    | String | SINGLE\_TX, TIMEFRAME | This limit applies to a single transaction or to all transactions within the defined time period.                                                                                                                                                                                                                                                                                                                                                                                                       |
| Amount         | String |                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| periodSec      | Number |                       | Time period in seconds which applies to the `amountScope` field to accumulate transferred amounts in transactions that match the rule, until the total exceeds the value you specify under Minimum. When the specified amount is reached within that period, whether by one or many transactions, further transactions in that period either fail or require more approvals.   - *Note:*\* If `amountScope` = “SINGLE\_TX”, meaning that the rule should not cover a Time period, set `periodSec` = “0” |
| Type           | String | TRANSFER (Default)    | The default value of TRANSFER is fixed and the value cannot be changed. If you wish to change the rule to apply on any of the other possible transaction types, add the `transactionType` key. \*\*Note:\*\*Additional mandatory fields apply when changing the `transactionType`.                                                                                                                                                                                                                      |

# Objects within the Policy Rule

## externalDescriptor

Each Policy rule receives a unique string ID identifying it. A “rule” is an object managed separately in Fireblocks as part of the Policy. The `externalDescriptor` key is an object holding that string ID value. This value is used to reference the specific rule when you wish to overwrite an existing rule using the [Send publish request for a set of policy rules endpoint](/api-reference/policy-editor-beta/send-publish-request-for-a-set-of-policy-rules). It is also referenced after the Policy Validation process is executed, and its response is returned under the `checkResult` object.

## Operators

Pass one or more `userID` strings inside an array of strings as the value for the “users” key in order to represent the users that are allowed to sign the transactions which are relevant under the scope of this rule. Use the [List users endpoint](/api-reference/users/list-users) to obtain the user IDs.

```json theme={"system"}
"operators": {
             "usersGroups": ["userId1", "userId2", "userId3"]
           },
```

Alternatively, to configure a rule where all users are allowed, replace the “users” key with the "wildcard" key and pass `*`.

```json theme={"system"}
"operators": {
             "wildcard": "*"
           },
```

Passing an Array of “userGroups” instead of “users” is optional. Use the [List user groups endpoint](/reference/getusergroups) to obtain the `userGroups` IDs.

```json theme={"system"}
"operators": {
             "userGroups": ["userGroupID1", "userGroupID2"]
           },
```

Check the example section below for payloads that have rules defined with either option.

## transactionType

It is possible to pass the transactionType key with either of the below values to configure a rule for the following types:

* TRANSFER - Default. Transfers funds from one account to another.
* CONTRACT\_CALL - calls a smart contract.
* APPROVE - enables the approve function to be used for a smart contract to withdraw from a designated wallet. [Learn more](https://support.fireblocks.io/hc/en-us/articles/4404616097426-Approve-Transaction-Amount-Cap).
* MINT - performs a mint operation (increases supply) on a supported token.
* BURN - performs a burn operation (reduces supply) on a supported token.
* STAKE - allows you to allocate and lock assets supported for staking to accrue rewards. [Learn more](https://support.fireblocks.io/hc/en-us/articles/4417214701970-Staking-on-Fireblocks).
* RAW - an off-chain message used to sign any message with your private key.
* TYPED\_MESSAGE - an off-chain message type that follows a predefined format and used to sign specific ETH or BTC messages.

Each of the Policy rule types may have different mandatory fields that are seen inside the endpoint’s [API reference documentation](/api-reference/policy-editor-beta/send-publish-request-for-a-set-of-policy-rules). For example, for the TRANSFER type, you can use any of the following sources or destinations:

* `*`
* VAULT
* ONE\_TIME\_ADDRESS
* EXCHANGE
* UNMANAGED
* NETWORK\_CONNECTION
* FIAT\_ACCOUNT

> **Note**
>
> Using ONE\_TIME\_ADDRESS, UNMANAGED & NETWORK\_CONNECTION is only possible under DST.

## SRC & DST

Standard Transfer rules as well as Contract Call rules limit the activity for specific sources or destinations. Exceptions to these rules, where the rule should not include a destination limitation, are Typed Message, RAW and Burn rule types.

The SRC & DST object structures should be an array of arrays. Each array can hold an array of either:

* A single key - “wildcard”, as the type of address should not be indicated
* Two keys - ID and Type
* Three keys - ID, Type, and Subtype of the address

```json theme={"system"}
            "dst": {
                 "ids": [
                     [
                         "*",
                         "UNMANAGED"
                     ],
                     [
                         "*",
                         "EXCHANGE",
                         "*"
                     ],
                     [
                         "*",
                         "NETWORK_CONNECTION",
                         "*"
                     ]
                 ]
             },
             "src": {
                 "ids": [
                     [
                         "*",
                         "VAULT",
                         "*"
                     ],
                     [
                         "*",
                         "EXCHANGE",
                         "KRAKEN"
                     ]
                 ]
             },
```

Check the example section below for full payloads that have rules defined with either option.

# Publishing, approving and validating Policy rules

A Policy should normally have more than a single rule to govern the operations of the workspace. Therefore, multiple Policy Rule objects are passed inside the “rules” object. The [Send publish request for a set of policy rules endpoint](/api-reference/policy-editor-beta/send-publish-request-for-a-set-of-policy-rules) should receive a payload of your entire Policy. Check the example section below for payloads that have multiple rules defined.

# Publish a Poli​​cy using an SDK

To publish your Policy, use the `publishPolicyRules` SDK method and include the Policy Rule object. In the following example, you can see the passed object named “rule”. As mentioned, a typical Policy includes rules which are sent under the same array as a separate object.

Here is a code sample for configuring a single rule allowing ETH transactions:

```javascript theme={"system"}
async function publishPolicyRules(){[
   rule = [
       	{
             "action": "ALLOW",
             "asset": "ETH",
             "amountCurrency": "USD",
             "src": {
                 "ids": [
                     [
                         "*"
                     ]
                 ]
             },
      "dst": {
                 "ids": [
                     [
                         "*"
                     ]
                 ]
             },
             "amountScope": "SINGLE_TX",
             "amount": "0",
             "periodSec": 0,
             "type": "TRANSFER",
             "operators": {
                 "wildcard": "*"
             }
      }
  	]
   ]
   console.log(typeof(rule));
   const publishPolicyRules = await fireblocks.publishPolicyRules(rule);
   console.log(JSON.stringify(publishPolicyRules, null, 2));
}
```

Check the example section below for payloads that have multiple rules defined.

## Edit an Existing Policy rule

Using the [Send publish request for a set of policy rules endpoint](/api-reference/policy-editor-beta/send-publish-request-for-a-set-of-policy-rules), you can edit existing rules by passing the Policy Rule object details and adding the externalDescriptor ID of an existing rule that you wish to overwrite. Get the externalDescriptor from the [Get the active policy and its validation endpoint](/api-reference/policy-editor-beta/get-the-active-policy-and-its-validation). To edit multiple rules, pass the Policy Rule object and add each rule’s unique externalDescriptor in every rule object.

# Approving the Policy change inside the Console

Once you execute the code as the example above shows, your workspace Owner will receive a **Review Policy changes** notification in their Console. They will have to login and review the changes prior to getting the approval request on their mobile device.

Below is the notification that the Owner should look for once logging into the Console and navigating to the **Settings** page:

<img alt="" />

On the top-right side of the screen, the following will appear:

<img alt="" />

# Customizing the Rules

## Time-Based Threshold

Passing the `amountAggregation` object, together with the amountScope key (set to “TIMEFRAME”) and the `periodSec` (representing the time period in seconds), will configure the rule to match the aggregated value of transactions, the source and destination inclusion pattern, and the time period.

### Note:

This is a mandatory ***number*** parameter that should be set to “0” if no Time Based Threshold is used in the rule.

**Example**: Block transfers when a \$15,000 accumulation is reached over a 12-hour period (12hx60mx60s=43200 seconds))

```json theme={"system"}
             "action": "BLOCK",
             "amount": "15000",
             "amountCurrency": "USD",
             "transactionType": "TRANSFER",
             "allowedAssetTypes": "FUNGIBLE",

             "amountAggregation": {
                 "operators": "ACROSS_ALL_MATCHES",
                 "dstTransferPeers": "ACROSS_ALL_MATCHES",
                 "srcTransferPeers": "ACROSS_ALL_MATCHES"
             },
             "amountScope": "TIMEFRAME",
             "periodSec": 43200,
```

## applyForApprove

Passing this key with a True value, will configure a Contract\_Call rule to match for initial “Approve” transaction used in Web3 smart contracts.

```json theme={"system"}
       "applyForApprove": true,
```

## applyForTypedMessage

Passing this key with a True value, when configuring a Contract\_Call rule, will match interactions with decentralized apps (dApps) that require signing EIP-712 or ETH personal messages. Alternatively, you can create a separate Typed\_Message type rule for that purpose only. Configuring this key is relevant for Contract\_Call rules when one-time address (OTA) and whitelisted destinations are used or for Off-chain messages that have no destination.

```json theme={"system"}
           "applyForTypedMessage": true,
```

## rawMessageSigning

Passing this object, will configure the rule to match specific Raw Signing messages by either their derivation paths(s) or their signing algorithm.

```json theme={"system"}
       "rawMessageSigning": {
          "algorithm": "MPC_ECDSA_SECP256K1",
          "derivationPath": {
            "path": [
              44,0,0,0,0
            ]
          }
        },
```

This is applicable when the rule is configured with the “All vaults” as the source. In the example below, the SRC object limits the source to the “Vault” type. Unlike the other types of sources allowed, vaults have a derivation path per each asset wallet. [See Policy Rules for RAW Signing](https://support.fireblocks.io/hc/en-us/articles/4413379762450-Raw-Signing).

```json theme={"system"}
           "src": {
               "ids": [
                   [
                     "*",
                     "VAULT",
                     "*"
                   ]
                 ]
           },
```

Note that passing the “derivationPath” key is mandatory while passing “algorithm” is optional.

# Policy Validation

Fireblocks checks your rule submission for errors. Each rule receives a unique string ID identifying the rule. The rule ID is returned under the Policy response body inside the `externalDescriptor` parameter. Together with the details of the submitted rule(s), the Policy response object shows additional validation-related details under the status key and the `checkResult` object:

* `status`: the status of the Policy operation
* `checkResult`: an object showing the details of the check for each rule submitted
* `errors`(1): a number indicating the total amount of errors found
* `results`: an array holding the details of the validation per each rule submitted. Each validation result will have an index key that represents the position of the rule within the set of Policy rules. Each validation will contain an array of errors found within it.
* `errors` (2): an array of objects, each reflecting the specific error details identified.

Here is an example Response object showing the validation fields (the rule itself is redacted):

```json theme={"system"}
{
 "status": "INVALID_CONFIGURATION",
 "checkResult": {
   "errors": 1,
   "results": [
     {
       "index": 0,
       "externalDescriptor": "{\"id\":\"1e9cf057-028d-4657-8da1-b604800ed198\"}",
       "status": "failure",
       "errors": [
         {
           "errorMessage": "INVALID_ASSET_TYPE",
           "errorCode": 2,
           "errorCodeName": "INVALID_PARAMETERS",
           "errorField": "allowedAssetTypes"
         }
       ]
     }
   ]
 }
}
```

# Metadata response object

Together with the details of the submitted rule(s), the status of the Policy submission, and the `checkResult` object, the Policy response object holds a few important metadata details:

* `editedAt`: the timestamp of receiving the Policy edit request
* `editedBy`: the user ID submitting the Policy
* `publishedAt`: the timestamp of publishing the Policy
* `publishedBy`: the user ID that published the Policy

Example Metadata object details that are a part of the Policy Response object:

```yaml theme={"system"}
 "metadata": {
 "editedAt": 1708865838000,
 "editedBy": "a54eb4b7-6a90-2e26-50c1-94369aa00177",
 "publishedAt": 1708865838314,
 "publishedBy": "a54eb4b7-6a90-2e26-50c1-94369aa00177"
}
```

# Policy examples

* Transfer OTA
* Transfer accumulated
* Contract Call

The following JSON sequence shows a set of transfer rules demonstrating the usage of `designatedSigners`, `authorizationGroups`, and operators (initiators) in an individual/group/combined configuration. Also, notice that `dstAddressType` matches the specific destination type.

The flow in this example shows:

* A separate handling of One-time Address destinations, requiring special approvals and signature.
* Four consecutive rules that define permitted transfers to whitelisted destinations for:
  * Overall accumulation which blocks deviating transfers.
  * Requirement of special approvals for single transactions above a certain amount and between specific sets of venues.
  * Definition of the most permitted transfer rule for transactions that do not match preceding rules.

<img alt="" />

```json theme={"system"}
{
 "draftResponse": {
     "draftId": "0f8f98d8-43d8-4b68-b167-9b1e35c99e2e",
     "status": "UNVALIDATED",
     "rules": [
         {
             "dst": {
                 "ids": [
                     [
                         "*"
                     ]
                 ]
             },
             "src": {
                 "ids": [
                     [
                         "*",
                         "VAULT",
                         "*"
                     ]
                 ]
             },
             "type": "TRANSFER",
             "asset": "*",
             "action": "2-TIER",
             "amount": "0",
             "operators": {
                 "usersGroups": [
                     "5a325451-d970-4dd0-87e4-ae2c54936f4f"
                 ]
             },
             "periodSec": 0,
             "amountScope": "SINGLE_TX",
             "amountCurrency": "USD",
             "dstAddressType": "ONE_TIME",
             "applyForApprove": false,
             "transactionType": "TRANSFER",
             "allowedAssetTypes": "FUNGIBLE",
             "designatedSigners": {
                 "users": [
                     "316c2789-e8f0-45a3-9d2f-16cfec340a10"
                 ],
                 "usersGroups": [
                     "5a325451-d970-4dd0-87e4-ae2c54936f4f"
                 ]
             },
             "externalDescriptor": "{\"id\":\"ca863088-718b-4516-820c-3d06e80c4aad\"}",
             "authorizationGroups": {
                 "logic": "OR",
                 "groups": [
                     {
                         "th": 2,
                         "users": [
                             "9e165261-cffc-4a7f-9f7e-3ed515cfbf16"
                         ],
                         "usersGroups": [
                             "5a325451-d970-4dd0-87e4-ae2c54936f4f"
                         ]
                     }
                 ],
                 "allowOperatorAsAuthorizer": false
             }
         },
         {
             "dst": {
                 "ids": [
                     [
                         "*"
                     ]
                 ]
             },
             "src": {
                 "ids": [
                     [
                         "*"
                     ]
                 ]
             },
             "type": "TRANSFER",
             "asset": "*",
             "action": "BLOCK",
             "amount": "10000000",
             "operators": {
                 "usersGroups": [
                     "5a325451-d970-4dd0-87e4-ae2c54936f4f"
                 ]
             },
             "periodSec": 86400,
             "amountScope": "TIMEFRAME",
             "amountCurrency": "USD",
             "dstAddressType": "WHITELISTED",
             "applyForApprove": false,
             "transactionType": "TRANSFER",
             "allowedAssetTypes": "FUNGIBLE",
             "amountAggregation": {
                 "operators": "ACROSS_ALL_MATCHES",
                 "dstTransferPeers": "ACROSS_ALL_MATCHES",
                 "srcTransferPeers": "ACROSS_ALL_MATCHES"
             },
             "externalDescriptor": "{\"id\":\"b4c22327-e0cb-4a8b-9d81-7e352ab4e213\"}"
         },
         {
             "dst": {
                 "ids": [
                     [
                         "*",
                         "UNMANAGED"
                     ],
                     [
                         "*",
                         "EXCHANGE",
                         "*"
                     ],
                     [
                         "*",
                         "NETWORK_CONNECTION",
                         "*"
                     ]
                 ]
             },
             "src": {
                 "ids": [
                     [
                         "*",
                         "VAULT",
                         "*"
                     ],
                     [
                         "*",
                         "EXCHANGE",
                         "KRAKEN"
                     ]
                 ]
             },
             "type": "TRANSFER",
             "asset": "*",
             "action": "2-TIER",
             "amount": "100000",
             "operators": {
                 "usersGroups": [
                     "5a325451-d970-4dd0-87e4-ae2c54936f4f"
                 ]
             },
             "periodSec": 0,
             "amountScope": "SINGLE_TX",
             "amountCurrency": "USD",
             "dstAddressType": "WHITELISTED",
             "applyForApprove": false,
             "transactionType": "TRANSFER",
             "allowedAssetTypes": "FUNGIBLE",
             "externalDescriptor": "{\"id\":\"ea2a03cc-05da-4bdc-a119-4ba23798ed22\"}",
             "authorizationGroups": {
                 "logic": "OR",
                 "groups": [
                     {
                         "th": 1,
                         "users": [
                             "9e165261-cffc-4a7f-9f7e-3ed515cfbf16",
                             "316c2789-e8f0-45a3-9d2f-16cfec340a10"
                         ],
                         "usersGroups": [
                             "5a325451-d970-4dd0-87e4-ae2c54936f4f"
                         ]
                     }
                 ],
                 "allowOperatorAsAuthorizer": false
             }
         },
         {
             "dst": {
                 "ids": [
                     [
                         "*"
                     ]
                 ]
             },
             "src": {
                 "ids": [
                     [
                         "*"
                     ]
                 ]
             },
             "type": "TRANSFER",
             "asset": "*",
             "action": "ALLOW",
             "amount": "0",
             "operators": {
                 "usersGroups": [
                     "5a325451-d970-4dd0-87e4-ae2c54936f4f"
                 ]
             },
             "periodSec": 0,
             "amountScope": "SINGLE_TX",
             "amountCurrency": "USD",
             "dstAddressType": "WHITELISTED",
             "applyForApprove": false,
             "transactionType": "TRANSFER",
             "allowedAssetTypes": "FUNGIBLE",
             "externalDescriptor": "{\"id\":\"3972a016-6903-4eb6-85f4-07192392f82f\"}"
         }
     ],
     "metadata": {
         "editedBy": "316c2789-e8f0-45a3-9d2f-16cfec340a10",
         "editedAt": "2024-02-18T16:19:51.000Z"
     }
 },
 "validation": {
     "status": "SUCCESS",
     "checkResult": {
         "errors": 0,
         "results": [
             {
                 "index": 0,
                 "externalDescriptor": "{\"id\":\"ca863088-718b-4516-820c-3d06e80c4aad\"}",
                 "status": "ok",
                 "errors": []
             },
             {
                 "index": 1,
                 "externalDescriptor": "{\"id\":\"b4c22327-e0cb-4a8b-9d81-7e352ab4e213\"}",
                 "status": "ok",
                 "errors": []
             },
             {
                 "index": 2,
                 "externalDescriptor": "{\"id\":\"ea2a03cc-05da-4bdc-a119-4ba23798ed22\"}",
                 "status": "ok",
                 "errors": []
             },
             {
                 "index": 3,
                 "externalDescriptor": "{\"id\":\"3972a016-6903-4eb6-85f4-07192392f82f\"}",
                 "status": "ok",
                 "errors": []
             }
         ]
     }
 }
}
```

The next JSON example demonstrates similar sets of rules which can be placed within your Policy, according to the first-match principle, to allow web3 interactions.

The flow in this example shows:

* A permissive rule for Contract Calls performed from a specific vault designated to whitelisted contracts
* A Contract Call rule that allows other vaults to interact with whitelisted contracts upon approval
* A rule that allows users to interact with non-whitelisted contracts with more restrictive approvals

<img alt="" />

```json theme={"system"}
{
 "policy": {
   "rules": [
     {
       "dst": {
         "ids": [
           [
             "*",
             "UNMANAGED",
             "CONTRACT"
           ]
         ]
       },
       "src": {
         "ids": [
           [
             "0",
             "VAULT",
             "*"
           ]
         ]
       },
       "type": "TRANSFER",
       "asset": "*",
       "action": "ALLOW",
       "amount": 0,
       "operators": {
         "usersGroups": [
           "5a325451-d970-4dd0-87e4-ae2c54936f4f"
         ]
       },
       "periodSec": 0,
       "amountScope": "SINGLE_TX",
       "amountCurrency": "USD",
       "dstAddressType": "WHITELISTED",
       "applyForApprove": true,
       "transactionType": "CONTRACT_CALL",
       "allowedAssetTypes": "FUNGIBLE",
       "applyForDeployment": false,
       "externalDescriptor": "{\"id\":\"3972a016-6903-4eb6-85f4-07192392f82f\"}",
       "applyForTypedMessage": true
     },
     {
       "dst": {
         "ids": [
           [
             "*",
             "UNMANAGED",
             "CONTRACT"
           ]
         ]
       },
       "src": {
         "ids": [
           [
             "*",
             "VAULT",
             "*"
           ]
         ]
       },
       "type": "TRANSFER",
       "asset": "*",
       "action": "2-TIER",
       "amount": 0,
       "operators": {
         "usersGroups": [
           "5a325451-d970-4dd0-87e4-ae2c54936f4f"
         ]
       },
       "periodSec": 0,
       "amountScope": "SINGLE_TX",
       "amountCurrency": "USD",
       "dstAddressType": "WHITELISTED",
       "applyForApprove": true,
       "transactionType": "CONTRACT_CALL",
       "allowedAssetTypes": "FUNGIBLE",
       "applyForDeployment": false,
       "externalDescriptor": "{\"id\":\"059c0bb7-807a-4de2-a250-bc933e3c8969\"}",
       "authorizationGroups": {
         "logic": "OR",
         "groups": [
           {
             "th": 1,
             "usersGroups": [
               "5a325451-d970-4dd0-87e4-ae2c54936f4f"
             ]
           }
         ],
         "allowOperatorAsAuthorizer": false
       },
       "applyForTypedMessage": true
     },
     {
       "dst": {
         "ids": [
           [
             "*"
           ]
         ]
       },
       "src": {
         "ids": [
           [
             "*",
             "VAULT",
             "*"
           ]
         ]
       },
       "type": "TRANSFER",
       "asset": "*",
       "action": "2-TIER",
       "amount": 0,
       "operators": {
         "usersGroups": [
           "5a325451-d970-4dd0-87e4-ae2c54936f4f"
         ]
       },
       "periodSec": 0,
       "amountScope": "SINGLE_TX",
       "amountCurrency": "USD",
       "dstAddressType": "ONE_TIME",
       "applyForApprove": true,
       "transactionType": "CONTRACT_CALL",
       "allowedAssetTypes": "FUNGIBLE",
       "applyForDeployment": false,
       "externalDescriptor": "{\"id\":\"ee775834-e46c-4413-a713-de114c0193eb\"}",
       "authorizationGroups": {
         "logic": "OR",
         "groups": [
           {
             "th": 2,
             "usersGroups": [
               "5a325451-d970-4dd0-87e4-ae2c54936f4f"
             ]
           }
         ],
         "allowOperatorAsAuthorizer": false
       },
       "applyForTypedMessage": true
     }
   ],
   "metadata": {
     "publishedBy": "316c2789-e8f0-45a3-9d2f-16cfec340a10",
     "publishedAt": 1710168706517
   }
 },
 "validation": {
   "status": "SUCCESS",
   "checkResult": {
     "errors": 0,
     "results": [
       {
         "index": 0,
         "externalDescriptor": "{\"id\":\"3972a016-6903-4eb6-85f4-07192392f82f\"}",
         "status": "ok",
         "errors": []
       },
       {
         "index": 1,
         "externalDescriptor": "{\"id\":\"059c0bb7-807a-4de2-a250-bc933e3c8969\"}",
         "status": "ok",
         "errors": []
       },
       {
         "index": 2,
         "externalDescriptor": "{\"id\":\"ee775834-e46c-4413-a713-de114c0193eb\"}",
         "status": "ok",
         "errors": []
       }
     ]
   }
 }
}
```


# Configure Webhook URLs
Source: https://developers.fireblocks.com/reference/configure-webhook-urls



> **Deprecation notice**
>
> Webhooks v1 will be deprecated on **June 15th, 2026**. Please use the Developer Center in the Fireblocks Console to upgrade to Webhooks V2, which offers improved reliability, performance, and observability.

Follow these steps in the Fireblocks Console:

1. Navigate to **Settings** > **General**, then scroll down to the **Configure Webhook URL** heading and select **Manage URLs**.
2. In the **Configure Webhook URL** window, enter a URL to define the HTTPS endpoint, then press **Enter**.
3. Select **Save**

> **Webhook URL requirement**
>
> Each webhook URL must be a complete, globally available HTTPS address (e.g., `https://example.com`).

Once your Webhook is connected to your Fireblocks workspace, you will start receiving notifications on events in that workspace.


# Consolidate UTXOs
Source: https://developers.fireblocks.com/reference/consolidate-utxos



# Overview

If you regularly run operations on the Bitcoin blockchain, you will likely notice that the list of UTXOs in your wallets grows very quickly. This is especially common in situations where you have multiple addresses used to consolidate into an omnibus account or just as part of an ongoing operation. This can be a major problem for retail-facing operations.

A process utilized by most companies is "consolidating UTXOs", or creating a transaction that will take many small unspent UTXOs and turn them into a single bigger UTXO.

This is done by creating an "internal" transaction within your own vault account that takes the maximum amount of inputs (250) and turns them into a single output.

Although Bitcoin is the most popular UTXO blockchain, this limitation applies to Bitcoin Cash, Bitcoin SV, Dash, Litecoin, ZCash, and a maximum of 110 inputs for Cardano.

# Example

The logic to decide which unspent UTXOs to use can be as simple or complex as you wish, but in this example, we will use any small unspent UTXO that has received enough confirmations.

We have 3 steps in the process of consolidating UTXOs:

1. Retrieve the max spendable amount for a specific wallet.
2. This will result in an amount that considers up to 250 UTXOs within the wallet (by default, from smallest to biggest).
3. Create a transaction with the amount provided.

```javascript theme={"system"}
const getMaxSpendableAmount = async (
  assetId: string,
  vaultAccountId: string,
): Promise<GetMaxSpendableAmountResponse | undefined> => {
  try {
    const maxSpendableAmount = await fireblocks.vaults.getMaxSpendableAmount({
      vaultAccountId,
      assetId,
    });
    console.log(
      JSON.stringify(maxSpendableAmount.data.maxSpendableAmount, null, 2),
    );
    return maxSpendableAmount.data;
  } catch (error) {
    console.error(error);
  }
};

let transactionPayload = {};

const consolidateWallet = async (
  assetId: string,
  vaultAccountId: string,
  treasuryVault: string,
): Promise<CreateTransactionResponse | undefined> => {
  const amount = await getMaxSpendableAmount(assetId, vaultAccountId);
  transactionPayload = {
    assetId,
    amount: amount?.maxSpendableAmount,
    source: {
      type: TransferPeerPathType.VaultAccount,
      id: vaultAccountId,
    },
    destination: {
      type: TransferPeerPathType.VaultAccount,
      id: treasuryVault,
    },
  };
  console.log(JSON.stringify(transactionPayload, null, 2));
  try {
    const result = await fireblocks.transactions.createTransaction({
      transactionRequest: transactionPayload,
    });
    console.log(JSON.stringify(result.data, null, 2));
    return result.data;
  } catch (error) {
    console.error(error);
  }
};
getMaxSpendableAmount("BTC", "2");
consolidateWallet("BTC", "2", "0");
```

```javascript theme={"system"}
async function consolidate(vaultAccountId, assetId, treasuryVault){
    let amountToConsolidate = await fireblocks.getMaxSpendableAmount(vaultAccountId, assetId).maxSpendableAmount
    const payload = {
        assetId,
        amount: amountToConsolidate.maxSpendableAmount,
        source: {
            type: PeerType.VAULT_ACCOUNT,
            id: vaultAccountId
        },
        destination: {
            type: PeerType.VAULT_ACCOUNT,
            id: treasuryVault
        },
    };
    const result = await fireblocks.createTransaction(payload);
    console.log(JSON.stringify(result, null, 2));
 }
 consolidate("0", "BTC", "1");
```

```python theme={"system"}
from  fireblocks_sdk import TransferPeerPath, DestinationTransferPeerPath

def consolidate(vault_id: str, asset: str, treasury_id: str):
  amountToConsolidate = fireblocks.get_max_spendable_amount(vault_id, asset)["maxSpendableAmount"]

  fireblocks.create_transaction(
     asset_id=asset,
     amount=amountToConsolidate,
     source=TransferPeerPath(VAULT_ACCOUNT, vault_id),
     destination=DestinationTransferPeerPath(VAULT_ACCOUNT, treasury_id)
  )

 consolidate("0", "BTC", "1");
```

Retrieving the maximum spendable amount for consolidation is used through the getMaxSpendableAmount endpoint.

Do note you need the `vaultId` and `assetId`.

Once we create a transaction with the specified amount, Fireblocks automatically selects all of the inputs (smallest to biggest) to consolidate. You can [contact Fireblocks Support](https://support.fireblocks.io/hc/en-us/requests/new) in order to change the default consolidation selection method and reverse it to a selection going from largest to smallest.

> **UTXO consolidation to source**
>
> You can send a transaction to yourself, thus just consolidating the UTXOs without sending them outwards.


# Webhooks v1
Source: https://developers.fireblocks.com/reference/consume-webhooks



> **Deprecation notice**
>
> Webhooks v1 will be deprecated on **June 15th, 2026**. Please use the Developer Center in the Fireblocks Console to upgrade to Webhooks V2, which offers improved reliability, performance, and observability.

## Overview

Webhooks provide real-time notifications for events happening within your Fireblocks workspace, such as incoming and outgoing transactions, transaction status updates, and the addition of new vault accounts, contract wallets, internal wallets, or external wallets. By configuring webhooks, you can 'listen' for these events at your chosen URL, ensuring that all relevant event types are broadcast to your designated endpoint.

Using webhooks offers several benefits, particularly for event-driven development. They enable immediate awareness of critical events, allowing your systems to respond quickly and automatically to changes in your workspace. This real-time monitoring enhances operational efficiency, as it can trigger automated workflows, updates, or alerts based on the specific events received. Webhooks also facilitate seamless integration with your existing applications, enabling more dynamic and responsive interactions between your Fireblocks workspace and other platforms.

When implementing webhooks, consider the reliability and scalability of the receiving endpoint. Ensure that your system can handle the volume of incoming events and process them efficiently.

If notifications are missed due to any issue, Fireblocks offers the following API endpoints for resending webhook notifications:

* [Resend failed webhooks](/reference/resendwebhooks) - Resends all failed webhook notifications
* [Resend webhooks for a transaction by ID](/reference/resendtransactionwebhooks) - Resends webhook notifications for a transaction by its unique identifier

**Key Features**:

* **Event Ordering** - Webhook events are sent in order with a 10-second delay.
* **Retry Logic** - Missed Webhooks are retried every 5, 15, 35, 75, 155, 315, 635, 1275, 2555 (in seconds).

## Payload Structure

We have a standard payload structure that we implement throughout, as shown below:

| Parameter | Type   | Description                                        |
| --------- | ------ | -------------------------------------------------- |
| type      | string | The event type. For example: `VAULT_ACCOUNT_ADDED` |
| tenantId  | string | Unique ID of your Fireblocks workspace             |
| timestamp | number | Timestamp in milliseconds                          |
| data      | object | Object details                                     |

Below is a sample of the payload response:

```json theme={"system"}
{
    "type": "TRANSACTION_CREATED",
    "tenantId”:  ".........-.....-....-....-...........",
    "timestamp": 1679651214621,
    "data": {
        "id": "........-....-....-....-............",
        "createdAt": 1679651104380,
        "lastUpdated": 1679651104380,
        "assetId": "WETH_TEST3",
        "source": {
            "id": "0",
            "type": "VAULT_ACCOUNT",
            "name": "Main",
            "subType": ""
        },
        "destination": {
            "id": "12",
            "type": "VAULT_ACCOUNT",
            "name": "MintBurn",
            "subType": ""
        },
        "amount": 0.001,
        "sourceAddress": "",
        "destinationAddress": "",
        "destinationAddressDescription": "",
        "destinationTag": "",
        "status": "SUBMITTED",
        "txHash": "",
        "subStatus": "",
        "signedBy": [],
        "createdBy": ".........-.....-....-....-...........",
        "rejectedBy": "",
        "amountUSD": null,
        "addressType": "",
        "note": "",
        "exchangeTxId": "",
        "requestedAmount": 0.001,
        "feeCurrency": "ETH_TEST3",
        "operation": "TRANSFER",
        "customerRefId": null,
        "amountInfo": {
            "amount": "0.001",
            "requestedAmount": "0.001"
        },
        "feeInfo": {},
        "destinations": [],
        "externalTxId": null,
        "blockInfo": {},
        "signedMessages": [],
        "assetType": "ERC20"
    }
}
```

## Event Types

| Category                             | Event Type                                 |
| ------------------------------------ | ------------------------------------------ |
| Transactions                         | TRANSACTION\_CREATED                       |
| Transactions                         | TRANSACTION\_STATUS\_UPDATED               |
| Transactions                         | TRANSACTION\_APPROVAL\_STATUS\_UPDATED     |
| Internal, External & Contract Wallet | EXTERNAL\_WALLET\_ASSET\_ADDED             |
| Internal, External & Contract Wallet | EXTERNAL\_WALLET\_ASSET\_REMOVED           |
| Internal, External & Contract Wallet | INTERNAL\_WALLET\_ASSET\_ADDED             |
| Internal, External & Contract Wallet | INTERNAL\_WALLET\_ASSET\_REMOVED           |
| Internal, External & Contract Wallet | CONTRACT\_WALLET\_ASSET\_ADDED             |
| Internal, External & Contract Wallet | CONTRACT\_WALLET\_ASSET\_REMOVED           |
| Vault                                | VAULT\_ACCOUNT\_ADDED                      |
| Vault                                | VAULT\_ACCOUNT\_ASSET\_ADDED               |
| Vault                                | VAULT\_BALANCE\_UPDATE                     |
| NFT                                  | NFT\_BALANCE\_CHANGED                      |
| Exchange & Fiat Account              | EXCHANGE\_ACCOUNT\_ADDED                   |
| Exchange & Fiat Account              | FIAT\_ACCOUNT\_ADDED                       |
| Network Connection                   | NETWORK\_CONNECTION\_ADDED                 |
| Smart Transfer                       | TICKET\_CREATED                            |
| Smart Transfer                       | TICKET\_SUBMITTED                          |
| Smart Transfer                       | TICKET\_EXPIRED                            |
| Smart Transfer                       | TICKET\_CANCELED                           |
| Smart Transfer                       | TICKET\_FULFILLED                          |
| Smart Transfer                       | TICKET\_COUNTERPARTY\_ADDED                |
| Smart Transfer                       | TICKET\_COUNERPARTY\_EXTERNAL\_ID\_SET     |
| Smart Transfer                       | TICKET\_NOTE\_ADDED                        |
| Smart Transfer                       | TICKET\_EXPIRES\_IN\_SET                   |
| Smart Transfer                       | TICKET\_EXPIRES\_AT\_SET                   |
| Smart Transfer                       | TICKET\_TERM\_ADDED                        |
| Smart Transfer                       | TICKET\_TERM\_UPDATED                      |
| Smart Transfer                       | TICKET\_TERM\_DELETED                      |
| Smart Transfer                       | TICKET\_TERM\_FUNDED                       |
| Smart Transfer                       | TICKET\_TERM\_MANUALLY\_FUNDED             |
| Smart Transfer                       | TICKET\_TERM\_FUNDING\_CANCELED            |
| Smart Transfer                       | TICKET\_TERM\_FUNDING\_COMPLETED           |
| Smart Transfer                       | TICKET\_TERM\_TRANSACTION\_STATUS\_CHANGED |
| Off Exchange                         | SETTLEMENT\_CREATED                        |
| Off Exchange                         | COLLATERAL\_SIGNER\_READY\_EVENT           |

## IP Whitelisting

Whitelisting Webhook IP addresses is optional but recommended. Webhooks are sent from the following IPs:

* **US environment:** 3.134.25.131
* **EU environment:** 3.72.125.45, 18.184.217.45, 18.198.71.192


# Contract Objects
Source: https://developers.fireblocks.com/reference/contract-objects



## ContractAsset

| Parameter      | Type                      | Description                                                                                                                  |
| -------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| id             | string                    | The ID of the contract wallet.                                                                                               |
| balance        | string                    | The balance of the contract wallet.                                                                                          |
| lockedAmount   | string                    | Locked amount in the contract wallet.                                                                                        |
| status         | ConfigChangeRequestStatus | Status of the contract wallet.                                                                                               |
| activationTime | string                    | The time the contract wallet will be activated in case wallet activation is postponed according to the workspace definition. |
| address        | string                    | The address of the contract wallet.                                                                                          |
| tag            | string                    | Used as destination tag for XRP; `memo` for ATOM, EOS, HBAR, LUNA, LUNC, XDB, XEM; `memo_text` for XLM; `notes` for ALGO.    |

***

## UnmanagedContract

| Parameter | Type                                             | Description                                                    |
| --------- | ------------------------------------------------ | -------------------------------------------------------------- |
| id        | string                                           | The ID of the unmanaged contract wallet.                       |
| name      | string                                           | Name of the contract wallet container.                         |
| assets    | Array of [ContractAsset](#contractasset) objects | An array of assets available in the unmanaged contract wallet. |


# Securing communication
Source: https://developers.fireblocks.com/reference/cosigner-callbackhandler-secure-communication-authentication



## Authenticating the Callback Handler Response Object

When setting up the Callback Handler server for an API user paired with the Co-signer, you can choose between five options to secure the communication between them.

This selection determines the payload structure of the POST request sent by the Co-signer to the Callback Handler server. It also defines how the request is authenticated by the Callback Handler. More details are provided below.

***

## Option 1: Public key authentication

In this option, the Co-signer and the Callback Handler exchange JSON Web Token (JWT) encoded messages, each signed with their respective private keys. The Co-signer's POST request to the Callback Handler server and the Callback Handler's response to the Co-signer are authenticated using their corresponding public keys.

### JWT-encoded signed request

* The Co-signer, acting as a client of the Callback Handler server, sends a POST request and uses its private key to sign the JWT-encoded message.
* The Callback Handler uses the Co-signer's public key to authenticate the message and ensure it originated from the Co-signer.
* You can retrieve the Co-signer's public key directly from the Co-signer ([see the guides](/reference/api-cosigner-maintenance)).

> **Note:** The same Co-signer private key is used to sign request messages sent to the Callback Handler server for all API users paired with this Co-signer.

### JWT-encoded signed response

* The Callback Handler responds with a JWT-encoded message signed with its private key.
* The Co-signer uses the Callback Handler's public key to authenticate the message and ensure it originated from it.
* You provide the API user's Callback Handler public key to the Co-signer during installation or while configuring the Callback Handler for that API user. This public key corresponds to the private key used by the Callback Handler to sign JWT-encoded response messages.

Follow these steps to generate a private-public key pair for signing JWT-encoded responses. This allows the Co-signer to authenticate your Callback Handler's responses using the corresponding public key:

1. Generate a private key using the following command:

```bash theme={"system"}
openssl genrsa -out callback_private.pem 2048
```

> **Note:** Only RSA 2048 bit keys are supported for public key Callback Handler response authentication.

2. Export the public key from the previously generated private key using the following command:

```bash theme={"system"}
openssl rsa -in callback_private.pem -outform PEM -pubout -out callback_public.pem
```

3. Use this public key to configure the Co-signer's Callback Handler for the specified API user.
4. Set up the Callback Handler as an HTTPS server using a certificate signed by a trusted Certificate Authority (CA). Configure the Callback Handler endpoints to **include** a `/v2` prefix in their URLs:

> `https://your_callback_base_url/v2/tx_sign_request`
> or
> `https://your_callback_base_url/v2/config_change_sign_request`

### Communication channel security

TLS communication between the Co-signer and the Callback Handler server requires the Callback Handler to operate as an HTTPS server with a certificate signed by a trusted Certificate Authority (CA).

***

## Option 2: Self-Signed Certificate-based communication (Certificate pinning)

In this option, a self-signed certificate or a certificate signed by a trusted Certificate Authority (CA) is used to establish certificate-pinning-based secure communication between the Co-signer and the Callback Handler. TLS certificate authentication occurs during SSL negotiation and is based on the certificate you provide to the Co-signer.

The certificate is provided to the Co-signer during installation or while configuring the Callback Handler for a specific API user. In this setup, both the Co-signer's POST request to the Callback Handler server and the server's response are in JSON format, instead of using signed JWTs.

Create a certificate and sign it yourself or have it signed by a trusted CA; set up an HTTPS server and configure your Callback Handler endpoints to respond to requests that **do not include** a `/v2` prefix:

> `https://your_callback_base_url/tx_sign_request`
> or
> `https://your_callback_base_url/config_change_sign_request`

***

## Option 3: Root-CA Certificate-based communication

> **Note:**
>
> This feature requires Co-signers version 2025.12.11 or newer.

In this option, a Root-CA certificate is used to establish certificate-based secure communication between the Co-signer and the Callback Handler. TLS certificate authentication occurs during SSL negotiation and is based on the Root-CA certificate you provide to the Co-signer.

The Root-CA certificate is provided to the Co-signer during installation or while configuring the Callback Handler for a specific API user. A certificate that was signed by the Root-CA needs to be provided to the Co-signer by the Callback Handler during the TLS certificate authentication.

In this setup, both the Co-signer's POST request to the Callback Handler server and the server's response are in JSON format, instead of using signed JWTs.

Create a certificate and have it signed by the Root-CA; set up an HTTPS server and configure your Callback Handler endpoints to respond to requests that **do not include** a `/v2` prefix:

> `https://your_callback_base_url/tx_sign_request`
> or
> `https://your_callback_base_url/config_change_sign_request`

***

## Option 4: Hybrid - Public key authentication with certificate pinning

> **Note:**
>
> This feature requires Co-signer version 2025.12.11 or newer and is currently supported only by the SGX cosigner.

This hybrid option combines the message-level security of Option 1(public key authentication) with the transport-level security of Option 2 (certificate pinning).

In this configuration:

* **TLS Layer**: The secure TLS connection is established using certificate pinning with a self-signed certificate or a certificate signed by a trusted Certificate Authority (CA), as described in Option 2.
* **Message Layer**: Communication messages are exchanged as JWT-encoded messages signed with private keys, exactly as described in Option 1.

This approach provides dual-layer security:

1. The TLS handshake authenticates the Callback Handler server using the pinned certificate
2. The JWT signatures authenticate individual messages using public key cryptography

### Configuration steps:

1. Create a certificate and sign it yourself or have it signed by a trusted CA

2. Provide the certificate to the Co-signer during installation or while configuring the Callback Handler for the specific API user

3. Generate and configure JWT signing keys as described in Option 1:
   1. Generate a private-public key pair for the Callback Handler
   2. Provide the public key to the Co-signer for JWT verification

4. Configure your Callback Handler endpoints to include a /v2 prefix (as in Option 1):

   > `https://your_callback_base_url/v2/tx_sign_request`
   > or
   > `https://your_callback_base_url/v2/config_change_sign_request`

5. Implement your Callback Handler to:
   1. Accept JWT-encoded requests from the Co-signer
   2. Respond with JWT-encoded messages signed with your private key

***

## Option 5: Hybrid - Public key authentication with Root-CA certificate

> **Note:**
>
> This feature requires Co-signer version 2025.12.11 or newer and is currently supported only by the SGX cosigner.

This hybrid option combines the message-level security of Option 1(public key authentication) with the transport-level security of Option 3 (Root-CA certificate validation).

In this configuration:

* **TLS Layer**: The secure TLS connection is established using Root-CA certificate validation, as described in Option 3.
* **Message Layer**: Communication messages are exchanged as JWT-encoded messages signed with private keys, exactly as described in Option 1.

This approach provides dual-layer security:

1. The TLS handshake authenticates the Callback Handler server using Root-CA certificate validation
2. The JWT signatures authenticate individual messages using public key cryptography

### Configuration steps:

1. Create a certificate and have it signed by your Root-CA

2. Provide the Root-CA certificate to the Co-signer during installation or while configuring the Callback Handler for the specific API user

3. Generate and configure JWT signing keys as described in Option 1:

   1. Generate a private-public key pair for the Callback Handler
   2. Provide the public key to the Co-signer for JWT verification

4. Configure your Callback Handler endpoints to include a `/v2` prefix (as in Option 1):

   > `https://your_callback_base_url/v2/tx_sign_request`
   > or
   > `https://your_callback_base_url/v2/config_change_sign_request`

5. Implement your Callback Handler to:

   1. Accept JWT-encoded requests from the Co-signer
   2. Respond with JWT-encoded messages signed with your private key

> **Note:**
>
> When adding the Callback Handler URL to the Co-signer, you should pass only the base URL + custom relative path.
> The `/v2/tx_sign_request` or `/v2/config_change_sign_request` relative paths will be automatically added upon each request made by the Co-signer.
>
> For example if you exposed the Callback Handler URL in the following path:
> `https://subdomain.example.com/fireblocks/callback_handler/v2/tx_sign_request`
>
> You should configure the following URL in the Co-signer:
> `https://subdomain.example.com/fireblocks/callback_handler`


# Create Omnibus Structure
Source: https://developers.fireblocks.com/reference/create-omnibus-structure



# Overview

For customers who have taken the omnibus account structure, it is important to make sure the vaults are structured accordingly, and there is no bottleneck of transactions within the withdrawal mechanism, for example.

> **Important:**
>
> * **Intermediate vault accounts**: This is the vault account assigned to an end client. Because you could have numerous end clients, you can use the Fireblocks API to automatically generate as many intermediate vault accounts as needed.
> * **Omnibus deposits**: This is the central vault omnibus account where end-client funds are swept and stored.
> * **Withdrawal pool**: These are the vault accounts containing funds allocated for end-client withdrawal requests. More than one withdrawal pool vault account is required due to blockchain limitations.
>
> Make sure you are following the right structure for you by reading the [Create Direct Custody Wallets](/docs/create-direct-custody-wallets) article.

# Understanding Asset Types

Handling your omnibus account correctly requires a clear understanding of the differences between different asset types - UTXO vs Account Based.

Due to the nature of UTXO-based blockchains, the transaction includes the source address for each end client, unlike account-based transactions which require an intermediary vault account.

We will explain the two methodologies separately in this article.

## UTXO Based

### Structure

* In the Omnibus Deposits vault account, you can assign each end client a deposit address (which is derived from the permanent wallet address of the UTXO asset).
* When adding an address for an end client in the Omnibus Deposits vault account, use the [Create a New Deposit Address of an Asset in a Vault Account API call](/reference/createvaultaccountassetaddress)

  and use the `name` parameter to associate the end client's ID, as a prefix or suffix for the name of the vault account.
  The `customerRefId` parameter is the ID for AML providers to associate the owner of funds with transactions and should now be used for other purposes. Both the name of the vault account and the AML customerRefID fields are propagated to every transaction to the end client in your system.

### Deposit

Funds are deposited using the following process:

* The retail platform shares the deposit address with the end client.
* The end client makes a deposit.
* The incoming deposit triggers a webhook notification.
* Your client-facing software automatically notifies the end client that the deposit was successfully received.
* The deposit appears on the Transaction History page.

### Example

```javascript theme={"system"}
const createUTXOWithdrawalVaultAccounts = async (
  assetId: string,
  name: string,
): Promise<Array<{}> | undefined> => {
  const result: Array<{}> = [];

  try {
    const vaultAccount = await fireblocks.vaults.createVaultAccount({
      createVaultAccountRequest: {
        name,
      },
    });

    if (vaultAccount.data) {
      const vaultWallet = await fireblocks.vaults.createVaultAccountAsset({
        vaultAccountId: vaultAccount.data.id as string,
        assetId,
      });

      result.push({
        "Vault Account Name": vaultAccount.data.name,
        "Vault Account ID": vaultAccount.data.id,
        "Asset ID": assetId,
        Address: vaultWallet.data.address,
      });

      console.log(JSON.stringify(result, null, 2));
    }

    return result;
  } catch (error) {
    console.error(error);
  }
};

// Create an omnibus vault account for UTXO based assets
const createOmnibusUTXOAccount = async (
  numOfAddresses: number,
  assetId: string,
): Promise<{} | undefined> => {
  try {
    const myOmnibusVault = await fireblocks.vaults.createVaultAccount({
      createVaultAccountRequest: {
        name: "My Omnibus Vault",
      },
    });

    if (myOmnibusVault.data) {
      const vaultAccountId = myOmnibusVault.data.id as string;

      let result = {};

      await fireblocks.vaults.createVaultAccountAsset({
        vaultAccountId,
        assetId,
      });

      for (let i = 0; i < numOfAddresses; i++) {
        // Generating additional addresses is possible for UTXO based assets only
        await fireblocks.vaults.createVaultAccountAssetAddress({
          assetId,
          vaultAccountId,
          createAddressRequest: {
            description: `UserAddress${i + 1}`,
          },
        });
      }

      const addresses =
        await fireblocks.vaults.getVaultAccountAssetAddressesPaginated({
          vaultAccountId,
          assetId,
        });

      result = {
        "Vault Account Name": myOmnibusVault.data.name,
        "VaultAccount ID": myOmnibusVault.data.id,
        "Asset ID": assetId,
        Addresses: addresses?.data.addresses,
      };

      console.log(JSON.stringify(result, null, 2));

      return result;
    }
  } catch (error) {
    console.error(error);
  }
};
createUTXOWithdrawalVaultAccounts("BTC_TEST", "MyWithdrawalVault");
createOmnibusUTXOAccount(3, "BTC_TEST");
```

```javascript theme={"system"}
// Obtain a list of user identifiers associated with the vault accounts and pass them as a strings inside internalCustRefIds
// each of the internalCustRefIds is concatenated to the vault's name

const internalCustRefIds = ["a","b","c"];
const assetId = "BTC_TEST";

async function createUTXOWithdrawalVaultAccounts(assetId, name){
    vault = await fireblocks.createVaultAccount(name);
    vaultWallet = await fireblocks.createVaultAsset(Number(vault.id), assetId);
    const result = [{"Vault Name": vault.name, "Vault ID": vault.id, "Asset ID": assetId, "Wallet Address": vaultWallet.address}];
    console.log(JSON.stringify(result, null, 2));
    return(result);
}

async function createUTXOOmnibusAccount(amountOfVaultAccounts, assetId, internalCustRefIds){
    let vault;
    let vaultWallet;
    let address = [];

    vault = await fireblocks.createVaultAccount("Omnibus");
    vaultWallet = await fireblocks.createVaultAsset(Number(vault.id), assetId);
    for (let i = 0; i < amountOfVaultAccounts; i++){
        address[i] = await fireblocks.generateNewAddress(Number(vault.id), assetId, "CustomerID_"+internalCustRefIds[i]+"_vault");
    }
    console.log("Created vault account:"+JSON.stringify(vault, null, 2)+" with wallet addresses:"+JSON.stringify(address, null, 2));
    return("Omnibus:", vault, "Addresses:", address);
 }

createUTXOWithdrawalVaultAccounts(assetId, "Withdrawal");
createUTXOOmnibusAccount(2, assetId, internalCustRefIds);
```

```python theme={"system"}
# Obtain a list of user identifiers associated with the vault accounts and pass them as a strings inside internalCustRefIds
# each of the internalCustRefIds is concatenated to the vault's name

ASSET = "BTC_TEST"
CUSTOMER_IDS = ["a", "b", "c"]

def create_utxo_withdrawal_vault(asset: str, name: str):
    vault_id = fireblocks.create_vault_account(name=name)["id"]
    address = fireblocks.create_vault_asset(vault_account_id=vault_id, asset_id=asset)["address"]

    return {name: vault_id}, address

def create_utxo_omnibus_vault(amount: int, asset: str, customer_ids: list, hidden_on_ui: bool = True):
    deposit_address = {}

    vault_id = fireblocks.create_vault_account(name="Omnibus")["id"]
    fireblocks.create_vault_asset(vault_account_id=vault_id, asset_id=asset)
    for i in range(amount):
        address = fireblocks.generate_new_address(vault_account_id=vault_id, asset_id=asset, description=customer_ids[i], hidden_on_ui=hidden_on_ui)["address"]
        deposit_address[customer_ids[i]] = address

    return {"Omnibus": vault_id, "Addresses": deposit_address}

print(create_utxo_withdrawal_vault(ASSET, "Withdrawal"))
print(create_utxo_omnibus_vault(3, ASSET, CUSTOMER_IDS))
```

The above code creates the Omnibus vault and a withdrawal vault, from which we can later on move funds back to end users who would like to settle.

Afterwards, we create a deposit address per end user, while using an available, unique customer ID. The function then returns a dictionary of the newly created vaults and generated deposit addresses.

## Account Based

> **Note**
>
> Do note this section refers to account based assets without a tag / memo capability. You can refer to tag / memo based assets in the next section.

### Structure

* The workspace should contain one or more intermediate vault accounts per end client in addition to a single Omnibus Deposits vault account.

* When adding a vault account, we recommend using the [Create a New Vault Account API call](/reference/createvaultaccount) and use the `name` parameter to associate the end client's ID, as a prefix or suffix for the name of the vault account.

  The `customerRefId` parameter is the ID for AML providers to associate the owner of funds with transactions and should now be used for other purposes. Both the name of the vault account and the AML customerRefID fields are propagated to every transaction to the end client in your system.

* Due to the nature of account-based blockchains, transactions with account-based assets can only be transferred from one account-based address to another account-based address (unlike UTXO, where multiple addresses are included in a single transaction).

### Deposit

Funds are deposited using the following process:

* The end client receives a deposit address.
* The end client makes a deposit.
* The incoming deposit triggers a webhook notification.
* Your client-facing software automatically notifies the end client that the deposit was successfully received.
* The deposit is swept to the Omnibus Deposits vault account. You can see further on the sweeping logic in the [Sweeping within an Omnibus Vault structure](/docs/sweep-funds) article.

### Example

> **Recommended: Set "Hidden Vaults" on**
>
> For the creation of end user vaults, we will usually choose to set **hiddenOnUi** as true, as part of the **createVaultAccount** endpoint.
>
> By default, it is set to false, hence all of the vaults created in this article will be visible in the UI which is not recommended for a very large amount of vaults.
>
> This also means transfers to these vaults won't be visible in the UI, but only programatically.

As the name suggests, the end-user vaults will be serving your end users. If you have followed the structure section, you might have noticed that account based assets require a one-to-one vault per end user.
The treasury vault is a single account where all of the swept assets will move to. You can see more in regarding to sweeping in the following [sweeping article](/docs/sweep-funds).
Lastly, we will also create a few withdrawal vaults in order to distribute our load in regards to settlements, making sure we don't have a bottleneck at the withdrawal part.

We will use the below code in order to perform the following:

1. Create 5 vaults for 5 end users.
2. Create 1 treasury vault.
3. Create 3 withdrawal vaults.

```javascript theme={"system"}
const createAccountBasedVaultAccounts = async (
  vaultAccountNamePrefix: string,
  numOfVaultAccounts: number,
  assetId: string,
  hiddenOnUI: boolean,
  endUserReferences?: string[],
): Promise<Array<{}> | undefined> => {
  try {
    let vaultAccount: FireblocksResponse<VaultAccount>;
    let results: Array<{}> = [];

    for (let i = 0; i < numOfVaultAccounts; i++) {
      if (
        endUserReferences &&
        endUserReferences.length !== numOfVaultAccounts
      ) {
        throw new Error(
          "Number of Vault Accounts does not equal to the number of end user references",
        );
      }

      vaultAccount = await fireblocks.vaults.createVaultAccount({
        createVaultAccountRequest: {
          name: endUserReferences
            ? vaultAccountNamePrefix + "_" + endUserReferences[i]
            : vaultAccountNamePrefix + "_Vault" + String(i + 1),
          hiddenOnUI,
        },
      });

      const vaultAccountId = vaultAccount.data?.id as string;

      const vaultWallet = await fireblocks.vaults.createVaultAccountAsset({
        assetId,
        vaultAccountId,
      });

      const singleVaultResult = {
        "Vault Account": vaultAccount.data?.name,
        "Vault Account ID": vaultAccountId,
        "Asset ID": assetId,
        Address: vaultWallet.data?.address,
      };

      results.push(singleVaultResult);
      console.log(
        `Created Vault Account:\n ${JSON.stringify(singleVaultResult, null, 2)}`,
      );
    }

    return results;
  } catch (error) {
    console.error(error);
  }
};

createAccountBasedVaultAccounts("Deposits", 5, "ETH_TEST5", true, [
  "UserA",
  "UserB",
  "UserC",
  "UserD",
  "UserE",
]);
createAccountBasedVaultAccounts("Treasury", 1, "ETH_TEST5", false);
createAccountBasedVaultAccounts("Withdrawal_Pool", 3, "ETH_TEST5", false);
```

```javascript theme={"system"}
// Obtain a list of user identifiers associated with the vault accounts and pass them as a strings inside internalCustRefIds
// each of the internalCustRefIds is concatenated to the vault's name

const internalCustRefIds = ["a","b","c","d","e"];
const assetId = "ETH_TEST3";

async function createAccountBasedVaultAccounts(vaultAccountNamePrefix, amountOfVaultAccounts, assetId, hiddenOnUI, internalCustRefIds){
    let createVaultRes;
    let vault;
    let vaultWallet;

    for (let i = 0; i < amountOfVaultAccounts; i++){
        if (internalCustRefIds){
            createVaultRes = await fireblocks.createVaultAccount(vaultAccountNamePrefix.toString()+"_"+internalCustRefIds[i]+"_vault", hiddenOnUI);
        }
        else {
            createVaultRes = await fireblocks.createVaultAccount(vaultAccountNamePrefix.toString()+"_"+i.toString()+"_vault", hiddenOnUI);
        }
        vault = {
            vaultName: createVaultRes.name,
            vaultID: createVaultRes.id
        }
        vaultWallet = await fireblocks.createVaultAsset(Number(vault.vaultID), assetId);
        console.log("Created vault account", vault.vaultName,":", "with wallet address:", vaultWallet.address);
    }
 }

createAccountBasedVaultAccounts("Deposits_End_User", 5, assetId, false, internalCustRefIds);
createAccountBasedVaultAccounts("Treasury", 1, assetId, false, undefined);
createAccountBasedVaultAccounts("Withdrawal_pool", 3, assetId, false, undefined);
```

```python theme={"system"}
# Obtain a list of user identifiers associated with the vault accounts and pass them as a strings inside internalCustRefIds
# each of the internalCustRefIds is concatenated to the vault's name

CUSTOMER_IDS = ["a", "b", "c", "d", "e"]
ASSET = "ETH_TEST3"

def create_account_vault_accounts(prefix: str, amount: int, asset_id: str, customer_ids: list, is_hidden: bool = False) -> dict:
  vault_dict = {}

  for index in range(amount):
    if customer_ids:
	    vault_name = f"{prefix}_{customer_ids[index]}_vault"
    else:
      vault_name = f"{prefix}_vault"
    vault_id = fireblocks.create_vault_account(name=vault_name, hidden_on_ui=is_hidden)["id"]
    fireblocks.create_vault_asset(vault_id, )
    vault_dict[vault_name] = vault_id

  return vault_dict

print(create_account_vault_accounts("End-User", 5, ASSET, CUSTOMER_IDS, True))
print(create_account_vault_accounts("Treasury", 1, ASSET))
print(create_account_vault_accounts("Withdrawal", 3, ASSET))
```

In the above code, we have created a function that takes a prefix for the vault name and a number of vaults that we would like to create and also uses the and the internalCustRefIds and `hiddenOnUI` params, if relevant, depending on vault accounts creation purpose.

We then run it three times.

1. For the end user vaults.
2. For the treasury vault.
3. For the withdrawal vault.

## Tag / Memo Based

> **Note**
>
> Although these are basically also account based, they have a special differentiating attribute: the **tag** / **memo**. This helps us identify different customers / accounts within our single wallet, crediting customers in our internal ledger.

### Structure

* In the Omnibus Deposits vault account, you can assign each end client a tag or memo (name varies based on the blockchain).
* When adding an address for an end client in the Omnibus Deposits vault account, use the [Create a New Deposit Address of an Asset in a Vault Account API call](/reference/createvaultaccountassetaddress)

  and use the `name` parameter to associate the end client's ID, as a prefix or suffix for the name of the vault account.
  The `customerRefId` parameter is the ID for AML providers to associate the owner of funds with transactions and should now be used for other purposes. Both the name of the vault account and the AML customerRefID fields are propagated to every transaction to the end client in your system.

### Deposit

Funds are deposited using the following process:

* The end client receives a deposit address and a **tag** or **memo**.
* The end client makes a deposit, using the address and the tag.
* The incoming deposit triggers a webhook notification.
* Your client-facing software automatically notifies the end client that the deposit was successfully received, assuming he passed a **tag** or **memo**.
* All of your funds will be located in the same account, while managing different customer balances in an internal ledger.

### Example

```javascript theme={"system"}
const createTagWithdrawalVaultAccounts = async (
  assetId: string,
  name: string,
): Promise<Array<{}> | undefined> => {
  const result: Array<{}> = [];

  try {
    const vaultAccount = await fireblocks.vaults.createVaultAccount({
      createVaultAccountRequest: {
        name,
      },
    });

    if (vaultAccount.data) {
      const vaultWallet = await fireblocks.vaults.createVaultAccountAsset({
        vaultAccountId: vaultAccount.data.id as string,
        assetId,
      });

      result.push({
        "Vault Account Name": vaultAccount.data.name,
        "Vault Account ID": vaultAccount.data.id,
        "Asset ID": assetId,
        Address: vaultWallet.data.address,
      });

      console.log(JSON.stringify(result, null, 2));
    }

    return result;
  } catch (error) {
    console.error(error);
  }
};

// Create an omnibus vault account for Tag/Memo based assets
const createTagOmnibusAccount = async (
  numOfAddresses: number,
  assetId: string,
): Promise<{} | undefined> => {
  try {
    const myOmnibusVault = await fireblocks.vaults.createVaultAccount({
      createVaultAccountRequest: {
        name: "My Omnibus Vault",
      },
    });

    if (myOmnibusVault.data) {
      const vaultAccountId = myOmnibusVault.data.id as string;

      let result = {};

      await fireblocks.vaults.createVaultAccountAsset({
        vaultAccountId,
        assetId,
      });

      for (let i = 0; i < numOfAddresses; i++) {
        // For Tag/Memo based assets, the address of the wallet is always the same but a new Memo/Tag is generated upon each user
        await fireblocks.vaults.createVaultAccountAssetAddress({
          assetId,
          vaultAccountId,
          createAddressRequest: {
            description: `UserAddress${i + 1}`,
          },
        });
      }

      const addresses =
        await fireblocks.vaults.getVaultAccountAssetAddressesPaginated({
          vaultAccountId,
          assetId,
        });

      result = {
        "Vault Account Name": myOmnibusVault.data.name,
        "VaultAccount ID": myOmnibusVault.data.id,
        "Asset ID": assetId,
        Addresses: addresses?.data.addresses,
      };

      console.log(JSON.stringify(result, null, 2));

      return result;
    }
  } catch (error) {
    console.error(error);
  }
};

createTagWithdrawalVaultAccounts("XLM_TEST", "Withdrawal");
createTagOmnibusAccount(2, "XLM_TEST");
```

```javascript theme={"system"}
// Obtain a list of user identifiers associated with the vault accounts and pass them as a strings inside internalCustRefIds
// each of the internalCustRefIds is concatenated to the vault's name

const internalCustRefIds = ["a","b","c"];
const assetId = "XLM_TEST";

async function createTagWithdrawalVaultAccounts(assetId, name){
    vault = await fireblocks.createVaultAccount(name);
    vaultWallet = await fireblocks.createVaultAsset(Number(vault.id), assetId);
    const result = [{"Vault Name": vault.name, "Vault ID": vault.id, "Asset ID": assetId, "Wallet Address": vaultWallet.address}];
    console.log(JSON.stringify(result, null, 2));
    return(result);
}

async function createTagOmnibusAccount(amountOfVaultAccounts, assetId, internalCustRefIds){
    let vault;
    let vaultWallet;
    let tag = [];

    vault = await fireblocks.createVaultAccount("Omnibus");
    vaultWallet = await fireblocks.createVaultAsset(Number(vault.id), assetId);
    for (let i = 0; i < amountOfVaultAccounts; i++){
        tag[i] = await fireblocks.generateNewAddress(Number(vault.id), assetId, "CustomerID_"+internalCustRefIds[i]+"_vault");
    }
    console.log("Created vault account:"+JSON.stringify(vault, null, 2)+" with wallet tag:"+JSON.stringify(tag, null, 2));
    return("Omnibus:", vault, "Tags:", tag);
 }

createTagWithdrawalVaultAccounts(assetId, "Withdrawal");
 createTagOmnibusAccount(2, assetId, internalCustRefIds);
```

```python theme={"system"}
ASSET = "XLM_TEST"
CUSTOMER_IDS = ["a", "b", "c"]

def create_tag_withdrawal_vault(asset: str, name: str):
    vault_id = fireblocks.create_vault_account(name=name)["id"]
    address = fireblocks.create_vault_asset(vault_account_id=vault_id, asset_id=asset)["address"]

    return {name: vault_id}, address

def create_tag_omnibus_vault(amount: int, asset: str, customer_ids: list, hidden_on_ui: bool = True):
    deposit_tags = {}

    vault_id = fireblocks.create_vault_account(name="Omnibus")
    address = fireblocks.create_vault_asset(vault_account_id=vault_id, asset_id=asset)["address"]
    for i in range(amount):
        tag = fireblocks.generate_new_address(vault_account_id=vault_id, asset_id=asset, description=customer_ids[i], hidden_on_ui=hidden_on_ui)["tag"]
        deposit_tags[customer_ids[i]] = address

    return {"Omnibus": vault_id, "Address": address, "Tags": deposit_tags}

print(create_tag_withdrawal_vault(ASSET, "Withdrawal"))
print(create_tag_omnibus_vault(3, ASSET, CUSTOMER_IDS))
```

The above code creates the Omnibus vault and a withdrawal vault, from which we can later on move funds back to end users who would like to settle.

Afterwards, we create a deposit tag per end user, while using an available, unique customer ID. The function then returns a dictionary of the newly created vaults and generated deposit tags.


# Create a Staking Position
Source: https://developers.fireblocks.com/reference/create-stake



1. [Approve the terms of service](/reference/approvetermsofservicebyproviderid) of your desired staking provider (Kiln or Figment):

```javascript theme={"system"}
const FireblocksSDK = require("fireblocks-sdk").FireblocksSDK;
const fireblocks = new FireblocksSDK(privateKey, apiKey);

const approveRequest = await fireblocks.approveStakingProviderTermsOfService("kiln");
```

2. [Create your staking position](/reference/stake) :

```javascript theme={"system"}
const stakeRequest = await fireblocks.executeStakingStake(
  "SOL",{
		vaultAccountId:"1",
		providerId:"kiln",
		stakeAmount:"100",
		txNote:"stake 100 SOL from vaultId 1, 24 Jan 2024"
  }
);
```

**Important:**
The response object from the staking action includes an ID that serves as the unique identifier for the staking position.
It's essential to save this ID for future reference. If you lose this ID, you can retrieve all the IDs from the staking position in your workspace by using the `fireblocks.getStakingPositions()` function.

## Monitor and sign the staking request

[Find the relevant transaction](/reference/getdelegationbyid) - After creating the staking position, find the new transaction ID using `getStakingPosition(id)`. The transaction ID can be found under `responseBody.relatedTransactions[0].txId`:

```javascript theme={"system"}
const positionId = stakeRequest.id
const position = await fireblocks.getStakingPosition(positionId);

// When creating a new staking position, there is only 1 transaction
const txId = position.relatedTransactions[0].txId

// ... sign it
```

To sign the transaction, please follow the necessary steps outlined. Learn more about the [transaction signing request and approval process](https://support.fireblocks.io/hc/en-us/articles/12006018592156-API-Co-Signer-Overview) .

Once the stake position is created, you can monitor the position status and available actions, such as unstaking or withdrawing, using `getPosition(positionId)`.


# Create Transactions
Source: https://developers.fireblocks.com/reference/create-transactions



# Overview

Every transaction on the Fireblocks platform is initiated using the [Create a new transaction](/reference/createtransaction) API endpoint. Its default operation type is `TRANSFER`. However, other important operations are available as valid values for the `operation` body parameter:

* **TRANSFER:** Transfers funds from one account to another. UTXO blockchains allow multi-input and multi-output transfers. All other blockchains allow transfers with one source address and one destination address.
* **CONTRACT\_CALL:** Calls a smart contract method for Web3 operations on any EVM blockchain.
* **PROGRAM\_CALL:** Calls programs for Web3 operations on the Solana blockchain. Learn more [here](/reference/interact-with-solana-programs#/).
* **TYPED\_MESSAGE:** An off-chain message in either [Ethereum Personal Message](https://geth.ethereum.org/docs/rpc/ns-personal#personal_sign) or EIP-712 format. Used to sign specific readable messages that are not actual transactions.
* **RAW:** An off-chain message with no predefined format. Used to sign any message with your private key, including protocols such as blockchains and custom transaction types not natively supported by Fireblocks.
* **MINT:** Perform a mint operation to increase the supply of a token. Supported for Stellar, Ripple, and EVM-based blockchains.
* **BURN:** Perform a burn operation to reduce the supply of a token. Supported for Stellar, Ripple, and EVM-based blockchains.

The API call serves all possible source and destination combinations, including a one-time address destination (OTA), vault account, pre-whitelisted internal wallet, external wallet & contract wallet, Fireblocks Network connections and any connected exchange account and fiat account.

> **Optional parameters for assets & operations**
>
> Although there are required parameters for the [Create a new transaction](/reference/createtransaction) API call, you can pass other optional body parameters depending on the asset or the required operation.
>
> The endpoint also accepts the addition of the `extraParameters` object, used to describe additional details required for raw message signing, contract calls, and specific UTXO selections.
>
> [Learn how the `extraParameters` object works in transaction responses.](/reference/transaction-objects)

# Your first transaction

## Vault account to vault account transaction

To start, initiate a transaction from one Fireblocks vault account to another. Account-based assets allow single-destination transfers, and UTXO assets allow multi-destination transfers.

### Single destination transfer (ETH)

The example transfers 0.001 amount of ETH from vault account ID `0` to vault account ID `1`.

```javascript theme={"system"}
const transactionPayload = {
  assetId: "ETH",
  amount: "0.001",
  source: {
    type: TransferPeerPathType.VaultAccount,
    id: "0",
  },
  destination: {
    type: TransferPeerPathType.VaultAccount,
    id: "1",
  },
  note: "Your first transaction!",
};

const createTransaction = async (
  transactionPayload: TransactionRequest,
): Promise<CreateTransactionResponse | undefined> => {
  try {
    const transactionResponse = await fireblocks.transactions.createTransaction(
      {
        transactionRequest: transactionPayload,
      },
    );
    console.log(JSON.stringify(transactionResponse.data, null, 2));
    return transactionResponse.data;
  } catch (error) {
    console.error(error);
  }
};

createTransaction(transactionPayload);
```

```javascript theme={"system"}
async function createTransaction(assetId, amount, srcId, destId){
    let payload = {
        assetId,
        amount,
        source: {
            type: PeerType.VAULT_ACCOUNT,
            id: String(srcId)
        },
        destination: {
            type: PeerType.VAULT_ACCOUNT,
            id: String(destId)
        },
        note: "Your first transaction!"
    };
    const result = await fireblocks.createTransaction(payload);
    console.log(JSON.stringify(result, null, 2));
}
createTransaction("ETH", "0.001", "0", "1");
```

```python theme={"system"}
def create_transaction(asset_id, amount, src_id, dest_id):
   tx_result = fireblocks.create_transaction(
       asset_id=asset_id,
       amount=amount,
       source=TransferPeerPath(VAULT_ACCOUNT, src_id),
       destination=DestinationTransferPeerPath(VAULT_ACCOUNT, dest_id),
       note="Your first transaction!"
   )
   print(tx_result)

create_transaction("ETH", "0.001", "0", "1")
```

### Multiple-destination transfer

Transfer 0.001 BTC from the first vault account (`"1"`), by sending 0.0005 BTC to the second vault account (using `id: "2"`) and 0.0005 BTC to the third vault account (`id: "3"`) as destinations.

```javascript theme={"system"}
const transactionPayload = {
  assetId: "BTC",
  amount: "0.001",
  source: {
    type: TransferPeerPathType.VaultAccount,
    id: "1",
  },
  destinations: [
    {
      amount: "0.0005",
      destination: {
        type: TransferPeerPathType.VaultAccount,
        id: "2",
      },
    },
    {
      amount: "0.0005",
      destination: {
        type: TransferPeerPathType.VaultAccount,
        id: "3",
      },
    },
  ],
  note: "Your first multiple destination transaction!",
};

const createTransaction = async (
  transactionPayload: TransactionRequest,
): Promise<CreateTransactionResponse | undefined> => {
  try {
    const transactionResponse = await fireblocks.transactions.createTransaction(
      {
        transactionRequest: transactionPayload,
      },
    );
    console.log(JSON.stringify(transactionResponse.data, null, 2));
    return transactionResponse.data;
  } catch (error) {
    console.error(error);
  }
};
createTransaction(transactionPayload);
```

```javascript theme={"system"}
async function createTransaction(assetId, amount, srcId){
    let payload = {
        assetId,
        amount,
        source: {
            type: PeerType.VAULT_ACCOUNT,
            id: String(srcId)
        },
        destinations: [
            {amount: "0.0005", destination: {type: PeerType.VAULT_ACCOUNT, id: "2"}},
            {amount: "0.0005", destination: {type: PeerType.VAULT_ACCOUNT, id: "3"}}
        ],
        note: "Your first multiple destination transaction!"
    };
    const result = await fireblocks.createTransaction(payload);
    console.log(JSON.stringify(result, null, 2));
}
createTransaction("BTC", "0.001", "1");
```

```python theme={"system"}
def create_transaction(asset_id, amount, src_id):
    tx_result = fireblocks.create_transaction(
        asset_id=asset_id,
        amount=amount,
        source=TransferPeerPath(VAULT_ACCOUNT, src_id),
        destinations=[
            TransactionDestination("0.0005", DestinationTransferPeerPath(VAULT_ACCOUNT, "2")),
            TransactionDestination("0.0005", DestinationTransferPeerPath(VAULT_ACCOUNT, "3"))

        ],
        note="Your first multiple destination transaction!"
    )
    print(tx_result)

create_transaction("BTC", "0.001", "1")
```

## Vault account to one-time address transaction

Transfer 0.01 ETH between the vault account (`"1"`) to a specific one-time blockchain address.

```javascript theme={"system"}
const transactionPayload = {
  assetId: "ETH",
  amount: "0.001",
  source: {
    type: TransferPeerPathType.VaultAccount,
    id: "1",
  },
  destination: {
    type: TransferPeerPathType.OneTimeAddress,
    oneTimeAddress: {
      address: "0x13277a70e3F48EEAD9C8a8bab12EbEDbC3DB6446",
    },
  },
  note: "Your first OTA transaction!",
};

const createTransaction = async (
  transactionPayload: TransactionRequest,
): Promise<CreateTransactionResponse | undefined> => {
  try {
    const transactionResponse = await fireblocks.transactions.createTransaction(
      {
        transactionRequest: transactionPayload,
      },
    );
    console.log(JSON.stringify(transactionResponse.data, null, 2));
    return transactionResponse.data;
  } catch (error) {
    console.error(error);
  }
};
createTransaction(transactionPayload);
```

```javascript theme={"system"}
async function createTransaction(assetId, amount, srcId, address){
    let payload = {
        assetId,
        amount,
        source: {
            type: PeerType.VAULT_ACCOUNT,
            id: String(srcId)
        },
        destination: {
            type: PeerType.ONE_TIME_ADDRESS,
            oneTimeAddress: {
                address: String(address)
            }
        },
        note: "Your first OTA transaction!"
    };
   const result = await fireblocks.createTransaction(payload);
   console.log(JSON.stringify(result, null, 2));
}
createTransaction("ETH", "0.001", "1", "0x13277a70e3F48EEAD9C8a8bab12EbEDbC3DB6446");
```

```python theme={"system"}
def create_transaction(asset_id, amount, src_id, address):
    tx_result = fireblocks.create_transaction(
        asset_id=asset_id,
        amount=amount,
        source=TransferPeerPath(VAULT_ACCOUNT, src_id),
        destination=DestinationTransferPeerPath(ONE_TIME_ADDRESS, None, {"address": address}),
        note="Your first OTA transaction!"
    )
    print(tx_result)

create_transaction("ETH", "0.001", "1", "0x13277a70e3F48EEAD9C8a8bab12EbEDbC3DB6446")
```

> **API idempotency for transactions**
>
> The best practice for creating transactions is to use the `externalTxId` parameter as seen in the [Optional parameters section.](doc:creating-a-transaction#optional-parameters)

## Contract Call Transaction

```javascript theme={"system"}
import { readFileSync } from 'fs';
import {
  Fireblocks,
  BasePath,
  TransactionOperation,
  TransferPeerPathType
} from "@fireblocks/ts-sdk";

// Initialize a Fireblocks API instance with local variables
const FIREBLOCKS_API_SECRET_PATH = "<PATH_TO_YOUR_SECRET>";
const fireblocks = new Fireblocks({
    apiKey: "<API_KEY>",
    basePath: BasePath.US,
    secretKey: readFileSync(FIREBLOCKS_API_SECRET_PATH, "utf8"),
});

(async() => {

  const contractAddress = "0x43506849D7C04F9138D1A2050bbF3A0c054402dd" // USDC contract address
  const contractCallData = "0x095ea7b3000000000000000000000000d09971d8ed6c6a5e57581e90d593ee5b94e348d4ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff" // calling the approve function with some example params

  try{

    const contractCallTransaction = await fireblocks.transactions.createTransaction({
      transactionRequest: {
        operation: TransactionOperation.ContractCall,
        assetId: "ETH",
        source: {
          type: TransferPeerPathType.VaultAccount,
          id: "0"
        },
        destination: {
          type: TransferPeerPathType.OneTimeAddress,
          oneTimeAddress: {
            address: contractAddress
          }
        },
        amount: "0",
        extraParameters: {
          contractCallData
        }
      }
    })

    console.log(JSON.stringify(contractCallTransaction, null, 2))
  } catch(e){
    console.log(e)
  }
})();
```

***

# Optional parameters

Some blockchains have different technicalities when building transactions, handled using optional parameters.

## externalTxId

A *critical* practice to avoid processing multiple identical POST transaction requests more than once is to use the `externalTxId` parameter in the [Create a new transaction](/reference/createtransaction) API call.

The `externalTxId` value is an internal identifier of the transaction that you create and manage on your end.

This value is securely stored in the Fireblocks system, and additional transaction requests with the same `externalTxId` value are not processed on our system. The `externalTxId` is limited to a maximum of 255 characters.

```javascript theme={"system"}
const transactionPayload = {
  assetId: "ETH",
  amount: "0.001",
  externalTxId: "UniqueIdentifier", // the unique identifier of the transaction outside of Fireblocks
  source: {
    type: TransferPeerPathType.VaultAccount,
    id: "0",
  },
  destination: {
    type: TransferPeerPathType.VaultAccount,
    id: "1",
  },
  note: "Your first transaction!",
};

const createTransaction = async (
  transactionPayload: TransactionRequest,
): Promise<CreateTransactionResponse | undefined> => {
  try {
    const transactionResponse = await fireblocks.transactions.createTransaction(
      {
        transactionRequest: transactionPayload,
      },
    );
    console.log(JSON.stringify(transactionResponse.data, null, 2));
    return transactionResponse.data;
  } catch (error) {
    console.error(error);
  }
};
createTransaction(transactionPayload);
```

```javascript theme={"system"}
async function createTransaction(assetId, amount, srcId, destId, externalTxId){
    let payload = {
        assetId,
        amount,
        externalTxId, // the unique identifier of the transaction outside of Fireblocks
        source: {
            type: PeerType.VAULT_ACCOUNT,
         		id: String(srcId)
        },
        destination: {
            type: PeerType.VAULT_ACCOUNT,
        		id: String(destId)
        },
        note: "Your first transaction identified by an external ID"
    };
		const result = await fireblocks.createTransaction(payload);
    console.log(JSON.stringify(result, null, 2));
}
createTransaction("ETH", "0.001", "0", "1", "uniqueTXid");
```

```python theme={"system"}
def create_transaction(asset_id, amount, src_id, dest_id, external_tx_id):
    tx_result = fireblocks.create_transaction(
        asset_id=asset_id,
        amount=amount,
        external_tx_id=external_tx_id, # the unique identifier of the transaction outside of Fireblocks
        source=TransferPeerPath(VAULT_ACCOUNT, src_id),
        destination=DestinationTransferPeerPath(VAULT_ACCOUNT, dest_id),
        note="Your first transaction identified by an external ID"
    )
    print(tx_result)

create_transaction("ETH", "0.001", "0", "1", "uniqueTXid")
```

## treatAsGrossAmount

The value is`false` by default. If it is set to `true`, the network fee is deducted from the requested amount.

> **Note**
>
> If you send the entire vault account balance without the treatAsGrossAmount field, then the transaction amount will be treated as a gross amount.

```javascript theme={"system"}
const transactionPayload = {
	assetId: "ETH",
	amount: "0.001",
	treatAsGrossAmount: true, // true or false (by default - false)
	source: {
		type: TransferPeerPathType.VaultAccount,
		id: "0",
	},
	destination: {
		type: TransferPeerPathType.VaultAccount,
		id: "1",
	},
	note: "Your first treat as gross transaction!"
}

const createTransaction = async (
	transactionPayload:TransactionRequest
):Promise<CreateTransactionResponse | undefined > => {
	try {
		const transactionResponse = await fireblocks.transactions.createTransaction(
			{
				transactionRequest:transactionPayload
			}
		);
		console.log(JSON.stringify(transactionResponse.data, null, 2));
		return transactionResponse.data;
	}
	catch(error){
		console.error(error);
	}
}
createTransaction(transactionPayload);
```

```javascript theme={"system"}
async function createTransaction(assetId, amount, srcId, destId){
    let payload = {
       assetId,
       amount,
       treatAsGrossAmount: true, // true / false (by default)
       source: {
           type: PeerType.VAULT_ACCOUNT,
           id: String(srcId)
       },
       destination: {
           type: PeerType.VAULT_ACCOUNT,
           id: String(destId)
       },
       note: "Your first treat as gross transaction!"
    };
    const result = await fireblocks.createTransaction(payload);
    console.log(JSON.stringify(result, null, 2));
}
createTransaction("ETH", "0.001", "0", "1");
```

```python theme={"system"}
def create_transaction(asset_id, amount, src_id, dest_id):
    tx_result = fireblocks.create_transaction(
        asset_id=asset_id,
        amount=amount,
        treat_as_gross_amount=True, # true / false (by default)
        source=TransferPeerPath(VAULT_ACCOUNT, src_id),
        destination=DestinationTransferPeerPath(VAULT_ACCOUNT, dest_id),
     note: "Your first treat as gross transaction!"
    )
    print(tx_result)

create_transaction("ETH", "0.001", "0", "1")
```

## fee

For UTXO-based assets, `fee` refers to the fee per byte in the asset's smallest unit (Satoshi, Latoshi, etc).

```javascript theme={"system"}
const transactionPayload = {
	assetId: "BTC",
	amount: "0.001",
	fee: "15", // Satoshi per Byte
	source: {
		type: TransferPeerPathType.VaultAccount,
		id: "0",
	},
	destination: {
		type: TransferPeerPathType.VaultAccount,
		id: "1",
	},
	note: "Your first high fee transaction!"
}

const createTransaction = async (
	transactionPayload:TransactionRequest
):Promise<CreateTransactionResponse | undefined > => {
	try {
		const transactionResponse = await fireblocks.transactions.createTransaction(
			{
				transactionRequest:transactionPayload
			}
		);
		console.log(JSON.stringify(transactionResponse.data, null, 2));
		return transactionResponse.data;
	}
	catch(error){
		console.error(error);
	}
}
createTransaction(transactionPayload);
```

```javascript theme={"system"}
async function createTransaction(assetId, amount, srcId, destId, fee){
    let payload = {
        assetId,
        amount,
        fee, //Satoshi per Byte
        source: {
            type: PeerType.VAULT_ACCOUNT,
         		id: String(srcId)
        },
        destination: {
            type: PeerType.VAULT_ACCOUNT,
        		id: String(destId)
        },
        note: "Your first high fee transaction!"
    };
    const result = await fireblocks.createTransaction(payload);
    console.log(JSON.stringify(result, null, 2));
}
createTransaction("BTC", "0.001", "0", "1", "15");
```

```python theme={"system"}
def create_transaction(asset_id, amount, src_id, dest_id, fee):
    tx_result = fireblocks.create_transaction(
        asset_id=asset_id,
        amount=amount,
        fee=fee, #Satoshi per Byte
        source=TransferPeerPath(VAULT_ACCOUNT, src_id),
        destination=DestinationTransferPeerPath(VAULT_ACCOUNT, dest_id),
        note="Your first high fee transaction!"
    )
    print(tx_result)

create_transaction("BTC", "0.001", "0", "1", "15")
```

## feeLevel

Defines the blockchain fee level that will be paid for the transaction (only for Ethereum, Solana, and UTXO-based blockchains). Set to `MEDIUM` by default. Valid values are `LOW` `MEDIUM` & `HIGH`.

```javascript theme={"system"}
const transactionPayload = {
  assetId: "ETH",
  amount: "0.001",
  feeLevel: TransactionRequestFeeLevelEnum.High, // Low / Medium / High
  source: {
    type: TransferPeerPathType.VaultAccount,
    id: "0",
  },
  destination: {
    type: TransferPeerPathType.VaultAccount,
    id: "1",
  },
  note: "Your first high fee level transaction!",
};

const createTransaction = async (
  transactionPayload: TransactionRequest,
): Promise<CreateTransactionResponse | undefined> => {
  try {
    const transactionResponse = await fireblocks.transactions.createTransaction(
      {
        transactionRequest: transactionPayload,
      },
    );
    console.log(JSON.stringify(transactionResponse.data, null, 2));
    return transactionResponse.data;
  } catch (error) {
    console.error(error);
  }
};
createTransaction(transactionPayload);
```

```javascript theme={"system"}
async function createTransaction(assetId, amount, srcId, destId, feeLevel){
    let payload = {
        assetId,
        amount,
        feeLevel, // LOW / MEDIUM / HIGH
        source: {
            type: PeerType.VAULT_ACCOUNT,
         		id: String(srcId)
        },
        destination: {
            type: PeerType.VAULT_ACCOUNT,
        		id: String(destId)
        },
        note: "Your first high fee level transaction!"
    };
    const result = await fireblocks.createTransaction(payload);
    console.log(JSON.stringify(result, null, 2));
}
createTransaction("BTC", "0.001", "0", "1", "HIGH");
```

```python theme={"system"}
def create_transaction(asset_id, amount, src_id, dest_id, fee_level):
    tx_result = fireblocks.create_transaction(
        asset_id=asset_id,
        amount=amount,
        fee_level=fee_level, # LOW / MEDIUM / HIGH
        source=TransferPeerPath(VAULT_ACCOUNT, src_id),
        destination=DestinationTransferPeerPath(VAULT_ACCOUNT, dest_id),
        note="Your first high fee level transaction!"
    )
    print(tx_result)

create_transaction("BTC", "0.001", "0", "1", "HIGH")
```

## failOnLowFee

Set to`false` by default. If set to `true`, and the `feeLevel` (value: `MEDIUM`) is higher than the acceptable amount specified in the transaction, the transaction will fail, to avoid getting stuck with 0 confirmations.

```javascript theme={"system"}
const transactionPayload = {
  assetId: "ETH",
  amount: "0.001",
  failOnLowFee: true, // true / false (default - false)
  source: {
    type: TransferPeerPathType.VaultAccount,
    id: "0",
  },
  destination: {
    type: TransferPeerPathType.VaultAccount,
    id: "1",
  },
  note: "Your first failOnLowFee transaction",
};

const createTransaction = async (
  transactionPayload: TransactionRequest,
): Promise<CreateTransactionResponse | undefined> => {
  try {
    const transactionResponse = await fireblocks.transactions.createTransaction(
      {
        transactionRequest: transactionPayload,
      },
    );
    console.log(JSON.stringify(transactionResponse.data, null, 2));
    return transactionResponse.data;
  } catch (error) {
    console.error(error);
  }
};
createTransaction(transactionPayload);
```

```javascript theme={"system"}
async function createTransaction(assetId, amount, srcId, destId, failOnLowFee){
    let payload = {
        assetId,
        amount,
        failOnLowFee, // true / false (default)
        source: {
            type: PeerType.VAULT_ACCOUNT,
         		id: String(srcId)
        },
        destination: {
            type: PeerType.VAULT_ACCOUNT,
        		id: String(destId)
        },
        note: "Your first failOnLowFee transaction"
    };
    const result = await fireblocks.createTransaction(payload);
    console.log(JSON.stringify(result, null, 2));
}
createTransaction("BTC", "0.001", "0", "1", true);
```

```python theme={"system"}
def create_transaction(asset_id, amount, src_id, dest_id, fail_on_low_fee):
    tx_result = fireblocks.create_transaction(
        asset_id=asset_id,
        amount=amount,
        fail_on_low_fee=fail_on_low_fee, # True / False (by default)
        source=TransferPeerPath(VAULT_ACCOUNT, src_id),
        destination=DestinationTransferPeerPath(VAULT_ACCOUNT, dest_id),
        note="Your first failOnLowFee transaction"
    )
    print(tx_result)

create_transaction("BTC", "0.001", "0", "1", True)
```


# Create Vault Accounts
Source: https://developers.fireblocks.com/reference/create-vault-account



Your Fireblocks workspace utilizes a hierarchy of vault accounts as part of its [Object Model](doc:object-model). This hierarchy allows you to segregate funds belonging to different business units or deposited by different users.

A Vault account can hold multiple assets. To transfer to or from vault accounts, your source or destination targets must be provided with both their vault ID and asset ID.

Use the [Create a new vault account](/reference/createvaultaccount) API call to create a new vault account that will hold your UTXO or account-based wallets.

### Important:

Vault account names should consist of ASCII characters only.

### Code Example

```javascript theme={"system"}
(async() => {

  const vaultAccount = await fireblocks.vaults.createVaultAccount({
    createVaultAccountRequest: {
      name: "MyVaultAccount",
      autoFuel: true,
      hiddenOnUI: false
    }
  })
  console.log(JSON.stringify(vaultAccount.data, null, 2))

})();
```

```python theme={"system"}
vault_account = fireblocks.create_vault_account(
    name="MyVaultAccount",
    hiddenOnUI=False,
    autoFuel=True
)
```

### Response Example

```json theme={"system"}
{
  "id": "148",
  "name": "MyVaultAccount",
  "hiddenOnUI": false,
  "assets": [],
  "autoFuel": true
}
```

***

# Optional parameters

### hiddenOnUI

Set to `true` by default, hides this vault account from appearing in the Fireblocks Console.

This is the best practice when creating intermediate deposit vault accounts for your users as it helps reduce visual clutter and improves UI loading time.

The best practice is configuring this setting so that only your omnibus account and another operational vault account (or multiple) are visible in the Fireblocks Console.

### autoFuel

If the Gas Station service is enabled on your workspace, this flag needs to be set to `true` if you wish to monitor and fuel this account's Ethereum address upon detected balance refresh events, such as when deposits of ERC20 tokens occur.


# Create Vault Wallets
Source: https://developers.fireblocks.com/reference/create-vault-wallet



Fireblocks vault accounts contain vault wallets. For each vault wallet, there are one or more deposit addresses.

# Address generation

## Account-based wallets

For account-based assets, there are two address-generation options:

1. Account-based assets *without* tag/memo/note support, such as ETH, can only generate one deposit address, making each vault account unique per vault wallet. This allows you to manage one deposit address per asset, per vault account. This requires you to create additional vault accounts when more than one deposit address of the same asset is required.
2. Account-based assets *with* tag/memo/note support, such as XRP, can generate one or more deposit addresses. Each deposit address has the same on-chain address. However, they are differentiated by their tag/memo.

## UTXO wallets

UTXO-based assets, such as Bitcoin, can hold multiple wallet addresses. This allows you to manage deposits in a single vault account.

### Create Vault Wallet code example:

```javascript theme={"system"}
(async() => {

  try {
    const vaultWallet = await fireblocks.vaults.createVaultAccountAsset({
      vaultAccountId: "148",
      assetId: "BTC"
    })

    console.log(JSON.stringify(vaultWallet, null, 2))
  } catch(e){
    console.log(e)
  }
})();
```

```python theme={"system"}
vault_wallet = fireblocks.create_vault_asset(
    vault_account_id="148",
    asset_id="BTC"
)
pprint.pprint(vault_wallet)
```

### Response example

```json theme={"system"}
{
 'address': 'bc1q8q87uy8h2mru0q5gc7u680w76dz350s6sx5u8a',
 'id': '148',
 'legacyAddress': '167RvaKttzN2wRrJwmYEwjKG7kvdjwhKfq',
 'tag': ''
}
```

### Create Deposit Address for UTXO and Tag/Memo based assets:

```javascript theme={"system"}
(async() => {

  try {

    const depositAddress = await fireblocks.vaults.createVaultAccountAssetAddress({
      assetId: "BTC",
      vaultAccountId: "148",
      createAddressRequest: {
        description: "EndUserA"
      }
    })

    console.log(JSON.stringify(depositAddress, null, 2))
  } catch(e){
    console.log(e)
  }
})();
```

```python theme={"system"}
deposit_address= fireblocks.generate_new_address(
    vault_account_id='148',
    asset_id='BTC',
    description='EndUserA'
)

pprint.pprint(deposit_address)
```

### Response Example:

```json theme={"system"}
{
  'address': 'bc1qkwxyzs68a3nsulhe4eavfm5dzuucf25jjnefex',
 	'bip44AddressIndex': 1,
 	'legacyAddress': '1HNMyRRzt4beCDnYLRwQKEbPAwTgmKjwrJ',
 	'tag': ''
}
```

> **Check the Create Vault Wallet and Create a Deposit Address API Reference**


# Create Workflow Configuration
Source: https://developers.fireblocks.com/reference/create-workflow-configuration



Call the [POST /payments/workflow\_config](/reference/createflowconfiguration) endpoint.

After a configuration is created, the operation type for the WC can’t be changed. However, other WC parameters can be defined and edited later when creating the WE.

## Example

```json theme={"system"}
{
  configName: 'some-name',
  preScreening: {
    enabled: true
  },
  failureHandling: {
    enabled: true,
    type: 'REVERSE'
  },
  configOperations: {
    type: 'TRANSFER',
    params: {
      source: {
        accountId: 'xyz',
        accountType: 'EXCHANGE_ACCOUNT',
      },
      assetId: 'USDC_POLYGON',
      destination: {
        accountType: 'VAULT_ACCOUNT',
        accountId: '0',
      },
    },
  },
  {
    type: 'TRANSFER',
    params: {
      destination: {
        accountType: 'EXCHANGE_ACCOUNT',
        accountId: 'abc',
      },
      source: {
        accountType: 'VAULT_ACCOUNT',
        accountId: '0',
      },
      assetId: 'USDC_POLYGON',
    },
  },
}
```

This route returns the configuration ID which will be used to create the WE.

A configuration proceeds through the following statuses during its creation. These statuses will be applied to each WCO and the WC as a whole.

1. **PENDING:** The configuration is about to start the validation process.
2. **VALIDATION\_IN\_PROGRESS:** The validation process has started, ensuring the configuration is valid.
3. **VALIDATION\_FAILED** or **READY\_FOR\_EXECUTION:** The validation failed or the configuration can be executed. These statuses are finite states.

All the operation validation processes must succeed for the configuration validation to succeed.

If one or more operation validations fail, the entire configuration validation fails. Failed WCOs may show VALIDATION\_FAILED while others may show VALIDATION\_COMPLETED. However, the WC status will show VALIDATION\_FAILED. The failure details will be included under the failed operation in the validationFailure field. In this scenario, you should call the API endpoint again with the corrected configuration.


# Create Workflow Execution
Source: https://developers.fireblocks.com/reference/create-workflow-execution



Once the WC is in **READY\_FOR\_EXECUTION** status, call the [POST /payments/workflow\_execution](/reference/createflowexecution) endpoint.

When creating a WE, mandatory parameters, such as amounts and addresses, that weren’t provided during the configuration phase must be provided. Parameters provided when creating the WC can be overridden when creating the WE. Some parameters are only provided when creating the WE.

The `amount` parameter can only be provided during the WE since it’s required for the preview and launch but not for the WC, which is just a template. This parameter is usually provided to the first operation and then carried from one operation to another down the flow.

## Example

```json theme={"system"}
{
  "configId": "string",
  "preScreening":{
    "enabled": false
  },
  failureHandling: {
    enabled: true,
    type: 'REVERSE'
  },
  "params": [
    {
      "configOperationId": "string",
      "configOverrideParams": {
        "accountId": "string",
        "srcAssetId": "string",
        "destAssetId": "string",
        "slippageBasisPoints": 10000
      },
      "executionParams": {
        "amount": "string"
      }
    },
    {
      "configOperationId": "string",
      "configOverrideParams": {
        "paymentAccount": {
          "accountId": "string",
          "accountType": "EXCHANGE_ACCOUNT"
        },
        "instructionSet": [
          {
            "payeeAccount": {
              "accountId": "string",
              "accountType": "EXCHANGE_ACCOUNT"
            },
            "assetId": "string",
            "amount": "string"
          },
          {
            "payeeAccount": {
              "accountId": "string",
              "accountType": "EXCHANGE_ACCOUNT"
            },
            "assetId": "string",
            "percentage": "string"
          }
        ]
      },
      "executionParams": {
        "amount": "string"
      }
    }
  ]
}
```

The request body `configId` field must include the id for a WC in READY\_FOR\_EXECUTION status.

The request body `params` field holds an array. Each item of the array has a `configOperationId`, which points to a specific operation from the WC. This is necessary when overriding or setting an operation.

An execution proceeds through the following statuses during its creation:

1. **PENDING:** The execution is about to start the validation process.
2. **VALIDATION\_IN\_PROGRESS:** The validation process has started, ensuring the execution is valid.
3. **VALIDATION\_FAILED** or **VALIDATION\_COMPLETED:** The validation failed or completed. If completed, the preview process starts automatically.
4. **PREVIEW\_IN\_PROGRESS:** The preview process has started.
5. **PREVIEW\_FAILED** or **READY\_FOR\_LAUNCH:** The preview failed or the execution can be launched. These statuses are finite states.

If an execution is in VALIDATION\_FAILED status or a PREVIEW\_FAILED, it can't be launched or used again. To get another corrected preview, create a new WE to trigger the validation and preview processes.


# Data Objects
Source: https://developers.fireblocks.com/reference/data-objects



On the following pages, you can find descriptions of all the data objects expected and returned by the Fireblocks API's endpoints.


# Deploy an NFT Collection
Source: https://developers.fireblocks.com/reference/deploy-an-nft-collection



# Overview

You can deploy smart contracts using [The Fireblocks Hardhat plugin integration](https://hardhat.org/hardhat-runner/docs/guides/deploying)

# Create your ERC-721 collection

You can create your own NFT collection using the common ERC-721 standard.

For this example, we’ll name our collection “Space Bunnies”.

There are some great tools to help you do this pretty easily. This example was pre-generated using the [Contracts Wizard by OpenZeppelin](https://docs.openzeppelin.com/contracts/4.x/wizard).

```solidity theme={"system"}
pragma solidity ^0.8.4;

import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
import "@openzeppelin/contracts/token/ERC721/extensions/ERC721URIStorage.sol";
import "@openzeppelin/contracts/access/Ownable.sol";
import "@openzeppelin/contracts/utils/Counters.sol";

contract SpaceBunnies is ERC721, ERC721URIStorage, Ownable {
    using Counters for Counters.Counter;

    Counters.Counter private _tokenIdCounter;

    constructor() ERC721("Space Bunnies", "SPCB") {}

    function safeMint(address to, string memory uri) public onlyOwner {
        uint256 tokenId = _tokenIdCounter.current();
        _tokenIdCounter.increment();
        _safeMint(to, tokenId);
        _setTokenURI(tokenId, uri);
    }

    // The following functions are overrides required by Solidity.

    function _burn(uint256 tokenId) internal override(ERC721, ERC721URIStorage) {
        super._burn(tokenId);
    }

    function tokenURI(uint256 tokenId)
        public
        view
        override(ERC721, ERC721URIStorage)
        returns (string memory)
    {
        return super.tokenURI(tokenId);
    }
}
```

> **OpenZeppelin required**
>
> To run the generated code, you also need to install the OpenZeppelin contracts package from NPM.
>
> In your project directory, run: `npm install @openzeppelin/contracts`.

You are ready to go!

Check out the [Fireblocks Hardhat Plugin Documenation](/reference/hardhat-plugin), [Fireblocks Local JSON RPC](/reference/evm-local-json-rpc) and [Fireblocks Web3 provider](/reference/evm-web3-provider) .

Make sure you go through these and deploy the above contract as explained there, using your choice of available options.

> **Hardhat Deployment**
>
> Hardhat is the go-to market solution for easily deploying contracts. We highly recommend that you choose this option if you feel comfortable with going through the configuration process.


# Estimate Transaction Fee
Source: https://developers.fireblocks.com/reference/estimate-transaction-fee



> **Learn more about Fee Management in Fireblocks in [the following guide](/docs/verify-fee-effeciency)**

# Overview

Ethereum (ETH) fees, also referred to as "gas price" or "gas fees," are calculated based on the amount of network activity and the network resources required. Fireblocks allows you to set the fee when creating a new transaction. You can either use a **custom fee** to set the amount used manually, or you can have Fireblocks estimate the fee by default.

You can estimate network gas fees using the Fireblocks API:

* Estimate a tentative fee for low, medium, or high rates by making a request to [Estimate the required fee for an asset.](/reference/estimatenetworkfee)
* Estimate a specific fee based on your transaction's parameters by making a request to [Estimate the transaction fee.](/reference/estimatetransactionfee)

> **Fee levels determine transaction speed**
>
> The fee rate dictates the speed at which your transaction will be picked up and confirmed by the blockchain. When setting a tentative fee rate, the fee amount is an estimate only. Gas fee calculation is not finalized until your transaction is signed.

> **Using custom fee**
>
> Using the custom fee option can be complex as it offers different parameters, similar to stock trading, that allow you to set options like:
>
> * **Maximum priority fee** - Transaction time takes priority over gas fee price.
> * **Max fee** - The gas fee max price is preset and takes priority over transaction time.
>
> [Learn more about the current Ethereum Network EIP-1559 standard for fee estimation.](https://support.fireblocks.io/hc/en-us/articles/4403728014994-London-Fork-and-EIP-1559)

***

# Estimated network fee

> **Response Caching:**
>
> The network fee response is cached for 30 seconds on the Fireblocks side. Customers should consider this interval when using this endpoint, as querying it more frequently than every 30 seconds will not provide additional value.

You'll see the tentative fee estimation in your fee values before creating your transaction data. This example shows how the estimated network fee is returned by the `getFeeForAsset` SDK function for the ETH asset. A high `priorityFee` estimation is used here to create a transaction sending 0.001 from vault ID `0` to vault ID `1`.

The fee level can be either `LOW` / `MEDIUM` / `HIGH`. It will be `MEDIUM` by default.

* **Note**: You are required to specify the `maxFee`when using `priorityFee`.

```javascript theme={"system"}
const createTxWithNetworkFee = async (
  payload: TransactionRequest,
): Promise<CreateTransactionResponse | undefined> => {
  try {
    const fee = await fireblocks.transactions.estimateNetworkFee({
      assetId: payload.assetId as string,
    });
    console.log(
      JSON.stringify(
        `Priority fee for the Tx is: ${fee.data.high.priorityFee}`,
      ),
    );
    payload.priorityFee = fee.data.high.priorityFee;
    payload.maxFee = "120";
    const result = await fireblocks.transactions.createTransaction({
      transactionRequest: payload,
    });
    console.log(JSON.stringify(result.data, null, 2));
    return result.data;
  } catch (error: any) {
    console.error(error);
  }
};

createTxWithNetworkFee({
  assetId: "ETH",
  source: {
    type: TransferPeerPathType.VaultAccount,
    id: "0",
  },
  destination: {
    type: TransferPeerPathType.VaultAccount,
    id: "1",
  },
  amount: 0.01,
});
```

```javascript theme={"system"}
async function createTransactionWithNetworkFee(assetId, amount, sourceId, destId){
    const fee = await getFee(assetId)
    console.log(JSON.stringify("Priority Fee for Transaction is: " + fee.high.priorityFee, null, 2));

    const payload = {
        assetId,
        source: {
            type: PeerType.VAULT_ACCOUNT,
            id: sourceId
        },
        destination: {
            type: PeerType.VAULT_ACCOUNT,
            id: destId
        },
        amount,
        priorityFee: fee.high.priorityFee,
        maxFee: "120"
    };
    const result = await fireblocks.createTransaction(payload);
    console.log(JSON.stringify(result, null, 2));
}
createTransactionWithNetworkFee("ETH", "0.001", "0", "1");
```

```python theme={"system"}
def create_transaction_with_network_fee(asset_id: str, amount: str, source_id: str, dest_id: str):
    fee = fireblocks.get_fee_for_asset(asset_id=asset_id)
    print("Priority Fee for Transaction is:", fee["high"]["priorityFee"])
    result = fireblocks.create_transaction(
        asset_id=asset_id,
        source=TransferPeerPath(
            peer_type=VAULT_ACCOUNT,
            peer_id=source_id
        ),
        destination=DestinationTransferPeerPath(
            peer_type=VAULT_ACCOUNT,
            peer_id=dest_id
        ),
        amount=amount,
        priority_fee=fee["high"]["priorityFee"],
        max_fee="120"
    )

    print(result)

create_transaction_with_network_fee("ETH", "0.001", "0", "1")
```

***

# Estimate transaction fee

You'll see the `feeLevel` parameter value inside your transaction data based on the fee level selection from the `estimateFeeForTransaction` SDK function.

This example shows how the estimated network fee is returned by the `getFeeForAsset` SDK function for the ETH asset. A high `priorityFee` estimation is used here to create a transaction sending 0.001 from vault ID `0` to vault ID `1`:

```javascript theme={"system"}
const getTxFee = async (
  payload: TransactionRequest,
): Promise<EstimatedTransactionFeeResponse | undefined> => {
  try {
    const txFee = await fireblocks.transactions.estimateTransactionFee({
      transactionRequest: payload,
    });
    return txFee.data;
  } catch (error: any) {
    console.error(error);
  }
};

// The function should include the logic that will determine the fee level used
// it should be based on the threshold relevant for your use-case
// The logic options are HIGH/LOW as MEDIUM is the default when feeLevel is null

const getFeeLevelToUse = (
  feeEstimation: EstimatedTransactionFeeResponse,
): TransactionRequestFeeLevelEnum | undefined => {
  let feeLevelToUse: TransactionRequestFeeLevelEnum | undefined;
  if ("<ADD_YOUR_LOGIC_HERE>") {
    feeLevelToUse = TransactionRequestFeeLevelEnum.High;
  } else if ("<ADD_MORE_LOGIC_HERE>") {
    feeLevelToUse = TransactionRequestFeeLevelEnum.Low;
  }
  return feeLevelToUse;
};

const createTxWithFeeEstimation = async (
  payload: TransactionRequest,
): Promise<CreateTransactionResponse | undefined> => {
  try {
    const txFee = (await getTxFee(payload)) as EstimatedTransactionFeeResponse;
    const feeLevel = getFeeLevelToUse(txFee);
    payload.feeLevel = feeLevel as TransactionRequestFeeLevelEnum;
    const result = await fireblocks.transactions.createTransaction({
      transactionRequest: payload,
    });
    console.log(JSON.stringify(result.data, null, 2));
    return result.data;
  } catch (error: any) {
    console.error(error);
  }
};

createTxWithFeeEstimation({
  assetId: "ETH",
  source: {
    type: TransferPeerPathType.VaultAccount,
    id: "0",
  },
  destination: {
    type: TransferPeerPathType.VaultAccount,
    id: "1",
  },
  amount: 0.01,
});
```

```javascript theme={"system"}
async function getTxFee(payload){
    const getTxFee = await fireblocks.estimateFeeForTransaction(payload);
    return getTxFee;
}

// the function should include the logic that will determine the fee level used
// it should be based on the threshold relevant for your use-case
// The logic options are HIGH/LOW as MEDIUM is the default when feeLevel is null
function logicForWhatFeeLevelToUse(feeEstimation){
    if(... <= myThreshold){
        feeLevelToUse = FeeLevel.HIGH
    }
    else if(.....){
        feeLevelToUse = FeeLevel.LOW
    }
    return feeLevelToUse;
}

async function createTransaction(assetId, amount, sourceId, destId){
    var feeLevel;

    const payload = {
        assetId,
        amount,
        source: {
            type: PeerType.VAULT_ACCOUNT,
            id: sourceId
        },
        destination: {
            type: PeerType.VAULT_ACCOUNT,
            id: destId
        },
        feeLevel
    };
    payload.feeLevel = logicForWhatFeeLevelToUse(getTxFee(payload));
    const result = await fireblocks.createTransaction(payload);
    console.log(JSON.stringify(result, null, 2));
}
createTransaction("ETH", "0.001", "0", "1");
```

```python theme={"system"}
def create_transaction(asset_id: str, amount: str, source_id: str, dest_id: str):
    fee_level = ""

    payload = {
        "asset_id": asset_id,
        "amount": amount,
        "source": TransferPeerPath(
            peer_type=VAULT_ACCOUNT,
            peer_id=source_id
        ),
        "destination": DestinationTransferPeerPath(
            peer_type=VAULT_ACCOUNT,
            peer_id=dest_id
        ),
        "fee_level": fee_level
    }

    try:
        payload["fee_level"] = logic_for_what_fee_level_to_use(fireblocks.estimate_fee_for_transaction(**payload))
        result = fireblocks.create_transaction(**payload)
        print(result)
    except Exception as e:
        print("Error:", e)
```


# EVM Local JSON RPC
Source: https://developers.fireblocks.com/reference/evm-local-json-rpc



# Overview

The Fireblocks JSON-RPC is a command-line server that utilizes the Fireblocks API to facilitate interactions with Ethereum Virtual Machine (EVM) chains. It enables users to perform blockchain operations through a JSON-RPC interface, and it was developed to simplify the integration of Fireblocks' secure wallet infrastructure with blockchain applications.

In this article, you will find installation instructions, code examples, and guidance on how to utilize Fireblocks JSON RPC and other frameworks (e.g. Brownie, Foundry) for smart contract development and interactions.

# Getting Started

## web3.py integration

[Fireblocks JSON-RPC](https://github.com/fireblocks/fireblocks-json-rpc) helps seamlessly integrate Fireblocks into your web3.py development stack.

You can use it to deploy contracts, sign messages, and send transactions.

### Installation

```bash theme={"system"}
npm install -g @fireblocks/fireblocks-json-rpc
pip install web3
```

### Setup

Set the [environment variables](https://github.com/fireblocks/fireblocks-json-rpc/blob/main/.env.example).

Create `example.py`:

```python theme={"system"}
import json
import os
from datetime import datetime
from web3 import Web3

web3 = Web3(Web3.IPCProvider(os.environ['FIREBLOCKS_JSON_RPC_ADDRESS'], 60000*180))
web3.eth.defaultAccount = web3.eth.accounts[0]
CONTRACT_ADDRESS = Web3.toChecksumAddress("0x8A470A36a1BDE8B18949599a061892f6B2c4fFAb")
GREETER_ABI = json.loads('[{"inputs":[{"internalType":"string","name":"_greeting","type":"string"}],"stateMutability":"nonpayable","type":"constructor"},{"inputs":[],"name":"greet","outputs":[{"internalType":"string","name":"","type":"string"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"string","name":"_greeting","type":"string"}],"name":"setGreeting","outputs":[],"stateMutability":"nonpayable","type":"function"}]')
GREETING = "Hello web3! By " + web3.eth.defaultAccount + " at " + str(datetime.now())

if __name__ == '__main__':
    print('last block number: ', web3.eth.blockNumber)
    for account in web3.eth.accounts:
        print('account: ', account)
        print('account balance: ', web3.fromWei(web3.eth.getBalance(account), "ether"), ' ETH\n')

    print('Greeter contract: https://sepolia.etherscan.io/address/' + CONTRACT_ADDRESS)

  	contract = web3.eth.contract(address=CONTRACT_ADDRESS, abi=GREETER_ABI)

    print('Current greeting:', contract.functions.greet().call())

    print('Setting greeting to:', GREETING)
    tx_hash = contract.functions.setGreeting(GREETING).transact({'from':web3.eth.defaultAccount})
    print('Transaction signed and broadcasted: https://sepolia.etherscan.io/tx/' + tx_hash.hex())
    print('Waiting for transaction to be mined...')
    web3.eth.wait_for_transaction_receipt(tx_hash)

    print('Current greeting:', contract.functions.greet().call())
```

### Usage

```bash theme={"system"}
fireblocks-json-rpc -- python example.py
```

You can now use the `web3` object exactly as you normally would!

# Ethereum Smart Contract Development

## Using Brownie

Use the [Fireblocks JSON-RPC](https://github.com/fireblocks/fireblocks-json-rpc) to seamlessly work with Brownie on top of Fireblocks.

## Installation

### Step 1 - Brownie installation:

Please follow the Brownie official [documentation](https://eth-brownie.readthedocs.io/en/stable/install.html) for installation

### Step 2 - Install Fireblocks JSON RPC server:

```bash theme={"system"}
npm install -g @fireblocks/fireblocks-json-rpc
```

## Setup

### Step 1 - Create a new example Brownie project:

```bash theme={"system"}
brownie bake token
cd token
```

### Step 2 - set environment variables:

Set the [environment variables](https://github.com/fireblocks/fireblocks-json-rpc/blob/main/.env.example)

### Step 3 - Add Fireblocks Sepolia network to Brownie:

```bash theme={"system"}
brownie networks add Fireblocks fireblocks-sepolia name="Sepolia (Fireblocks)" chainid=11155111 host='http://127.0.0.1:8545/${FIREBLOCKS_API_KEY}' timeout=600
```

### Step 4 - Configure brownie-config.yaml file:

Add ***dotenv: .env*** parameter to the config yaml file.

Example:

```yaml theme={"system"}
# exclude SafeMath when calculating test coverage
# https://eth-brownie.readthedocs.io/en/v1.10.3/config.html#exclude_paths
reports:
  exclude_contracts:
    - SafeMath
dotenv: .env
```

## Usage:

```bash theme={"system"}
fireblocks-json-rpc -- brownie run --network fireblocks-sepolia scripts/token.py
```

## Using Foundry

## Installing Foundry

You can skip this section if you already have Foundry installed or follow that [Foundry Installation guide](https://book.getfoundry.sh/getting-started/installation) , [Foundry New Project guide](https://book.getfoundry.sh/projects/creating-a-new-project) on the Foundry website for all details.

We provide you with a very basic process here for convenience:

```bash theme={"system"}
curl -L https://foundry.paradigm.xyz | bash
foundryup
forge init hello_foundry
cd hello_foundry
forge build
forge test
```

After you complete these steps, you'll have a new Foundry project.

## Foundry integration

The [Fireblocks Local JSON-RPC](https://github.com/fireblocks/fireblocks-json-rpc) helps seamlessly integrate Fireblocks into your [Foundry](https://book.getfoundry.sh/) development stack.

You can use it to deploy contracts, sign messages, and send transactions.

### Installation

```bash theme={"system"}
npm install -g @fireblocks/fireblocks-json-rpc
```

### Configuration

Configuration can be set via command line flags or environment variables.

Command line flags:

* Ignore apiBaseUrl if you are not using a sandbox environment

```bash theme={"system"}
fireblocks-json-rpc --apiKey <key> --privateKey <path_or_contents> --chainId <chainId> --apiBaseUrl https://sandbox-api.fireblocks.io
```

Environment variables:

* Ignore FIREBLOCKS\_API\_BASE\_URL if you are not using a sandbox environment

```bash theme={"system"}
FIREBLOCKS_API_KEY=<key> \
FIREBLOCKS_API_PRIVATE_KEY_PATH=<path_or_contents> \
FIREBLOCKS_CHAIN_ID=<chainId> \
FIREBLOCKS_API_BASE_URL=https://sandbox-api.fireblocks.io
fireblocks-json-rpc
```

Delete the files that came with your Foundry boilerplate template:

```bash theme={"system"}
rm test/Counter.t.sol script/Counter.s.sol src/Counter.sol
```

## Deploy Contract - Using 'forge script'

Now that you have a Foundry project set up, create your smart contract `src/Hello.sol` in the project folder and then deploy it to the Sepolia Ethereum Testnet.

### Step 1: Create and compile the Solidity file

```solidity theme={"system"}
pragma solidity ^0.8.17;

contract HelloWorld {
    string public greet = "Hello World!";
}
```

Run the following command to compile it:

```bash theme={"system"}
forge build
```

### Step 2: Create the deployment script

Create a deployment script `script/Hello.s.sol` :

```solidity theme={"system"}
pragma solidity ^0.8.17;

import "forge-std/Script.sol";
import "../src/Hello.sol";

contract MyScript is Script {
    function run() external {
        vm.startBroadcast();

        HelloWorld hello = new HelloWorld();

        vm.stopBroadcast();
    }
}
```

### Step 3: Deploy smart contract

Deploy your contract to the Ethereum Sepolia Testnet (It is recommended to use the `--slow` parameter in your forge script command, specifically when the script is processing few transactions sequentially):

```bash theme={"system"}
FIREBLOCKS_API_KEY=12345678-1234-1234-1234-123456789abc \
FIREBLOCKS_API_PRIVATE_KEY_PATH=/path/to/secret.key \
FIREBLOCKS_CHAIN_ID=11155111 \
fireblocks-json-rpc --http -- \
forge script script/Hello.s.sol:MyScript \
--sender <sender_address> --slow --broadcast --unlocked --rpc-url {}
```

* `sender_address` can be found in your Fireblocks workspace, through Fireblocks API, or using the JSON RPC directly.

  Get address of vault account 0:

```bash theme={"system"}
FIREBLOCKS_API_KEY=12345678-1234-1234-1234-123456789abc \
FIREBLOCKS_API_PRIVATE_KEY_PATH=/path/to/secret.key \
FIREBLOCKS_CHAIN_ID=11155111 \
fireblocks-json-rpc --http --vaultAccountIds 0 -- curl {} \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"method":"eth_accounts","id":1,"jsonrpc":"2.0"}'
```

This should take a couple of minutes to run if everything was configured correctly.


# EVM Web3 Provider
Source: https://developers.fireblocks.com/reference/evm-web3-provider



# Overview

Popular blockchain choices for building Web3 capabilities are based typically on the Ethereum Virtual Machine (EVM), and therefore share the development tech stack.

Some examples of EVM blockchains:

* Ethereum
* BNB Chain (BSC)
* Polygon
* Avalanche
* Arbitrum

# Convenience libraries

Most commonly, developers interact with EVM-based blockchains using "convenience libraries" such as [web3.js](https://web3js.readthedocs.io/) and [ethers.js](https://docs.ethers.io).

To streamline your JavaScript development experience, we created the [Fireblocks Web3 Provider](https://github.com/fireblocks/fireblocks-web3-provider), to easily connect `ethers.js` and `web3.js` to your Fireblocks workspace.

# web3.js integration

The [Fireblocks Web3 Provider](https://github.com/fireblocks/fireblocks-web3-provider) helps seamlessly integrate Fireblocks into your [`web3.js`](https://web3js.readthedocs.io/) development stack. Use it to deploy contracts, sign messages, and send transactions.

### Installation

```bash theme={"system"}
npm install @fireblocks/fireblocks-web3-provider web3
```

### Setup

```javascript theme={"system"}
import { FireblocksWeb3Provider, ChainId, ApiBaseUrl } from "@fireblocks/fireblocks-web3-provider";

const eip1193Provider = new FireblocksWeb3Provider({
    apiBaseUrl: ApiBaseUrl.Sandbox, // If using a sandbox workspace
    privateKey: process.env.FIREBLOCKS_API_PRIVATE_KEY_PATH,
    apiKey: process.env.FIREBLOCKS_API_KEY,
    vaultAccountIds: process.env.FIREBLOCKS_VAULT_ACCOUNT_IDS,
    chainId: ChainId.SEPOLIA,
})
```

If you are not using a Sandbox environment, but rather a regular one, just comment the apiBaseUrl line.

### Usage

```javascript theme={"system"}
import Web3 from "web3";

const web3 = new Web3(eip1193Provider);
```

Now you can use the `web3` object exactly as you normally would!

### Example

In this example we are executing the 'approve' method of [USDC](https://goerli.etherscan.io/address/0x07865c6E87B9F70255377e024ace6630C1Eaa37F#writeProxyContract) (ERC20) token on Sepolia by using web3.js and Fireblocks web3 provider.

```javascript theme={"system"}
const { FireblocksWeb3Provider, ChainId, ApiBaseUrl } = require("@fireblocks/fireblocks-web3-provider")
const Web3 = require("web3");

// Import the Sepolia USDC ABI
const ABI = require("./USDC_SEPOLIA_ABI.json");

// Sepolia USDC Contract Address
const CONTRACT_ADDRESS = "0x94a9d9ac8a22534e3faca9f4e7f2e2cf85d5e4c8"

const eip1193Provider = new FireblocksWeb3Provider({
    privateKey: process.env.FIREBLOCKS_API_PRIVATE_KEY_PATH,
    apiKey: process.env.FIREBLOCKS_API_KEY,
    vaultAccountIds: process.env.FIREBLOCKS_VAULT_ACCOUNT_IDS,
    chainId: ChainId.SEPOLIA,
 // apiBaseUrl: ApiBaseUrl.Sandbox // If using a sandbox workspace
});

(async() => {

  	const web3 = new Web3(eip1193Provider);
  	const myAddr = await web3.eth.getAccounts()
  	const contract = new web3.eth.Contract(ABI, CONTRACT_ADDRESS);
  	const spenderAddr = "<spender_address>"

    // 1 USDC to approve
    const amount = 1e6

    // Invoke approve method
    console.log(
        await contract.methods.approve(spenderAddr, amount).send({
            from: myAddr[0]
        })
    )

})().catch(error => {
    console.log(error)
});
```

# ethers.js integration

The [Fireblocks Web3 Provider](https://github.com/fireblocks/fireblocks-web3-provider) helps seamlessly integrate Fireblocks into your [`ethers.js`](https://docs.ethers.io/) development stack.

You can use it to deploy contracts, sign messages, and send transactions.

### Installation

```bash theme={"system"}
npm install @fireblocks/fireblocks-web3-provider ethers@5
```

### Setup

```javascript theme={"system"}
import { FireblocksWeb3Provider, ChainId, ApiBaseUrl } from "@fireblocks/fireblocks-web3-provider";

const eip1193Provider = new FireblocksWeb3Provider({
    apiBaseUrl: ApiBaseUrl.Sandbox, // If using a sandbox workspace
    privateKey: process.env.FIREBLOCKS_API_PRIVATE_KEY_PATH,
    apiKey: process.env.FIREBLOCKS_API_KEY,
    vaultAccountIds: process.env.FIREBLOCKS_VAULT_ACCOUNT_IDS,
    chainId: ChainId.SEPOLIA,
})
```

If you are not using a Sandbox environment, but rather a regular one, just comment the apiBaseUrl line.

### Usage

```javascript theme={"system"}
import * as ethers from "ethers"

const provider = new ethers.providers.Web3Provider(eip1193Provider);
```

Now you can use the `provider` object exactly as you normally would!

### Example

In this example we are executing the 'approve' method of [USDC](https://goerli.etherscan.io/address/0x07865c6E87B9F70255377e024ace6630C1Eaa37F#writeProxyContract) (ERC20) token on Sepolia by using ethers.js and Fireblocks web3 provider.

```javascript theme={"system"}
const { FireblocksWeb3Provider, ChainId, ApiBaseUrl } = require("@fireblocks/fireblocks-web3-provider")
const ethers = require("ethers")

// Import the Sepolia USDC ABI
const ABI = require("./USDC_SEPOLIA_ABI.json");

// Sepolia USDC Contract Address
const CONTRACT_ADDRESS = "0x94a9d9ac8a22534e3faca9f4e7f2e2cf85d5e4c8"

const eip1193Provider = new FireblocksWeb3Provider({
    privateKey: process.env.FIREBLOCKS_API_PRIVATE_KEY_PATH,
    apiKey: process.env.FIREBLOCKS_API_KEY,
    vaultAccountIds: process.env.FIREBLOCKS_VAULT_ACCOUNT_IDS,
    chainId: ChainId.SEPOLIA,
 // apiBaseUrl: ApiBaseUrl.Sandbox // If using a sandbox workspace
});

(async() => {

    const provider = new ethers.providers.Web3Provider(eip1193Provider);
    const myContract = new ethers.Contract(CONTRACT_ADDRESS, ABI, provider.getSigner());
    const spenderAddr = "<spender_address>"

    // 1 USDC to approve
    const amount = 1e6

    // Invoke approve method
    const tx = await myContract.approve(
        spenderAddr,
        amount
    )

    console.log(JSON.stringify(tx, null, 2))

})().catch(error => {
    console.log(error)
});
```

# Viem integration

The [Fireblocks Web3 Provider](https://github.com/fireblocks/fireblocks-web3-provider) helps seamlessly integrate Fireblocks into your [viem](https://viem.sh/) development stack.

You can use it to deploy contracts, sign messages, and send transactions.

### Installation

```bash theme={"system"}
npm install @fireblocks/fireblocks-web3-provider viem
```

### Setup

```javascript theme={"system"}
import { FireblocksWeb3Provider, ChainId, ApiBaseUrl } from "@fireblocks/fireblocks-web3-provider";

const eip1193Provider = new FireblocksWeb3Provider({
    apiBaseUrl: ApiBaseUrl.Sandbox, // If using a sandbox workspace
    privateKey: process.env.FIREBLOCKS_API_PRIVATE_KEY_PATH,
    apiKey: process.env.FIREBLOCKS_API_KEY,
    vaultAccountIds: process.env.FIREBLOCKS_VAULT_ACCOUNT_IDS,
    chainId: ChainId.SEPOLIA,
})
```

If you are not using a Sandbox environment, but rather a regular one, just comment the apiBaseUrl line.

### Usage

```javascript theme={"system"}
const { createWalletClient, custom } = require("viem")
const { sepolia } = require("viem/chains")

const walletClient = createWalletClient({
    chain: sepolia,
    transport: custom(eip1193Provider),
});
```

Now you can use the `walletClient` object exactly as you normally would!

### Example

In this example we are executing the 'approve' method of [USDC](https://goerli.etherscan.io/address/0x07865c6E87B9F70255377e024ace6630C1Eaa37F#writeProxyContract) (ERC20) token on Sepolia by using *viem* and Fireblocks web3 provider.

```javascript theme={"system"}
const { sepolia } = require("viem/chains")
const {
  ChainId,
  FireblocksWeb3Provider,
  ApiBaseUrl
} = require("@fireblocks/fireblocks-web3-provider")

const {
  createWalletClient,
  custom,
  createPublicClient,
  http
} = require("viem")

// Import the Sepolia USDC ABI
const ABI = require("./USDC_SEPOLIA_ABI.json");

// Sepolia USDC Contract Address
const CONTRACT_ADDRESS = '0x94a9d9ac8a22534e3faca9f4e7f2e2cf85d5e4c8'

(async () => {

  const spenderAddr = "<spender_addr>";

  // 1 USDC to approve
  const amount = 1e6;

  const eip1193Provider = new FireblocksWeb3Provider({
   // apiBaseUrl: ApiBaseUrl.Sandbox, // If using a sandbox workspace
    privateKey: process.env.FIREBLOCKS_API_PRIVATE_KEY_PATH,
    apiKey: process.env.FIREBLOCKS_API_KEY,
    vaultAccountIds: process.env.FIREBLOCKS_VAULT_ACCOUNT_IDS,
    chainId: ChainId.SEPOLIA
  });

  // Create wallet client instance
  const walletClient = createWalletClient({
    chain: sepolia,
    transport: custom(eip1193Provider),
  });

  // Create public client instance
  const publicClient = createPublicClient({
    chain: sepolia,
    transport: http()
  })

  // Get my account's address
  const [ account ] = await walletClient.getAddresses();

  // Simulate the 'approve' call
  const { request } = await publicClient.simulateContract({
    address: CONTRACT_ADDRESS,
    abi: ABI,
    functionName: 'approve',
    args: [spenderAddr, amount],
    account
  })

  // Execute approve call via Fireblocks
  await walletClient.writeContract(request)
})();
```

# Ethereum Smart Contract Development

Smart contract development frameworks make it easy to develop, test, and deploy smart contracts on EVM-based blockchains.

# Using Truffle

Use the [Fireblocks Web3 Provider](https://github.com/fireblocks/fireblocks-web3-provider) to seamlessly work with Truffle on top of Fireblocks.

### Installation

```bash theme={"system"}
npm install -g truffle
npm install @fireblocks/fireblocks-web3-provider
```

## Configuration

### Step 1:

Set the [environment variables](https://github.com/fireblocks/fireblocks-json-rpc/blob/main/.env.example)

### Step 2:

Initialize an example Truffle NFT project:

```bash theme={"system"}
truffle unbox nft-box
```

### Step 3:

Edit the **truffle-config.js** file:

```javascript theme={"system"}
require('dotenv').config();
const { FireblocksWeb3Provider, ChainId } = require("@fireblocks/fireblocks-web3-provider");

module.exports = {
  networks: {
    sepolia: {
      provider: () => new FireblocksWeb3Provider({
        privateKey: process.env.FIREBLOCKS_API_PRIVATE_KEY_PATH,
        apiKey: process.env.FIREBLOCKS_API_KEY,
        vaultAccountIds: process.env.FIREBLOCKS_VAULT_ACCOUNT_IDS,
        chainId: ChainId.SEPOLIA,
      }),
      network_id: ChainId.SEPOLIA,
    },
  },
  compilers: {
    solc: {
      version: "0.8.13"
    }
  },
};
```

### Usage:

```bash theme={"system"}
truffle migrate --network sepolia
```


# EW API errors
Source: https://developers.fireblocks.com/reference/ew-api-errors



# Overview

This page covers API errors associated with the Fireblocks Embedded Wallet. Every error is accompanied by the correct HTTP error code and a message structured as follows:

```javascript theme={"system"}
{
	error: 'HTTP Error description',
	message: 'Error message'
}
```

# 4XX errors

## 400 - Bad Request

| Error Name                                     | Error Message                                                                                                                                     |
| :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
| No active webhook subscriptions                | The workspace was not configured with a Webhook endpoint that is required for NCW async communication.                                            |
| Unsupported algorithm                          | The provided algorithm for MPC key generation is not supported. Learn more [here](https://ncw-developers.fireblocks.com/docs/mpc-key-generation). |
| Pagination limit too large                     | The provided pagination limit parameter is higher than 50.                                                                                        |
| Validation failed (numeric string is expected) | The API call was made with an invalid NCW wallet identifier or account ID.                                                                        |

## 403 - Forbidden

| Error Name      | Error Message                                                                 |
| :-------------- | :---------------------------------------------------------------------------- |
| Wallet disabled | The requested NCW is disabled. Learn more [here](/reference/enablewallet).    |
| Device disabled | The requested device is disabled. Learn more [here](/reference/enabledevice). |
| Tenant disabled | The entire Fireblocks workspace is disabled.                                  |

## 404 - Not Found

| Error Name       | Error Message                         |
| :--------------- | :------------------------------------ |
| Wallet not found | The provided wallet ID was not found. |
| Device not found | The provided device ID was not found. |
| Tenant not found | The provided tenant ID was not found. |

## 409 - Conflict

| Error Name                      | Error Message                              |
| :------------------------------ | :----------------------------------------- |
| Incomplete MPC Setup            | The MPC Key generation was not completed.  |
| Ongoing setup already in motion | MPC Key generation ceremony is in process. |

***

# 1XXX errors

## 1000 - Incomplete Wallet

| Error Name        | Error Message                                                                                                                                |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------- |
| Incomplete Wallet | None of the devices in the Wallet have a COMPLETE status. Learn more [here](https://ncw-developers.fireblocks.com/docs/multiple-algorithms). |

## 1001 - Incomplete Device

| Error Name        | Error Message                                                                                                                     |
| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
| Incomplete Device | The device key status is in status INCOMPLETE. Learn more [here](https://ncw-developers.fireblocks.com/docs/multiple-algorithms). |

## 1002 - Incomplete Backup

| Error Name        | Error Message                                                                                                                                                                                                                    |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Incomplete Backup | The device key was not backed up. Learn more about backups [here](https://ncw-developers.fireblocks.com/docs/backup-recovery-1)  and multiple algorithms [here](https://ncw-developers.fireblocks.com/docs/multiple-algorithms). |

## 1003 - Unsupported Algorithms

| Error Name             | Error Message                                                                                                                       |
| :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------- |
| Unsupported Algorithms | The Algorithm is not supported by the workspace. Learn more [here](https://ncw-developers.fireblocks.com/docs/multiple-algorithms). |


# Exchange & Fiat Account Webhooks
Source: https://developers.fireblocks.com/reference/exchange-fiat-account-webhooks



> **Deprecation notice**
>
> Webhooks v1 will be deprecated on **June 15th, 2026**. Please use the Developer Center in the Fireblocks Console to upgrade to Webhooks V2, which offers improved reliability, performance, and observability.

This page describes all events relating to exchange and fiat accounts that produce webhook notifications, and their associated data objects.

The `type` parameter is automatically set to the description name for the data objects below.

## Exchange account added

Notification is sent when an exchange account is added.

**Webhook data**

| Parameter | Type                                    | Description                            |
| --------- | --------------------------------------- | -------------------------------------- |
| type      | string                                  | EXCHANGE\_ACCOUNT\_ADDED               |
| tenantId  | string                                  | Unique ID of your Fireblocks workspace |
| timestamp | number                                  | Timestamp in milliseconds              |
| data      | [ThirdPartyWebhook](#thirdpartywebhook) | Exchange accounts details              |

## Fiat account added

Notification is sent when a fiat account is added.

**Webhook data**

| Parameter | Type                                    | Description                            |
| --------- | --------------------------------------- | -------------------------------------- |
| type      | string                                  | FIAT\_ACCOUNT\_ADDED                   |
| tenantId  | string                                  | Unique ID of your Fireblocks workspace |
| timestamp | number                                  | Timestamp in milliseconds              |
| data      | [ThirdPartyWebhook](#thirdpartywebhook) | Fiat account details                   |

***

### ThirdPartyWebhook

| Parameter | Type   | Description                                                  |
| --------- | ------ | ------------------------------------------------------------ |
| id        | string | The ID of the third-party account on the Fireblocks platform |
| subType   | string | The subtype of the third party, ie. exchange or fiat name    |
| name      | string | Account name                                                 |


# Exchange Account Objects
Source: https://developers.fireblocks.com/reference/exchange-objects



## ExchangeAccount

| Parameter           | Type                                                                              | Description                                                                                         |
| ------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| id                  | string                                                                            | The ID of the exchange asset to return                                                              |
| type                | [ExchangeType](#exchangetype)                                                     | The name of the exchange the account is associated with                                             |
| name                | string                                                                            | Display name of the exchange account                                                                |
| status              | [ConfigChangeRequestStatus](/reference/general-objects#configchangerequeststatus) | Status of the exchange account connection                                                           |
| assets              | Array of [ExchangeAsset](#exchangeasset)                                          | Assets in the account                                                                               |
| isSubaccount        | boolean                                                                           | True if the account is a subaccount in an exchange                                                  |
| mainAccountId       | string                                                                            | The ID of the exchange main account                                                                 |
| tradingAccounts     | Array of [TradingAccount](#tradingaccount)                                        | Trading accounts under this exchange account                                                        |
| fundableAccountType | [TradingAccountType](#tradingaccounttype)                                         | The internal account that is used for deposits or withdrawals of this exchange's main or subaccount |

***

## ExchangeAsset

| Parameter    | Type   | Description                                                                                 |
| ------------ | ------ | ------------------------------------------------------------------------------------------- |
| id           | string | The ID of the exchange asset to return                                                      |
| total        | string | The total balance of the asset in the exchange account                                      |
| available    | string | The balance that can be withdrawn from the exchange account or moved to a different account |
| lockedAmount | string | Locked amount in the account                                                                |
| balance      | string | Deprecated - replaced by "total"                                                            |

***

## ExchangeType

| Parameter | Type   | Description                                                                                                                                                                                                                                                            |
| --------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type      | string | \[BINANCE, BINANCEUS, BITFINEX, BITHUMB, BITMEX, BITSO, BITSTAMP, BITTREX, BYBIT, CIRCLE, COINBASEEXCHANGE, COINBASEPRO, COINMETRO, COINSPRO, CRYPTOCOM, DERIBIT, GATE, GEMINI, HITBTC, HUOBI, IR, KORBIT, KRAKEN, KRAKENINTL, LIQUID, POLONIEX, OKCOIN, OKEX, SEEDCX] |

> **Notes**
>
> * The `BINANCEUS` value should be used only by Binance.us customers.
> * The `KRAKENINTL` value should be used only by non-US Kraken customers.

***

## TradingAccount

| Parameter | Type                                      | Description                                             |
| --------- | ----------------------------------------- | ------------------------------------------------------- |
| type      | [TradingAccountType](#tradingaccounttype) | The specific trading account under the exchange account |
| assets    | Array of [ExchangeAsset](#exchangeasset)  | Assets in the trading account                           |

***

## TradingAccountType

| Parameter | Type   | Description                                                                                                                                                                              |
| --------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type      | string | \[SPOT, FUTURES, MARGIN, FUNDING, OPTIONS, EXCHANGE, COIN\_MARGINED\_SWAP, USDT\_FUTURES, COIN\_FUTURES, USDT\_ISOLATED\_MARGINED\_SWAP, USDT\_MARGINED\_SWAP\_CROSS, FUNDABLE, UNIFIED] |


# Execute Payouts
Source: https://developers.fireblocks.com/reference/executing-payouts



# Creating a payout instruction set

When a user wants to send a payment to one or more of their merchants, they can use the Payout Service API to send the payout from their exchange account.

First, the user creates a payout instruction set using the [Create a payout instruction set](/reference/createpayout) API call. The instruction set defines:

* the payment account and its account type (vault, exchange, or fiat).
* the account type (vault account, exchange account, whitelisted address, network connection, fiat account, or merchant account), the amount, and the asset of payment for each payee account.

In this example, the user wants to send funds from an exchange account (id: “EX\_SUB3”) in their Fireblocks workspace. They want to send 43 USDC to Merchant 1 (id: “bef85a1c-b605-4b2e-bdb5-2d400f4d0bf3”) who is configured as an external wallet and 4,423 USDC to Merchant 2 (id: “3adc1f92-e791-44a8-9aee-7f31c2108b78”) who is configured as a Fireblocks Network connection.

## Example

```json theme={"system"}
{
  "paymentAccount": {
    "id": "EX_SUB3",
    "type": "EXCHANGE_ACCOUNT"
  },
  "instructionSet": [
    {
      "payeeAccount": {
        "id": "bef85a1c-b605-4b2e-bdb5-2d400f4d0bf3",
        "type": "EXTERNAL_WALLET"
      },
      "amount": {
        "amount": "43",
        "assetId": "USDC"
      }
    },
    {
      "payeeAccount": {
        "id": "3adc1f92-e791-44a8-9aee-7f31c2108b78",
        "type": "NETWORK_CONNECTION"
      },
      "amount": {
        "amount": "4423",
        "assetId": "USDC"
      }
    }
  ]
}
```

## Response

The user then receives a unique payoutId ("1fe3b61f-7e1f-4a19-aff0-4f0a524d44d7") for their payout instruction set. This payoutId can then be used for executing the payout.

The response body also lists the state of the payout instruction set as REQUESTED and the two payment states as NOT\_STARTED.

Following are descriptions of the parameters in the response:

* **payoutId**: unique ID for the payout
* **paymentAccount**
  * **id**: the ID of the payment account
  * **type**: the type of payment account (vault account, exchange account, or fiat account)
* **createdAt**: when the instruction set was created
* **state**: the state of the instruction set
* **initMethod**: method of creating the instruction set
* **instructionSet**: an array of instructions for the payout. Each one details the payee, the payment amount, and the status of the payment.
  * **id**: the ID for the individual payment in the instruction set
  * **name**: the name of the payee
  * **payeeAccount**
    * **id**: the ID of the account receiving the payment
    * **type**: the type of account receiving the payment
  * **amount**
    * **amount**: the amount being sent
    * **assetId**: the asset being sent
  * **state**: the status of the individual payment
  * **transactions**: the transactions included in the payment

```json theme={"system"}
{
  "payoutId": "1fe3b61f-7e1f-4a19-aff0-4f0a524d44d7",
  "paymentAccount": {
    "id": "EX_SUB3",
    "type": "EXCHANGE_ACCOUNT"
  },
  "createdAt": 1645365800,
  "state": "REQUESTED",
  "initMethod": "API",
  "instructionSet": [
    {
      "id": "6ea4a016-536b-49af-b1a0-40b343ccf879",
      "name": "Merchant 1",
      "payeeAccount": {
        "id": "bef85a1c-b605-4b2e-bdb5-2d400f4d0bf3",
        "type": "EXTERNAL_WALLET"
      },
      "amount": {
        "amount": "43",
        "assetId": "USDC"
      },
      "state": "NOT_STARTED",
      "transactions": []
    },
    {
      "id": "e783a79b-6acc-4d18-885d-ed533cad8eeb",
      "name": "Merchant 2",
      "payeeAccount": {
        "id": "3adc1f92-e791-44a8-9aee-7f31c2108b78",
        "type": "NETWORK_CONNECTION"
      },
      "amount": {
        "amount": "4423",
        "assetId": "USDC"
      },
      "state": "NOT_STARTED"
      "transactions": []
    }
  ]
}
```

***

# Executing a payout instruction set

Once the payout instruction set is created, the user can execute the payout using the [Execute a payout instruction set](/reference/executepayoutaction) API call and entering the payoutId of the instruction set that was just created ("1fe3b61f-7e1f-4a19-aff0-4f0a524d44d7").

***

# Monitoring payouts

The user can also monitor the status of the newly executed payout using the [Get the status of a payout instruction set](/reference/getpayout) API call and entering the payoutId.

## Example

`GET /payments/payout/1fe3b61f-7e1f-4a19-aff0-4f0a524d44d7`

## Response

The state and the payout status are returned.

```json theme={"system"}
{
  "payoutId": "1fe3b61f-7e1f-4a19-aff0-4f0a524d44d7",
  "paymentAccount": {
    "id": "EX_SUB3",
    "type": "EXCHANGE_ACCOUNT"
  },
  "createdAt": 1645365800,
  "state": "FINALIZED",
  "status": " DONE"
  "initMethod": "API",
  "instructionSet": [
    {
      "id": "6ea4a016-536b-49af-b1a0-40b343ccf879",
      "name": "Merchant 1",
      "payeeAccount": {
        "id": "bef85a1c-b605-4b2e-bdb5-2d400f4d0bf3",
        "type": "EXTERNAL_WALLET"
      },
      "amount": {
        "amount": "4312",
        "assetId": "USDC"
      },
      "state": "COMPLETED",
      "transactions": [{
            "id": "35a4b10c-1f83-4f0b-ba2a-da0e73be2d6e",
            "state": "COMPLETED",
            "timestamp": 1645367429
      }]
    },
    {
      "id": "e783a79b-6acc-4d18-885d-ed533cad8eeb",
      "name": "Merchant 2",
      "payeeAccount": {
        "id": "3adc1f92-e791-44a8-9aee-7f31c2108b78",
        "type": "NETWORK_CONNECTION"
      },
      "amount": {
        "amount": "4423",
        "assetId": "USDC"
      },
      "state": "COMPLETED",
      "transactions": [{
            "id": "4505e7d9-bfc7-41bc-9750-54311fcbbf26",
            "state": "COMPLETED",
            "timestamp": 1645367449
      }]
    }
    }
  ],
  "reportUrl": "https://some-url.com/reports/cc5777c1-75a9-4337-aebd-f1f5a40a9391"
}
```


# Postman Guide
Source: https://developers.fireblocks.com/reference/explore-postman-collection



# Overview

Postman is an application designed to help with API integration and exploration. Intuitive for different tech skill levels, this is the tool of choice both for experienced developers and no-code enthusiasts to get familiar with our available endpoints, requests, and responses.

Using our Postman Collection, you can start testing our API before you write a single line of code.

## Install Postman and Fireblocks Collection

1. Download and install the [Postman app](https://www.postman.com/downloads/) or [use Postman online](https://identity.getpostman.com/login?continue=https%3A%2F%2Fweb.postman.co%2Fhome).
2. **Import the Fireblocks collection:**

   [![Run in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/25881726-6597f15a-56e5-4c82-a75e-2befc2c5264d?action=collection%2Ffork\&collection-url=entityId%3D25881726-6597f15a-56e5-4c82-a75e-2befc2c5264d%26entityType%3Dcollection%26workspaceId%3Dddfe6a6b-2c7b-4005-89f3-7204e03ec3b6%3Fenv%3DBoilerplate%2520Fireblocks%2520Environment%253D%253D)

After following the steps above and opening Postman, you'll see the Fireblocks API collection.


# Fee Estimation Objects
Source: https://developers.fireblocks.com/reference/fee-estimation-objects



## NetworkFee

| Parameter   | Type   | Description                                                 |
| ----------- | ------ | ----------------------------------------------------------- |
| feePerByte  | string | \[optional] For UTXOs                                       |
| gasPrice    | string | \[optional] For Ethereum assets (ETH and Tokens)            |
| networkFee  | string | \[optional] All other assets                                |
| baseFee     | string | \[optional] Base Fee according to EIP-1559 (ETH assets)     |
| priorityFee | string | \[optional] Priority Fee according to EIP-1559 (ETH assets) |

***

## TransactionFee

| Parameter   | Type   | Description                                                                          |
| ----------- | ------ | ------------------------------------------------------------------------------------ |
| feePerByte  | string | \[optional] For UTXOs,                                                               |
| gasPrice    | string | \[optional] For Ethereum assets (ETH and Tokens)                                     |
| gasLimit    | string | \[optional] For Ethereum assets (ETH and Tokens), the limit for how much can be used |
| networkFee  | string | \[optional] Transaction fee                                                          |
| baseFee     | string | \[optional] Base Fee according to EIP-1559 (ETH assets)                              |
| priorityFee | string | \[optional] Priority Fee according to EIP-1559 (ETH assets)                          |

***

## EstimatedTransactionFeeResponse

| Parameter | Type                              | Description                                                      |
| --------- | --------------------------------- | ---------------------------------------------------------------- |
| low       | [TransactionFee](#transactionfee) | Transactions with this fee will probably take longer to be mined |
| medium    | [TransactionFee](#transactionfee) | Average transactions fee                                         |
| high      | [TransactionFee](#transactionfee) | Transactions with this fee should be mined the fastest           |

## EstimatedFeeDetails

| Parameter | Type                                                                                                                   | Description                                                                        |
| --------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| low       | [FeeBreakdown - Solana Specific](#feebreakdown---solana-specific) OR [FeeBreakdown - Generic](#feebreakdown---generic) | Detailed fee breakdown where the transaction will probably take longer to be mined |
| medium    | [FeeBreakdown - Solana Specific](#feebreakdown---solana-specific) OR [FeeBreakdown - Generic](#feebreakdown---generic) | Average transactions fee                                                           |
| high      | [FeeBreakdown - Solana Specific](#feebreakdown---solana-specific) OR [FeeBreakdown - Generic](#feebreakdown---generic) | Detailed fee breakdown where the transaction will be mined the fastest             |

## FeeBreakdown - Solana Specific

| Parameter   | Type   | Description                                  |
| ----------- | ------ | -------------------------------------------- |
| baseFee     | string | Base fee for Solana transaction              |
| priorityFee | string | Priority fee for Solana transaction          |
| rent        | string | Rent fee for Solana account creation/storage |
| totalFee    | string | Total fee amount                             |

## FeeBreakdown - Generic

| Parameter   | Type   | Description            |
| ----------- | ------ | ---------------------- |
| baseFee     | string | Base fee component     |
| priorityFee | string | Priority fee component |
| totalFee    | string | Total fee amount       |


# Fiat Account Objects
Source: https://developers.fireblocks.com/reference/fiat-account-objects



## FiatAccount

| Parameter | Type                              | Description                              |
| --------- | --------------------------------- | ---------------------------------------- |
| id        | string                            | The ID of the account                    |
| type      | string                            | \[ BLINC ]                               |
| name      | string                            | The display name of the fiat account     |
| address   | string                            | The address of the account               |
| assets    | Array of [FiatAssets](#fiatasset) | An array of the assets under the account |

***

## FiatAsset

| Parameter | Type   | Description              |
| --------- | ------ | ------------------------ |
| id        | string | The ID of the asset      |
| balance   | string | The balance of the asset |


# Fund the Gas Station
Source: https://developers.fireblocks.com/reference/fund-the-gas-station



# Overview

Maintaining funds for the Gas Station is critical to avoid business interruptions. Transactions made from wallets with insufficient gas will continuously fail until you add more funds.

Ensure proper funding by depositing the appropriate base assets into the Gas Station wallet. The Gas Station will then use these assets to refuel your monitored vault accounts with gas for their outbound transactions.

***

# Funding with the API

1. Call the [List internal wallets endpoint](/api-reference/internal-wallets/list-internal-wallets) to find the Gas Station's wallet ID.
2. Call the [Create a new transaction endpoint](/api-reference/transactions/create-a-new-transaction), enter **INTERNAL\_WALLET** in the destination object's **type** field and the Gas Station's wallet ID in the **walletId** field, and then enter the appropriate base asset (as [defined in Fireblocks](/api-reference/blockchains-&-assets/list-assets-legacy)) in the **assetId** field.

The example below funds the Gas Station wallet with ETH based on its `gasStationWalletUUID`, in the value of 0.1 ETH transferred from vault account ID 0.

```javascript theme={"system"}
const fundGasStationWallet = async (
  payload: TransactionRequest,
): Promise<CreateTransactionResponse | undefined> => {
  try {
    const result = await fireblocks.transactions.createTransaction({
      transactionRequest: payload,
    });
    console.log(JSON.stringify(result, null, 2));
    return result.data;
  } catch (e) {
    console.error(e);
  }
};

fundGasStationWallet({
  assetId: "ETH", //update the assetID
  source: {
    type: TransferPeerPathType.VaultAccount,
    id: "1", // update to your funding vault account ID
  },
  destination: {
    type: TransferPeerPathType.InternalWallet,
    id: "904c6da6-5aae-4280-bcb3-d0b1a36fc6e9", //update to your Gas Station internal Wallet UUID
  },
  amount: 0.5,
  note: "Gas Station Internal Wallet Funding",
});
```

```javascript theme={"system"}
async function fundGasStationWallet(assetId, gasStationWalletUUID, fillAmount, fundingVaultId){
    const payload = {
        assetId: assetId,
        source: {
            type: PeerType.VAULT_ACCOUNT,
            id: fundingVaultId
        },
        destination: {
            type: PeerType.INTERNAL_WALLET,
            id: gasStationWalletUUID
        },
        amount: fillAmount,
        note: "Gas Station Funding"
    };
    const result = await fireblocks.createTransaction(payload);
    console.log(JSON.stringify(result, null, 2));
 }
 fundGasStationWallet("ETH", "gasStationWalletUUID" ,"0.1","0");
```

```python theme={"system"}
def fund_gas_station(asset_id: str, gas_station_wallet_uuid: str, fill_amount: str,funding_vault_id: str):
    tx_id = fireblocks.create_transaction(asset_id=asset_id,
                                  				amount=fill_amount,
				                                  source=TransferPeerPath("VAULT_ACCOUNT", funding_vault_id),
        				                          destination=DestinationTransferPeerPath("INTERNAL_WALLET",gas_station_wallet_uuid)
                				                 )
    print(tx_id)

fund_gas_station("ETH","gasStationWalletUUID", "0.1","0")
```


# Gas Station Objects
Source: https://developers.fireblocks.com/reference/gas-station-objects



## GasStationPropertiesResponse

| Parameter     | Type                                                | Description                                                 |
| ------------- | --------------------------------------------------- | ----------------------------------------------------------- |
| balance       | dictionary                                          | A dictionary of an asset and its balance in the Gas Station |
| configuration | [GasStationConfiguration](#gasstationconfiguration) | The settings of your Gas Station                            |

***

## GasStationConfiguration

| Parameter    | Type   | Description                                                                               |
| ------------ | ------ | ----------------------------------------------------------------------------------------- |
| gasThreshold | string | Below this ETH balance the address will be funded up until the gasCap value, in ETH units |
| gasCap       | string | Up to this level, the address will be funded with ETH, in ETH units                       |
| maxGasPrice  | string | The funding transaction will be sent with this maximum value gas price, in Gwei units     |


# General Objects
Source: https://developers.fireblocks.com/reference/general-objects



## ConfigChangeRequestStatus

| Parameter | Type   | Description                                                        |
| --------- | ------ | ------------------------------------------------------------------ |
| status    | string | \[ WAITING\_FOR\_APPROVAL, APPROVED, CANCELLED, REJECTED, FAILED ] |

***

## Paging

| Parameter | Type   | Description              |
| --------- | ------ | ------------------------ |
| next      | string | Cursor to the next page. |


# Handle API Errors
Source: https://developers.fireblocks.com/reference/handling-api-errors



# Overview

Understanding errors and how to handle them is critical to user experience and business operations when working with *any* third-party API.

Some errors might include:

* A timeout as the third-party service is experiencing issues or is down.
* An improperly formatted request due to user error or a non-fatal software bug.
* A runtime error due to a system state or an "unexpected" error.

These types of errors are important to handle when working with third-party APIs and handling individual errors will depend on the nature of each API call.

## Error types

In this section, we will dive into how to handle API errors when using Fireblocks API in terms of best practices and common pitfalls.

As the Fireblocks API uses HTTP requests to send the calls, we will look into three main error types:

1. [Non-HTTP errors](doc:error-handling#non-http-errors)
2. [4xx status codes](doc:error-handling#4xx-status-codes)
3. [500 status code](doc:error-handling#500-status-code)

> **How to handle unspecified errors**
>
> While we do our best to cover all the errors that are possible, and are constantly improving error reporting, you might encounter an error you did not read about in this guide, or the approach and best practices do not suffice.
>
> We recommend making sure to read the message that accompanies every Fireblocks API error as these are usually descriptive and can help pinpoint the issue.

***

# Non-HTTP errors

Non-HTTP errors are a broad error type that relates to anything that is not specifically a response back from the Fireblocks API. As a result, this error type may contain many individual errors that can typically be resolved with the relevant third-party documentation.

Examples of such errors include:

* Errors that prevent the execution of `.js` or `.py` (or any other extension) files such as `command not found`, or `No such file or directory`
* Errors relating to internal formatting of a file (missing indent, missing bracket, `==` instead of `===`)
* Errors relating to system state, such as lack of memory, or network connectivity issues

As described in our API guides, signing a JWT (JSON Web Token) is a critical part of API usage as the means of authenticating your message and validating your identity. (This assumes the private key used to sign your API request is securely stored and not available to anyone else).

You may be unable to sign the JWT token if you are experiencing issues with your private key. These issues are classified as "**private key corruption**". While uncommon, it can be a serious issue when trying to sign API requests.

## Private key corruption

Observe the following error message:

(If you are unfamiliar with this error, a Google search will yield many results pointing to authentication problems.)

```text theme={"system"}
Error:  Error: error:1E08010C:DECODER routines::unsupported
    at Sign.sign (/myproject/lib/internal/crypto/sig.js:131:29)
    at Object.sign /myproject/node_modules/jwa/index.js:152:45)
    at Object.jwsSign [as sign] (/myproject/node_modules/jws/lib/sign-stream.js:32:24)
    at module.exports [as sign] (/myproject/node_modules/jsonwebtoken/sign.js:204:16)
    at ApiTokenProvider.signJwt (/myproject/fireblocks-sdk-js/src/api-token-provider.ts:11:28)
    at ApiClient.<anonymous> (/myproject/fireblocks-sdk-js/src/api-client.ts:15:41)
    at Generator.next (<anonymous>)
    at /myproject/fireblocks-sdk-js/dist/api-client.js:8:71
    at new Promise (<anonymous>)
    at __awaiter (/myproject/fireblocks-sdk-js/dist/api-client.js:4:12)
    at ApiClient.issueGetRequest (/myproject/fireblocks-sdk-js/dist/api-client.js:27:16)
    at FireblocksSDK.<anonymous> (/myproject/fireblocks-sdk-js/src/fireblocks-sdk.ts:537:37)
    at Generator.next (<anonymous>)
    at /myproject/fireblocks-sdk-js/dist/fireblocks-sdk.js:18:71
    at new Promise (<anonymous>)
    at __awaiter (/myproject/fireblocks-sdk-js/dist/fireblocks-sdk.js:14:12)
```

```text theme={"system"}
Traceback (most recent call last):
  File "/myproject/venv/lib/python3.10/site-packages/jwt/algorithms.py", line 257, in prepare_key
    key = load_pem_private_key(key, password=None)
  File "/myproject/venv/lib/python3.10/site-packages/cryptography/hazmat/primitives/serialization/base.py", line 22, in load_pem_private_key
    return ossl.load_pem_private_key(data, password)
  File "/myproject/venv/lib/python3.10/site-packages/cryptography/hazmat/backends/openssl/backend.py", line 900, in load_pem_private_key
    return self._load_key(
  File "/myproject/venv/lib/python3.10/site-packages/cryptography/hazmat/backends/openssl/backend.py", line 1168, in _load_key
    self._handle_key_loading_error()
  File "/myproject/venv/lib/python3.10/site-packages/cryptography/hazmat/backends/openssl/backend.py", line 1227, in _handle_key_loading_error
    raise ValueError(
ValueError: ('Could not deserialize key data. The data may be in an incorrect format, it may be encrypted with an unsupported algorithm, or it may be an unsupported key type (e.g. EC curves with explicit parameters).', [_OpenSSLErrorWithText(code=503841036, lib=60, reason=524556, reason_text=b'error:1E08010C:DECODER routines::unsupported')])
```

The issue within this error is a "corruption" of the private key. "Corruption" can also mean human error such as submitting an incorrect file that is not a private key. Follow the instructions below to resolve this error.

1. Verify that the file being used is indeed a private key.

   A private key typically looks like this:

   ```yaml theme={"system"}
   -----BEGIN PRIVATE KEY-----
              ...
   -----END PRIVATE KEY-----
   ```

2. Verify that the private key is intact.

3. Generate something out of the private key using OpenSSL.

   This command will attempt to convert the private key into its corresponding public key:

   `openssl rsa -in <api-private-key>.key -pubout`

   A valid response will look something like this:

   ```yaml theme={"system"}
   -----BEGIN PUBLIC KEY-----
               ...
   -----END PUBLIC KEY-----
   ```

***

# 4xx status codes

4xx status codes are codes that are returned as part of an HTTP request to indicate a problem on the client's side - in the context of this article, it means that there is an issue with the request that you have sent.

We will look into 3 specific status codes and how to handle each of them:

1. [400 - Bad request](doc:error-handling#400---bad-request) Indicates that the API request itself is incorrect and contains invalid or incorrect values
2. [401 - Unauthorized](doc:error-handling#401---unauthorized) - Indicates that the API request is sent with invalid authentication information (for example, bad JWT)
3. [403 - Forbidden](doc:error-handling#403---forbidden) - Indicates that the API request is trying to perform something that the user is not allowed to do
4. [404 - Not found](doc:error-handling#404---not-found) - Indicates that the API request is trying to query a page that does not exist

In addition to the three codes, we would also like to remind you that there is the status code `429 Too many requests`, which is caused by breaking the rate limits. More information can be found in the [Working with Rate Limits](doc:rate-limits) article.

> **Example code**
>
> The example code is written to illustrate how to approach the described scenario. It might contain functions or types which are not explicitly written out, but we add a short description of what they do after the code sample.
>
> No such type or function is written in the SDK and they merely are used to illustrate some logical container for an operation.

> **Assumptions for examples**
>
> Throughout each Error Handling section the following assumptions apply:
>
> * The user input ***may not*** be valid, through function call or direct integration.
> * The network connection is functioning as expected.
> * The system has sufficient resources (memory and disk space).
>
> This is important for security and stability, as it shows how to ensure your information is valid before submitting the request and how to double-check or sanitize the user input.
>
> Typical validations are provided at the bottom of the article.

## 400 - Bad request

As mentioned above, 400 response codes indicate that the request you sent contains incorrect information or is invalid.

#### 400 example - Bad request

Your internal database links users per asset public keys with their internal database reference (for example, their user ID).

To do this, upon registration or upon some update, your code calls the following `getPublicKey`\ `get_public_key` function with the asset **supplied by the user**:

```javascript theme={"system"}
const DEFAULT_VAULT_ACCOUNT_ID = "123";
/**
fbksSdk - an instance of FireblocksSDK
asset - the asset id
*/
async function getPublicKey(fbksSdk, asset){
  let pubKey = await fbks.getPublicKeyInfoForVaultAccount({
    vaultAccountId: DEFAULT_VAULT_ACCOUNT_ID,
    assetId:asset,
    compressed:true,
    addressIndex:"0",
    change:"0"
  });
  //... Some extra work on the public key ...
}
```

```python theme={"system"}
DEFAULT_VAULT_ACCOUNT_ID = "123";

def get_public_key(fbks, asset):
  """
  fbks - FireblocksSDK instance
  asset - the asset id
  """
  pub_key = fbks.get_public_key_info_for_vault_account(
    vault_account_id=DEFAULT_VAULT_ACCOUNT_ID,
    asset_id=asset,
    compressed=False,
    change="0",
    address_index="0"
  )
  # ... Some extra work on the public key ...
```

The user mistakenly put an invalid asset (for example `BTC1` instead of `BTC`). Your code will receive the following error:

```text theme={"system"}
Error: Request failed with status code 400
    at createError (/myproject/fireblocks-sdk-js/node_modules/axios/lib/core/createError.js:16:15)
    at settle (/myproject/fireblocks-sdk-js/node_modules/axios/lib/core/settle.js:17:12)
    at IncomingMessage.handleStreamEnd (/myproject/fireblocks-sdk-js/node_modules/axios/lib/adapters/http.js:293:11)
    at IncomingMessage.emit (node:events:525:35)
    at endReadableNT (node:internal/streams/readable:1359:12)
    at process.processTicksAndRejections (node:internal/process/task_queues:82:21)
```

```text theme={"system"}
Traceback (most recent call last):
  File "/myproject/main.py", line 10, in <module>
    get_public_key(fbksSdk, "jngjewqn")
  File "/myproject/main.py", line 8, in get_public_key
    fbks.get_public_key_info_for_vault_account(vault_account_id="2", asset_id=asset, compressed=False, change="0", address_index="0")
  File "/myproject/venv/lib/python3.10/site-packages/fireblocks_sdk/sdk.py", line 1066, in get_public_key_info_for_vault_account
    return self._get_request(url)
  File "/myproject/venv/lib/python3.10/site-packages/fireblocks_sdk/sdk.py", line 1334, in _get_request
    return handle_response(response, page_mode)
  File "/myproject/venv/lib/python3.10/site-packages/fireblocks_sdk/sdk.py", line 22, in handle_response
    raise FireblocksApiException("Got an error from fireblocks server: " + response.text, error_code)
fireblocks_sdk.api_types.FireblocksApiException:
  Got an error from fireblocks server: {
    "message":"The asset 'rando' is not supported by Fireblocks, please check the supported assets endpoint.",
    "code":1503
  }
```

For cases where you receive a 400 HTTP status code error, try using a `try{}catch{}`\ `try:...except...` block. This can be used to handle the error in the proper way, like notifying the user or adjusting the input parameters before attempting the call again.

The following is an example of how these types of 400-based errors can be handled for the specific scenario we described:

```javascript theme={"system"}
const DEFAULT_VAULT_ACCOUNT_ID = "123";
/**
fbksSdk - an instance of FireblocksSDK
asset - the asset id
*/
async function getPublicKey(fbksSdk, asset){
  let pubKeyResponse = undefined;
  try{
    pubKeyResponse = await fbks.getPublicKeyInfoForVaultAccount({
      vaultAccountId: DEFAULT_VAULT_ACCOUNT_ID,
      assetId:asset,
      compressed:true,
      addressIndex:"0",
      change:"0"
    });
  } catch (e) {
    let response = e.response;
    if(response.status < 400 || response.status >= 500){
      	// Non request based error
      	// We assume that execution of this function will be halted after this block is done
    }

    let respData = response.data;
    if(respData.code === 1503){ // This is discussed later on in the article
      	return new Error("The asset you specified is invalid, please verify that you're sending the correct asset.");
    }

    // Other handling
  }
  //... Some extra work on the public key ...
}
```

```python theme={"system"}
DEFAULT_VAULT_ACCOUNT_ID = "123"
# fbksSdk - an instance of FireblocksSDK
# asset - the asset id
def get_public_key(fbks_sdk, asset):
    pub_key = None
    try:
        pub_key = fbks_sdk.get_public_key_info_for_vault_account(
            vault_account_id=DEFAULT_VAULT_ACCOUNT_ID,
            asset_id=asset,
            compressed=True,
            address_index=0,
            change=0
        )
    except FireblocksApiException as e:
        if e.error_code == 1503:
            raise Exception("The asset you specified is invalid, please verify that you're sending the correct asset.")

        # Other handling

    # ... Some extra work on the public key ...
```

In both code samples, start by verifying that you received a 4xx response code (for 5xx refer to the information below). Then, you'll get the call response data and reference the parameter called `code` which represents the error code returned for the request. Each error code indicates a different issue with the request.

[Refer to our API Responses page to learn more.](ref:api-responses)

* Fireblocks Python SDK does this seamlessly for 4xx and 5xx errors, therefore handling should only consider the error code or message

### Handling a 400 error

When a 400 response is returned from the Fireblocks API, you will receive the following message:

```json theme={"system"}
{
  error_code: number (optional)
  message: string
}
```

This message will provide a description to inform you of any potential issues.

A best practice for error handling that you can see below is setting up a proper error handling flow for sensitive error code responses. This is done by first outlining the following:

1. Identify the features/components you're using - Are you performing wallet-specific operations (whitelisting, creating a new wallet, adding a deposit address to a wallet, etc.)?
2. Identify the user / system-provided inputs - What is constant? What is received as part of the system state (a database query, a read from a file, etc.)? What is received from user input?
3. Identify the potential errors from the [API Responses page](ref:api-responses).

After you've identified the points above, prepare your error handling respective to the API calls to best fit your needs (inform the user, run some runtime fix of the system state, etc.).

#### Implementing 400 error handling

> **Integrating into your code**
>
> The code sample, as well as the general flow, is customizable to fit your code, business logic, or existing implementation.
>
> The best practice is to change the code (shown below) to match your code language preference, as well as your business-specific practices, regulations and systems.
>
> Errors should also receive the same treatment, with the errors written in this section as an example, and should be changed to work with your flow.
>
> The most important part to take away from this section is to identify the components you'll be using and what potential errors might occur based on what input you'll receive.

For example, you're working on a system that receives a request from a user to perform a withdrawal of some amount of a given asset from their Fireblocks asset wallet address.

1. Refresh the balance of the specific asset they'd want to withdraw from the vault account we assigned to this user - using the [refresh asset balance data](ref:post_vault-accounts-vaultaccountid-assetid-balance) operation.
2. Create a transaction to send the asset from their vault account to the target address - using the [create transaction](ref:post_transactions) operation.

The refresh balance operation uses a vault account (`vaultAccountId`) and an asset (`assetId`), while the create transaction has very many potential parameters. This means that the errors returned from these parameters You can narrow down the cause of the error by going through each operation requirement to perform for your desired end result.

1. The [refresh asset balance data](ref:post_vault-accounts-vaultaccountid-assetid-balance) operation requires a valid vault account Id and a valid asset.
2. The [create transaction](ref:post_transactions) operation requires:
   1. A valid asset (can be assumed valid after operation #1 takes place)
   2. A valid amount of said asset (which does not exceed what they have in the wallet)
   3. A valid target address

Referencing the [API Responses page](ref:api-responses) shows that given the operation requirements you should expect to see these error codes:

1. `1503` - invalid asset
2. `11001` - invalid vault account id

You might be asking yourself - what about the amount and the target address? While incorrect in the scope of the example, these values could theoretically be anything (within their given domains, amount as a positive integer, and address as a string of some length).

> **Monitoring transaction status**
>
> The failures caused by amount and destination address values are not covered in this guide. [Please refer to Monitoring transaction status for more information about these specific errors.](doc:monitor-tx-status)

```javascript theme={"system"}
// Fireblocks SDK initialized beforehand and is defined as the parameter - fbks
// There exists some variable which allows us to query a database for information, defined as - dbSvc
async function withdrawal(userId, asset, amount, to){
    if(!dbSvc.userExists(userId)){
        return new Error(`Unknown user: ${userId}`);
    }
    if(!validateToAddress(to, asset)){
          return new Error("The address provided does not match conventions for the asset specificed.");
    }
    // We assume that the information is stored somewhere you are able to retrieve it, but where it's stored is irrelevant, this is merely for the example
    let userVaultAccountId = dbSvc.getVaultAccountForUser(userId);
    let assetBalance = undefined;
    try{
        assetBalance = parseFloat((await fbks.refreshVaultAssetBalance(userVaultAccountId, asset)).available);
    } catch (e) {
        fbksError(e);
    }

    // At this point you might want to do additional checks against different information
    // in your system, depending on what your needs are.

    let txArgs = {
        source: {
            type: PeerType.VAULT_ACCOUNT,
            id: userVaultAccountId
        },
        destination: {
            type: PeerType.ONE_TIME_ADDRESS,
            oneTimeAddress: {
                address: to
            }
        },
        operation: TransactionOperation.TRANSFER,
        amount: amount,
        assetId: asset
    };

    try{
        let {txId: id} = (await fbks.createTransaction(txArgs));
        // Continue monitoring the transaction
    } catch (e) {
        fbksError(e);
    }
}

// This function is used as a generic error handler for all FireblocksAPI calls, preventing us from duplicating code and
// allowing us to easily fix issues in a single location. If a call requires custom handling, its catch clause can
// be written without using this function
function fbksError(e){
    let resp = e.response;
    if(resp !== 400) {
        // Handle other errors and return
    }

    let respData = resp.data;
    switch(respData.code){
        case 1503:
            throw new Error("The asset specified is invalid");
        case 11001:
            // In this scenario, since the vault account Id is stored in a local database, we might want to
            // show a different error or potentially raise an alert, depending on your needs.
            throw new Error("The vault account Id used is invalid");
        default:
            // If we didn't map the potential error code, it's important to write as much information
            // about the error as possible, that way we can patch the code with minimal replications or intrusive investigation
            logUnexpectedError(`Faced error: ${util.inspect(respData,false,null,true)} which is not mapped.`);
            throw new Error("Unexpected error - please try again later");
    }
}
```

```python theme={"system"}
# Fireblocks SDK initialized beforehand and is defined as the parameter - fbks
# There exists some variable which allows us to query a database for information, defined as - db_svc
def withdrawal(user_id, asset, amount, to):
    if not db_svc.user_exists(user_id):
        raise Exception(f"User does not exist: {user_id}")
    if not validate_address(to, asset):
        raise Exception("The address provided does not match conventions for the asset specificed.")

    user_vault_account_id = db_svc.get_vault_account_for_user(user_id)
    asset_balance = None
    try:
        asset_balance = fbks.refresh_vault_asset_balance(user_vault_account_id, asset)
    except FireblocksApiException as e:
        fbks_error_handler(e)

    try:
        fbks.create_transaction(
            tx_type=fireblocks_sdk.TRANSACTION_TRANSFER,
            amount=amount,
            source=TransferPeerPath(fireblocks_sdk.VAULT_ACCOUNT, user_vault_account_id),
            destination=DestinationTransferPeerPath(fireblocks_sdk.ONE_TIME_ADDRESS, one_time_address=to)
        )
    except FireblocksApiException as e:
        fbks_error_handler(e)

# This function is used as a generic error handler for all FireblocksAPI calls, preventing us from duplicating code and
# allowing us to easily fix issues in a single location. If a call requires custom handling, its catch clause can
# be written without using this function
def fbks_error_handler(e):
    if e.error_code == 1503:
        raise Exception("The asset specified is invalid")
    elif e.error_code == 11001:
        # In this scenario, since the vault account Id is stored in a local database, we might want to
        # show a different error or potentially raise an alert, depending on your needs.
        raise Exception("The vault account Id used is invalid")
    else:
        # If we didn't map the potential error code, it's important to write as much information
        # about the error as possible, that way we can patch the code with minimal replications or intrusive investigation
        log_unexpected_error(f"Faced error: {e} which is not mapped.")
        raise Exception("Unknown error - please try again later")
```

Let's dissect the above code (almost identical for Python);

1. **Lines 4-6**: Performs checks on the user. (This depends on your business logic.)
2. **Lines 7-9**: Performs validation of the `to` address. Using the asset, you'll see the format of the address to expect. You'll have to define this more thoroughly, however, there are libraries that already provide this functionality.
   1. Example: BTC SegWit will start with `bc1`, and EVM-based chains will be a 40-character hex (with `0x` prefix and checksummed). You'll have to define this more thoroughly, however, there are libraries that already provide this functionality.
3. **Line 11**: Get the vault account id for the user. Similar to #1 it depends on your business logic and specific setup.
4. **Lines 13-17**: Refresh the balance of the provided information (asset and vault account ID), using the try and catch you catch any exceptions, and send them to the generic API handler (this is also specific to your implementation, the way it's described here might not be the correct way to handle it in your code). If there was an error, with one of the expected, we return some descriptive error message which can be changed to explain to the user what to do.
5. **Lines 22-36**: Build the withdrawal transaction.
6. **Lines 39-43**: Send the transaction. Refer to our generic handler for any error generated from creating the transaction.

> **Fixing live error code 11001**
>
> The only part of the above code above that does not apply to live error handling error code `11001`, which specifies an invalid vault account. In this example is derived from a mock database. In live scenarios you will need to decide how to fix this yourself.

## 401 - Unauthorized

This error, though not common, basically occurs when a request that was sent contains either a missing, invalid, or otherwise incorrect JWT, and therefore the transaction fails.

Different codes indicate different reasons for the error caused in the JWT. Unless there is a widespread issue with the SDKs themselves, 401 error response codes will only result from:

1. Signing with a different user's private key (e.g. signing with another API user's key instead of yours)
2. Signing with the correct private key, but the incorrect User ID.

Both scenarios are not directly code related, and will most likely occur during the development stages of integration or executions of impromptu scripts such as staking. As a result, we cannot provide code samples to address this.

[Refer to the API Responses page to review codes related to 401 errors for JWT.](ref:api-responses)

When encountered, simply validate the API User key and API User secret path (make sure it contains the correct private key). A JWT error code might indicate a critical issue on the production server which you should address immediately. If you encounter such an error during production, do the same on the server that the code is running on.

The only other cause of this error is when you do not use the official, unedited Fireblocks SDK (or one of the specific supported side branches). In this instance, modifications to the source code of the Fireblocks SDK caused the error.

To address this, you'll need to check code modification and check if a change was made that would yield such an error. Keep in mind, however, that there is no beneficial need to perform changes to the Fireblocks SDK. Therefore, we will not discuss any further details on this matter.

## 403 - Forbidden

For specific API calls, such as [get audit logs](ref:get_audits) or [list users](ref:get_users), you might receive HTTP status code 403. This is uncommon since the API currently does not include user changes capabilities and only a small number of operations that can trigger 403.

If you see that you might run into the error, test the code prior to moving it to production. This can make certain that your API user has the sufficient permissions needed.

[Refer to the API Responses page to review specific 403 errors.](ref:api-responses)

## 404 - Not Found

A very common error code, "404 not found". This indicates that the page you were looking for, does not exist. Simply, this error message type states that whatever query you performed, whatever information you wanted to get - does not exist.

How to address such an issue:

1. Identify what's missing - These errors usually happen with GET requests, more than with other HTTP methods, and those GET requests are usually no more than 3 different arguments (with some exceptions), to help you pinpoint which one is "incorrect".
2. Address the missing data by either regenerating it using a new Fireblocks API call or raising an exception/error to notify upstream whoever sent this data.

Let's take a look at an example:
We provide some code that is invoked by a different component of the system. This code will query a vault account for the number of different assets this wallet contains. If there are more than 10 different assets, `true`, otherwise, this value is `false`.

Using the [Find a vault account by ID](ref:get_vault-accounts-vaultaccountid) API reference, you know this specific call uses the vault feature, therefore you can quickly identify the likely one:

* `1004` - No vault account by that Id

You can assume this since the response of the API call provides all the data you need, while only needing a single argument - the vault account Id. So, you can identify that this is the most suitable error code.

The code:

```javascript theme={"system"}
// Fireblocks SDK initialized beforehand and is defined as the parameter - fbks
// There exists some variable which allows us to query a database for information, defined as - dbSvc
async function sufficientAssets(userId){
    if(!dbSvc.userExists(userId)){
        return new Error(`Unknown user: ${userId}`);
    }
    // We assume that the information is stored somewhere you are able to retrieve it, but where it's stored is irrelevant, this is merely for the example
    let userVaultAccountId = dbSvc.getVaultAccountForUser(userId);
    try{
        let numberOfAssets = (await fbks.getVaultAccountById(userVaultAccountId)).assets.length;
        return numberOfAssets <= 10;
    } catch (e) {
        fbksError(e);
    }
}

// This function is used as a generic error handler for all FireblocksAPI calls, preventing us from duplicating code and
// allowing us to easily fix issues in a single location. If a call requires custom handling, its catch clause can
// be written without using this function
function fbksError(e){
    let resp = e.response;
    if(resp !== 400) {
        // Handle other errors and return
    }

    let respData = resp.data;
    switch(respData.code){
        case 1004:
            throw new UnknownVaultAccountIdError();
        default:
            // If we didn't map the potential error code, it's important to write as much information
            // about the error as possible, that way we can patch the code with minimal replications or intrusive investigation
            logUnexpectedError(`Faced error: ${util.inspect(respData,false,null,true)} which is not mapped.`);
            throw new Error("Unexpected error - please try again later");
    }
}
```

```python theme={"system"}
# Fireblocks SDK initialized beforehand and is defined as the parameter - fbks
# There exists some variable which allows us to query a database for information, defined as - db_svc
def sufficient_assets(user_id):
    if not db_svc.user_exists(user_id):
        raise Exception(f"User does not exist: {user_id}")

    user_vault_account_id = db_svc.get_vault_account_for_user(user_id)
    try:
        asset_count = len(fbks.get_vault_account_by_id(user_vault_account_id)["assets"])
        return asset_count <= 10
    except FireblocksApiException as e:
        fbks_error_handler(e)

# This function is used as a generic error handler for all FireblocksAPI calls, preventing us from duplicating code and
# allowing us to easily fix issues in a single location. If a call requires custom handling, its catch clause can
# be written without using this function
def fbks_error_handler(e):
    if e.error_code == 1004:
        raise UnknownVaultAccountIdException()
    else:
        # If we didn't map the potential error code, it's important to write as much information
        # about the error as possible, that way we can patch the code with minimal replications or intrusive investigation
        log_unexpected_error(f"Faced error: {e} which is not mapped.")
        raise Exception("Unknown error - please try again later")
```

Let's dissect the code once more (almost identical for python):

1. Lines 4-6: Check the existence of such a `userId`
2. Line 8: Finds the vault account correlated to this `userId`
   1. Let's assume, in this case, that if no such vault account exists in your internal database, you need to add a new entry incrementing from the last added vault account id
3. Lines 9-14: Gets the vault account and counts the number of assets. Returns based on our previous explanation (at most 10).

   If there is an error, handle using the generic error handler. If there is an error code `1004`, you'll receive a specific type of error. This type of error, in our scenario, will generate a new vault account by something upstream from where the error occurred.

***

# 500 status code

500 status code is an indication that there was an issue that happened on the server side. Due to this, it is not possible for us to provide a way to handle such errors in the same manner as we did for the 4xx errors.

We suggest the following:

1. Do not immediately attempt the request again
2. Double-check the parameters you're passing, it might be that one of the parameters you're passing is not formatted correctly, thus resulting in a failure in our backend
3. Check the [status page](https://status.fireblocks.com/) to check if there is an ongoing issue
4. Open a Support ticket / reach out to Support on Slack to see address the issue

***

# Common validations to perform

Generally, validations should be done based on your needs and as soon as you have sufficient details to validate them. This will divide into two potential scenarios (but not limited to those two):

1. You received the value and can immediately perform validation on that value
2. You received the value but some additional data is required before performing the validation

We provide some common validations that can and should be done which will lower your risk of getting errors in your response that is caused by your code.

* Asset validation - When getting an asset, always verify that the asset is indeed a supported one. [More information can be found in the supported assets API reference](ref:get_supported-assets).
* OTA validation - When using one-time address, which is received from the user themselves, ensure that the format of the address matches the format of the network.
  * For example, BTC SegWit will require an address starting with `bc1` and complying with Bech32 formatting. EVMs will be a 40-character checksummed hex string with a prefix of `0x`.
* Amount validation - In cases where you allow users to specify amounts, such as partial withdrawal uses, you'll always need to:
  1. Get the current balance available for the user, either via an API call or via an internal ledger (depending on your business logic).
  2. Verify that the amount is a positive decimal value in the range of (0, retrieved balance] (excluding 0).
* Vault account validation - Ensure the vault account is a non-negative integer.

  You might want to add restrictions (both in your Transaction Authorization Policy and in your code, to prevent access to vault accounts you don't want users to be able to access).


# Fireblocks Hardhat Plugin
Source: https://developers.fireblocks.com/reference/hardhat-plugin



# Overview

Hardhat is a development environment for Ethereum software that provides tools for editing, compiling, debugging, and deploying smart contracts and dApps.

The [Fireblocks Hardhat Plugin](https://github.com/fireblocks/hardhat-fireblocks) integrates Fireblocks' secure transaction features into your Hardhat workflow, enabling secure deployment and transaction signing.

# Using Hardhat

To use the Fireblocks Hardhat Plugin, you must have [Hardhat installed](https://hardhat.org/hardhat-runner/docs/getting-started).

You can follow our abridged Hardhat installation steps below or skip to the [Fireblocks Hardhat Plugin](ref:hardhat-plugin#fireblocks-plugin) section if you already have Hardhat installed.

## Install Hardhat

If you need to install Hardhat, you can use our abridged installation guide below. For a complete guide, refer to the official [Hardhat installation guide](https://hardhat.org/hardhat-runner/docs/getting-started).

### Abridged Hardhat installation guide

1. Install the Hardhat package:

```bash theme={"system"}
npm install --save-dev hardhat
```

2. Initialize a new Hardhat project:

```bash theme={"system"}
npx hardhat
```

This generates the following Hardhat menu display:

```text theme={"system"}
888    888                      888 888               888
888    888                      888 888               888
888    888                      888 888               888
8888888888  8888b.  888d888 .d88888 88888b.   8888b.  888888
888    888     "88b 888P"  d88" 888 888 "88b     "88b 888
888    888 .d888888 888    888  888 888  888 .d888888 888
888    888 888  888 888    Y88b 888 888  888 888  888 Y88b.
888    888 "Y888888 888     "Y88888 888  888 "Y888888  "Y888

👷 Welcome to Hardhat v2.10.1 👷‍

? What do you want to do? …
❯ Create a JavaScript project
  Create a TypeScript project
  Create an empty hardhat.config.js
```

3. Select **Create a JavaScript project** and press **Enter**.
4. Follow the proceeding setup prompts.

Complete these steps to generate a new JavaScript Hardhat project in your current directory.

## Fireblocks Plugin

The [Fireblocks Hardhat Plugin](https://github.com/fireblocks/hardhat-fireblocks) helps seamlessly integrate Fireblocks into your Hardhat development stack. You can use it to deploy contracts, sign messages, and send transactions securely through Fireblocks.

### Installing the Hardhat plugin

1. Install the plugin package:

```bash theme={"system"}
npm install @fireblocks/hardhat-fireblocks
```

2. Import the plugin into your `hardhat.config.js` file:

```javascript theme={"system"}
require("@fireblocks/hardhat-fireblocks");
const { ApiBaseUrl } = require("@fireblocks/fireblocks-web3-provider");
require('dotenv').config();
```

### Configuring the Hardhat plugin

This plugin extends the `HttpNetworkUserConfig` object with an optional `fireblocks` field.

1. For this example, copy the code sample below into your `hardhat.config.js` configuration file:

```javascript theme={"system"}
module.exports = {
  solidity: "0.8.17",
  networks: {
    sepolia: {
      url: "https://sepolia.drpc.org",
      fireblocks: {
        apiBaseUrl: ApiBaseUrl.Sandbox, // Only use in a Sandbox workspace
        privateKey: process.env.FIREBLOCKS_API_PRIVATE_KEY_PATH,
        apiKey: process.env.FIREBLOCKS_API_KEY,
        vaultAccountIds: process.env.FIREBLOCKS_VAULT_ACCOUNT_IDS,
      }
    },
  },
};
```

> **Working in Sandbox**
>
> If you are not using a Sandbox workspace, remove the `apiBaseUrl` line.

2. Delete the `Lock.sol` file that came with your generated Hardhat environment:

```bash theme={"system"}
rm contracts/Lock.sol
```

## Deploy a contract using Hardhat Ignition

Now that your Hardhat plugin has been configured to work with Fireblocks, you can begin deploying a smart contract to the Sepolia Ethereum Testnet.

### Create and compile the Solidity file

1. Create a Solidity file in your project folder:

```bash theme={"system"}
touch contracts/HelloWorld.sol
```

2. Copy the following code sample into your `HelloWorld.sol` file:

```solidity theme={"system"}
pragma solidity ^0.8.17;

contract HelloWorld {
    string public greet = "Hello World!";
}
```

3. Run the following command to compile the project:

```bash theme={"system"}
npx hardhat compile
```

### Update and deploy the script

1. Create a new file `ignition/modules/HelloWorld.js` and add the following module definition:

```javascript theme={"system"}
const { buildModule } = require("@nomicfoundation/hardhat-ignition/modules");

module.exports = buildModule("HelloWorld", (m) => {
	const helloWorld = m.contract("HelloWorld");

	return { helloWorld };
});
```

2. Deploy your contract to the Ethereum Sepolia Testnet using Hardhat Ignition:

```bash theme={"system"}
npx hardhat ignition deploy ignition/modules/HelloWorld.js --network sepolia
```

This should take a couple of minutes to run if everything was configured correctly.

Once the deploy script has finished running successfully, the following message will appear:

```bash theme={"system"}
Hardhat Ignition 🚀

Deploying [ HelloWorld ]

Batch #1
	Executed HelloWorld#HelloWorld

[ HelloWorld ] successfully deployed 🚀

Deployed Addresses

HelloWorld#HelloWorld - <contract_address>
```

### Post-deployment

Hardhat Ignition creates an `ignition/deployments/chain-11155111` folder for Sepolia that contains all the deployment details. This data enables Hardhat Ignition to recover from errors, resume interrupted deployments, and manage deployment states.

## Summary

You have now integrated the Fireblocks Hardhat Plugin into your Ethereum development workflow and deployed a smart contract to the Sepolia Testnet using Hardhat Ignition! This setup enables you to securely deploy contracts and manage transactions with Fireblocks’ infrastructure.


# Hedera Token Service SDK
Source: https://developers.fireblocks.com/reference/hedera-token-service-sdk



> **This Tool Utilizes Fireblocks RAW Signing**
>
> Raw Signing is an insecure signing method and is not generally recommended.
> Bad actors can trick someone into signing a valid transaction message and use it to steal funds.
>
> For this reason, Raw Signing is a premium feature that requires an additional purchase and is not available in production workspaces by default. If you're interested in this feature and want to see if your use case is eligible for it, please contact your Customer Success Manager.
>
> **Note:** Fireblocks Sandbox workspaces have Raw Signing enabled by default to allow for testing purposes.

This library provides an implementation of the Hedera Client designed for signing operations with the Fireblocks TypeScript SDK. It adheres to [HIP-338](https://hips.hedera.com/hip/hip-338).

Internally, the implementation acts as a wrapper utilizing Raw Signing. It manages all necessary raw signing calls, abstracting the complexities to ensure easy and seamless integration with both Fireblocks and the Hedera SDK.

Additionally, this library supports any token operations on the Hedera blockchain that are not yet natively available through the Fireblocks console and APIs. For code examples and further guidance on how to use the library, please visit the [GitHub repository](https://github.com/fireblocks/hbar-fireblocks-sdk).


# How to Use Fireblocks TypeScript SDK with Travel Rule Messages
Source: https://developers.fireblocks.com/reference/how-to-use-fireblocks-typescript-sdk-with-travel-rule-messages



The legacy Fireblocks JS SDK already includes PII encryption, whereas the new Fireblocks TS SDK does not. Therefore, you need to implement a manual install to add the PII encryption to use Fireblocks TypeScript SDK with Travel Rule Messages. For details, please follow the steps below:

***

## Step 1: Install the SDK

* Run `yarn add @fireblocks/ts-sdk`or `npm install @fireblocks/ts-sdk`

## Step 2: Implement Notabene PII Encryption

Since the new TypeScript SDK does not include PII encryption, users must manually encrypt PII data before sending the request. The example below is using @notabene/pii-sdk:

```typescript theme={"system"}
import PIIsdk, { PIIEncryptionMethod } from "@notabene/pii-sdk";

const piiEncryption = new PIIsdk({
  piiURL: "[https://pii.notabene.dev"](https://pii.notabene.dev"),
  audience: "[https://pii.notabene.dev"](https://pii.notabene.dev"),
  clientId: process.env.NOTABENE\_CLIENT\_ID,
  clientSecret: process.env.NOTABENE\_CLIENT\_SECRET,
  authURL: "[https://auth.notabene.id/oauth/token"](https://auth.notabene.id/oauth/token"),
});

// Encrypt the PII data
async encode(
    travelRuleMessage: TravelRuleCreateTransactionRequest,
    travelRuleEncryptionOptions?: TravelRuleEncryptionOptions,
  ): Promise<TravelRule> {
    // If there's no "pii" field, default to originator & beneficiary
    const pii = travelRuleMessage.pii || {
      originator: travelRuleMessage.originator,
      beneficiary: travelRuleMessage.beneficiary,
    };
const jsonDidKey = this.configService.config.notabene.jsonDIDKey;
const counterpartyDIDKey =
  travelRuleEncryptionOptions?.beneficiaryPIIDidKey;

let piiIvms = await this.toolset.generatePIIField({
    pii,
    originatorVASPdid: travelRuleMessage.originatorVASPdid,
    beneficiaryVASPdid: travelRuleMessage.beneficiaryVASPdid,
    counterpartyDIDKey,
    keypair: JSON.parse(jsonDidKey),
    senderDIDKey: JSON.parse(jsonDidKey).did,
    encryptionMethod: travelRuleEncryptionOptions?.sendToProvider
      ? PIIEncryptionMethod.HYBRID
      : PIIEncryptionMethod.END_2_END,
  });
travelRuleMessage.beneficiary = piiIvms.beneficiary;
travelRuleMessage.originator = piiIvms.originator;
return travelRuleMessage;
}
```

## Step 3: Send a Fireblocks Transaction with the Travel Rule Message

Once PII data is encrypted, users can pass it into the Fireblocks TypeScript SDK when creating a blockchain transaction.

```javascript theme={"system"}
import { FireblocksSDK, PeerType, TransactionArguments, TravelRuleCreateTransactionRequest } from "@fireblocks/ts-sdk";

// Initialize Fireblocks SDK
const fireblocks = new FireblocksSDK(
  process.env.FIREBLOCKS_API_SECRET_KEY,
  process.env.FIREBLOCKS_API_KEY,
  process.env.FIREBLOCKS_API_URL
);

// Construct the transaction request
const transaction: TransactionArguments = {
  assetId: "ETH_TEST",
  source: {
    type: PeerType.VAULT_ACCOUNT,
    id: "1",
  },
  destination: {
    type: PeerType.ONE_TIME_ADDRESS,
    oneTimeAddress: {
      address: "0x123456789abcdef123456789abcdef123456789a",
    },
  },
  operation: "TRANSFER",
  amount: "0.5",
  note: "Travel Rule Test TX",
  travelRuleMessage: TravelRuleCreateTransactionRequest, // Pass the encrypted Travel Rule message here
};
// Send the transaction request
const result = await fireblocks.createTransaction(transaction);
console.log("Transaction Created:", result);
```


# Add a new Co-signer to the workspace
Source: https://developers.fireblocks.com/reference/install-api-cosigner-add-new-cosigner-p2



To connect a new Co-signer to your workspace, pair it with an API user from the workspace. It is recommended to create a new API user for that purpose. The pairing process for the first API user requires admin-level access to the Fireblocks Console and the owner's availability to approve the necessary workspace configuration operations.

Pairing the Co-signer is performed using a JWT-encoded Pairing Token obtained from the Console for a specific API user. This pairing token is used during Co-signer installation to pair the initial API user, enabling communication with Fireblocks' SaaS. The Co-signer is identified exclusively by the workspace and the API user used to establish the connection.

***

## Prerequisites

During installation, you will use the following items from the Fireblocks Console. Copy them to your clipboard for later use.

* The API user's pairing token
* The download link of the installation script that matches your Co-signer type: Intel SGX, AWS Nitro, or Google Cloud Confidential Space.

***

## Step 1: Add a new API user

Add a new API user to the workspace using the [Fireblocks APIs](https://docs.fireblocks.com/api/swagger-ui/#/Api%20User/createApiUser) or the **API users** tab in the Console's Developer Center. This API user will enable the Co-signer to connect to the workspace.

* Enter the name of the new API user (you can enter up to 30 characters)
* Select the role you want to assign to the API user
* Attach [a CSR file](/docs/generate-a-csr-for-an-api-user)

> **Important note**
>
> While the Co-signer does not use the CSR file to connect to the workspace, you must still provide it. This is necessary because the API user can be used to make API calls.

***

## Step 2: Add a new Co-signer to the workspace

Add a new Co-signer to the workspace using the [Fireblocks Co-signer APIs](https://docs.fireblocks.com/api/swagger-ui/#/Cosigners%20\(Beta\)) or the **Co-signers** tab in the Console's Developer Center.

To add a new Co-signer to the workspace, click **Add co-signer** and follow the instructions:

* Enter the name of the new Co-signer
* Select **Install a new co-signer on the local machine** and press **Continue**
* Choose an available API user from the list (only API users not already paired with Co-signers will be displayed)
* Click **Add** to create a new Co-signer entry

The new Co-signer will now appear in the list of Co-signers in the Co-signers tab. It is not yet connected to the workspace, so it appears as offline. The connection will be established once you complete the installation process.

***

## Step 3: Copy the API user's pairing token & the installation script's download link

Click **Pair API user** in the new Co-signer's entry to open a dialog, and follow the instructions:

* Copy the API user's pairing token to your clipboard. In mainnet workspaces, the pairing token is valid for one hour.
* Copy the download link for the AWS Nitro Co-signer installation package (found under "Manual") to your clipboard. This link is valid for seven days.

> **Need help?**
>
> If you have any issues with finding or retrieving the download link of the Co-signer's installation script in the Console, [contact Fireblocks Support](https://support.fireblocks.io/hc/en-us/requests/new).


# Install SGX Alibaba Cloud API Co-signer
Source: https://developers.fireblocks.com/reference/install-api-cosigner-alibaba



## Overview

To install an SGX Co-signer in Alibaba Cloud and connect it to your workspace, follow these steps:

1. **Setup and configure your Alibaba Cloud environment**

   Prepare your Alibaba Cloud environment by creating and configuring the required resources. Ensure it meets the necessary specifications and security settings.

2. **Add a Co-signer to the workspace using an API user**

   Using the Fireblocks Console or APIs, create an API user and use it to add a Co-signer to the workspace.

3. **Install and connect the Co-signer to the workspace**

   Download the installation script to the SGX-capable virtual machine and run the script to install the Co-signer. Once installation is complete, the workspace owner approves the new MPC key shares for the API user through the Fireblocks mobile app.

You can now view the Co-signer and its paired API user in your Fireblocks Console. Additionally, you can retrieve information about them using the Co-signer APIs.

***

## Step 1: Setup and configure your Alibaba Cloud environment

### 1.1. Allowlist domains

To ensure the Co-signer can be installed and operated successfully, add the following domains to your allowlist:

| Domain                                  | Owner                      |
| --------------------------------------- | -------------------------- |
| `mobile-api.fireblocks.io`              | Fireblocks                 |
| `signurl.fireblocks.io`                 | Fireblocks                 |
| `s3signurl.fireblocks.io`               | Fireblocks                 |
| `fb-certs.s3.amazonaws.com`             | AWS                        |
| `fb-customers.s3.amazonaws.com/uploads` | AWS                        |
| `fb-cosigner-images.s3.amazonaws.com`   | AWS                        |
| `fb-customers.s3.amazonaws.com`         | AWS                        |
| `download.docker.com`                   | Docker                     |
| `registry.gitlab.com`                   | GitLab                     |
| `cdn.registry.gitlab-static.net`        | GitLab                     |
| `gitlab.com`                            | GitLab                     |
| `github.com`                            | GitHub                     |
| `download.01.org`                       | Intel SGX Driver           |
| `bootstrap.pypa.io`                     | Python Software Foundation |
| `files.pythonhosted.org`                | Python Software Foundation |
| `pypi.org`                              | Python Software Foundation |
| `pypi.python.org`                       | Python Software Foundation |

Fireblocks-owned domains differ based on the specific Fireblocks SaaS environment you are connected to. If you are connected to the European or Swiss SaaS, update your allowlist according to the domains listed in the table below:

| Fireblocks SaaS | Domains to Allow                                                                           |
| --------------- | ------------------------------------------------------------------------------------------ |
| Global          | `mobile-api.fireblocks.io`  `signurl.fireblocks.io`  `s3signurl.fireblocks.io`             |
| Europe          | `eu2-mobile-api.fireblocks.io`  `eu2-signurl.fireblocks.io`  `eu2-s3signurl.fireblocks.io` |
| Swiss           | `eu-mobile-api.fireblocks.io`  `eu-signurl.fireblocks.io`  `eu-s3signurl.fireblocks.io`    |

Additionally, ensure port access is configured for the following services:

| Port | Service URL                                      |
| ---- | ------------------------------------------------ |
| 443  | `https://mobile-api.fireblocks.io`               |
| 443  | `https://s3signurl.fireblocks.io`                |
| 443  | `https://fb-certs.s3.amazonaws.com`              |
| 443  | `https://fb-customers.s3.amazonaws.com/uploads/` |
| 443  | `https://bootstrap.pypa.io/get-pip.py`           |
| 443  | `https://download.docker.com/linux`              |
| 443  | `https://download.01.org/intel-sgx/`             |
| 5000 | `https://registry.gitlab.com/customer-cosigner`  |

### 1.2. Create an SGX virtual machine

> **Important:**
>
> See this [Alibaba Security Enhanced Instance Family Overview](https://www.alibabacloud.com/help/en/elastic-compute-service/latest/security-enhanced-instance-family-overview) document for details on which instance type to select.

**The minimum hardware requirements for the VM are:**

* RAM: 16GB
* Storage: 256GB
* OS:
  * Ubuntu 20.04
  * Latest Linux kernel version
  * Latest Intel microcode (BIOS update)

Complete the following steps to create an SGX-capable VM in Alibaba Cloud:

1. On the **Workbench** page, click **Elastic Compute Service**.

<img alt="" />

2. On the Overview tab, click **Create Instance**.

<img alt="" />

3. Select the following options from Custom Launch:
   1. Region: Select your region.
   2. Instance Type: Enter "g7t" in "Search by instance type name", then select `ecs.g7t.2xlarge` (recommended).

<img alt="" />

4. Complete the Networking, System Configurations, and Grouping pages per your organization's policies for each.
5. Click **Create Instance**.

### 1.3. Verify SGX is enabled on your VM

After creating your virtual machine, confirm that SGX is enabled. The SGX Co-signer requires a server with SGX enabled and the latest patches applied. This verification ensures smooth operation and avoids potential issues.

To verify that SGX is enabled on the VM, run the following commands with root privileges::

```bash theme={"system"}
 apt update
 apt upgrade
 apt install cpuid
 cpuid -1 | grep -i sgx
```

Verify the following:

1. `SGX`: Software Guard Extensions supported is **true**
2. `SGX_LC`: SGX launch config supported is **true**

<img alt="" />

### 1.4. Additional security recommendations

It is highly recommended to control user and network access to Co-signer's machine. See [API Co-signer security checklist and recommended defense and monitoring systems](/docs/co-signer-security-checklist-defense-monitoring) for further information.

***

## Step 2: Add a Co-signer to the workspace using an API user

Follow the instructions to [add a new Co-signer to the workspace](/reference/install-api-cosigner-add-new-cosigner-p2). Ensure you copy to your clipboard the following items, which you will use during the installation process:

* The API user's pairing token
* The download link of the Co-signer's installation script

***

## Step 3: Install and connect the Co-signer to the workspace

> **Note:** You must have root privileges on the Co-signer machine to install the Co-signer. Ensure you are logged in as a root user or use `sudo` to execute the commands.

### 3.1. Download the installation script

Using the download link of the SGX Co-signer installation script you copied from the Console, run the `curl` command to download the package directly to your machine.

Paste the appropriate URL into the following command:

```bash theme={"system"}
curl -o cosigner "URL"
```

### 3.2. Run the installation script

After downloading the installation script, navigate to the directory containing the script and modify the script's permissions to make it executable:

```bash theme={"system"}
chmod +x cosigner
```

To install the Co-signer, run:

```bash theme={"system"}
./cosigner setup
```

You will be prompted to enter the **Pairing token** for the API user, which you retrieve from the Fireblocks Console. This token pairs the API user with the Co-signer.

At this stage, you will have the option to configure the Callback Handler parameters for the API user connecting the Co-signer to the workspace. This feature is optional. You can [configure it later through the Console, APIs, or locally](/reference/api-cosigner-operate) from the Co-signer's host machine.

For detailed instructions on setting up your Callback Handler's interface to the Co-signer and implement its logic and code, refer to the [Setup API Co-signer Callback Handler](/reference/api-cosigner-setup-callback-handler) section.

The setup process validates the machine's hardware and installs the necessary drivers to support the appropriate SGX version and the SGX Co-signer's executable image. It includes an attestation flow to ensure that the SGX Co-signer's executable runs securely inside an Intel SGX enclave. Additionally, the script installs other required components.

Once the installation is complete, the Co-signer will automatically start running. At the end of the process, the Co-Signer generates a JSON configuration file, which can be used for future configuration updates.

### 3.3: Approve MPC key shares for the API user

If the API user used to pair with the Co-Signer and connect it to your workspace has an Admin or User role, the workspace owner will receive a notification. This notification will prompt them to approve a new MPC key share request for that API user using the Fireblocks mobile app.

You can now see the Co-signer you installed in the Co-signers tab within the Console's Developer Center. Observe it is online and that the API user is paired to it.

***

> **To check the Co-signer's status and observe the logs, see the SGX Co-signer Maintenance article.**


# Install AWS Nitro API Co-signer
Source: https://developers.fireblocks.com/reference/install-api-cosigner-aws



## Overview

To install a Nitro Co-signer in AWS and connect it to your workspace, follow these steps:

1. **Setup and configure your AWS environment:** Prepare your AWS environment by creating and configuring the required resources. Ensure it meets the necessary specifications and security settings.
2. **Add a Co-signer to the workspace using an API user:** Using the Fireblocks Console or APIs, create an API user and use it to add a Co-signer to the workspace.
3. **Install and connect the Co-signer to the workspace:** Download the installation script to the Nitro-capable EC2 machine and run the script to install the Co-signer. Once installation is complete, the workspace owner approves the new MPC key shares for the API user through the Fireblocks mobile app.

You can now view the Co-signer and its paired API user in your Fireblocks Console. Additionally, you can retrieve information about them using the Co-signer APIs.

***

## Step 1: Set up and configure your AWS environment

Proper configuration of your AWS environment is straightforward but must be performed step by step in the specified order. Any misconfiguration could compromise the Co-signer's functionality or security.

### Required AWS account permissions

You must have the necessary AWS account permissions to enable network access to the required domains and to create and configure the following resources:

* IAM Role
* Customer Managed Key (CMK)
* S3 bucket
* Nitro-capable EC2 machine

### Step 1.1: Allowlist domains

To ensure the Co-signer can be installed and operated successfully, add the following domains to your allowlist:

| Domain                       | Owner                                            |
| ---------------------------- | ------------------------------------------------ |
| `mobile-api.fireblocks.io`   | Fireblocks                                       |
| `signurl.fireblocks.io`      | Fireblocks                                       |
| `s3signurl.fireblocks.io`    | Fireblocks                                       |
| `s3.{region}.amazonaws.com`  | AWS (Replace `{region}` with the applicable one) |
| `kms.{region}.amazonaws.com` | AWS (Replace `{region}` with the applicable one) |
| `bootstrap.pypa.io`          | Python Software Foundation                       |
| `files.pythonhosted.org`     | Python Software Foundation                       |
| `pypi.org`                   | Python Software Foundation                       |
| `pypi.python.org`            | Python Software Foundation                       |
| `fb-certs.s3.amazonaws.com`  | AWS                                              |

Fireblocks-owned domains differ based on the specific Fireblocks SaaS environment you are connected to. If you are connected to the European or Swiss SaaS, update your allowlist according to the domains listed in the table below:

| Fireblocks SaaS | Domains to Allow                                                                           |
| --------------- | ------------------------------------------------------------------------------------------ |
| Global          | `mobile-api.fireblocks.io`  `signurl.fireblocks.io`  `s3signurl.fireblocks.io`             |
| Europe          | `eu2-mobile-api.fireblocks.io`  `eu2-signurl.fireblocks.io`  `eu2-s3signurl.fireblocks.io` |
| Swiss           | `eu-mobile-api.fireblocks.io`  `eu-signurl.fireblocks.io`  `eu-s3signurl.fireblocks.io`    |

> **Additional notes**
>
> * For a better understanding of the Co-Signer's communication with the above URLs, refer to the [AWS Nitro API Co-signer Architecture](/docs/aws-nitro-api-co-signer) article.
> * If you cannot support DNS IP whitelisting with an advanced firewall or within the cloud itself, you must allow egress traffic to any destination on port 443.

### Step 1.2: Set up and configure an IAM role

Identity and Access Management (IAM) roles are used to delegate access to your AWS resources. Create an IAM security role that ties everything together by granting only the necessary permissions to the specific resources.

1. From the Identity and Access Management (IAM) page, select **Roles** and **Create role**. On the Select trusted entity page, select:
   1. **Trusted entity type:** AWS service
   2. **Service or use case:** EC2
2. Select **Next**. On the Add permissions page, don’t make any selections.
3. Select **Next**. Enter the role’s name and select **Create role** without changing the trust policy.
4. Select the newly created role and copy the IAM ARN for the next steps. The IAM ARN has the following structure:

   `arn:aws:iam::{ACCOUNT-ID}:role/{ROLE-NAME}`

When you finish, the Permissions policies section will be empty (as shown below). After setting up the S3 bucket and the Customer Managed Key (CMK) in the Key Management Service (KMS), you will return to Permissions policies to add the required policies for those resources.

<img alt="" />

### Step 1.3: Set up and configure an S3 bucket

Create the S3 bucket that serves as the Co-signer's persistent storage.

1. From the Amazon S3 page, select **Create bucket**. Enter its name, leave everything else as default, and create the bucket.
2. Select the newly created bucket and on the bucket’s details page, select **Permissions**.
3. In the Bucket policy section, select **Edit** and copy-paste the S3 policy from the text box below.
4. Select **Save changes** to complete the operation.
5. Select the newly created bucket and copy the Bucket ARN for the next steps. The Bucket ARN has the following structure:

   `arn:aws:s3:::\{BUCKET-NAME}`

Make sure you replace the`{BUCKET-NAME}`, `{ACCOUNT-ID}` and `{ROLE-NAME}` with the correct values.

```json theme={"system"}
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Deny",
            "Principal": "*",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:DeleteObject",
                "s3:ListBucket",
                "s3:ListBucketMultipartUploads",
                "s3:AbortMultipartUpload",
                "s3:GetObjectAcl",
                "s3:PutObjectAcl",
                "s3:RestoreObject"
            ],
            "Resource": [
                "arn:aws:s3:::{BUCKET-NAME}",
                "arn:aws:s3:::{BUCKET-NAME}/*"
            ],
            "Condition": {
                "ArnNotEquals": {
                    "aws:PrincipalArn": "arn:aws:iam::{ACCOUNT-ID}:role/{ROLE-NAME}"
                }
            }
        }
    ]
}
```

### Step 1.4: Set up and configure a KMS Customer-Managed Key (CMK)

Create a Customer-Managed Key (CMK) in KMS to safeguard the Co-signer’s MPC key shares.

#### Create the key

1. Open the Key Management Service (KMS) page and select **Create key**.

2. On the Configure key page, select:
   1. **Key type:** Symmetric
   2. **Key usage:** Encrypt and decrypt

3. Expand the **Advanced options** section and select:
   1. **Key material origin:** KMS
   2. **Regionality:** Single-Region key.

      **Note:** Select the Multi-Region key only if the EC2 instance is in a different region.

4. Select **Next**.

#### Add labels

1. On the Add labels page, set a display name for the key in the **Alias** field (e.g., `fireblocks-nitro-cosigner`).
2. Optionally, fill in the **Description** and **Tags** fields.
3. Select **Next**.

#### Configure permissions

1. On the Define key administrative permissions page, leave the **Key administrators** section blank and leave the **Key deletion** option checked.
2. Select **Next**.
3. On the Define key usage permissions page, leave the **Key users** section blank.
4. Select **Next**.

#### Finalize the key

1. On the Review page, scroll down to the Key policy section.
2. Paste the KMS policy in the Key policy section.
3. Select **Finish**.

#### Get the key ARN

1. Select the newly created key.
2. Copy the KMS ARN for the next steps.

The KMS ARN has the following structure: `arn:aws:kms:{KEY-REGION}:{ACCOUNT-ID}:key/{KEY-ID}`

Ensure you replace `{ACCOUNT-ID}` and `{KEY-ID}` with the correct values.

#### Understanding the policy warning

When you paste the KMS policy, you might see the following warning:

> **Unsupported Action For Condition Key**
>
> The following actions: `kms:GetKeyPolicy` are not supported by the condition key `kms:RecipientAttestation:PCR8`. The condition will not be evaluated for these actions. We recommend that you move these actions to a different statement without this condition key.

**Why you can safely ignore this warning:**

* The `kms:RecipientAttestation:PCR8` condition is only evaluated on KMS calls that include an attestation report from the enclave.
* AWS ignores the condition on actions that never carry a report in the request (such as `GetKeyPolicy` and `Encrypt`) and emits this advisory.
* **Security impact:** None. All sensitive operations (`Decrypt`, `DeriveSharedSecret`, `GenerateDataKey`, `GenerateRandom`) remain protected by the PCR8 attestation check.
* **Functionality impact:** Unaffected. This behavior is by design, and the key can be used by the Fireblocks Nitro Co-signer immediately.

The value for PCR8 varies based on the Fireblocks SaaS environment to which you are connected. Copy the correct value into the CMK policy:

| Fireblocks SaaS | `{PCR8-VALUE}`                                                                                     |
| --------------- | -------------------------------------------------------------------------------------------------- |
| Global          | `da1d9eca20ce98ab4fdbc51f8e5a2307fd4c61829b7d8bff40976cd6676862c8f3476ff4bdd0f65ecf4a48d6eb3099a8` |
| Europe          | `fffc94d68a150b49dc39b23954c793cd1a4f7972f528a1ee258dc130b6cd9454e29ae72ef66bd9697a55e774e17a2d49` |
| Swiss           | `69b1fbe9fb4ea49e084fe6f9f9623d871bd22ceb5efad47b1a8d3708e6674868cad8bf088ced3976c2194360c7d58219` |

```json theme={"system"}
{
    "Version": "2012-10-17",
    "Id": "key-consolepolicy-4",
    "Statement": [
        {
            "Sid": "Enable enclave data processing for specific role",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::{ACCOUNT-ID}:role/{ROLE-NAME}"
            },
            "Action": [
                "kms:Decrypt",
                "kms:Encrypt",
                "kms:GenerateDataKey",
                "kms:GenerateDataKeyPair",
                "kms:GenerateDataKeyWithoutPlaintext",
                "kms:GenerateDataKeyPairWithoutPlaintext",
                "kms:GenerateRandom",
                "kms:GetKeyPolicy"
            ],
            "Resource": "*",
            "Condition": {
                "StringEqualsIgnoreCase": {
                    "kms:RecipientAttestation:PCR8": "{PCR8-VALUE}"
                }
            }
        },
        {
            "Sid": "Allow GetKeyPolicy to co-signer",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::{ACCOUNT-ID}:role/{ROLE-NAME}"
            },
            "Action": "kms:GetKeyPolicy",
            "Resource": "*"
        },
        {
            "Sid": "Allow policy management to root user",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::{ACCOUNT-ID}:root"
            },
            "Action": [
                "kms:DescribeKey",
                "kms:GetKeyPolicy",
                "kms:PutKeyPolicy",
                "kms:CreateAlias"
            ],
            "Resource": "*"
        }
    ]
}
```

### Step 1.5: Edit the IAM role's policy

Return to the IAM service and select the IAM role you created.

1. In the Permissions policies section, select **Attach policies**, select the `AmazonSSMManagedInstanceCore` policy, and then select **Add permissions**.

<img alt="" />

2. In the Permissions policies section, select **Create inline policy** and choose **JSON** in the Policy editor section. Copy-paste the IAM policy below in there. Finally, create the policy and assign it a name.

Make sure you replace the `{BUCKET-NAME}`, `{KEY-REGION}`, `{ACCOUNT-ID}` and `{KEY-ID}` with the correct values.

```json theme={"system"}
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "ListBuckets",
            "Effect": "Allow",
            "Action": "s3:ListAllMyBuckets",
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetBucketLocation"
            ],
            "Resource": "arn:aws:s3:::{BUCKET-NAME}"
        },
        {
            "Sid": "WritePermissionsOnBucket",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:PutObjectAcl",
                "s3:GetObject",
                "s3:GetObjectAcl",
                "s3:DeleteObject"
            ],
            "Resource": "arn:aws:s3:::{BUCKET-NAME}/*"
        },
        {
            "Sid": "AccessToTheKey",
            "Effect": "Allow",
            "Action": [
                "kms:Encrypt",
                "kms:Decrypt",
                "kms:GenerateDataKey",
                "kms:GenerateDataKeyPair",
                "kms:GenerateDataKeyWithoutPlaintext",
                "kms:GenerateDataKeyPairWithoutPlaintext",
                "kms:GenerateRandom",
                "kms:GetKeyPolicy"
            ],
            "Resource": [
                "arn:aws:kms:{KEY-REGION}:{ACCOUNT-ID}:key/{KEY-ID}"
            ]
        }
    ]
}
```

### Step 1.6: Set up and configure an EC2 instance

> **Use only the c5.xlarge or c5a.xlarge instance types!**
>
> AWS Nitro secure enclaves must have a minimum of two dedicated vCPUs and 4GB memory per enclave, and Nitro secure enclaves can utilize up to 50% of the host EC2 instance's resources. Therefore, the minimum requirement is to have an instance with four vCPUs and 8GB memory (`c5.xlarge`).

1. Create a Nitro-capable EC2 instance by selecting **Launch instances** from the EC2 Instances page. Enter its name and choose the Amazon Machine Image (AMI) **Amazon Linux 2023 AMI with 64-bit (x86) architecture**.

<img alt="" />

2. In the Instance type section, select `c5.xlarge` (4vCPUs, 8GB RAM) or `c5a.xlarge` if the former is not available in your region.
3. In the Network settings section, set where to allow SSH traffic from. We recommend restricting access as much as possible.
4. In the Advanced details section:
   1. **IAM instance profile:** Select the IAM Role you created in the previous steps.
   2. **Nitro Enclave:** Select **Enable**. This field will be grayed out if you selected an instance type that is incompatible with Nitro.
   3. **Metadata version:** Select **V2 only (token required)**.
   4. **Metadata response hop limit:** Set to a minimum of 2 (two).

When you’re done, launch the instance.

### Step 1.7: Additional security recommendations

* It is highly recommended to control user and network access to your AWS environment and EC2 instance by properly configuring your VPC and security groups. Learn more about [controlling network traffic](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/infrastructure-security.html#control-network-traffic) in the AWS documentation.
* See [API Co-signer security checklist and recommended defense and monitoring systems](/docs/co-signer-security-checklist-defense-monitoring) for further information.

***

## Step 2: Add a Co-signer to the workspace using an API user

[Use this guide](/reference/install-api-cosigner-add-new-cosigner-p2) to add a new Co-signer to the workspace. Be sure to copy-paste (or otherwise record) the following items to your notes since they are required during the installation process:

* The API user's pairing token
* The download link of the Co-signer's installation script

***

## Step 3: Install and connect the Co-signer to the workspace

> **You must have root privileges on the EC2 instance to install the Co-signer**
>
> Ensure you are logged in as a root user or use `sudo` to execute the installation commands.

### Step 3.1: Connect to your EC2 Instance

Connect to your EC2 instance with your preferred method.

### Step 3.2: Download and unpack the installation package

Using the download link of the AWS Nitro Co-signer installation package you copied from the Console, run the `wget` command to download the package directly to your machine.

Paste the appropriate URL into the following command:

```bash theme={"system"}
wget -O nitro-cosigner.tar.gz "URL"
```

Unpack the installation package by running the following command:

```bash theme={"system"}
tar -xzvf nitro-cosigner.tar.gz
```

### Step 3.3: Run the installation script

The installation package contains an Enclave Image File (EIF) and installation scripts. To install the Co-signer, navigate to the directory where the installation package was unpacked and run:

```bash theme={"system"}
./install.sh
```

You will be prompted to enter the following parameters:

* **Pairing token**: Enter the API user’s pairing token that you copied from the Fireblocks Console. This token pairs the API user with the Co-signer, establishing the connection between the Co-signer and the workspace.
* **S3 bucket name**: Enter the name of the S3 bucket that you created before. You should only add the bucket name and not the full ARN of the bucket. For example: If your bucket ARN is `arn:aws:s3:::{BUCKET-NAME}`, you need to enter only `{BUCKET-NAME}`.
* **CMK ARN:** Enter the Amazon Resource Name (ARN) of the CMK that you created before.

At this stage, you will have the option to configure the Callback Handler parameters for the API user connecting the Co-signer to the workspace. This feature is optional. You can [configure it later through the Console, APIs, or locally](/reference/api-cosigner-operate) from the Co-signer's host machine.

For detailed instructions on setting up your Callback Handler's interface to the Co-signer and implementing its logic and code, refer to the [Setup API Co-signer Callback Handler](/reference/api-cosigner-setup-callback-handler) section.

Once the installation is complete, the Co-signer will automatically start running.

> **The Nitro cosigner installation script installs the below components as services**
>
> * cosigner
> * cosigner-networking
> * cosigner-logging
> * cosigner-env-export
>
> The cosigner service is started up during the execution of the installation script, and is also enabled to start on boot, which in turn starts up the three remaining services.

### Step 3.4: Approve MPC key shares for the API user

If the API user paired with the Co-signer has an Admin or Signer role, the workspace Owner will receive a notification. This notification will prompt them to approve a new MPC key share request for that API user using the Fireblocks mobile app. The Owner must approve this request within 120 hours of receiving it.

You can now see the Co-signer you installed in the Co-signers tab within the Console's Developer Center. Observe that it is online and that the API user is paired to it.

> **Looking for the Co-signer's status and logs?**
>
> Refer to the [AWS Nitro Co-signer Maintenance](/reference/api-cosigner-maintenance-aws-nitro) guide for more information.

***


# Install SGX Azure API Co-signer
Source: https://developers.fireblocks.com/reference/install-api-cosigner-azure



## Overview

To install an SGX Co-signer in Microsoft Azure and connect it to your workspace, follow these steps:

1. **Setup and configure your Azure environment**

   Prepare your Azure environment by creating and configuring the required resources. Ensure it meets the necessary specifications and security settings.

2. **Add a Co-signer to the workspace using an API user**

   Using the Fireblocks Console or APIs, create an API user and use it to add a Co-signer to the workspace.

3. **Install and connect the Co-signer to the workspace**

   Download the installation script to the SGX-capable virtual machine and run the script to install the Co-signer. Once installation is complete, the workspace owner approves the new MPC key shares for the API user through the Fireblocks mobile app.

You can now view the Co-signer and its paired API user in your Fireblocks Console. Additionally, you can retrieve information about them using the Co-signer APIs.

***

## Step 1: Setup and configure your Azure environment

### 1.1. Allowlist domains

To ensure the Co-signer can be installed and operated successfully, add the following domains to your allowlist:

| Domain                                            | Owner                      |
| ------------------------------------------------- | -------------------------- |
| `mobile-api.fireblocks.io`                        | Fireblocks                 |
| `signurl.fireblocks.io`                           | Fireblocks                 |
| `s3signurl.fireblocks.io`                         | Fireblocks                 |
| `fb-certs.s3.amazonaws.com`                       | AWS                        |
| `fb-cosigner-images.s3.amazonaws.com`             | AWS                        |
| `fb-customers.s3.amazonaws.com`                   | AWS                        |
| `fb-customers.s3.amazonaws.com/uploads`           | AWS                        |
| `fireblocks-eu-prod-fr-cosigner.s3.amazonaws.com` | AWS                        |
| `download.docker.com`                             | Docker                     |
| `github.com`                                      | GitHub                     |
| `cdn.registry.gitlab-static.net`                  | GitLab                     |
| `gitlab.com`                                      | GitLab                     |
| `registry.gitlab.com`                             | GitLab                     |
| `download.01.org`                                 | Intel SGX Driver           |
| `bootstrap.pypa.io`                               | Python Software Foundation |
| `files.pythonhosted.org`                          | Python Software Foundation |
| `pypi.org`                                        | Python Software Foundation |
| `pypi.python.org`                                 | Python Software Foundation |

Fireblocks-owned domains differ based on the specific Fireblocks SaaS environment you are connected to. If you are connected to the European or Swiss SaaS, update your allowlist according to the domains listed in the table below:

| Fireblocks SaaS | Domains to Allow                                                                           |
| --------------- | ------------------------------------------------------------------------------------------ |
| Global          | `mobile-api.fireblocks.io`  `signurl.fireblocks.io`  `s3signurl.fireblocks.io`             |
| Europe          | `eu2-mobile-api.fireblocks.io`  `eu2-signurl.fireblocks.io`  `eu2-s3signurl.fireblocks.io` |
| Swiss           | `eu-mobile-api.fireblocks.io`  `eu-signurl.fireblocks.io`  `eu-s3signurl.fireblocks.io`    |

Additionally, ensure port access is configured for the following services:

| Port | Service URL                                               |
| ---- | --------------------------------------------------------- |
| 443  | `https://mobile-api.fireblocks.io`                        |
| 443  | `https://s3signurl.fireblocks.io`                         |
| 443  | `https://fb-certs.s3.amazonaws.com`                       |
| 443  | `https://fb-customers.s3.amazonaws.com/uploads/`          |
| 443  | `https://bootstrap.pypa.io/get-pip.py`                    |
| 443  | `https://download.docker.com/linux`                       |
| 443  | `https://download.01.org/intel-sgx/`                      |
| 443  | `https://fireblocks-eu-prod-fr-cosigner.s3.amazonaws.com` |
| 5000 | `https://registry.gitlab.com/customer-cosigner`           |

### 1.2. Create an Intel SGX virtual machine

Follow this [Microsoft installation guide](https://learn.microsoft.com/en-us/azure/confidential-computing/quick-create-portal) and create an Intel SGX virtual machine through the Azure portal.

> **Note**: Only the *Configure an Intel SGX virtual machine* section is required. The necessary settings are listed below. You do not need to complete the Connect to the Linux VM or Next Steps sections

**The minimum requirements for the VM are:**

* RAM: 16GB
* Storage: 256GB
* OS:
  * Ubuntu 22.04 LTS or 24.04 LTS (Canonical)
  * Latest Linux kernel version
  * Latest Intel microcode (BIOS update)
  * Install packages apt-update over port 80: [http://azure.archive.ubuntu.com/ubuntu](http://azure.archive.ubuntu.com/ubuntu)

See the official [Microsoft documentation to find which products are available per region](https://azure.microsoft.com/en-us/explore/global-infrastructure/products-by-region/?products=virtual-machines\&regions=all).

Complete the following steps to create an SGX-capable VM in Azure:

1. Select Ubuntu 22.04 LTS or Ubuntu 24.04 LTS (Canonical) as the image, with the latest Intel microcode (BIOS update). The microcode is automatically updated on Azure.
2. Select your region.
3. Under the **Advanced** tab, select **Gen 2**.
4. Select Size. The recommended size is `Standard_DC4s_v3`.

> **Note**: `Standard_DC4s_v3` is not mandatory. `Standard_DC4s_v2` also works, but v3 allows for optimized performance that is not available out of the box with v2. Therefore, requesting a quota increase by opening a ticket with the Azure support team is required. Consult with the official Microsoft documentation for a list of SGX-supported instances.

5. Name your Co-signer VM and create it.

The final resource setup window should look like this:

<img alt="" />

### 1.3. Verify SGX is enabled on your VM

After creating your virtual machine, confirm that SGX is enabled. The SGX Co-signer requires a server with SGX enabled and the latest patches applied. This verification ensures smooth operation and avoids potential issues.

To verify that SGX is enabled on the VM, run the following commands with root privileges::

```bash theme={"system"}
 apt update
 apt upgrade
 apt install cpuid
 cpuid -1 | grep -i sgx
```

Verify the following:

1. `SGX`: Software Guard Extensions supported is **true**
2. `SGX_LC`: SGX launch config supported is **true**

<img alt="" />

> **Note**: Azure `Standard_DC4s_v2` instances do not support SGX2. However, SGX2 is not required to run the Co-signer.

### 1.4. Install the required software packages

* Install Docker
* Install Docker compose
* Install PIP
* If not already installed, download the SGX driver from:

  `[https://download.01.org/intel-sgx/sgx-dcap/1.10.3/linux/distro/ubuntu20.04-server/](<>)`

### 1.5. Additional security recommendations

It is highly recommended to control user and network access to Co-signer's machine. See [API Co-signer security checklist and recommended defense and monitoring systems](/docs/co-signer-security-checklist-defense-monitoring) for further information.

***

## Step 2: Add a Co-signer to the workspace using an API user

Follow the instructions to [add a new Co-signer to the workspace](/reference/install-api-cosigner-add-new-cosigner-p2). Ensure you copy to your clipboard the following items, which you will use during the installation process:

* The API user's pairing token
* The download link of the Co-signer's installation script

***

## Step 3: Install and connect the Co-signer to the workspace

> **Note:** You must have root privileges on the Co-signer machine to install the Co-signer. Ensure you are logged in as a root user or use `sudo` to execute the commands.

### 3.1. Download the installation script

Using the download link of the SGX Co-signer installation script you copied from the Console, run the `curl` command to download the package directly to your machine.

Paste the appropriate URL into the following command:

```bash theme={"system"}
curl -o cosigner "URL"
```

### 3.2. Run the installation script

After downloading the installation script, navigate to the directory containing the script and modify the script's permissions to make it executable:

```bash theme={"system"}
chmod +x cosigner
```

To install the Co-signer, run:

```bash theme={"system"}
./cosigner setup
```

You will be prompted to enter the **Pairing token** for the API user, which you retrieve from the Fireblocks Console. This token pairs the API user with the Co-signer.

At this stage, you will have the option to configure the Callback Handler parameters for the API user connecting the Co-signer to the workspace. This feature is optional. You can [configure it later through the Console, APIs, or locally](/reference/api-cosigner-operate) from the Co-signer's host machine.

For detailed instructions on setting up your Callback Handler's interface to the Co-signer and implement its logic and code, refer to the [Setup API Co-signer Callback Handler](/reference/api-cosigner-setup-callback-handler) section.

The setup process validates the machine's hardware and installs the necessary drivers to support the appropriate SGX version and the SGX Co-signer's executable image. It includes an attestation flow to ensure that the SGX Co-signer's executable runs securely inside an Intel SGX enclave. Additionally, the script installs other required components.

Once installation is complete, to start the cosigner run: `./cosigner start`. At the end of the process, the Co-Signer generates a JSON configuration file, which can be used for future configuration updates.

### 3.3: Approve MPC key shares for the API user

If the API user used to pair with the Co-Signer and connect it to your workspace has an Admin or User role, the workspace owner will receive a notification. This notification will prompt them to approve a new MPC key share request for that API user using the Fireblocks mobile app.

You can now see the Co-signer you installed in the Co-signers tab within the Console's Developer Center. Observe it is online and that the API user is paired to it.

***

> **To check the Co-signer's status and observe the logs, see the SGX Co-signer Maintenance article.**


# Install SGX Azure Marketplace API Co-signer
Source: https://developers.fireblocks.com/reference/install-api-cosigner-azure-marketplace



The Fireblocks API Co-signer script is available as a managed and versioned component through [the Azure Marketplace](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/fireblocksinc1626390946623.co-signer?tab=Overview). This solution automates the deployment process, eliminating the need to create an SGX-enabled VM and install the Co-signer.

To install an SGX Co-signer in Microsoft Azure and connect it to your workspace through the Azure Marketplace, complete the following steps.

## Step 1: Add a Co-signer to the workspace using an API user

Follow the instructions to [add a new Co-signer to the workspace](/reference/install-api-cosigner-add-new-cosigner-p2). Ensure you copy to your clipboard the following items, which you will use during the installation process:

* The API user's pairing token
* The download link of the Co-signer's installation script

## Step 2: Set up your Azure environment, install and connect the Co-signer to the workspace

### 2.1. Azure prerequisites

You must have a valid Azure Subscription with permissions to create Confidential Compute VMs, VNets, Resource Groups, and OS Disk at a minimum. Your subscription must also be registered for `Microsoft.Compute`, `Microsoft.Solutions` and `Microsoft.Network` service providers.

Your Azure subscription must have Quota limits enabled for `Standard_DC4s_v3` VM. If you are unsure, check with your Azure Administrator. You may have to submit a support ticket with Microsoft to increase the quota limits.

Also, your Azure subscription must have the following permissions:

* `Microsoft.Solutions/locations/operationStatuses/read`
* `Microsoft.Resources/deployments/write`
* `Microsoft.Network/virtualNetworks/write`
* `Microsoft.Network/networkInterfaces/write`
* `Microsoft.Compute/virtualMachines/write`
* `Microsoft.Compute/virtualMachines/extensions/write`

### 2.2. Using the marketplace automation

Complete the following steps to deploy a new SGX Co-signer using the Azure Marketplace.

#### Basics tab

* Under **Subscription**, select or enter your existing Azure subscription where you want to deploy this Co-signer.
* Under **Resource group**, select or create a group that properly organizes your resources within your subscription (i.e. geographic, commercial, sales affiliation, etc).
* Under **Region**, select the geographic region where you want your virtual machine to be deployed.
* Under **Virtual Machine**, select a name for your machine that is aligned with your best practices. Here you can also change the machine’s size, depending on your estimate of your projected transaction volume. We recommend DC4S as a minimum, but you may decide to change it based on your expected processing volume.
* Under **Username**, enter a username, and we will create one for you with an admin role, which is necessary for the creation of your API Co-signer and for logging into and fully managing your Azure’s virtual machine.
* Alternatively, if you are not interested in a username and password, you can upload a **Public key**. Once we receive it from you, we will use it to create a virtual machine for you, and you can use this key to log into the machine.
* If you decide to go with a username, enter and confirm a **Password** of your choice. The password must meet the specifications listed on the marketplace.
* Under **Managed application**, which is where we package all of your resources (the VM, Virtual network, storage), enter the name of your managed application (just as you entered the name of your Subscription above).
* Similarly, under **Managed resource group**, enter the name of your Managed resource group (just as you entered the name of your Resource group above).
* Select Next to move on to the next tab.

<img alt="" />

#### API Cosigner Settings tab

* Enter the API user's pairing token you copied from the Console
* Enter the download link of the SGX Co-signer's installation script you copied from the Console

At this stage, you will have the option to configure the Callback Handler parameters for the API user connecting the Co-signer to the workspace. This feature is optional. You can [configure it later through the Console, APIs, or locally](/reference/api-cosigner-operate) from the Co-signer's host machine.

For detailed instructions on setting up your Callback Handler's interface to the Co-signer and implementing its logic and code, refer to the [Setup API Co-signer Callback Handler](/reference/api-cosigner-setup-callback-handler) section.

<img alt="" />

#### Review + Create tab

In this tab, you can review all the information you provided in the previous sections and confirm it is accurate, or go back to modify whatever needs correction.

Select **Create**, and the Azure Marketplace solution will initiate the creation of the Azure SGX API Co-signer after a few minutes. If the deployment fails, you will see an error on the Azure Marketplace portal along with details on its root cause. Refer to the Troubleshooting section below for potential issues that could cause such a failure.

<img alt="" />

#### Co-signer script

The Azure Co-signer script is installed in the home folder of the admin user (e.g., `/home/yourname/`). You can [operate](/reference/api-cosigner-operate) and [maintain](/reference/api-cosigner-maintenance-sgx) the Co-signer using the Console or the script from the Azure VM, just as you would from the command line of an SGX machine you set up manually.

### 2.3: Approve MPC key shares for the API user

If the API user used to pair with the Co-Signer and connect it to your workspace has an Admin or User role, the workspace owner will receive a notification. This notification will prompt them to approve a new MPC key share request for that API user using the Fireblocks mobile app.

You can now see the Co-signer you installed in the Co-signers tab within the Console's Developer Center. Observe it is online and that the API user is paired to it.

## Troubleshooting

> **Co-signer Maintenance**
>
> To check the Co-signer's status and observe the logs, see the [SGX Co-signer Maintenance](/reference/api-cosigner-maintenance-sgx) article.

Since the solution is deployed on an Azure instance in your environment, a wide range of issues may occur depending on your configuration. Here are some common issues:

* Quota limits on your subscription may prevent the provisioning of `Standard_DC4s_v3 VM`. You may have to request an increase in quota limits or open a support ticket with Microsoft to increase the quota limits.
* Review the Azure deployment logs for any permissions-related errors. [Learn more about resolving these errors in the official Microsoft Azure documentation](https://learn.microsoft.com/en-us/azure/azure-resource-manager/troubleshooting/error-register-resource-provider?tabs=azure-portal).
* Ensure your subscription has Microsoft.Compute, Microsoft.Solutions, and Microsoft.Network registered.
* Your subscription should also have permission to create resource groups.
* Your Azure subscription should have the permissions listed in the prerequisites section above.
* Check if your pairing token has expired. If it has, renew the token and try again.
* The API Co-signer script URL must be entered with opening and closing double quotes.
* If you modified the default VM, make sure you selected an SGX-enabled VM.
* Log a ticket with Fireblocks Support and attach the `*_run.log` files from the `/var/lib/waagent/custom-script/download/0` folder.
* You may need to delete the VM and any resources created during the deployment of the solution.


# Install Google Cloud Confidential Space API Co-signer
Source: https://developers.fireblocks.com/reference/install-api-cosigner-gcp



## Overview

To install a Confidential Space Co-signer in Google Cloud and connect it to your workspace, follow these steps:

1. **Setup and configure your Google Cloud environment**
   Prepare your Google Cloud environment and the machine where you plan to install the Co-signer from (e.g., your laptop).
2. **Add a Co-signer to the workspace using an API user**
   Using the Fireblocks Console or APIs, create an API user and use it to add a Co-signer to the workspace.
3. **Install and connect the Co-signer to the workspace**
   Download the installation script to the machine where you plan to execute it, run the script to set up the necessary Google Cloud resources, and install the Co-signer. Once installation is complete, the workspace owner approves the new MPC key shares for the API user through the Fireblocks mobile app.

You can now view the Co-signer and its paired API user in your Fireblocks Console. Additionally, you can retrieve information about them using the Co-signer APIs.

## Step 1: Set up and configure your Google Cloud environment

Proper configuration of your Google Cloud environment is straightforward but must be performed step by step in the specified order. The installation script automates the resource creation and setup process and it is not recommended to change it. Any misconfiguration could compromise the Co-signer's functionality or security.

### 1.1. Allowlist Domains

To ensure the Co-signer can be installed and operated successfully, add the Fireblocks' domains to your allowlist. Fireblocks-owned domains differ based on the specific Fireblocks SaaS environment you are connected to. If you are connected to the European or Swiss SaaS, update your allowlist according to the domains in the table below.

| Fireblocks SaaS | Domains to Allow                                                                   |
| --------------- | ---------------------------------------------------------------------------------- |
| Global          | `mobile-api.fireblocks.iosignurl.fireblocks.ios3signurl.fireblocks.io`             |
| Europe          | `eu2-mobile-api.fireblocks.ioeu2-signurl.fireblocks.ioeu2-s3signurl.fireblocks.io` |
| Swiss           | `eu-mobile-api.fireblocks.ioeu-signurl.fireblocks.ioeu-s3signurl.fireblocks.io`    |

### 1.2. Install the required software packages

Ensure the following software packages are installed on the machine where you will run the installation script (e.g., your laptop):

* [**gcloud**](https://cloud.google.com/sdk/gcloud): The installation script automates the setup process by using gcloud and prompts you for the required inputs. It assumes you have the necessary credentials and permissions for your Google Cloud account. **gcloud sdk version of 396+ is required.**
* **uuidgen**: used for generating the Co-signer’s unique ID during installation.
* **jq**: used to create an output JSON configuration file.

The installation script uses those packages to create the resources and install the Co-signer.

### 1.3. Ensure account permissions for the required Google Cloud resources

You must have the necessary Google Cloud account permissions to enable network access to required domains and to create and configure the following resources:

* Project
* IAM Role
* Workload Identity Pool provider
* Customer Managed Key (CMK)
* Bucket
* Workload Container

### 1.4. Additional security recommendations

It is highly recommended to control user and network access to your Google Cloud environment. See [API Co-signer security checklist and recommended defense and monitoring systems](/docs/co-signer-security-checklist-defense-monitoring) for further information.

## Step 2: Add a Co-signer to the workspace using an API user

Follow the instructions to [add a new Co-signer to the workspace](/reference/install-api-cosigner-add-new-cosigner-p2). Ensure you copy to your clipboard the following items, which you will use during the installation process:

* The API user's pairing token
* The download link of the Co-signer's installation script

## Step 3: Install and connect the Co-signer to the workspace

### 3.1. Download and unpack the installation package

Using the download link of the GCP Co-signer installation package you copied from the Console, run the `wget` command to download the package directly to your machine.

Paste the appropriate URL into the following command:

`wget -O gcp-cosigner.zip "URL"`

Unpack the installation package by running the following command:

`tar -xzvf gcp-cosigner.zip`

### 3.2. Run the installation script

1. Log in to gcloud with `gcloud auth login`.
2. The installation package contains an installation script. To install the Co-signer, navigate to the directory where the installation package was unpacked and run `client_install_gcp_api_cosigner_script.sh` script in an interactive shell and respond to prompts as the script executes.
3. When prompted, select option **"1 - Create"** for first-time setup.

### 3.3. Approve MPC key shares for the API user

If the API user used to pair with the Co-Signer and connect it to your workspace has an Admin or User role, the workspace owner will receive a notification. This notification prompts them to approve a new MPC key share request for that API user in the Fireblocks mobile app.

You can now see the Co-signer you installed in the Co-signers tab within the Console's Developer Center. [Observe that it is online](/reference/api-cosigner-maintenance-gcp-confspace) and that the API user is paired to it.

## **Proxy configuration (optional)**

The Co-signer can route outbound traffic through an HTTPS proxy. When a proxy is configured, the Co-signer automatically switches from WebSocket to long-polling (REST), since WebSocket connections cannot reliably traverse proxies.

The script prompts you for a proxy URL during installation. If you don't need a proxy, press **Enter** to skip this step.

```text theme={"system"}
Please enter HTTPS proxy URL [can be empty; e.g. http://proxy:8080 or http://user:pass@proxy:8080]:
```

To authenticate to the proxy, include the credentials directly in the URL:

```http theme={"system"}
http://username:password@proxy.example.com:8080
```

The proxy URL — including any credentials — is encrypted immediately using your Cloud KMS key and is never stored in plaintext. Only the encrypted value is written to the `cloud-resources-*.yaml` file.

If you provide a proxy URL, the script also prompts for `NO_PROXY` patterns: a comma-separated list of hosts that should bypass the proxy. The recommended defaults are:

```text theme={"system"}
169.254.169.254,metadata.google.internal,googleapis.com
```

These cover the GCP metadata server and Google APIs, which must remain reachable directly.

**For non-interactive installs**, set these fields in your `install-config.yaml`:

```yaml theme={"system"}
# Optional proxy fields
proxy_url: http://username:password@proxy.example.com:8080
no_proxy: 169.254.169.254,metadata.google.internal,googleapis.com
```


# Install SGX IBM Cloud API Co-signer
Source: https://developers.fireblocks.com/reference/install-api-cosigner-ibm



## Overview

To install an SGX Co-signer in IBM Cloud and connect it to your workspace, follow these steps:

1. **Setup and configure your IBM Cloud environment**

   Prepare your IBM Cloud environment by creating and configuring the required resources. Ensure it meets the necessary specifications and security settings.

2. **Add a Co-signer to the workspace using an API user**

   Using the Fireblocks Console or APIs, create an API user and use it to add a Co-signer to the workspace.

3. **Install and connect the Co-signer to the workspace**

   Download the installation script to the SGX-capable virtual machine and run the script to install the Co-signer. Once installation is complete, the workspace owner approves the new MPC key shares for the API user through the Fireblocks mobile app.

You can now view the Co-signer and its paired API user in your Fireblocks Console. Additionally, you can retrieve information about them using the Co-signer APIs.

***

## Step 1: Setup and configure your IBM Cloud environment

### 1.1. Allowlist domains

To ensure the Co-signer can be installed and operated successfully, add the following domains to your allowlist:

| Domain                                  | Owner                      |
| --------------------------------------- | -------------------------- |
| `mobile-api.fireblocks.io`              | Fireblocks                 |
| `signurl.fireblocks.io`                 | Fireblocks                 |
| `s3signurl.fireblocks.io`               | Fireblocks                 |
| `fb-certs.s3.amazonaws.com`             | AWS                        |
| `fb-cosigner-images.s3.amazonaws.com`   | AWS                        |
| `fb-customers.s3.amazonaws.com`         | AWS                        |
| `fb-customers.s3.amazonaws.com/uploads` | AWS                        |
| `download.docker.com`                   | Docker                     |
| `registry.gitlab.com`                   | GitLab                     |
| `cdn.registry.gitlab-static.net`        | GitLab                     |
| `gitlab.com`                            | GitLab                     |
| `github.com`                            | GitHub                     |
| `download.01.org`                       | Intel SGX Driver           |
| `bootstrap.pypa.io`                     | Python Software Foundation |
| `files.pythonhosted.org`                | Python Software Foundation |
| `pypi.org`                              | Python Software Foundation |
| `pypi.python.org`                       | Python Software Foundation |

Fireblocks-owned domains differ based on the specific Fireblocks SaaS environment you are connected to. If you are connected to the European or Swiss SaaS, update your allowlist according to the domains listed in the table below:

| Fireblocks SaaS | Domains to Allow                                                                           |
| --------------- | ------------------------------------------------------------------------------------------ |
| Global          | `mobile-api.fireblocks.io`  `signurl.fireblocks.io`  `s3signurl.fireblocks.io`             |
| Europe          | `eu2-mobile-api.fireblocks.io`  `eu2-signurl.fireblocks.io`  `eu2-s3signurl.fireblocks.io` |
| Swiss           | `eu-mobile-api.fireblocks.io`  `eu-signurl.fireblocks.io`  `eu-s3signurl.fireblocks.io`    |

Additionally, ensure port access is configured for the following services:

| Port | Service URL                                      |
| ---- | ------------------------------------------------ |
| 443  | `https://mobile-api.fireblocks.io`               |
| 443  | `https://s3signurl.fireblocks.io`                |
| 443  | `https://fb-certs.s3.amazonaws.com`              |
| 443  | `https://fb-customers.s3.amazonaws.com/uploads/` |
| 443  | `https://bootstrap.pypa.io/get-pip.py`           |
| 443  | `https://download.docker.com/linux`              |
| 443  | `https://download.01.org/intel-sgx/`             |
| 5000 | `https://registry.gitlab.com/customer-cosigner`  |

### 1.2. Create an SGX virtual machine

**The minimum hardware requirements for the VM are:**

* RAM: 32GB
* Storage: 256GB
* OS:
  * Ubuntu 20.04
  * Latest Linux kernel version
  * Latest Intel microcode (BIOS update)

Complete the following steps to create an SGX-capable VM in IBM Cloud:

1. On the Dashboard page, select **Create Resource**.

<img alt="" />

2. Go to **IBM Cloud catalog** > **Compute** > **Bare Metal Servers**.

<img alt="" />

<img alt="" />

3. In the Server Profile section, select **View all profiles**.

<img alt="" />

4. Select **Intel Xeon E-2174G CPU**.

<img alt="" />

5. In the Operating System section, select the following options:
   1. Vendor: Ubuntu
   2. Version: 18.04 LTS (64-bit)
   3. RAM (recommended): 32 GB

<img alt="" />

6. Select the **Software Guard Extensions** toggle under Add-ons > **Security and Business Continuity**.

<img alt="" />

7. Lastly, create the VM.

### 1.3. Verify SGX is enabled on your VM

After creating your virtual machine, confirm that SGX is enabled. The SGX Co-signer requires a server with SGX enabled and the latest patches applied. This verification ensures smooth operation and avoids potential issues.

To verify that SGX is enabled on the VM, run the following commands with root privileges::

```bash theme={"system"}
 apt update
 apt upgrade
 apt install cpuid
 cpuid -1 | grep -i sgx
```

Verify the following:

1. `SGX`: Software Guard Extensions supported is **true**
2. `SGX_LC`: SGX launch config supported is **true**

<img alt="" />

### 1.4. Additional security recommendations

It is highly recommended to control user and network access to Co-signer's machine. See [API Co-signer security checklist and recommended defense and monitoring systems](/docs/co-signer-security-checklist-defense-monitoring) for further information.

***

## Step 2: Add a Co-signer to the workspace using an API user

Follow the instructions to [add a new Co-signer to the workspace](/reference/install-api-cosigner-add-new-cosigner-p2). Ensure you copy to your clipboard the following items, which you will use during the installation process:

* The API user's pairing token
* The download link of the Co-signer's installation script

***

## Step 3: Install and connect the Co-signer to the workspace

> **Note:** You must have root privileges on the Co-signer machine to install the Co-signer. Ensure you are logged in as a root user or use `sudo` to execute the commands.

### 3.1. Download the installation script

Using the download link of the SGX Co-signer installation script you copied from the Console, run the `curl` command to download the package directly to your machine.

Paste the appropriate URL into the following command:

```bash theme={"system"}
curl -o cosigner "URL"
```

### 3.2. Run the installation script

After downloading the installation script, navigate to the directory containing the script and modify the script's permissions to make it executable:

```bash theme={"system"}
chmod +x cosigner
```

To install the Co-signer, run:

```bash theme={"system"}
./cosigner setup
```

You will be prompted to enter the **Pairing token** for the API user, which you retrieve from the Fireblocks Console. This token pairs the API user with the Co-signer.

At this stage, you will have the option to configure the Callback Handler parameters for the API user connecting the Co-signer to the workspace. This feature is optional. You can [configure it later through the Console, APIs, or locally](/reference/api-cosigner-operate) from the Co-signer's host machine.

For detailed instructions on setting up your Callback Handler's interface to the Co-signer and implement its logic and code, refer to the [Setup API Co-signer Callback Handler](/reference/api-cosigner-setup-callback-handler) section.

The setup process validates the machine's hardware and installs the necessary drivers to support the appropriate SGX version and the SGX Co-signer's executable image. It includes an attestation flow to ensure that the SGX Co-signer's executable runs securely inside an Intel SGX enclave. Additionally, the script installs other required components.

Once the installation is complete, the Co-signer will automatically start running. At the end of the process, the Co-Signer generates a JSON configuration file, which can be used for future configuration updates.

### 3.3: Approve MPC key shares for the API user

If the API user used to pair with the Co-Signer and connect it to your workspace has an Admin or User role, the workspace owner will receive a notification. This notification will prompt them to approve a new MPC key share request for that API user using the Fireblocks mobile app.

You can now see the Co-signer you installed in the Co-signers tab within the Console's Developer Center. Observe it is online and that the API user is paired to it.

***

> **To check the Co-signer's status and observe the logs, see the SGX Co-signer Maintenance article.**


# Install SGX On-prem API Co-signer
Source: https://developers.fireblocks.com/reference/install-api-cosigner-onprem



## Overview

To install an SGX Co-signer on-premises and connect it to your workspace, follow these steps:

1. **Setup and configure your on-prem environment:** Prepare your on-prem environment by creating and configuring the required resources. Ensure it meets the necessary specifications and security settings.
2. **Add a Co-signer to the workspace using an API user:** Using the Fireblocks Console or APIs, create an API user and use it to add a Co-signer to the workspace.
3. **Install and connect the Co-signer to the workspace:** Download the installation script to the SGX-capable machine, then run it to install the Co-signer. Once installation is complete, the workspace owner approves the new MPC key shares for the API user through the Fireblocks mobile app.

You can now view the Co-signer and its paired API user in your Fireblocks Console. Additionally, you can retrieve information about them using the Co-signer APIs.

## Step 1: Set up and configure your on-prem environment and SGX server

### Step 1.1: Allowlist domains

To ensure the Co-signer can be installed and operated successfully, add the following domains to your allowlist:

| Domain                                  | Owner                      |
| --------------------------------------- | -------------------------- |
| `mobile-api.fireblocks.io`              | Fireblocks                 |
| `signurl.fireblocks.io`                 | Fireblocks                 |
| `s3signurl.fireblocks.io`               | Fireblocks                 |
| `fb-certs.s3.amazonaws.com`             | AWS                        |
| `fb-cosigner-images.s3.amazonaws.com`   | AWS                        |
| `fb-customers.s3.amazonaws.com`         | AWS                        |
| `fb-customers.s3.amazonaws.com/uploads` | AWS                        |
| `download.docker.com`                   | Docker                     |
| `github.com`                            | GitHub                     |
| `cdn.registry.gitlab-static.net`        | GitLab                     |
| `gitlab.com`                            | GitLab                     |
| `registry.gitlab.com`                   | GitLab                     |
| `download.01.org`                       | Intel SGX Driver           |
| `bootstrap.pypa.io`                     | Python Software Foundation |
| `files.pythonhosted.org`                | Python Software Foundation |
| `pypi.org`                              | Python Software Foundation |
| `pypi.python.org`                       | Python Software Foundation |

Fireblocks-owned domains differ based on the specific Fireblocks SaaS environment you are connected to. If you are connected to the European or Swiss SaaS, update your allowlist according to the domains listed in the table below:

| Fireblocks SaaS | Domains to Allow                                                                         |
| --------------- | ---------------------------------------------------------------------------------------- |
| Global          | `mobile-api.fireblocks.io` `signurl.fireblocks.io` `s3signurl.fireblocks.io`             |
| Europe          | `eu2-mobile-api.fireblocks.io` `eu2-signurl.fireblocks.io` `eu2-s3signurl.fireblocks.io` |
| Swiss           | `eu-mobile-api.fireblocks.io` `eu-signurl.fireblocks.io` `eu-s3signurl.fireblocks.io`    |

Additionally, ensure port access is configured for the following services:

| Port | Service URL                                      |
| ---- | ------------------------------------------------ |
| 443  | `https://mobile-api.fireblocks.io`               |
| 443  | `https://s3signurl.fireblocks.io`                |
| 443  | `https://fb-certs.s3.amazonaws.com`              |
| 443  | `https://fb-customers.s3.amazonaws.com/uploads/` |
| 443  | `https://bootstrap.pypa.io/get-pip.py`           |
| 443  | `https://download.docker.com/linux`              |
| 443  | `https://download.01.org/intel-sgx/`             |
| 5000 | `https://registry.gitlab.com/customer-cosigner`  |

### Step 1.2: Set up and configure an on-prem SGX server

Your on-prem SGX server should meet the following hardware requirements:

* **CPU processor:** Only one of the following [Intel® processors](https://www.intel.com/content/www/us/en/architecture-and-technology/software-guard-extensions-processors.html)
* **CPU cores:** Minimum 4
* **OS:** Ubuntu 22.04 LTS or 24.04 LTS (Canonical) with -
  * Latest Linux kernel version
  * Latest Intel microcode (BIOS update)
* **RAM:** Minimum 16GB
* **Storage:** Minimum 128GB
* **SGX Memory:** Minimum 2GB EPC

> **Fireblocks also supports on-prem SGX servers installed on OVHcloud providers.**

Additionally, configure your on-prem SGX server BIOS to match the following setup:

* Enable Intel SGX (Software Guard Extension)
* Enable DCAP (FLC)
* Disable hyper threading
* Disable Intel SpeedStep Technology
* Disable Onboard VGA

### Step 1.3: Verify SGX is enabled on your SGX server

After setting up your on-prem SGX server, confirm that SGX is enabled. The SGX Co-signer requires a server with SGX enabled and the latest patches applied. This verification ensures smooth operation and avoids potential issues.

To verify that SGX is enabled on the VM, run the following commands with root privileges:

```bash theme={"system"}
 apt update
 apt upgrade
 apt install cpuid
 cpuid -1 | grep -i sgx
```

Verify the following:

1. `SGX`: Software Guard Extensions supported is **true**
2. `SGX_LC`: SGX launch config supported is **true**

<img alt="" />

### Step 1.4: Install the SGX drivers

1. [Subscribe to the Intel PCS for ECDSA Attestation and to obtain the required API keys](https://api.portal.trustedservices.intel.com/provisioning-certification).
2. Set up Intel's reference caching service, the Provisioning Certification Caching Service (PCCS):
   1. **Redhat/Debian:** [Installation Guide, page 39](https://download.01.org/intel-sgx/latest/dcap-latest/linux/docs/Intel_SGX_SW_Installation_Guide_for_Linux.pdf?#page=39)
   2. **Another Debian approach:** Follow the steps in the document above (intel-dcap.pdf), but skip the *Verify the empty cache* step.
   3. **Cache Fill Mode:** [Intel SGX DCAP Caching Service Design Guide, page 38](https://download.01.org/intel-sgx/latest/dcap-latest/linux/docs/SGX_DCAP_Caching_Service_Design_Guide.pdf#page=38)
3. Provision the Intel SGX-enabled platform for Intel SGX workloads. The goal is to run PCKIDRetrievalTool. *Make sure pckid\_retrieval.csv is created.* This file will be used to register the CPU data with Intel. Without this registration, the remote attestation will fail.
   1. **Debian resources:** [Intel SGX DCAP Quick Install Guide, page 4](https://drive.google.com/file/d/1lZWM4_dTSdOID9PdKGFDenkyi4DA9OR8/view)
   2. **Redhat resources:** Download the binary file from one of these locations:
      1. [https://download.01.org/intel-sgx/sgx-dcap/1.18/linux/distro/rhel8.6-server/](https://download.01.org/intel-sgx/sgx-dcap/1.18/linux/distro/rhel8.6-server/)
      2. [https://github.com/intel/SGXDataCenterAttestationPrimitives/tree/main/tools/PCKRetrievalTool](https://github.com/intel/SGXDataCenterAttestationPrimitives/tree/main/tools/PCKRetrievalTool)
4. Convert the pckid\_retrieval.csv file to JSON format using this Python script and submit it to Intel for registration. You can view a sample JSON [here](https://drive.google.com/file/d/1x9NCvFHYMR8-MaauEWspZZAsZjU6qjdS/view).

   ```python theme={"system"}
   import json
   import sys

   if len(sys.argv) != 2 and len(sys.argv) != 3:
       print("usage: pckid2json <pckid file path> <outputfile>")
       exit(0)

   f = open(sys.argv[1], 'r')
   data = f.read().split(',')
   f.close()

   if len(data) == 5:
       print("WARNING: platform metadata is missing from pckid file")
   elif len(data) != 6:
       print("ERROR: pckid file has invalid format")
       exit(-1)

   obj = {}
   obj['enc_ppid'] = data[0]
   obj['pce_id'] = data[1]
   obj['cpu_svn'] = data[2]
   obj['pce_svn'] = data[3]
   obj['qe_id'] = data[4]
   if len(data) == 6:
       obj['platform_manifest'] = data[5]

   if len(sys.argv) == 3:
       f = open(sys.argv[2], 'w')
       json.dump(obj, f)
       f.close()
   else:
       print(json.dumps(obj))
   ```

   1. For more information about the registration process, visit the following references:
      1. [Design Guide for Intel SGX PCCS, page 20](https://download.01.org/intel-sgx/latest/dcap-latest/linux/docs/SGX_DCAP_Caching_Service_Design_Guide.pdf#page=20\&zoom=100,92,200)
      2. [Get PCK Certificates, V4](https://api.portal.trustedservices.intel.com/content/documentation.html#pcs-certificates-v4)
5. When prompted to verify the provisioning data, skip this step.
6. Reimage the Intel SGX-enabled platform.
7. Load the Intel SGX runtime stack onto the reimaged system:
   1. **Debian:** Refer to the [Intel SGX DCAP Quick Install Guide, page 5](https://drive.google.com/file/d/1lZWM4_dTSdOID9PdKGFDenkyi4DA9OR8/view). Note that steps 5 and 6 are bulked up in the "Runtime configuration" section.
   2. **Redhat:** Refer to the [Intel Confidential Computing Documentation](https://cc-enabling.trustedservices.intel.com/intel-sgx-sw-installation-guide-linux/01/introduction/).

### Step 1.5: Registration with Intel

1. Follow the registration instructions located [here](https://api.portal.trustedservices.intel.com/content/documentation.html#pcs-tcb-info-v4). Note that you'll need the JSON format of the pckid\_retrieval.csv file for this step.

2. Verify that your CSV is registered with Intel via Fireblocks:

   ```bash theme={"system"}
   curl -L
   "https://mobile-api.fireblocks.io/sgx/certification/v3/pckcert?qeid=FC88E54A32E9BE6455A01CE78A55B85C&encrypted_ppid=635DBA646F13077DC75291B12ABE96D4D69A956D7FF5524D8090290EEB8ACC6450F72CD7539D1578E636911321D96E0CEC15E04FACBC7652DE1775F76DF460D472A7F5C8118B22C37F4590789F46161D99F2758D120C5BD4CD8FD302C444F56E620A98DFAFD156887B73DAEEB04EA6C9007C2EEB9B00DF49FBBD4B9535B8DB61445A28F73CADDADB36B27E35DACE6A4287621D2FF6E01B31C579FC9D73512B631558427370020DAB10DF315D740400ED73D64AACBFC76A0B88975A52086CD656809A58821A9B8516A4571BF33CBA042B76EC4409745635ADF2DE5F62FA8C0F6E4970712209F3D2EF83E5850646105B841F1905CB3E7F5AE21BF8759250C9981F8DEA229265CC619D9990842AC71739BCF155FCBA6AD262EDF04AA8A9E668E2F87A3FA822E7F6F330CA955C9B6244E5C35BFA71DA08655C1244156E598F97B97BAF1DF6CF79B624E5129AF190A24930436BDCC2371BEA322EEF2D733769372D5F763763B937BF680D4245441F234623051FAFCF0DA8FA79D744E3F261FD352275&cpusvn=0C0C0F0EFFFF01000000000000000000&pcesvn=0C00&pceid=0000"
   ```

3. A certificate will appear in the response if the registration was successful:

   ```yaml theme={"system"}
   -----BEGIN CERTIFICATE-----
   MIIE8jCCBJigAwIBAgIUUWcKdCIgJwOmz/lT0UrRd9zVUU8wCgYIKoZIzj0EAwIw
   cDEiMCAGA1UEAwwZSW50ZWwgU0dYIFBDSyBQbGF0Zm9ybSBDQTEaMBgGA1UECgwR
   SW50ZWwgQ29ycG9yYXRpb24xFDASBgNVBAcMC1NhbnRhIENsYXJhMQswCQYDVQQI
   DAJDQTELMAkGA1UEBhMCVVMwHhcNMjQxMjAzMDg1MzA2WhcNMzExMjAzMDg1MzA2
   …….
   …….
   …….
   -----END CERTIFICATE-----
   ```

## Step 2: Add a Co-signer to the workspace using an API user

Follow the instructions to [add a new Co-signer to the workspace](/reference/install-api-cosigner-add-new-cosigner-p2). Ensure you copy to your clipboard the following items, which you will use during the installation process:

* The API user's pairing token
* The download link of the Co-signer's installation script

## Step 3: Install and connect the Co-signer to the workspace

> **You must have root privileges on the Co-signer server to install the Co-signer**
>
> Ensure you are logged in as a root user or use `sudo` to execute the commands.

### Step 3.1: Download the installation script

Using the download link of the SGX Co-signer installation script you copied from the Console, run the `curl` command to download the package directly to your machine.

Paste the appropriate URL into the following command:

```bash theme={"system"}
curl -o cosigner "URL"
```

### Step 3.2: Run the installation script

After downloading the installation script, navigate to the directory containing the script and modify the script's permissions to make it executable:

```bash theme={"system"}
chmod +x cosigner
```

To install the Co-signer, run:

```bash theme={"system"}
./cosigner setup
```

You will be prompted to enter the **Pairing token** for the API user, which you retrieve from the Fireblocks Console. This token pairs the API user with the Co-signer.

At this stage, you will have the option to configure the Callback Handler parameters for the API user connecting the Co-signer to the workspace. This feature is optional. You can [configure it later through the Console, APIs, or locally](/reference/api-cosigner-operate) from the Co-signer's host machine.

For detailed instructions on setting up your Callback Handler's interface to the Co-signer and implementing its logic and code, refer to the [Setup API Co-signer Callback Handler](/reference/api-cosigner-setup-callback-handler) section.

The setup process validates the machine's hardware and installs the necessary drivers to support the appropriate SGX version and the SGX Co-signer's executable image. It includes an attestation flow to ensure that the SGX Co-signer's executable runs securely inside an Intel SGX enclave. Additionally, the script installs other required components.

Once the installation is complete, the Co-signer will automatically start running. At the end of the process, the Co-Signer generates a JSON configuration file, which can be used for future configuration updates.

### Step 3.3: Approve MPC key shares for the API user

If the API user used to pair with the Co-Signer and connect it to your workspace has an Admin or User role, the workspace owner will receive a notification. This notification prompts them to approve a new MPC key share request for that API user in the Fireblocks mobile app.

You can now see the Co-signer you installed in the Co-signers tab within the Console's Developer Center. Observe it is online and that the API user is paired to it.

> **To check the Co-signer's status and observe the logs, see the SGX Co-signer Maintenance article.**


# Interact with Solana Programs
Source: https://developers.fireblocks.com/reference/interact-with-solana-programs



> **Solana Program Calls require hot wallets**
>
> Solana Program Calls require a hot wallet and cannot be used in cold workspaces.

# Overview of Solana transactions & programs

Solana programs are on-chain executable codes that power the decentralized applications (dApps) and other functionalities within the Solana blockchain. They enable smart contract-like behavior, allowing developers to write logic that processes transactions and manages state.

## Solana transactions

A Solana transaction is a set of instructions bundled together to be executed automatically on the blockchain. It typically consists of the following components:

1. **Signatures:** A list of cryptographic signatures to authorize the transaction.
2. **Message:** The core of the transaction, which includes:
   1. **Instructions:** The set of actions to be performed. Each instruction targets a specific program on the blockchain, includes accounts to be accessed or modified, and contains any necessary data for the operation.
   2. **Account Keys:** A list of all accounts involved in the transaction.
   3. **Recent Blockhash:** A reference to a recent block to ensure the transaction is processed promptly and prevent replay attacks.

When a transaction is submitted, it is signed by the relevant parties and serialized before being broadcast to the network.

Fireblocks simplifies interacting with Solana programs by allowing you to use the [createTransaction](/reference/createtransaction) endpoint. This endpoint supports Solana program calls through the `PROGRAM_CALL` operation, ensuring secure transaction signing and execution.

> **SetAuthority instruction not allowed**
>
> Fireblocks' policy does not allow using the `SetAuthority` instruction, as it may expose users to malicious activity.

***

# Policy configuration

Solana Program Calls can be executed in Fireblocks without whitelisting any addresses if the One-Time Address feature is enabled. In this scenario, the Policy rule should include a condition for the `Program Call` operation, with the destination set to `Any`.

For clients who prefer to work with whitelisted addresses due to security concerns and Fireblocks' best practices, the Policy rule should be configured with the destination type set to `Whitelisted only` for any `Program Call` operation. In this case, the client must whitelist the following addresses involved in the Solana Program Call transaction:

1. **Any non-prewhitelisted program:** Fireblocks internally whitelists certain built-in Solana programs, including:

   * [System Program](https://docs.anza.xyz/runtime/programs#system-program)
   * [Compute Budget Program](https://github.com/solana-program/compute-budget)

   Additionally, the following [Sysvar Cluster Data](https://docs.anza.xyz/runtime/sysvars) accounts are pre-whitelisted:

   * [Recent Block Hashes](https://docs.anza.xyz/runtime/sysvars#recentblockhashes)
   * [Rental Rate](https://docs.anza.xyz/runtime/sysvars#rent)

   Any other program must be explicitly whitelisted as an **External Wallet/Contract** in Fireblocks.

2. **Any account designated as a destination:** For the [Transfer instructions](https://solana.com/docs/core/transactions#instruction) (if applicable) within the `Program Call` transaction.

***

# Practical example

When performing a SOL to USDC swap on **Jupiter**, the following list of programs participates in the transaction:

<img alt="" />

In the example above, **Programs 1, 2, and 4 (Green)** are automatically whitelisted. However, in this scenario, the customer must manually whitelist the following programs (Red):

1. **Associated Token Program**
2. **Token Program**
3. **Program #6**, which is a custom **Jupiter program**

> **Looking for a program's address?**
>
> You can expand a specific program's section to view its address (the `programId` value).

Additionally, expanding the **System Program** section reveals that this program includes a single instruction: `Transfer`. Expanding the `Transfer` instruction shows that, as expected, two accounts are involved:

* **`from`account** (index 1)
* **`to`account** (index 2)

To ensure the `Program Call` operation functions correctly, the `pubkey`value of the`to` address must be whitelisted.

<img alt="" />

> **Warning: For demonstrative purposes only**
>
> The addresses shown above are for demonstrative purposes only! Customers should always review and determine which addresses need to be whitelisted based on the specific Program Call context relevant to their use case.

***

# How do program calls work on Fireblocks?

To make a Solana program call using the Fireblocks API, you will:

1. **Build the Solana Transaction:** Use the Solana `web3.js` library or other tools to construct the unsigned transaction. Ensure the transaction includes all necessary instructions and accounts.

   **Note:** Fireblocks supports legacy and versioned v0 Solana transaction payloads only. Transactions built with any other message version are not supported and will fail with INTERNAL\_ERROR.

2. **Serialize and Encode:** Serialize the unsigned transaction object and encode it in Base64 format.

3. **Call Fireblocks API:**
   1. Use the Create Transaction endpoint.
   2. Set the operation parameter to `PROGRAM_CALL`.
   3. Pass the serialized, Base64 encoded transaction object in the `programCallData` parameter within the `extraParams` object.

Fireblocks securely signs the transaction using your organization’s private key, ensuring seamless execution without exposing sensitive cryptographic materials.

## Example transaction structure

Below is a sample payload for invoking a Solana program using the [Create Transaction API](/reference/createtransaction) :

```json theme={"system"}
{
  "operation": "PROGRAM_CALL",
  "assetId": "SOL",
  "source": {
    "type": "VAULT_ACCOUNT",
    "id": "<your_vault_account_id>"
  },
  "extraParameters": {
    "programCallData": "<base64_encoded_transaction>"
  }
}
```

#### Parameters

1. **operation:** Must be `PROGRAM_CALL` for Solana program calls.
2. **assetId:** Use SOL for Solana mainnet transactions, SOL\_TEST for devnet.
3. **source:** The vault account ID that holds the funds and signs the transaction.
4. **extraParams.programCallData:** The unsigned, serialized transaction object (Base64 encoded).
5. **extraParams.useDurableNonce:** (Optional; boolean) The configurable durable nonce. The default is `true`.
6. **extraParams.signOnly:** (Optional; boolean) Set to `true` to sign the transaction without submitting it to the blockchain. The default is `false`.

> **Durable nonce & Sign-only mode usage**
>
> #### Durable nonce usage
>
> By default, Fireblocks includes a [durable nonce](https://solana.com/developers/courses/offline-transactions/durable-nonces) in your transaction by adding an `AdvanceNonce` instruction. This ensures the transaction remains valid even if it's not immediately submitted.
>
> Set **useDurableNonce** to `false` to use the recent blockhash instead. This reduces transaction size, which may be necessary to stay within Solana's maximum transaction size limit.
>
> **useDurableNonce** is only used with Solana Program Calls. Other transactions do not use this field and will ignore its value.
>
> #### Sign-only mode usage
>
> Use sign-only mode when you want to sign a transaction but submit it to the blockchain through another method or service.
>
> After you sign a transaction, it normally moves from `PENDING_SIGNATURE` to `BROADCASTING` as Fireblocks submits it to the blockchain. When you enable sign-only mode, the transaction moves from `PENDING_SIGNATURE` to `SIGNED` instead. Fireblocks doesn't submit the transaction, but updates its status to `COMPLETED` if the blockchain includes it in a new block.
>
> **signOnly** is only used with Solana Program Calls. Other transactions do not use this field and will ignore its value.

# Fireblocks Solana Web3 Connection Adapter

[The Fireblocks Solana Web3 Connection Adapter](/reference/solana-web3-adapter) serves as a bridge between the Fireblocks API and the Solana blockchain, streamlining transaction submissions via Fireblocks when using Solana's official `web3.js` library.


# Internal, External & Contract Wallet Webhooks
Source: https://developers.fireblocks.com/reference/internal-external-contract-wallet-webhooks



> **Deprecation notice**
>
> Webhooks v1 will be deprecated on **June 15th, 2026**. Please use the Developer Center in the Fireblocks Console to upgrade to Webhooks V2, which offers improved reliability, performance, and observability.

This page describes all events relating to internal, external, and contract whitelisted wallets that produce webhook notifications, and their associated data objects.

The `type` parameter is automatically set to the description name for the data objects below.

***

## Asset added to internal wallet

Notification is sent when an asset is added to an internal wallet.

| Parameter | Type                                      | Description                            |
| --------- | ----------------------------------------- | -------------------------------------- |
| type      | string                                    | INTERNAL\_WALLET\_ASSET\_ADDED         |
| tenantId  | string                                    | Unique ID of your Fireblocks workspace |
| timestamp | number                                    | Timestamp in milliseconds              |
| data      | [WalletAssetWebhook](#walletassetwebhook) | Internal wallet details                |

## Asset removed from internal wallet

Notification is sent when an asset is removed from an internal wallet.

| Parameter | Type                                      | Description                            |
| --------- | ----------------------------------------- | -------------------------------------- |
| type      | string                                    | INTERNAL\_WALLET\_ASSET\_REMOVED       |
| tenantId  | string                                    | Unique ID of your Fireblocks workspace |
| timestamp | number                                    | Timestamp in milliseconds              |
| data      | [WalletAssetWebhook](#walletassetwebhook) | Internal wallet details                |

## Asset added to external wallet

Notification is sent when an asset is added to an external wallet.

| Parameter | Type                                      | Description                            |
| --------- | ----------------------------------------- | -------------------------------------- |
| type      | string                                    | EXTERNAL\_WALLET\_ASSET\_ADDED         |
| tenantId  | string                                    | Unique ID of your Fireblocks workspace |
| timestamp | number                                    | Timestamp in milliseconds              |
| data      | [WalletAssetWebhook](#walletassetwebhook) | External wallet details                |

## Asset removed from external wallet

Notification is sent when an asset is removed from an external wallet.

| Parameter | Type                                      | Description                            |
| --------- | ----------------------------------------- | -------------------------------------- |
| type      | string                                    | EXTERNAL\_WALLET\_ASSET\_REMOVED       |
| tenantId  | string                                    | Unique ID of your Fireblocks workspace |
| timestamp | number                                    | Timestamp in milliseconds              |
| data      | [WalletAssetWebhook](#walletassetwebhook) | External wallet details                |

## Asset added to contract wallet

Notification is sent when an asset is added to a contract wallet.

| Parameter | Type                                      | Description                            |
| --------- | ----------------------------------------- | -------------------------------------- |
| type      | string                                    | CONTRACT\_WALLET\_ASSET\_ADDED         |
| tenantId  | string                                    | Unique ID of your Fireblocks workspace |
| timestamp | number                                    | Timestamp in milliseconds              |
| data      | [WalletAssetWebhook](#walletassetwebhook) | Contract wallet details                |

## Asset removed from contract wallet

Notification is sent when an asset is removed from a contract wallet.

| Parameter | Type                                      | Description                            |
| --------- | ----------------------------------------- | -------------------------------------- |
| type      | string                                    | CONTRACT\_WALLET\_ASSET\_REMOVED       |
| tenantId  | string                                    | Unique ID of your Fireblocks workspace |
| timestamp | number                                    | Timestamp in milliseconds              |
| data      | [WalletAssetWebhook](#walletassetwebhook) | Contract wallet details                |

***

### WalletAssetWebhook

| Parameter      | Type   | Description                                                                                                                                                                                                 |
| -------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| assetId        | string | The wallet's asset                                                                                                                                                                                          |
| walletId       | string | The ID of the wallet                                                                                                                                                                                        |
| walletName     | string | The name of the wallet                                                                                                                                                                                      |
| address        | string | The address of the wallet                                                                                                                                                                                   |
| tag            | string | Destination address tag for Ripple; destination memo for Cosmos, EOS, Luna, Luna Classic, NEM, Stellar, Hedera, & DigitalBits; destination note for Algorand; bank transfer description for fiat providers. |
| activationTime | number | The time the wallet will be activated, if wallet activation is postponed according to your workspace definition                                                                                             |


# Internal/External Wallet Objects
Source: https://developers.fireblocks.com/reference/internalexternal-wallet-objects



## WalletAsset

| Parameter      | Type                                                                              | Description                                                                                                               |
| -------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| id             | string                                                                            | The ID of the asset                                                                                                       |
| balance        | string                                                                            | The balance of the wallet                                                                                                 |
| lockedAmount   | string                                                                            | Locked amount in the wallet                                                                                               |
| status         | [ConfigChangeRequestStatus](/reference/general-objects#configchangerequeststatus) | Status of the Internal Wallet                                                                                             |
| activationTime | string                                                                            | The time the wallet will be activated if wallet activation is postponed according to the workspace definition             |
| address        | string                                                                            | The address of the wallet                                                                                                 |
| tag            | string                                                                            | Used as destination tag for XRP; `memo` for ATOM, EOS, HBAR, LUNA, LUNC, XDB, XEM; `memo_text` for XLM; `notes` for ALGO. |

***

## ExternalWalletAsset

| Parameter      | Type                                                                              | Description                                                                                                                                                            |
| -------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id             | string                                                                            | The ID of the asset                                                                                                                                                    |
| status         | [ConfigChangeRequestStatus](/reference/general-objects#configchangerequeststatus) | Status of the External Wallet                                                                                                                                          |
| activationTime | string                                                                            | The time the wallet will be activated if wallet activation is postponed according to the workspace definition                                                          |
| address        | string                                                                            | The address of the wallet                                                                                                                                              |
| tag            | string                                                                            | Used as destination tag for XRP; `memo` for ATOM, EOS, HBAR, LUNA, LUNC, XDB, XEM; `memo_text` for XLM; `notes` for ALGO; bank transfer description for fiat providers |

***

## UnmanagedWallet

| Parameter     | Type                                 | Description                                                                            |
| ------------- | ------------------------------------ | -------------------------------------------------------------------------------------- |
| id            | string                               | The ID of the Unmanaged Wallet                                                         |
| name          | string                               | Name of the Wallet Container                                                           |
| customerRefId | string                               | \[optional] The ID for AML providers to associate the owner of funds with transactions |
| assets        | Array of [WalletAsset](#walletasset) | An array of the assets available in the unmanaged wallet                               |

***

## ExternalWallet

| Parameter     | Type                                                 | Description                                                                            |
| ------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------- |
| id            | string                                               | The ID of the Unmanaged Wallet                                                         |
| name          | string                                               | Name of the Wallet Container                                                           |
| customerRefId | string                                               | \[optional] The ID for AML providers to associate the owner of funds with transactions |
| assets        | Array of [ExternalWalletAsset](#externalwalletasset) | An array of the assets available in the external wallet                                |


# iOS SDK errors
Source: https://developers.fireblocks.com/reference/ios-sdk-errors



| Error Code | Error Message                                                                    |
| :--------- | :------------------------------------------------------------------------------- |
| 100        | Unknown error                                                                    |
| 102        | Failed to download certificates                                                  |
| 106        | Missing algorithms                                                               |
| 107        | Missing private keys                                                             |
| 108        | Failed to upload logs                                                            |
| 109        | Failed to send version                                                           |
| 111        | Maximum number of devices per wallet reached                                     |
| 200        | Timeout during key creation, didn't get startup message                          |
| 201        | Unknown algorithm                                                                |
| 202        | Failed to generate key, key exists in server but not on the device               |
| 203        | Timeout during key creation                                                      |
| 204        | Failed to send public key                                                        |
| 205        | Failed to request key                                                            |
| 206        | Failed to enroll player                                                          |
| 207        | Failed to create key                                                             |
| 300        | Failed to request end-user takeover                                              |
| 301        | Failed to takeover keys                                                          |
| 302        | Timeout during key takeover                                                      |
| 400        | Failed to export keys                                                            |
| 401        | Missing public keys                                                              |
| 402        | Missing public key                                                               |
| 403        | Failed to derive asset key                                                       |
| 404        | Missing cloud private keys                                                       |
| 405        | Missing chain code                                                               |
| 406        | Missing private key                                                              |
| 407        | Failed to export key, recovered PublicKey is not equal to the original PublicKey |
| 408        | Failed to export key                                                             |
| 500        | Failed to sign transaction, unknown txId                                         |
| 501        | Error during transaction signing creation, didn't get start signing message      |
| 502        | Failed to sign transaction                                                       |
| 503        | Timeout during transaction signing                                               |
| 600        | Backup not available                                                             |
| 601        | Failed to recover keys                                                           |
| 603        | The provided passphrase is wrong                                                 |
| 700        | Failed to get key IDs                                                            |
| 701        | Missing key IDs in server for backup                                             |
| 702        | We have a discrepancy between valid key IDs between server and client            |
| 703        | Failed to backup keys, missing keys                                              |
| 704        | Failed to backup key                                                             |
| 705        | Invalid passphrase error                                                         |
| 800        | Invalid add device setup data                                                    |
| 900        | Failed to join wallet                                                            |
| 901        | Timeout during join wallet                                                       |
| 902        | Join wallet was stopped                                                          |
| 1000       | Failed to approve join wallet                                                    |
| 1001       | Timeout during approve join wallet                                               |
| 1002       | No keys to provision                                                             |
| 1003       | Approve join wallet was stopped                                                  |


# Issue New ERC20F Tokens
Source: https://developers.fireblocks.com/reference/issue-new-erc-20f-tokens



This guide explains how to use the `/v1/tokenization/tokens` endpoint through the SDK to issue a new ERC20F token. This will allow you to deploy and link the token to an asset, enabling easy management of issuance, minting, and burning operations.

## What is ERC20F?

ERC20F is a fungible token reference implementation developed by Fireblocks. It builds upon the widely used ERC-20 token standard, with added functionality for upgradability and enhanced control over token operations. This implementation is designed to be flexible, allowing for token minting, burning, and secure integration within Fireblocks' ecosystem. It is optimized for compliance, making it ideal for organizations requiring scalable and customizable token management solutions.

It's important to note that the ERC20F token uses a proxy pattern, which decouples the state (in the proxy) from the
smart contract logic (referred to as `implementation` in this guide) to support upgradability. Read more about the upgradability features of this contract [here](https://support.fireblocks.io/hc/en-us/articles/14018887816476-Fireblocks-upgradeable-smart-contracts).

We built a contract template for ERC20F tokens that you can use to issue new tokens. To find more information about Templates, refer to the [Contract Template guide](/reference/upload-contract-template#what-are-contract-templates).

## Prerequisites

Before issuing a new ERC20F token using the Fireblocks SDK, ensure you know the following:

1. **Asset ID:** The `assetId` of the blockchain where the token will be deployed (e.g. ETH\_TEST5 for Sepolia). This is the Fireblocks ID of the gas token of the blockchain where the token will be deployed. (To get the asset ID, refer to this [assetId list](https://support.fireblocks.io/hc/en-us/articles/8993656344092-Supported-blockchain-networks))
2. **Vault Account:** The `vaultAccountId` that will deploy the token. Ensure the vault has sufficient native gas for transaction fees. You can retrieve the vaultAccountId from the Fireblocks console by checking the URL of the selected vault, e.g., `https://console.fireblocks.io/v2/accounts/vault/<vaultAccountId>`. For more details about Vault Accounts, refer to the [Create Vault Account guide](/reference/create-vault-account).
3. **Contract Template:** Ensure the contract template is uploaded, and you have the `templateId` from the template. for details. (For `ERC20F`, the contract template ID is `41c76f08-3144-4641-96c9-260c8fe846a7` for `Prod US` workspaces).
4. Ensure you have access to the `Fireblocks Smart Contracts package`, which includes the reference protocol contracts.

With these in place, you can use the Fireblocks SDK to issue a new token.

## Example: Issuing a New ERC20F Token

Here's an example of how to issue a new ERC20F token using the Fireblocks SDK:

### 1. Initialize the Fireblocks SDK

First, the Fireblocks SDK and initialize the SDK with your Fireblocks API key and private key:

```javascript theme={"system"}
import {
    Fireblocks,
    BasePath,
} from '@fireblocks/ts-sdk';

const privateKey = '...'; // Your Fireblocks API private key
const apiKey = '...'; // Your Fireblocks API key

const fireblocksSdk = new Fireblocks({
    apiKey,
    basePath: BasePath.US, // Use BasePath.EU for the EU region
    secretKey: privateKey,
});
```

### 2. Retrieve ERC20F Contract Template

We need to retrieve the ERC20F contract template using the `getContractTemplate` method:
For more information, refer to the [Get Contract Template API reference page](/reference/getcontracttemplatebyid).

```javascript theme={"system"}
const template = await fireblocksSdk.contractTemplates.getContractTemplate({contractTemplateId: '00000000-0000-0000-0000-000000000003'});
```

As part of the response, you'll receive the `implementationContractId` which is required for the next steps.

### 3. Retrieve Implementation Contract Address

To get the address of the implementation contract, you need to call the `getDeployedContracts` method:

This extra step is required only for templates of contracts that follow the proxy pattern (such as ERC20F).

```javascript theme={"system"}
    const contractDetails = await fireblocksSdk.deployedContracts.getDeployedContracts({
    baseAssetId: 'ETH_TEST5',
    contractTemplateId: 'YOUR_TEMPLATE_ID_HERE'
})
```

As part of the response, you'll receive the `contractAddress` which is required for the next step.

### 4. Issue New Token

To proceed with deploying the new token, you need to define the following deployment variables:

* `name`: The token name (e.g., "MyToken").
* `symbol`: The token symbol (e.g., "MTK").
* `defaultAdminAddress`: The address that will receive the DEFAULT\_ADMIN\_ROLE.
* `minterAddress`: The address that will receive the MINTER\_ROLE.
* `pauserAddress`: The address that will receive the PAUSER\_ROLE.

For more information about the roles, refer to the [Roles in Fireblocks smart contracts article](https://support.fireblocks.io/hc/en-us/articles/13926413716892-Roles-in-Fireblocks-smart-contracts).

Example:

```javascript theme={"system"}
const name = 'MyToken';
const symbol = 'MTK';
const defaultAdminAddress = '0x1234567890123456789012345678901234567890';
const minterAddress = '0x1234567890123456789012345678901234567890';
const pauserAddress = '0x1234567890123456789012345678901234567890';
```

It's important to recall that the ERC20F token uses a proxy pattern. This means that when deploying the token, you must provide both the implementation contract address and the encoded initialize function in the `constructorParams` field. The proxy will reference the implementation contract and use the initialize method to set up the token parameters.

Now let's issue the new token:

```javascript theme={"system"}
let deployRequest: CreateTokenRequestDto = {
    assetId: 'ETH_TEST5', // Fireblocks asset ID for Sepolia network
    vaultAccountId: '0',  // The vault account ID to manage the token
    createParams: {
        contractId: '41c76f08-3144-4641-96c9-260c8fe846a7', // The ERC20F contract template ID
        deployFunctionParams: [
            {
                name: 'implementation',
                type: 'address',
                internalType: 'address',
                value: 'implementationContractAddress', // Address of the implementation contract retrieved in Step 3
            },
            {
                "name": "_data",
                "type": "bytes",
                "functionValue": {
                    "name": "initialize",
                    "type": "function",
                    "inputs": [
                        {
                            "name": "_name",
                            "type": "string",
                            "internalType": "string",
                            "value": name // _name (e.g., 'MyToken')
                        },
                        {
                            "name": "_symbol",
                            "type": "string",
                            "internalType": "string",
                            "value": symbol // _symbol (e.g., 'MTK')
                        },
                        {
                            "name": "defaultAdmin",
                            "type": "address",
                            "internalType": "address",
                            "value": defaultAdminAddress // Address with DEFAULT_ADMIN_ROLE
                        },
                        {
                            "name": "minter",
                            "type": "address",
                            "internalType": "address",
                            "value": minterAddress // Address with MINTER_ROLE
                        },
                        {
                            "name": "pauser",
                            "type": "address",
                            "internalType": "address",
                            "value": pauserAddress // Address with PAUSER_ROLE
                        }
                    ],
                }
            }
        ],
    },
};

// Issue the token
const response = await fireblocksSdk.tokenization.issueNewToken({createTokenRequestDto: deployRequest});
console.log('New token issued:', response);
```

## Highlights:

* Ensure that `contractId` passed in the `createParams` corresponds to the template ID of the contract you want to deploy. In this case, it is the ERC20F contract template ID.
* Replace the example addresses with your own values for `defaultAdminAddress`, `minterAddress`, and `pauserAddress`.
* Ensure that the vault account has sufficient native gas for transaction fees.
* If you need to obtain the ABI for the `initialize` function of the proxy used in step 4, you can find it in the

  contract template:

  ```javascript theme={"system"}
    const implementationTemplate = await fireblocksSdk.contractTemplates.getContractTemplate({contractTemplateId: 'implementationContractId'});
  ```

## Further Reading

For more detailed information on API parameters and responses, including examples for using plain HTTP requests or in other programming languages, please have a look at the [Fireblocks API Reference](/reference/issuenewtoken).

For more specific guidance on ERC20F contract operations, refer to the [Operating the Upgradable ERC20F Contract Support Center Articles](https://support.fireblocks.io/hc/en-us/articles/13926379966876-Operating-the-Upgradeable-ERC-20F-contract).


# Issue new ERC721F/ERC1155F Tokens
Source: https://developers.fireblocks.com/reference/issue-new-erc721ferc1155f-tokens



This guide explains how to use the `v1/tokenization/collections` endpoint through the Fireblocks SDK to issue new ERC721F/ERC1155F tokens. It will walk you through the process that will result in deploying collection contracts, making them available in the Tokenization Engine. It will also show how to perform minting, burning, and other operations related to their respective standards.

## What are ERC721F and ERC1155F contracts?

ERC721F and ERC1155F are non-fungible and semi-fungible token reference implementations developed by Fireblocks. They build upon the widely used ERC-721 and ERC-1155 token standards. ERC721F and ERC1155F tokens can represent ownership of digital or physical assets. They are used in various applications such as digital art, collectibles, and gaming. These implementations are designed to be flexible, allowing for token minting, burning, and secure integration within Fireblocks' ecosystem. They are designed for compliance, making them ideal for organizations requiring scalable and customizable token management solutions.

## Why use Collections API?

The Collections API allows you to easily deploy mint, burn and manage non-fungible and semi-fungible tokens. It is a wrapper around the Tokenization API that enables you to handle operations related to ERC721F/ERC1155F tokens. This means the Collections API will deploy and link the NFT contract by leveraging the tokenization API, with additional helpers to manage the NFT metadata. Essentially, it's a convenience layer on top of the Tokenization API that abstracts the complexity of deploying and linking NFT contracts.

> **Note:**
>
> Collections API is only available for ERC721F and ERC1155F tokens.

## Prerequisites

Before issuing a new ERC721F/ERC1155F token using the Fireblocks SDK, ensure you know the following:

1. assetId: The Asset Id of the blockchain where the token will be deployed (e.g. ETH\_TEST5 for Sepolia). This is the Fireblocks ID of the gas token of the blockchain where the token will be deployed. (To get the asset ID, refer to this [assetId](https://support.fireblocks.io/hc/en-us/articles/8993656344092-Supported-blockchain-networks) list)
2. vaultAccountId: The Id of the Vault that will deploy the token. Ensure the vault has sufficient native gas for transaction fees. The vaultAccountId can be retrieved from the Fireblocks console by checking the URL of the selected vault, e.g., `https://console.fireblocks.io/v2/accounts/vault/<vaultAccountId>`. For more details about Vault Accounts, refer to the Create Vault Account [guide](/reference/create-vault-account).
3. Ensure you have access to the Fireblocks Smart Contracts package, which includes the reference protocol contracts. Contact your CSM if unsure if your workspace has this SKU.

## Example 1: Issuing a New NFT collection

Here's an example of how to issue a new ERC721F or ERC1155F token using the Fireblocks SDK:

### 1. Initialize the Fireblocks SDK

First, import the Fireblocks SDK and initialize it by providing your Fireblocks API key and private key:

```javascript theme={"system"}
import {
    Fireblocks,
    BasePath,
} from '@fireblocks/ts-sdk';

const privateKey = '...'; // Your Fireblocks API private key
const apiKey = '...'; // Your Fireblocks API key

const fireblocksSdk = new Fireblocks({
    apiKey,
    basePath: BasePath.US, // Use BasePath.EU for the EU region
    secretKey: privateKey,
});
```

### 2. Create a new Collection

To deploy a new ERC721F/ERC1155F collection contract, you need to know the following:

* `baseAssetId`: The assetId of the blockchain where the collection will be deployed (e.g. ETH\_TEST5 for Sepolia).
* `vaultAccountId`: The vaultAccountId of the vault that will deploy the token.
* `type`: The type of the collection, either `NON_FUNGIBLE_TOKEN` or `SEMI_FUNGIBLE_TOKEN`.
  * when type is `NON_FUNGIBLE_TOKEN` the collection will be an ERC721F contract.
  * when type is `SEMI_FUNGIBLE_TOKEN` the collection will be an ERC1155F contract.
* `name`: The name of the collection. This name will be stored on the smart contract.
* `symbol`: The symbol of the collection.
* `adminAddress`: The address that will receive admin roles on the contract. Ensure that it's an address you control.
* `displayName`: The display name of the collection. This name will be displayed in the Fireblocks console.

For the purpose of this example, we will create an ERC721F collection on the Ethereum Sepolia network.

```javascript theme={"system"}
let collectionRequest: CollectionDeployRequestDto = {
    baseAssetId: 'ETH_TEST5',
    vaultAccountId: '0',
    type: 'NON_FUNGIBLE_TOKEN',
    name: 'My Collection',
    symbol: 'MC',
    adminAddress: '0x5503766D27d1ED4525f5053222E18b29C38eDdB2',
    displayName: 'My Collection',
};

const collection = await fireblocksSdk.tokenization.createCollection({
			collectionDeployRequest: collectionRequest,
		});
```

This will return a collection object with the following properties:

* `id`: The token link id of the collection. Since collections are linked to Tokenization Engine just like fungible tokens deployed using the tokenization API, the collection will have a token link id.
* `status`: The token link status. Possible values are `PENDING`, `COMPLETED` and `FAILED` but, right after sending create collection request, status will be `PENDING`.
* `type`: The type of the collection, either `NON_FUNGIBLE_TOKEN` or `SEMI_FUNGIBLE_TOKEN`.
* `displayName`: The display name of the collection as it appears in the Fireblocks console.
* `tokenMetadata`: The metadata of the collection. For now, it will be empty. But once the deployment transaction is completed, and the collection is linked, the metadata will be updated with the contract address and other details. For more information, refer to the [Collection Metadata](/reference/issue-new-erc721ferc1155f-tokens#collection-metadata) section below.

> **Note:**
>
> The procedure for creating an ERC1155F collection is the same, only that the type should be changed to `SEMI_FUNGIBLE_TOKEN`.

#### Collection Metadata:

The token metadata can be one of the following:

* `ContractMetadataDto`: If the contract is a utility contract (i.e. any arbitrary contract).
* `AssetMetadataDto`: If the contract is a fungible token (i.e. ERC20).
* `CollectionMetadataDto`: If the contract is a non-fungible token (i.e. ERC721 or ERC1155).

Once the contract is deployed and the collection is linked. The `tokenMetadata` will assume a value of type `collectionMetadataDto`. This metadata object that holds the contract address and other details. This object will be stored on the Fireblocks database and it looks like this:

```json theme={"system"}
{
    name: "My Collection",
    symbol: "MC",
    standard: "ERC721F",
    blockchainDescriptor: "ETH",
    contractAddress: "0x5503766D27d1ED4525f5053222E18b29C38eDdB2",
}
```

Now that we have a token link with a pending status, we can poll the status of the token link to check if the collection is deployed and the linkage is complete. To do that we can use the `getLinkedCollections` method.

#### 2.1 Fetching a Collection

To fetch a collection, you need to know the id of the collection, which is the token link id of the linked token. In this example we will use the id of the collection we created in the previous step. If the id is not known, you can use the getLinkedCollections method, which will return a list of all linked collections. Then you can find and use the id of the collection you want to fetch.

```javascript theme={"system"}
const collectionId = collection.id; // collection object from the previous step
const fetchedCollection = await fireblocksSdk.tokenization.getCollectionById({ TokenIdParamDto: collectionId });
This will return a collection object with the same properties as mentioned in the previous step.
```

If you want to continue to mint an NFT, you can proceed to the next example below.

## Example 2: Minting an NFT

To mint an NFT, the caller must have the `MINTER_ROLE` role on the collection contract. If the collection was deployed through Collections API, the `MINTER_ROLE` role is assigned to the adminAddress that was provided when creating the collection. You also need to perform two steps mentioned in Issuing a New NFT collection example above.

> **Note:**
>
> If you wish to use a different address to mint tokens, you can assign the `MINTER_ROLE` role to the desired address. The process is similar to the one described in the [Assigning Roles](/reference/setting-up-roles-in-erc20f-tokens#3-grant-role-to-address) guide for ERC20F.

### 3. Minting an NFT

To mint an NFT, you need to know the following:

* `vaultAccountId`: The vaultAccountId that will mint the token. Make sure this vault has enough native gas tokens for the transaction fees and the MINTER\_ROLE role on the smart contract.
* `to`: The address that will receive the minted token.
* `tokenId`: The id of the token to mint. This id must be unique within the collection. For this field, it is recommended to have a numerical format and in sequential order.
* `amount`: (Optional) The amount of the token to mint. For ERC721F, amount is ignored. For ERC1155F, the amount should be 1 or greater.
* `metadataURI`: (Optional) The metadata URI of the token. This URI will be stored on the smart contract and can be used to fetch the metadata of the token. This URL is usually an IPFS URL.
* `metadata`: (Optional) The metadata of the token. This metadata object will be uploaded to IPFS and the URI will be stored on the smart contract. For detailed information about the metadata, refer to the [NFT metadata](/reference/issue-new-erc721ferc1155f-tokens#nft-metadata) section below.

#### NFT Metadata:

The metadata object should have the following properties:

* `name`: The name of the token.
* `description`: The description of the token.
* `image`: (Optional) The image of the token. This should be a URL to the image of the token. (e.g. [https://some\\\_domain.com/image\\\_filepath](https://some\\_domain.com/image\\_filepath)).
* `animation`: (Optional) The animation of the token. This should be a URL to the animation of the token. (e.g. [https://some\\\_domain.com/animation\\\_filepath](https://some\\_domain.com/animation\\_filepath)).
* `external_url`: (Optional) The external URL of the token. This should be a URL to the token's external page. (e.g. [https://some\\\_domain.com/token\\\_page](https://some\\_domain.com/token\\_page)).
* `attributes`: (Optional) The attributes of the token. The token can have many attributes or traits depending on the use case. This should be an array of objects, each object should have the following properties:
* `trait_type`: The trait type of the attribute. (e.g. rarity).
* `value`: The value of the attribute. (e.g. common, legendary).
* `display_type`: (Optional) The display type of the attribute. This describes how would you like the trait to be displayed (e.g. number, date).

Here is an example of a metadata object:

```json theme={"system"}
{
    name: "My Token",
    description: "This is my token",
    image: "https\://some_domain.com/image_filepath",
    animation: "https\://some_domain.com/animation_filepath",
    external_url: "https\://some_domain.com/token_page",
    attributes: [
        {
            trait_type: "rarity",
            value: "common",
            display_type: "string"
        },
        {
            trait_type: "level",
            value: 1,
            display_type: "number"
        }
    ]
}
```

**What if I don't want to upload images and animations to a hosted server?**

If you don't want to upload images and animations to a hosted server, you can encode the image and animation files to base64 and pass them in the metadata object. Fireblocks will upload the metadata object containing base64 content to IPFS. This can be done as follows for an image in PNG format:

```javascript theme={"system"}
const image = fs.readFileSync('path/to/fileimage.png').toString('base64');

const metadata = {
    name: "My Token",
    description: "This is my token",
    image: `data:image/png;base64,${image}`,
    attributes: [
        {
            trait_type: "rarity",
            value: "common",
            display_type: "string"
        },
        {
            trait_type: "level",
            value: 1,
            display_type: "number"
        }
    ]
}
```

Once you have the metadata object, you can pass it to the metadata field in the mint request.

For this example, we assume that the metadata is already uploaded to IPFS and we have the URI of the metadata. We are also minting an ERC721F token, so we will not use the amount field. If you are minting an ERC1155F token, you can set the amount field to the desired amount.

> **Caution:**
>
> Make sure to use either `metadataURI` or `metadata` - not both. If you use both metadataURI and metadata the request will fail.

```javascript theme={"system"}
let mintRequest: CollectionMintRequestDto = {
    vaultAccountId: 'vaultAccountId',
    to: '0x5503766D27d1ED4525f5053222E18b29C38eDdB2',
    tokenId: 1,
    metadataURI: 'ipfs://QmP4P6f7mDHzikhdwLBVSCxCPEgmjwcWSVBHbtSyfBYzBC',
};
const collectionId: CollectionIdParamDto = { id: collection.id }; // collection object from the previous step

const txId = await fireblocksSdk.tokenization.mintCollectionToken({
			colletionId,
			collectionMintRequest: mintRequest,
		});
```

This will return the Fireblocks transaction id of the Mint transaction.

#### 3.1. Fetching the minted token

To fetch the minted token, you need to know the tokenId of the token. In this example we will use the tokenId we minted in the previous step. To fetch the token you can use the fetchCollectionTokenDetails method that will return the nft token object.

```javascript theme={"system"}
const tokenId = mintRequest.tokenId; // tokenId from the mint request
const fetchedToken = await fireblocksSdk.tokenization.fetchCollectionTokenDetails(collectionId, tokenId);
```

This will return a token object with the following properties:

* `tokenId`: The id of the token.
* `metadataURI`: The metadata URI of the token.
* `totalSupply`: The total supply of the token.

If you would like to continue learn how to burn NFT, you can proceed to the next example.

## Example 3: Burning an NFT

To burn an NFT, the caller must have the `BURNER_ROLE` role on the collection contract. The `BURNER_ROLE` role is not assigned to anyone by default. You also need to make sure you have a collection of NFTs and an NFT to burn which described in example 1 and 2. To assign the `BURNER_ROLE` role to an address, you can use the `grantRole` method. For more information, refer to the [Assigning Roles](/reference/setting-up-roles-in-erc20f-tokens#3-grant-role-to-address) guide for ERC20F. The process is the same for ERC721F/ERC1155F.

### 4. Burning an NFT

To burn an NFT, you need to know the following:

* `collectionId`: The id of the collection.
* `vaultAccountId`: The vaultAccountId that will burn the token. Make sure this vault has enough native gas for the transaction fees and the BURNER\_ROLE role on the smart contract.
* `tokenId`: The id of the token to burn.
* `amount`: (Optional) The amount of the token to burn. For ERC721F, amount is ignored. For ERC1155F, amount should be 1 or greater.

For this example, we will burn an ERC721F token, so we will not use the amount field. If you are burning an ERC1155F token, you can set the amount field to the desired amount.

```javascript theme={"system"}
let burnRequest: CollectionBurnRequestDto = {
    vaultAccountId: 'vaultAccountId',
    tokenId: 1,
};
let collectionId = { id: collection.id }: CollectionIdParamDto; // collection object from the previous step

const txId = await fireblocksSdk.tokenization.burnCollectionToken({
            colletionId,
            collectionBurnRequestDto: burnRequest,
        });
```

This will return the Fireblocks transaction id of the Burn transaction.

## Summary

The Collections API is a high-level API provides a simple interface to manage NFTs. Without collections API, you would need to:

1. Fetch the templates from `getContractTemplates`.
2. Find the template (e.g. ERC721F) from the list.
3. Fetch the template using `getContractTemplate`.
4. Deploy the contract.
5. Mint the NFT.

With collections API all of that is abstracted into the purpose-driven methods explained in this guide.

## Further Reading

For more detailed information on API parameters and responses, including examples for using plain HTTP requests or in other programming languages, please have a look at the [Fireblocks API Reference](/reference/createnewcollection).

For more specific guidance on ERC721F and ERC1155F contracts operations, refer to the \[Operating the Upgradable ERC721F Contract Support Center Articles]\(Operating the Upgradable ERC721F Contract Support Center Articles) guides.


# Java SDK
Source: https://developers.fireblocks.com/reference/java-sdk



<Note>
  **Install the Fireblocks Documentation MCP first.** Whether you're using an AI assistant or not, this makes it easy to search, reference, and keep your Fireblocks work grounded in the official docs. The setup steps are in [Getting Started](/docs/quickstart).
</Note>

# Overview

Java developers can use [the official Fireblocks Java SDK](https://github.com/fireblocks/java-sdk) to interact with the Fireblocks API. Instructions for setup and usage can be found in the repo's README.md file.

# Using the Fireblocks Java SDK

Building the API client library requires:

1. Java 11+
2. Maven/Gradle

## Installation

To install the API client library to your local Maven repository, execute:

```bash theme={"system"}
mvn clean install
```

To deploy it to a remote Maven repository instead, configure the settings of the repository and execute:

```bash theme={"system"}
mvn clean deploy
```

Refer to the [OSSRH Guide](http://central.sonatype.org/pages/ossrh-guide.html) for more information.

### Maven users

Add this dependency to your project's POM:

```xml theme={"system"}
<dependency>
  <groupId>com.fireblocks.sdk`</groupId>`
  <artifactId>fireblocks-sdk`</artifactId>`
  <version>0.0.0`</version>`
  <scope>compile`</scope>`
`</dependency>`
```

### Gradle users

Add this dependency to your project's build file:

```groovy theme={"system"}
compile "com.fireblocks.sdk:fireblocks-sdk:0.0.0"
```

### Others

At first, generate the JAR by executing:

```bash theme={"system"}
mvn clean package
```

Then manually install the following JARs:

* `target/fireblocks-sdk-0.0.0.jar`
* `target/lib/*.jar`

## Getting Started

### Initiate Fireblocks Client

You can initialize the Fireblocks SDK in two ways: either by setting environment variables or by providing the parameters directly:

**Using Environment Variables**
You can initialize the SDK using environment variables from your .env file or by setting them programmatically.

> **Use the correct API Base URL**
>
> In the following script, make sure you're using the correct value for `FIREBLOCKS_BASE_PATH` for your environment:
>
> * For Sandbox workspaces: `https://sandbox-api.fireblocks.io`
> * For US Mainnet or Testnet workspaces: `https://api.fireblocks.io`
> * For EU Mainnet or Testnet workspaces: `https://eu-api.fireblocks.io`
> * For EU2 Mainnet or Testnet workspaces: `https://eu2-api.fireblocks.io`
>
> [Learn more about workspace differences](doc:workspace-environments).

Use bash commands to set environment variables:

```bash theme={"system"}
export FIREBLOCKS_BASE_PATH="https://sandbox-api.fireblocks.io/v1"
export FIREBLOCKS_API_KEY="my-api-key"
export FIREBLOCKS_SECRET_KEY="my-secret-key"
```

Execute the following Java code:

```java theme={"system"}
import com.fireblocks.sdk.Fireblocks;
import com.fireblocks.sdk.ConfigurationOptions;

ConfigurationOptions configurationOptions = new ConfigurationOptions();
Fireblocks fireblocks = new Fireblocks(configurationOptions);
```

**Providing Local Variables**
Alternatively, you can directly pass the required parameters when initializing the Fireblocks API instance:

```java theme={"system"}
import com.fireblocks.sdk.BasePath;
import com.fireblocks.sdk.Fireblocks;
import com.fireblocks.sdk.ConfigurationOptions;

ConfigurationOptions configurationOptions = new ConfigurationOptions()
    .basePath(BasePath.Sandbox)
    .apiKey("my-api-key")
    .secretKey("my-secret-key");
Fireblocks fireblocks = new Fireblocks(configurationOptions);
```

## Examples

### Creating a Vault Account

```java theme={"system"}
CreateVaultAccountRequest request = new CreateVaultAccountRequest().name("My Vault Account");
String idempotencyKey = Integer.toString(new Random().nextInt()); // String | A unique identifier for the request. If the request is sent multiple times with the same idempotency key, the server will return the same response as the first request. The idempotency key is valid for 24 hours.
// Async request
CompletableFuture<VaultAccount> response = fireblocks.vaults().createVaultAccount(request, idempotencyKey);
// Waiting for the request
VaultAccount vaultAccount = response.get();
```

### Retrieving Vault Accounts

```java theme={"system"}
BigDecimal limit = new BigDecimal(10);
CompletableFuture<VaultAccountsPagedResponse> response = fireblocks.vaults().getPagedVaultAccounts(null, null, null, null, null, null, null, limit);
VaultAccountsPagedResponse vaultAccountsPagedResponse = response.get();
```

### Creating a Transaction

```java theme={"system"}
TransactionRequest transactionRequest = new TransactionRequest()
    .operation(TransactionOperation.TRANSFER)
    .source(new TransferPeerPath()
        .type(TransferPeerPath.TypeEnum.VAULT_ACCOUNT)
        .id("0"))
    .destination(new DestinationTransferPeerPath()
        .type(DestinationTransferPeerPath.TypeEnum.VAULT_ACCOUNT)
        .id("1"))
    .amount(new TransactionRequestAmount("0.001"))
    .assetId("ETH_TEST3"); // Ethereum Goerli testnet
    .note("My first Java transaction!");
String idempotencyKey = Integer.toString(new Random().nextInt()); // String | A unique identifier for the request. If the request is sent multiple times with the same idempotency key, the server will return the same response as the first request. The idempotency key is valid for 24 hours.
CompletableFuture<CreateTransactionResponse> response = fireblocks.transactions().createTransaction(transactionRequest, null, idempotencyKey);
CreateTransactionResponse transactionResponse = response.get();
String txId = transactionResponse.getId();
```


# JavaScript SDK errors
Source: https://developers.fireblocks.com/reference/javascript-sdk-errors



| Error Code | Error Message                            |
| :--------- | :--------------------------------------- |
| 100        | UNKNOWN\_ERROR                           |
| 101        | PROCESS\_ALREADY\_RUNNING                |
| 102        | INVALID\_CERTIFICATE                     |
| 103        | INVALID\_MPC\_MESSAGE                    |
| 104        | FAILED\_MPC\_BROADCAST                   |
| 105        | UNEXPECTED\_MPC\_MESSAGE                 |
| 106        | MISSING\_ALGORITHMS                      |
| 107        | MISSING\_PRIVATE\_KEYS                   |
| 108        | INCOMPLETE\_DEVICE                       |
| 109        | INSTANCE\_ALREADY\_INITIALIZED           |
| 110        | INVALID\_PHYSICAL\_DEVICE\_ID            |
| 111        | MAX\_DEVICES\_PER\_WALLET\_REACHED       |
| 112        | UNKNOWN\_RESPONSE\_FROM\_MESSAGEHANDLER  |
| 113        | API\_CALL\_FAILED                        |
| 200        | NO\_FIRST\_MESSAGE\_TIMEOUT              |
| 201        | UNKNOWN\_ALGORITHM                       |
| 202        | MISSING\_KEY\_ON\_DEVICE                 |
| 203        | KEY\_CREATION\_TIMEOUT                   |
| 204        | FAILED\_TO\_SEND\_PUBLIC\_KEY            |
| 205        | FAILED\_TO\_REQUEST\_KEY                 |
| 206        | FAILED\_TO\_ENROLL\_PLAYER               |
| 207        | FAILED\_TO\_CREATE\_KEY                  |
| 208        | FAILED\_TO\_CONFIRM\_KEY                 |
| 300        | FAILED\_TO\_REQUEST\_END\_USER\_TAKEOVER |
| 301        | FAILED\_TO\_TAKEOVER\_KEYS               |
| 302        | KEY\_TAKEOVER\_TIMEOUT                   |
| 400        | FAILED\_TO\_EXPORT\_KEYS                 |
| 401        | MISSING\_PUBLIC\_KEYS                    |
| 402        | MISSING\_PUBLIC\_KEY                     |
| 403        | FAILED\_TO\_DERIVE\_ASSET\_KEY           |
| 404        | MISSING\_CLOUD\_PRIVATE\_KEYS            |
| 405        | MISSING\_CHAIN\_CODE                     |
| 406        | MISSING\_PRIVATE\_KEY                    |
| 407        | PUBLIC\_KEYS\_DISCREPANCY\_ERROR         |
| 408        | FAILED\_TO\_EXPORT\_KEY                  |
| 500        | UNKNOWN\_TX\_ID                          |
| 501        | NO\_FIRST\_TX\_SIGNING\_MESSAGE          |
| 502        | FAILED\_TO\_SIGN\_TRANSACTION            |
| 503        | TRANSACTION\_SIGNING\_TIMEOUT            |
| 504        | SIGNING\_STOPPED                         |
| 505        | TRANSACTION\_STATUS\_FAILURE             |
| 600        | BACKUP\_NOT\_AVAILABLE\_ERROR            |
| 601        | FAILED\_TO\_RECOVER\_KEYS                |
| 602        | UNKNOWN\_BACKUP\_ALGORITHM               |
| 603        | WRONG\_RECOVERY\_PASSPHRASE              |
| 700        | FAILED\_TO\_GET\_KEY\_IDS                |
| 701        | MISSING\_KEY\_IDS\_FOR\_BACKUP           |
| 702        | KEYS\_DISCREPANCY\_BACKUP\_ERROR         |
| 703        | MISSING\_KEYS\_BACKUP\_ERROR             |
| 704        | FAILED\_TO\_BACKUP\_KEY                  |
| 705        | INVALID\_PASSPHRASE\_ERROR               |
| 706        | INCOMPLETE\_BACKUP                       |
| 800        | INVALID\_ADD\_DEVICE\_SETUP\_DATA        |
| 801        | MPC\_SETUP\_ALREADY\_STARTED             |
| 900        | FAILED\_TO\_JOIN\_WALLET                 |
| 901        | JOIN\_WALLET\_TIMEOUT                    |
| 902        | JOIN\_WALLET\_STOPPED                    |
| 1000       | FAILED\_TO\_APPROVE\_JOIN\_WALLET        |
| 1001       | APPROVE\_JOIN\_WALLET\_TIMEOUT           |
| 1002       | NO\_KEYS\_TO\_PROVISION                  |
| 1003       | APPROVE\_JOIN\_WALLET\_STOPPED           |


# JS SDK (Legacy)
Source: https://developers.fireblocks.com/reference/js-sdk-legacy



> **We released our official TypeScript SDK! Make sure to check it out in here**

# Overview

A JavaScript or Typescript developer can use the Fireblocks API in 2 different ways:

1. [The Fireblocks JavaScript SDK.](https://github.com/fireblocks/fireblocks-sdk-js)
2. A standard HTTP library, such as [Axios.](https://axios-http.com/docs/intro)

In this guide, you'll set up the Fireblocks SDK and see an example of non-SDK usage (including signing the JWT token).

Additionally if you are developing on EVM chains - you might be using some of the familiar libraries, such as `web3.js` or `ethers.js` - Fireblocks is well intergrated into these libraries as described in the [Ethereum Development](doc:ethereum-development).

# Using the Fireblocks SDK

## Install Node v16 or newer

The Fireblocks JavaScript SDK requires **Node v16 or newer**. You can check which version of Node you already have installed by running the following command.

`node -v`

[Learn how to install or update Node to a newer version.](https://nodejs.org/en/download/)

## Install fireblocks-sdk

The Fireblocks JavaScript SDK is open-source and hosted on both GitHub and PIP, the official package repository.

* **Source code:** [https://github.com/fireblocks/fireblocks-sdk-js](https://github.com/fireblocks/fireblocks-sdk-js)
* **JavaScript Package:** [https://www.npmjs.com/package/fireblocks-sdk](https://www.npmjs.com/package/fireblocks-sdk)

Installing the latest SDK is easy with `npm`:

`npm install fireblocks-sdk`

## Your First Fireblocks JavaScript script!

Now that you're set-up, run a quick check for the API. The script will query existing vaults, create a new vault and then query again to see that the vaults were created.

This Axios-based implementation will require some library dependencies:

* [Axios](https://www.npmjs.com/package/axios)
* [jsonwebtoken](https://www.npmjs.com/package/jsonwebtoken)

> **Use the correct API Base URL**
>
> In the following script, make sure you're using the correct value for `baseUrl` for your environment:
>
> * For Sandbox workspaces: `https://sandbox-api.fireblocks.io`
> * For Mainnet or Testnet workspaces: `https://api.fireblocks.io`
>
> [Learn more about workspace differences](doc:workspace-environments).

```javascript theme={"system"}
const fs = require('fs');
const path = require('path');
const { FireblocksSDK } = require('fireblocks-sdk');
const { exit } = require('process');
const { inspect } = require('util');

const apiSecret = fs.readFileSync(path.resolve("`</path/to/fireblocks_secret.key>`"), "utf8");
const apiKey = "<your-api-key-here>"
// Choose the right api url for your workspace type
const baseUrl = "https://sandbox-api.fireblocks.io";
const fireblocks = new FireblocksSDK(apiSecret, apiKey, baseUrl);

(async () => {

    // Print vaults before creation
    let vaultAccounts = await fireblocks.getVaultAccountsWithPageInfo({});
    console.log(inspect(vaultAccounts, false, null, true));

    // Create vault account
    const vaultCreation = await fireblocks.createVaultAccount("QuickStart_Vault");
    console.log(inspect(vaultCreation, false, null, true));

    // Print vaults after creation
    vaultAccounts = await fireblocks.getVaultAccountsWithPageInfo({});
    console.log(inspect(vaultAccounts, false, null, true));

})().catch((e)=>{
    console.error(`Failed: ${e}`);
    exit(-1);
})
```

```javascript theme={"system"}
const fs = require('fs');
const path = require('path');
const { FireblocksSDK } = require('fireblocks-sdk');
const { exit } = require('process');
const { inspect } = require('util');
const axios = require('axios');
const { sign } = require('jsonwebtoken');
const { v4: uuid } = require('uuid');
const crypto = require('crypto');

const apiSecret = fs.readFileSync(path.resolve("`</path/to/fireblocks_secret.key>`"), "utf8");
const apiKey = "<your-api-key-here>"
// Choose the right api url for your workspace type
const baseUrl = "https://sandbox-api.fireblocks.io";
const fireblocks = new FireblocksSDK(apiSecret, apiKey, baseUrl);

class FireblocksRequestHandler{

    baseUrl;
    apiSecret;
    apiKey;

    constructor(apiSecret, apiKey, baseUrl = "https://api.fireblocks.io"){
        this.baseUrl = baseUrl;
        this.apiSecret = apiSecret;
        this.apiKey = apiKey;
    }

    async post(path, data){
        const jwt = this.jwtSign(path,data);
        return (await this.req(jwt, path, data, "POST"));
    }

    async get(path) {
        const jwt = this.jwtSign(path);
        return (await this.req(jwt, path, undefined, "GET"));
    }

    async req(jwt, path, data, method){
        const resp = await axios({
            url: `${this.baseUrl}${path}`,
            method: method,
            data,
            headers:{
                "X-API-Key":this.apiKey,
                "Authorization": `Bearer ${jwt}`
            }
        });
        return resp.data;
    }

    jwtSign(path, data){
        const token = sign({
            uri: path,
            nonce: uuid(),
            iat: Math.floor(Date.now() / 1000),
            exp: Math.floor(Date.now() / 1000) + 55,
            sub: this.apiKey,
            bodyHash: crypto.createHash("sha256").update(JSON.stringify(data || "")).digest().toString("hex")
        }, this.apiSecret, {algorithm: "RS256"});
        return token;
    }

}

(async () => {

    const requestHandler = new FireblocksRequestHandler(apiSecret, apiKey);

    // Print vaults before creation
    let vaults = await requestHandler.get("/v1/vault/accounts_paged");
    console.log(inspect(vaults, false, null, true));

    // Create vault account
    const vaultCreation = await requestHandler.post("/v1/vault/accounts", {"name":"QuickStart_Vault"});
    console.log(inspect(vaultCreation, false, null, true));

    // Print vaults after creation
    vaults = await requestHandler.get("/v1/vault/accounts_paged");
    console.log(inspect(vaults, false, null, true));

})().catch((e)=>{
    console.error(`Failed: ${e}`);
    exit(-1);
});
```


# Launch Workflow Execution
Source: https://developers.fireblocks.com/reference/launch-workflow-execution



Once the WE is in **READY\_FOR\_LAUNCH** status, call the [POST /payments/workflow\_execution//actions/execute](/reference/launchflowexecution) endpoint.

The WE proceeds through the following statuses. These statuses will be applied to each WEO and the WE as a whole.

1. **EXECUTION\_IN\_PROGRESS:** The execution process has started.
2. **EXECUTION\_COMPLETED** or **EXECUTION\_FAILED:** The execution completed or failed. These are finite states.


# Mint an NFT
Source: https://developers.fireblocks.com/reference/mint-an-nft



First, upload an image of your newly almost minted NFT. The minting function will receive it as one of its parameters.

> **Image hosting options**
>
> You can upload your selected image using any image-hosting site.
>
> While not covered in this guide, another option would be to use a system like [IPFS protocol](https://en.wikipedia.org/wiki/InterPlanetary_File_System) to store your image on-chain as a decentralized solution.

Then we call upon the function while passing these values with it.

| Parameter | Description                                                 |
| --------- | ----------------------------------------------------------- |
| `sender`  | The transaction signer address (your address)               |
| `tokenId` | The ID value of the newly minted NFT                        |
| `uri`     | The NFT's name, description, properties, and image location |

Now we will use Hardhat for the actual deployment. First, we need to make sure it is well set up as described in the [Fireblocks Hardhat Plugin](/reference/hardhat-plugin) guide and then we follow the steps described in this guide.

***

# Using Hardhat

> **Hardhat Runtime Environment required**
>
> We specifically require the Hardhat Runtime Environment.
>
> This is optional but useful for running the script in a standalone fashion through `node <script>`.
>
> You can also run a script with `npx hardhat run <script>`. If you run that script, Hardhat will compile your contracts, add the Hardhat Runtime Environment's members to the global scope, and execute the script.

In the scripts directory, create a new minting script titled: `scripts/mint.js`

```javascript theme={"system"}
const hre = require("hardhat");
const DatauriParser = require('datauri/parser');
const parser = new DatauriParser();

async function main() {
  const collectionAddress = "<CONTRACT_ADDRESS>";
  const signer = await hre.ethers.getSigner()
  const signerAdderss = await signer.getAddress()
  const nftContract = await hre.ethers.getContractAt("<COLLECTION_NAME>", collectionAddress, signer);
  const tokenData = {
    "name": "<NFT_NAME>",
    "image": "<IMAGE_URL>",
  }

  const tokenURI = parser.format('.json', JSON.stringify(tokenData)).content

  const tx = await nftContract.safeMint(signerAdderss, tokenURI);
  await tx.wait()

  console.log("A new NFT has been minted to:", signerAdderss);
  // console.log("tokenURI:", await nftContract.tokenURI(0))
}

// We recommend this pattern to be able to use async/await everywhere
// and properly handle errors.
main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});
```

***

# Verify your NFT

Now that you have your very own NFT collection, verify it on your Fireblocks workspace and the NFT marketplace [Rarible](https://rarible.com/).

## In your Fireblocks workspace

Log in to your Fireblocks Console to see whether the last transaction was completed successfully. It will be a **Contract Call** type.

## On Rarible

1. Visit Rarible using the following URL: [https://testnet.rarible.com/user/your\_wallet\_address/owned](https://testnet.rarible.com/user/your_wallet_address/owned)
2. Look for your NFT collection in your Rarible account.

> **Note**
>
> The `your_wallet_address` value is the address you used to receive the NFT (the vault that deployed the contract).


# Monitor the Gas Station
Source: https://developers.fireblocks.com/reference/monitor-the-gas-station



As your vault accounts get auto-fueled with gas assets transferred from the different Gas Station wallets, the level of each asset in your gas station is reduced and eventually requires additional funding.

* Check the asset balances in your Gas Station wallet regularly to ensure the wallet is funded properly. To add more funds, use the `fundGasStationWallet` function.
* Call the [Get an asset from an internal wallet endpoint](/api-reference/internal-wallets/get-an-asset-from-an-internal-wallet) to check your current Gas Station asset balances; for example, the code below retrieves the current ETH balance from the Gas Station wallet.

```javascript theme={"system"}
const getGasStationBalance = async (
  payload: ExternalWalletsApiGetExternalWalletAssetRequest,
): Promise<ExternalWalletAsset | undefined> => {
  try {
    const internalWalletAsset =
      await fireblocks.internalWallets.getInternalWalletAsset(payload);
    console.log(
      `Gas Station's ${payload.assetId} balance is: ${internalWalletAsset.data.balance}`,
    );
    return internalWalletAsset.data;
  } catch (e) {
    console.error(e);
  }
};

getGasStationBalance({
  walletId: "904c6da6-5aae-4280-bcb3-d0b1a36fc6e9", // update to your gas station internal wallet UUID
  assetId: "ETH", // update assetID
});
```

```javascript theme={"system"}
async function getGasStationBalance(walletId, assetId){
   const internalWalletAsset = await fireblocks.getInternalWalletAsset(walletId, assetId);
   console.log(JSON.stringify(internalWalletAsset.balance, null, 2));
}

getGasStationBalance("gasStationWalletUUID", "ETH");
```

```python theme={"system"}
def get_gas_station_balance(wallet_id: str, asset_id: str) -> str:
   print(fireblocks.get_internal_wallet_asset(wallet_id, asset_id)['balance'])

get_gas_station_balance("gas_station_wallet_uuid", "ETH")
```

* Monitor your transaction history for transactions that don't have enough gas to identify problems in this process. Learn more about [best practices for error handling with Fireblocks.](doc:error-handling)


# Monitoring Transaction Statuses
Source: https://developers.fireblocks.com/reference/monitoring-transaction-status



# Overview

Fireblocks posts several transaction statuses and sub-status messages while a transaction is progressing and based on the asset type. For example:

* UTXO-based assets: A notification of an incoming transaction is created when the transaction is present in the mempool.
* Account-based assets: A notification of an incoming transaction is created when the transaction is mined.

The best practice is to use webhooks to receive these status updates and populate your front-end or back-end as the transaction progresses.

***

# Webhook examples - best practice

If you've installed a webhook server inside your environment and configured it in your workspace, following the [Webhooks guide](/reference/configure-webhook-urls) , you'll now receive push notifications for transactions created or other workspace notifications.

On your webhook server, you can trigger additional behaviors with the code you place for the response to the webhook event post message your server got, basing it on the Transaction ID.

Your webhook server notification includes the primary status of the transaction and its sub-status.

[See a full list of the transaction statuses and sub-statuses.](/reference/statuses)

## Basic example

The example below shows how the `app.post` function, which is a part of our basic example for a Webhooks server, responds to the Console with the transaction ID, status, and sub-status details received inside the Webhook.

```javascript theme={"system"}
app.post( '/', ( req, res ) => {
    console.log( '********************* received webhook ******************');
    console.log( 'Transaction ID:', req.body.data.id);
    console.log( 'Transaction Sub Status:', req.body.data.subStatus);
    console.log( 'Transaction Status:', req.body.data.status );
    res.sendStatus( 200 )
} );
```

```python theme={"system"}
class SimpleRequest:
  def on_post(self, req, resp):
    request = json.loads(req.body.decode("utf-8"))
    print("********************* received webhook ******************")
    print("Transaction ID:", request["id"])
    print("Transaction Sub Status:", request["subStatus"])
    print("Transaction Status:", request["status"])
    resp.status = falcon.HTTP_200

app.add_route('/', SimpleRequest())
```

### Act on transaction success example

The example below shows how the `app.post` function responds with a call to an example backend function to report the failure and provide the details around it.

```javascript theme={"system"}
app.post( '/', ( req, res ) => {
    console.log( '********************* received webhook ******************');
		 if (req.body.data.status === TransactionStatus.BLOCKED || tx.status === TransactionStatus.CANCELLED || tx.status === TransactionStatus.FAILED) {
            failedTx(req.body.data.id);
     }
    res.sendStatus( 200 )
} );
```

```python theme={"system"}
class SuccessfulRequest:
  def on_post(self, req, resp):
    request = json.loads(req.body.decode("utf-8"))
    if request["status"] in (TRANSACTION_STATUS_BLOCKED, TRANSACTION_STATUS_FAILED, TRANSACTION_STATUS_CANCELLED):
      failed_tx([request["id"])
    resp.status = falcon.HTTP_200

app.add_route('/', SuccessfulRequest())
```

### Act on transaction failure example

[See examples of transaction failures and how to handle them.](/reference/api-error-codes)

> **Learn more about Balance Validation in the following guide**

***

# Non-production monitoring example

If you have not yet configured a webhook and would like to monitor transaction status on your non-production environment, you can use the example below which regularly calls the Fireblocks [Find a specific transaction](/reference/gettransaction) endpoint to get the status.

The example below calls the `getTransactionById` function with the transaction ID as its parameter (`txId`) and continuously polls for status change in a fixed interval, returning an error if it is not finalized with the completed status.

```javascript theme={"system"}
const getTxStatus = async (
  txId: string,
): Promise<TransactionStateEnum | string> => {
  try {
    let response: FireblocksResponse<TransactionResponse> =
      await fireblocks.transactions.getTransaction({ txId });
    let tx: TransactionResponse = response.data;
    let messageToConsole: string = `Transaction ${tx.id} is currently at status - ${tx.status}`;

    if (!tx) {
      return "Transaction does not exist";
    }

    console.log(messageToConsole);
    while (tx.status !== TransactionStateEnum.Completed) {
      await new Promise((resolve) => setTimeout(resolve, 3000));

      response = await fireblocks.transactions.getTransaction({ txId });
      tx = response.data;

      switch (tx.status) {
        case TransactionStateEnum.Blocked:
        case TransactionStateEnum.Cancelled:
        case TransactionStateEnum.Failed:
        case TransactionStateEnum.Rejected:
          throw new Error(
            `Signing request failed/blocked/cancelled: Transaction: ${tx.id} status is ${tx.status}`,
          );
        default:
          console.log(messageToConsole);
          break;
      }
    }

    return tx.status;
  } catch (error) {
    throw error;
  }
};

getTxStatus("<SOME_TX_ID>");
```

```javascript theme={"system"}
async function getTxStatus(txId){
    let tx = await fireblocks.getTransactionById(txId);
    console.log('TX ' + tx.id + ' is currently at status - '+ tx.status);
    while (tx.status !== TransactionStatus.COMPLETED) {
        await new Promise(resolve => setTimeout(resolve, 3000));
        tx = await fireblocks.getTransactionById(txId);
        if (tx.status === TransactionStatus.BLOCKED || tx.status === TransactionStatus.CANCELLED || tx.status === TransactionStatus.FAILED) {
            throw new Error("Signing request failed.");
        }
        console.log('TX ' + tx.id + ' is currently at status - '+ tx.status);
    }
}
```

```python theme={"system"}
def get_tx_status(tx_id) -> dict:
   timeout = 0
   current_status = fireblocks.get_transaction_by_id(tx_id)[STATUS_KEY]
   while current_status not (TRANSACTION_STATUS_COMPLETED):
       print(f"TX [{tx_id}] is currently at status - {current_status} {'.' * (timeout % 3)}                ",
             end="\r")
       time.sleep(3)
       current_status = fireblocks.get_transaction_by_id(tx_id)[STATUS_KEY]
       timeout += 1
```

> **Rate limits with monitoring:**
>
> Rate limits can affect monitoring. Use webhooks whenever possible to minimize the number of API calls made against your rate limits. More information at [Working with Rate Limits](doc:rate-limits) .
>
> This method also allows you to scale monitoring for more transactions as you build your business, without affecting your ability to actually process more transactions.


# Network Connection Webhooks
Source: https://developers.fireblocks.com/reference/network-connection-webhooks



> **Deprecation notice**
>
> Webhooks v1 will be deprecated on **June 15th, 2026**. Please use the Developer Center in the Fireblocks Console to upgrade to Webhooks V2, which offers improved reliability, performance, and observability.

This page describes all events relating to Fireblocks Network connections that produce webhook notifications, and their associated data objects.

The `type` parameter is automatically set to the description name for the data objects below.

## Connection added

Notification is sent when a Fireblocks Network connection is added.

**Webhook data**

| Parameter | Type                                    | Description                            |
| --------- | --------------------------------------- | -------------------------------------- |
| type      | string                                  | NETWORK\_CONNECTION\_ADDED             |
| tenantId  | string                                  | Unique ID of your Fireblocks workspace |
| timestamp | number                                  | Timestamp in milliseconds              |
| data      | [NetworkConnection](#networkconnection) | Network connection details             |

***

### NetworkConnection

| Parameter     | Type                | Description                       |
| ------------- | ------------------- | --------------------------------- |
| id            | string              | The ID of the Network Connection. |
| localChannel  | [Channel](#Channel) | Local channel ID.                 |
| remoteChannel | [Channel](#Channel) | Remote channel ID.                |

### Channel

| Parameter | Type   | Description                        |
| --------- | ------ | ---------------------------------- |
| networkId | string | The 8-character ID of the channel. |
| name      | string | The name of the channel.           |


# Network Connection Objects
Source: https://developers.fireblocks.com/reference/network-objects



## NetworkConnectionResponse

| Parameter       | Type                                                              | Description                                    |
| --------------- | ----------------------------------------------------------------- | ---------------------------------------------- |
| id              | string                                                            | The ID of the Network Connection               |
| localNetworkId  | [NetworkId](#networkid)                                           | Local network ID                               |
| remoteNetworkId | [NetworkId](#networkid)                                           | Remote network ID                              |
| routingPolicy   | [NetworkConnectionRoutingPolicy](#networkconnectionroutingpolicy) | The routing policy for the network connection. |

***

## NetworkConnectionRoutingPolicy

| Parameter | Type                                                                                                                                                                               | Description                |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| crypto    | [CustomCryptoRoutingDest](#customcryptoroutingdest), [DefaultNetworkRoutingDest](#defaultnetworkroutingdest), or [NoneNetworkRoutingDest](ref:data-objects#nonenetworkroutingdest) | The crypto routing policy. |

***

## CustomCryptoRoutingDest

| Parameter | Type   | Description                                                                        |
| --------- | ------ | ---------------------------------------------------------------------------------- |
| scheme    | string | The network routing logic. Valid value: `CUSTOM`                                   |
| dstType   | string | The type of account the funds are being sent to. Valid values: `VAULT`, `EXCHANGE` |
| dstId     | string | The ID of the fiat account to which the funds are being sent.                      |

***

## CustomFiatRoutingDest

| Parameter | Type   | Description                                                                  |
| --------- | ------ | ---------------------------------------------------------------------------- |
| scheme    | string | The network routing logic. Valid value: `CUSTOM`                             |
| dstType   | string | The type of account the funds are being sent to. Valid value: `FIAT_ACCOUNT` |
| dstId     | string | The ID of the fiat account to which the funds are being sent.                |

***

## DefaultNetworkRoutingDest

| Parameter | Type   | Description                                               |
| --------- | ------ | --------------------------------------------------------- |
| scheme    | string | The default network routing logic. Valid value: `DEFAULT` |

***

## NoneNetworkRoutingDest

| Parameter | Type   | Description                                   |
| --------- | ------ | --------------------------------------------- |
| scheme    | string | No network routing logic. Valid value: `NONE` |

***

## NetworkId

| Parameter | Type   | Description                    |
| --------- | ------ | ------------------------------ |
| id        | string | 8 characters ID of the network |
| name      | string | The name of the network        |

***

## NetworkIdResponse

| Parameter      | Type                                              | Description                                    |
| -------------- | ------------------------------------------------- | ---------------------------------------------- |
| id             | string                                            | 8 characters ID of the network                 |
| name           | string                                            | The name of the network                        |
| routingPolicy  | [NetworkIdRoutingPolicy](#networkidroutingpolicy) | The routing policy for the network connection. |
| isDiscoverable | boolean                                           | Whether the specific network is discoverable.  |


# Python SDK
Source: https://developers.fireblocks.com/reference/new-python-sdk



<Note>
  **Install the Fireblocks Documentation MCP first.** Whether you're using an AI assistant or not, this makes it easy to search, reference, and keep your Fireblocks work grounded in the official docs. The setup steps are in [Getting Started](/docs/quickstart).
</Note>

# Overview

A Python developer can use the Fireblocks API easily with the official Python SDK:

* [The Fireblocks Python SDK.](https://github.com/fireblocks/py-sdk)

In this guide, you'll set up the Fireblocks Python SDK and see an example of a basic API script to create a vault and print its data.

Additionally if you are developing on EVM chains - you might be using some of the familiar library, such as `web3.py` - Fireblocks is well integrated into these libraries as described in the [Local JSON RPC guide](/reference/evm-local-json-rpc).

# Using the Fireblocks SDK

## Install Python 3.8 or newer

The Fireblocks Python SDK requires **Python 3.8 or newer**. You can check which version of Python you already have installed with the following command.

`python --version` or `python3 --version`

[Learn how to install or update Python to a newer version.](https://docs.python-guide.org/starting/installation/)

## Install py-sdk

The Fireblocks Python SDK is open-source and hosted on both GitHub and PIP, the official package repository.

* **Source code:** [Fireblocks GitHub](https://github.com/fireblocks/py-sdk)
* **Python Package:** [Pypi](https://pypi.org/project/fireblocks/)

Installing the latest SDK is easy with `pip`:

`pip install fireblocks`

## Your First Fireblocks Python script!

> **Use the correct API Base URL**
>
> Make sure you're using the correct value for the API base URL for your environment:
>
> ```
> from fireblocks.base_path import BasePath
> ```
>
> * For Sandbox workspaces: `BasePath.Sandbox`
> * For US Mainnet or Testnet workspaces: `BasePath.US`
> * For EU Mainnet or Testnet workspaces: `BasePath.EU`
> * For EU2 Mainnet or Testnet workspaces: `BasePath.EU2`

### Import

For this basic example, we should import the following from the fireblocks module:

```python theme={"system"}
from fireblocks.client import Fireblocks
from fireblocks.client_configuration import ClientConfiguration
from fireblocks.base_path import BasePath
from fireblocks.models.create_vault_account_request import CreateVaultAccountRequest
from pprint import pprint
```

### Load your API Secret and API key

```python theme={"system"}
from fireblocks.client import Fireblocks
from fireblocks.client_configuration import ClientConfiguration
from fireblocks.base_path import BasePath
from fireblocks.models.create_vault_account_request import CreateVaultAccountRequest
from pprint import pprint

my_api_key="your_api_key"
with open('your_secret_key_file_path', 'r') as file:
    secret_key_value = file.read()
```

### Build the configuration

```python theme={"system"}
from fireblocks.client import Fireblocks
from fireblocks.client_configuration import ClientConfiguration
from fireblocks.base_path import BasePath
from fireblocks.models.create_vault_account_request import CreateVaultAccountRequest
from pprint import pprint

my_api_key="your_api_key"
with open('your_secret_key_file_path', 'r') as file:
    secret_key_value = file.read()

configuration = ClientConfiguration(
        api_key=my_api_key,
        secret_key=secret_key_value,
        base_path=BasePath.US
)
```

### Create a new vault account

```python theme={"system"}
from fireblocks.client import Fireblocks
from fireblocks.client_configuration import ClientConfiguration
from fireblocks.base_path import BasePath
from fireblocks.models.create_vault_account_request import CreateVaultAccountRequest
from pprint import pprint

my_api_key="your_api_key"
with open('your_secret_key_file_path', 'r') as file:
    secret_key_value = file.read()

configuration = ClientConfiguration(
        api_key=my_api_key,
        secret_key=secret_key_value,
        base_path=BasePath.Sandbox
)

with Fireblocks(configuration) as fireblocks:
    create_vault_account_request: CreateVaultAccountRequest = CreateVaultAccountRequest(
                                    name='My First Vault Account',
                                    hidden_on_ui=False,
                                    auto_fuel=False
                                    )
    try:
        # Create a new vault account
        future = fireblocks.vaults.create_vault_account(create_vault_account_request=create_vault_account_request)
        api_response = future.result()  # Wait for the response
        print("The response of VaultsApi->create_vault_account:\n")
        pprint(api_response.data.to_json())
    except Exception as e:
        print("Exception when calling VaultsApi->create_vault_account: %s\n" % e)
```


# NFT Objects
Source: https://developers.fireblocks.com/reference/nft-objects



## MediaEntityResponse

| Parameter   | Type   | Description            |
| ----------- | ------ | ---------------------- |
| url         | string | Cached accessible URL. |
| contentType | string | Media Type.            |

***

## TokenCollectionResponse

| Parameter | Type   | Description                                 |
| --------- | ------ | ------------------------------------------- |
| id        | string | Unique token collection ID with Fireblocks. |
| name      | string | The display name of the token collection.   |
| symbol    | string | The ticker symbol for the token.            |

***

## TokenResponse

| Parameter            | Type                           | Description                                                                                     |
| -------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------- |
| id                   | string                         | Unique token ID with Fireblocks.                                                                |
| tokenId              | string                         | Token ID within the contract/collection.                                                        |
| standard             | string                         | ERC721 or ERC1155                                                                               |
| metadataURI          | string                         | URL to original token metadata JSON                                                             |
| media                | MediaEntityResponse object     | Media items extracted from metadata JSON                                                        |
| collection           | TokenCollectionResponse object | Parent collection information                                                                   |
| blockchainDescriptor | string                         | Blockchain descriptor filter. Available values: ETH, ETH\_TEST3, POLYGON, POLYGON\_TEST\_MUMBAI |
| description          | string                         | A summary of the token.                                                                         |
| name                 | string                         | The display name of the token.                                                                  |

***

## TokenOwnershipResponse

| Parameter            | Type                           | Description                                                                                     |
| -------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------- |
| id                   | string                         | Unique token ID with Fireblocks.                                                                |
| tokenId              | string                         | Token ID within the contract/collection.                                                        |
| standard             | string                         | ERC721 or ERC1155                                                                               |
| metadataURI          | string                         | URL to original token metadata JSON                                                             |
| media                | MediaEntityResponse object     | Media items extracted from metadata JSON                                                        |
| collection           | TokenCollectionResponse object | Parent collection information                                                                   |
| vaultAccountId       | string                         | The ID for the vault account that owns the token.                                               |
| balance              | number                         | Balance of vault token collection.                                                              |
| blockchainDescriptor | string                         | Blockchain descriptor filter. Available values: ETH, ETH\_TEST3, POLYGON, POLYGON\_TEST\_MUMBAI |
| description          | string                         | The description of the NFT                                                                      |
| name                 | string                         | The display name of the NFT                                                                     |


# NFT Webhooks
Source: https://developers.fireblocks.com/reference/nft-webhooks



> **Deprecation notice**
>
> Webhooks v1 will be deprecated on **June 15th, 2026**. Please use the Developer Center in the Fireblocks Console to upgrade to Webhooks V2, which offers improved reliability, performance, and observability.

This page describes all events related to reporting balance changes for incoming and outgoing non-fungible token (NFT) transfers that produce webhook notifications and their associated data objects.

## Webhook payload

```typescript theme={"system"}
type: string, // NFT_BALANCE_CHANGED
tenantId: string,
timestamp: number,
data: {
  id: string, // unique web-hook id
  transaction?: TransactionObject, // when WH is from refresh call, this will be empty
  token: TokenObject,
  balance: BalanceObject, // current balance
}
```

## Data Objects

### TransactionObject

| Name        | Type   | Description                                                |
| ----------- | ------ | ---------------------------------------------------------- |
| id          | string | The Fireblocks transaction ID.                             |
| hash        | string | The hash of the transaction for the on-chain NFT transfer. |
| blockNumber | number | The transaction's block number.                            |

### TokenObject

| Name                 | Type               | Description                                         |
| -------------------- | ------------------ | --------------------------------------------------- |
| assetId              | string             | The identifier of the NFT asset.                    |
| blockchainDescriptor | string             | The descriptor for the specific blockchain network. |
| tokenId              | string             | The ID of the transferred token.                    |
| contractAddress      | string \[Optional] | The address of the NFT contract.                    |
| standard             | string \[Optional] | The NFT standard for the token.                     |

### BalanceObject

| Name        | Type                        | Description                                                          |
| ----------- | --------------------------- | -------------------------------------------------------------------- |
| owner       | [OwnerObject](#ownerobject) | The owner of the NFT with the changed balance.                       |
| outgoing    | boolean \[Optional]         | Indicates whether the transfer is outgoing from the vault.           |
| amount      | string \[Optional]          | The amount of the NFT transferred in the balance change.             |
| total       | string                      | The token balance. Represented as a decimal string.                  |
| blockNumber | number                      | The block number of the NFT when its token balance was last queried. |

### OwnerObject

| Name      | Type               | Description                                                            |
| --------- | ------------------ | ---------------------------------------------------------------------- |
| type      | PeerType           | The source of the transfer (e.g., VAULT\_ACCOUNT, INTERNAL\_WALLET).   |
| accountId | string             | The vault account ID.                                                  |
| walletId  | string \[Optional] | The Non-Custodial Wallet (NCW) ID.                                     |
| address   | string             | The owner's wallet address (i.e., the vault account ID or the NCW ID). |


# Off Exchange Webhooks
Source: https://developers.fireblocks.com/reference/off-exchange-webhooks



> **Deprecation notice**
>
> Webhooks v1 will be deprecated on **June 15th, 2026**. Please use the Developer Center in the Fireblocks Console to upgrade to Webhooks V2, which offers improved reliability, performance, and observability.

## Settlement Created

A notification is sent when a new settlement is initiated in the workspace.

| Parameter | Type                                                                    | Description                             |
| --------- | ----------------------------------------------------------------------- | --------------------------------------- |
| type      | string                                                                  | SETTLEMENT\_CREATED                     |
| tenantId  | string                                                                  | Unique ID of your Fireblocks workspace. |
| timestamp | number                                                                  | Timestamp in milliseconds.              |
| data      | [settlementDetails](/reference/off-exchange-webhooks#settlementdetails) | Settlement details.                     |

### settlementDetails

| Parameter                                                     | Type          | Description                                                                                                                   |
| ------------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| collateralAccountId                                           | string        | The collateral account ID.                                                                                                    |
| settlementId                                                  | string        | Unique settlement ID provided by Fireblocks.                                                                                  |
| isForceSettlement                                             | boolean       | A flag or condition that indicates whether a settlement should be forcibly executed, overriding normal settlement procedures. |
| exchangeAccountId                                             | string        | The ID of the exchange account.                                                                                               |
| [toExchange](/reference/off-exchange-webhooks#toexchange)     | data \[array] | All settlement transaction details are required to be sent to the exchange.                                                   |
| [toCollateral](/reference/off-exchange-webhooks#tocollateral) | data \[array] | All settlement transaction details are required to be sent to the collateral account.                                         |

### toExchange

| Parameter | Type   | Description                                                                                                                                                                                                                 |
| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| txId      | string | The transaction ID (within the main workspace).                                                                                                                                                                             |
| assetId   | string | The ID of the transaction's asset, applicable to `TRANSFER`, `MINT, BURN`, or `ENABLE_ASSET` operations. For a list of supported assets and their corresponding IDs, please refer [here](/reference/list-supported-assets). |
| amount    | string | The actual amount requested for transfer.                                                                                                                                                                                   |

### toCollateral

| Parameter | Type   | Description                                                                                                                                                                                                                  |
| --------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| txId      | string | The transaction ID (within the main workspace).                                                                                                                                                                              |
| assetId   | string | The ID of the transaction's asset, applicable to `TRANSFER`, `MINT, BURN`, or `ENABLE_ASSET` operations. For a list of supported assets and their corresponding IDs, please refer [here](/reference/list-supported-assets) . |
| amount    | string | The actual amount requested for transfer.                                                                                                                                                                                    |

### Sample Payload

```json theme={"system"}
{
	"type": "SETTLEMENT_CREATED",
	"tenantId": "your-tenant-id", (main tenant Id)
	"timestamp": 1633036800000,
	"settlementDetails": {
		"collateralAccountId": "collateral-account-id", COLLATERAL Account ID (not collateral ID)
		"settlementId": "settlement-id",
		"isForceSettlement": false,
		"toExchange": [
	{
		"txId": "transaction-id-1",
	 	"assetId": "asset-id-1",
	 	"amount": "1000",
	}],
	"toCollateral": [
	{
    "txId": "transaction-id-2",
    "assetId": "asset-id-2",
    "amount": "500",
  }]
 }
}
```


# Operational Guide for ERC20F Token
Source: https://developers.fireblocks.com/reference/operational-guide-for-erc20f-token



In this guide, we will walk you through how to operate an ERC20F token. There are five functions available:

1. Deploy
2. Mint
3. Burn
4. Grant Role
5. Revoke Role

This guide will show you how to interact with the token contract for three common operations: minting, burning, and granting roles. It will help you manage your token with Fireblocks tooling.

## Prerequisites

Before operating an ERC20F token using the Fireblocks SDK, ensure you know the following:

1. **ERC20F Contract Address**: The address of the ERC20F token contract you want to manage.

2. **Vault Account (for minting/burning):** The `vaultAccountId` will either mint or burn tokens. You only need the vault account to have the role required for the specific action—either the `MINTER_ROLE` for minting or the `BURNER_ROLE` for burning. Ensure the vault has sufficient native gas for transaction fees. You can retrieve the `vaultAccountId` from the Fireblocks console by checking the URL of the selected vault,

   e.g., `https://console.fireblocks.io/v2/accounts/vault/<vaultAccountId>`. For more details about Vault Accounts, refer to the [Create Vault Account guide](/reference/create-vault-account).

3. **Vault Account (for granting roles):** The `vaultAccountId` is responsible for granting roles. Ensure this vault also has sufficient native gas for transaction fees.

4. **Implementation Contract ABI:** The `ABI` of the implementation contract of the ERC20F token. This is required to interact with the token contract. For more details about how to retrieve the ABI, refer to the [Issue New ERC20F Tokens guide](/reference/issue-new-erc-20f-tokens).

5. **BaseAssetId ID:** The `baseAssetId` of the blockchain where the token is deployed (e.g. ETH\_TEST5 for Sepolia). This is the Fireblocks ID of the gas token of the blockchain where the token is deployed. (To get the base asset ID, refer to this [base assetId list](https://support.fireblocks.io/hc/en-us/articles/8993656344092-Supported-blockchain-networks))

With these in place, you can use the Fireblocks SDK to manage privileged roles for your ERC20F token and perform minting operations.

## Preparation steps

Here's an example of how to prepare the Fireblocks SDK to interact with the ERC20F token contract:

### 1. Initialize the Fireblocks SDK

First, import ethers and the Fireblocks SDK, and initialize the SDK with your Fireblocks API key and private key:

```javascript theme={"system"}
import {
    Fireblocks,
    BasePath,
} from '@fireblocks/ts-sdk';

const privateKey = '...'; // Your Fireblocks API private key
const apiKey = '...'; // Your Fireblocks API key

const fireblocksSdk = new Fireblocks({
    apiKey,
    basePath: BasePath.US, // Use BasePath.EU for the EU region
    secretKey: privateKey,
});
```

## Example: Mint Tokens

Minting tokens allows you to create new tokens and assign them to a specific address. In this example, the `MINTER_ROLE` has already been granted to an address during deployment.

> **Note:**
>
> The `vaultAccountId` used in the request must have the `MINTER_ROLE`. If the account does not have this role, the minting transaction will fail.

First, define the parameters for minting tokens:

* `recipientAddress`: The address to receive the tokens.
* `amount`: The fixed-point (integer) representation of the amount of tokens to burn. Since `ERC20F` token has 18 decimals, 1 token can be represented as `1 * 10^18` wei. The amount should be specified in wei.

Example:

```javascript theme={"system"}
const recipientAddress = '0x1234567890123456789012345678901234567890'; // Address to receive the tokens
const amount = '1000000000000000000'; // 1 token (in wei)
```

Use the `mint` function from the implementation contract `ABI` initially retrieved. Here's how to mint the tokens:

```javascript theme={"system"}
let mintTokensRequest: ContractInteractionsApiWriteCallFunctionRequest = {
    writeCallFunctionDto: {
        vaultAccountId: '0', // The vault account ID that has the MINTER_ROLE
        abiFunction: {
            "name": "mint",
            "type": "function",
            "inputs": [
                {
                    "name": "to",
                    "type": "address",
                    "internalType": "address",
                    value: recipientAddress,

                },
                {
                    "name": "amount",
                    "type": "uint256",
                    "internalType": "uint256",
                    value: amount
                }
            ],
            "outputs": [],
            "stateMutability": "nonpayable"
        },
    },
    contractAddress: '0x549E73A4aDF85757BD5Aa170cFb51cd6bBBafBb0', // Address of the ERC20F contract
    baseAssetId: 'ETH_TEST5', // Fireblocks asset ID
}

// Mint tokens
const response = await fireblocksSdk.contractInteractions.writeCallFunction(mintTokensRequest);
console.log('Mint tokens success:', response);
```

## Example: Burn Tokens

Burning tokens allows you to remove tokens from circulation. In this example, the `BURNER_ROLE` has not been granted to an address during deployment. So we need to grant the `BURNER_ROLE` to an address before burning tokens.

> **Note:**
>
> The `vaultAccountId` used in the request must have the `BURNER_ROLE`. If the account does not have this role, the burn transaction will fail.

Additionally, ensure that the vault account initiating the burn transaction has enough tokens to burn from its balance,
as the transaction will fail if the balance is insufficient.

For more information on how to grant roles to addresses, refer to the [Setting Up Roles in ERC20F Tokens guide](/reference/setting-up-roles-in-erc20f-tokens).

Example:

```javascript theme={"system"}
const roleBytes = '0x9f2df0fed2c77648de5860a4cc508cd0818c85b8b8a1ab4ceeef8d981c8956a6'; // BURNER_ROLE bytes
const granteeAddress = '0x1234567890123456789012345678901234567890'; // Address to receive the role

let grantRoleRequest: ContractInteractionsApiWriteCallFunctionRequest = {
    writeCallFunctionDto: {
        vaultAccountId: '0', // The vault account ID to grant the role
        abiFunction: {
            "name": "grantRole",
            "type": "function",
            "inputs": [
                {
                    "name": "role",
                    "type": "bytes32",
                    "internalType": "bytes32",
                    "value": roleBytes // BURNER_ROLE bytes
                },
                {
                    "name": "account",
                    "type": "address",
                    "internalType": "address",
                    "value": granteeAddress // Address to receive the role
                }
            ],
            "outputs": [],
            "stateMutability": "nonpayable"
        },
    },
    contractAddress: '0x549E73A4aDF85757BD5Aa170cFb51cd6bBBafBb0', // Address of the ERC20F contract
    baseAssetId: 'ETH_TEST5', // Fireblocks asset ID
}
```

Once we can confirm the vault account has been granted the role, we need to define the parameters for burning tokens:

* `amount`: The fixed-point (integer) representation of the amount of tokens to burn. Since `ERC20F` token has 18 decimals, 1 token can be represented as `1 * 10^18` wei. The amount should be specified in wei.

Example:

```javascript theme={"system"}
const amount = '1000000000000000000'; // 1 token (in wei)
```

Use the `burn` function from the implementation contract ABI initially retrieved. Here's how to burn the tokens:

```javascript theme={"system"}
let burnTokensRequest: ContractInteractionsApiWriteCallFunctionRequest = {
    writeCallFunctionDto: {
        vaultAccountId: '0', // The vault account ID that has the BURNER_ROLE
        abiFunction: {
            "name": "burn",
            "type": "function",
            "inputs": [
                {
                    "name": "amount",
                    "type": "uint256",
                    "internalType": "uint256",
                    "value": amount
                }
            ],
            "outputs": [],
            "stateMutability": "nonpayable"
        },
    },
    contractAddress: '0x549E73A4aDF85757BD5Aa170cFb51cd6bBBafBb0', // Address of the ERC20F contract
    baseAssetId: 'ETH_TEST5', // Fireblocks asset ID
}

// Burn tokens
const response = await fireblocksSdk.contractInteractions.writeCallFunction(burnTokensRequest);
console.log('Burn tokens success:', response);
```

## Further Reading

For more detailed information on API parameters and responses, including examples for using plain HTTP requests or in other programming languages, please have a look at the [Fireblocks API Reference for read function](/reference/readcallfunction) and the [Fireblocks API Reference for write function](/reference/writecallfunction).

For more specific guidance on ERC20F contract operations, refer to the [Operating the Upgradable ERC20F Contract Support Center Articles](https://support.fireblocks.io/hc/en-us/articles/13926379966876-Operating-the-Upgradeable-ERC-20F-contract).


# Order events
Source: https://developers.fireblocks.com/reference/order-events



This page covers all Orders events that can trigger webhook notifications, and their associated data objects for the Webhooks v2 service.

## Orders event types

To receive a specific event, include its `eventType` in the webhook's notification object.

| Event type    | Data object returned |
| ------------- | -------------------- |
| order.updated | orderDetails         |

## Data objects

orderDetails is the primary object returned in Orders webhook events. Nested objects are included only when relevant to the order type and lifecycle stage.

## orderDetails

| Parameter                   | Type                     | Description                                                       |
| --------------------------- | ------------------------ | ----------------------------------------------------------------- |
| id                          | string                   | Unique identifier for the order                                   |
| status                      | orderStatus              | Current status of the order                                       |
| createdAt                   | string                   | ISO 8601 timestamp for when the order was created                 |
| updatedAt                   | string                   | ISO 8601 timestamp for when the order was last updated (optional) |
| executionResponseDetails    | executionResponseDetails | Order execution details                                           |
| executionSteps              | executionSteps array     | Array of execution steps with their statuses                      |
| paymentInstructions         | paymentInstructions      | Payment instructions for on/off ramps orders (optional)           |
| receipt                     | receipt                  | Transfer receipt information (optional)                           |
| settlement                  | settlement               | Settlement details                                                |
| via                         | via                      | Account access information                                        |
| customerInternalReferenceId | string                   | Customer's internal reference ID for the order (optional)         |
| note                        | string                   | Note providing additional information about the order (optional)  |
| expiresAt                   | string                   | ISO 8601 timestamp for when the order expires (optional)          |
| failure                     | failure                  | Failure information for if the order failed                       |
| createdBy                   | string                   | Identifier of the user or service that created the order          |
| generalFees                 | fee array                | Array of fees associated with the order                           |

## orderStatus

| Value                 | Description                                                          |
| --------------------- | -------------------------------------------------------------------- |
| CREATED               | Order was created but not yet initiated                              |
| PENDING\_USER\_ACTION | Order is waiting for user action, such as a policy check or approval |
| AWAITING\_PAYMENT     | Order is waiting for payment to be initiated                         |
| PROCESSING            | Order is currently being processed                                   |
| CANCELLED             | Order was cancelled                                                  |
| COMPLETED             | Order was successfully completed                                     |
| FAILED                | Order failed. Check the failure field for details                    |

## executionResponseDetails

| Parameter      | Type    | Description                                           |
| -------------- | ------- | ----------------------------------------------------- |
| type           | string  | Execution type. Possible values: QUOTE, MARKET        |
| quoteId        | string  | Quote ID. Required if type is QUOTE                   |
| reQuote        | boolean | Whether this is a re-quote. Required if type is QUOTE |
| side           | string  | Order side. Possible values: BUY, SELL                |
| baseAmount     | string  | Amount to convert                                     |
| quoteAmount    | string  | Quote amount. Optional, but required if type is QUOTE |
| baseAssetId    | string  | Source asset identifier                               |
| quoteAssetId   | string  | Target asset identifier                               |
| baseAssetRail  | string  | Base asset rail identifier (optional)                 |
| quoteAssetRail | string  | Quote asset rail identifier (optional)                |

## executionSteps

| Parameter | Type   | Description                                                                      |
| --------- | ------ | -------------------------------------------------------------------------------- |
| type      | string | Step type. Possible values: APPROVE, DELIVERY, EXECUTE, SETTLEMENT               |
| status    | string | Step status. Possible values: WAITING, PROCESSING, COMPLETED, FAILED, CANCELLED  |
| fee       | fee    | Fee associated with this step (optional)                                         |
| txId      | string | Transaction ID within the main workspace (optional)                              |
| txHash    | string | Blockchain transaction hash (optional)                                           |
| error     | string | Error information if the step failed. Possible value: INTERNAL\_ERROR (optional) |

## paymentInstructions

| Parameter   | Type   | Description                                                                                                                                    |
| ----------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| type        | string | Payment instruction type. Possible values: IBAN, SWIFT, ACH, WIRE, SPEI, PIX, LOCAL\_BANK\_TRANSFER, EUROPEAN\_SEPA, MOBILE\_MONEY, BLOCKCHAIN |
| referenceId | string | Reference ID for the payment instruction (optional)                                                                                            |
| address     | object | Address details specific to the payment type                                                                                                   |

## receipt

| Parameter   | Type   | Description                                                 |
| ----------- | ------ | ----------------------------------------------------------- |
| type        | string | Receipt type. Possible values: BLOCKCHAIN, FIAT             |
| txHash      | string | Blockchain transaction hash. Required if type is BLOCKCHAIN |
| amount      | string | Transfer amount                                             |
| referenceId | string | Reference ID for fiat transfer (optional)                   |

## settlement

| Parameter          | Type                    | Description                                      |
| ------------------ | ----------------------- | ------------------------------------------------ |
| type               | string                  | Settlement type. Possible values: PREFUNDED, DVP |
| destinationAccount | accountReference        | Destination account reference                    |
| sourceAccount      | settlementSourceAccount | Source account (optional for PREFUNDED)          |

## accountReference

| Parameter | Type   | Description                                                                                                                                |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| accountId | string | Account ID. Optional for ONE\_TIME\_ADDRESS                                                                                                |
| type      | string | Account type. Possible values: VAULT\_ACCOUNT, EXCHANGE\_ACCOUNT, UNMANAGED\_WALLET, FIAT\_ACCOUNT, CONNECTED\_ACCOUNT, ONE\_TIME\_ADDRESS |
| address   | string | Address for one-time address accounts. Required for ONE\_TIME\_ADDRESS                                                                     |
| tag       | string | Tag or memo for one-time address accounts (optional)                                                                                       |

## settlementSourceAccount

| Parameter | Type   | Description                                                                                    |
| --------- | ------ | ---------------------------------------------------------------------------------------------- |
| type      | string | Account type. Possible values: EXTERNAL, VAULT\_ACCOUNT, EXCHANGE\_ACCOUNT, CONNECTED\_ACCOUNT |
| accountId | string | Account ID. Optional for EXTERNAL                                                              |

## via

| Parameter  | Type   | Description                                |
| ---------- | ------ | ------------------------------------------ |
| type       | string | Account access type. PROVIDER\_ACCOUNT     |
| accountId  | string | The ID of the account                      |
| providerId | string | The ID of the venue or provider (optional) |

## failure

| Parameter   | Type   | Description                                                                                                                                                                                                                                                                                                                                                                        |
| ----------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| reason      | string | Failure reason. Possible values: INSUFFICIENT\_FUNDS, UNKNOWN\_REASON, INITIATE\_PAYMENT\_FAILURE, POLICY\_REJECTION, TRANSACTION\_FAILED, ACCOUNT\_NOT\_ACTIVE, ACCOUNT\_NOT\_FOUND, BAD\_REQUEST, QUOTE\_NOT\_READY, INVALID\_DATA, UNSUPPORTED\_CONVERSION, REFUNDED, FAILED\_BY\_PROVIDER, ORDER\_EXPIRED, TRANSACTION\_CANCELLED, TRANSACTION\_REJECTED, TRANSACTION\_BLOCKED |
| failureInfo | object | Additional failure information as key-value pairs                                                                                                                                                                                                                                                                                                                                  |

## fee

| Parameter  | Type             | Description                                                                                                           |
| ---------- | ---------------- | --------------------------------------------------------------------------------------------------------------------- |
| feeType    | string           | Fee type. Possible values: ORDER, NETWORK, SPREAD, REBATE                                                             |
| assetId    | string           | Asset identifier for the fee                                                                                          |
| amountType | string           | Amount type. Possible values: FIXED, BPS                                                                              |
| amount     | string or number | Fee amount. FIXED is a string value. BPS is a numeric value where 1 equals 0.01 percent and 10,000 equals 100 percent |

## IBAN

| Parameter     | Type                 | Description                       |
| ------------- | -------------------- | --------------------------------- |
| accountHolder | accountHolderDetails | Account holder information        |
| iban          | string               | International Bank Account Number |

## SWIFT

| Parameter     | Type                 | Description                                 |
| ------------- | -------------------- | ------------------------------------------- |
| accountHolder | accountHolderDetails | Account holder information                  |
| swiftCode     | string               | SWIFT or BIC code identifying the bank      |
| routingNumber | string               | Routing number identifying the bank account |

## ACH

| Parameter         | Type                 | Description                                           |
| ----------------- | -------------------- | ----------------------------------------------------- |
| accountHolder     | accountHolderDetails | Account holder information                            |
| bankName          | string               | Name of the bank (optional)                           |
| bankAccountNumber | string               | Bank account number for the ACH transfer              |
| routingNumber     | string               | Routing number identifying the bank account           |
| accountType       | string               | Bank account type. Possible values: CHECKING, SAVINGS |

## WIRE

| Parameter         | Type                 | Description                                 |
| ----------------- | -------------------- | ------------------------------------------- |
| accountHolder     | accountHolderDetails | Account holder information                  |
| bankName          | string               | Name of the bank (optional)                 |
| bankAccountNumber | string               | Bank account number for the wire transfer   |
| routingNumber     | string               | Routing number identifying the bank account |
| bankAddress       | bankAddress          | Bank address (optional)                     |

## SPEI

| Parameter         | Type                 | Description                               |
| ----------------- | -------------------- | ----------------------------------------- |
| accountHolder     | accountHolderDetails | Account holder information                |
| bankName          | string               | Name of the bank (optional)               |
| bankAccountNumber | string               | Bank account number for the SPEI transfer |

## PIX

| Parameter     | Type                 | Description                                                    |
| ------------- | -------------------- | -------------------------------------------------------------- |
| accountHolder | accountHolderDetails | Account holder information                                     |
| pixKey        | string               | PIX key identifier                                             |
| keyType       | string               | PIX key type. Possible values: CPF, CNPJ, EMAIL, PHONE, RANDOM |
| bankName      | string               | Name of the bank (optional)                                    |
| bankCode      | string               | Bank code identifier (optional)                                |

## LOCAL\_BANK\_TRANSFER

| Parameter     | Type                 | Description                |
| ------------- | -------------------- | -------------------------- |
| accountHolder | accountHolderDetails | Account holder information |
| accountNumber | string               | Bank account number        |
| bankName      | string               | Name of the bank           |
| bankCode      | string               | Bank code identifier       |

## EUROPEAN\_SEPA

| Parameter     | Type                 | Description                              |
| ------------- | -------------------- | ---------------------------------------- |
| accountHolder | accountHolderDetails | Account holder information               |
| iban          | string               | International Bank Account Number        |
| bic           | string               | Bank Identifier Code (optional)          |
| bankName      | string               | Name of the bank (optional)              |
| bankBranch    | string               | Bank branch information (optional)       |
| bankAddress   | string               | Bank address (optional)                  |
| purposeCode   | string               | Purpose code for the transfer (optional) |
| taxId         | string               | Tax identification number (optional)     |

## MOBILE\_MONEY

| Parameter               | Type                 | Description                                                              |
| ----------------------- | -------------------- | ------------------------------------------------------------------------ |
| accountHolder           | accountHolderDetails | Account holder information                                               |
| mobilePhoneNumber       | string               | Mobile phone number in E.164 format                                      |
| provider                | string               | Mobile money provider. Possible values: MPESA, AIRTEL, MTN, TIGO, ORANGE |
| beneficiaryDocumentId   | string               | Beneficiary document ID (optional)                                       |
| beneficiaryRelationship | string               | Relationship to the beneficiary (optional)                               |

## AccountHolderDetails

| Parameter   | Type   | Description                                                |
| ----------- | ------ | ---------------------------------------------------------- |
| name        | string | Account holder full name                                   |
| address     | string | Street address (optional)                                  |
| city        | string | City of residence (optional)                               |
| country     | string | Country code in ISO 3166-1 alpha-2 format (optional)       |
| subdivision | string | Administrative subdivision in ISO 3166-2 format (optional) |
| postalCode  | string | Postal or ZIP code (optional)                              |

## bankAddress

| Parameter      | Type   | Description                                                |
| -------------- | ------ | ---------------------------------------------------------- |
| streetName     | string | Street name (optional)                                     |
| buildingNumber | string | Building number (optional)                                 |
| postalCode     | string | Postal or ZIP code (optional)                              |
| city           | string | City (optional)                                            |
| subdivision    | string | Administrative subdivision in ISO 3166-2 format (optional) |
| district       | string | District or area within the city (optional)                |
| country        | string | Country code in ISO 3166-1 alpha-2 format (optional)       |

## Example of events

```json theme={"system"}
{
  "event": {
    "type": "order.updated",
    "data": {
      "id": "ramp-abc123def456",
      "status": "PROCESSING",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:35:00.000Z",
      "executionResponseDetails": {
        "type": "QUOTE",
        "quoteId": "quote-xyz789",
        "reQuote": false,
        "side": "BUY",
        "baseAmount": "1000.00",
        "quoteAmount": "950.50",
        "baseAssetId": "USD",
        "quoteAssetId": "BTC",
        "baseAssetRail": "FIAT",
        "quoteAssetRail": "BLOCKCHAIN"
      },
      "executionSteps": [
        {
          "type": "APPROVE",
          "status": "COMPLETED",
          "txId": "tx-approve-001"
        },
        {
          "type": "EXECUTE",
          "status": "PROCESSING",
          "txId": "tx-execute-002"
        },
        {
          "type": "SETTLEMENT",
          "status": "WAITING"
        }
      ],
      "paymentInstructions": {
        "type": "IBAN",
        "referenceId": "ref-123456",
        "address": {
          "accountHolder": {
            "name": "John Doe",
            "address": "123 Main Street",
            "city": "New York",
            "country": "US",
            "subdivision": "NY",
            "postalCode": "10001"
          },
          "iban": "GB82WEST12345698765432"
        }
      },
      "receipt": {
        "type": "BLOCKCHAIN",
        "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
        "amount": "0.025"
      },
      "settlement": {
        "type": "DVP",
        "sourceAccount": {
          "accountId": "vault-account-123",
          "type": "VAULT_ACCOUNT"
        },
        "destinationAccount": {
          "accountId": "exchange-account-456",
          "type": "EXCHANGE_ACCOUNT"
        }
      },
      "via": {
        "type": "PROVIDER_ACCOUNT",
        "accountId": "provider-account-789",
        "providerId": "provider-coinbase"
      },
      "customerInternalReferenceId": "customer-ref-001",
      "note": "Monthly crypto purchase",
      "expiresAt": "2024-01-15T11:30:00.000Z",
      "createdBy": "user-12345",
      "generalFees": [
        {
          "feeType": "ORDER",
          "assetId": "USD",
          "amountType": "FIXED",
          "amount": "10.00"
        },
        {
          "feeType": "NETWORK",
          "assetId": "BTC",
          "amountType": "BPS",
          "amount": 50
        }
      ]
    }
  }
}
```


# Payments Objects
Source: https://developers.fireblocks.com/reference/payments-objects



## XBSettlementConfigCreationRequestBody

| Parameter  | Type                                                            | Description                                                      |
| ---------- | --------------------------------------------------------------- | ---------------------------------------------------------------- |
| name       | string                                                          | The text name of the settlement configuration.                   |
| corridorId | string                                                          | The ID of the cross-border corridor.                             |
| steps      | [XBSettlementConfigStepsRecord](#xbsettlementconfigstepsrecord) | The recorded steps of the cross-border settlement configuration. |

***

## XBSettlementConfigCreationResponse

| Parameter  | Type                                                            | Description                                                      |
| ---------- | --------------------------------------------------------------- | ---------------------------------------------------------------- |
| tenantId   | string                                                          | The ID of the tenant.                                            |
| configId   | string                                                          | The ID of the cross-border settlement configuration.             |
| corridorId | string                                                          | The ID of the cross-border corridor.                             |
| name       | string                                                          | The text name of the settlement configuration.                   |
| steps      | [XBSettlementConfigStepsRecord](#xbsettlementconfigstepsrecord) | The recorded steps of the cross-border settlement configuration. |

***

## XBSettlementConfigEditRequestBody

| Parameter | Type                                                            | Description                                                                 |
| --------- | --------------------------------------------------------------- | --------------------------------------------------------------------------- |
| name      | string                                                          | Optional - The text name of the settlement configuration.                   |
| steps     | [XBSettlementConfigStepsRecord](#xbsettlementconfigstepsrecord) | Optional - The recorded steps of the cross-border settlement configuration. |

***

## XBSettlementConfigEditResponse

| Parameter  | Type                                                            | Description                                                      |
| ---------- | --------------------------------------------------------------- | ---------------------------------------------------------------- |
| tenantId   | string                                                          | The ID of the tenant.                                            |
| configId   | string                                                          | The ID of the cross-border settlement configuration.             |
| corridorId | string                                                          | The ID of the cross-border corridor.                             |
| name       | string                                                          | The text name of the settlement configuration.                   |
| steps      | [XBSettlementConfigStepsRecord](#xbsettlementconfigstepsrecord) | The recorded steps of the cross-border settlement configuration. |

***

## XBSettlementConfigDeletionResponse

| Parameter | Type   | Description                                          |
| --------- | ------ | ---------------------------------------------------- |
| configId  | string | The ID of the cross-border settlement configuration. |

***

## GetXBSettlementConfigResponse

| Parameter  | Type                                                            | Description                                                      |
| ---------- | --------------------------------------------------------------- | ---------------------------------------------------------------- |
| tenantId   | string                                                          | The ID of the tenant.                                            |
| configId   | string                                                          | The ID of the cross-border settlement configuration.             |
| corridorId | string                                                          | The ID of the cross-border corridor.                             |
| name       | string                                                          | The text name of the settlement configuration.                   |
| steps      | [XBSettlementConfigStepsRecord](#xbsettlementconfigstepsrecord) | The recorded steps of the cross-border settlement configuration. |

***

## GetAllXBSettlementConfigsResponse

| Parameter      | Type                                                | Description                                       |
| -------------- | --------------------------------------------------- | ------------------------------------------------- |
| configurations | [XBSettlementConfigModel](#xbsettlementconfigmodel) | The configuration of the cross-border settlement. |

***

## XBCreateSettlementFlowRequestBody

| Parameter | Type                                    | Description                                                                         |
| --------- | --------------------------------------- | ----------------------------------------------------------------------------------- |
| configId  | string                                  | The ID of the cross-border settlement configuration.                                |
| amount    | [XBSettlementAsset](#xbsettlementasset) | The type and amount of an asset setup in the cross-border settlement configuration. |

***

## XBCreateSettlementFlowResponse

| Parameter          | Type                                                            | Description                                                                                      |
| ------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| tenantId           | string                                                          | The ID of the tenant.                                                                            |
| flowId             | string                                                          | The ID of the settlement flow configuration.                                                     |
| configId           | string                                                          | The ID of the cross-border settlement configuration.                                             |
| steps              | [XBSettlementConfigStepsRecord](#xbsettlementconfigstepsrecord) | The recorded steps of the cross-border settlement configuration.                                 |
| inputAmount        | [XBSettlementAsset](#xbsettlementasset)                         | The type and amount of an asset input in the cross-border settlement configuration.              |
| outputAmount       | [XBSettlementAsset](#xbsettlementasset)                         | The type and amount of an asset output in the cross-border settlement configuration.             |
| totalEstimatedFees | [XBSettlementAsset](#xbsettlementasset)                         | The type and amount of estimated asset fees setup in the cross-border settlement configuration.  |
| totalEstimatedTime | number                                                          | The total amount of time estimated for the complete cross-border settlement flow to be executed. |

***

## XBSettlementFlowExecutionResponse

| Parameter    | Type                                                                | Description                                                                                     |
| ------------ | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| tenantId     | string                                                              | The ID of the tenant.                                                                           |
| flowId       | string                                                              | The ID of the settlement flow configuration.                                                    |
| configId     | string                                                              | The ID of the cross-border settlement configuration.                                            |
| steps        | [XBSettlementConfigStepsRecord](#xbsettlementconfigstepsrecord)     | The recorded steps of the cross-border settlement configuration.                                |
| inputAmount  | [XBSettlementAsset](#xbsettlementasset)                             | The type and amount of an asset input in the cross-border settlement configuration.             |
| outputAmount | [XBSettlementAsset](#xbsettlementasset)                             | The type and amount of an asset output in the cross-border settlement configuration.            |
| totalFees    | [XBSettlementAsset](#xbsettlementasset)                             | The type and amount of estimated asset fees setup in the cross-border settlement configuration. |
| initiatedAt  | number                                                              | The time the flow execution was initiated.                                                      |
| initiatedBy  | string                                                              | The ID of the user who initiated the flow execution.                                            |
| state        | [XBSettlementFlowExecutionStatus](#xbsettlementflowexecutionstatus) | The status of the flow execution.                                                               |

***

## XBSettlementFlowExecutionStep

| Parameter    | Type                                                                        | Description                                                                          |
| ------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| id           | string                                                                      | The ID of the individual flow execution step.                                        |
| accountId    | string                                                                      | The ID of the account initiating the flow execution step.                            |
| status       | [XBSettlementFlowExecutionStepStatus](#xbsettlementflowexecutionstepstatus) | The status of the individual step of the flow execution.                             |
| inputAmount  | [XBSettlementAsset](#xbsettlementasset)                                     | The type and amount of an asset input in the cross-border settlement configuration.  |
| outputAmount | [XBSettlementAsset](#xbsettlementasset)                                     | The type and amount of an asset output in the cross-border settlement configuration. |
| fee          | [XBSettlementAsset](#xbsettlementasset)                                     | The type and amount of an asset setup in the cross-border settlement configuration.  |
| startedAt    | number                                                                      | The time the specific flow execution step began.                                     |

***

## XBSettlementFlowExecutionStepStatus

| Parameter                           | Type   | Description                                                |
| ----------------------------------- | ------ | ---------------------------------------------------------- |
| XBSettlementFlowExecutionStepStatus | string | Valid values: NOT\_STARTED, PROCESSING, COMPLETED, FAILED. |

***

## XBSettlementFlowExecutionStatus

| Parameter                       | Type   | Description                                                |
| ------------------------------- | ------ | ---------------------------------------------------------- |
| XBSettlementFlowExecutionStatus | string | Valid values: NOT\_STARTED, PROCESSING, COMPLETED, FAILED. |

***

## XBSettlementConfigModel

| Parameter | Type                                                            | Description                                                      |
| --------- | --------------------------------------------------------------- | ---------------------------------------------------------------- |
| tenantId  | string                                                          | The ID of the tenant.                                            |
| flowId    | string                                                          | The ID of the settlement flow configuration.                     |
| configId  | string                                                          | The ID of the cross-border settlement configuration.             |
| name      | string                                                          | The text name of the cross-border settlement configuration.      |
| steps     | [XBSettlementConfigStepsRecord](#xbsettlementconfigstepsrecord) | The recorded steps of the cross-border settlement configuration. |

***

## XBSettlementConfigStep

| Parameter | Type                                          | Description                                               |
| --------- | --------------------------------------------- | --------------------------------------------------------- |
| stepType  | [XBSettlementStepType](#xbsettlementsteptype) | The type of step specified in the configuration.          |
| accountId | string                                        | The ID of the account initiating the flow execution step. |

***

## XBSettlementStepType

| Parameter            | Type   | Description                                                            |
| -------------------- | ------ | ---------------------------------------------------------------------- |
| XBSettlementStepType | string | Valid values: ON\_RAMP, VAULT\_ACCOUNT, OFF\_RAMP, FIAT\_DESTINATION . |

***

## XBSettlementFlowSetupStep

| Parameter          | Type                                    | Description                                                                                          |
| ------------------ | --------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| accountId          | string                                  | The ID of the account initiating the flow execution step.                                            |
| inputAmount        | [XBSettlementAsset](#xbsettlementasset) | The type and amount of an asset input in the cross-border settlement configuration.                  |
| outputAmount       | [XBSettlementAsset](#xbsettlementasset) | The type and amount of an asset output in the cross-border settlement configuration.                 |
| estimatedFeeAmount | [XBSettlementAsset](#xbsettlementasset) | The type and amount of asset fees estimated in the cross-border settlement configuration.            |
| estimatedTime      | number                                  | The amount of time estimated for the complete cross-border settlement flow setup step to be executed |

***

## XBSettlementFlowSetupModel

| Parameter               | Type                                                        | Description                                                                                         |
| ----------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| tenantId                | string                                                      | The ID of the tenant.                                                                               |
| flowId                  | string                                                      | \[Optional] The ID of the settlement flow configuration.                                            |
| configId                | string                                                      | The ID of the cross-border settlement configuration.                                                |
| steps                   | [XBSettlementFlowStepsRecord](#xbsettlementflowstepsrecord) | The specified steps for the cross-border settlement flow configuration.                             |
| inputAmount             | [XBSettlementAsset](#xbsettlementasset)                     | The type and amount of an asset input in the cross-border settlement configuration.                 |
| outputAmount            | [XBSettlementAsset](#xbsettlementasset)                     | The type and amount of an asset output in the cross-border settlement configuration.                |
| totalEstimatedFeeAmount | [XBSettlementAsset](#xbsettlementasset)                     | The type and total amount of asset fees estimated in the cross-border settlement configuration.     |
| totalEstimatedTime      | number                                                      | The amount of total time estimated for each cross-border settlement flow setup step to be executed. |

***

## XBSettlementFlowExecutionModel

| Parameter    | Type                                                                | Description                                                                           |
| ------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| tenantId     | string                                                              | The ID of the tenant.                                                                 |
| flowId       | string                                                              | The ID of the settlement flow configuration.                                          |
| configId     | string                                                              | The ID of the cross-border settlement configuration.                                  |
| steps        | [XBSettlementFlowExecutionStep](#xbsettlementflowexecutionstep)     | The instructions for the specified cross-border settlement flow configuration step.   |
| inputAmount  | [XBSettlementAsset](#xbsettlementasset)                             | The type and amount of an asset input in the cross-border settlement configuration.   |
| outputAmount | [XBSettlementAsset](#xbsettlementasset)                             | The type and amount of an asset output in the cross-border settlement configuration.  |
| totalFees    | [XBSettlementAsset](#xbsettlementasset)                             | The type and amount of total asset fees in the cross-border settlement configuration. |
| initiatedAt  | number                                                              | The time the flow execution was initiated.                                            |
| initiatedBy  | string                                                              | The ID of the user who initiated the flow execution.                                  |
| state        | [XBSettlementFlowExecutionStatus](#xbsettlementflowexecutionstatus) | The status of the flow execution.                                                     |

***

## XBSettlementConfigStepsRecord

| Parameter | Type                                          | Description                                               |
| --------- | --------------------------------------------- | --------------------------------------------------------- |
| stepType  | [XBSettlementStepType](#xbsettlementsteptype) | The type of step specified in the configuration.          |
| accountId | string                                        | The ID of the account initiating the flow execution step. |

***

## XBSettlementFlowStepsRecord

| Parameter                 | Type                                                    | Description                                                                 |
| ------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------- |
| stepType                  | [XBSettlementStepType](#xbsettlementsteptype)           | The type of step specified in the configuration.                            |
| XBSettlementFlowSetupStep | [XBSettlementFlowSetupStep](#xbsettlementflowsetupstep) | The arrangement and setup of steps for the cross-border configuration flow. |

***

## XBSettlementAsset

| Parameter | Type   | Description                                                                  |
| --------- | ------ | ---------------------------------------------------------------------------- |
| amount    | string | The amount of the asset being used in the cross-border settlement.           |
| assetId   | string | The ID of the specific asset type being used in the cross-border settlement. |


# Plugin-based Callback Handler
Source: https://developers.fireblocks.com/reference/plugin-based-callback-handler



The Fireblocks Plugin-based Callback Handler is a boilerplate application designed to simplify the installation and setup process for Fireblocks users.

It integrates seamlessly with plugins, enabling you to easily develop custom functionalities without investing time and resources in server application development. The application comes with a collection of pre-configured plugins, which are described in detail below for your reference.

Check out the Plugin-Based Callback Handler boilerplate in [our official GitHub account](https://github.com/fireblocks/plugin-based-callback-handler).


# Python SDK (Legacy)
Source: https://developers.fireblocks.com/reference/python-sdk



> **We released our new official Python SDK! Make sure to check it out in the Python SDK guide**

# Overview

A Python developer can use the Fireblocks API in 2 different ways:

1. [The Fireblocks Python SDK.](https://github.com/fireblocks/fireblocks-sdk-py)
2. A standard HTTP library such as [http.client](https://docs.python.org/3/library/http.client.html) or [Requests](https://requests.readthedocs.io/en/latest/).

In this guide, you'll set up the Fireblocks SDK and see an example of non-SDK usage (including signing the JWT token).

# Using the Fireblocks SDK

## Install Python 3.6 or newer

The Fireblocks Python SDK requires **Python 3.6 or newer**. You can check which version of Python you already have installed with the following command.

`python --version` or `python3 --version`

[Learn how to install or update Python to a newer version.](https://docs.python-guide.org/starting/installation/)

## Install fireblocks-sdk

The Fireblocks Python SDK is open-source and hosted on both GitHub and PIP, the official package repository.

* **Source code:** [https://github.com/fireblocks/fireblocks-sdk-py](https://github.com/fireblocks/fireblocks-sdk-py)
* **Python Package:** [https://pypi.org/project/fireblocks-sdk/](https://pypi.org/project/fireblocks-sdk/)

Installing the latest SDK is easy with `pip`:

`pip install fireblocks-sdk`

## Your First Fireblocks Python script!

Now that you're set up, run a quick check for the API. The script will query existing vaults, create a new vault and then query again to see that the vaults were created.

The requests-based implementation will require some library dependencies:

* [requests](https://requests.readthedocs.io/en/latest/)
* [pyjwt](https://pyjwt.readthedocs.io/en/stable/)

> **Use the correct API Base URL**
>
> Depending on the script, make sure you're using the correct value for `base_url` for your environment:
>
> * For Sandbox workspaces: `https://sandbox-api.fireblocks.io`
> * For Mainnet or Testnet workspaces: `https://api.fireblocks.io`

```python theme={"system"}
from fireblocks_sdk import FireblocksSDK, VAULT_ACCOUNT, PagedVaultAccountsRequestFilters
import json

api_secret = open('`</path/to/fireblocks_secret.key>`', 'r').read()
api_key = '<your-api-key-here>'
base_url = 'https://sandbox-api.fireblocks.io' # Choose the right api url for your workspace type
fireblocks = FireblocksSDK(api_secret, api_key, api_base_url=base_url)

# Print vaults before creation
vault_accounts = fireblocks.get_vault_accounts_with_page_info(PagedVaultAccountsRequestFilters())
print(json.dumps(vault_accounts, indent = 1))

# Create new vault
vault_account = fireblocks.create_vault_account(name = "Quickstart_Vault")

# Print vaults after creation
vault_accounts = fireblocks.get_vault_accounts_with_page_info(PagedVaultAccountsRequestFilters())
print(json.dumps(vault_accounts, indent = 1))
```

```python theme={"system"}
import json
import math
import secrets
import time
import urllib.parse
from hashlib import sha256

import jwt
import requests

class FireblocksRequestHandler(object):
    def __init__(self, base_url, private_key, api_key):
        self.base_url = base_url
        self.private_key = private_key
        self.api_key = api_key

    def _sign_jwt(self, path, body_json=""):
        timestamp = time.time()
        nonce = secrets.randbits(63)
        timestamp_secs = math.floor(timestamp)
        path = path.replace("[", "%5B")
        path = path.replace("]", "%5D")
        token = {
            "uri": path,
            "nonce": nonce,
            "iat": timestamp_secs,
            "exp": timestamp_secs + 55,
            "sub": self.api_key,
            "bodyHash": sha256(json.dumps(body_json).encode("utf-8")).hexdigest()
        }
        return jwt.encode(token, key=self.private_key, algorithm="RS256")

    def get_request(self, path):
        token = self._sign_jwt(path)
        headers = {
            "X-API-Key": self.api_key,
            "Authorization": f"Bearer {token}"
        }

        return requests.get(urllib.parse.urljoin(self.base_url, path), headers=headers)

    def post_request(self, path, body_json={}):
        token = self._sign_jwt(path, body_json)
        headers = {
            "X-API-Key": self.api_key,
            "Authorization": f"Bearer {token}"
        }

        response = requests.post(urllib.parse.urljoin(self.base_url, path), json=body_json, headers=headers)
        return response

api_secret = open('`</path/to/fireblocks_secret.key>`', 'r').read()
api_key = '<your-api-key-here>'
base_url = 'https://sandbox-api.fireblocks.io' # Choose the right api url for your workspace type
request_handler = FireblocksRequestHandler(base_url, api_secret, api_key)

# Print vaults before creation
response = request_handler.get_request('/v1/vault/accounts_paged')
print(response.text)

# Create new vault
response = request_handler.post_request('/v1/vault/accounts', body_json={'name': 'Quickstart_Vault'})
print(response.text)

# Print vaults after creation
response = request_handler.get_request('/v1/vault/accounts_paged')
print(response.text)
```


# Rate Limiting
Source: https://developers.fireblocks.com/reference/rate-limiting



# Overview

Fireblocks strives to offer a stable and secure platform at all times. Accordingly, API call traffic is continuously monitored by all parties to identify patterns that might affect the network. API rate limits assure that a single client can't overload the system for other clients.

Error responses with HTTP status code **429** indicate that rate limits have been temporarily exceeded.

If normal test or production operations repeatedly result in rate limiting, you can contact your [Customer Success Manager](https://support.fireblocks.io/hc/en-us/requests/new?ticket_form_id=6947882197532) or [Fireblocks Support.](https://support.fireblocks.io/hc/en-us/requests/new).

API rate limits are set at the API user level. If you regularly receive HTTP 429 responses, do your best to limit the rate of requests, spread them out across minute intervals, or spread them out across multiple API users.

Some **common mistakes** that can result in receiving many API rate limit errors are:

* Not monitoring 429 errors on the client
* Retry API calls whenever they fail without noticing the error type - causing an escalation in rate limits
* Using too many parallel processes for batch operations
* Monitoring many transactions via polling instead of using webhooks
* Excessively checking gas prices or token prices

Rate limits for traffic are based on a per API endpoint and per minute basis.

### Rate limit error response

If you reach your rate limit, you'll see a 429 error response to let you know your rate limit has been exceeded.

### Increasing your rate limit

If you would like to raise your rate limits, please contact your Customer Success Manager or [Fireblocks support](mailto:support@fireblocks.com).

**Note:** Not all requests to increase rate limits will be honored, and additional charges may apply for higher limits.

***

# Best Practices

**Monitor rate limit errors** - if you receive 429 errors more than a handful of times a day - something is probably not done properly. Consider what change in the solution architecture can reduce the number of API calls you are making.

**Retry API calls reasonably** - If you are calling an API periodically - consider not retrying and relying on the next time it will be checked. Additional, an exponential backoff retry strategy is recommended when it is required to try again.

**Use Webhooks to monitor applications** - using push notifications and webhooks will dramatically reduce the number of API calls you need to make for standard operations. It will reduce the load on both your internal system and the Fireblocks backed.

**Use Cache** - Some elements do not need to be checked on every transaction or every second - consider using cache for data points that you only need to update periodically.

> **Note**
>
> Developer Sandbox workspaces have a very low rate limit configuration and so you might see many rate limit errors if you try to test for scale.
>
> The Developer Sandbox workspace was not meant for that level of testing, so you should use a Testnet workspace. Testnet environment rate limits are more flexible and handle large amounts of requests for testing.


# Raw Signing Objects
Source: https://developers.fireblocks.com/reference/raw-signing-objects



## RawMessageData

| Parameter | Type                                                       | Description                                                                                                                                     |
| --------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| messages  | array of [UnsignedRawMessage](#unsignedrawmessage) objects | The messages that should be signed                                                                                                              |
| algorithm | string                                                     | \[optional] The algorithm which will be used to sign the transaction, one of the [SigningAlgorithms](/reference/vault-objects#signingalgorithm) |

***

## SignedMessage

| Parameter      | Type             | Description                                                                                                                                                               |
| -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| content        | string/object    | The content that was sent to be signed.  For RAW signing - the message for signing (hex-formatted).  For EIP712 Typed Message signing - the object (payload) for signing. |
| algorithm      | string           | The algorithm that was used for signing, one of the [SigningAlgorithms](/reference/vault-objects#signingalgorithm)                                                        |
| derivationPath | Array of numbers | [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) derivation path of the signing key. E.g.                                                          |
| signature      | dictionary       | The message signature                                                                                                                                                     |
| publicKey      | string           | The signature's public key is used for verification.                                                                                                                      |

***

## UnsignedRawMessage

| Parameter         | Type                                                                                                                           | Description                                                                                                                                                                                                                                               |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| content           | string                                                                                                                         | The message to be signed in hex format encoding                                                                                                                                                                                                           |
| bip44AddressIndex | number                                                                                                                         | RawMess [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) address\_index path level                                                                                                                                                 |
| bip44change       | number                                                                                                                         | RawMess [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) change path level                                                                                                                                                         |
|                   | The 2 fields above complement the derivation path given the source id and asset were provided in the transaction body request. |                                                                                                                                                                                                                                                           |
|                   | In case none of the above was provided, please specify the derivation path.                                                    |                                                                                                                                                                                                                                                           |
| derivationPath    | array of numbers                                                                                                               | RawMess Should be passed only if asset and source were not specified.   - *Note:*\* for Testnet assets, `coin_type` is always '1'.                                                                                                                        |
| type              | string                                                                                                                         | RawMess Should be passed only if `operation` is `TYPED_MESSAGE`. Possible values are:   - `EIP191`: for ETH/EVM personal messages - `EIP712`: For ETH/EVM typed messages - `TIP191`: For TRX personal messages - `BTC_MESSAGE`: For BTC personal messages |
| preHash           | [PreHash object](/reference/raw-signing-objects#prehash)                                                                       | An object to send (described below) when creating ECDSA Raw signing requests in cold wallet workspaces.  **Required in Cold Wallet workspaces only. Regular Fireblocks workspaces do not require this object to be sent.**                                |

## PreHash

| Parameter     | Type   | Description                                                                                                                       |
| ------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------- |
| content       | string | The pre-hashed content in hexadecimal representation.                                                                             |
| hashAlgorithm | string | The hashing algorithm to apply to the provided content.  Possible values:   - SHA256 - KECCAK256 - BLAKE2 - SHA3 - DOUBLE\_SHA256 |


# Resend Webhook Notifications
Source: https://developers.fireblocks.com/reference/resend-webhook-notifications



> **Deprecation notice**
>
> Webhooks v1 will be deprecated on **June 15th, 2026**. Please use the Developer Center in the Fireblocks Console to upgrade to Webhooks V2, which offers improved reliability, performance, and observability.

Fireblocks customers can resend webhook notifications that were missed by their server by using the following API endpoints:

* [Resend failed webhooks](/reference/resendwebhooks) - Resends all failed webhook notifications
* [Resend webhooks for a transaction by ID](/reference/resendtransactionwebhooks) - Resends webhook notifications for a transaction by its unique identifier

# Resend all failed webhook notifications

The following command re-sends **all** the failed webhooks pending the backoff retry mechanism being re-sent.

```javascript theme={"system"}
const result = await fireblocks.resendWebhooks();
```

```python theme={"system"}
result = fireblocks.resend_webhooks()
```

* The above command returns `webhookCount`, which is the number of re-sent webhook notifications.

# Resend missed notifications for a specific transaction

Use the following command to resend a missing webhook notification per specific transaction:

```javascript theme={"system"}
const result = await fireblocks.resendTransactionWebhooksById(txId, resendCreated, resendStatusUpdated);
```

```python theme={"system"}
result = fireblocks.resend_transaction_webhooks_by_id(txId, resend_created, resend_status_updated)
```

> Returns 200 on success


# Callback Handler response object
Source: https://developers.fireblocks.com/reference/response-object



> **New Callback Handler parameters**
>
> Starting with SGX API Co-signer image version 3.5.0, as well as all versions of AWS Nitro and GCP Confidential Space Co-signer, the following enhancements have been introduced:
>
> * The Callback Handler's payload includes the **signerId**, which represents the **API user ID** (API key) of the API user handling the request. This is particularly useful in high availability configurations with multiple API Co-signers, as it allows the Callback Handler to identify the specific Co-signer that initiated the request.

Below is the response expected from the Callback Handler for any request. If it does not respond within 30 seconds, Fireblocks fails the request.

| **Parameter**   | **Type** | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| action          | string   | `APPROVE`: Approves the request. For some configuration requests an approval quorum may be required.  `REJECT`: Denies the request. Even if a quorum of approvals is expected, one rejection denies the request.  `RETRY`: Retry the request until it times out, reaches the maximum number of retries, or the Callback Handler returns `APPROVE` or `REJECT`. The default timeout setting is 20 retries every 3 minutes, for a total of 60 minutes. If necessary, Fireblocks Support can adjust the retry interval to a minimum of 30 seconds or a maximum of 1 hour, and the total retry duration up to a maximum of 48 hours. Additionally, retries are performed using identical parameters, so to prevent duplication, make sure your Callback Handler is properly configured to deal with the asynchronous nature of the calls.  `IGNORE`: This action is only supported for transaction and configuration approvals, not transaction signing. Dismisses the request without denying it, allowing the following approval requests to be processed. If a quorum is required to approve a request, the other approvers may approve this request independently. |
| requestId       | string   | The unique identifier of the call, as received in the approval request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| rejectionReason | string   | (Optional) Free text of the reason for rejection. This is used for logging purposes and recorded in the workspace's audit logs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |


# REST API Guide
Source: https://developers.fireblocks.com/reference/rest-api-guide-1



Fireblocks provides a robust REST API for developers to leverage Fireblocks' capabilities programmatically. Our REST API is the base layer for all Fireblocks SDKs.

If you prefer to work directly with the Fireblocks API, [view the complete Fireblocks REST API reference documentation](/reference/getconsoleusers).

To practice with our API before implementing any code, read the [Postman Guide](doc:postman-guide) containing the pre-defined API endpoints.

## OpenAPI Specification

[View the Fireblocks OpenAPI 3.0 specification](https://docs.fireblocks.com/api/v1/swagger.yaml).

Fireblocks uses the OpenAPI 3.0 (Swagger) format to maintain our API and provide the specification file for download.

The API Reference section is auto-generated from our OpenAPI specification. You can also import it into your tool of choice, such as Swagger UI, ReDoc, and so on.

If you prefer using Postman, you can also explore the API using our [Postman Guide](doc:postman-guide).

## Generating client libraries and SDKs

Using the Swagger Editor, you can generate your client libraries and SDKs in the language of your choice.

1. [Navigate to the publicly hosted Swagger Editor](https://editor.swagger.io/).
2. Copy [our latest OpenAPI specification file](https://docs.fireblocks.com/api/v1/swagger.yaml) and paste it into the editor window.
3. Select **Generate Client** on the top menu bar and select the language to download.
4. The last step is to set up the proper headers in order to authenticate with the Fireblocks API.

   [See here for more details on the JWT structure.](doc:signing-a-request-jwt-structure) You can see examples on how this is done for our SDKs so you can replicate this in the language of the generated client library.

## Fireblocks Developers Hub

Visit our [Developers Hub GitHub repository](https://github.com/fireblocks/developers-hub) for code examples, snippets, and other helpful resources that you can use as a reference.


# Retail Demo Application
Source: https://developers.fireblocks.com/reference/retail-demo



> **This code is intended solely as a reference and is NOT production-ready.**
>
> It should not be used directly in a production environment.
> Fireblocks assumes no responsibility for any financial loss or other damages resulting from the use of this code in production.

# Fireblocks Retail Demo Application - Work in Progress!

The Fireblocks Retail Demo application is designed to support Fireblocks clients by serving as a reference model for their integration processes. It embodies the best practices that Fireblocks advocates for building secure, retail-facing solutions.

This demo aims to accelerate and simplify the integration of Fireblocks into your projects, ensuring that you adhere to the recommended best practices when building on the Fireblocks platform.

[Retail Demo Application on GitHub](https://github.com/fireblocks/retail-demo)

## Overview

* **Frontend**: Built with Next.js, this frontend application serves as a retail cryptocurrency platform, providing features like portfolio dashboards, multi-asset wallet management, and transaction handling. It leverages Fireblocks for secure asset management, offering a comprehensive example of a retail-facing crypto solution.
* **Backend**: Developed with Node.js (Express.js), the backend handles essential operations such as user authentication, wallet and asset management, and transaction processing. It integrates with a MySQL database to store user data locally and communicates with the Fireblocks API for wallet and transaction operations.

***

## Before you start: Fireblocks workspace configurations:

### Fireblocks testnet workspace setup

* Running the retail demo app requires a Fireblocks testnet workspace. Complete activating your workspace with the workspace Owner before proceeding with this guide.
* [Create an API user](https://support.fireblocks.io/hc/en-us/articles/4407823826194-Adding-new-API-Users) to execute the backend processes. Our implementation requires a single API user with signing privileges to simplify the integration, for a production-grade application please consider these [best practices](/docs/manage-api-keys) when creating your API users and access levels.
* Upload the `fireblocks-secret.key` file to the `keys` folder on the backend root project folder (create one if not yet created).
* Complete the API user setup and the pairing to an API Co-Signer.
* Copy the API user ID from the console UI and update it in your `.env` file of the backend library (more details below).
* Enable [One Time Address (OTA)](https://support.fireblocks.io/hc/en-us/articles/4409104568338-One-Time-Address-OTA-feature) to allow user withdrawals.
* Determine your Omnibus vault account and copy its ID (found on the vault account page URL) and update your `.env` file in the backend library (more details below).
* Create your withdrawal vault accounts and update their IDs in the `.env` file.

  Note: If not manually set in the `.env` file, the app will create the omnibus and 3 withdrawal vault accounts, and update the database accordingly on the initial run of the app.

***

### Policy setup

Our retail demo app uses the Fireblocks [Policy](https://support.fireblocks.io/hc/en-us/articles/7354983580316-About-the-TAP) feature to govern the flow of assets between vault accounts and from the withdrawals accounts to external user wallets.
Use the below example to tailor your policy and update it on your testnet workspace.
This simplified Policy rule set dictates that the API Admin user will be able to perform rebalancing and sweeping transactions (any vault account to any vault account), and perform user withdrawal transactions (from the 3 withdrawal vault accounts to OTAs).

<img alt="" />

> **Note**
>
> This Policy example is a very simplified rule set that only shows the bare minimum rules required for the demo app to run smoothly. For production level apps, please consider hardening your policy as required by your operations.

***

### Test coins funding

In order to run the demo app, an initial deposit of test coins is required to the withdrawal vault accounts.
Please fund your withdrawal vault accounts with the sufficient balance of tokens and according to the supported assets list found [here](https://github.com/fireblocks/retail-demo/blob/main/backend/src/utils/supportedAssets.json).

Optional public faucets to use:

[Bitcoin Test tokens](https://bitcoinfaucet.uo1.net/)

[Sepolia Test tokens](https://www.alchemy.com/faucets/ethereum-sepolia)

[Solana Devnet tokens](https://faucet.solana.com/)

***

### Webhooks setup

The retail demo app listens to webhooks from Fireblocks and triggers business operations and database updates based on specific events, follow this guide to properly configure your environment to receive webhook messages from Fireblocks.

* Configure a local tunneling service like `ngrok` or `exposed` and forward the messages to `http://localhost:3000`.
* Copy the publicly available URL of the tunneling service.
* [Configure](https://support.fireblocks.io/hc/en-us/articles/4408110107794-Configuring-webhook-URLs) the URL as a webhook server on your Fireblocks testnet workspace's general settings.
* **Important:** The app's webhook endpoint is configured on the `./webhook` path, make sure you add it to the public URL provided by the local tunneling tool you use (example: `https://1e70-94-188-131-83.ngrok-free.app/webhook`).

***

### Rebalancing Automation

The retail demo app utilizes Fireblocks's [Automations feature](https://support.fireblocks.io/hc/en-us/articles/14873112741660-Automation) to trigger rebalancing transactions from the omnibus vault account (where all user deposit accumulates) to the withdrawal vault accounts.
Below, you will find an example of an automation created to facilitate the above. Use it as a reference when creating your automation.

<img alt="" />

Explanation:

* This automation will be triggered by any BTC\_TEST withdrawal from withdrawal vault #1.
* Once the withdrawal is completed, the remaining balance of BTC\_TEST in that vault will be checked.
* If the remaining balance is lower than 0.01 BTC\_TEST, a rebalancing transaction will be triggered to top-up the balance up to 0.1 BTC\_TEST.

Notes:

* An automation should be created for **each** supported asset on **every** withdrawal vault account.
* The amounts used above should be changed based on the anticipated operation in your app.

***

### Running the application:

The retail demo app can run with Docker or locally, both options require updating the environment variable files for both the backend and frontend servers.

#### Backend environment variables

Note: You may use the [.env.example](https://github.com/fireblocks/retail-demo/blob/main/backend/.env.example) file as reference.
Here's a detailed explanation of each variable:

#### Database Configuration

* `DB_NAME`: Name of the MySQL database (default: retail\_demo)
* `DB_USER`: MySQL user (default: root)
* `DB_PASSWORD`: MySQL password
* `DB_HOST`: Database host (default: localhost)
* `DB_PORT`: Database port (default: 3306)

#### Authentication

[Google OAuth 2.0 docs](https://developers.google.com/identity/protocols/oauth2)

* `GOOGLE_CLIENT_ID`: Google OAuth client ID
* `GOOGLE_CLIENT_SECRET`: Google OAuth client secret
* `GIT_CLIENT_ID`: GitHub OAuth client ID
* `GIT_CLIENT_SECRET`: GitHub OAuth client secret
* `JWT_SECRET_KEY`: Secret key for JWT token generation
* `JWT_REFRESH_KEY`: Secret key for JWT refresh token generation

#### Fireblocks Configuration

* `FIREBLOCKS_API_KEY`: Your Fireblocks API key
* `FIREBLOCKS_PATH_TO_SECRET`: Path to your Fireblocks secret key file

#### Application Settings

* `PORT`: Port on which the server will run (default: 3000)
* `FRONTEND_BASE_URL`: URL of the frontend application

#### Vault Configuration

* `OMNIBUS_VAULT`: ID of the Omnibus vault in Fireblocks
* `WITHDRAWAL_VAULTS`: Comma-separated IDs of withdrawal vaults in Fireblocks

#### Frontend enviroment variables

* `NEXT_PUBLIC_BACKEND_BASE_URL`: [http://localhost:3000](http://localhost:3000)
* `CMC_API_KEY`: your\_coinmarketcap\_api\_key

You can get your CMC API key [here](https://coinmarketcap.com/api/documentation/v1/) - we use it as USD value oracle for the app.

#### Run with Docker:

Prerequisites:

* Install Docker and Docker Compose.
* Update the `.env` files for both servers, as mentioned above.

1. Build and Run the Docker container:

```bash theme={"system"}
docker-compose up --build
```

2. Navigate to `http://localhost:3001/login` once the container is up and running to access the app console UI.

#### Run locally:

Prerequisites:

* Install MySQL.
* Install the BE dependencies:

```bash theme={"system"}
npm install --prefix ./backend
```

* Install the FE dependencies:

```bash theme={"system"}
npm install --prefix ./frontend
```

1. Run the backend server:

```bash theme={"system"}
cd backend
npm start
```

2. Run the frontend server: (on another terminal)

```bash theme={"system"}
cd frontend
npm run dev
```

3. Navigate to `http://localhost:3001/login` to access the app console UI.

***

### Setup script:

The setup script will run only the first time you start the app. It will initialize the connection to the database, create the tables and configure the default data fields.

The setup script uses the `OMNIBUS_VAULT` and `WITHDRAWAL_VAULTS` variables to determine whether to create new vault accounts or use existing ones:

1. If `OMNIBUS_VAULT` is empty:

   * The script will create a new vault account in Fireblocks called "Omnibus Vault".
   * It will then create a BTC\_TEST wallet in this vault account.
2. If `OMNIBUS_VAULT` contains a value:

   * The script will use the provided vault ID as the Omnibus vault.
   * It will not create a new vault account in Fireblocks.
3. If `WITHDRAWAL_VAULTS` is empty:

   * The script will create three new vault accounts in Fireblocks named "Withdrawal Vault #1", "#2", and "#3".
   * It will create SOL\_TEST, ETH\_TEST5, and BTC\_TEST wallets in each of these vault accounts.
4. If `WITHDRAWAL_VAULTS` contains a comma-separated list of vault IDs:

   * The script will use these IDs as the withdrawal vaults.
   * It will not create new vault accounts in Fireblocks.

This flexibility allows you to either use existing vault accounts or let the application create new ones. If you're using existing vault accounts, make sure to set the appropriate IDs in the .env file before running the application for the first time.
**Important:** The setup script runs only once when the database is empty. If you need to re-run the setup, you'll need to clear the existing data from the database.

***

### Backend Application Details

This backend application showcases how to integrate Fireblocks' services into a typical retail-facing scenario. Key features include:

* User authentication (supports Local, Google, and GitHub)
* Wallet creation and management
* Asset creation and balance tracking
* Transaction processing
* WebSocket integration for real-time updates
* Integration with Fireblocks API for vault account and transaction management

For more detailed information, please refer to the [Backend README](https://github.com/fireblocks/retail-demo/tree/main/backend).

***

### Frontend Application Details

The frontend, named **FireX**, is a retail cryptocurrency demo platform built with Next.js and MobX, and integrated with Fireblocks for secure asset management. This project serves as a comprehensive reference for integrating Fireblocks into retail-facing applications.

**FireX** includes features such as a portfolio dashboard, multi-asset wallet management, and a transaction system with Fireblocks integration for secure transfers.

For more detailed information, please refer to the [Frontend README](https://github.com/fireblocks/retail-demo/tree/main/frontend).


# Retrieve NFTs
Source: https://developers.fireblocks.com/reference/retrieve-nfts



# Overview

Fireblocks enables retrieving and refreshing data related to all Non-Fungible Tokens (NFTs) listed in your vault accounts. This allows builders who want to present NFTs on their platform to use the data directly from the Fireblocks database, without the need to query an external node or IPFS for the metadata or media.

Given the different characteristics of fungible assets and NFTs, listing the NFTs owned by your vaults uses other endpoints than the ones used for listing your fungible assets.

# Managing NFTs

Currently, native NFT listing is enabled for tokens that implement ERC-721 or ERC-1155 standards, on the following blockchains.

| Blockchain | Chain   | Descriptor            |
| ---------- | ------- | --------------------- |
| Ethereum   | Mainnet | ETH                   |
| Ethereum   | Goerli  | ETH\_TEST3            |
| Polygon    | Mainnet | POLYGON               |
| Polygon    | Mumbai  | POLYGON\_TEST\_MUMBAI |

# Initial account synchronization

Customers with existing Fireblocks vault accounts can use the refresh function to sync their vault with NFTs not already stored in the Fireblocks database.

```javascript theme={"system"}
// Get vaults
const vaultAccounts = await fireblocks.getVaultAccountsWithPageInfo({});

console.log(inspect(vaultAccounts, false, null, true));

// Extract vault account ids
const vaultAccountsIds = vaultAccounts.accounts.map((va: any) => va.id);
console.log(inspect(vaultAccountsIds, false, null, true));

// Refresh tokens metadata per vault
for (const vaId of vaultAccountsIds) {
  try {
    await fireblocks.refreshNftOwnershipByVault({
      vaultAccountId: vaId,
      blockchainDescriptor: "ETH_TEST3",
    });
  } catch (e) {
    console.log(`Could not refresh vault vtId=${vtId}`);
  }
}
```

```python theme={"system"}
# Get vaults
vault_accounts = fireblocks.get_vault_accounts_with_page_info(
    PagedVaultAccountsRequestFilters()
)

# Extract vault account ids
vault_accounts_ids = [va.get("id") for va in vault_accounts.get("accounts")]
print(vault_accounts_ids)

# Refresh tokens metadata per vault
for va_id in vault_accounts_ids:
    try:
        fireblocks.refresh_nft_ownership_by_vault(
            vault_account_id=va_id,
            blockchain_descriptor="ETH_TEST3",
        )
    except FireblocksApiException:
        print(f"Could not refresh vault {vt_id=}")
```

# Listing NFTs

Users can list and retrieve metadata regarding the NFTs stored in their vault accounts.

```javascript theme={"system"}
const getNFTsList = async (
  blockchainDescriptor?: GetOwnershipTokensBlockchainDescriptorEnum,
  pageSize?: number,
): Promise<GetOwnershipTokens200Response | undefined> => {
  try {
    let nextPage: boolean = true;
    let pageCursor: string | undefined = "";

    // Fetch all owned tokens in workspace with their corresponding balance
    const ownedNFTs: GetOwnershipTokens200Response = (
      await fireblocks.nfts.getOwnershipTokens({
        blockchainDescriptor: blockchainDescriptor,
        pageSize: pageSize,
        pageCursor: pageCursor,
      })
    ).data;
    pageCursor = ownedNFTs.paging?.next;
    // iterate over all pages to fetch all NTFs
    while (nextPage) {
      const nextPageNFTs: GetOwnershipTokens200Response = (
        await fireblocks.nfts.getOwnershipTokens({
          blockchainDescriptor: blockchainDescriptor,
          pageSize: pageSize,
          pageCursor: pageCursor,
        })
      ).data;
      if (!nextPageNFTs.paging) {
        nextPage = false;
      } else {
        pageCursor = nextPageNFTs.paging?.next;
        nextPageNFTs.data?.forEach((item) => {
          ownedNFTs.data?.push(item);
        });
      }
    }
    console.log(
      JSON.stringify(ownedNFTs.data, null, 2),
      "\nNumber of NFTs: ",
      ownedNFTs.data?.length,
    );
    return ownedNFTs;
  } catch (e) {
    console.log(e);
  }
};
getNFTsList(); // add blockchainDescriptorEnum and/or pageSize to filter the response and set the results per page size
```

```javascript theme={"system"}
// Get vaults
const vaultAccounts = await fireblocks.getVaultAccountsWithPageInfo({});

// Extract vault account ids
const vaultAccountsIds = vaultAccounts.accounts.map((va: any) => va.id);
console.log(inspect(vaultAccountsIds, false, null, true));

// Fetch all owned tokens in tenant with their corresponding balance
const ownedNFTs = await fireblocks.getOwnedNFTs({
  vaultAccountIds: vaultAccountsIds,
  blockchainDescriptor: "POLYGON_TEST_MUMBAI",
});

console.log(inspect(ownedNFTs, false, null, true));
```

```python theme={"system"}
# Get vaults
vault_accounts = fireblocks.get_vault_accounts_with_page_info(
    PagedVaultAccountsRequestFilters()
)

# Extract vault account ids
vault_accounts_ids = [va.get("id") for va in vault_accounts.get("accounts")]
print(vault_accounts_ids)

# Fetch all owned tokens in tenant with their corresponding balance
print(
    fireblocks.get_owned_nfts(
        vault_account_ids=vault_accounts_ids,
        blockchain_descriptor="POLYGON_TEST_MUMBAI",
    )
)
```

# Refreshing a token's metadata

The metadata of some NFTs may change over time. To make sure an NFT has the most up-to-date metadata, call `refreshNFTMetadata` function

```javascript theme={"system"}
const refreshNFTsMetada = async (
  TokensBlockchainDescriptorEnum?: GetOwnershipTokensBlockchainDescriptorEnum,
) => {
  try {
    const ownedNFTs: GetOwnershipTokens200Response | undefined = (
      await fireblocks.nfts.getOwnershipTokens({
        blockchainDescriptor: TokensBlockchainDescriptorEnum,
      })
    ).data;

    // Extract NFT ids
    const nftIds: any[] | undefined =
      ownedNFTs.data?.map((nft: { id: string }) => nft.id) ?? [];

    // Refresh metadata for every ids
    for (const nftId of nftIds) {
      try {
        await fireblocks.nfts.refreshNFTMetadata(nftId);
      } catch (error) {
        console.log(`Could not refresh NFT metadata for ${nftId}`);
      }
    }
    console.log(`NFTs metadata was updated successfully!`);
  } catch (e) {
    console.error(e);
  }
};

refreshNFTsMetada(); // add TokensBlockchainDescriptorEnum to update the metada of NFTs only on a specific chain.
```

```javascript theme={"system"}
// Get vaults
const vaultAccounts = await fireblocks.getVaultAccountsWithPageInfo({});

// Filter for ids
const vaultAccountsIds = vaultAccounts.accounts.map((va: any) => va.id);
console.log(inspect(vaultAccountsIds, false, null, true));

// Fetch all owned tokens in tenant with their corresponding balance
const ownedNFTs = await fireblocks.getOwnedNFTs({
  vaultAccountIds: vaultAccountsIds,
  blockchainDescriptor: "POLYGON_TEST_MUMBAI",
});

// Extract NFT ids
const nftIds: string[] = ownedNFTs.data?.map((nft: { id: string; }) => nft.id) ?? [];

// Refresh metadata for every ids
for (const nftId of nftIds) {
  try {
    await fireblocks.refreshNFTMetadata(nftId);
  } catch (error) {
    console.log(`Could not refresh NFT metadata for ${nftId}`);
  }
}
```

```python theme={"system"}
# Get vaults
vault_accounts = fireblocks.get_vault_accounts_with_page_info(
    PagedVaultAccountsRequestFilters()
)

# Extract vault account ids
vault_accounts_ids = [va.get("id") for va in vault_accounts.get("accounts")]

# Fetch all owned tokens in tenant with their corresponding balance
nfts_data = fireblocks.get_owned_nfts(
    vault_account_ids=vault_accounts_ids,
    blockchain_descriptor="ETH_TEST3",
)

# Extract NFT ids
nft_ids = [nft_id.get("id") for nft_id in nfts_data.get("data", [])]

# Refresh metadata for every ids
for nft_id in nft_ids:
    try:
        fireblocks.refresh_nft_metadata(id=nft_id)
    except FireblocksApiException:
        print(f"Could not refresh NFT metadata for {nft_id=}")
```

# NFT webhook examples

The `TRANSACTION_CREATED` webhook shows that an NFT transaction was created and includes all the relevant transaction details.

> **Note**
>
> This webhook does not indicate that the NFT itself was created, only that a transaction using the specified NFT was created.

```json theme={"system"}
{
  "type": "TRANSACTION_CREATED",
  "tenantId": "00...00",
  "timestamp": 1685537055712,
  "data": {
    "id": "00...00",
    "createdAt": 1685537045477,
    "lastUpdated": 1685537045477,
    "assetId": "ETH_TEST3",
    "source": {
      "id": "34",
      "type": "VAULT_ACCOUNT",
      "name": "Vault 2",
      "subType": ""
    },
    "destination": {
      "id": "",
      "type": "ONE_TIME_ADDRESS",
      "name": "N/A",
      "subType": ""
    },
    "amount": 0,
    "netAmount": 0,
    "sourceAddress": "",
    "destinationAddress": "0x...00",
    "destinationAddressDescription": "",
    "destinationTag": "",
    "status": "SUBMITTED",
    "txHash": "",
    "subStatus": "",
    "signedBy": [],
    "createdBy": "00...00",
    "rejectedBy": "",
    "amountUSD": null,
    "addressType": "",
    "note": "Created by ",
    "exchangeTxId": "",
    "requestedAmount": 0,
    "feeCurrency": "ETH_TEST3",
    "operation": "CONTRACT_CALL",
    "amountInfo": {
      "amount": "0",
      "requestedAmount": "0",
      "netAmount": "0"
    },
    "feeInfo": {},
    "externalTxId": null,
    "blockInfo": {},
    "contractCallDecodedData": {
      "contractName": "SampleERC1155",
      "functionCalls": [
        {
          "name": "safeTransferFrom",
          "params": [
            {
              "name": "from",
              "type": "address",
              "value": "0x...00"
            },
            {
              "name": "to",
              "type": "address",
              "value": "0x...00"
            },
            {
              "name": "id",
              "type": "uint256",
              "value": "676"
            },
            {
              "name": "amount",
              "type": "uint256",
              "value": "3"
            },
            {
              "name": "data",
              "type": "bytes",
              "value": "0x00"
            }
          ],
          "payloadSuffix": ""
        }
      ]
    },
    "extraParameters": {
      "contractCallData": "0x...00"
    }
  }
}
```

The `TRANSACTION_STATUS_UPDATED` webhook shows the NFT transaction's most recent status in the transaction flow.

```json theme={"system"}
{
  "type": "TRANSACTION_STATUS_UPDATED",
  "tenantId": "00...00",
  "timestamp": 1685537118476,
  "data": {
    "id": "00...00",
    "createdAt": 1685537045477,
    "lastUpdated": 1685537108198,
    "assetId": "ETH_TEST3",
    "source": {
      "id": "34",
      "type": "VAULT_ACCOUNT",
      "name": "Vault 2",
      "subType": ""
    },
    "destination": {
      "id": "",
      "type": "ONE_TIME_ADDRESS",
      "name": "N/A",
      "subType": ""
    },
    "amount": 0,
    "networkFee": 0.004458229302275784,
    "netAmount": 0,
    "sourceAddress": "",
    "destinationAddress": "0x...00",
    "destinationAddressDescription": "",
    "destinationTag": "",
    "status": "COMPLETED",
    "txHash": "0x...00",
    "subStatus": "CONFIRMED",
    "signedBy": [],
    "createdBy": "00...00",
    "rejectedBy": "",
    "amountUSD": 0,
    "addressType": "",
    "note": "Created by ",
    "exchangeTxId": "",
    "requestedAmount": 0,
    "feeCurrency": "ETH_TEST3",
    "operation": "CONTRACT_CALL",
    "numOfConfirmations": 3,
    "amountInfo": {
      "amount": "0",
      "requestedAmount": "0",
      "netAmount": "0",
      "amountUSD": null
    },
    "feeInfo": {
      "networkFee": "0.004458229302275784",
      "gasPrice": "76.16217886899999"
    },
    "externalTxId": null,
    "blockInfo": {
      "blockHeight": "0...0",
      "blockHash": "00...00"
    },
    "contractCallDecodedData": {
      "contractName": "SampleERC1155",
      "functionCalls": [
        {
          "name": "safeTransferFrom",
          "params": [
            {
              "name": "from",
              "type": "address",
              "value": "0x...00"
            },
            {
              "name": "to",
              "type": "address",
              "value": "0x...00"
            },
            {
              "name": "id",
              "type": "uint256",
              "value": "676"
            },
            {
              "name": "amount",
              "type": "uint256",
              "value": "3"
            },
            {
              "name": "data",
              "type": "bytes",
              "value": "0x00"
            }
          ],
          "payloadSuffix": ""
        }
      ]
    },
    "networkRecords": [
      {
        "source": {
          "id": "34",
          "type": "VAULT_ACCOUNT",
          "name": "Vault 2",
          "subType": ""
        },
        "destination": {
          "id": "",
          "type": "ONE_TIME_ADDRESS",
          "name": "N/A",
          "subType": ""
        },
        "txHash": "0x...00",
        "networkFee": "0.004458229302275784",
        "assetId": "NFT-00...00",
        "netAmount": "3",
        "isDropped": false,
        "type": "CONTRACT_CALL",
        "destinationAddress": "0x...00",
        "amountUSD": null
      },
      {
        "source": {
          "id": "34",
          "type": "VAULT_ACCOUNT",
          "name": "Vault 2",
          "subType": ""
        },
        "destination": {
          "id": "",
          "type": "ONE_TIME_ADDRESS",
          "name": "N/A",
          "subType": ""
        },
        "txHash": "0x...00",
        "networkFee": "0.004458229302275784",
        "assetId": "ETH_TEST3",
        "netAmount": "0.000000000000000000",
        "isDropped": false,
        "type": "CONTRACT_CALL",
        "destinationAddress": "0x...00",
        "amountUSD": "0.00"
      }
    ],
    "signedMessages": [],
    "extraParameters": {
      "contractCallData": "0x...00"
    },
    "assetType": "BASE_ASSET"
  }
}
```


# SDK Migration Guide
Source: https://developers.fireblocks.com/reference/sdk-migration-guide



Learn how to migrate to the latest version of the Fireblocks SDK.

We've upgraded the Fireblocks SDKs to enhance performance and streamline integration. To ensure uninterrupted functionality, we strongly recommend migrating to the new SDK as soon as possible. Migrating will give you access to the latest features, optimized performance, and ongoing support.

This document will help you to:

* Understand the latest features and improvements
* Map changes between the legacy and new SDKs
* Complete the migration to the new SDKs with actionable steps

<Warning>
  ### Migrate now to avoid disruptions and keep access to features and updates

  The legacy SDKs are being deprecated in phases, reducing its functionality and support over time. Here are important dates to remember:

  * **February 15, 2025:** Legacy SDKs enter maintenance mode. No new API endpoints will be added, and only critical bug fixes will be provided.
  * **August 1, 2026:** Legacy SDKs reach end-of-life (EOL). No further updates, bug fixes, or support will be provided, and the SDK will no longer be actively maintained.
</Warning>

## Key improvements

* **Fully Typed:** Reduces runtime errors and improves code reliability.
* **Complete API Alignment:** Fully consistent with the API specification.
* **Inline Guidance:** Provides detailed descriptions for function arguments.
* **Code Samples:** Includes practical examples for every function.
* **Comprehensive Documentation:** Clear and detailed resources, including method explanations and HTTP request structures.

## Key actions for migration

1. **Upgrade your environment:**
   1. Update your Python to **3.8 or newer** for the latest Python SDK
   2. Upgrade to **Node.js v16 or newer** for the latest TypeScript SDK.
2. **Install the latest SDK versions:** Ensure you have the latest SDK packages by checking all the relevant links for each SDK.
   1. [TypeScript SDK](/reference/typescript-sdk)
      1. Please note that the new TS SDK does *NOT* include PII encryption.
   2. [Java SDK](/reference/java-sdk)
   3. [Python SDK](/reference/new-python-sdk)
3. **Update your codebase:** Replace the outdated methods with the new ones [here](/reference/new-python-sdk).
4. **Get support if needed:** Reach out to your Customer Success Manager (CSM) or Fireblocks Support if you experience any migration issues.

## GitHub repository mapping: Legacy to New

| Legacy SDK                                                                        | New SDK                                                           |
| :-------------------------------------------------------------------------------- | :---------------------------------------------------------------- |
| [Fireblocks JS SDK (Legacy)](https://github.com/fireblocks/fireblocks-sdk-js)     | [Fireblocks TypeScript SDK](https://github.com/fireblocks/ts-sdk) |
| [Fireblocks Python SDK (Legacy)](https://github.com/fireblocks/fireblocks-sdk-py) | [Fireblocks Python SDK](https://github.com/fireblocks/py-sdk)     |

## SDK mapping: JS SDK (Legacy) to New TypeScript SDK

<SdkMigrationTable />

## SDK Mapping: Python (Legacy) to New Python SDK

<SdkMigrationTable />

## FAQs

### Why are the current SDKs being deprecated?

The legacy SDKs are being phased out to provide a more reliable, efficient, and developer-friendly experience through our new SDKs. The new versions are fully typed, better aligned with our API, and include improved documentation and inline guidance.

### Can I continue using the legacy SDKs after August 1, 2026?

Yes, but we strongly advise against it. The SDKs will no longer be maintained, which may result in security risks, compatibility issues, and a lack of support, potentially impacting your application.

### Which programming languages are supported in the new SDKs?

We offer SDKs for TypeScript, Python, and Java. Developers using other languages should integrate directly with our API.

### What happens if I don't migrate before August 1, 2026?

If you continue using the legacy SDKs:

* It will no longer receive updates or bug fixes
* Security vulnerabilities may arise over time
* New API endpoints and features will not be available
* Fireblocks Support will no longer assist with issues related to the legacy SDKs

### Will Fireblocks Support provide extended support for the legacy SDKs?

No. There will be no extended support after August 1, 2026. To avoid any disruptions, migrate as soon as possible.


# SDK - Multichain Deployment
Source: https://developers.fireblocks.com/reference/sdk-multichain-deployment



# What is a Multichain Deployment?

The Multichain Deployment feature in Fireblocks allows you to deploy the same smart contract to the same address across multiple EVM-compatible blockchain networks, all in one streamlined UI flow.

> **Note:**
>
> This feature is currently available only for EVM chains.

This is particularly useful when:

* Maintaining identical contract addresses on different networks (for example, Ethereum, Arbitrum, or Polygon) for seamless cross-chain integration.
* Having your dApp, token, or protocol rely on a consistent contract address to simplify frontends, indexers, or backend services.
* Reducing complexity for developers, indexers, and frontend apps by using a single contract address across all chains.
* Improving user experience: Users interacting with your protocol on different chains do not have to deal with varying addresses.

Fireblocks utilizes a deterministic deployment mechanism to ensure the same address across blockchains. To perform a multichain deployment, use the Fireblocks SDK to select the chains where the contract will be deployed. As long as you have enough gas on each selected network, deployment proceeds simultaneously.

# Multichain Deployment using the Fireblocks SDK

## Step 1: Install dependencies & bootstrap the SDK

1. Add packages:

   <img alt="" />

2. Create .env and store the public and private key of your api-user:

   <img alt="" />

3. Initialize the client:

   <img alt="" />

## Step 2: Define the deployment scope

### Fields:

* **contractId** - ensure the contract template is uploaded, and you have the `templateId` from the template.
* **deployerVaultAccountId** - the `deployerVaultAccountId` that will deploy the tokens. Ensure the vault has sufficient native gas for transaction fees. Use the [Get Vault Accounts endpoint](/reference/getpagedvaultaccounts) to retrieve the correct vault account ID.
* **targetChains** - the Fireblocks asset IDs for each network you are deploying to (for example, ETH\_TEST5).
* **feeLevel** - the gas-price tier for broadcasting each deployment transaction..

<img alt="" />

## Step 3: Build the CreateMultichainTokenRequest

<img alt="" />

<img alt="" />

### What each block does

* **\_logic** – points the proxy to your implementation contract.
* **\_data** – packs the proxy’s initialize() call to create a name, symbol, and set roles for the ERC-20F deployment.

### What deployFunctionParams represents

The deployFunctionParams represents the list of constructor/initializer arguments that Fireblocks will pass to the specific contract template you picked. For an upgradeable proxy you usually see two items (\_logic and \_data). For a non-upgradeable contract, you might have one, three, or zero items, depending on the template’s ABI requirements. Always adjust the entire **deployFunctionParams** array—the field names, types, order, and values—to match the constructor or initializer of the contract you’re deploying. For instructions on finding the initializer’s parameters, see “**Highlights**” in this [guide](/reference/issue-new-erc-20f-tokens#highlights).

## Step 4: Submit & monitor the deployment

<img alt="" />

### On Success:

Once deployment is complete, you can view your deployed contracts in the Fireblocks Console on the Tokenization page, in the Tokens and Contracts section, or use the [Get Deployed Contracts endpoint](/reference/getdeployedcontracts). You can also track the status of each deployment in the Recent Activity tab. In this example, we deployed to Ethereum Holesky and Ethereum Sepolia. Both deployments share the same contract address, confirming a successful multichain deployment.

**Deployed Contracts:**

* [Ethereum Holesky Contract](https://holesky.etherscan.io/address/0x24810534B24e3927152C1B814A9B25EC4AEff29B)
* [Ethereum Sepolia Contract](https://sepolia.etherscan.io/address/0x24810534B24e3927152C1B814A9B25EC4AEff29B)

<img alt="" />

## Important deployment information

Before proceeding with a multichain deployment, keep the following in mind:

* You need gas for transaction fees on every selected network. Ensure the deployer wallet has enough of each base asset (for example, ETH, MATIC) on each chain to cover deployment costs. Being unable to pay transaction fees will block deployment.
* Deployment is pre-validated across all chains. Fireblocks runs simulations before executing transactions. If any chain is predicted to fail, the deployment will not proceed for any chain. This guarantees consistency across your selected networks.
* Transactions must be signed per chain. Even though the deployment is unified, a separate transaction must be signed for each chain. Expect multiple signing prompts during execution.
* Inputs apply uniformly across all chains. Deployment parameters, such as token name, symbol, supply, and roles (this includes the minter address), are shared across all selected networks. You cannot customize them per chain. If different parameters are required per network, you need to deploy each token contract separately,and the contract address will differ.

## Additional SDK capability – getDeployableAddress

You can predict the contract address before broadcasting using the getDeployableAddress endpoint. This uses the initializer and salt in issueTokenMultiChain() to compute the deterministic address that a template will deploy to. After following Steps 1-3 above, call tokenization.getDeployableAddress().

<img alt="" />

### Fields

* **templateId** - the contract template ID you will deploy.
* **initParams** - the exact deployFunctionParams array from Step 3.
* **chainDescriptor** - the Fireblocks asset IDs of the network you are deploying to (for example . ETH\_TEST5).
* **salt** - any arbitrary whole number that becomes part of the deterministic calculation and therefore fixes the resulting contract address.

Knowing the address ahead of time lets you pre-whitelist or publish it before the actual *issueTokenMultiChain()* call.


# Select UTXOs
Source: https://developers.fireblocks.com/reference/select-utxos-for-a-transaction



Manual UTXO selection lets you control which unspent transaction outputs (UTXOs) are spent in a transaction, instead of relying on the default selection logic. Use it to send only from UTXOs that match criteria such as label, amount, or address, or to manage funds across multiple clients with precision.

> **Note: Beta endpoints** — The UTXO labeling and listing endpoints, and the `utxoSelectionParams` field on Create Transaction, are in beta and may change. Supported assets: BTC, LTC, DOGE, BCH. To request access, contact your Customer Success Manager.

## How UTXO selection works

UTXO selection has three building blocks. You can use them independently or in combination:

* **Labels** are arbitrary strings you attach to UTXOs (for example, `client-a` or `counterparty`). You can use them later as filter criteria.
* **Filters** narrow a set of UTXOs by label, amount, address, and other attributes. Filters work both in the listing endpoint and inside `utxoSelectionParams` when you create a transaction.
* **Explicit selection** lets you specify exact UTXOs to spend by `txHash` and `vout`.

When you create a transaction with `utxoSelectionParams`, you can pass either filters, an explicit selection, or both. When you pass both, Fireblocks spends the explicit picks first and uses filters to select any additional UTXOs needed to cover the fee, if `fillFeeForSelectedInputs` is set to `true`.

## API reference

| Endpoint                                                                       | Description                                                                                                                                                                                                                                                 |
| :----------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Label UTXOs — `PATCH /utxo_management/{vaultAccountId}/{assetId}/labels`       | Attach or detach labels on UTXOs. Identify UTXOs by `{txHash, vout}` or `{txId}`. Up to 200 UTXOs and 5 labels per request. [Endpoint reference](https://developers.fireblocks.com/reference/label-utxos)                                                   |
| List UTXOs — `GET /utxo_management/{vaultAccountId}/{assetId}/unspent_outputs` | Paginated, filterable listing of unspent outputs. Filter by labels, amount range, address, status, change/coinbase. Default page size 50, max 250. [Endpoint reference](https://developers.fireblocks.com/reference/list-unspent-outputs)                   |
| Create Transaction — `POST /transactions`                                      | New `utxoSelectionParams` field for server-side UTXO filtering (`filters`) and explicit UTXO picks (`inputSelection`). [Endpoint reference](https://developers.fireblocks.com/reference/create-a-new-transaction)                                           |
| Estimate Transaction Fee — `POST /transactions/estimate_fee`                   | New `utxoSelectionParams` field for server-side UTXO filtering (`filters`) and explicit UTXO picks (`inputSelection`). [Endpoint reference](https://developers.fireblocks.com/api-reference/transactions/estimate-transaction-fee#estimate-transaction-fee) |

## Label UTXOs

Attach or detach labels by identifying UTXOs with `{txHash, vout}` or `{txId}`.

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  import { Fireblocks } from "@fireblocks/ts-sdk";

  const fireblocks = new Fireblocks();

  await fireblocks.utxoManagementBeta.updateUtxoLabels({
    vaultAccountId: "0",
    assetId: "BTC",
    attachDetachUtxoLabelsRequest: {
      utxoIdentifiers: [{ txHash: "abc123...def", vout: 0 }],
      labelsToAttach: ["counterparty"],
    },
  });
  ```

  ```python Python theme={"system"}
  from fireblocks.client import Fireblocks

  fireblocks = Fireblocks()

  fireblocks.utxo_management_beta.update_utxo_labels(
      vault_account_id="0",
      asset_id="BTC",
      attach_detach_utxo_labels_request={
          "utxo_identifiers": [{"tx_hash": "abc123...def", "vout": 0}],
          "labels_to_attach": ["counterparty"],
      },
  ).result()
  ```

  ```java Java theme={"system"}
  Fireblocks fireblocks = new Fireblocks();

  fireblocks.utxoManagementBeta().updateUtxoLabels(
      "0",
      "BTC",
      new AttachDetachUtxoLabelsRequest()
          .utxoIdentifiers(List.of(new UtxoIdentifier().txHash("abc123...def").vout(0)))
          .labelsToAttach(List.of("counterparty")),
      null  // idempotencyKey
  ).get();
  ```
</CodeGroup>

## List UTXOs

Retrieve a paginated list of unspent outputs for a vault account and asset. Filter by labels, amount range, address, status, and change/coinbase.

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  const { data: utxoList } = await fireblocks.utxoManagementBeta.getUtxos({
    vaultAccountId: "0",
    assetId: "BTC",
    includeAnyLabels: ["counterparty"],
  });

  utxoList.data.forEach((utxo) => {
    console.log(utxo.input.txHash, utxo.input.index, utxo.amount, utxo.address);
  });
  ```

  ```python Python theme={"system"}
  api_response = fireblocks.utxo_management_beta.get_utxos(
      vault_account_id="0",
      asset_id="BTC",
      include_any_labels=["counterparty"],
  ).result()

  for utxo in api_response.data.data:
      print(utxo.input.tx_hash, utxo.input.index, utxo.amount, utxo.address)
  ```

  ```java Java theme={"system"}
  ListUtxosResponse utxoList = fireblocks.utxoManagementBeta().getUtxos(
      "0",                // vaultAccountId
      "BTC",              // assetId
      null,               // pageCursor
      null,               // pageSize
      null,               // sort
      null,               // order
      null,               // includeAllLabels
      List.of("counterparty"),  // includeAnyLabels
      null,               // excludeAnyLabels
      null,               // includeStatuses
      null,               // address
      null,               // minAmount
      null,               // maxAmount
      null,               // useChange
      null                // useCoinbase
  ).get().getData();

  for (UtxoOutput utxo : utxoList.getData()) {
      System.out.println(utxo.getInput().getTxHash() + " " + utxo.getInput().getIndex()
          + " " + utxo.getAmount() + " " + utxo.getAddress());
  }
  ```
</CodeGroup>

## Select UTXOs in a transaction

The `utxoSelectionParams` field on Create Transaction has two subfields:

* `filters` — server-side filter criteria. Fireblocks selects UTXOs that match.
* `inputSelection` — an explicit list of UTXOs to spend. Set `fillFeeForSelectedInputs: true` to let Fireblocks add more UTXOs (subject to `filters`) if the selected inputs don't cover the fee.

> **Note:** `utxoSelectionParams` replaces the previous `extraParameters.inputsSelection` field. You can still use `extraParameters.inputsSelection` in requests, but you cannot use both fields together or the transaction will fail.

### Example: Send from labeled UTXOs above a minimum amount

When you manage funds for multiple clients using labels, you can send from UTXOs labeled for specific clients without picking them manually. Filters alone are enough — Fireblocks selects matching UTXOs that cover the transaction amount.

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  import { Fireblocks, TransferPeerPathType } from "@fireblocks/ts-sdk";

  const fireblocks = new Fireblocks();

  const { data: tx } = await fireblocks.transactions.createTransaction({
    transactionRequest: {
      assetId: "BTC",
      amount: "0.5",
      source: { type: TransferPeerPathType.VaultAccount, id: "0" },
      destination: {
        type: TransferPeerPathType.OneTimeAddress,
        oneTimeAddress: { address: "bc1q..." },
      },
      utxoSelectionParams: {
        filters: {
          includeAnyLabels: ["client-a", "client-b"],
          minAmount: "0.1",
        },
      },
    },
  });
  ```

  ```python Python theme={"system"}
  from fireblocks.client import Fireblocks
  from fireblocks.models.transfer_peer_path_type import TransferPeerPathType

  fireblocks = Fireblocks()

  api_response = fireblocks.transactions.create_transaction(
      transaction_request={
          "asset_id": "BTC",
          "amount": "0.5",
          "source": {"type": TransferPeerPathType.VAULT_ACCOUNT, "id": "0"},
          "destination": {
              "type": TransferPeerPathType.ONE_TIME_ADDRESS,
              "one_time_address": {"address": "bc1q..."},
          },
          "utxo_selection_params": {
              "filters": {
                  "include_any_labels": ["client-a", "client-b"],
                  "min_amount": "0.1",
              },
          },
      }
  ).result()
  ```

  ```java Java theme={"system"}
  Fireblocks fireblocks = new Fireblocks();

  TransactionRequest request = new TransactionRequest()
      .assetId("BTC")
      .amount(new TransactionRequestAmount("0.5"))
      .source(new SourceTransferPeerPath()
          .type(TransferPeerPathType.VAULT_ACCOUNT).id("0"))
      .destination(new DestinationTransferPeerPath()
          .type(TransferPeerPathType.ONE_TIME_ADDRESS)
          .oneTimeAddress(new OneTimeAddress().address("bc1q...")))
      .utxoSelectionParams(new UtxoSelectionParams()
          .filters(new UtxoSelectionFilters()
              .includeAnyLabels(List.of("client-a", "client-b"))
              .minAmount("0.1")));

  fireblocks.transactions().createTransaction(request, null, null).get();
  ```
</CodeGroup>

### Example: Drain a specific address and pay fees from another address (same vault)

A common pattern for omnibus vault operators: transfer the full balance of a specific customer address and have the network fee paid by a different address in the same vault (a dedicated "gas station" address). This keeps the customer's transaction clean on the block explorer — no extra fee-related transfers.

The flow:

1. Call List UTXOs filtered by the customer's address to get all their unspent outputs.
2. Sum the UTXO amounts to get the transfer amount.
3. Call Create Transaction with `inputsToSpend` set to those UTXOs and `fillFeeForSelectedInputs: true`. Fireblocks automatically picks additional UTXOs from other addresses in the vault to cover the fee.

Optionally, use `filters` to restrict which UTXOs Fireblocks can pick for fee coverage (for example, only UTXOs labeled `gas-station`).

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  import { Fireblocks, TransferPeerPathType } from "@fireblocks/ts-sdk";

  const fireblocks = new Fireblocks();

  const VAULT_ID = "0";
  const ASSET_ID = "BTC";
  const CUSTOMER_ADDRESS = "bc1q...customer";
  const DESTINATION_ADDRESS = "bc1q...destination";

  // Step 1: List all UTXOs for the customer's address
  const { data: utxoList } = await fireblocks.utxoManagementBeta.getUtxos({
    vaultAccountId: VAULT_ID,
    assetId: ASSET_ID,
    address: CUSTOMER_ADDRESS,
    pageSize: 250,
  });

  const utxos = utxoList.data;
  if (!utxos || utxos.length === 0) {
    throw new Error(`No UTXOs found for address ${CUSTOMER_ADDRESS}`);
  }

  // Step 2: Calculate total amount and build inputsToSpend
  const totalAmount = utxos
    .reduce((sum, u) => sum + parseFloat(u.amount), 0)
    .toString();

  const inputsToSpend = utxos.map((u) => ({
    txHash: u.input.txHash,
    vout: u.input.index,
  }));

  // Step 3: Create transaction — drain the address, fee paid by other UTXOs in the vault
  const { data: tx } = await fireblocks.transactions.createTransaction({
    transactionRequest: {
      assetId: ASSET_ID,
      amount: totalAmount,
      source: { type: TransferPeerPathType.VaultAccount, id: VAULT_ID },
      destination: {
        type: TransferPeerPathType.OneTimeAddress,
        oneTimeAddress: { address: DESTINATION_ADDRESS },
      },
      utxoSelectionParams: {
        inputSelection: {
          inputsToSpend,
          fillFeeForSelectedInputs: true,
        },
        // Optional: restrict fee-covering UTXOs to a labeled pool
        // filters: { includeAllLabels: ["gas-station"] },
      },
    },
  });

  console.log(`Transaction ${tx.id} — status: ${tx.status}`);
  ```

  ```python Python theme={"system"}
  from fireblocks.client import Fireblocks
  from fireblocks.models.transfer_peer_path_type import TransferPeerPathType

  fireblocks = Fireblocks()

  VAULT_ID = "0"
  ASSET_ID = "BTC"
  CUSTOMER_ADDRESS = "bc1q...customer"
  DESTINATION_ADDRESS = "bc1q...destination"

  # Step 1: List all UTXOs for the customer's address
  api_response = fireblocks.utxo_management_beta.get_utxos(
      vault_account_id=VAULT_ID,
      asset_id=ASSET_ID,
      address=CUSTOMER_ADDRESS,
      page_size=250,
  ).result()

  utxos = api_response.data.data
  if not utxos:
      raise Exception(f"No UTXOs found for address {CUSTOMER_ADDRESS}")

  # Step 2: Calculate total amount and build inputs_to_spend
  total_amount = sum(float(u.amount) for u in utxos)
  inputs_to_spend = [
      {"tx_hash": u.input.tx_hash, "vout": u.input.index}
      for u in utxos
  ]

  # Step 3: Create transaction — drain the address, fee paid by other UTXOs in the vault
  api_response = fireblocks.transactions.create_transaction(
      transaction_request={
          "asset_id": ASSET_ID,
          "amount": str(total_amount),
          "source": {"type": TransferPeerPathType.VAULT_ACCOUNT, "id": VAULT_ID},
          "destination": {
              "type": TransferPeerPathType.ONE_TIME_ADDRESS,
              "one_time_address": {"address": DESTINATION_ADDRESS},
          },
          "utxo_selection_params": {
              "input_selection": {
                  "inputs_to_spend": inputs_to_spend,
                  "fill_fee_for_selected_inputs": True,
              },
              # Optional: restrict fee-covering UTXOs to a labeled pool
              # "filters": {"include_all_labels": ["gas-station"]},
          },
      }
  ).result()

  print(f"Transaction {api_response.data.id} — status: {api_response.data.status}")
  ```

  ```java Java theme={"system"}
  import com.fireblocks.sdk.Fireblocks;
  import com.fireblocks.sdk.model.*;
  import java.util.List;
  import java.util.stream.Collectors;

  Fireblocks fireblocks = new Fireblocks();

  String VAULT_ID = "0";
  String ASSET_ID = "BTC";
  String CUSTOMER_ADDRESS = "bc1q...customer";
  String DESTINATION_ADDRESS = "bc1q...destination";

  // Step 1: List all UTXOs for the customer's address
  ListUtxosResponse utxoList = fireblocks.utxoManagementBeta().getUtxos(
      VAULT_ID,           // vaultAccountId
      ASSET_ID,           // assetId
      null,               // pageCursor
      250,                // pageSize
      null,               // sort
      null,               // order
      null,               // includeAllLabels
      null,               // includeAnyLabels
      null,               // excludeAnyLabels
      null,               // includeStatuses
      CUSTOMER_ADDRESS,   // address
      null,               // minAmount
      null,               // maxAmount
      null,               // useChange
      null                // useCoinbase
  ).get().getData();

  List<UtxoOutput> utxos = utxoList.getData();
  if (utxos == null || utxos.isEmpty()) {
      throw new RuntimeException("No UTXOs found for address " + CUSTOMER_ADDRESS);
  }

  // Step 2: Calculate total amount and build inputsToSpend
  double totalAmount = utxos.stream()
      .mapToDouble(u -> Double.parseDouble(u.getAmount()))
      .sum();

  List<UtxoInput> inputsToSpend = utxos.stream()
      .map(u -> new UtxoInput()
          .txHash(u.getInput().getTxHash())
          .vout(u.getInput().getIndex()))
      .collect(Collectors.toList());

  // Step 3: Create transaction — drain the address, fee paid by other UTXOs in the vault
  TransactionRequest request = new TransactionRequest()
      .assetId(ASSET_ID)
      .amount(new TransactionRequestAmount(String.valueOf(totalAmount)))
      .source(new SourceTransferPeerPath()
          .type(TransferPeerPathType.VAULT_ACCOUNT).id(VAULT_ID))
      .destination(new DestinationTransferPeerPath()
          .type(TransferPeerPathType.ONE_TIME_ADDRESS)
          .oneTimeAddress(new OneTimeAddress().address(DESTINATION_ADDRESS)))
      .utxoSelectionParams(new UtxoSelectionParams()
          .inputSelection(new UtxoInputSelection()
              .inputsToSpend(inputsToSpend)
              .fillFeeForSelectedInputs(true))
          // Optional: restrict fee-covering UTXOs to a labeled pool
          // .filters(new UtxoSelectionFilters().includeAllLabels(List.of("gas-station")))
      );

  CreateTransactionResponse tx = fireblocks.transactions()
      .createTransaction(request, null, null).get().getData();

  System.out.printf("Transaction %s — status: %s%n", tx.getId(), tx.getStatus());
  ```
</CodeGroup>

Key points:

* `fillFeeForSelectedInputs: true` tells Fireblocks to use the specified UTXOs for the transfer amount, and to automatically select additional UTXOs from the vault to cover the network fee.
* Without this flag, if the specified UTXOs don't have enough to cover both the amount and the fee, the transaction fails.

## Field reference

| Field                                | Used in                                   | Description                                                                                                                                                     |
| :----------------------------------- | :---------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `utxoIdentifiers`                    | Label UTXOs                               | Array identifying the UTXOs to label. Each entry is `{txHash, vout}` or `{txId}`.                                                                               |
| `labelsToAttach`                     | Label UTXOs                               | Array of label strings to attach to the identified UTXOs.                                                                                                       |
| `labelsToDetach`                     | Label UTXOs                               | Array of label strings to detach from the identified UTXOs.                                                                                                     |
| `txHash / vout`                      | UTXO identifiers                          | `txHash` is the transaction hash; `vout` is the output index within that transaction. `txId` is accepted as an alternative identifier in labeling requests.     |
| `includeAllLabels`                   | List UTXOs, `utxoSelectionParams.filters` | Array of labels. Matches UTXOs that carry **all** of the listed labels (AND logic). Use when you need every label to be present.                                |
| `includeAnyLabels`                   | List UTXOs, `utxoSelectionParams.filters` | Array of labels. Matches UTXOs that carry **at least one** of the listed labels (OR logic).                                                                     |
| `excludeAnyLabels`                   | List UTXOs, `utxoSelectionParams.filters` | Array of labels. Excludes UTXOs that carry any of the listed labels.                                                                                            |
| `utxoSelectionParams`                | Create Transaction                        | Container for UTXO selection criteria. Replaces `extraParameters.inputsSelection`.                                                                              |
| `utxoSelectionParams.filters`        | Create Transaction                        | Server-side filter criteria. Supported sub-fields include `address`, `minAmount`, `includeAllLabels`, and `includeAnyLabels`.                                   |
| `utxoSelectionParams.inputSelection` | Create Transaction                        | Explicit UTXO picks. Spent first, before any filter-based selection.                                                                                            |
| `inputsToSpend`                      | `inputSelection`                          | Array of UTXOs to spend explicitly. Each entry is `{txHash, vout}`.                                                                                             |
| `fillFeeForSelectedInputs`           | `inputSelection`                          | When `true`, Fireblocks adds more UTXOs (subject to `filters`) if the explicit selection doesn't cover the fee. Requires at least one entry in `inputsToSpend`. |


# Setting Up Roles in ERC20F Tokens
Source: https://developers.fireblocks.com/reference/setting-up-roles-in-erc20f-tokens



In this guide, we will walk you through how to set up roles for your ERC20F token. This is necessary because the ERC20F contract uses [Role-Based Access Control (RBAC)](https://docs.openzeppelin.com/contracts/4.x/access-control#role-based-access-control) for security purposes. RBAC ensures that specific actions within the contract, such as minting or pausing tokens, can only be performed by authorized accounts assigned to specific roles.

## What is RBAC?

Role-Based Access Control (RBAC) is a security model that restricts access to certain functionalities of a system based on roles assigned to users. In the context of the ERC20F token, RBAC ensures that only addresses with the appropriate roles—such as `DEFAULT_ADMIN_ROLE`, `MINTER_ROLE`, `PAUSER_ROLE`, and others—can perform actions like granting roles, minting and pausing or pausing the token. This approach enhances both security and flexibility by limiting critical operations to trusted parties.

## Prerequisites

Before granting roles to addresses, you need to have the following:

1. **ERC20F Contract Address**: The address of the ERC20F token contract you want to manage.
2. **Vault Account:** The `vaultAccountId` that will grant roles and manage the token. This account must have the`DEFAULT_ADMIN_ROLE` in the ERC20F contract. Ensure the vault has sufficient native gas for transaction fees. You can retrieve the vaultAccountId from the Fireblocks console by checking the URL of the selected vault, e.g., `https://console.fireblocks.io/v2/accounts/vault/<vaultAccountId>`. For more details about Vault Accounts, refer to the [Create Vault Account guide](/reference/create-vault-account).
3. **Implementation Contract ABI:** The `ABI` of the implementation contract of the ERC20F token. This is required to interact with the token contract. For more details about how to retrieve the ABI, refer to the [Issue New ERC20F Tokens guide](/reference/issue-new-erc-20f-tokens).
4. **Base Asset ID:** The `baseAssetId` of the blockchain where the token is deployed (e.g. ETH\_TEST5 for Sepolia). This is the Fireblocks ID of the gas token of the blockchain where the token is deployed. (To get the base asset ID, refer to this [base assetId list](https://support.fireblocks.io/hc/en-us/articles/8993656344092-Supported-blockchain-networks))

With these in place, you can use the Fireblocks SDK to set up roles for your ERC20F token.

## Example: Setting Up Roles in ERC20F Token

Here's an example of how to set up roles in an ERC20F token using the Fireblocks SDK:

### 1. Initialize the Fireblocks SDK

First, import the Fireblocks SDK and initialize the SDK with your Fireblocks API key and private key:

```javascript theme={"system"}
import {
    Fireblocks,
    BasePath,
} from '@fireblocks/ts-sdk';

const privateKey = '...'; // Your Fireblocks API private key
const apiKey = '...'; // Your Fireblocks API key

const fireblocksSdk = new Fireblocks({
    apiKey,
    basePath: BasePath.US, // Use BasePath.EU for the EU region
    secretKey: privateKey,
});
```

### 2. Read role hash

In order to assign or manage roles in the ERC20F token contract, you need the unique identifier (hash) for each role, such as `MINTER_ROLE`. This identifier allows the contract to distinguish between different roles. You can find the supported roles in the contract’s ABI.

For this example, we will retrieve the hash of the `MINTER_ROLE`. Once you locate the role in the ABI, you can use the `readCallFunction` method from the Fireblocks SDK to retrieve the role’s hash, which will be used in the next steps to grant the role to specific addresses.

Here’s an example:

```javascript theme={"system"}
   let minterRoleBytesRequest: ContractInteractionsApiReadCallFunctionRequest = {
    readCallFunctionDto: {
        abiFunction: {
            "name": "MINTER_ROLE",
            "type": "function",
            "inputs": [],
            "outputs": [
                {
                    "name": "",
                    "type": "bytes32",
                    "internalType": "bytes32"
                }
            ],
            "stateMutability": "view"
        },
    },
    assetId: 'ETH_TEST5', // Fireblocks asset ID
    contractAddress: '0x549E73A4aDF85757BD5Aa170cFb51cd6bBBafBb0', // Address of the ERC20F contract
}
let response = await fireblocksSdk.contractInteractions.readCallFunction(minterRoleBytesRequest);
console.log('Response:', response);
let minterRoleBytes = response.data[0].value;
console.log('Minter Role Bytes:', minterRoleBytes);
```

### 3. Grant Role to Address

First we need to define the variables for the role grant:

* `granteeAddress`: The address to which you want to grant the role.
* `roleBytes`: The role hash retrieved in the previous step.

Example:

```javascript theme={"system"}
const roleBytes = '0x9f2df0fed2c77648de5860a4cc508cd0818c85b8b8a1ab4ceeef8d981c8956a6'; // MINTER_ROLE bytes
const granteeAddress = '0x1234567890123456789012345678901234567890'; // Address to receive the role
```

Use the `grantRole` function from the implementation contract ABI initially retrieved, to grant the role. Now let's
grant the role to the address:

```javascript theme={"system"}
let grantRoleRequest: ContractInteractionsApiWriteCallFunctionRequest = {
    writeCallFunctionDto: {
        vaultAccountId: '0', // The vault account ID to grant the role
        abiFunction: {
            "name": "grantRole",
            "type": "function",
            "inputs": [
                {
                    "name": "role",
                    "type": "bytes32",
                    "internalType": "bytes32",
                    "value": roleBytes
                },
                {
                    "name": "account",
                    "type": "address",
                    "internalType": "address",
                    "value": granteeAddress
                }
            ],
            "outputs": [],
            "stateMutability": "nonpayable"
        },
    },
    contractAddress: '0x549E73A4aDF85757BD5Aa170cFb51cd6bBBafBb0', // Address of the ERC20F contract
    assetId: 'ETH_TEST5', // Fireblocks asset ID
}

// Grant the role
const response = await fireblocksSdk.contractInteractions.writeCallFunction(grantRoleRequest);
console.log('Grant role success:', response);
```

## Highlights:

* Ensure that the `vaultAccountId` has the `DEFAULT_ADMIN_ROLE`, as only the admin has the authority to grant roles to other addresses.

## Further Reading

For more detailed information on API parameters and responses, including examples for using plain HTTP requests or in other programming languages, please have a look at the [Fireblocks API Reference for read function](/reference/readcallfunction) and the [Fireblocks API Reference for write function](/reference/writecallfunction).

For more specific guidance on ERC20F contract operations, refer to the [Operating the Upgradable ERC20F Contract Support Center Articles](https://support.fireblocks.io/hc/en-us/articles/13926379966876-Operating-the-Upgradeable-ERC-20F-contract).


# Setup
Source: https://developers.fireblocks.com/reference/setup



> **This code is intended solely as a reference and is NOT production-ready.**
>
> It should not be used directly in a production environment.
> Fireblocks assumes no responsibility for any financial loss or other damages resulting from the use of this code in production.

# Fireblocks Retail Demo Application - Work in Progress!

The Fireblocks Retail Demo application is designed to support Fireblocks clients by serving as a reference model for their integration processes. It embodies the best practices that Fireblocks advocates for building secure, retail-facing solutions.

This demo aims to accelerate and simplify the integration of Fireblocks into your projects, ensuring that you adhere to the recommended best practices when building on the Fireblocks platform.

[Retail Demo Application on GitHub](https://github.com/fireblocks/retail-demo)

## Overview

* **Frontend**: Built with Next.js, this frontend application serves as a retail cryptocurrency platform, providing features like portfolio dashboards, multi-asset wallet management, and transaction handling. It leverages Fireblocks for secure asset management, offering a comprehensive example of a retail-facing crypto solution.
* **Backend**: Developed with Node.js (Express.js), the backend handles essential operations such as user authentication, wallet and asset management, and transaction processing. It integrates with a MySQL database to store user data locally and communicates with the Fireblocks API for wallet and transaction operations.

***

## Before you start: Fireblocks workspace configurations:

### Fireblocks testnet workspace setup

* Running the retail demo app requires a Fireblocks testnet workspace. Complete activating your workspace with the workspace Owner before proceeding with this guide.
* [Create an API user](https://support.fireblocks.io/hc/en-us/articles/4407823826194-Adding-new-API-Users) to execute the backend processes. Our implementation requires a single API user with signing privileges to simplify the integration, for a production-grade application please consider these [best practices](/docs/manage-api-keys) when creating your API users and access levels.
* Upload the `fireblocks-secret.key` file to the `keys` folder on the backend root project folder (create one if not yet created).
* Complete the API user setup and the pairing to an API Co-Signer.
* Copy the API user ID from the console UI and update it in your `.env` file of the backend library (more details below).
* Enable [One Time Address (OTA)](https://support.fireblocks.io/hc/en-us/articles/4409104568338-One-Time-Address-OTA-feature) to allow user withdrawals.
* Determine your Omnibus vault account and copy its ID (found on the vault account page URL) and update your `.env` file in the backend library (more details below).
* Create your withdrawal vault accounts and update their IDs in the `.env` file.

  Note: If not manually set in the `.env` file, the app will create the omnibus and 3 withdrawal vault accounts, and update the database accordingly on the initial run of the app.

***

### Policy setup

Our retail demo app uses the Fireblocks [Policy](https://support.fireblocks.io/hc/en-us/articles/7354983580316-About-the-TAP) feature to govern the flow of assets between vault accounts and from the withdrawals accounts to external user wallets.
Use the below example to tailor your policy and update it on your testnet workspace.
This simplified Policy rule set dictates that the API Admin user will be able to perform rebalancing and sweeping transactions (any vault account to any vault account), and perform user withdrawal transactions (from the 3 withdrawal vault accounts to OTAs).

<img alt="" />

Note: This Policy example is a very simplified rule set that only shows the bare minimum rules required for the demo app to run smoothly. For production level apps, please consider hardening your policy as required by your operations.

***

### Test coins funding

In order to run the demo app, an initial deposit of test coins is required to the withdrawal vault accounts.
Please fund your withdrawal vault accounts with the sufficient balance of tokens and according to the supported assets list found [here](https://github.com/fireblocks/retail-demo/blob/main/backend/src/utils/supportedAssets.json).

Optional public faucets to use:

[Bitcoin Test tokens](https://bitcoinfaucet.uo1.net/)

[Sepolia Test tokens](https://www.alchemy.com/faucets/ethereum-sepolia)

[Solana Devnet tokens](https://faucet.solana.com/)

***

### Webhooks setup

The retail demo app listens to webhooks from Fireblocks and triggers business operations and database updates based on specific events, follow this guide to properly configure your environment to receive webhook messages from Fireblocks.

* Configure a local tunneling service like `ngrok` or `exposed` and forward the messages to `http://localhost:3000`.
* Copy the publicly available URL of the tunneling service.
* [Configure](https://support.fireblocks.io/hc/en-us/articles/4408110107794-Configuring-webhook-URLs) the URL as a webhook server on your Fireblocks testnet workspace's general settings.
* **Important:** The app's webhook endpoint is configured on the `./webhook` path, make sure you add it to the public URL provided by the local tunneling tool you use (example: `https://1e70-94-188-131-83.ngrok-free.app/webhook`).

***

### Rebalancing Automation

The retail demo app utilizes Fireblocks's [Automations feature](https://support.fireblocks.io/hc/en-us/articles/14873112741660-Automation) to trigger rebalancing transactions from the omnibus vault account (where all user deposit accumulates) to the withdrawal vault accounts.
Below, you will find an example of an automation created to facilitate the above. Use it as a reference when creating your automation.

<img alt="" />

Explanation:

* This automation will be triggered by any BTC\_TEST withdrawal from withdrawal vault #1.
* Once the withdrawal is completed, the remaining balance of BTC\_TEST in that vault will be checked.
* If the remaining balance is lower than 0.01 BTC\_TEST, a rebalancing transaction will be triggered to top-up the balance up to 0.1 BTC\_TEST.

Notes:

* An automation should be created for **each** supported asset on **every** withdrawal vault account.
* The amounts used above should be changed based on the anticipated operation in your app.

***

### Running the application:

The retail demo app can run with Docker or locally, both options require updating the environment variable files for both the backend and frontend servers.

#### Backend environment variables

Note: You may use the [.env.example](https://github.com/fireblocks/retail-demo/blob/main/backend/.env.example) file as reference.
Here's a detailed explanation of each variable:

#### Database Configuration

* `DB_NAME`: Name of the MySQL database (default: retail\_demo)
* `DB_USER`: MySQL user (default: root)
* `DB_PASSWORD`: MySQL password
* `DB_HOST`: Database host (default: localhost)
* `DB_PORT`: Database port (default: 3306)

#### Authentication

[Google OAuth 2.0 docs](https://developers.google.com/identity/protocols/oauth2)

* `GOOGLE_CLIENT_ID`: Google OAuth client ID
* `GOOGLE_CLIENT_SECRET`: Google OAuth client secret
* `GIT_CLIENT_ID`: GitHub OAuth client ID
* `GIT_CLIENT_SECRET`: GitHub OAuth client secret
* `JWT_SECRET_KEY`: Secret key for JWT token generation
* `JWT_REFRESH_KEY`: Secret key for JWT refresh token generation

#### Fireblocks Configuration

* `FIREBLOCKS_API_KEY`: Your Fireblocks API key
* `FIREBLOCKS_PATH_TO_SECRET`: Path to your Fireblocks secret key file

#### Application Settings

* `PORT`: Port on which the server will run (default: 3000)
* `FRONTEND_BASE_URL`: URL of the frontend application

#### Vault Configuration

* `OMNIBUS_VAULT`: ID of the Omnibus vault in Fireblocks
* `WITHDRAWAL_VAULTS`: Comma-separated IDs of withdrawal vaults in Fireblocks

#### Frontend enviroment variables

* `NEXT_PUBLIC_BACKEND_BASE_URL`: [http://localhost:3000](http://localhost:3000)
* `CMC_API_KEY`: your\_coinmarketcap\_api\_key

You can get your CMC API key [here](https://coinmarketcap.com/api/documentation/v1/) - we use it as USD value oracle for the app.

#### Run with Docker:

Prerequisites:

* Install Docker and Docker Compose.
* Update the `.env` files for both servers, as mentioned above.

1. Build and Run the Docker container:a

```bash theme={"system"}
docker-compose up --build
```

2. Navigate to `http://localhost:3001/login` once the container is up and running to access the app console UI.

#### Run locally:

Prerequisites:

* Install MySQL.
* Install the BE dependencies:

```bash theme={"system"}
npm install --prefix ./backend
```

* Install the FE dependencies:

```bash theme={"system"}
npm install --prefix ./frontend
```

1. Run the backend server:

```bash theme={"system"}
cd backend
npm start
```

2. Run the frontend server: (on another terminal)

```bash theme={"system"}
cd frontend
npm run dev
```

3. Navigate to `http://localhost:3001/login` to access the app console UI.

***

### Setup script:

The setup script will run only the first time you start the app. It will initialize the connection to the database, create the tables and configure the default data fields.

The setup script uses the `OMNIBUS_VAULT` and `WITHDRAWAL_VAULTS` variables to determine whether to create new vault accounts or use existing ones:

1. If `OMNIBUS_VAULT` is empty:

   * The script will create a new vault account in Fireblocks called "Omnibus Vault".
   * It will then create a BTC\_TEST wallet in this vault account.
2. If `OMNIBUS_VAULT` contains a value:

   * The script will use the provided vault ID as the Omnibus vault.
   * It will not create a new vault account in Fireblocks.
3. If `WITHDRAWAL_VAULTS` is empty:

   * The script will create three new vault accounts in Fireblocks named "Withdrawal Vault #1", "#2", and "#3".
   * It will create SOL\_TEST, ETH\_TEST5, and BTC\_TEST wallets in each of these vault accounts.
4. If `WITHDRAWAL_VAULTS` contains a comma-separated list of vault IDs:

   * The script will use these IDs as the withdrawal vaults.
   * It will not create new vault accounts in Fireblocks.

This flexibility allows you to either use existing vault accounts or let the application create new ones. If you're using existing vault accounts, make sure to set the appropriate IDs in the .env file before running the application for the first time.
**Important:** The setup script runs only once when the database is empty. If you need to re-run the setup, you'll need to clear the existing data from the database.

***

### Backend Application Details

This backend application showcases how to integrate Fireblocks' services into a typical retail-facing scenario. Key features include:

* User authentication (supports Local, Google, and GitHub)
* Wallet creation and management
* Asset creation and balance tracking
* Transaction processing
* WebSocket integration for real-time updates
* Integration with Fireblocks API for vault account and transaction management

For more detailed information, please refer to the [Backend README](https://github.com/fireblocks/retail-demo/tree/main/backend).

***

### Frontend Application Details

The frontend, named **FireX**, is a retail cryptocurrency demo platform built with Next.js and MobX, and integrated with Fireblocks for secure asset management. This project serves as a comprehensive reference for integrating Fireblocks into retail-facing applications.

**FireX** includes features such as a portfolio dashboard, multi-asset wallet management, and a transaction system with Fireblocks integration for secure transfers.

For more detailed information, please refer to the [Frontend README](https://github.com/fireblocks/retail-demo/tree/main/frontend).


# Sign Typed Messages in Ethereum
Source: https://developers.fireblocks.com/reference/sign-typed-messages-for-ethereum-and-evm-networks



Ethereum provides robust capabilities for typed message signing, particularly through [EIP-191](https://eips.ethereum.org/EIPS/eip-191) and [EIP-712](https://eips.ethereum.org/EIPS/eip-712).

These Ethereum Improvement Proposals enhance the security and usability of signing data on the Ethereum blockchain.

***

## EIP-191: Versioned Signatures

EIP-191 specifies a standard for signing messages that includes a versioning scheme. The version byte in the signature tells how the message should be structured, enabling multiple types of signatures under a single framework.

### How EIP-191 Works

* **Prefix Addition:** A standard prefix `\x19Ethereum Signed Message:\n` is added to the message. This prefix includes a declaration of the length of the message that follows, which helps ensure that the message is exactly as intended when signed and verified.
* **Message Concatenation:** The length of the message and the message itself are then concatenated following the prefix.
* **Hashing:** The entire string (prefix + length + message) is typically hashed using a cryptographic hash function like `keccak-256`.
* **Signing:** The resulting hash is then signed using the private key associated with the Ethereum address of the signer.

***

## EIP-712: Signing Structured Data

EIP-712 takes typed message signing further by introducing a standard for signing structured data that humans and machines can read. This EIP aims to make blockchain interactions as understandable as possible, providing users with a clear understanding of what they are signing, thereby reducing the risk of malicious activities.

### How EIP-712 Works

* **Data Typing and Structuring:** Data is structured into types, each defined with a name and a series of fields. EIP-712 allows you to define custom types in addition to predefined types.
* **Domain Separation:** EIP-712 introduces the concept of domain separation, which allows different applications to define their own unique "domains" to prevent signature collisions. A domain includes defining the contract's name, version, and the chain it's deployed on.
* **Message Creation:** The message to be signed is composed of typed data according to the specified schema. This can include multiple fields and data types.
* **Signing the Data:** Users sign the structured data using their private keys. This signature can be verified against the signer’s public key.
* **Verification:** The smart contract can then verify the signature directly by reconstructing the typed data and using the signer’s public address.

***

## Ethereum Typed Message Signing in Fireblocks:

Fireblocks supports both EIP-191 and EIP-712 Typed Message Signing. Additionally, Fireblocks users can sign Typed Messages for any EVM-compatible blockchain supported by Fireblocks. This capability is facilitated by all EVM networks using the same address derivation, resulting in the same address within the same vault account.

> **For any EVM compatible network other than Ethereum, users must still specify ETH as the assetId when calling the API.**

Below you can find TypeScript SDK examples on how to use Fireblocks for EIP712 and EIP191 Typed Message Signing:

```javascript theme={"system"}
import {
  BasePath,
  Fireblocks,
  FireblocksResponse,
  TransactionOperation,
  TransactionResponse,
  TransactionStateEnum,
  TransferPeerPathType,
} from "@fireblocks/ts-sdk";
import { readFileSync } from "fs";

require("dotenv").config();

const FIREBLOCKS_API_KEY = process.env.FIREBLOCKS_API_KEY;
const FIREBLOCKS_SECRET_KEY_PATH = process.env.FIREBLOCKS_SECRET_KEY_PATH;
const FIREBLOCKS_SECRET_KEY = readFileSync(FIREBLOCKS_SECRET_KEY_PATH, "utf-8");

const fireblocks = new Fireblocks({
  apiKey: FIREBLOCKS_API_KEY,
  secretKey: FIREBLOCKS_SECRET_KEY,
  basePath: BasePath.US,
});

let txInfo: any;

const transactionPayload = {
  operation: TransactionOperation.TypedMessage,
  assetId: "ETH",
  source: {
    type: TransferPeerPathType.VaultAccount,
    id: "0", // The vault account ID representing the address used to sign
  },
  note: `Test EIP-191 Message`,
  extraParameters: {
    rawMessageData: {
      messages: [
        {
          content: Buffer.from("Hello, Ethereum!").toString("hex"),
          type: "EIP191",
        },
      ],
    },
  },
};

const getTxStatus = async (txId: string): Promise<TransactionResponse> => {
  try {
    let response: FireblocksResponse<TransactionResponse> =
      await fireblocks.transactions.getTransaction({ txId });
    let tx: TransactionResponse = response.data;
    let messageToConsole: string = `Transaction ${tx.id} is currently at status - ${tx.status}`;

    console.log(messageToConsole);
    while (tx.status !== TransactionStateEnum.Completed) {
      await new Promise((resolve) => setTimeout(resolve, 3000));

      response = await fireblocks.transactions.getTransaction({ txId });
      tx = response.data;

      switch (tx.status) {
        case TransactionStateEnum.Blocked:
        case TransactionStateEnum.Cancelled:
        case TransactionStateEnum.Failed:
        case TransactionStateEnum.Rejected:
          throw new Error(
            `Signing request failed/blocked/cancelled: Transaction: ${tx.id} status is ${tx.status}`,
          );
        default:
          console.log(messageToConsole);
          break;
      }
    }
    while (tx.status !== TransactionStateEnum.Completed);

    return tx;
  } catch (error) {
    throw error;
  }
};

const signArbitraryMessage = async (): Promise<
  TransactionResponse | undefined
> => {
  try {
    const transactionResponse = await fireblocks.transactions.createTransaction(
      {
        transactionRequest: transactionPayload,
      },
    );
    const txId = transactionResponse.data.id;
    if (!txId) {
      throw new Error("Transaction ID is undefined.");
    }
    txInfo = await getTxStatus(txId);

    console.log(txInfo);
    return transactionResponse.data;
  } catch (error) {
    console.error(error);
  }
};

signArbitraryMessage();
```

```javascript theme={"system"}
import {
  BasePath,
  Fireblocks,
  FireblocksResponse,
  TransactionOperation,
  TransactionResponse,
  TransactionStateEnum,
  TransferPeerPathType,
} from "@fireblocks/ts-sdk";
import { readFileSync } from "fs";

require("dotenv").config();

const FIREBLOCKS_API_KEY = process.env.FIREBLOCKS_API_KEY;
const FIREBLOCKS_SECRET_KEY_PATH = process.env.FIREBLOCKS_SECRET_KEY_PATH;
const FIREBLOCKS_SECRET_KEY = readFileSync(FIREBLOCKS_SECRET_KEY_PATH, "utf-8");

const fireblocks = new Fireblocks({
  apiKey: FIREBLOCKS_API_KEY,
  secretKey: FIREBLOCKS_SECRET_KEY,
  basePath: BasePath.US,
});

const getTxStatus = async (txId: string): Promise<TransactionResponse> => {
  try {
    let response: FireblocksResponse<TransactionResponse> =
      await fireblocks.transactions.getTransaction({ txId });
    let tx: TransactionResponse = response.data;
    let messageToConsole: string = `Transaction ${tx.id} is currently at status - ${tx.status}`;

    console.log(messageToConsole);
    while (tx.status !== TransactionStateEnum.Completed) {
      await new Promise((resolve) => setTimeout(resolve, 3000));

      response = await fireblocks.transactions.getTransaction({ txId });
      tx = response.data;

      switch (tx.status) {
        case TransactionStateEnum.Blocked:
        case TransactionStateEnum.Cancelled:
        case TransactionStateEnum.Failed:
        case TransactionStateEnum.Rejected:
          throw new Error(
            `Signing request failed/blocked/cancelled: Transaction: ${tx.id} status is ${tx.status}`,
          );
        default:
          console.log(messageToConsole);
          break;
      }
    }
    while (tx.status !== TransactionStateEnum.Completed);
    return tx;
  } catch (error) {
    throw error;
  }
};

const chainId = 1; // Update the chainId for the relevant EVM network

const eip712message = {
  types: {
    EIP712Domain: [
      { name: "name", type: "string" },
      { name: "version", type: "string" },
      { name: "chainId", type: "uint256" },
      { name: "verifyingContract", type: "address" },
    ],
    Permit: [
      { name: "holder", type: "address" },
      { name: "spender", type: "address" },
      { name: "nonce", type: "uint256" },
      { name: "expiry", type: "uint256" },
      { name: "allowed", type: "bool" },
    ],
  },
  primaryType: "Permit",
  domain: {
    name: "Dai Stablecoin",
    version: "1",
    chainId, // Update the chainId for the relevant EVM network
    verifyingContract: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  },
  message: {
    holder: "0x289826f7248b698B2Aef6596681ab0291BFB2599",
    spender: "0x043f38E9e8359ca32cD57503df25B8DEF2845356",
    nonce: 123,
    expiry: 1655467980,
    allowed: true,
  },
};

const transactionPayload = {
  operation: TransactionOperation.TypedMessage,
  assetId: "ETH",
  source: {
    type: TransferPeerPathType.VaultAccount,
    id: "0", // The vault account ID represnting the address used to sign
  },
  note: "Test EIP-712 Message",
  extraParameters: {
    rawMessageData: {
      messages: [
        {
          content: eip712message,
          type: "EIP712",
        },
      ],
    },
  },
};

let txInfo: any;

const signArbitraryMessage = async (): Promise<
  TransactionResponse | undefined
> => {
  try {
    const transactionResponse = await fireblocks.transactions.createTransaction(
      {
        transactionRequest: transactionPayload,
      },
    );
    const txId = transactionResponse.data.id;
    if (!txId) {
      throw new Error("Transaction ID is undefined.");
    }
    txInfo = await getTxStatus(txId);
    console.log(txInfo);

    return transactionResponse.data;
  } catch (error) {
    console.error(error);
  }
};

signArbitraryMessage();
```

***

## Structuring the Signature

Once the Typed Message Signing request is successfully signed, you can retrieve the transaction using the [Get Transaction By TxId Endpoint](/reference/gettransaction). The signed transaction will appear in the following format:

```json theme={"system"}
{
  "id": "<your_transaction_id>",
  "assetId": "ETH",
  "source": {
    "id": "<vault_account_id>",
    "type": "VAULT_ACCOUNT",
    "name": "<vault_account_name>",
    "subType": ""
  },
  "destination": {
    "id": null,
    "type": "UNKNOWN",
    "name": "N/A",
    "subType": ""
  },
  "requestedAmount": null,
  "amount": null,
  "netAmount": -1,
  "amountUSD": null,
  "fee": -1,
  "networkFee": -1,
  "createdAt": 1712522541024,
  "lastUpdated": 1712522564793,
  "status": "COMPLETED",
  "txHash": "",
  "subStatus": "",
  "sourceAddress": "",
  "destinationAddress": "",
  "destinationAddressDescription": "",
  "destinationTag": "",
  "signedBy": [],
  "createdBy": "<API_KEY>",
  "rejectedBy": "",
  "addressType": "",
  "note": "Test EIP191 Message",
  "exchangeTxId": "",
  "feeCurrency": "ETH",
  "operation": "TYPED_MESSAGE",
  "amountInfo": {},
  "feeInfo": {},
  "signedMessages": [
    {
      "derivationPath": [
        44,
        60,
        0,
        0,
        0
      ],
      "algorithm": "MPC_ECDSA_SECP256K1",
      "publicKey": "03af66c4551559d54bfbfd14c84870a337b06bf2738ed6427480ec56ee551c7458",
      "signature": {
        "r": "c8ab06c7c3447ac8f594a643d5942ceb2451b9434bb29c4b1a40da5cf3240300",
        "s": "2bfba73d825b240f2e2949df139c2f3e26e6cdd36579eb1a0cbd4abc4e6e348a",
        "v": 0,
        "fullSig": "c8ab06c7c3447ac8f594a643d5942ceb2451b9434bb29c4b1a40da5cf32403002bfba73d825b240f2e2949df139c2f3e26e6cdd36579eb1a0cbd4abc4e6e348a"
      },
      "content": "90089ed244695164981f5f54e78bea15387a2bdda0dca6a81e1fe79cd30075db"
    }
  ],
  "extraParameters": {
    "rawMessageData": {
      "messages": [
        {
          "type": "ETH_MESSAGE",
          "index": 0,
          "content": "494e53455254205445585420484552452121"
        }
      ]
    }
  },
  "destinations": [],
  "blockInfo": {},
  "assetType": "BASE_ASSET"
}
```

```json theme={"system"}
{
  "id": "<your_transaction_id>",
  "assetId": "ETH",
  "source": {
    "id": "<vault_account_id>",
    "type": "VAULT_ACCOUNT",
    "name": "<vault_account_name>",
    "subType": ""
  },
  "destination": {
    "id": null,
    "type": "UNKNOWN",
    "name": "N/A",
    "subType": ""
  },
  "requestedAmount": null,
  "amount": null,
  "netAmount": -1,
  "amountUSD": null,
  "fee": -1,
  "networkFee": -1,
  "createdAt": 1712520602396,
  "lastUpdated": 1712520622523,
  "status": "COMPLETED",
  "txHash": "",
  "subStatus": "",
  "sourceAddress": "",
  "destinationAddress": "",
  "destinationAddressDescription": "",
  "destinationTag": "",
  "signedBy": [],
  "createdBy": "<API_KEY>",
  "rejectedBy": "",
  "addressType": "",
  "note": "Test EIP-712 Message",
  "exchangeTxId": "",
  "feeCurrency": "ETH",
  "operation": "TYPED_MESSAGE",
  "amountInfo": {},
  "feeInfo": {},
  "signedMessages": [
    {
      "derivationPath": [
        44,
        60,
        0,
        0,
        0
      ],
      "algorithm": "MPC_ECDSA_SECP256K1",
      "publicKey": "03af66c4551559d54bfbfd14c84870a337b06bf2738ed6427480ec56ee551c7458",
      "signature": {
        "r": "2e31d257c1bcd232c50d628e9e97407373c4a1c5cc79672039a1f7946984a702",
        "s": "370b8e16123e30968ba7018a6726f97dfc82f5547f99fe78b432a40a1d1f8564",
        "v": 0,
        "fullSig": "2e31d257c1bcd232c50d628e9e97407373c4a1c5cc79672039a1f7946984a702370b8e16123e30968ba7018a6726f97dfc82f5547f99fe78b432a40a1d1f8564"
      },
      "content": "36c0b1b40bcd032c871ca176243f5ff7e603a9ce91ff8dae62d79ab8dee6817a"
    }
  ],
  "extraParameters": {
    "rawMessageData": {
      "messages": [
        {
          "type": "EIP712",
          "index": 0,
          "content": {
            "types": {
              "Permit": [
                {
                  "name": "holder",
                  "type": "address"
                },
                {
                  "name": "spender",
                  "type": "address"
                },
                {
                  "name": "nonce",
                  "type": "uint256"
                },
                {
                  "name": "expiry",
                  "type": "uint256"
                },
                {
                  "name": "allowed",
                  "type": "bool"
                }
              ],
              "EIP712Domain": [
                {
                  "name": "name",
                  "type": "string"
                },
                {
                  "name": "version",
                  "type": "string"
                },
                {
                  "name": "chainId",
                  "type": "uint256"
                },
                {
                  "name": "verifyingContract",
                  "type": "address"
                }
              ]
            },
            "domain": {
              "name": "Dai Stablecoin",
              "chainId": 1,
              "version": "1",
              "verifyingContract": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
            },
            "message": {
              "nonce": 123,
              "expiry": 1655467980,
              "holder": "0x289826f7248b698B2Aef6596681ab0291BFB2599",
              "allowed": true,
              "spender": "0x043f38E9e8359ca32cD57503df25B8DEF2845356"
            },
            "primaryType": "Permit"
          }
        }
      ]
    }
  },
  "destinations": [],
  "blockInfo": {},
  "assetType": "BASE_ASSET"
}
```

To access the signature, navigate to the object at the first index (0) of the `signedMessages` array. Within this object, the `signature` object contains three components: `r`, `s`, and `v`:

* `r`: This is the first 32 bytes of the signature, representing the X coordinate of the point on the elliptic curve
* `s`: This is the second 32 bytes of the signature, representing the scalar component of the elliptic curve point
* `v`: This parameter is crucial for correctly reconstructing the public key used in signing. It helps distinguish between the possible public keys that could correspond to the signature

There are principally two methods to assemble a complete, correctly structured signature on EVM-based blockchains, differing primarily in how the `v` value is calculated, a modification introduced by [EIP-155](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-155.md).
EIP-155 prevents certain types of replay attacks by incorporating the `chainId` into the `v` value:

```javascript theme={"system"}
const signature = txInfo.signedMessages[0].signature;
const v = 27 + signature.v;

const finalSignature =  "0x" + signature.r + signature.s + v.toString(16);
```

```javascript theme={"system"}
const signature = txInfo.signedMessages[0].signature;
const v = chainId * 2 + 35 + signature.v;

const finalSignature = "0x" + signature.r + signature.s + v.toString(16);
```

It is important to consider the `chainId` value when working with any EVM-based blockchain as it directly affects the calculation of the `v` parameter.

Properly calculating `v` ensures that the signature correctly corresponds to the network on which the transaction is intended, thus preventing cross-chain replay attacks.

A full list of EVM Networks `chainId` values can be found [here](https://chainlist.org/).

***

## Verifying the Signature

In the examples below we are using [ethers.js](https://docs.ethers.org/v6/) (v6.11.1) in order to verify the signed Typed Message:

```javascript theme={"system"}
import { verifyMessage } from "ethers"

const mySignerAddress = "<my_signer_address>"
const message = "Hello, Ethereum!"
const signature = "<signature_from_fireblocks>"

function verifyMessageWithEthers(message, signature) {
    const signerAddress = verifyMessage(message, signature);
    return signerAddress;
}

const signerAddress = verifyMessageWithEthers(message, signature);

if(signerAddress === mySignerAddress) {
  console.log(`Signature is valid!`);
} else {
  console.log('Signature is invalid!');
}
```

```javascript theme={"system"}
const { ethers } = require('ethers');

const domain = {
  name: "Dai Stablecoin",
  version: "1",
  chainId: 1,
  verifyingContract: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
};

const types = {
  Permit: [
    { name: "holder", type: "address" },
    { name: "spender", type: "address" },
    { name: "nonce", type: "uint256" },
    { name: "expiry", type: "uint256" },
    { name: "allowed", type: "bool" }
  ]
};

const value = {
  holder: "0x289826f7248b698B2Aef6596681ab0291BFB2599",
  spender: "0x043f38E9e8359ca32cD57503df25B8DEF2845356",
  nonce: 123,
  expiry: 1655467980,
  allowed: true
};

const signature = '<my_signature_from_fireblocks>';

async function verifySignature() {
  try {
    const signerAddress = await ethers.verifyTypedData(domain, types, value, signature);
    console.log('Recovered address:', signerAddress);

    if (signerAddress.toLowerCase() === value.holder.toLowerCase()) {
      console.log('Signature is valid!');
    } else {
      console.log('Signature is invalid.');
    }
  } catch (error) {
    console.error('Error verifying signature:', error);
  }
}

verifySignature();
```


# Authenticate
Source: https://developers.fireblocks.com/reference/signing-a-request-jwt-structure



> Before you begin
>
> Ensure you have created an **API User ID** (API key) in your [Fireblocks Console](https://console.fireblocks.io/v2/developer/api-users).

# Signing a request

Fireblocks uses **API keys** (API User IDs) to authenticate all API calls. Depending on the type of workspace environment, the **base API URL** will be one of the following:

* US Sandbox: `https://sandbox-api.fireblocks.io/v1`
* US Mainnet/Testnet: `https://api.fireblocks.io/v1`
* For EU Mainnet or Testnet workspaces: `https://eu-api.fireblocks.io/v1`
* For EU2 Mainnet or Testnet workspaces: `https://eu2-api.fireblocks.io/v1`

Every API request must contain the following headers:

* `X-API-Key` - The API key created from your Fireblocks workspace.
* `Authorization` - This value should be set to `Bearer <Access Token>`. The access token is a Base64-encoded JSON Web Token (JWT).

***

# JWT Structure

`Authorization: Bearer <JWT>`

The JWT payload field should contain the following fields:

* `uri` - The URI part of the request (e.g., /v1/transactions).
* `nonce` - Unique number or string. Each API request must have a unique nonce.
* `iat` - The time at which the JWT was issued, in seconds since Epoch.
* `exp` - The expiration time on and after which the JWT must not be accepted for processing, in seconds since Epoch. (Must be less than `iat`+30sec.)
* `sub` - The API key.
* `bodyHash` - Hex-encoded SHA-256 hash of the raw HTTP request body.

The JWT must be signed with the Fireblocks API private key and the RS256 (RSASSA-PKCS1-v1\_5 using SHA-256 hash) algorithm.

> **API Authentication code examples:**
>
> Check out the [following](https://github.com/fireblocks/developers-hub/tree/main/authentication_examples) API Authentication code examples

***

# Using the Fireblocks SDKs

You can set up the request headers using the [Fireblocks API SDKs](/reference/sdk-migration-guide):

```javascript theme={"system"}
import { Fireblocks } from "@fireblocks/ts-sdk";
import * as fs from "fs";

// Initialize the Fireblocks SDK
const fireblocks = new Fireblocks({
  apiKey: "your-api-key",
  secretKey: fs.readFileSync("/path/to/your/secret.key", "utf8"),
  basePath: "https://api.fireblocks.io"
});
```

```python theme={"system"}
from fireblocks.client import Fireblocks
from fireblocks.client_configuration import ClientConfiguration
from fireblocks.base_path import BasePath

# load the secret key content from a file
with open('your_secret_key_file_path', 'r') as file:
    secret_key_value = file.read()

# build the configuration
configuration = ClientConfiguration(
        api_key="your_api_key",
        secret_key=secret_key_value,
        base_path=BasePath.Sandbox, # or set it directly to a string "https://sandbox-api.fireblocks.io/v1"
)

# Enter a context with an instance of the API client
with Fireblocks(configuration) as fireblocks:
    pass
```

```bash theme={"system"}
export FIREBLOCKS_BASE_PATH="https://sandbox-api.fireblocks.io/v1"
export FIREBLOCKS_API_KEY="my-api-key"
export FIREBLOCKS_SECRET_KEY="my-secret-key"
```

> **Fireblocks API key**
>
> When using the above SDK code examples to sign a request, be sure to replace `apiKey` with your own API key.


# Sign Typed Messages in Bitcoin
Source: https://developers.fireblocks.com/reference/signing-typed-messages-in-bitcoin



Bitcoin typed message signing, commonly referred to as "Bitcoin personal message signing," is a way for users to prove ownership of a Bitcoin address by signing a message with the private key associated with that address.

This functionality is widely used in the Bitcoin ecosystem to verify ownership without requiring a transaction or revealing the private key. Here's a detailed breakdown of the process, including the structure of the message to sign, the prefix used, and the structure of the signature.

When signing a message in Bitcoin, the user typically inputs a plain text message.

The actual message that gets signed, however, includes a standard prefix to prevent certain types of attacks and to distinguish these personal messages from other types of data that might be signed with Bitcoin keys (like transactions).
The prefix used is not part of the message itself but is added to the message during the signing process to create a complete hash that will be signed. The standard prefix is: `"\x18Bitcoin Signed Message:\n"`

## Process of Signing a Message

* **Concatenation:** The actual text that gets signed is a concatenation of the prefix and the message. Specifically, it's the prefix followed by the length of the message (as a single byte or varint) and then the message itself.
* **Hashing:** Before signing, the concatenated string is hashed twice using SHA-256 (SHA-256d). This double hashing is a common practice in Bitcoin for added security.
* **Signing:** The double `SHA-256` hash of the message is then signed using the private key associated with the Bitcoin address. This signing is done according to the ECDSA (Elliptic Curve Digital Signature Algorithm) standard used in Bitcoin.

***

## Bitcoin Typed Message Signing in Fireblocks:

Below is a TypeScript SDK code example on how to execute Typed Message Signing (Personal Message) in Bitcoin.
In this example we are specifically showing how to sign a [TRUST platform](https://www.coinbase.com/blog/introducing-the-travel-rule-universal-solution-technology-trust) compatible message:

```javascript theme={"system"}
const transactionPayload = {
  operation: TransactionOperation.TypedMessage,
  assetId: "BTC",
  source: {
    type: TransferPeerPathType.VaultAccount,
    id: "0", // The vault account ID represnting the address used to sign
  },
  note: "Bitcoin Message",
  extraParameters: {
    rawMessageData: {
      messages: [
        {
          content: "", // Content remains blank and is replaced by the message built when signing the TX
          type: "BTC_MESSAGE",
        },
      ],
    },
  },
};
const getWalletAddress = async (): Promise<VaultWalletAddress | any> => {
  try {
    const addressResponse =
      await fireblocks.vaults.getVaultAccountAssetAddressesPaginated({
        vaultAccountId: transactionPayload.source.id,
        assetId: transactionPayload.assetId,
      });
    if (addressResponse.data.addresses.length === 0) {
      throw new Error("No wallet addresses found");
    }
    return addressResponse.data;
  } catch (error) {
    console.error(error);
  }
};

const getTxStatus = async (txId: string): Promise<TransactionResponse> => {
  try {
    let response: FireblocksResponse<TransactionResponse> =
      await fireblocks.transactions.getTransaction({ txId });
    let tx: TransactionResponse = response.data;
    let messageToConsole: string = `Transaction ${tx.id} is currently at status - ${tx.status}`;

    console.log(messageToConsole);
    while (tx.status !== TransactionStateEnum.Completed) {
      await new Promise((resolve) => setTimeout(resolve, 3000));

      response = await fireblocks.transactions.getTransaction({ txId });
      tx = response.data;

      switch (tx.status) {
        case TransactionStateEnum.Blocked:
        case TransactionStateEnum.Cancelled:
        case TransactionStateEnum.Failed:
        case TransactionStateEnum.Rejected:
          throw new Error(
            `Signing request failed/blocked/cancelled: Transaction: ${tx.id} status is ${tx.status}`,
          );
        default:
          console.log(messageToConsole);
          break;
      }
    }
    while (tx.status !== TransactionStateEnum.Completed);
    return tx;
  } catch (error) {
    throw error;
  }
};

const signArbitraryMessage = async (): Promise<
  TransactionResponse | undefined
> => {
  const address = await getWalletAddress();
  try {
    // replacing payload message with the format required before creating the transaction
    // message format is {vasp_prefix}{address}{UUID}
    const message =
      "tripleaio" + address + "975f0090-a88f-4be0-a123-d38484e8394d";
    transactionPayload.extraParameters.rawMessageData.messages[0].content =
      message;

    const transactionResponse = await fireblocks.transactions.createTransaction(
      {
        transactionRequest: transactionPayload,
      },
    );
    const txId = transactionResponse.data.id;
    if (!txId) {
      throw new Error("Transaction ID is undefined.");
    }
    txInfo = await getTxStatus(txId);
    const signature = txInfo.signedMessages[0].signature;

    const encodedSig =
      Buffer.from([Number.parseInt(signature.v, 16) + 31]).toString("hex") +
      signature.fullSig;
    console.log(
      "Encoded Signature:",
      Buffer.from(encodedSig, "hex").toString("base64"),
    );

    return transactionResponse.data;
  } catch (error) {
    console.error(error);
  }
};

signArbitraryMessage();
```

### Structure of the Signature:

The signature produced in Bitcoin message signing is composed of the following:

A single-byte recovery ID `recid` - this byte helps in recovering the public key (and thus the address) from the signature and the signed message.

Two 32-byte numbers representing the ECDSA signature components - `r` and `s`.
The signature is usually encoded in `Base64` format when being displayed or transmitted, making it easier to handle in web interfaces and other applications.


# Sign Typed Messages in Tron
Source: https://developers.fireblocks.com/reference/signing-typed-messages-in-tron



[TIP-191](https://github.com/tronprotocol/tips/blob/master/tip-191.md), much like EIP-191 in Ethereum, defines a standard for signing messages in the Tron network. The protocol is designed to allow users to sign plain messages in a way that can be securely verified. This includes specifying how messages should be formatted and signed to ensure they are distinguishable from transactions and other types of data.

The TIP-191 standard does not involve complex structures like JSON or detailed data typing as in EIP-712.
Instead, it focuses on the secure signing of simpler, plain-text messages. Here’s how it generally works:

* **Message Formatting:** The message to be signed is typically prepared with a specific prefix to distinguish it from transaction data. This prefix is crucial to prevent certain types of attacks where signed data could be misused.
* **Prefixing the Message:** Similar to EIP-191, a common practice in message signing under TIP-191 would involve adding a prefix that clarifies the message is a signed message and not part of a transaction. The prefix often used in Ethereum (and likely a similar approach in Tron) is `"\x19Tron Signed Message:\n"`, where `\x19` serves as a control character to differentiate the data.
* **Hashing**: Once the message is concatenated with the prefix, it is hashed using a cryptographic hash function, typically `SHA-256`. This hash ensures that the message is converted into a fixed-length, unique data set.
* **Signing:** The resulting hash is then signed using the private key of the signer’s Tron wallet. Tron also uses ECDSA for digital signatures, similar to Bitcoin and Ethereum.

***

## Tron Typed Message Signing In Fireblocks:

Below you can find a TypeScript SDK example for TIP191 Typed Message Signing. This is very similar to Ethereum and Bitcoin while the main differences are the `assetId` and the `type` of the message:

```javascript theme={"system"}
import {
  BasePath,
  Fireblocks,
  FireblocksResponse,
  TransactionOperation,
  TransactionResponse,
  TransactionStateEnum,
  TransferPeerPathType,
} from "@fireblocks/ts-sdk";
import { readFileSync } from "fs";

require("dotenv").config();

const FIREBLOCKS_API_KEY = process.env.FIREBLOCKS_API_KEY;
const FIREBLOCKS_SECRET_KEY_PATH = process.env.FIREBLOCKS_SECRET_KEY_PATH;
const FIREBLOCKS_SECRET_KEY = readFileSync(FIREBLOCKS_SECRET_KEY_PATH, "utf-8");

const fireblocks = new Fireblocks({
  apiKey: FIREBLOCKS_API_KEY,
  secretKey: FIREBLOCKS_SECRET_KEY,
  basePath: BasePath.US,
});

let txInfo:any;

const transactionPayload = {
  operation: TransactionOperation.TypedMessage,
  assetId: "TRX",
  source: {
    type: TransferPeerPathType.VaultAccount,
    id: "0", // The vault account ID represnting the address used to sign
  },
  note: `Test TIP-191 Message`,
  extraParameters: {
    rawMessageData: {
      messages: [
        {
          content: Buffer.from("Hello, Tron!").toString("hex"),
          type: "TIP191",
        },
      ],
    },
  },
};

const getTxStatus = async (txId: string): Promise<TransactionResponse> => {
  try {
    let response: FireblocksResponse<TransactionResponse> =
      await fireblocks.transactions.getTransaction({ txId });
    let tx: TransactionResponse = response.data;
    let messageToConsole: string = `Transaction ${tx.id} is currently at status - ${tx.status}`;

    console.log(messageToConsole);
    while (tx.status !== TransactionStateEnum.Completed) {
      await new Promise((resolve) => setTimeout(resolve, 3000));

      response = await fireblocks.transactions.getTransaction({ txId });
      tx = response.data;

      switch (tx.status) {
        case TransactionStateEnum.Blocked:
        case TransactionStateEnum.Cancelled:
        case TransactionStateEnum.Failed:
        case TransactionStateEnum.Rejected:
          throw new Error(
            `Signing request failed/blocked/cancelled: Transaction: ${tx.id} status is ${tx.status}`,
          );
        default:
          console.log(messageToConsole);
          break;
      }
    }
    while (tx.status !== TransactionStateEnum.Completed);

    return tx;
  } catch (error) {
    throw error;
  }
};

const signArbitraryMessage = async (): Promise<
  TransactionResponse | undefined
> => {
  try {
    const transactionResponse = await fireblocks.transactions.createTransaction(
      {
        transactionRequest: transactionPayload,
      },
    );
    const txId = transactionResponse.data.id;
    if (!txId) {
      throw new Error("Transaction ID is undefined.");
    }
    txInfo = await getTxStatus(txId);

    console.log(txInfo)
    return transactionResponse.data;

  } catch (error) {
    console.error(error);
  }
};

signArbitraryMessage();
```

```json theme={"system"}
{
  "id": "cfe8c2b5-4095-413d-b41a-17d06749f317",
  "assetId": "TRX",
  "source": {
    "id": "your_vault_account_id",
    "type": "VAULT_ACCOUNT",
    "name": "Your_Vault_Name",
    "subType": ""
  },
  "destination": {
    "id": null,
    "type": "UNKNOWN",
    "name": "N/A",
    "subType": ""
  },
  "requestedAmount": null,
  "amount": null,
  "netAmount": -1,
  "amountUSD": null,
  "fee": -1,
  "networkFee": -1,
  "createdAt": 1712857479116,
  "lastUpdated": 1712857494054,
  "status": "COMPLETED",
  "txHash": "",
  "subStatus": "",
  "sourceAddress": "",
  "destinationAddress": "",
  "destinationAddressDescription": "",
  "destinationTag": "",
  "signedBy": [],
  "createdBy": "69a744b2-65dd-4bc0-95b4-7e049f448f72",
  "rejectedBy": "",
  "addressType": "",
  "note": "Test TIP-191 Message",
  "exchangeTxId": "",
  "feeCurrency": "TRX",
  "operation": "TYPED_MESSAGE",
  "amountInfo": {},
  "feeInfo": {},
  "signedMessages": [
    {
      "derivationPath": [
        44,
        195,
        0,
        0,
        0
      ],
      "algorithm": "MPC_ECDSA_SECP256K1",
      "publicKey": "03f01fd4069816ae8ebc0804736418397f94aaaf723a5bd7d20e8bc5f6a5b65c83",
      "signature": {
        "r": "5eaa33459387d23fe807444ad354e41ef95d240a0437a0a5b3b27a8d067276b5",
        "s": "5c4acdce460030de8eb90d22fb80de2512444d3927a08023856c3f356c6a0b81",
        "v": 1,
        "fullSig":"5eaa33459387d23fe807444ad354e41ef95d240a0437a0a5b3b27a8d067276b55c4acdce460030de8eb90d22fb80de2512444d3927a08023856c3f356c6a0b81"
      },
      "content": "35b82ee9a41533dada0749e62b3ee561b55e3f4a1555dba5703aa322911d2618"
    }
  ],
  "extraParameters": {
    "rawMessageData": {
      "messages": [
        {
          "type": "TIP191",
          "index": 0,
          "content": "48656c6c6f2c2054726f6e21"
        }
      ]
    }
  }
```

***

## Structuring The Signature:

The final signature is just the concatenated `r`, `s` and `v` values of the signature, prefixed with `0x` while the returned `v` (integer) is `0`/`1` ( 1 byte in hex so `00` /`01`) or the same as [EVM signature structuring](/reference/sign-typed-messages-for-ethereum-and-evm-networks#structuring-the-signature):

```javascript theme={"system"}
const signature = txInfo.signedMessages[0].signature;
const v = 27 + signature.v;

const finalSignature =  "0x" + signature.r + signature.s + v.toString(16);
```

***

## Validating The Signature:

In the example below we are using `verifyMessageV2()` from the [TronWeb](https://tronweb.network/docu/docs/API%20List/trx/verifyMessageV2) JS library:

```python theme={"system"}
import TronWeb from "tronweb"

const mySignerAddress = "<my_signer_address>"
const message = "Hello, Tron!"
const signature = "<signature_from_fireblocks>" // '0x' + r + s + v (hex)

const signerAddress = TronWeb.Trx.verifyMessageV2(
  message,
  signature
)

if(signerAddress === mySignerAddress) {
  console.log(`Signature is valid!`);
} else {
  console.log('Signature is invalid!');
}
```


# Smart Transfer Webhooks
Source: https://developers.fireblocks.com/reference/smart-transfer-webhooks



> **Deprecation notice**
>
> Webhooks v1 will be deprecated on **June 15th, 2026**. Please use the Developer Center in the Fireblocks Console to upgrade to Webhooks V2, which offers improved reliability, performance, and observability.

This page describes all events relating to Fireblocks Smart Transfers that produce Webhook notifications, and their associated data objects.

The `type` parameter is automatically set to the description name for the data objects below.

## Ticket created

Notification is sent when a Smart Transfer ticket is created.

| Parameter              | Type   | Description                                                              |
| ---------------------- | ------ | ------------------------------------------------------------------------ |
| ticketId               | string | Unique ID for the ticket                                                 |
| type                   | string | The type of settlement for the ticket: Currently only async              |
| status                 | string | The status of the ticket                                                 |
| createdByNetworkId     | string | The network ID of the Fireblocks Network profile that created the ticket |
| createdByNetworkIdName | string | The name of the Fireblocks Network profile that created the ticket       |
| createdAt              | date   | Time and date when the ticket was created                                |
| expiresIn              | number | Expiration of the ticket in hours                                        |

## Ticket counterparty added

Notification is sent when a counterparty is added to a Smart Transfer ticket.

| Parameter     | Type   | Description                                                 |
| ------------- | ------ | ----------------------------------------------------------- |
| ticketId      | string | Unique ID for the ticket                                    |
| networkId     | string | Network ID of the connection receiving a ticket             |
| networkIdName | string | Name of the Fireblocks Network profile receiving the ticket |

## Ticket counterparty external ID added

Notification is sent when an external ID is added to a Smart Transfer ticket.

| Parameter     | Type   | Description                          |
| ------------- | ------ | ------------------------------------ |
| ticketId      | string | Unique ID for the ticket             |
| externalRefId | string | Any ID a customer adds to the system |

## Ticket note added

Notification is sent when a note is added to a Smart Transfer ticket.

| Parameter | Type   | Description                             |
| --------- | ------ | --------------------------------------- |
| ticketId  | string | Unique ID for the ticket                |
| body      | string | Text of the note                        |
| createdAt | date   | Time and date when the note was created |

## Ticket submitted

Notification is sent when a Smart Transfer ticket is submitted.

| Parameter   | Type   | Description                           |
| ----------- | ------ | ------------------------------------- |
| ticketId    | string | Unique ID for the ticket              |
| expiresIn   | number | Expiration of the ticket in hours     |
| status      | string | Status of the ticket                  |
| expiresAt   | date   | Date and time when the ticket expires |
| submittedAt | date   | Date and time the ticket is submitted |

## Ticket expires at set

Notification is sent when a Smart Transfer ticket expiration is set.

| Parameter | Type   | Description                           |
| --------- | ------ | ------------------------------------- |
| ticketId  | string | Unique ID for the ticket              |
| expiresAt | date   | Date and time when the ticket expires |

## Ticket expires in set

Notification is sent when a Smart Transfer ticket expiration is set.

| Parameter | Type   | Description                       |
| --------- | ------ | --------------------------------- |
| ticketId  | string | Unique ID for the ticket          |
| expiresIn | number | Expiration of the ticket in hours |

## Ticket expired

Notification is sent when a Smart Transfer ticket expires.

| Parameter | Type   | Description                           |
| --------- | ------ | ------------------------------------- |
| ticketId  | string | Unique ID for the ticket              |
| status    | string | Status of the ticket                  |
| expiresAt | date   | Date and time when the ticket expired |

## Ticket fulfilled

Notification is sent when a Smart Transfer ticket is fulfilled.

| Parameter   | Type   | Description                                               |
| ----------- | ------ | --------------------------------------------------------- |
| ticketId    | string | Unique ID for the ticket                                  |
| fulfilledAt | date   | Date and time when the ticket was fulfilled by both sides |

## Ticket canceled

Notification is sent when a Smart Transfer ticket is canceled.

| Parameter  | Type   | Description                                |
| ---------- | ------ | ------------------------------------------ |
| ticketId   | string | Unique ID for the ticket                   |
| canceledAt | date   | Date and time when the ticket was canceled |

## Ticket term added

Notification is sent when a Smart Transfer ticket term is added.

| Parameter     | Type   | Description                                  |
| ------------- | ------ | -------------------------------------------- |
| ticketId      | string | Unique ID for the ticket                     |
| termId        | string | Unique ID of the term                        |
| asset         | string | Asset name being sent in the term            |
| amount        | string | Amount of the asset being sent               |
| fromNetworkId | string | NetworkId from which the asset is being sent |
| toNetworkId   | string | NetworkId to which the asset is being sent   |
| status        | string | Status of the ticket                         |

## Ticket term updated

Notification is sent when a Smart Transfer ticket term is updated.

| Parameter     | Type   | Description                                  |
| ------------- | ------ | -------------------------------------------- |
| ticketId      | string | Unique ID for the ticket                     |
| termId        | string | Unique ID of the term                        |
| asset         | string | Asset name being sent in the term            |
| amount        | string | Amount of the asset being sent               |
| fromNetworkId | string | NetworkId from which the asset is being sent |
| toNetworkId   | string | NetworkId to which the asset is being sent   |

## Ticket term deleted

Notification is sent when a Smart Transfer ticket term is deleted.

| Parameter | Type   | Description              |
| --------- | ------ | ------------------------ |
| ticketId  | string | Unique ID for the ticket |
| termId    | string | Unique ID of the term    |

## Ticket term funded

Notification is sent when a Smart Transfer ticket term is funded.

| Parameter           | Type   | Description                                                                                                             |
| ------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------- |
| ticketId            | string | Unique ID for the ticket                                                                                                |
| termId              | string | Unique ID of the term                                                                                                   |
| asset               | string | Asset name of the asset being sent to fund the term                                                                     |
| amount              | string | Amount of the asset being sent to fund the term                                                                         |
| networkConnectionId | string | Network ID funding the term                                                                                             |
| srcId               | string | vaultId if srcType is VAULT\_ACCOUNT;  exchangeId if srcType is EXCHANGE; or  fiatAccountId if srcType is FIAT\_ACCOUNT |
| srcType             | string | Type of the account from which the funds are originating;  can be a vault, an exchange, or a fiat account               |
| note                | string | Text of the note                                                                                                        |
| fee                 | string | Amount of fee paid for the transaction funding the term                                                                 |
| feeLevel            | string | Fee level being paid                                                                                                    |

## Ticket term manually funded

Notification is sent when a Smart Transfer ticket term is manually funded.

| Parameter | Type   | Description                                 |
| --------- | ------ | ------------------------------------------- |
| ticketId  | string | Unique ID for the ticket                    |
| termId    | string | Unique ID of the term                       |
| txHash    | string | TX hash of the transaction funding the term |

## Ticket term funding canceled

Notification is sent when a Smart Transfer ticket term’s funding is canceled.

| Parameter | Type   | Description                             |
| --------- | ------ | --------------------------------------- |
| ticketId  | string | Unique ID for the ticket                |
| termId    | string | Unique ID of the term                   |
| txStatus  | string | Status of the transfer funding the term |

## Ticket term funding failed

Notification is sent when a Smart Transfer ticket term’s funding fails.

| Parameter | Type   | Description                             |
| --------- | ------ | --------------------------------------- |
| ticketId  | string | Unique ID for the ticket                |
| termId    | string | Unique ID of the term                   |
| txStatus  | string | Status of the transfer funding the term |

## Ticket term funding completed

Notification is sent when a Smart Transfer ticket term’s funding is completed.

| Parameter | Type   | Description                                 |
| --------- | ------ | ------------------------------------------- |
| ticketId  | string | Unique ID for the ticket                    |
| termId    | string | Unique ID of the term                       |
| txSHash   | string | TX hash of the transaction funding the term |
| txStatus  | string | Status of the transfer funding the term     |

## Ticket term transaction status changed

Notification is sent when a Smart Transfer ticket term’s transaction status changes.

| Parameter | Type   | Description                             |
| --------- | ------ | --------------------------------------- |
| ticketId  | string | Unique ID for the ticket                |
| termId    | string | Unique ID of the term                   |
| txStatus  | string | Status of the transfer funding the term |


# Solana Web3 Connection Adapter
Source: https://developers.fireblocks.com/reference/solana-web3-adapter



The Fireblocks Solana Web3 Connection Adapter facilitates interactions between the Fireblocks API and the Solana blockchain, simplifying the process of sending transactions through Fireblocks by handling complex authentication and transaction signing procedures.

The Solana Web3 Connection Adapter utilizes the [Fireblocks Program Call API](/reference/interact-with-solana-programs) to process and sign all transactions, providing seamless integration with the Solana blockchain and Solana web3.js library.

[Visit our GitHub repo to view code examples](https://github.com/fireblocks/solana-web3-adapter/tree/main/examples)!


# Overview
Source: https://developers.fireblocks.com/reference/staking-overview



> **Learn more about Staking in Fireblocks here**

In Fireblocks, you can natively stake the following assets:

* [ETH](https://support.fireblocks.io/hc/en-us/articles/8757586323740-Staking-ETH)
* [MATIC](https://support.fireblocks.io/hc/en-us/articles/11948105257500-Staking-MATIC)
* [SOL](https://support.fireblocks.io/hc/en-us/articles/6991638294172-Staking-SOL)

This guide outlines the process for staking assets using the Fireblocks API. It includes prerequisites, a detailed flowchart, and necessary code snippets for successful asset staking.

The [Fireblocks API Reference](/reference/getchains) offers comprehensive documentation on all Fireblocks REST API endpoints. It includes example responses and SDK commands. You will find detailed information about requests and response objects for each functionality along with examples of SDK staking functions in various programming languages.

Before you begin the staking process, ensure the following:

* Fireblocks API Credentials: You must have the credentials for the Fireblocks API.
* Supported Staking Asset: Ensure you have a supported staking asset in a vault account, and validate that you have enough of that asset to stake. Each asset has specific characteristics:
  * **ETH**: You must stake in multiples of 32, up to 3200 ETH. Staking positions larger than 32 ETH are created using a smart contract and separated into distinct sets of 32 ETH. For example, staking 320 ETH will appear as 100 stakes of 32 ETH. To pay for fees, make sure you have a sufficient amount of ETH in the same vault account from which you intend to stake.
  * **SOL**: A minimum of 0.01 SOL must be retained in the vault account to cover transfer fees.
  * **MATIC**: Staking involves sending MATIC, the ERC-20 token on Ethereum, to the Polygon MATIC PoS Staking Contract. Please note that MATIC\_POLYGON, the gas token on the Polygon network, is not used for staking. There is no minimum for staking MATIC. Before the initial staking transaction from each vault account, you must sign an Approve transaction that allows the staking contract to withdraw your funds. Since fees are paid in ETH, you must have a sufficient amount of ETH in the same vault account from which you intend to stake your MATIC.

The following diagram outlines the high level flow for staking your assets in Fireblocks:

<img alt="" />


# Statuses
Source: https://developers.fireblocks.com/reference/statuses



# Overview

This article describes primary transaction statuses on Fireblocks and how they appear in the Fireblocks Console and API.

Many primary transaction statuses have substatuses that include additional status-related information. Learn more about [transaction substatuses](/reference/sub-statuses).

Transaction statuses are displayed in the Transaction History and the Recent Activity panel in the Fireblocks Console. You can hover over the status in the Recent Activity panel to see the substatus and additional details.

<img alt="" />

# Primary transaction statuses

## Submitted

The **Submitted** status indicates an outgoing transaction was submitted to the Fireblocks system and is currently being processed. It is the first stage for any outgoing transaction where AML/KYC screening is not enabled.

* **API status code:** SUBMITTED
* **Appears in the Fireblocks Console as:** Submitted

The status can be followed by **Queued** and then continue being processed.

Submitted transactions can be blocked by the Fireblocks Policy Engine or otherwise fail, with a substatus that includes additional information.

***

## Pending Screening

The **Pending Screening** status indicates a transaction’s progress depends on the transaction screening result from your Anti-Money Laundering (AML) provider or Travel Rule provider. Only transactions from workspaces with the AML or Travel Rule feature enabled can have this status.

* **API status code:** PENDING\_AML\_SCREENING
* **Appears in the Fireblocks Console as:** Pending Screening

This transaction status is not the same as the transaction’s [AML screening status](https://support.fireblocks.io/hc/en-us/articles/360014290380#screening-statuses-0-6) or [Travel Rule screening status](https://support.fireblocks.io/hc/en-us/articles/8271647366812-Travel-Rule-transaction-screening). Under certain circumstances, a transaction’s *screening* status can appear as **Pending** even when its transaction status shows as **Completed** on the Recent Activity panel. When you receive the screening result, you can view it in the transaction’s details on the Transaction History page.

***

## Pending Enrichment

The **Pending Enrichment** status indicates a transaction’s progress depends on the result of Fireblocks’ internal security screening. This security enhancement looks for connections to known smart contract vulnerabilities in limited situations. If a transaction is successfully enriched, some additional metadata is added to the transaction, and the transaction signer may see additional information on their Fireblocks mobile app. No additional notifications or actionable data are sent to the API Co-signer.

This internal security screening and enrichment takes place while initiating a transaction and usually takes a few seconds to complete. The status is followed by Pending Authorization. If security enrichment is unsuccessful, the transaction continues processing and does not fail. This security screening will not affect the approval flow of your transactions.

Three types of transactions can be enriched:

* **Typed messages on any EVM blockchain**: The typed message is parsed and displayed to the transaction signer.
* **Contract calls on Ethereum**: A simulation of the contract runs to see which vault assets and balances will be affected, and their projected final values. Outgoing and incoming values, and expected transaction fees are displayed to the transaction signer.
* **Any transaction initiated by a dApp**: The dApp and the transaction destination are scanned for malicious concern. If the dApp is identified as suspicious, or the destination address is flagged as sanctioned, a notification is shown to the transaction signer. The signer can still choose to sign the transaction and continue.

[Learn more about the dApp Protection feature and its security screening](https://support.fireblocks.io/hc/en-us/articles/11497035958940-dApp-Protection).

* **API status code:** PENDING\_ENRICHMENT
* **Appears in the Fireblocks Console as:** Pending Security Screening

This transaction status is not the same as the [Pending Screening status](#pending-screening) , which correlates to the screening from your AML or Travel Rule provider.

***

## Pending Authorization

The **Pending Authorization** status indicates an outgoing transaction’s progress depends on a Fireblocks Console user, an API user, or a group of users authorizing the transaction, as defined by the Policies.

* **API status code:** PENDING\_AUTHORIZATION
* **Appears in the Fireblocks Console as:** Pending Authorization

This status should be followed by **Queued** if the transaction is authorized or **Cancelled** if the transaction is not authorized. If no action is taken for two hours, the transaction will fail. Learn more about [transaction authorization expiration](https://support.fireblocks.io/hc/en-us/articles/360015963760).

***

## Queued

The **Queued** status indicates an outgoing transaction is queued for processing.

* **API status code:** QUEUED
* **Appears in the Fireblocks Console as:** Queued

Fireblocks can only process a single transaction per blockchain standard per vault account. For example, if you create a transaction for an Ethereum blockchain asset and another transaction for a Polygon blockchain asset from the same vault account, then Fireblocks will process them one at a time for signing because they are both EVM-compatible assets. However, if you create a Bitcoin transaction and a Solana transaction from the same vault account, then both transactions will be processed simultaneously.

### Transactions stuck in the Queued status

When a transaction appears stuck in the **Queued** status, you should check for another transaction in the **Pending Signature** status. This transaction's details will show the user or users who need to sign or reject the transaction for it to progress, which will allow the next transaction to progress.

To help streamline signing and avoid delays associated with manual signing, we recommend that you install and configure an API Co-Signer to process and sign transactions automatically according to your Policy rules.

***

## Pending Signature

The **Pending Signature** status indicates an outgoing transaction is waiting to be signed by the transaction’s designated signer as defined in your Policy. You can view who the designated signer is by hovering over the transaction's status in the Recent Activity panel.

* **API status code:** PENDING\_SIGNATURE
* **Appears in the Fireblocks Console as:** Pending Signature

If no action is taken for two hours after authorization, the transaction will fail. Learn more about [transaction signing expiration](https://support.fireblocks.io/hc/en-us/articles/360015963760).

To help streamline signing and avoid delays associated with manual signing, we recommend installing and configuring an API Co-Signer to process and sign transactions automatically according to your Policy rules.

***

## Pending email approval

The **Pending email approval** status indicates the transaction is waiting for the required approval from a third-party service, such as an exchange. The manual approval is usually sent via email.

* **API status code:** PENDING\_3RD\_PARTY\_MANUAL\_APPROVAL
* **Appears in the Fireblocks Console as:** Pending email approval

***

## Processing at the exchange

The **Processing at the exchange** status indicates a transaction is waiting for approval by a third-party service, such as an exchange.

* **API status code:** PENDING\_3RD\_PARTY
* **Appears in the Fireblocks Console as:** Processing at the exchange

Learn more about [Processing at the exchange substatuses](/reference/sub-statuses#pending_3rd_party-sub-statuses).

***

## Broadcasting

The **Broadcasting** status indicates an outgoing transaction is being broadcast to the blockchain network.

* **API status code:** BROADCASTING
* **Appears in the Fireblocks Console as:** Broadcasting

Typically, a transaction should remain in this status for no longer than one minute, but it depends on the current load on the Fireblocks system. When a transaction remains in this status for longer than one minute, check the [Fireblocks Status page](https://status.fireblocks.com/) to see if there are ongoing service disruptions. If you don’t see any service disruptions, contact Fireblocks Support for assistance.

***

## Confirming

The **Confirming** status indicates a transaction is waiting to be confirmed on the blockchain. Fireblocks monitors the state of the transaction on the blockchain and updates its status accordingly.

* **API status code:** CONFIRMING
* **Appears in the Fireblocks Console as:** Confirming

Learn more about [Confirming substatuses](/reference/sub-statuses#confirming-sub-statuses).

***

## Completed

The **Completed** status indicates the transaction was completed successfully, is now part of the blockchain, and all assets have been transferred.

* **API status code:** COMPLETED
* **Appears in the Fireblocks Console as:** Completed

**Completed** is a final transaction status and marks the transaction as successful. After a transaction is marked as completed, all associated assets are no longer available in their source account.

> **Note**
>
> If you use [webhooks](https://support.fireblocks.io/hc/en-us/articles/4408110107794) to receive transaction status updates, you may receive multiple updates to the **Completed** status. For example, if your Deposit Control & Confirmation Policy is set for zero confirmations for a particular blockchain, you may receive a webhook notification for the **Completed** status when the transaction appears on the blockchain as well as on its first or further confirmations.

Learn more about [Completed substatuses](/reference/sub-statuses#completed-sub-statuses).

***

## Cancelling

The **Cancelling** status indicates a transaction was canceled or rejected by a Fireblocks user, such as the transaction’s initiator, approver, or designated signer.

* **API status code:** CANCELLING
* **Appears in the Fireblocks Console as:** Cancelling

Typically, a transaction should remain in this status for no longer than 30 seconds, but it depends on the current load on the Fireblocks system. When a transaction remains in this status for longer than 30 seconds, check the [Fireblocks Status page](https://status.fireblocks.com/) to see if there are ongoing service disruptions. If you don’t see any service disruptions, contact Fireblocks Support for assistance.

***

## Cancelled

The **Cancelled** status indicates a transaction was canceled or rejected by a Fireblocks user, such as the transaction’s initiator, approver, or designated signer, or by the third-party service that was the source of the transaction.

* **API status code:** CANCELLED
* **Appears in the Fireblocks Console as:** Cancelled

**Cancelled** is a final transaction status and marks the transaction as unsuccessful. After a transaction is marked as canceled, all associated assets are available for new transactions.

Learn more about [Cancelled substatuses](/reference/sub-statuses#cancelled-sub-statuses).

***

## Blocked by policy

The **Blocked by policy** status indicates an outgoing transaction was blocked from being completed due to a Policy rule.

* **API status code:** BLOCKED
* **Appears in the Fireblocks Console as:** Blocked by policy

**Blocked by policy** is a final transaction status and marks the transaction as unsuccessful. After a transaction is marked as blocked, all associated assets are available for new transactions.

### Resolving blocked transactions

Transactions that are blocked by policy include the corresponding Policy rule number as it appears in your workspace's settings. If you want to allow these transactions, create a new policy rule in a position that allows the transaction to be correctly enforced according to the first-match principle.

Learn more about [Blocked by policy substatuses](/reference/sub-statuses#blocked-sub-statuses).

***

## Rejected

The **Rejected** status indicates an incoming or outgoing transaction was rejected by the Fireblocks system, an Approver or a Signer, or by a third-party service.

* **API status code:** REJECTED
* **Appears in the Fireblocks Console as:** Rejected by AML, Manually frozen

Transactions that are rejected or manually frozen mark the transaction as unsuccessful. Note that:

* After an *outgoing* transaction is marked as rejected, all associated assets are available for new transactions.
* After an *incoming* transaction is marked as rejected, all associated assets will not be available until an Admin-level user unfreezes them.

Learn more about [Rejected substatuses](/reference/sub-statuses#rejected-sub-statuses).

***

## Failed

The **Failed** status indicates the transaction is no longer being processed and no assets have been transferred. Transactions can fail from any state.

* **API status code:** FAILED
* **Appears in the Fireblocks Console as:** Failed

**Failed** is a final transaction status and marks the transaction as unsuccessful. After a transaction is marked as failed, all associated assets are available for new transactions.

Learn more about [Failed substatuses](/reference/sub-statuses#failed-sub-statuses).


# Structure
Source: https://developers.fireblocks.com/reference/structure



Overview of the structure of the Fireblocks retail demo application, including the database models and the business-logic services.

## Database Models

<img alt="" />

### User

Represents a user of the application.

**Columns**: id (PK), email, name, googleId, githubId, password, wallet (FK)

### Wallet

Represents a user's wallet.

**Columns**: id (PK), name, user (FK), assets (FK), transactions (FK), assetBalances (FK), description

### Asset

Represents a cryptocurrency asset.

**Columns**: id (PK), assetId, assetName, address, isSwept, balance, vaultAccount (FK), wallet (FK)

### Transaction

Represents a cryptocurrency transaction.

**Columns**: id (PK), assetId, status, fireblocksTxId, txHash, amount, isSweeping, wallet (FK), sourceVaultAccount (FK), destinationVaultAccount (FK), sourceExternalAddress, destinationExternalAddress, outgoing, createdAt

### VaultAccount

Represents a Fireblocks vault account.

**Columns**: id (PK), fireblocksVaultId, name, assets (FK), balance, sourceTransactions (FK), destinationTransactions (FK)

### WalletAssetBalance

Represents the balance of an asset in a wallet.

**Columns**: id (PK), wallet (FK), assetId, totalBalance, incomingPendingBalance, outgoingPendingBalance

### SupportedAssets

Represents the list of the assets supported by the demo application.

**Columns**: id (PK), explorerUrl, fireblocksAssetId, depositCounter, name

<img alt="" />

## Services

### [AuthService](https://github.com/fireblocks/retail-demo/blob/main/backend/src/service/auth.service.ts)

Handles user authentication and creation.

**Description**: The AuthService provides the functionality for user authentication and log in with email & password / GoogleOAuth2 / GitHub userId.

### [AssetService](https://github.com/fireblocks/retail-demo/blob/main/backend/src/service/asset.service.ts)

Handles balance updates for users' asset records and tracks which assets have already been swept to Omnibus.

### [WalletService](https://github.com/fireblocks/retail-demo/blob/main/backend/src/service/wallet.service.ts)

Manages wallet-related operations.

### [VaultService](https://github.com/fireblocks/retail-demo/blob/main/backend/src/service/vault.service.ts)

Interacts with Fireblocks vault accounts.

### [TransactionService](https://github.com/fireblocks/retail-demo/blob/main/backend/src/service/transaction.service.ts)

Handles transaction-related operations and updates users' transaction records on the database.

### [ApiClient](https://github.com/fireblocks/retail-demo/blob/main/backend/src/service/fireblocks/api.client.ts)

Handles the initialization of a Fireblocks API Client using environment variables.

**Description**: This service handles the creation of the Fireblocks API Client, which the app uses to interact with the Fireblocks API gateway.\
For more information on SDK initialization, check the [TypeScript SDK guide](/reference/typescript-sdk#your-first-fireblocks-typescript-code-example).\
The ApiClient also introduces two important concepts when working with the Fireblocks API:\
a. [Idempotent Requests ](/reference/api-idempotency)\
b. [Rate Limits](/reference/rate-limiting)

### [FireblocksTransactionService](https://github.com/fireblocks/retail-demo/blob/main/backend/src/service/fireblocks/transaction.service.ts)

Interacts with Fireblocks API for transaction creation and processing.\
**Description**: This service wraps the primary endpoints of the Fireblocks SDK to provide the required transaction-related functionality for the demo app.\
For more information on these endpoints, check the [Transaction section](/reference/gettransactions) on our API documentation.\
It also introduces the important concept of the *externalTxId* parameter, which is used for unique transaction identification and ensures transactions are idempotent forever.\
Learn more in the [Manage Withdrawals guide](/docs/manage-withdrawals-at-scale#idempotent-transactions).

### [FireblocksVaultAccountService](https://github.com/fireblocks/retail-demo/blob/main/backend/src/service/fireblocks/vaultAccount.service.ts)

Interacts with Fireblocks API for vault account-related operations.\
**Description**: This service wraps several endpoints of the Fireblocks SDK and provides vault account-related functionality to the demo application. It manages vault account creation and updates, as well as asset wallet and deposit address creation for users on the Fireblocks workspace.\
For more information on these endpoints, check the [Vaults section](/reference/createvaultaccount) on our API documentation.\
Also, useful information about your vault structure can be found in the [Manage Deposits guide](/docs/manage-deposits-at-scale).

### [ConsolidationService](https://github.com/fireblocks/retail-demo/blob/main/backend/src/service/consolidation.service.ts)

Manages UTXO asset deposits, monitors their count, and initiates UTXO consolidations in the omnibus vault account\
**Description**: This service handles all the UTXO asset deposit consolidation functionality. It will update the deposit counter for each supported UTXO asset per deposit and will trigger a consolidation Tx to burn small unspent inputs on the omnibus wallet to allow high withdrawal availability for users. Additionally, the service has an automated job that runs periodically to act as a backup to the deposit-triggered process and prevent a situation where more than 250 UTXOs are stored in the omnibus wallet.\
For more information, check the [Consolidate UTXOs guide](/reference/consolidate-utxos).

### [FeeService](https://github.com/fireblocks/retail-demo/blob/main/backend/src/service/fee.service.ts)

Handles the functionality to obtain the Tx fee estimations from Fireblocks API and calculates the required fee for a withdrawal Tx.\
For more information, check the [Estimate Transaction Fee guide](/reference/estimate-transaction-fee).

### [SweepingService](https://github.com/fireblocks/retail-demo/blob/main/backend/src/service/sweeping.service.ts)

Handles the functionality for sweeping account-based asset deposits from intermediate deposit vault accounts to the omnibus vault account.\
**Description**: This service acts as a job that runs periodically and checks for balances in the intermediate deposit vault accounts created for users. Once a balance above the sweeping threshold is found, a sweeping Tx is triggered to accumulate all user deposits of account-based assets into the omnibus vault account.\
For more information, check the [Sweep to Omnibus guide](/reference/sweep-to-omnibus-1).

### [WebhookService](https://github.com/fireblocks/retail-demo/blob/main/backend/src/service/webhook.service.ts)

Handles balance updates for user deposits based on the webhooks events sent from Fireblocks.\
Learn more about Fireblocks webhooks in the [Configure Webhooks guide](/reference/configure-webhook-urls).

### [WebSocketService](https://github.com/fireblocks/retail-demo/blob/main/backend/src/service/websocket.service.ts)

Manages real-time communication with the front end.


# Structure the API Call
Source: https://developers.fireblocks.com/reference/structure-the-api-call



## Structuring The Raw Signing request for Vaults

In your vaults, you can sign RAW messages via the [Create Transaction API endpoint](/reference/createtransaction) for a natively supported or unsupported asset.

1. To sign RAW messages for a natively supported asset, you need to use `assetId`and source account id under the payload. For your reference, please use the following code:

```javascript theme={"system"}
const res = await signer.createTransaction({
      assetId: 'BTC_TEST',
      note: 'raw signing test',
      source: {
        type: PeerType.VAULT_ACCOUNT,
        id: "vaultAccountId",
      },
      operation: TransactionOperation.RAW,
      extraParameters: {
        rawMessageData: {
          messages: [
            {
              content,
            },
          ],
        },
      },
    },
  );
```

2. To sign RAW messages for an unsupported asset, you need to use `derivationPath` and `algorithm` under the payload. For your reference, please use the following code:

```javascript theme={"system"}
const res = await signer.createTransaction(
  {
    note: "raw signing test",
    source: {
      type: PeerType.VAULT_ACCOUNT,
    },
    operation: TransactionOperation.RAW,
    extraParameters: {
      rawMessageData: {
        messages: [
          {
            content: "<your_content_to_sign>",
            bip44AddressIndex: 0, // Optional
            bip44change: 0, // Optional
            derivationPath: [44, 0, 0, 0, 0],
          },
        ],
        algorithm: "MPC_ECDSA_SECP256K1" / "MPC_EDDSA_ED25519",
      },
    },
  },
);
```

## Structuring The Raw Signing request for Embedded Wallets

In your embedded wallets, you can sign RAW messages via the [Create Transaction API endpoint](/reference/createtransaction) for a natively supported or unsupported asset.

1. To sign RAW messages for a natively supported asset, you need to use `assetId`and source account id under the payload. For your reference, please use the following code:

```javascript theme={"system"}
const res = await signer.createTransaction({
      assetId: 'BTC_TEST',
      note: 'raw signing test',
      source: {
        type: PeerType.END_USER_WALLET,
        walletId,
        id: "walletaccountId",
      },
      operation: TransactionOperation.RAW,
      extraParameters: {
        rawMessageData: {
          messages: [
            {
              content,
            },
          ],
        },
      },
    },{ ncw: { walletId } });
```

2. To sign RAW messages for an unsupported asset, you need to use `derivationPath` and `algorithm` under the payload. For your reference, please use the following code:

```javascript theme={"system"}
const res = await signer.createTransaction(
  {
    note: "raw signing test",
    source: {
      type: PeerType.END_USER_WALLET,
      walletId,
    },
    operation: TransactionOperation.RAW,
    extraParameters: {
      rawMessageData: {
        messages: [
          {
            content: "<your_content_to_sign>",
            derivationPath: [44, 0, 0, 0, 0],
          },
        ],
        algorithm: "MPC_ECDSA_SECP256K1" / "MPC_EDDSA_ED25519",
      },
    },
  },
  { ncw: { walletId } }
);
```

> **rawMessageData object:**
>
> [See here for more details](/reference/raw-signing-objects#rawmessagedata) on how to construct the`rawMessageData` object

> **About messages**
>
> You can aggregate a maximum of 127 messages for Raw Signing


# Structure the API Call
Source: https://developers.fireblocks.com/reference/structuring-the-api-call



> **Learn more about Typed Message Signing in Fireblocks in the following guide**

# Structuring the API Call:

Typed message signing in Fireblocks is performed through the [Fireblocks API - Create Transaction](/reference/createtransaction) Endpoint. The following parameters are required for any Typed Message Signing API request:

```json theme={"system"}
{
  operation: "TYPED_MESSAGE",
    assetId: "ETH"/"BTC"/"TRX",
    source: {
      type: "VAULT_ACCOUNT",
      id: "<vaultAccountId>"
  },
    extraParameters: {
    rawMessageData: {
      messages: [{
        content: "my_message",
        type: "EIP191"/"EIP712"/"TIP191"/"BTC_MESSAGE"
      }]
    }
  }
}
```

* `assetId` - The network to use (possible values are `ETH`, `BTC` and `TRX`
* `operation` - Transaction operation type (`TYPED_MESSAGE`)
* `source` - The vault account from which the Typed Message Signing is to be executed
* `extraParameters` - An additional parameters object that includes the `rawMessageData` object, which contains the messages array. Each message in this array specifies its `content` and the `type` of message signing. The possible types are: `EIP191`, `EIP712`, `TIP191` and `BTC_MESSAGE`

> **Fireblocks users are not required to prefix the message before submitting it to the API. The only requirement is that for any message type other than EIP712, the message to be signed must be submitted in hexadecimal format.**

For more detailed examples on how to structure your API calls correctly for the relevant supported asset, please refer to the guides per asset provided in this section.


# Sub-Statuses
Source: https://developers.fireblocks.com/reference/sub-statuses



# Overview

This article includes a list of sub-statuses related to [primary transaction statuses](/reference/statuses). Sub-statuses typically add clarification to primary statuses, such as a transaction failing due to incorrect user input. Some primary statuses do not have any sub-statuses.

Transaction statuses are displayed in the Transaction History and the Recent Activity panel in the Fireblocks Console. You can hover over the status in the Recent Activity panel to see the sub-status and additional details.

<img alt="" />

# Transaction sub-statuses

## PENDING\_3RD\_PARTY sub-statuses

| Status Code                                 | Description                                                                                              |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `3RD_PARTY_PROCESSING`                      | The transaction is awaiting approval by a third-party service, such as an exchange.                      |
| `3RD_PARTY_PENDING_SERVICE_MANUAL_APPROVAL` | Fireblocks is waiting for the third-party service to manually approve this transaction.                  |
| `PENDING_3RD_PARTY_MANUAL_APPROVAL`         | The third-party service is waiting for a customer’s approval, typically via email or the exchange's app. |

***

## CONFIRMING sub-statuses

| Status Code                        | Description                                                                             |
| ---------------------------------- | --------------------------------------------------------------------------------------- |
| `3RD_PARTY_CONFIRMING`             | The transaction is awaiting confirmation by a third-party service, such as an exchange. |
| `PENDING_BLOCKCHAIN_CONFIRMATIONS` | The transaction is awaiting confirmation on the blockchain.                             |

***

## COMPLETED sub-statuses

| Status Code                        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `3RD_PARTY_COMPLETED`              | The transaction was completed on a third-party service, such as an exchange.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `COMPLETED_BUT_3RD_PARTY_FAILED`   | The transaction was completed on the blockchain, as shown on block explorers, but it failed on the associated third-party platform. This is often a third-party system error. If the transaction was sent from a vault account in your Fireblocks workspace, the balance will be deducted from the account. If the exchange does not show the transaction in recent history or labels the transaction as failed, contact the exchange with the transaction details.                                                                                                                                                                       |
| `COMPLETED_BUT_3RD_PARTY_REJECTED` | The transaction was completed on the blockchain as shown on block explorers but rejected by the associated third-party platform. If the transaction was sent from a vault account in your Fireblocks workspace, the balance will be deducted from the account. An exchange may reject a transaction due to a user input error. For example, some exchanges require an account or deposit minimum. Alternatively, the transaction may have been manually canceled on the exchange. If the exchange does not show the transaction in recent history or labels the transaction as failed, contact the exchange with the transaction details. |
| `CONFIRMED`                        | The transaction reached the required number of confirmations on the blockchain and is recognized by all parties                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

***

## BLOCKED sub-statuses

| Status Code         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BLOCKED_BY_POLICY` | The transaction was blocked from being completed due to a Policy rule. Transactions that are blocked by the policy include the Policy rule number as it appears in your workspace Policy settings. If you want to allow these transactions, create a new policy rule in a position that allows the transaction to be correctly enforced according to the first-match principle. The `BLOCKED_BY_POLICY` sub-status can also indicate that your transaction was blocked due to the source address being a sanctioned address. |

***

## CANCELLED sub-statuses

| Status Code                 | Description                                                                                                |
| --------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `3RD_PARTY_CANCELLED`       | The transaction was canceled by a third party, such as an exchange.                                        |
| `3RD_PARTY_REJECTED`        | The transaction was rejected by a third party, such as an exchange, or not approved in time by the user.   |
| `CANCELLED_BY_USER`         | The transaction was canceled using the Fireblocks Console or the Fireblocks API or by an API Co-Signer.    |
| `CANCELLED_BY_USER_REQUEST` | The transaction was canceled by a user in your workspace contacting Fireblocks Support.                    |
| `REJECTED_BY_USER`          | The transaction was rejected by one of its signers using the Fireblocks mobile app or by an API Co-Signer. |

***

## REJECTED sub-statuses

| Status Code              | Description                                                                                                                                                                                                                                                       |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTO_FREEZE`            | The transaction was [frozen automatically](https://support.fireblocks.io/hc/en-us/articles/4409273351186#h_01GC932SYH1MD11FVSD3ECHMRZ) by the Transaction Screening Policy. Any associated assets will not be available until an Admin-level user unfreezes them. |
| `FROZEN_MANUALLY`        | The incoming transaction was frozen manually by a Fireblocks Console user or an API user. Any associated assets will not be available until an Admin-level user unfreezes them.                                                                                   |
| `REJECTED_AML_SCREENING` | The transaction was identified as high-risk by your AML service provider and rejected accordingly. Any associated assets will not be available until an Admin-level user unfreezes them.                                                                          |

***

## FAILED sub-statuses

### User input issues

| Status Code                                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ACTUAL_FEE_TOO_HIGH`                          | The transaction failed because the specified fee was lower than the current gas price. This issue usually occurs if network transaction fees have increased significantly between submitting and signing the transaction. Set the transaction fee to current rates and resubmit the transaction.                                                                                                                                                                                                                                                                                          |
| `ADDRESS_WHITELISTING_SUSPENDED`               | The outgoing transaction failed because the destination address was whitelisted too recently. This only applies to workspaces with [this feature](https://support.fireblocks.io/hc/en-us/articles/360019661399) manually enabled. Resubmit the transaction after the whitelisted address is active.                                                                                                                                                                                                                                                                                       |
| `AMOUNT_TOO_SMALL`                             | The transaction failed due to a withdrawal request below the minimum allowed amount. Some blockchains have required minimums for transactions to complete successfully. Alternatively, the transaction fee is higher than the net transfer amount on a gross transaction. Confirm the transfer amount is above the required minimum for this blockchain or more than the required transaction fees before resubmitting the transaction.  Minimum transfer amounts vary per blockchain.  Known minimums:  Bitcoin (BTC) - 546 satoshi  Cardano (ADA) - 1 ADA + applicable transaction fees |
| `AUTHORIZATION_FAILED`                         | The API Co-Signer Callback Handler did not correctly approve or sign the transaction. Review your Callback Handler authentication logic or confirm that your Callback Handler and API Co-Signer are correctly configured before resubmitting the transaction.                                                                                                                                                                                                                                                                                                                             |
| `AUTHORIZER_NOT_FOUND`                         | The transaction failed because an authorizer was not found for it, or the only available authorizer is the transaction’s initiator. This status occurs if the MPC device setup is incomplete for an authorizer or one authorizer in a Policy group. Ensure all authorizers have completed their MPC device setup before resubmitting the transaction.                                                                                                                                                                                                                                     |
| `ENV_UNSUPPORTED_ASSET`                        | The transaction failed because your workspace does not support the specified asset. This asset may be a testnet asset on a mainnet workspace or vice versa. Confirm that the correct asset ID is selected before resubmitting the transaction.                                                                                                                                                                                                                                                                                                                                            |
| `ERROR_UNSUPPORTED_TRANSACTION_TYPE`           | The transaction failed because Fireblocks does not currently support the transaction type for the specified blockchain.                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `GAS_LIMIT_TOO_LOW`                            | The transaction failed because the gas limit was set below the minimum amount to complete the transaction, causing it to be rejected by the blockchain. Make sure to set all fee parameters to sufficient amounts before resubmitting the transaction.                                                                                                                                                                                                                                                                                                                                    |
| `GAS_PRICE_TOO_LOW_FOR_RBF`                    | The transaction failed because the specified gas price was too low for Replace-by-Fee (RBF). Resubmit the RBF transaction with a gas price at least 15% higher than the original transaction's gas price.                                                                                                                                                                                                                                                                                                                                                                                 |
| `INCOMPLETE_USER_SETUP`                        | The transaction failed because the transaction's initiator did not complete their MPC key setup. Make sure that both the workspace Owner and the signer for this transaction have completed their MPC setup before resubmitting the transaction.                                                                                                                                                                                                                                                                                                                                          |
| `INSUFFICIENT_FUNDS`                           | The transaction failed because the vault account does not have enough funds to fulfill the withdrawal request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `INSUFFICIENT_FUNDS_FOR_FEE`                   | The transaction failed because the vault account does not have enough funds for the requested fee. Fees for token transfers (e.g., USDC) are paid in the base asset (e.g., ETH) from the same vault account as the transaction source.                                                                                                                                                                                                                                                                                                                                                    |
| `INTEGRATION_SUSPENDED`                        | The transaction failed due to Fireblocks Support deactivating an exchange integration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `INVALID_ADDRESS`                              | The transaction failed because the destination is an unsupported format for a one-time address. Verify that the address format matches the asset and blockchain before resubmitting the transaction.                                                                                                                                                                                                                                                                                                                                                                                      |
| `INVALID_CONTRACT_CALL_DATA`                   | The transaction failed because its data was not encoded properly. Typically, this occurs due to an internal error or an error made when using the Raw Signing feature. Confirm that the contract call and raw signing data have been encoded correctly before resubmitting this transaction. Check the Fireblocks Status page for ongoing service disruptions. If there are none, resubmit your transaction.                                                                                                                                                                              |
| `INVALID_FEE_PARAMS`                           | The transaction failed due to inconsistent or unknown fee parameters. Confirm that all fee parameters were entered correctly for the specified blockchain.                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `INVALID_NONCE_FOR_RBF`                        | The replacement transaction failed because Fireblocks did not find a matching pending transaction. Confirm the status of the original transaction before resubmitting this RBF transaction. RBF transactions can only be used with transactions that are *not* Failed or Confirmed. Check the Fireblocks Status page for ongoing service disruptions. If there are none, resubmit your transaction.                                                                                                                                                                                       |
| `INVALID_TAG_OR_MEMO`                          | The transaction failed due to an invalid destination tag or memo, which some assets require. Resubmit this transaction with the correct destination tag or memo for the selected asset type.                                                                                                                                                                                                                                                                                                                                                                                              |
| `INVALID_UNMANAGED_WALLET`                     | The transaction failed because the associated internal whitelisted wallet was removed or nonexistent. Verify that the entered Wallet ID is correct. If the wallet does not exist, create and approve the wallet and address before resubmitting the transaction.                                                                                                                                                                                                                                                                                                                          |
| `MAX_FEE_EXCEEDED`                             | The transaction failed because the current network gas prices exceeded the specified maximum fee. Verify that all fee parameters are set to current rates before resubmitting the transaction.                                                                                                                                                                                                                                                                                                                                                                                            |
| `MISSING_TAG_OR_MEMO`                          | The transaction failed due to a missing destination tag or memo, which some assets require. Resubmit this transaction with the correct destination tag or memo for the selected asset type.                                                                                                                                                                                                                                                                                                                                                                                               |
| `MISSING_DEPOSIT_CONFIRMATIONS_FOR_WITHDRAWAL` | The transaction failed due to the exchange not receiving the number of confirmations required to credit the associated main account or subaccount. This only applies to Binance exchange accounts.  Resolution via Binance: Use Binance's User Asset (USER\_DATA) endpoint to verify whether your assets are available for withdrawal.                                                                                                                                                                                                                                                    |
| `NEED_MORE_TO_CREATE_DESTINATION`              | The transaction failed due to insufficient funds for creating the destination account. Confirm the transaction amount is above the minimum requirement before resubmitting this transaction. Only the Polkadot, Kusama, and Westend (testnet) blockchains have this limitation.                                                                                                                                                                                                                                                                                                           |
| `NO_MORE_PREPROCESSED_INDEXES`                 | This sub-status only applies to outgoing transactions sent from Cold Wallet workspaces. It indicates that the Cold Wallet device has used all available signatures for signing. Use another existing device or provision a new signing device for your workspace.                                                                                                                                                                                                                                                                                                                         |
| `NON_EXISTING_ACCOUNT_NAME`                    | The transaction failed because the destination address cannot be validated. This only applies to whitelisted addresses, exchange account addresses, or one-time addresses on the EOS, NEAR, and Stellar networks. Verify that the destination address is correct before resubmitting this transaction. For some exchanges, you may need to generate a deposit address manually in the exchange's account settings.                                                                                                                                                                        |
| `RAW_MSG_EMPTY_OR_INVALID`                     | The raw signing transaction failed due to incorrect raw data. Validate the raw data before resubmitting this transaction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `RAW_MSG_LEN_INVALID`                          | The raw signing transaction failed due to incorrect raw data or the message length parameter that applies to ECDSA signing being incorrect. Validate the raw data and ECDSA signature parameters before resubmitting this transaction.                                                                                                                                                                                                                                                                                                                                                    |
| `TOO_MANY_INPUTS`                              | The transaction failed because the maximum number of UTXO inputs exceeded the requested amount. This only applies to the Bitcoin and Cardano blockchains.                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `TX_SIZE_EXCEEDED_MAX`                         | The `TX_SIZE_EXCEEDED_MAX` sub-status indicates the transaction failed because the transaction exceeded the allowed amount. This only applies to transactions on the Cardano blockchain.                                                                                                                                                                                                                                                                                                                                                                                                  |
| `UNAUTHORISED__DEVICE`                         | The transaction failed because an unauthorized device was used to initiate, approve, or sign it. Confirm that the approving and signing devices have the latest version of the Fireblocks mobile app before resubmitting this transaction.                                                                                                                                                                                                                                                                                                                                                |
| `UNAUTHORISED__USER`                           | The transaction failed due to an unauthorized user attempting to initiate or approve it. This may occur if a user's setup is incomplete or a user was disabled before the transaction was completed. Confirm that all relevant users have completed their mobile setup and are using the latest version of the Fireblocks mobile app before resubmitting this transaction.                                                                                                                                                                                                                |
| `UNALLOWED_RAW_PARAM_COMBINATION`              | The raw signing transaction failed due to incorrect raw data parameters. Validate the raw data parameters before resubmitting this transaction.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `UNSUPPORTED_OPERATION`                        | The transaction failed because Fireblocks or a third-party service does not currently support the specified operation. Check the status page for the third-party service, if available, and the Fireblocks Status page for ongoing service disruptions. If there are none, resubmit your transaction.                                                                                                                                                                                                                                                                                     |
| `UNSUPPORTED_TRANSACTION_TYPE`                 | The transaction failed due to either an API error or an internal system error. Confirm that the operation parameter is set to transfer or another value, then determine whether the specified parameters match the operation type.                                                                                                                                                                                                                                                                                                                                                        |
| `ZERO_BALANCE_IN_PERMANENT_ADDRESS`            | The transaction failed due to the permanent address not holding enough Omni. Check the Fireblocks Status page for ongoing service disruptions. If there are none, resubmit your transaction.                                                                                                                                                                                                                                                                                                                                                                                              |

### MPC issues

| Status Code                | Description                                                                                                                                                                                                                                    |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OUT_OF_DATE_SIGNING_KEYS` | The transaction failed because the signer's key share must be updated to the MPC-CMP protocol. [Learn more about updating any device to MPC-CMP in the Fireblocks help center](https://support.fireblocks.io/hc/en-us/articles/4411991378962). |

### Fireblocks system issues

| Status Code                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CONNECTIVITY_ERROR`            | The transaction failed due to an internal network error. Check the Fireblocks Status page for ongoing service disruptions. If there are none, resubmit your transaction.                                                                                                                                                                                                                                                                                 |
| `ERROR_ASYNC_TX_IN_FLIGHT`      | The transaction failed due to a Fireblocks internal error during processing. Check the Fireblocks Status page for ongoing service disruptions. If there are none, resubmit your transaction.                                                                                                                                                                                                                                                             |
| `INTERNAL_ERROR`                | The transaction failed due to a Fireblocks internal error during processing. Check the Fireblocks Status page for ongoing service disruptions. If there are none, resubmit your transaction.                                                                                                                                                                                                                                                             |
| `INVALID_NONCE_TOO_HIGH`        | The transaction failed because the Fireblocks system selected a nonce that is too high, creating a gap between the last transaction and this one. As a result, this transaction cannot be processed until the gap is filled. Check the Fireblocks Status page for ongoing service disruptions. If there are none, resubmit your transaction.                                                                                                             |
| `INVALID_NONCE_TOO_LOW`         | The transaction failed because the Fireblocks system assigned an illegal nonce. The nonce chosen for this transaction already belongs to a transaction that was previously confirmed on this account. This may occur when an RBF or drop transaction is used to replace a pending transaction that was completed before being replaced. If this transaction references another transaction, confirm the status of both transactions before resubmitting. |
| `INVALID_ROUTING_DESTINATION`   | The transaction failed because the Fireblocks system could not identify a valid destination. This status is specific to Fireblocks Network transactions. Check the Fireblocks Status page for ongoing service disruptions. If there are none, resubmit your transaction.                                                                                                                                                                                 |
| `LOCKING_NONCE_ACCOUNT_TIMEOUT` | The transaction failed because the transaction request timed out due to an internal error. Check the Fireblocks Status page for ongoing service disruptions. If there are none, resubmit your transaction.                                                                                                                                                                                                                                               |
| `NETWORK_ROUTING_MISMATCH`      | The transaction failed because a valid routing destination couldn’t be identified by the Fireblocks Network. Check the Fireblocks Status page for ongoing service disruptions. If there are none, resubmit your transaction.                                                                                                                                                                                                                             |
| `NONCE_ALLOCATION_FAILED`       | The transaction failed because the transaction could not be created due to an internal error. Check the Fireblocks Status page for ongoing service disruptions. If there are none, resubmit your transaction.                                                                                                                                                                                                                                            |
| `RESOURCE_ALREADY_EXISTS`       | The transaction failed due to a Fireblocks internal error during processing. Check the Fireblocks Status page for ongoing service disruptions. If there are none, resubmit your transaction.                                                                                                                                                                                                                                                             |
| `SIGNER_NOT_FOUND`              | The transaction failed because no signer was found for it. This transaction likely failed because the signer designated in the Policy does not have an MPC signing device setup, or the designated signer is no longer active in your workspace. Make sure the designated signer is available and has completed their MPC device setup before resubmitting this transaction.                                                                             |
| `SIGNING_ERROR`                 | The transaction failed due to an internal error during the MPC signing process. The transaction signer should make sure their Fireblocks mobile app is updated to the latest version before resubmitting this transaction.                                                                                                                                                                                                                               |
| `TIMEOUT`                       | The transaction failed because the transaction request timed out due to an internal error or because it was not approved or signed within the expiration window. If approval and signing were completed in the correct period, check the Fireblocks Status page for ongoing service disruptions. If there are none, resubmit your transaction.                                                                                                           |
| `TX_OUTDATED`                   | The transaction failed because the nonce set for this transaction by the Fireblocks system was used by another transaction. Check the Fireblocks Status page for ongoing service disruptions. If there are none, resubmit your transaction.                                                                                                                                                                                                              |
| `UNKNOWN_ERROR`                 | The transaction failed due to an unexpected error in the Fireblocks system. Check the Fireblocks Status page for ongoing service disruptions. If there are none, resubmit your transaction.                                                                                                                                                                                                                                                              |
| `UNSUPPORTED_MEDIA_TYPE`        | The transaction failed due to a Fireblocks internal error during processing. Check the Fireblocks Status page for ongoing service disruptions. If there are none, resubmit your transaction.                                                                                                                                                                                                                                                             |
| `VAULT_WALLET_NOT_READY`        | The transaction failed because the asset wallet in the specified vault account was not available for the transaction. This status usually occurs after creating multiple asset wallets in the same vault account at once. Activate the asset wallet before resubmitting this transaction.                                                                                                                                                                |

### Third-party account issues

| Status Code                          | Description                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ADDRESS_NOT_WHITELISTED`            | The transaction failed due to it attempting to withdraw funds from an exchange to a non-whitelisted destination address.                                                                                                                                                                                                                                                                                                 |
| `API_KEY_MISMATCH`                   | The transaction failed due to the third-party account API connectivity information no longer being accurate. Confirm that the API Key, API Secret, and other parameters are valid according to your third-party account portal, then delete and re-add the third-party account to your Fireblocks workspace before resubmitting this transaction.                                                                        |
| `ASSET_NOT_ENABLED_ON_DESTINATION`   | The transaction failed due to the asset type requiring manual enablement at a third-party destination, such as an exchange.                                                                                                                                                                                                                                                                                              |
| `DEST_TYPE_NOT_SUPPORTED`            | The transaction failed because the transaction from a third-party account to the selected destination is not supported. This sub-status currently only applies to withdrawals from a Paxos exchange account to a one-time address. To ensure a withdrawal transaction from Paxos is completed, use a whitelisted address instead of a one-time address.                                                                  |
| `EXCEEDED_DECIMAL_PRECISION`         | The transaction failed due to a third-party service not supporting the same amount of decimal digits for a transaction amount as Fireblocks. The exchange or fiat connection may then report an error that the amount is not supported. Re-submit the transaction with fewer decimals in the transaction amount. Currently, this issue most commonly occurs with Coinbase, Coinbase Pro, and Crypto.com.                 |
| `EXCHANGE_CONFIGURATION_MISMATCH`    | The transaction failed because the associated exchange integration is temporarily unavailable. Check the Fireblocks Status page for additional information. Contact Fireblocks Support to resolve this issue. Resubmitting the transaction without Fireblocks Support will result in a failed transaction.                                                                                                               |
| `EXCHANGE_VERSION_INCOMPATIBLE`      | The transaction failed because the associated exchange integration is temporarily unavailable. Contact Fireblocks Support to resolve this issue. Resubmitting the transaction without Fireblocks Support will result in a failed transaction.                                                                                                                                                                            |
| `INVALID_EXCHANGE_ACCOUNT`           | The transaction failed due to the associated exchange account being disabled or nonexistent.                                                                                                                                                                                                                                                                                                                             |
| `METHOD_NOT_ALLOWED`                 | The transaction failed because the associated exchange integration is temporarily unavailable. Contact Fireblocks Support to resolve this issue. Resubmitting the transaction without Fireblocks Support will result in a failed transaction.                                                                                                                                                                            |
| `NON_EXISTENT_AUTO_ACCOUNT`          | The transaction failed due to the third-party account configuration being incorrect in your Fireblocks workspace. Currently, this only occurs with Paxos exchange accounts. Verify that the third-party account is configured correctly. If needed, delete the account from your Fireblocks workspace, add it again, and then resubmit this transaction.                                                                 |
| `ON_PREMISE_CONNECTIVITY_ERROR`      | This sub-status only applies to transactions using the Fireblocks On-Prem Exchange Service (FOPES). This sub-status indicates that Fireblocks could not retrieve the third-party account's details due to a connectivity error with FOPES.                                                                                                                                                                               |
| `PEER_ACCOUNT_DOES_NOT_EXIST`        | The transaction failed because one of the following third-party account details is incorrect: this is a sub-account, and this sub-account name no longer exists on your third-party account, or your Fireblocks Network settings that were previously directed to this account have been deleted. Verify your third-party sub-account configuration or Fireblocks Network settings before resubmitting this transaction. |
| `THIRD_PARTY_MISSING_ACCOUNT`        | The transaction failed due to incorrect third-party account configuration in your Fireblocks workspace. Currently, this sub-status only occurs with the Zodia Fireblocks Network account. Verify that the third-party account is configured correctly. If needed, delete the account connection from your Fireblocks workspace, add it again, and then resubmit this transaction.                                        |
| `UNAUTHORISED__IP_WHITELISTING`      | The transaction failed due to the third-party account being misconfigured. The third-party account requires whitelisting a Fireblocks IP address, and that information is currently incorrect or missing. Delete the third-party account from your workspace, add it again using the correct Fireblocks IP address, and then resubmit this transaction.                                                                  |
| `UNAUTHORISED__MISSING_CREDENTIALS`  | The transaction failed due to missing credentials from a third-party service, such as an exchange.                                                                                                                                                                                                                                                                                                                       |
| `UNAUTHORISED__MISSING_PERMISSION`   | The transaction failed due to a missing third-party service’s API permission, such as an exchange’s API.                                                                                                                                                                                                                                                                                                                 |
| `UNAUTHORISED__OTP_FAILED`           | The transaction failed due to incorrect third-party account configuration. The third-party account requires specifying a Two-Factor Authentication (2FA) registration code, and a wrong code was entered during the third-party account configuration. Delete the third-party account from your workspace, add it again using the correct 2FA details, and then resubmit this transaction.                               |
| `WITHDRAW_LIMIT`                     | The transaction failed due to it exceeding the exchange's withdrawal limit.                                                                                                                                                                                                                                                                                                                                              |
| `PROVIDER_INSUFFICIENT_BALANC`       | The transaction failed because the provider reports insufficient balance to complete this withdrawal. Check your balance on the provider and ensure sufficient funds are available before resubmitting this transaction.                                                                                                                                                                                                 |
| `PROVIDER_ADDRESS_NOT_VERIFIED`      | The transaction failed because the withdrawal address has not been verified by the provider. Verify the address in your provider account settings before resubmitting this transaction.                                                                                                                                                                                                                                  |
| `PROVIDER_COMPLIANCE_INFO_REQUIRED`  | The transaction failed because the exchange requires additional compliance information for this withdrawal. Provide the required information through transaction PII details if supported, or through the provider platform directly.                                                                                                                                                                                    |
| `PROVIDER_ACCOUNT_ERROR`             | The transaction failed due to an issue with the provider account configuration. Verify that your provider account is active and properly configured before resubmitting this transaction.                                                                                                                                                                                                                                |
| `PROVIDER_WITHDRAWAL_LIMIT_EXCEEDED` | The transaction failed because the withdrawal amount exceeds a limit set by the provider. Reduce the amount or check the provider's withdrawal limits for your account tier before resubmitting this transaction.                                                                                                                                                                                                        |

### Third-party system issues

| Status Code                         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `3RD_PARTY_FAILED`                  | The transaction failed with a third-party service, such as an exchange. Check the status page for the third-party service and the Fireblocks Status page for ongoing service disruptions. If there are none, resubmit your transaction.                                                                                                                                                                                                                                                                  |
| `API_CALL_LIMIT`                    | The transaction failed because it exceeded the API call limit of a third-party service, such as an exchange. Wait a few seconds before making more API calls. API call limits vary between different exchanges. Make sure to follow each exchange’s published limits to avoid failed transactions.                                                                                                                                                                                                       |
| `API_INVALID_SIGNATURE`             | The transaction failed due to a third-party service’s API, such as an exchange’s API, providing an invalid signature. If this issue occurs more than once, delete the exchange account from your Fireblocks workspace and then connect it again. This may require generating a new API key and API secret from your exchange account settings.                                                                                                                                                           |
| `CANCELLED_EXTERNALLY`              | The transaction failed due to being canceled by the third-party service associated with the transaction's source address. Contact the third-party service with the transaction details to determine the issue.                                                                                                                                                                                                                                                                                           |
| `FAILED_AML_SCREENING`              | The transaction failed Anti-Money Laundering (AML) screening due to the AML service provider not communicating their results.                                                                                                                                                                                                                                                                                                                                                                            |
| `INVALID_FEE`                       | The transaction failed because there is an insufficient balance in the exchange account of the asset required for the withdrawal and transaction fees. Withdrawal and transaction fees from exchange accounts are calculated after a transaction is submitted. Review the exchange’s withdrawal fee policy, and then verify there is a sufficient balance in the account for all fees before resubmitting this transaction.                                                                              |
| `INVALID_THIRD_PARTY_RESPONSE`      | The transaction failed due to Fireblocks receiving an unrecognized or invalid response from a third-party service, such as an exchange. If this issue occurs repeatedly, delete the exchange account from your Fireblocks workspace and then reconnect it. This may require generating a new API key and API secret from your exchange account settings. Resubmit the transaction after reconnecting the exchange account.                                                                               |
| `MANUAL_DEPOSIT_ADDRESS_REQUIRED`   | The transaction failed due to Fireblocks encountering an error while retrieving a deposit address from an exchange. Manually generate a deposit address for the selected asset from your exchange account settings. Resubmit the transaction using that address.                                                                                                                                                                                                                                         |
| `MISSING_DEPOSIT ADDRESS`           | The transaction failed because Fireblocks was unable to retrieve a deposit address from the exchange. Verify that the deposit address is accurate, then resubmit the transaction. If this issue occurs repeatedly, delete the exchange account from your Fireblocks workspace and then reconnect it. This may require generating a new API key and API secret from your exchange account settings. Resubmit the transaction after reconnecting the exchange account.                                     |
| `NO_DEPOSIT_ADDRESS`                | The transaction failed because the deposit address was unavailable or had not been created on a third-party service, such as an exchange. Verify that the deposit address is accurate, then resubmit the transaction. If this issue occurs repeatedly, delete the exchange account from your Fireblocks workspace and then reconnect it. This may require generating a new API key and API secret from your exchange account settings. Resubmit the transaction after reconnecting the exchange account. |
| `SUB_ACCOUNTS_NOT_SUPPORTED`        | The transaction failed because this exchange integration doesn't support transactions between main and subaccounts or between different subaccounts. You can only create transactions in Fireblocks to or from this exchange's main account. Use your exchange account portal to transact with this subaccount.                                                                                                                                                                                          |
| `SPEND_COINBASE_TOO_EARLY`          | The `SPEND_COINBASE_TOO_EARLY` sub-status indicates the transaction failed because the UTXO assets received as mining awards in your Coinbase account have not reached the minimum number of blockchain confirmations. You can withdraw the assets after they receive the required number of confirmations. Bitcoin mining rewards require 100 confirmations before they can be withdrawn.                                                                                                               |
| `THIRD_PARTY_INTERNAL_ERROR`        | The transaction failed due to Fireblocks receiving an internal error response from a third-party service, such as an exchange. This error is most commonly associated with Binance. Check the status page for the third-party service and the Fireblocks Status page for ongoing service disruptions. If there are none, resubmit your transaction.                                                                                                                                                      |
| `TX_ID_NOT_ACCEPTED_BY_THIRD_PARTY` | The transaction failed due to an unexpected error that occurred when trying to resolve the destination address through the Zodia registry. Contact Zodia Support for assistance if the transaction fails repeatedly with this sub-status.                                                                                                                                                                                                                                                                |
| `UNSUPPORTED_ASSET`                 | The transaction failed because the specified asset is not supported by a third-party service, such as an exchange. Confirm that the asset is available and enabled in your exchange account settings. Then, submit a transaction with a lower asset amount.                                                                                                                                                                                                                                              |
| `PROVIDER_SYSTEM_ERROR`             | The transaction failed because the provider is experiencing a temporary system issue. Try again later. If this issue persists, check the provider's status page for ongoing service disruptions.                                                                                                                                                                                                                                                                                                         |
| `PROVIDER_WITHDRAWAL_SUSPENDED`     | The transaction failed because the provider has suspended withdrawals for this asset. Check the provider's status page for updates on withdrawal availability.                                                                                                                                                                                                                                                                                                                                           |
| `PROVIDER_ASSET_NOT_AVAILABLE`      | The transaction failed because this asset or blockchain is not currently available for withdrawal on the provider. Consider using an alternative chain or try again later.                                                                                                                                                                                                                                                                                                                               |
| `PROVIDER_WITHDRAWAL_MAINTENANCE`   | The transaction failed because the provider is performing blockchain maintenance. Check the provider's status page for estimated completion time before resubmitting this transaction.                                                                                                                                                                                                                                                                                                                   |
| `PROVIDER_RATE_LIMITED`             | The transaction failed because the provider is rejecting requests due to too many transactions in a short period. Wait a few minutes before resubmitting this transaction.                                                                                                                                                                                                                                                                                                                               |

### Blockchain issues

| Status Code                         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DOUBLE_SPENDING`                   | The transaction failed due to the blockchain determining that a transaction with a duplicate hash exists in the mempool. This could be caused by a Fireblocks internal error or by another user signing with the full private key outside of Fireblocks. This is only relevant for UTXO-based blockchain transactions. Only the initial transaction is processed in this case. Check the status of the initial transaction in your transaction history for any issues. Check the Fireblocks Status page for ongoing service disruptions. If there are none, resubmit your transaction.                                                      |
| `DROPPED_BY_BLOCKCHAIN`             | The transaction failed before being confirmed on the blockchain, or that the transaction was mined but dropped. Funds become available again to the source account. This can occur for several reasons:   - **Nonce replacement (RBF):** A higher-fee transaction with the same nonce replaced the original. This can result from a manual RBF submission or a Fireblocks boost or drop operation. - **Mempool eviction:** The transaction was removed from the mempool due to a low gas price, network congestion, or a timeout. - **Network rejection:** The transaction was rejected by the node before it could be included in a block. |
| `INSUFFICIENT_RESERVED_FUNDING`     | The transaction failed because a minimum amount of the selected asset must remain in the asset wallet at all times. Currently, this only applies to the Polkadot and Westend (Polkadot testnet) blockchains. Resubmit the transaction with an amount that leaves at least one DOT in the source account.                                                                                                                                                                                                                                                                                                                                    |
| `INVALID_SIGNATURE`                 | The transaction failed because the blockchain rejected it due to an invalid signature. Check the Fireblocks Status page for ongoing service disruptions. If there are none, resubmit your transaction.                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `PARTIALLY_FAILED`                  | One or more aggregated transactions submitted as a single operation have failed. Note that aggregated transactions are submitted to the blockchain network individually and can be partially or fully completed or fail. Confirm the status and sub-status of each aggregated transaction, and determine the issue for each to find a resolution.                                                                                                                                                                                                                                                                                           |
| `POWERUP_SUGGESTION_FAILURE`        | The transaction failed due to a Fireblocks internal error during the processing of transaction fees on the EOS blockchain. Check the Fireblocks Status page for ongoing service disruptions on the EOS blockchain. If there are none, resubmit your transaction.                                                                                                                                                                                                                                                                                                                                                                            |
| `REACHED_MEMPOOL_LIMIT_FOR_ACCOUNT` | This sub-status only occurs with transactions on the Tezos blockchain. The blockchain's mempool does not allow more than one active transaction from an account. Therefore, if one transaction from that source vault account already exists in the mempool, all other transactions that are pending blockchain confirmations will be rejected. Wait until all previous Tezos transactions from the same vault account have been completed or failed before sending another transaction from that same source vault account.                                                                                                                |
| `REJECTED_BY_BLOCKCHAIN`            | The transaction failed due to being rejected by the blockchain or the EOS node. Typically, transactions are rejected by the blockchain when the selected fee is significantly lower than the current average rate. Resubmit this transaction with a higher fee, or check the blockchain network activity and resubmit when the network is less active.                                                                                                                                                                                                                                                                                      |
| `SMART_CONTRACT_EXECUTION_FAILED`   | This error occurs when the transaction reverts due to a smart contract error. Check the transaction's `errorDescription` field for the specific reversion reason.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `TOO_LONG_MEMPOOL_CHAIN`            | The transaction failed because there are too many unconfirmed transactions pending from an address. Wait for unconfirmed transactions from the same vault account to be confirmed before resubmitting this transaction. If this issue persists, consider using multiple vault accounts to distribute activity.                                                                                                                                                                                                                                                                                                                              |


# Blockchain & Asset Objects
Source: https://developers.fireblocks.com/reference/supported-assets-object



## AssetTypeResponse

| Parameter       | Type   | Description                                                                            |
| --------------- | ------ | -------------------------------------------------------------------------------------- |
| id              | string | The ID of the asset                                                                    |
| name            | string | The name of the asset                                                                  |
| type            | string | \[ ALGO\_ASSET, BASE\_ASSET, BEP20, ERC20, FIAT, SOL\_ASSET, TRON\_TRC20, XLM\_ASSET ] |
| contractAddress | string | Contract address for ERC-20 smart contracts                                            |
| nativeAsset     | string | The name of the native asset                                                           |
| decimals        | number | The number of digits after the decimal point                                           |

***

## ValidateAddressResponse

| Parameter   | Type    | Description                                                                                                                       |
| ----------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| isValid     | boolean | Returns `true` if the address is valid. Returns "false" if the address is the wrong format.                                       |
| isActive    | boolean | Returns `true` if the address is active. Returns `false` if the address doesn't have a sufficient balance or requires activation. |
| requiresTag | boolean | Returns "true" if the address requires a destination tag, memo, or note.                                                          |


# Sweep to Omnibus
Source: https://developers.fireblocks.com/reference/sweep-to-omnibus-1



# Overview

For customers covering different market segments, the Fireblocks platform can support several different use cases by offering two options for your main vault structure: **Segregated** **account** vault structure and omnibus account vault structure.

> **Important:**
>
> Detailed information about each of these vault structures and how each can be implemented per use case. It's important to understand the differences.
>
> * **Intermediate vault accounts**: This is the vault account assigned to an end client. Because you could have numerous end clients, you can use the Fireblocks API to automatically generate as many intermediate vault accounts as needed.
> * **Omnibus deposits**: This is the central vault omnibus account where end-client funds are swept and stored.
> * **Withdrawal pool**: This is the vault account containing funds allocated for end-client withdrawal requests. More than one withdrawal pool vault account is required due to blockchain limitations.
>
> [Learn more about best practices for structuring your Fireblocks Vault.](https://support.fireblocks.io/hc/en-us/articles/5253421857564)

## Sweeping

The sweeping operation moves the funds from the intermediate vault accounts, assigned to your end-users for their deposits, into your omnibus account.

As an on-chain transfer of funds, sweeping requires you to pay fees from a source vault account. Set the triggering factor for when sweeping logic is applied based on business needs.

For example, this can be:

* Based on the capacity of the funds accumulated inside the Intermediate vault account
* Periodically based on a set time frame (daily, weekly)
* Based on the network fees - These fluctuate during different times of the day.

> **Reconciliation, crediting, and confirmation control**
>
> To learn more about additional parameters that affect sweeping, see below.
>
> * [Reconciliation & crediting](https://support.fireblocks.io/hc/en-us/articles/5431957627548-Best-practices-for-transaction-reconciliation-and-crediting) - You can create an automated mechanism that notifies your organization or clients about incoming transactions via webhook notifications or by using the Fireblocks API.
> * [Deposit control & Control policy](https://support.fireblocks.io/hc/en-us/articles/360013034359-Deposit-Control-Confirmation-Policy) - The Deposit Control & Confirmation Policy lets you specify how many network confirmations are required for an incoming transaction to clear so its funds can be credited to a wallet.

## Fueling

Sweeping will move the funds into your omnibus account from vault accounts existing on intermediate vault accounts that are assigned to your end-users for their deposits.

When sweeping non-base assets from intermediate vault accounts, such as ERC-20 tokens, the transaction fee should be paid in the base asset.

> **Example**
>
> USDC transfer fees on Ethereum are paid in ETH. Therefore, these accounts must be fueled with ETH (or "gas") to fund the transaction fees that are required for sweeping.

Fireblocks provides an automated fueling service known as the Gas Station to save you the trouble of managing this manually. You can learn more about it in the [Gas station setup and usage](doc:gas-station-setup) guide.

## Example

### Step 1: Create the vault accounts in batch

This guide assumes you use a backend “internal ledger” system that will correlate the internal customer ref ID with your new Fireblocks vault account ID.

[See a basic example of an internal ledger mechanism description.](doc:sweep-to-omnibus#internal-ledger-for-tracking-the-balance-of-end-users)

Using the following code example:

1. Create the vault accounts for your end-users using your chosen naming convention to identify the vault accounts for your user deposits.
2. Create your ETH deposit address under the vault accounts.
3. Create your omnibus vault account used as the treasury account.

The example demonstrates calling either the `createVaultAccounts`or`create_vault_accounts` function that is passed with the `amount` parameter value as the number of vault accounts you wish to create for your sweeping batch, the underlying vault accounts, the name used to describe the batch, and the treasury omnibus account that will be used for the sweeping process.

In the example below, 3 vault accounts are created

```javascript theme={"system"}
const createVaultAccounts = async (
  amountOfVaultAccounts: number,
  assetId: string,
  vaultAccountNamePrefix: string
): Promise<Array<{}> | undefined> => {
  const result: Array<{}> = [];
  try {
    for (let i = 1; i <= amountOfVaultAccounts; i++) {
      const vaultAccountResponse = await fireblocks.vaults.createVaultAccount(
        {
          createVaultAccountRequest:
          {
            name: vaultAccountNamePrefix.toString() + i.toString()
          }
        }
      );
      let vaultWalletAddress = await fireblocks.vaults.createVaultAccountAsset(
        {
          vaultAccountId: vaultAccountResponse.data.id as string,
          assetId
        }
      );
      result.push({
        "Vault Account Name": vaultAccountResponse.data.name,
        "Vault Account ID": vaultAccountResponse.data.id,
        "Asset ID": assetId,
        "Address": vaultWalletAddress.data.address
      })
      console.log("Vault Account Details: ", result);
    }

    return result;
  }
  catch (error) {
    console.error(error);
  }
}

createVaultAccounts(2, "ETH_TEST6", "END-USER#22223");
```

```javascript theme={"system"}
async function createVaultAccounts(amountOfVaultAccounts, assetId, vaultAccountNamePrefix){
    let vaultRes;
    let vault;
    let vaultWallet;

    for (let i = 1; i <= amountOfVaultAccounts; i++){
            vaultRes = await fireblocks.createVaultAccount(vaultAccountNamePrefix.toString()+i.toString());
            vault = {
                vaultName: vaultRes.name,
                vaultID: vaultRes.id
            }
            vaultWallet = await fireblocks.createVaultAsset(Number(vault.vaultID), assetId);
            console.log("Created vault account", vault.vaultName,":", "with wallet address:", vaultWallet.address);
    };
 }
 createVaultAccounts(2, "ETH","END-USER-#","treasuryVaultName");
```

```python theme={"system"}
ASSET = "ETH_TEST"
def create_vault_accounts(amount: int) -> dict:
   """
   :param amount: Amount of vault accounts to create (one, per end user).
   :return: A dictionary where keys are the vault names and IDs are the co-responding values.
   """
   vault_dict = {}
   counter = 1

   while counter <= amount:
       vault_name = f"End-User {counter} Vault"
       vault_id = fireblocks.create_vault_account(name=vault_name, hiddenOnUI=True)['id']
       fireblocks.create_vault_asset(vault_id, ASSET)
       vault_dict[vault_name] = vault_id
       counter += 1
   else:
       vault_name = "Treasury"
       vault_id = SDK.create_vault_account(name=vault_name)['id']
       fireblocks.create_vault_asset(vault_id, ASSET)
       vault_dict[vault_name] = vault_id

   return vault_dict
```

### Step 2: Create the sweeping logic

This guide assumes that your "internal ledger" can produce a list of vault accounts that are relevant for treasury sweeping. For a basic "internal ledger" mechanism description, review the section at the bottom of this article.

You will define which vault accounts will be swept to your omnibus account. The next example shows the sweeping of any account that has at least 1 ETH to the relevant treasury account.

* Define the intermediate vault accounts that you wish to sweep their funds from.
* Initiate the Create Transaction loop.

### Testing

Add this code block to the code you built using any of the language-specific guides under the **Developing with Fireblocks** section.

```javascript theme={"system"}
const createTagWithdrawalVaultAccounts = async (
  assetId: string,
  name: string,
): Promise<Array<{}> | undefined> => {
  const result: Array<{}> = [];

  try {
    const vaultAccount = await fireblocks.vaults.createVaultAccount({
      createVaultAccountRequest: {
        name,
      },
    });

    if (vaultAccount.data) {
      const vaultWallet = await fireblocks.vaults.createVaultAccountAsset({
        vaultAccountId: vaultAccount.data.id as string,
        assetId,
      });

      result.push({
        "Vault Account Name": vaultAccount.data.name,
        "Vault Account ID": vaultAccount.data.id,
        "Asset ID": assetId,
        Address: vaultWallet.data.address,
      });

      console.log(JSON.stringify(result, null, 2));
    }

    return result;
  } catch (error) {
    console.error(error);
  }
};

const sweepToOmnibus = async (
  vaNamePrefix: string,
  minAmount: number,
  assetId: string,
  omnibusVaId: string,
): Promise<
  Array<{
    fromVaName: string;
    fromVaId: string;
    txId: string;
    grossAmount: string;
  }>
> => {
  let sweepingInfo: any[] = [];

  const vaultsToSweepFrom = await fireblocks.vaults.getPagedVaultAccounts({
    namePrefix: vaNamePrefix,
    assetId,
    minAmountThreshold: minAmount,
  });

  if (vaultsToSweepFrom.data.accounts) {
    await Promise.all(
      vaultsToSweepFrom.data.accounts.map(
        async (vaultAccount: VaultAccount) => {
          if (vaultAccount.assets && vaultAccount.assets.length > 0) {
            const createTxResponse =
              await fireblocks.transactions.createTransaction({
                transactionRequest: {
                  assetId,
                  source: {
                    type: TransferPeerPathType.VaultAccount,
                    id: vaultAccount.id,
                  },
                  destination: {
                    type: TransferPeerPathType.VaultAccount,
                    id: omnibusVaId,
                  },
                  amount: vaultAccount.assets[0].available,
                },
              });

            sweepingInfo.push({
              fromVaName: vaultAccount.name,
              fromVaId: vaultAccount.id,
              txId: createTxResponse.data.id,
              grossAmount: vaultAccount.assets[0].available,
            });
          }
        },
      ),
    );
  }

  console.log(
    "Initiated sweeping transactions:\n" +
      JSON.stringify(sweepingInfo, null, 2),
  );
  return sweepingInfo;
};

sweepToOmnibus("END-USER-#", 0.1, "ETH_TEST5", "0");
```

```javascript theme={"system"}
async function sweep(vaultAccountNamePrefixtoSweep, sweepAmount, assetId, treasuryVaultAccountId){
    vaultListToSweep = await fireblocks.getVaultAccountsWithPageInfo({namePrefix: vaultAccountNamePrefixtoSweep, assetId: assetId, minAmountThreshold:sweepAmount});
    for (let i = 0; i < Object.keys(vaultListToSweep.accounts).length; i++) {
        await fireblocks.createTransaction({
            "assetId" : assetId,
            "source" : {
                "type" : PeerType.VAULT_ACCOUNT,
                "id" : vaultListToSweep.accounts[i].id
            },
            "destination" : {
                "type" : PeerType.VAULT_ACCOUNT,
                "id" : String(treasuryVaultAccountId)
            },
            "amount" : vaultListToSweep.accounts[i].assets[0].total,
        })
    };
    vaultListToSweep.accounts.forEach(element => {
        console.log("Swept", "Vault id:", element.id,", Vault name:", element.name);
    })
 }
sweep("END-USER-#",1,"ETH","0");
```

```python theme={"system"}
ASSET = "ETH_TEST"
def sweep_accounts(treasury_vault_id: str) -> dict:
   """
   :param treasury_vault_id: The vault that will receive all the funds.
   :return: A dictionary of accounts swept with the values being the amount transferred.
   """
   vault_dict = {}
   vault_accounts = fireblocks.get_vault_accounts(name_prefix="End-User")
   for vault in vault_accounts['accounts']:
       for asset in vault['assets']:
           if asset['id'] == ASSET and int(asset['amount']) >= 1:
               fireblocks.create_transaction(
                   asset_id=ASSET,
                   amount=asset['amount'],
                   source=TransferPeerPath(
                       peer_type=VAULT_ACCOUNT,
                       peer_id=vault['id']
                   ),
                   destination=DestinationTransferPeerPath(
                       peer_type=VAULT_ACCOUNT,
                       peer_id=treasury_vault_id
                   )
               )
               vault_dict[vault['name']] = asset['amount']

   return vault_accounts
```


# Transaction Authorization Objects
Source: https://developers.fireblocks.com/reference/transaction-authorization-objects



## AuthorizationInfo

| Parameter                 | Type                                               | Description                                                                                                                                                                                                                                                                                                                                      |
| ------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| allowOperatorAsAuthorizer | boolean                                            | Set to "true" if the initiator of the transaction can be one of the approvers                                                                                                                                                                                                                                                                    |
| logic                     | string                                             | "AND" or "OR"; is the logic that is applied between the different authorization groups listed below.                                                                                                                                                                                                                                             |
| groups                    | list of [AuthorizationGroups](#authorizationgroup) | The list of authorization groups and users that are required to approve this transaction. The logic applied between the different groups is the “logic” field above. Each element in the response is the user ID (found via the [List users](/api-reference/users/list-users) endpoint) and the value is their [ApprovalStatus](#approvalstatus) |

***

## AuthorizationGroup

| Parameter | Type            | Description                                                                                                                                                                                                                                                                                      |
| --------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| th        | number          | The threshold of required approvers in this authorization group                                                                                                                                                                                                                                  |
| users     | object of users | The mapping of users to which the threshold number is applied for transaction approval. Each user in the response is a "key:value" where the key is the user ID (found via the [List users](/api-reference/users/list-users) endpoint) and the value is their [ApprovalStatus](#approvalstatus). |

***

## ApprovalStatus

| Parameter | Type   | Description                                         |
| --------- | ------ | --------------------------------------------------- |
| approval  | string | \[ PENDING\_AUTHORIZATION, APPROVED, REJECTED, NA ] |


# Transaction Objects
Source: https://developers.fireblocks.com/reference/transaction-objects



## InputsSelection

| Parameter       | Type                      | Description                                      |
| --------------- | ------------------------- | ------------------------------------------------ |
| inputsToSpend   | Array of [Inputs](#input) | Inputs that should be used in the transaction    |
| inputsToExclude | Array of [Inputs](#input) | Inputs that shouldn't be used in the transaction |

***

## Input

| Parameter | Type   | Description        |
| --------- | ------ | ------------------ |
| txHash    | string | txHash             |
| index     | string | vOut of the txHash |

***

## DestinationTransferPeerPath

| Parameter      | Type                              | Description                                                                                                                                           |
| -------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| type           | string                            | \[ VAULT\_ACCOUNT, EXCHANGE\_ACCOUNT, INTERNAL\_WALLET, EXTERNAL\_WALLET, UNMANAGED\_WALLET, ONE\_TIME\_ADDRESS, NETWORK\_CONNECTION, FIAT\_ACCOUNT ] |
| id             | string                            | The peer ID (not needed for ONE\_TIME\_ADDRESS)                                                                                                       |
| oneTimeAddress | [OneTimeAddress](#onetimeaddress) | Destination address                                                                                                                                   |

***

## OneTimeAddress

| Parameter | Type   | Description                                                                                                                                                          |
| --------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| address   | string | Transfer destination address                                                                                                                                         |
| tag       | string | Used as destination tag for XRP;`memo for ATOM, EOS, HBAR, LUNA, LUNC, XDB, XEM;`memo\_text`for XLM;`notes\` for ALGO; Bank Transfer Description for fiat providers. |

***

## BlockInfo

| Parameter   | Type   | Description                                                   |
| ----------- | ------ | ------------------------------------------------------------- |
| blockHeight | string | The height (number) of the block the transaction was mined in |
| blockHash   | string | The hash of the block the transaction was mined in            |

***

## RewardsInfo

| Parameter   | Type   | Description                                                                 |
| ----------- | ------ | --------------------------------------------------------------------------- |
| srcRewards  | string | The ALGO rewards acknowledged by the source account of the transaction      |
| destRewards | string | The ALGO rewards acknowledged by the destination account of the transaction |

***

## BlockchainInfo

| **Blockchain** | **Parameter**        | **Type**                                                    | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| -------------- | -------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| HBAR           |                      |                                                             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
|                | hbarTxHash           | string                                                      | HBAR transaction hash                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| EVM            |                      |                                                             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
|                | evmTransferType      | enum                                                        | Type of transfer:  **NATIVE** for native transfer.  **TOKEN** for token transfers that are reflected via the transaction’s logs.  **INTERNAL** for internal transfers that are reflected via the transaction’s traces.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| TON            |                      |                                                             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
|                | messageComment       | string                                                      | Contains the payload of the internal message (see [TON internal message docs](https://docs.ton.org/v3/documentation/smart-contracts/message-management/internal-messages)).  This field represents the smart contract input or data sent to the wallet.  Unlike structured blockchains (e.g. EVM, Solana, Stellar), TON allows arbitrary message bodies. Fireblocks exposes this raw data so you can apply custom parsing logic for non-standard formats if needed.                                                                                                                                                                                                                                                                                                                   |
|                | tonTransferType      | enum                                                        | Type of transfer:  **NATIVE** for native transfer.  **JETTON** for Jetton transfer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
|                | hashes               | [TonHashes](/reference/transaction-objects#/tonhashes)      | Additional hashes of ton transfers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| CANTON         |                      |                                                             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
|                | transactionType      | enum                                                        | Types of transactions:   - **OFFER** - Transfer initiated. Sender has created a transfer offer awaiting the recipient's action. This is the first step in a 2-step transfer flow. - **ACCEPT** - Transfer completed. The recipient has accepted the pending transfer offer. Funds have been transferred successfully. - **REJECT** - Transfer failed. Recipient has rejected the pending transfer offer. No funds were transferred. - **WITHDRAW** - Transfer cancelled. Sender has withdrawn/cancelled their pending transfer offer before recipient took action. No funds were transferred. - **PRE\_APPROVAL** - Transfer completed instantly. Recipient had pre-approved incoming transfers, enabling a 1-step transfer flow (e.g., transfers from external sources like Kraken). |
|                | traceableId          | string                                                      | `UpdateId` of the original transfer offer or auto-approved transaction. The hash that could be used to locate the transaction in Canton explorers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
|                | hashes               | [CantonHashes](/reference/transaction-objects#cantonhashes) | Additional hashes of Canton transfers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| DOT            |                      |                                                             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
|                | substrateExtrinsicId | string                                                      | The extrinsic ID of the transaction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| SUI            |                      |                                                             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
|                | gasUsed              | [GasUsed](/reference/transaction-objects#gasused)           | Detailed breakdown of the costs incurred. The total gas cost and gas rebate can be calculated from these values.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

> For **ACCEPT**, **REJECT**, and **WITHDRAW** transaction types, the `offerUpdateId` links back to the original **OFFER** transaction, enabling full transaction lifecycle tracking.

***

## TonHashes

| Parameter        | Type   | Description                           |
| ---------------- | ------ | ------------------------------------- |
| externalIncoming | string | Hash of the external incoming message |
| tonTransfer      | string | Hash of the ton transfer              |
| jettonTransfer   | string | Hash of the jetton transfer           |

## CantonHashes

| Parameter           | Type   | Description                                                                                                                      |
| ------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------- |
| offerUpdateId       | string | `UpdateId` of the original transfer offer transaction. Present in transaction types such as OFFER, ACCEPT, REJECT, and WITHDRAW. |
| acceptUpdateId      | string | `UpdateId` of the accept action transaction. Present in transaction types like ACCEPT.                                           |
| rejectUpdateId      | string | `UpdateId` of the reject action transaction. Present in transaction types like REJECT.                                           |
| withdrawUpdateId    | string | `UpdateId` of the withdraw action transaction. Present in transaction types like WITHDRAW.                                       |
| preApprovalUpdateId | string | `UpdateId` of the pre-approval transfer transaction. Present in transaction types like PRE\_APPROVAL.                            |

## GasUsed

| Parameter               | Type   | Description                                          |
| ----------------------- | ------ | ---------------------------------------------------- |
| storageCost             | string | Gas units consumed for data storage.                 |
| storageRebate           | string | Gas units refunded due to storage cleanup.           |
| computationCost         | string | Gas units consumed for computation.                  |
| nonRefundableStorageFee | string | A portion of the storage fee that is non-refundable. |

***

## feeInfo

| Parameter   | Type    | Description                                                                                               |
| ----------- | ------- | --------------------------------------------------------------------------------------------------------- |
| networkFee  | string  | The fee paid to the network                                                                               |
| serviceFee  | string  | The total fee deducted by the exchange from the actual requested amount (serviceFee = amount - netAmount) |
| gasPrice    | string  | The amount of gas required by/paid to the network to process the transaction                              |
| paidByRelay | boolean | `true` or `false`; indicates whether the relay paid the fee                                               |
| relayType   | string  | Indicates whether the relay is the same tenant (`LOCAL`) or another tenant (`THIRD_PARTY`)                |
| relayId     | string  | The Vault account ID of the relay                                                                         |
| relayName   | string  | The name of the tenant hosting the third-party relay                                                      |

***

## NetworkRecord

| Parameter          | Type                                                                                 | Description                                                          |
| ------------------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
| source             | [TransferPeerPathResponse](/reference/transaction-webhooks#transferpeerpathresponse) | Source of the transaction                                            |
| destination        | [TransferPeerPathResponse](/reference/transaction-webhooks#transferpeerpathresponse) | Destination of the transaction                                       |
| txHash             | string                                                                               | Blockchain hash of the transaction                                   |
| networkFee         | number                                                                               | The fee paid to the network                                          |
| assetId            | string                                                                               | Transaction asset                                                    |
| netAmount          | number                                                                               | The net amount of the transaction, after fee deduction               |
| status             | [NetworkStatus](#networkstatus) object                                               | Status of the blockchain transaction                                 |
| type               | string                                                                               | Type of the operation                                                |
| destinationAddress | string                                                                               | Destination address                                                  |
| sourceAddress      | string                                                                               | For account-based assets only, the source address of the transaction |

***

## NetworkStatus

| Parameter     | Type | Description                                                                                                                                                                                                                                                                                                                    |
| ------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| networkStatus | enum | `DROPPED` - The transaction was dropped by the network (Typically due to a low fee, or if the mempool is full). \n`BROADCASTING` - Broadcasting to the blockchain. \n`CONFIRMING` - Pending confirmations. \n`FAILED` - The transaction has failed to complete on the blockchain. \n`CONFIRMED` - Confirmed on the blockchain. |

***

## TransactionRequestDestination

| Parameter   | Type                                                        | Description                               |
| ----------- | ----------------------------------------------------------- | ----------------------------------------- |
| amount      | string                                                      | The amount to be sent to this destination |
| destination | [DestinationTransferPeerPath](#destinationtransferpeerpath) | The specific destination                  |

***

## DropTransactionRequest

| Parameter | Type   | Description                                                    |
| --------- | ------ | -------------------------------------------------------------- |
| txId      | string | The ID of the transaction being dropped.                       |
| feeLevel  | string | The fee level for the replacement of non-ETH transactions.     |
| gasPrice  | string | The network fee level for the replacement of ETH transactions. |

***

## DropTransactionResponse

| Parameter    | Type    | Description                                                   |
| ------------ | ------- | ------------------------------------------------------------- |
| success      | boolean | True if the transaction dropped or the replacement succeeded. |
| transactions | array   | Dropped Transaction replacement Transaction ID(s).            |

***

## SetConfirmationsThresholdResponse

| Parameter    | Type             | Description               |
| ------------ | ---------------- | ------------------------- |
| success      | boolean          |                           |
| transactions | array of strings | txIds of the transactions |

***

## NodeControls

| Parameter | Type          | Description                                                                                                                                                                             |
| --------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type      | string (enum) | Transaction routing type. \nEnum Values: \n \n- **NODE\_ROUTER**\n- **MEV**For routing transactions to a custom node set - **NODE\_ROUTER** \n For MEV protection routing set - **MEV** |
| tag       | string        | Used for **NODE\_ROUTER** type only. The pre-configured tag of the node to route the transaction to                                                                                     |

## Index

| Parameter | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                            |
| --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Index     | integer | **(Optional)** Fireblocks’ internal identifier for a specific transfer within a transaction.   - For UTXO-based assets, this field corresponds to the UTOX's vOut index. - For other blockchains, like EVM, Tron, Solana, etc., this field is derived from the sequential position of the event within the transaction's transfer list. The field is not returned when the transaction includes multiple destinations. |

## logIndex

| Parameter | Type    | Description                                                                                                                                                                         |
| --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| logIndex  | integer | Applicable to EVM blockchains only. Represents the EVM log index that indicates the order of the log within the block. This information can be verified directly on the blockchain. |

## blockchainIndex

| Parameter       | Type   | Description                                                                                                                                                                                                                                                                                                                                                        |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| blockchainIndex | string | Blockchain-native transfer identifier showing the transfer’s exact position within the block data (e.g. log entry, trace path, or nested array index).   - **EVM token transfers**: Uses logIndex. - **EVM internal transfers**: Uses traceAddress (e.g., \[0,1,2] → "0\_1\_2"). - **Solana**: Refers to the nested instruction position in the instruction array. |

## nonce

| Parameter | Type   | Description                                     |
| --------- | ------ | ----------------------------------------------- |
| nonce     | string | Blockchain nonce for the transaction (EVM only) |


# Transaction Screening Objects
Source: https://developers.fireblocks.com/reference/transaction-screening-objects



## ComplianceResult

| Parameter       | Type                                                                                            | Description                                                    |
| --------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| aml             | [AmlScreeningResult](/reference/transaction-screening-objects#amlscreeningresult)               | An object containing AML screening result information.         |
| amlList         | array of [AmlScreeningResult](/reference/transaction-screening-objects#amlscreeningresult)      | List of AML screening result objects.                          |
| amlRegistration | [AmlRegistration](/reference/transaction-screening-objects#amlregistration)                     | An object containing AML registration information.             |
| tr              | [TravelRuleScreeningResult](/reference/transaction-screening-objects#travelrulescreeningresult) | An object containing Travel Rule screening result information. |
| status          | string                                                                                          | The status of the AML or Travel Rule screening request.        |

## AmlScreeningResult

| Parameter               | Type   | Description                                                                                                     |
| ----------------------- | ------ | --------------------------------------------------------------------------------------------------------------- |
| provider                | string | The AML service provider.                                                                                       |
| payload                 | any    | The response of the AML service provider.                                                                       |
| screeningStatus         | string | The status of the AML screening request.                                                                        |
| bypassReason            | string | The reason the transaction bypassed AML screening.                                                              |
| timestamp               | number | The date of the AML screening request in timestamp format.                                                      |
| category                | string | The risk category included the transaction screening.                                                           |
| categoryId              | number | The Chainalysis ID of the risk category.                                                                        |
| customerRefId           | string | The Customer Reference ID associated with the transaction.                                                      |
| destAddress             | string | For multi-destination transactions, the destination address with the highest risk of being screened.            |
| externalId              | string | The AML provider's ID of the screening result.                                                                  |
| matchedAlert            | any    | The alert corresponding to the result for matchedRule.                                                          |
| matchedRule             | any    | The AML Post-Screening Policy rule that matched the transaction.                                                |
| matchedPrescreeningRule | any    | The AML Transaction Screening Policy rule that matched the transaction.                                         |
| risk                    | string | The risk score for your transaction.                                                                            |
| verdict                 | string | The verdict that was made based on the provider's response and the post-screening policy rule that was matched. |

## AmlRegistration

| Parameter | Type    | Description                                            |
| --------- | ------- | ------------------------------------------------------ |
| provider  | string  | The AML service provider.                              |
| success   | boolean | Specifies whether the AML registration was successful. |
| timestamp | number  | The date of the AML registration in timestamp format.  |

## TravelRuleScreeningResult

| Parameter               | Type   | Description                                                                     |
| ----------------------- | ------ | ------------------------------------------------------------------------------- |
| provider                | string | The Travel Rule service provider.                                               |
| verdict                 | string | ACCEPT, REJECT, ALERT, WAIT, FREEZE, CANCEL                                     |
| payload                 | any    | The response of the Travel Rule service provider.                               |
| matchedRule             | any    | The Travel Rule Post-Screening Policy rule that matched the transaction.        |
| matchedPrescreeningRule | any    | The Travel Rule Transaction Screening Policy rule that matched the transaction. |
| bypassReason            | string | The reason the transaction bypassed Travel Rule screening.                      |
| timestamp               | number | The date of the Travel Rule screening request in timestamp format.              |
| status                  | string | The status of the Travel Rule screening request.                                |


# Transaction Sources & Destinations
Source: https://developers.fireblocks.com/reference/transaction-sources-destinations



All transactions in Fireblocks must have a source and a destination. This article describes the available options depending on transaction type and status.

***

# Available sources and destinations

## CONTRACT

If you had whitelisted a smart contract address and will be interacting with the smart contract or a one-time address.

* **Creating a new transaction:** Available as a destination.
* **Getting an existing transaction:** Available as a destination.

## END\_USER\_WALLET

Represents an [embedded wallet](/docs/create-embedded-wallets).

* **Creating a new transaction:** Available as a source and a destination.
* **Getting an existing transaction:** Available as a source and a destination.

## EXCHANGE\_ACCOUNT

A third-party exchange account connected to your workspace. The Fireblocks exchange integration supports initiating transactions to or from connected accounts and other addresses in your workspace, enabling you to use your Policies and a unified interface for all your exchange accounts.

* **Creating a new transaction:** Available as a source and a destination.
* **Getting an existing transaction:** Available as a source and a destination.

> **Note**
>
> Fireblocks only identifies the source of an incoming transaction as an exchange account if the transaction was initiated within your Fireblocks workspace. Otherwise, the source is displayed as `UNKNOWN`. This includes transactions initiated using the exchange's account portal.

## EXTERNAL\_WALLET

A whitelisted wallet assigned as external is typically used for addresses managed by your clients and counterparties.

* **Creating a new transaction:** Available as a destination.
* **Getting an existing transaction:** Available as a source and a destination.

## FIAT\_ACCOUNT

A third-party fiat account connected to your workspace.

* **Creating a new transaction:** Available as a source and a destination.
* **Getting an existing transaction:** Available as a source and a destination.

> **Note**
>
> Fireblocks only identifies the source of an incoming transaction as a fiat account if the transaction was initiated within your Fireblocks workspace. Otherwise, the source is displayed as `UNKNOWN`.

## GAS\_STATION

Your connected Gas Station account. The Fireblocks Gas Station is an opt-in service that automates asset funding for token transaction fees on EVM-based networks such as Ethereum, BSC, and others.

* **Creating a new transaction:** Available as a destination.
* **Getting an existing transaction:** Available as a source and a destination.

## INTERNAL\_WALLET

A whitelisted wallet assigned as internal is typically used for addresses that you control outside of your Fireblocks workspace. Internal addresses display their current balance and are included in your workspace's total billable address count.

* **Creating a new transaction:** Available as a destination.
* **Getting an existing transaction:** Available as a source and a destination.

## MULTI\_DESTINATION

A possible destination value when querying for past multi-destination transactions.

* **Creating a new transaction:** `NONE` or `MULTI_DESTINATION`, depending on the Fireblocks account. Learn more [here](https://support.fireblocks.io/hc/en-us/articles/360018447980-Multi-destination-UTXO-transactions#h_01KB0PP172XD02XT0GV8NZQ9VY).
* **Getting an existing transaction:** Available as a destination.

## NETWORK\_CONNECTION

The Fireblocks Network is a peer-to-peer, institutional liquidity and transfer network of 1,500+ liquidity providers, lending desks, and trading counterparties. You can transfer assets from any source connected to your workspace to any Network connection after the connection request is approved by both parties.

* **Creating a new transaction:** Available as a destination.
* **Getting an existing transaction:** Available as a source and a destination.

## OEC\_PARTNER

This represents the off-exchange partner. When funds are being sent to the exchange during a settlement, the destination will show up as `OEC_PARTNER`.

* **Creating a new transaction:** Available as a destination.
* **Getting an existing transaction:** Available as a destination.

## ONE\_TIME\_ADDRESS

This option is for transferring assets to non-whitelisted addresses from your Fireblocks Workspace.

> **Note**
>
> This feature is disabled by default because it poses security risks. We recommend configuring a strict Policy before enabling it.

* **Creating a new transaction:** Available as a destination.
* **Getting an existing transaction:** Available as a destination.

## PROGRAM\_CALL

Interacting with programs on the Solana Network (similar to contract calls).

* **Creating a new transaction:** Available as a destination.
* **Getting an existing transaction:** Unavailable.

## UNKNOWN

The default source of incoming transactions if Fireblocks was unable to match the source address to any of the other known sources in your workspace.

* **Creating a new transaction:** Unavailable.
* **Getting an existing transaction:** Available as a source.

## VAULT\_ACCOUNT

An account in your Fireblocks Vault.

* **Creating a new transaction:** Available as a source and a destination.
* **Getting an existing transaction:** Available as a source and a destination.

***

# Deprecated

## COMPOUND

> **Deprecated**
>
> As of **April 1st, 2023**, compound integration with Fireblocks has been deprecated.

Compound integration with Fireblocks was deprecated on **April 1st, 2023**. Older transactions may have this as their source or destination if the workspace had a direct integration between Fireblocks and the Compound DeFi protocol.

* **Creating a new transaction:** Unavailable.
* **Getting an existing transaction:** Available as a source and a destination.


# Transaction Webhooks
Source: https://developers.fireblocks.com/reference/transaction-webhooks



> **Deprecation notice**
>
> Webhooks v1 will be deprecated on **June 15th, 2026**. Please use the Developer Center in the Fireblocks Console to upgrade to Webhooks V2, which offers improved reliability, performance, and observability.

This page describes all events related to transactions that produce webhook notifications, along with their associated data objects.

The `type` parameter is automatically set to the description name for the data objects below.

> **Deprecated & Optional parameters**
>
> * Deprecated parameters may still appear in webhook payloads for backwards compatibility reasons. However, Fireblocks no longer maintains these parameters and they should not be used.
> * Some parameters are optional and may not appear in responses if empty. If you experience an issue, contact your Customer Success Manager.

## Transaction initiated

A notification is sent when a new transaction is initiated in the workspace.

**Webhook data**

| Parameter | Type                                      | Description                             |
| --------- | ----------------------------------------- | --------------------------------------- |
| type      | string                                    | TRANSACTION\_CREATED                    |
| tenantId  | string                                    | Unique ID of your Fireblocks' workspace |
| timestamp | number                                    | Timestamp in milliseconds               |
| data      | [TransactionDetails](#transactiondetails) | All the transaction information         |

***

## Transaction status updated

A notification is sent when there is any change in a transaction's status or when the number of confirmations is updated.

**Webhook data**

| Parameter | Type                                      | Description                             |
| --------- | ----------------------------------------- | --------------------------------------- |
| type      | string                                    | TRANSACTION\_STATUS\_UPDATED            |
| tenantId  | string                                    | Unique ID of your Fireblocks' workspace |
| timestamp | number                                    | Timestamp in milliseconds               |
| data      | [TransactionDetails](#transactiondetails) | All the transaction information         |

***

## Transaction approval status updated

A notification is sent with every approval based on the Policies.

**Webhook data**

| Parameter | Type                                      | Description                             |
| --------- | ----------------------------------------- | --------------------------------------- |
| type      | string                                    | TRANSACTION\_APPROVAL\_STATUS\_UPDATED  |
| tenantId  | string                                    | Unique ID of your Fireblocks' workspace |
| timestamp | number                                    | Timestamp in milliseconds               |
| data      | [TransactionDetails](#transactiondetails) | All the transaction information         |

***

### TransactionDetails

| Parameter                     | Type                                                                                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ----------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                            | string                                                                                   | The ID of the transaction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| externalTxId                  | string                                                                                   | Unique transaction ID provided by the user. Fireblocks recommends setting an externalTxId for every transaction created, to avoid submitting the same transaction twice.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| status                        | string                                                                                   | The current primary status of the transaction. See [Primary Transaction Statuses](https://support.fireblocks.io/hc/en-us/articles/5536566813468) for a detailed list.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| subStatus                     | string                                                                                   | See [Transaction Substatuses](https://support.fireblocks.io/hc/en-us/articles/5643077899036) for a detailed list of transaction substatuses.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| txHash                        | string                                                                                   | The hash of this transaction on the blockchain. txHash is only returned for crypto assets (not fiat) when the operation type is not `RAW` or `TYPED_MESSAGE`.  This parameter exists if at least one of the following conditions is met:   1. The transaction’s source type is `UNKNOWN`, `WHITELISTED_ADDRESS`, `ONE_TIME_ADDRESS`, `FIAT` or `GAS_STATION`. 2. The transaction’s source type is `VAULT` and the status is CONFIRMING, COMPLETED, or was either status before changing to FAILED or REJECTED. Some transactions with the status BROADCASTING will also include the txHash. 3. The transaction’s source type is `EXCHANGE` and the transaction’s destination type is `VAULT`, and the status is: CONFIRMING, COMPLETED, or was either status before changing to FAILED. |
| operation                     | [TransactionOperation](#transactionoperation)                                            | The transaction operation type. The default is `TRANSFER`. ll appear in webhook payloads for backwards compatibility reasons. However, Fireblocks no longer maintains these para                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| note                          | string                                                                                   | Custom note that describes this transaction in your Fireblocks workspace. This note is not sent to the blockchain.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| assetId                       | string                                                                                   | The ID of the transaction’s asset, for TRANSFER, MINT, BURN, or ENABLE\_ASSET operations. [See the list of supported assets and their IDs on Fireblocks](/reference/list-supported-assets).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| assetType                     | [AssetType](/reference/supported-assets-object)                                          | one of the following - XLM\_ASSET XDB\_ASSET TRON\_TRC20 SOL\_ASSET HBAR\_ERC20 FIAT ERC721 ERC20 ERC1155 BEP20 BASE\_ASSET ALGO\_ASSET                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| source                        | [TransferPeerPathResponse](#transferpeerpathresponse)                                    | The transaction’s source.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| sourceAddress                 | string                                                                                   | If the status is CONFIRMING, COMPLETED, or was CONFIRMING before either FAILED or REJECTED this parameter will contain only one source address even if the transaction is multi-input UTXO. This parameter is empty in any other case.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| destination                   | [TransferPeerPathResponse](#transferpeerpath)                                            | The transaction’s destination. If a transaction is sent to multiple destinations, the **destinations** parameter is used instead.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| destinations                  | Array of [DestinationsResponse](#destinationsresponse)                                   | For UTXO-based assets. All outputs are specified here.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| destinationAddress            | string                                                                                   | Address where the asset was transferred. For [Multi-destination transactions](https://support.fireblocks.io/hc/en-us/articles/360018447980-Multi-destination-transactions), this parameter will be empty and you should refer to the destinations field instead.  If the status is CONFIRMING, COMPLETED, or was CONFIRMING before either FAILED or REJECTED this parameter will contain the destination address. This parameter is empty in any other case.                                                                                                                                                                                                                                                                                                                            |
| destinationAddressDescription | string                                                                                   | Description of the address.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| destinationTag                | string                                                                                   | (Optional) Destination address tag for Ripple; destination memo for Cosmos, EOS, Luna, Luna Classic, NEM, Stellar, Hedera, & DigitalBits; destination note for Algorand; bank transfer description for fiat providers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| amountInfo                    | [AmountInfo](#amountinfo)                                                                | For `TRANSFER` operations. All details of the transfer amount.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| treatAsGrossAmount            | boolean                                                                                  | When set to **true**, the fee is deducted from the requested amount for transactions initiated from this Fireblocks workspace.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| feeInfo                       | [FeeInfo](#feeinfo) object                                                               | Details of the transaction's fee.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| feeCurrency                   | string                                                                                   | The asset type used to pay the fee (ETH for ERC-20 tokens, BTC for Omni, XLM for Stellar tokens, etc.)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| networkRecords                | Array of [NetworkRecord](/reference/transaction-objects#networkrecord) objects           | A transaction in Fireblocks can aggregate several blockchain transactions, typically as part of a contract call. Network records specify all intermediate transactions that took place on the blockchain. For single transactions, this parameter is empty.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| createdAt                     | number                                                                                   | The transaction’s creation date and time. Shown as a Unix timestamp.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| lastUpdated                   | number                                                                                   | The transaction’s last update date and time. Shown as a Unix timestamp.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| createdBy                     | string                                                                                   | User ID of the transaction's initiator.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| signedBy                      | Array of strings                                                                         | User ID(s) of the transaction's signer(s).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| rejectedBy                    | string                                                                                   | User ID of the user that rejected the transaction. Only populated when a transaction is rejected.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| authorizationInfo             | [AuthorizationInfo](/reference/transaction-authorization-objects#authorizationinfo)      | Data object with information about your Policies. For more about Policies, refer to the [Fireblocks Help Center](https://support.fireblocks.io/hc/en-us/articles/7354983580316-About-the-TAP).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| exchangeTxId                  | string                                                                                   | If the transaction originated from an exchange, this is the exchange’s ID of this transaction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| customerRefId                 | string                                                                                   | The ID for AML providers to associate the owner of the funds with the transaction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| amlScreeningResult            | [AmlScreeningResult](/reference/transaction-screening-objects#amlscreeningresult) object | The result of the AML screening.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| replacedTxHash                | string                                                                                   | The hash of the replaced transaction. Only populated if this is an RBF transaction on an EVM blockchain. [Learn more about RBF transactions](https://support.fireblocks.io/hc/en-us/articles/360018600160-Boosting-or-dropping-a-stuck-EVM-based-transaction).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| extraParameters               | [TransactionExtraParameters](#extraparameters) object                                    | Parameters that are specific to some transaction operation types and blockchain networks.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| signedMessages                | Array of [SignedMessage](/reference/raw-signing-objects#signedmessage) objects           | A list of signed messages returned for raw signing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| numOfConfirmations            | number                                                                                   | The number of blockchain confirmations of the transaction. The number will increase until your workspace's confirmation policy threshold is satisfied.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| blockInfo                     | [BlockInfo](/reference/transaction-objects#blockinfo) object                             | The hash and height of the block in which the transaction was mined. If an outgoing transaction uses the destinations object with more than one value in the array, **blockHash** is set to null.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| index                         | number                                                                                   | (Optional) For UTXO-based assets this is the vOut. For EVM-based, this is the index of the event of the contract call. This field is not returned if a transaction uses the destinations object with more than one value.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| blockchainIndex               | string                                                                                   | Identifies the specific log entry or nested log entries related to the funds transfer. Uses dot notation for nested logs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| paidRent                      | string                                                                                   | The amount of rent paid in SOL to the destination token account. **Currently in gradual rollout to customers.**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| rewardsInfo                   | [RewardsInfo](/reference/transaction-objects#rewardsinfo) object                         | This field is relevant only for ALGO transactions. Both srcRewrds and destRewards appear only for vault-to-vault transactions. Otherwise, only your workspace side of the transaction is recorded.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| systemMessages                | Array of [SystemMessageInfo](#systemmessageinfo) objects                                 | A response from Fireblocks with details about the health of the current process(es). If this object is returned with data, expect potential delays or incomplete transaction statuses.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| addressType                   | string                                                                                   | (Optional) ated parameters  Depreca                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| requestedAmount (Deprecated)  | number                                                                                   | The amount requested by the user.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| amount (Deprecated)           | number                                                                                   | If the transfer is a withdrawal from an exchange, the actual transfer amount. Otherwise, the requested amount.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| netAmount (Deprecated)        | number                                                                                   | The net amount of the transfer, after fee deduction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| amountUSD (Deprecated)        | number                                                                                   | The USD value of the requested amount.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| serviceFee (Deprecated)       | number                                                                                   | The total fee deducted by the exchange from the actual requested amount (serviceFee = amount - netAmount).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| networkFee (Deprecated)       | number                                                                                   | The fee paid to the blockchain network.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

***

### TransactionOperation

| Parameter | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| operation | string | `TRANSFER` - Default. Transfers funds from one account to another. UTXO blockchains allow multi-input and multi-output transfers. All other blockchains allow transfers with one source address and one destination address.  `MINT` - Mints new tokens. Supported for Stellar, Ripple, and EVM-based blockchains. [Learn more about tokenization on Fireblocks](https://support.fireblocks.io/hc/en-us/articles/4725474481308).  `BURN` - Burns tokens. Supported for Stellar, Ripple, and EVM-based blockchains. [Learn more about tokenization on Fireblocks](https://support.fireblocks.io/hc/en-us/articles/4725474481308).  `CONTRACT_CALL` - Calls a smart contract method for web3 operations on any EVM blockchain. The [Fireblocks development libraries](/reference/evm-web3-provider#convenience-libraries) are recommended for building contract call transactions.  `TYPED_MESSAGE` - An off-chain message in either Ethereum Personal Message or EIP712 format. Use it to sign specific readable messages that are not actual transactions. [Learn more about typed messages](https://support.fireblocks.io/hc/en-us/articles/4413379762450-Off-chain-message-signing#h_01FQXY26HB87NZJFRT77B1KY6Z).  `RAW` - An off-chain message with no predefined format. Use it to sign any message with your private key, including protocols such as blockchains and custom transaction types not natively supported by Fireblocks. [Learn more about raw signing transactions](https://support.fireblocks.io/hc/en-us/articles/4413379762450-Off-chain-message-signing).  `ENABLE_ASSET` - Algorand, DigitalBits, Solana, and Stellar require an on-chain transaction to create an asset wallet and enable the deposit address. This transaction is automatically created when adding assets on these blockchains to a vault account.  `STAKE` - Assign assets to a staking pool managed by a staking validator. [Learn more about staking transactions and supported blockchains](/reference/staking-overview). This transaction is automatically created when performing staking operations.  `UNSTAKE` - Remove assets from a staking pool managed by a staking validator. [Learn more about staking transactions and supported blockchains](/reference/staking-overview).This transaction is automatically created when performing staking operations.  `WITHDRAW` - Transfer assets from a dedicated staking vault account to another address. [Learn more about staking transactions and supported blockchains](/reference/staking-overview).This transaction is automatically created when performing staking operations.   - *Note:*\* Fireblocks may rename this type from WITHDRAW to a different name soon. There will be at minimum a 7-day notice regarding the new type name. |

***

### AmountInfo

| Parameter       | Type   | Description                                                                                                                                                                                                                                                                             |
| --------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| amount          | string | If the transfer is a withdrawal from an exchange, the actual amount that was requested to be transferred. Otherwise, it is the requested amount. This value will always be equal to the amount (number) parameter of [TransactionDetails](/reference/event-objects#transactiondetails). |
| requestedAmount | string | The amount requested by the user                                                                                                                                                                                                                                                        |
| netAmount       | string | The net amount of the transaction, after fee deduction                                                                                                                                                                                                                                  |
| amountUSD       | string | The USD value of the requested amount                                                                                                                                                                                                                                                   |

> **Note**
>
> `transaction_status_updated` webhooks contain only up to 17 digits past the decimal place when reporting balances.

***

### FeeInfo

| Parameter    | Type    | Description                                                                                               |
| ------------ | ------- | --------------------------------------------------------------------------------------------------------- |
| networkFee   | string  | The fee paid to the network                                                                               |
| serviceFee   | string  | The total fee deducted by the exchange from the actual requested amount (serviceFee = amount - netAmount) |
| gasPrice     | string  | The amount of gas required by/paid to the network to process the transaction.                             |
| L1networkFee | string  | Layer 1 network fee for Layer 2 blockchain transactions.                                                  |
| L2networkFee | string  | Layer 2 network fee (gas price component for Layer 2 transactions).                                       |
| paidByRelay  | boolean | Indicates whether the relay paid the fee.                                                                 |
| relayType    | string  | Indicates whether the relay is the same tenant (`LOCAL`) or another tenant (`THIRD_PARTY`).               |
| relayId      | string  | The Vault account ID of the relay.                                                                        |
| relayName    | string  | The name of the tenant hosting the third-party relay.                                                     |
| feeUSD       | string  | The USD equivalent value of the fee.                                                                      |

***

### TransferPeerPathResponse

| Parameter | Type   | Optional | Description                                                                                                                                                                                                      |   |   |
| --------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | - |
| type      | string | No       | AULT\_ACCOUNT`,` EXCHANGE\_ACCOUNT`,` INTERNAL\_WALLET`,` EXTERNAL\_WALLET`,` UNMANAGED\_WALLET`,` ONE\_TIME\_ADDRESS`,` NETWORK\_CONNECTION`,` FIAT\_ACCOUNT`,` GAS\_STATION`,` UNKNOWN`,`MULTI\_DESTINATION\`] |   |   |
| id        | string | Yes      | The ID of the account to return. Can return as  `null`  if the related transaction fails due to a connectivity error.                                                                                            |   |   |
| name      | string | Yes      | The name of the account.                                                                                                                                                                                         |   |   |
| address   | string | Yes      | The address where the asset was transferred                                                                                                                                                                      |   |   |
| subType   | string | Yes      | The specific account or wallet.                                                                                                                                                                                  |   |   |

> **Sources and destinations**
>
> Learn more about [transaction sources and destinations](/reference/transaction-sources-destinations).

***

### DestinationsResponse

| Parameter                     | Type                                                                              | Optional | Description                                                                |
| ----------------------------- | --------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------- |
| amount                        | string                                                                            | No       | The amount to be sent to this destination                                  |
| destination                   | [TransferPeerPathResponse](#transferpeerpathresponse)                             | No       | Destination of the transaction                                             |
| amountUSD                     | number                                                                            | Yes      | The USD value of the requested amount                                      |
| destinationAddressDescription | string                                                                            | Yes      | Description of the address                                                 |
| amlScreeningResult            | [AmlScreeningResult](/reference/transaction-screening-objects#amlscreeningresult) | Yes      | The result of the AML screening                                            |
| customerRefId                 | string                                                                            | Yes      | The ID for AML providers to associate the owner of funds with transactions |

***

### TransactionExtraParameters

| Parameter        | Type                                                                     | Description                                                                                                                                                                                                                                                                                                                                    |
| ---------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| inputsSelection  | [InputsSelection object](/reference/transaction-objects#inputsselection) | For UTXO-based blockchain multi-input selection, use the `inputsSelection` field with values set to the input selection structure. The inputs can be retrieved using the Retrieve Unspent Inputs endpoint.                                                                                                                                     |
| rawMessageData   | [RawMessageData object](/reference/raw-signing-objects#rawmessagedata)   | For `RAW` operations, use the rawMessageData field with the values set to the raw message data structure. Only included with raw signing transactions on Bitcoin and Ethereum.  This is an opt-in feature. Please contact [Fireblocks Support](https://support.fireblocks.io/hc/en-us/requests/new) to include this feature in your workspace. |
| contractCallData | string                                                                   | For `CONTRACT_CALL` operations, use the contractCallData field with the value set to the Ethereum smart contract Application Binary Interface (ABI) payload. The [Fireblocks development libraries](/reference/evm-web3-provider#convenience-libraries) are recommended for building contract call transactions                                |

***

### SystemMessageInfo

| Parameter | Type   | Description                                                                                                                                                                                                          |
| --------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type      | string | (`WARN`, `BLOCK`)                                                                                                                                                                                                    |
| message   | string | A response from Fireblocks that communicates a message about the health of the process being performed. If this object is returned with data, you should expect potential delays or incomplete transaction statuses. |


# Transfer NFTs
Source: https://developers.fireblocks.com/reference/transfer-nfts



Fireblocks enables you to transfer your NFTs using both the API and the Console. To transfer tokens through the Console, simply click the "Withdraw" button in the NFT view.

For clients wishing to use the API to move their NFTs out of their Fireblocks vault accounts or between their vault accounts, they can do so by calling the Fireblocks Create Transaction API - [POST /v1/transactions](/api-reference/transactions/create-a-new-transaction)

# Using the API

Here is a code example for transferring your NFTs from your Fireblocks Vault using the Fireblocks TS SDK:

> **Constant Parameters:**
>
> Please note that the `amount` value for any NFT transfer is always '1'

```javascript theme={"system"}
import { TransferPeerPathType } from "@fireblocks/ts-sdk";

const transferNFT = async (
  sourceId: string,
  destType: TransferPeerPathType,
  destId: string,
  assetId: string
) => {
  try {
    const txId = await fireblocks.transactions.createTransaction({
      transactionRequest: {
        assetId,
        source: {
          type: TransferPeerPathType.VaultAccount,
          id: sourceId,
        },
        destination: {
          type: destType,
          id: destId,
        },
        amount: "1",
      },
    });

    console.log(txId.data);
  } catch (e) {
    console.error(e);
  }
};

transferNFT("0", TransferPeerPathType.VaultAccount, "1", "NFT-6a94587325e091b15f4a52159a51d4476b5bdc7b");
```


# Travel Rule Support Integration Guide
Source: https://developers.fireblocks.com/reference/travel-rule-link-integration



## Overview

Travel Rule Support (TRSupport) is Fireblocks' comprehensive compliance solution for meeting cryptocurrency travel rule regulations across global jurisdictions. TRSupport automates the collection, encryption, and exchange of counterparty information required by regulatory frameworks like the Financial Action Task Force Travel Rule, ensuring your organization remains compliant while maintaining transaction speed and security.

## Prerequisites

Before integrating TRSupport:

* **Enable TRSupport Feature**: Contact your [Customer Success Manager](https://support.fireblocks.io/hc/en-us/requests/new?ticket_form_id=6947882197532) to enable TRSupport for your Fireblocks workspace
* **API Access**: Ensure you have valid API credentials for your Fireblocks workspace
* **Policy Planning**: Design your three-stage policy configuration strategy
* **Development Environment**: Set up test environments for integration testing

## Core Concepts

### Three-Stage Policy Framework

TRSupport processes transactions through three configurable policy stages:

1. **Screening Policy**: Determines whether to contact Travel Rule providers (TRP)
2. **Missing Travel Rule Message (TRM) Policy**: Handles scenarios when TRMs are unavailable
3. **Post-screening Policy**: Determines final actions based on screening results

### Multi-Destination Support

TRSupport intelligently handles transactions with multiple destinations:

* Each destination is evaluated independently
* Results combine using "worst result wins" logic
* Single transaction verdict with per-destination visibility

### Providers

TRSupport integrates with TRP networks to facilitate compliant information exchange between Virtual Asset Service Providers (VASPs).

#### Sumsub

Learn more about the integration flow in the [Fireblocks integration article](https://docs.sumsub.com/docs/fireblocks-integration) on Sumsub's documentation site.

#### Global Travel Rule (GTR)

Learn more about the integration flow in the [Fireblocks integration article](https://www.globaltravelrule.com/documentation/connect-fireblocks-with-gtr) on GTR's documentation site.

## Common Patterns and Best Practices

### Setup Flow

The initial setup process is typically performed once during onboarding and consists of two main stages: configuring legal entities and establishing TRP integrations.

### Legal Entities

TRSupport requires at least one legal entity to be configured. A legal entity represents a distinct business entity within your organization, subject to travel rule compliance. Most customers should use a single legal entity for their entire operation. However, if you operate as a large holding company across multiple jurisdictions with different compliance requirements, you can configure multiple legal entities and assign specific vault accounts to each jurisdiction.

When configuring legal entities, be aware that only one entity should be configured without vault restrictions. This entity will serve as the default for all vaults not explicitly assigned to other entities. Each legal entity can have multiple TRSupport integrations with different TRPs.

For example, a multi-jurisdictional organization might configure:

* **Legal Entity 1**: EU compliance rules (vaults 0-5)
* **Legal Entity 2**: US compliance rules (vaults 6-10)
* **Legal Entity 3**: APAC compliance rules (vaults 11-15)

Alternatively, you can designate one entity (e.g., US) as the "global" default, which will apply to all unassigned vaults.

Use the following endpoints to manage legal entities:

* `getLegalEntities` - Retrieves all configured legal entities
* `getTRLinkCustomerById` - Retrieves a specific legal entity
* `createTRLinkCustomer` - Creates a new legal entity
* `updateTRLinkCustomer` - Modifies an existing legal entity
* `deleteTRLinkCustomer` - Removes a legal entity

Below is an example of a legal entity creation:

```typescript theme={"system"}
const acmeLegalEntity = await fireblocks.trLink.createTRLinkCustomer({
  shortName: "ACME Corp",
  fullLegalName: "ACME Corporation Ltd",
  countryOfRegistration: "US",
  vaults: [0, 1]
});
```

### TRSupport Integrations

After configuring your legal entities, you must establish integrations for each legal entity with your chosen TRP(s).

First, initiate the integration by creating a customer integration record. This action generates a unique Customer Integration ID that identifies the connection between your legal entity and the TRP. You can share this Customer Integration ID with your TRP to initiate an "auto-connect" procedure (Sumsub only supports this method), where the TRP automatically provides your API credentials to Fireblocks. Alternatively, you can manually configure the API key and secret using the `connectLegalEntityIntegration` endpoint.

Once credentials are configured, use the `testTRLinkIntegrationConnection` endpoint to verify that the integration is functioning correctly before proceeding with travel rule operations.

```typescript theme={"system"}
// 1. Get available partners
const partners = await fireblocks.trLink.getTRLinkPartners();
const partnerX = partners.find(p => p.ident === "partnerX");

// 2. Create integration
const integration = await fireblocks.trLink.createTRLinkIntegration({
  customerId: acmeLegalEntity.id,
  partnerIdent: partnerX.ident
});

// 3. Connect with credentials
const connected = await fireblocks.trLink.connectTRLinkIntegration(
  integration.customerIntegrationId,
  {
    apiKey: "your-trp-api-key",
    secret: "your-trp-secret"
  }
);

// 4. Test connection
const testResult = await fireblocks.trLink.testTRLinkIntegrationConnection(
  integration.customerIntegrationId
);

if (testResult.success) {
  console.log("Setup complete and connection verified!");
} else {
  console.error("Connection test failed:", testResult.message);
}
```

### Inbound and Outbound Transaction Flows

Always use the `assessTravelRuleRequirement` endpoint before creating a TRM. This endpoint is the single source of truth for determining if a TRM is needed and what data it must contain.

The endpoint evaluates the transaction against compliance rules and will tell you if the status is `REQUIRED`, `NOT_REQUIRED`, or if you `NEED_MORE_INFO`. When required, it provides a precise list of mandatory IVMS101 fields to guide your data collection process.

#### Inbound Transaction Flow

For inbound transactions, use the existing Fireblocks transaction ID:

```typescript theme={"system"}
const txId = "12345678-1234-1234-1234-123456789abc";

// 1. Assess travel rule requirement using txId
const assessment = await fireblocks.trLink.assessTRLinkTravelRuleRequirement(
  customerIntegrationId,
  {
    txId: txId,
    originatorVaspId: "originator-vasp-123"
  }
);

if (assessment.decision === "REQUIRED") {
  // 2. Get public key for encryption and save to temp file
  const publicKey = await fireblocks.trLink.getTRLinkIntegrationPublicKey(customerIntegrationId);

 await fs.writeFile(path.join(__dirname, 'public-key.json'), JSON.stringify(publicKey, null, 2), 'utf8');

  // 3. Encrypt IVMS data (encrypt data + IVMS specification)

  // WARNING: This is not production-ready code. 
  // Due to the use of fixed file paths (like 'ivms.json'), 
  // race conditions can occur during parallel execution. 
  // It is recommended to use a solution for generating unique temporary 
  // filenames (e.g., using the 'tmp' npm package, or relying on 
  // system-level functions like the Linux tempnam()).
  const publicKeyPath = path.join(__dirname, 'public-key.json');
  const privateKeyPath = path.join(__dirname, 'private-key.json');
  const ivmsDataPath = path.join(__dirname, 'ivms.json');
  const scriptPath = path.join(__dirname, 'encrypt.js');

  const ivmsOutput = execSync(`node "${scriptPath}" "${publicKeyPath}" "${privateKeyPath}" "${ivmsDataPath}"`, {
    encoding: 'utf-8',
    stdio: ['pipe', 'pipe', 'pipe']
  });

  const ivms = JSON.parse(ivmsOutput.trim());


  // 4. Create TRM with txId
  const trm = await fireblocks.trLink.createTRLinkTrm(
    customerIntegrationId,
    {
      txId: txId,
      originatorVaspId: "originator-vasp-123",
      ivms,
    }
  );

  // 5. Link TRM to transaction.  Recommendation - use the <partnerIdent>:<trmId> format, indicating not only trmId, but also a partner where trm is registered

  await fireblocks.trLink.setTRLinkTransactionTravelRuleMessageId(txId, {
    travelRuleMessageId: trm.id
  });
}

```

#### Outbound Transaction Flow

For outbound transactions, create the TRM before creating the Fireblocks transaction:

```typescript theme={"system"}
// 1. Assess travel rule requirement
const assessment = await fireblocks.trLink.assessTRLinkTravelRuleRequirement(
  customerIntegrationId,
  {
    amount: "1500",
    assetId: "ETH",
    direction: "outbound",
    source: { type: "VAULT_ACCOUNT", id: "0" },
    destination: {
      type: "ONE_TIME_ADDRESS",
      oneTimeAddress: { address: "0xabcd..." }
    },
    beneficiaryVaspId: "vasp-456"
  }
);

if (assessment.decision === "REQUIRED") {
  // 2. Get public key for encryption and save to temp file
  const publicKey = await fireblocks.trLink.getTRLinkIntegrationPublicKey(customerIntegrationId);

  await fs.writeFile(path.join(__dirname, 'public-key.json'), JSON.stringify(publicKey, null, 2), 'utf8');

  // 3. Encrypt IVMS data (encrypt data + IVMS specification)
  
  // WARNING: This is not production-ready code. 
  // Due to the use of fixed file paths (like 'ivms.json'), 
  // race conditions can occur during parallel execution. 
  // It is recommended to use a solution for generating unique temporary 
  // filenames (e.g., using the 'tmp' npm package, or relying on 
  // system-level functions like the Linux tempnam()).
  
  const publicKeyPath = path.join(__dirname, 'public-key.json');
  const privateKeyPath = path.join(__dirname, 'private-key.json');
  const ivmsDataPath = path.join(__dirname, 'ivms.json');
  const scriptPath = path.join(__dirname, 'encrypt.js');

  const ivmsOutput = execSync(`node "${scriptPath}" "${publicKeyPath}" "${privateKeyPath}" "${ivmsDataPath}"`, {
    encoding: 'utf-8',
    stdio: ['pipe', 'pipe', 'pipe']
  });

  const ivms = JSON.parse(ivmsOutput.trim());

  // 4. Create TRM
  const trm = await fireblocks.trLink.createTRLinkTrm(
    customerIntegrationId,
    {
      amount: "1500",
      assetId: "ETH",
      direction: "outbound",
      source: { type: "VAULT_ACCOUNT", id: "0" },
      destination: {
        type: "ONE_TIME_ADDRESS",
        oneTimeAddress: { address: "0xabcd..." }
      },
      beneficiaryVaspId: "vasp-456",
      ivms,
    }
  );

  // 5a. Create Fireblocks transaction - use travelRuleMessageId field to set TRM id
  // recommendation - use the <partnerIdent>:<trmId> format, indicating not only trmId, but also a partner where trm is registered
  const txId = await createFireblocksTransaction({ 
/* ... */ 
travelRuleMessageId: `${partnerIdent}:${trm.id}`
});

  // Or, 5b. Link TRM to transaction later if not set during tx creation
  await fireblocks.trLink.setTRLinkTransactionTravelRuleMessageId(txId, {
    travelRuleMessageId: `${partnerIdent}:${trm.id}`
  });
}

```

### Encryption and Decryption (Partner: Sumsub using JWT encryption)

Below is an example of how to encrypt and decrypt IVMS data retrieved from Sumsub. To do this, we must use our private key to sign IVMS data and the partner's public key (as described in the [API Integration](#api-integration) section) to encrypt data. For decrypting, we need our own private key to decrypt the IVMS data and a partner's public key to verify the signature. At the moment, our public/private key pair is generated by a partner on their marketplace and available to download.

<Note>
  **Note:**

  Custom key pair upload is under consideration for future releases.
</Note>

#### Encryption Example

The following illustrates a partner's public key response:

```json theme={"system"}
{
  "issuer": "sumsub.com",
  "publicKey": {
    "kty": "RSA",
    "kid": "test-sender-2025",
    "e": "AQAB",
    "n": "q6fmy_rjX2xizMiXoWKRVZSrDXXYLnMk6J_q-5FAD5q7CdqK10XmQZrlzItLpj9qxl0LfcZhZ93PL55abei1F4u6Jdzh9LrfUF5WZ7Cvi25n6aeJoOd7JIERY0hP8s-xdiDrr5fRqdseHymENhvwK5J8_adEOcWHR_7ymb17c3ivFQmprytkJD6BfXaF7qGeE6cx0UiDlD1sHCGcd26I1JNjYQZJie0qlPT8x7jILNA7sW1_Nk8wx9jRDtUv6-K2qnz4MvFe1D6rddcnCsiX7MRPWKm10hy41MTJkQcWUYgtDqfdOXNo8D8BnaVuaLEsByNxMQiL8ePXZpBro0nrnw"
  }
}
```

Here is an example of a private key:

```json theme={"system"}
{
  "kty": "RSA",
  "kid": "test-recipient-2025",
  "e": "AQAB",
  "n": "m58UpcvahBK3-Uma_S4HTGwijmASh_3ATDwkjIb1svp2jnrv6lhjE2Yz28b0oUsEa7Wau6x0NPbaUCrQjjN5iUoumn4Jwq6jKttXFtd4v3583co4sBjGoPqk7GbkeYKzEOs2wmKgKbQjjk1BaHFpTPlAmS2JbNy6VmHNj-62BK1vIeegXheqxkr-b-MvESmL746juz_LlTMPmJqbaNuMeQMktT9lBLPfZermLfUuC7myuQhrsD8zJaNiNDWJQ6dzNi-Cy0uGlDcy9xtSQMW1Tv3Fc7hO_bRD1NI-sJp7nVi6hdc-QMOyrv8tzlhTV7gh3Wnn2kIFFkWy86gYYHw79Q",
  "d": "HJYLvmrkYGdp2QZ-zGwUliK09E9MiCOCG97eXdv6rR5aAdEuWe9Tf8BB3Wi-DhTQIpLw8fF7RTFlJ929gqmM9T2lsuZdF6Bpw5kX9c-t1AtBl6IqaJqcffycp_o8lN9_0idK30krn42CDIU_cxaGH8gXaCvXtyISroR3tK1GTTRfLSqcAQ3wI5Kj7IRf_oCyU6zZ9Vo30X1Tus-yE9Gv0D5wDOybfRljQJ7D7lA-thXzVeO8YwvoIp_K7aA5BaJjMg2TaYdPskCV4Wbu3O0ezHw2GCbkgusIG_ZEtcCFbldR45Vwtpp6Hm82g2lqDynNyRrTqeCoigkIqLwW8vir3w",
  "p": "0huuQD7Cv4R6pgucabPQt7I-1BSG5Ao32ZzTQzqB6H5zeyF76G82TRuSu3Ky4WBCJiFr1czHlA5RlpllU6lEivoOaslc4NtgABLyfTE3EPhP45xBhfOh1FmtMkZdJFXGwpIGOlPByc2nQC3mO9I8wRltvDAB0hds4vsEdQPPpNs",
  "q": "vZy-PHqEib7mYEGmhwoJcHzTrFjK5CAcQ0gqH41ALvKdArk1RzGJWEduQqG8s2_g84z3iobnlslSFM_FVvtQjGGqw8ul9VvHTOCiKlOCnJtCTOHqhGZMQTVSxoQito-RidKNA4rHpjHbU5Gq_3gLmVqdMeQw_Fx_NS1D2y5-k28",
  "dp": "YZA4-dwq0oPR8Ai0OOEmqiY6xoBBouKbzJDmCPHCIROWzDZgMy5xKJ0FJcW9CqqIDOy4Bi9w_W8os6XHR3HyQhabWzrlxgQYL_CcaUXRLDAh6K9GPc1D-DcsFYxW8-hgwzjLa4o5ElxMraCiqGSXkZMdQaWJMuVtyniFOVDrusE",
  "dq": "s3uvx-fhldISmIMMcz9Y-BXw-G-EfrS2jCm_VeaLHuWhInbWq_GEJQBYqtIWoXQB6AlEOOjCR8WB4Rlbn558_KVm07ft_HdIDMmGN7KdLEj7VXN0XqfG_uLO3AMwKMd16JRZz0SLABKpnk2BJBoqQJu5uQRcKkYUU-3pEYzNXBk",
  "qi": "k1qx6Qd4FpHw1185FZiRm4wGv6wzqSIm1LC0KS29CsGl4D6CVqVVaBwoW0Olw3jkrQe7znSuezC1_lZOGmjB2h3I5bKPlAUVKVqdfk4mwlh7Dfgs6AFcqUj5mpSx1a2L0SHQeZXsprA_EtXs0L37iLCEsoOre9qYRivZBqiTdJk"
}
```

Here is an example of source IVMS data:

```json theme={"system"}
{
  "Originator": {
    "originatorPersons": [
      {
        "naturalPerson": {
          "name": {
            "nameIdentifier": [
              {
                "primaryIdentifier": "John",
                "secondaryIdentifier": "Doe",
                "nameIdentifierType": "BIRT"
              }
            ],
            "localNameIdentifier": [],
            "phoneticNameIdentifier": []
          },
          "customerIdentification": "e8nvdf2vwa5036ix",
          "dateAndPlaceOfBirth": {
            "dateOfBirth": "1992-05-08"
          }
        }
      }
    ],
    "accountNumber": []
  },
  "Beneficiary": {
    "beneficiaryPersons": [
      {
        "naturalPerson": {
          "name": {
            "nameIdentifier": [
              {
                "primaryIdentifier": "Jack",
                "secondaryIdentifier": "Doe",
                "nameIdentifierType": "BIRT"
              }
            ],
            "localNameIdentifier": [],
            "phoneticNameIdentifier": []
          },
          "customerIdentification": "67b4defbfa5d2e41d8177ab3",
          "dateAndPlaceOfBirth": {
            "dateOfBirth": "1991-04-07"
          }
        }
      }
    ],
    "accountNumber": []
  }
}
```

This utility processes the paths to a partner's public key, our private key, and IVMS data, which are provided as arguments. It then generates an IVMS block containing encrypted data, along with all accompanying filled fields.

```javascript theme={"system"}
const jose = require('node-jose');
const crypto = require('crypto');
const path = require('path');
const fs = require('fs/promises');

const SIGNATURE_ALGORITHM = 'RS256';
const ENCRYPTION_ALGORITHM = 'RSA-OAEP-256';
const ENCRYPTION_METHOD = 'A256GCM';
const DEFAULT_EXPIRY_MS = 300000; // 5 minutes
const CLOCK_SKEW_SEC = 60; // ±60s skew
const CLAIM_DATA = 'data'; // The JWT claim holding the payload

/**
 * Travel Rule JWT Codec for PII Data Encryption
 *
 * Implements a nested JWT (JWS signed token encrypted inside a JWE)
 * for secure PII exchange, compatible with the Java TRJWTCodec implementation.
 *
 * Features:
 * - Object signing and encryption: `prepareIvmsData` / `decryptAndDecode`
 * - JTI (JWT ID) claim for replay attack protection
 * - Standard claims validation (iss, iat, exp)
 */
class TRJWTCodec {
  constructor() {
    this.keyStore = jose.JWK.createKeyStore();
    this.publicKey = null; // Partner's public key (for encryption)
    this.privateKey = null; // Our private key (for signing)
    this.initialized = false;
  }

  /**
   * Initialize the codec with RSA key pairs.
   *
   * @param {Object} config - Configuration object
   * @param {string} config.publicKey - PEM-encoded RSA public key (partner's key for encryption)
   * @param {string} config.privateKey - PEM-encoded RSA private key (our key for signing)
   */
  async initialize(config) {
    this._assert(config.publicKey, 'Public key is required');
    this._assert(config.privateKey, 'Private key is required');

    try {
      this.publicKey = await this.keyStore.add(config.publicKey);
      this.privateKey = await this.keyStore.add(config.privateKey);
      this.initialized = true;
    } catch (error) {
      throw new Error(`Failed to initialize TRJWTCodec with provided keys: ${error.message}`);
    }
  }

  /**
   * Encrypt and sign an object as a nested JWT (JWS inside JWE).
   * This is the lower-level function that returns only the JWE string.
   *
   * @param {Object} data - The JSON-serializable object to encrypt.
   * @param {string} issuer - The 'iss' claim (our identifier).
   * @param {number} [expiryMs=DEFAULT_EXPIRY_MS] - Expiry time in milliseconds.
   * @returns {Promise<string>} - The compact-serialized JWE token string.
   */
  async encodeAndEncrypt(data, issuer, expiryMs = DEFAULT_EXPIRY_MS) {
    this._assertInitialized();
    this._assert(data, 'Data cannot be null or undefined');
    this._assert(issuer && typeof issuer === 'string' && issuer.trim(), 'Issuer must be a non-empty string');

    // 1. Serialize the object to a JSON string
    const dataJson = JSON.stringify(data);
    // 2. Encode the JSON string as base64url
    const dataB64Url = Buffer.from(dataJson, 'utf8').toString('base64url');
    // 3. Pass the base64url string to the byte-level encryption method
    return this.encryptBytes(dataB64Url, issuer, expiryMs);
  }

  /**
   * Prepares the full IVMS data object, including the encrypted JWE
   * and the list of filled fields.
   *
   * @param {Object} data - The IVMS data object to encrypt.
   * @param {string} issuer - The 'iss' claim (our identifier).
   * @param {number} [expiryMs=DEFAULT_EXPIRY_MS] - Expiry time in milliseconds.
   * @returns {Promise<{version: string, data: string, filledFields: string[]}>}
   * An object containing the API version, the encrypted JWE string,
   * and the dot-notation paths of all non-null fields.
   */
  async prepareIvmsData(data, issuer, expiryMs = DEFAULT_EXPIRY_MS) {
    // 1. Create the encrypted JWE string from the data object.
    // This handles signing with our private key and encrypting with the partner's public key.
    const encryptedData = await this.encodeAndEncrypt(data, issuer, expiryMs);
    // 2. Extract all filled field paths from the original data object.
    const filledFields = this._extractFilledFields(data);

    return {
      version: 'IVMS101.2023', // API version
      data: encryptedData,
      filledFields: filledFields
    };
  }

  /**
   * Decrypt and decode data from an encrypted JWE token.
   *
   * @param {string} encryptedJWT - The compact-serialized JWE token.
   * @param {string} [expectedIssuer] - (Optional) The expected 'iss' claim for validation.
   * @returns {Promise<Object>} - The original decrypted and parsed JSON object.
   */
  async decryptAndDecode(encryptedJWT, expectedIssuer = null) {
    this._assertInitialized();
    this._assert(encryptedJWT, 'Encrypted JWT cannot be null or empty');

    // --- JWE Decryption ---
    // 1. Decrypt the outer JWE layer using our private key.
    const jweResult = await jose.JWE.createDecrypt(this.privateKey)
      .decrypt(encryptedJWT);

    // The payload of the JWE is the inner JWS.
    const signedJWT = jweResult.payload.toString('utf8');

    // --- JWS Verification ---
    // 2. Verify the signature of the inner JWS using the partner's public key.
    const jwsResult = await jose.JWS.createVerify(this.publicKey)
      .verify(signedJWT);

    // The payload of the JWS is the claims object.
    const claimsJson = jwsResult.payload.toString('utf8');
    const claims = JSON.parse(claimsJson);

    // --- Claims Validation ---
    // 3. Validate standard JWT claims (iat, exp, iss, jti).
    if (expectedIssuer && claims.iss !== expectedIssuer) {
      throw new Error(`Invalid issuer: expected ${expectedIssuer}, got ${claims.iss}`);
    }

    const nowSec = Math.floor(Date.now() / 1000);
    if (claims.iat && claims.iat > nowSec + CLOCK_SKEW_SEC) {
      throw new Error('Token "iat" (issued at) is in the future');
    }
    if (claims.exp && nowSec - CLOCK_SKEW_SEC > claims.exp) {
      throw new Error('Token has expired');
    }
    if (!claims.jti) {
      throw new Error('Missing "jti" (JWT ID) claim');
    }

    // --- Payload Extraction ---
    // 4. Extract, decode, and parse the custom 'data' claim.
    const dataB64Url = claims[CLAIM_DATA];
    if (!dataB64Url) {
      throw new Error(`Missing required "${CLAIM_DATA}" claim`);
    }

    const dataBuffer = Buffer.from(dataB64Url, 'base64url');
    const dataJson = dataBuffer.toString('utf8');

    return JSON.parse(dataJson);
  }

  /**
   * Encrypts a base64url-encoded string payload into a nested JWS-in-JWE token.
   *
   * @param {string} dataB64Url - The base64url-encoded data string.
   * @param {string} issuer - The 'iss' claim.
   * @param {number} expiryMs - Expiry time in milliseconds.
   * @returns {Promise<string>} - The compact-serialized JWE token string.
   * @private
   */
  async encryptBytes(dataB64Url, issuer, expiryMs) {
    this._assertInitialized();

    try {
      // --- JWS Claims Setup ---
      // 1. Create the claims for the inner JWS token.
      const nowMs = Date.now();
      const iat = Math.floor(nowMs / 1000); // Issued at
      const exp = Math.floor((nowMs + expiryMs) / 1000); // Expiration
      const jti = crypto.randomUUID(); // Unique token ID

      const claims = {
        iss: issuer,
        iat: iat,
        exp: exp,
        jti: jti,
        [CLAIM_DATA]: dataB64Url,
      };
      const claimsJson = JSON.stringify(claims);

      // --- JWS Creation (Signing) ---
      // 2. Sign the claims with our private key.
      const jwsOptions = {
        format: 'compact',
        fields: {
          alg: SIGNATURE_ALGORITHM,
          typ: 'JWT',
          kid: this.privateKey.kid
        }
      };

      const signedJWT = await jose.JWS.createSign(jwsOptions, this.privateKey)
        .update(claimsJson)
        .final();

      // --- JWE Creation (Encryption) ---
      // 3. Encrypt the signed JWS with the partner's public key.
      const jweOptions = {
        format: 'compact',
        contentAlg: ENCRYPTION_METHOD,
        fields: {
          alg: ENCRYPTION_ALGORITHM,
          enc: ENCRYPTION_METHOD,
          kid: this.publicKey.kid,
          cty: 'JWT' // Content Type: Indicates payload is a JWT
        }
      };

      const encryptedJWT = await jose.JWE.createEncrypt(jweOptions, this.publicKey)
        .update(signedJWT)
        .final();

      return encryptedJWT;

    } catch (error) {
      throw new Error(`Nested JWT encryption failed: ${error.message}`);
    }
  }

  /**
   * Recursively extracts all filled (non-null, non-undefined)
   * leaf node paths from an object in dot-notation.
   *
   * @param {Object} obj - The object to traverse.
   * @returns {string[]} - An array of dot-notation field paths.
   * @private
   */
  _extractFilledFields(obj) {
    // Start the recursion with the root object and no path prefix
    return this._recursiveExtract(obj, '');
  }

  /**
   * Helper function for _extractFilledFields.
   * @param {*} current - The current value being inspected.
   * @param {string} path - The dot-notation path to this value.
   * @returns {string[]} - A flat array of leaf paths found from this node.
   * @private
   */
  _recursiveExtract(current, path) {
    // 1. Base Case: Null/Undefined values are "empty" and ignored.
    if (current === null || current === undefined) {
      return [];
    }

    // 2. Array Case: Recurse on each item, but keep the *same* path.
    // This "flattens" the array, so 'person.addresses[0].city' and
    // 'person.addresses[1].city' both map to 'person.addresses.city'.
    if (Array.isArray(current)) {
      // Use flatMap to collect and flatten results from all items.
      return current.flatMap(item => this._recursiveExtract(item, path));
    }

    // 3. Object Case: Recurse on each key/value pair, *extending* the path.
    if (typeof current === 'object') {
      return Object.entries(current).flatMap(([key, value]) => {
        const newPath = path ? `${path}.${key}` : key;
        return this._recursiveExtract(value, newPath);
      });
    }

    // 4. Primitive Case: This is a leaf node (string, number, boolean).
    // Return its path, as long as it's not an empty path (i.e., a root primitive).
    return path ? [path] : [];
  }

  /**
   * Throws an error if the codec is not initialized.
   * @private
   */
  _assertInitialized() {
    if (!this.initialized || !this.privateKey || !this.publicKey) {
      throw new Error('TRJWTCodec is not initialized. Call initialize() with keys first.');
    }
  }

  /**
   * Simple assertion helper.
   * @private
   */
  _assert(condition, message) {
    if (!condition) {
      throw new Error(message);
    }
  }
}


// --- Command-Line Execution ---

/**
 * Helper to read and parse a JSON file from a given path.
 * @param {string} filePath - Path to the JSON file.
 * @returns {Promise<Object>} - The parsed JSON object.
 */
async function readJsonFile(filePath) {
  const absolutePath = path.resolve(filePath);
  try {
    const content = await fs.readFile(absolutePath, 'utf8');
    return JSON.parse(content);
  } catch (error) {
    throw new Error(`Failed to read or parse file ${absolutePath}: ${error.message}`);
  }
}

/**
 * Main execution function for the command-line demo.
 */
async function main() {
  const args = process.argv;
  // Basic argument check
  if (args.length < 5) {
    console.error('Usage: node your-script-name.js <partnerPublicKeyFile> <ourPrivateKeyFile> <ivmsDataFile>');
    console.error('Example: node encrypt.js partner-public.json my-private.json data.json');
    process.exit(1);
  }

  const [,, publicKeyFile, privateKeyFile, ivmsDataFile] = args;

  try {
    // 1. Load keys and data from files
    const publicKeyData = await readJsonFile(publicKeyFile);
    const privateKey = await readJsonFile(privateKeyFile);
    const ivmsData = await readJsonFile(ivmsDataFile);

    const { issuer, publicKey } = publicKeyData;
    if (!issuer || !publicKey) {
      throw new Error('Public key JSON file must contain "issuer" and "publicKey" fields.');
    }

    // 2. Initialize the Codec
    const codec = new TRJWTCodec();
    await codec.initialize({
      publicKey,  // Partner's public key (for encryption)
      privateKey, // Our private key (for signing)
    });

    // 3. Prepare the IVMS Data
    // This signs with our private key and encrypts with the partner's public key.
    const ivmsRequest = await codec.prepareIvmsData(ivmsData, issuer);

    console.log(JSON.stringify(ivmsRequest, null, 2)); // Pretty-print the result
  } catch (error) {
    console.error(`\n❌ An error occurred: ${error.message}`);
    // console.error(error.stack); // Uncomment for full stack trace
    process.exit(1);
  }
}

// Run the main function
main();

```

Executing the previous utility with proper arguments produces the following output:

```shell theme={"system"}
node dec-encrypt.ts public-key.json private-key.json ivms.json
Reading JSON from: public-key.json
Reading JSON from: private-key.json
Reading JSON from: ivms.json
✅ Codec initialized successfully.

Encrypting IVMS data for issuer: sumsub.com...

--- ✅ Prepared IVMS Request ---
{
  "version": "IVMS101.2023",
  "data": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoidGVzdC1zZW5kZXItMjAyNSIsImN0eSI6IkpXVCJ9.KNNX0QweA41Dhif_tLS26OFM3TIz7V8SuOnbGjVBJ1erB9GkhSGy3Q638ArSabSN0UoQKObd11UpDkw-ZiwWiGZ_OG1LsTKkfEWBtAQ5YSsNeJNMoQh3voIFHuLRm_RC2f0gj_v4q4iGpkyRqB6YN-kAFYQhWm_RuMuHSbatpBCzFT9XYybvRHe-oQ33WhIPFumiByq2FMzK94JNjwfILeqBtCiL9uWZSQtAPiOTQa88TMilZdeqOWmtg0_j7pYq8fl6x8tp3cyMfYKzpRaTZ8y8VDqt67BTehC0fOrn_Wh8TeuyYFKdiR3ROjIFBWnYEKimSgUeXMMynGMLnLq5Lg.bLixunwV8XdEi-TF.Mu8tSaJH_9fuZ7Sqk6gaR9m1hFJHU8mrPxHlT-jHp0x-3FBfPAxZM1N1vApS_foFIUgbbQA65FlG6kihGvvUBwpOlkQ9TjCaraaFyI3YSacJfBzDLQcL8NsBuaIqTanRcHlu77ph9A2Q0Rsqod_wwkMThAhb47vrq240fNKwwvKw5USeEUISVVc684CsLxxTC9n6PyfTCgUlWWdILxZ5Nv1LKtbHd_6IfNkBwi-ChKVz4E_N9B_KsJSRTquAlQMSLSHopOi50p5mq3LJCy97ZGc5ZKdAuoUV3lkYC7mQlY_T8A4o84pp-9uLI1pHTfyxCy0PUhIXb515jFRt5dFXt9fOWHOqMhCzBdHc_rfkaENw8zJSi3D3bqj8_dAQtw7xzCm0-bDmkj7Zb4-O_XBtehxFxQcQAWAoWdWBpRLw1XeMLgQSvGSGYkgDYJOxYzjTi0Ib8T1k8wQydfEqmdUPWcsw1_P-eDiG-NLdZuMLTdKNQsd2zSZ50JQILSyhsJ-MTYRN_Xn4RveND_sGud_Ck68dISSCUfrbdr7V9MStagCvCzyg6Vsd34g9-o2tjVV4QXR0S5ixweNpG-4mjVymIEf80XK4Eb1fkleLNa3L2vKnT8FjxZQUDbF4DMH2Enf9wx626hPx21AclJHvXWKJlA2bfHhqBpigIDClNQZZ5RZsekjTjCkW90u6myBxC6jz6rKVLkOY8zGY95VomI7aVzGDnWkQkW8v-dJZT9FMN8Z0u4EsH1SMFfOSjVVkTx_HikrHOaXuQ2_v5_-xvT8Cow8P2bkm1MYFQiAmzUwVaIJ87QDd09_iLL5xdOBjRY00M3CWXbvZxo_Oqp-qu62I4_TEIsl8rE42hMOH6lm4-FWJpnk-K8lakjXjSpVQMkPTNHFY3TyWhD3D7V3qa2oxWOWUcJxm0lsAspkNlgg4tG5ReWQlA002HwO4gaX8U0dGxkLqDaJYGIWeFlbn1IaQGEQ3Ia-f4mj9wTBGVDb0nk1dtTMQ-nNRHxDjh5ibbSIi2NCiMu7AKjN7xogh5EkWoSmIYrSZN6cDhSFMlNfsFbkhV8ruQrkV3bZB-kYbuyc1KLLIXdfR0MSTbqCogI3Ud2oJe0DRXpCoQnfb6FWKlXf5wjT5TKgNm6v6i3wj4QMYAzK1NvvmSd4e0XROtFxzz6wcb01IglrjRTN1Ot9G2Z-kycxfT1wkuv2NX0LqrQ3ljDm-virAGMfdamuMzkly2U8AErpBNAXDjFGKm6jdyjtyMvzUgjfpCU_l4H37rJgLaUuHq7L8F_RCLxfzJKQN24Bv4bpdUaji3f2HB0e3HosI4Sn_ZMIwHULs0FwrVeCLnOtn_5VoHFDbl9Vyku5Za6eij6cwU0vcpOgXRnksXdD_p72IUaMbgdJy8O3GiS0Ga9kFeqW9aqQ_JFBo1aUhhRbJVHIOG_AhEMVNBtbm7FkqQ1Qvp-kHSoZGLw4-ymrG60EKdyicGPwMXSeach1tdHZ965vJOpqMEjnjFOCYkkPweaAd-rQjXkGytQ_2N0UacP1SAsr8RQrE1BLBEgr9Yg8GFf4ChF8WcjYp-M68-h0WkG-zWYCXvc7bSJ9R5BdfOVourb1a2lo1Mvbd42Ad6dXx7Libs1yqMOnpCNVj5cWsPuEInd0Amco1UEdoyrsLVHRiJUAWlbZOzNP537StaTt6aK8gf1VkJP8EPZA70U7qdlWF1RyQtjIPORd4FoY-4_4X8IOZbt8yi8uCB7o9wiQyMM_fFHCpftLa5Sy8KHBzzR2pB78T2Pe6wWvRBKsQzxv50w4V7IyWHo8wLz72baG1_dSoLGp0RwxC9MrRNh6ZJF28iYqPCIPaDlikEierJd1JZ5bXt4A_-DvuQopTKhC3fB5_LNilIyNK80BjsgpWh6Fd7a07t8XXz6YvrBZ_2aJRDlVWwsHlmrbRi94OUyIbP5LcY6Z2YOhMIaUL1phMK9voPavhTlA1dDf52aKLnoAmNq_KRkq98n6HagyYscaSuusErKwAQEm7pjw7YxZyEXB47BXhVKTi4ZUQWgZLTpyH29gn0_CAuIfO21q9qa3Gc39GPjxIGF_Ss4i_DKjHnWframX6fOTVjYEtYFfxnE6bjhd9-KqZ0NrZelTIgdHWLxaFv7_RwPTCoTQ6wXSSGXKn-OJM_rITcNg0ikzc2Gv1z3Uvpf_cKmOBXSSwyXjxO4lQRSWTZppVuTDT1AfwfNtR0tsfJJel3lzTo_ldJlOFWWDuoBfOl0t1SAB5Yqh9ABXF89LknqwmIpxL8ykGsP-iByuaJhVngqbLDJdS4KO17VcX69o2oHC47CjzF0sB0lM_jWk69_Kmfl61Ky1nWjZNrDPoiW71oxdmNfAfsS7Rg5v9.Gi1d0Ou_IOu-WuHP8rIOMw",
  "filledFields": [
    "Originator.originatorPersons.naturalPerson.name.nameIdentifier.primaryIdentifier",
    "Originator.originatorPersons.naturalPerson.name.nameIdentifier.secondaryIdentifier",
    "Originator.originatorPersons.naturalPerson.name.nameIdentifier.nameIdentifierType",
    "Originator.originatorPersons.naturalPerson.customerIdentification",
    "Originator.originatorPersons.naturalPerson.dateAndPlaceOfBirth.dateOfBirth",
    "Beneficiary.beneficiaryPersons.naturalPerson.name.nameIdentifier.primaryIdentifier",
    "Beneficiary.beneficiaryPersons.naturalPerson.name.nameIdentifier.secondaryIdentifier",
    "Beneficiary.beneficiaryPersons.naturalPerson.name.nameIdentifier.nameIdentifierType",
    "Beneficiary.beneficiaryPersons.naturalPerson.customerIdentification",
    "Beneficiary.beneficiaryPersons.naturalPerson.dateAndPlaceOfBirth.dateOfBirth"
  ]
}
---------------------------------

```

#### Decryption Example

Here is an example of source IVMS structure with encrypted IVMS data. Note that this data is just an example input file and cannot be used for actual testing, as the parser will throw a token-expired exception. This encrypted data should be the content the partner has sent to us as part of creating or getting a TRM (i.e., signed with their private key and encrypted with our public key). In other words, the output of the previous script cannot be used here for testing.

```json theme={"system"}
{
  "version": "IVMS101.2023",
  "data": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoidGVzdC1zZW5kZXItMjAyNSIsImN0eSI6IkpXVCJ9.Q2TS_6NOsy_bfmOmS23uYItJJqtU8mhSxXCvkvuP2aLtZSgBmtnICnfq1l4CJmxP0MI03RHWqfhg4NmNBPwih524GCwu16Vt1T1MUmoEyzUGRGHl1x8rYam_x6tihfGADbXzrCiSOwZYPrc4mbP31wRCiFC8vhTx2PEzCvZrEGfGjWanZIPARtczxfjzN_QEok3D8HVIJOmTq-lYFf6mgaOWwoSz0xbae7wzlLFScWHwaGdQ-Un6_F7OR8ed-6bCrp24_qlpwLkA3dMVqX4cQarVca-DmfGmvVaoXSflUwePRfwkRkcJcvRxECekvoFpQvCQ6VDBg3SAvxK-khFzwQ.AkMTJBpld5ZhxECk.ZgWkgarTGWFnkDCcur9Z0Wr1HDPAG3G11SK5YZ5c8vE2hLTVWmRbof1YedpdVHiWEoUQjBEEzNmIqVIVoRSQ9-pbehXIN_i_lYgBehPJ_dVp0j79nXCGRSY5-vSRzVpMRWtqM-3R6cav-3ftduPEzn6XIjjkVxC_G7Hhp-BIuHNafaoAKJgxOWVZfUyw4HRHZ4s1f14l2lRQymVVFPyIAiNDWSWYivFqybIaMyDrmhJEBlSQKwKBhBMc11JEe11IaJb2asgZkeaf-C77ls-ZG4oVEAK03Rjk_I5C7sRQtunmJSrwBh5coDY_XGL9cmjCGlKW-n3eQMK01cHIHLikYxEN9DQo4XPF0Oi3L6czE7I5lFfzm4BBNeZejP8dvIAce7T-HhFk3SpnJ94omwmCrw_MNLfVFPGCNAxHUX5oM5XdWuazOVA8_fF6F18gVk7nWddkuQsyJEfCRT_-BRmdHhw4CGHDd1nMKjg0its2uHzrFM0hrd88NRLtzwX-7G-elSsydxuD5fWU4um93oYj5BgA70JDoS_N8bGFlBrpt0rv8cP3lEUlblIFAxbSFa3-5N6GP_bKmR02WFy7zaV5TQaQsods015glvTz0DBrNmyOmAu0xUzMj46KOC9qDDGRnZjCiBZW-ySt9CpFnesGEmfln1aw7TgSQ0kel4F7nwB0HykCTGKe8Wm9bEgl6w_aCEtSFt0IioA5lmNyZA8cZf6Cf8rgeihv--sbSWM5Y0zcaaO41_bifTUGnbTE63fApYmn2TceTz2KNy9Db9kMAsnb4moC1DgnVeb3-bRl_NNnnuRftM5LEsBqc-RC1Yt7t6gTmwCMqT3BghZjqm3GPJufXaulG7LpxLUVwcM7NhpJGw3DpCEtBkWJWwHE27EQy-17x2Mwpk_3TLmhvP2W0ZV1uFB_Qz_tsMz9lxQ4NStwmbDyBHBQSZ5gS-FpZzfrtilgIxKBt7-GaalcXRd8wV_MbLbHP4W7k1d3uFYwxAfFUDKWvxderSUQ-TmfzEHyJiXxXSpHIDMEJz9pGC_JKxM6G9zgAfosJ76bBqT3v_YdtPmuFUx9TVxBW_1EPk58yTJR5V1XL7B6HYd_qrCsOahnyaZ6zq3Ygsfza5IOP3-7rSF15JXMoQtN47rgOeplHa3xrTsCuEraXAbVwVp99n3OpPQ9R2MZwPzUEbDkQ7XRYHIhaKYrEiYE9E0atK1Dn4Kd2dB1nukVlC3k1ETMIb6evR0x2JpcrGFlk71rjd61uS07XpDV3gU09JbI-aRsUSbJ7-crssx0158aHsfO_XiTLiQ3e9Mz5vjY6gjiefo-fybxNmOZ7skWuG5-BOrbOAqWEu9j-QfMiHWi3L_r8vPNtythOIh4VkOF-x1SnEujJWEfyvEl6zTqVyy4ArWeJxiIx7eY0jdAh-DQ0lR70iALnr-MudqFbrb5Kda2Yf20B8f6rgcnvLUOm4rNS9ewgzNmzDjS3L_OAFdQahBve2t-8rDvbWYIdYEy4XdU9uBwN47CjfZRqxLbClMsUrEGJyffVsKXkE2q0kPSlHjsVcSIBpuUaFaRXPZDAp-vv0dRlgJnu7ojzmO9twe4rg5gCYWvhuTP6fvLNyxzpVjbuMNso5V_Kh1841510DofG8uJXl_Yweo9AaQ1_km_8PfClKAF9s90hhkc-bDXIQCv2tZasJ-l62iBXL9RgytDr73k5KCNAfREUN-pVT-ePhyoFkRjiJTp4i0UO7DMLHH2evnc6dDPoL38Imc5XVZ3nKDXBCtJqlP_b0fVNialqW-j86bVXPp-ROCZqN8568ohb2w7BcfnrG3Mu5-Z1uuUXkduROIR2YfpIYHs5MF7ibXx_KGDsyhQibqchCDHSihdQl0GcCf1ShIMGYJ6zHsjcRFMD6q_QbS14QSJWGYX5otCK_TEkKRKBDtP5LlPxzOb7t1X5aDkAWABOhiExengSvXKj_fh1LrrG0_hNHuZ3ZTdN33a9sHESwjTG9ftfTFmi8RD_SabVIOKNMjCbA21UAVBeLbj6O16lTMEqwyAg165o3nKIdwrgT4NTz2Q7OEjcmPpTrMUmJNhV5V8MrL6s3K9XOSq245nSfE5VC6U-bXM_U2GSK1_dAAA2PjH6OxiGzrDz3yhrXN_D2gOUkAtxI9zQOF5f__kbE4i4mT9wWLUBnk2zie2X7mPJMrTTPy6S1uPdm811hkmA7pEKwMyh4LI58boeORipzIY7yERWK516GFA1ISIX7AirlHxrgaiojBJ5K7kyI2futrDchX8m-cAnT6dDtzE5fvq_kw_4XzWn-NCtO1nMe7ZydzlNCmI_dHaADHAfxQo9Fi3yTeVV76wWnFEVcrEnoYmibyoW7fNS0Yjlh3D.M6DlnVu5kCnzXwtp3y1ToA",
  "filledFields": [
    "Originator.originatorPersons.naturalPerson.name.nameIdentifier.primaryIdentifier",
    "Originator.originatorPersons.naturalPerson.name.nameIdentifier.secondaryIdentifier",
    "Originator.originatorPersons.naturalPerson.name.nameIdentifier.nameIdentifierType",
    "Originator.originatorPersons.naturalPerson.customerIdentification",
    "Originator.originatorPersons.naturalPerson.dateAndPlaceOfBirth.dateOfBirth",
    "Beneficiary.beneficiaryPersons.naturalPerson.name.nameIdentifier.primaryIdentifier",
    "Beneficiary.beneficiaryPersons.naturalPerson.name.nameIdentifier.secondaryIdentifier",
    "Beneficiary.beneficiaryPersons.naturalPerson.name.nameIdentifier.nameIdentifierType",
    "Beneficiary.beneficiaryPersons.naturalPerson.customerIdentification",
    "Beneficiary.beneficiaryPersons.naturalPerson.dateAndPlaceOfBirth.dateOfBirth"
  ]
}
```

This utility processes the paths to a partner's public key, our private key, and encrypted IVMS data, which are provided as arguments. It then decrypts an IVMS block containing encrypted data.

```javascript theme={"system"}
const jose = require('node-jose');
const crypto = require('crypto');
const path = require('path');
const fs = require('fs/promises');

const SIGNATURE_ALGORITHM = 'RS256';
const ENCRYPTION_ALGORITHM = 'RSA-OAEP-256';
const ENCRYPTION_METHOD = 'A256GCM';
const DEFAULT_EXPIRY_MS = 300000; // 5 minutes
const CLOCK_SKEW_SEC = 60; // ±60s skew
const CLAIM_DATA = 'data'; // The JWT claim holding the payload

/**
 * Travel Rule JWT Codec for PII Data Encryption
 *
 * Implements a nested JWT (JWS signed token encrypted inside a JWE)
 * for secure PII exchange, compatible with the Java TRJWTCodec implementation.
 *
 * Features:
 * - Object signing and encryption: `prepareIvmsData` / `decryptAndDecode`
 * - JTI (JWT ID) claim for replay attack protection
 * - Standard claims validation (iss, iat, exp)
 */
class TRJWTCodec {
  constructor() {
    this.keyStore = jose.JWK.createKeyStore();
    this.publicKey = null; // Partner's public key (for encryption)
    this.privateKey = null; // Our private key (for signing)
    this.initialized = false;
  }

  /**
   * Initialize the codec with RSA key pairs.
   *
   * @param {Object} config - Configuration object
   * @param {string} config.publicKey - PEM-encoded RSA public key (partner's key for encryption)
   * @param {string} config.privateKey - PEM-encoded RSA private key (our key for signing)
   */
  async initialize(config) {
    this._assert(config.publicKey, 'Public key is required');
    this._assert(config.privateKey, 'Private key is required');

    try {
      this.publicKey = await this.keyStore.add(config.publicKey);
      this.privateKey = await this.keyStore.add(config.privateKey);
      this.initialized = true;
    } catch (error) {
      throw new Error(`Failed to initialize TRJWTCodec with provided keys: ${error.message}`);
    }
  }

  /**
   * Encrypt and sign an object as a nested JWT (JWS inside JWE).
   * This is the lower-level function that returns only the JWE string.
   *
   * @param {Object} data - The JSON-serializable object to encrypt.
   * @param {string} issuer - The 'iss' claim (our identifier).
   * @param {number} [expiryMs=DEFAULT_EXPIRY_MS] - Expiry time in milliseconds.
   * @returns {Promise<string>} - The compact-serialized JWE token string.
   */
  async encodeAndEncrypt(data, issuer, expiryMs = DEFAULT_EXPIRY_MS) {
    this._assertInitialized();
    this._assert(data, 'Data cannot be null or undefined');
    this._assert(issuer && typeof issuer === 'string' && issuer.trim(), 'Issuer must be a non-empty string');

    // 1. Serialize the object to a JSON string
    const dataJson = JSON.stringify(data);
    // 2. Encode the JSON string as base64url
    const dataB64Url = Buffer.from(dataJson, 'utf8').toString('base64url');
    // 3. Pass the base64url string to the byte-level encryption method
    return this.encryptBytes(dataB64Url, issuer, expiryMs);
  }

  /**
   * Prepares the full IVMS data object, including the encrypted JWE
   * and the list of filled fields.
   *
   * @param {Object} data - The IVMS data object to encrypt.
   * @param {string} issuer - The 'iss' claim (our identifier).
   * @param {number} [expiryMs=DEFAULT_EXPIRY_MS] - Expiry time in milliseconds.
   * @returns {Promise<{version: string, data: string, filledFields: string[]}>}
   * An object containing the API version, the encrypted JWE string,
   * and the dot-notation paths of all non-null fields.
   */
  async prepareIvmsData(data, issuer, expiryMs = DEFAULT_EXPIRY_MS) {
    // 1. Create the encrypted JWE string from the data object.
    // This handles signing with our private key and encrypting with the partner's public key.
    const encryptedData = await this.encodeAndEncrypt(data, issuer, expiryMs);
    // 2. Extract all filled field paths from the original data object.
    const filledFields = this._extractFilledFields(data);

    return {
      version: 'IVMS101.2023', // API version
      data: encryptedData,
      filledFields: filledFields
    };
  }

  /**
   * Decrypt and decode data from an encrypted JWE token.
   *
   * @param {string} encryptedJWT - The compact-serialized JWE token.
   * @param {string} [expectedIssuer] - (Optional) The expected 'iss' claim for validation.
   * @returns {Promise<Object>} - The original decrypted and parsed JSON object.
   */
  async decryptAndDecode(encryptedJWT, expectedIssuer = null) {
    this._assertInitialized();
    this._assert(encryptedJWT, 'Encrypted JWT cannot be null or empty');

    // --- JWE Decryption ---
    // 1. Decrypt the outer JWE layer using our private key.
    const jweResult = await jose.JWE.createDecrypt(this.privateKey)
      .decrypt(encryptedJWT);

    // The payload of the JWE is the inner JWS.
    const signedJWT = jweResult.payload.toString('utf8');

    // --- JWS Verification ---
    // 2. Verify the signature of the inner JWS using the partner's public key.
    const jwsResult = await jose.JWS.createVerify(this.publicKey)
      .verify(signedJWT);

    // The payload of the JWS is the claims object.
    const claimsJson = jwsResult.payload.toString('utf8');
    const claims = JSON.parse(claimsJson);

    // --- Claims Validation ---
    // 3. Validate standard JWT claims (iat, exp, iss, jti).
    if (expectedIssuer && claims.iss !== expectedIssuer) {
      throw new Error(`Invalid issuer: expected ${expectedIssuer}, got ${claims.iss}`);
    }

    const nowSec = Math.floor(Date.now() / 1000);
    if (claims.iat && claims.iat > nowSec + CLOCK_SKEW_SEC) {
      throw new Error('Token "iat" (issued at) is in the future');
    }
    if (claims.exp && nowSec - CLOCK_SKEW_SEC > claims.exp) {
      throw new Error('Token has expired');
    }
    if (!claims.jti) {
      throw new Error('Missing "jti" (JWT ID) claim');
    }

    // --- Payload Extraction ---
    // 4. Extract, decode, and parse the custom 'data' claim.
    const dataB64Url = claims[CLAIM_DATA];
    if (!dataB64Url) {
      throw new Error(`Missing required "${CLAIM_DATA}" claim`);
    }

    const dataBuffer = Buffer.from(dataB64Url, 'base64url');
    const dataJson = dataBuffer.toString('utf8');

    return JSON.parse(dataJson);
  }

  /**
   * Encrypts a base64url-encoded string payload into a nested JWS-in-JWE token.
   *
   * @param {string} dataB64Url - The base64url-encoded data string.
   * @param {string} issuer - The 'iss' claim.
   * @param {number} expiryMs - Expiry time in milliseconds.
   * @returns {Promise<string>} - The compact-serialized JWE token string.
   * @private
   */
  async encryptBytes(dataB64Url, issuer, expiryMs) {
    this._assertInitialized();

    try {
      // --- JWS Claims Setup ---
      // 1. Create the claims for the inner JWS token.
      const nowMs = Date.now();
      const iat = Math.floor(nowMs / 1000); // Issued at
      const exp = Math.floor((nowMs + expiryMs) / 1000); // Expiration
      const jti = crypto.randomUUID(); // Unique token ID

      const claims = {
        iss: issuer,
        iat: iat,
        exp: exp,
        jti: jti,
        [CLAIM_DATA]: dataB64Url,
      };
      const claimsJson = JSON.stringify(claims);

      // --- JWS Creation (Signing) ---
      // 2. Sign the claims with our private key.
      const jwsOptions = {
        format: 'compact',
        fields: {
          alg: SIGNATURE_ALGORITHM,
          typ: 'JWT',
          kid: this.privateKey.kid
        }
      };

      const signedJWT = await jose.JWS.createSign(jwsOptions, this.privateKey)
        .update(claimsJson)
        .final();

      // --- JWE Creation (Encryption) ---
      // 3. Encrypt the signed JWS with the partner's public key.
      const jweOptions = {
        format: 'compact',
        contentAlg: ENCRYPTION_METHOD,
        fields: {
          alg: ENCRYPTION_ALGORITHM,
          enc: ENCRYPTION_METHOD,
          kid: this.publicKey.kid,
          cty: 'JWT' // Content Type: Indicates payload is a JWT
        }
      };

      const encryptedJWT = await jose.JWE.createEncrypt(jweOptions, this.publicKey)
        .update(signedJWT)
        .final();

      return encryptedJWT;

    } catch (error) {
      throw new Error(`Nested JWT encryption failed: ${error.message}`);
    }
  }

  /**
   * Recursively extracts all filled (non-null, non-undefined)
   * leaf node paths from an object in dot-notation.
   *
   * @param {Object} obj - The object to traverse.
   * @returns {string[]} - An array of dot-notation field paths.
   * @private
   */
  _extractFilledFields(obj) {
    // Start the recursion with the root object and no path prefix
    return this._recursiveExtract(obj, '');
  }

  /**
   * Helper function for _extractFilledFields.
   * @param {*} current - The current value being inspected.
   * @param {string} path - The dot-notation path to this value.
   * @returns {string[]} - A flat array of leaf paths found from this node.
   * @private
   */
  _recursiveExtract(current, path) {
    // 1. Base Case: Null/Undefined values are "empty" and ignored.
    if (current === null || current === undefined) {
      return [];
    }

    // 2. Array Case: Recurse on each item, but keep the *same* path.
    // This "flattens" the array, so 'person.addresses[0].city' and
    // 'person.addresses[1].city' both map to 'person.addresses.city'.
    if (Array.isArray(current)) {
      // Use flatMap to collect and flatten results from all items.
      return current.flatMap(item => this._recursiveExtract(item, path));
    }

    // 3. Object Case: Recurse on each key/value pair, *extending* the path.
    if (typeof current === 'object') {
      return Object.entries(current).flatMap(([key, value]) => {
        const newPath = path ? `${path}.${key}` : key;
        return this._recursiveExtract(value, newPath);
      });
    }

    // 4. Primitive Case: This is a leaf node (string, number, boolean).
    // Return its path, as long as it's not an empty path (i.e., a root primitive).
    return path ? [path] : [];
  }

  /**
   * Throws an error if the codec is not initialized.
   * @private
   */
  _assertInitialized() {
    if (!this.initialized || !this.privateKey || !this.publicKey) {
      throw new Error('TRJWTCodec is not initialized. Call initialize() with keys first.');
    }
  }

  /**
   * Simple assertion helper.
   * @private
   */
  _assert(condition, message) {
    if (!condition) {
      throw new Error(message);
    }
  }
}


// --- Command-Line Execution ---

/**
 * Helper to read and parse a JSON file from a given path.
 * @param {string} filePath - Path to the JSON file.
 * @returns {Promise<Object>} - The parsed JSON object.
 */
async function readJsonFile(filePath) {
  const absolutePath = path.resolve(filePath);
  try {
    const content = await fs.readFile(absolutePath, 'utf8');
    return JSON.parse(content);
  } catch (error) {
    throw new Error(`Failed to read or parse file ${absolutePath}: ${error.message}`);
  }
}

/**
 * Main execution function for the command-line demo.
 */
async function main() {
  const args = process.argv;
  // Basic argument check
  if (args.length < 5) {
    console.error('Usage: node your-script-name.js <partnerPublicKeyFile> <ourPrivateKeyFile> <encryptedIvmsDataFile>');
    console.error('Example: node decrypt.js partner-public.json my-private.json data.json');
    process.exit(1);
  }

  const [,, publicKeyFile, privateKeyFile, ivmsDataFile] = args;

  try {
    // 1. Load keys and data from files
    const publicKeyData = await readJsonFile(publicKeyFile);
    const privateKey = await readJsonFile(privateKeyFile);
    const ivmsData = await readJsonFile(ivmsDataFile);

    const { issuer, publicKey } = publicKeyData;
    if (!issuer || !publicKey) {
      throw new Error('Public key JSON file must contain "issuer" and "publicKey" fields.');
    }

    // 2. Initialize the Codec
    const codec = new TRJWTCodec();
    await codec.initialize({
      publicKey,  // Partner's public key (for signature verification)
      privateKey, // Our private key (for decryption)
    });

    // 3. Decrypt the IVMS Data
    // This decrypts with our private key and verifies the signature with the partner's public key.
    const decryptedIvms = await codec.decryptAndDecode(ivmsData.data, issuer);

    console.log(JSON.stringify(decryptedIvms, null, 2)); // Pretty-print the result
  } catch (error) {
    console.error(`\n❌ An error occurred: ${error.message}`);
    // console.error(error.stack); // Uncomment for full stack trace
    process.exit(1);
  }
}

// Run the main function
main();

```

### Encryption and Decryption (Partner: GTR using Curve25519)

<Note>
  **Security requirement:**

  All PII must be encrypted before transmission to GTR. Plain-text PII is prohibited.
</Note>

GTR requires Curve25519 encryption with ED25519 key pairs. The IVMS101 data format remains consistent across providers.

#### Key Requirements

* **Algorithm:** Curve25519
* **Key Format:** ED25519 (Public/Private Key Pair)
* **Key Conversion:** ED25519 keys must be converted to Curve25519 format
* **Key Management:** Configure public key in GTR Dashboard (Settings > Public Key)

#### Differences from Sumsub

| Aspect                    | Sumsub                                    | GTR                           |
| ------------------------- | ----------------------------------------- | ----------------------------- |
| **Encryption Algorithm**  | RSA with JWT (JWS inside JWE)             | Curve25519                    |
| **Key Format**            | JWK (JSON Web Key)                        | ED25519                       |
| **Key Conversion**        | Not required                              | ED25519 → Curve25519 required |
| **Public Key Management** | Retrieved via `getPublicKeyForEncryption` | Configured in GTR Dashboard   |

#### Implementation

1. Configure public key in GTR Dashboard (Settings > Public Key) with curve25519 algorithm
2. Obtain GTR's public key from GTR integration settings
3. Encrypt IVMS101 data using GTR's encryption tool
4. Submit encrypted data via `createTravelRuleMessage` endpoint
5. Decrypt received data using GTR's decryption tool for inbound TRMs

#### GTR Encryption Tool

GTR provides a standalone open source encryption tool that handles ED25519 to Curve25519 key conversion, IVMS101 encryption, and decryption. This tool operates independently from the Fireblocks SDK.

Use GTR's encryption tool rather than implementing Curve25519 encryption manually to ensure compatibility with GTR's requirements.

Learn more about the encryption tool in the [GTR Fireblocks integration guide](https://www.globaltravelrule.com/documentation/connect-fireblocks-with-gtr).

<Note>
  **Note:**

  The `getPublicKeyForEncryption` endpoint does not apply to GTR integrations. Public keys are managed directly in the GTR Dashboard.
</Note>

## API Integration

### Legal Entity Management

Legal entity management endpoints handle the creation and maintenance of legal entities requiring travel rule compliance. Each legal entity can have multiple TRSupport integrations with different TRP partners. Legal entities contain essential identifying information such as legal names, geographic addresses, national identifiers, and associated vault accounts. The `discoverable` field controls visibility in partner address books for counterparty discovery.

#### Create a Legal Entity

Creates a new legal entity for TRSupport integrations. This is the first step in setting up travel rule compliance for a legal entity. The legal entity stores all the legal and identification information required for IVMS101 compliance, including geographic address, national identification numbers, and date of incorporation. Once created, the legal entity can be linked to one or more TRPs through customer integrations. The `vaults` array associates specific Fireblocks vault accounts with this customer entity, while the `discoverable` setting determines if this legal entity should be visible to counterparties in the partner's address book.

**Endpoint:**

```http theme={"system"}
POST /v1/screening/trlink/customers
```

**Request Body:**

```typescript theme={"system"}
{
  shortName: string;                // Short name for the legal entity
  fullLegalName?: string;           // Full legal name
  countryOfRegistration?: string;   // ISO 3166-1 alpha-2 code (e.g., "US")
  nationalIdentification?: string;  // National identifier
  dateOfIncorporation?: string;     // ISO date string (e.g., "2023-01-15")
  geographicAddress?: {             // Geographic address
    formattedAddress?: string;
    country?: string;
    streetName?: string;
    buildingNumber?: string;
    city?: string;
    postalCode?: string;
  };
  vaults?: number[];                // Array of vault IDs
  trPrimaryPurpose?: string;        // Travel rule primary purpose enum
  discoverable?: string;            // "discoverable", "hidden", or "anonymous"
}
```

**Response (201):**

```typescript theme={"system"}
{
  id: string;
  discoverable: string;
  shortName: string;
  fullLegalName: string;
  geographicAddress: {
    formattedAddress?: string;
    country?: string;
    streetName?: string;
    buildingNumber?: string;
    city?: string;
    postalCode?: string;
  };
  countryOfRegistration: string;
  nationalIdentification: string;
  dateOfIncorporation: Date;
  trPrimaryPurpose: string;
  createDate: Date;
  lastUpdate: Date;
  vaults: number[];
}
```

**SDK Example:**

```typescript theme={"system"}
// Create a legal entity
const { data: customer } = await fireblocks.trLink.createTRLinkCustomer({
  shortName: "ACME Corp",
  fullLegalName: "ACME Corporation Ltd",
  countryOfRegistration: "US",
  nationalIdentification: "EIN-123456789",
  dateOfIncorporation: "2020-01-15",
  geographicAddress: {
    formattedAddress: "123 Main St, New York, NY 10001",
    country: "US",
    streetName: "Main St",
    buildingNumber: "123",
    city: "New York",
    postalCode: "10001"
  },
  vaults: [0, 1],
  discoverable: "discoverable",
  trPrimaryPurpose: "BUSINESS"
});

console.log(`Legal entity created with ID: ${customer.id}`);
```

#### Get a Legal Entity

Retrieves complete details for a specific legal entity by its unique ID. This endpoint returns all stored information about the legal entity, including their legal identifiers, geographic address, associated vaults, and travel rule configuration. Use this endpoint to verify legal entity details before creating integrations or to display legal entity information in your application.

**Endpoint:**

```http theme={"system"}
GET /v1/screening/trlink/customers/:customerId
```

**Path Parameters:**

* `customerId` (string, UUID) - The legal entity ID

**Response (200):**

```typescript theme={"system"}
{
  id: string;
  discoverable: string;
  shortName: string;
  fullLegalName: string;
  geographicAddress: object;
  countryOfRegistration: string;
  nationalIdentification: string;
  dateOfIncorporation: Date;
  trPrimaryPurpose: string;
  createDate: Date;
  lastUpdate: Date;
  vaults: number[];
}
```

**SDK Example:**

```typescript theme={"system"}
const customerId = "12345678-1234-1234-1234-123456789abc";
const { data: legalEntity } = await fireblocks.trLink.getTRLinkCustomerById(customerId);
console.log(`Legal entity: ${legalEntity.shortName}`);
```

#### Get All Legal Entities

Retrieves a list of all legal entities associated with the current tenant. This endpoint is useful for displaying a list of all legal entities configured for travel rule compliance. Each legal entity in the response includes full details, including vaults, addresses, and identifiers. The response is scoped to the authenticated tenant to ensure data isolation between different organizations.

**Endpoint:**

```http theme={"system"}
GET /v1/screening/trlink/customers
```

**Response (200):**

```typescript theme={"system"}
Array<{
  id: string;
  discoverable: string;
  shortName: string;
  fullLegalName: string;
  geographicAddress: object;
  countryOfRegistration: string;
  nationalIdentification: string;
  dateOfIncorporation: Date;
  trPrimaryPurpose: string;
  createDate: Date;
  lastUpdate: Date;
  vaults: number[];
}>

```

**SDK Example:**

```typescript theme={"system"}
const { data: legalEntities } = await fireblocks.trLink.getTRLinkCustomers();

legalEntities.forEach(legalEntity => {
  console.log(`Legal entity: ${legalEntity.shortName} (${legalEntity.id})`);
});
```

#### Update a Legal Entity

Updates the information for an existing legal entity. This endpoint allows you to modify any legal entity field, including their legal name, geographic address, national identifiers, vault associations, and discoverability settings. Updates are typically needed when business information changes or when correcting registration data. All fields in the request body are optional, allowing partial updates while preserving unchanged fields.

**Endpoint:**

```http theme={"system"}
PUT /v1/screening/trlink/customers/:customerId
```

**Path Parameters:**

* `customerId` (string, UUID) - The legal entity ID

**Request Body:**

```typescript theme={"system"}
{
  shortName: string;                // Short name for the legal entity
  fullLegalName?: string;           // Full legal name
  countryOfRegistration?: string;   // ISO 3166-1 alpha-2 code (e.g., "US")
  nationalIdentification?: string;  // National identifier
  dateOfIncorporation?: string;     // ISO date string (e.g., "2023-01-15")
  geographicAddress?: {             // Geographic address
    formattedAddress?: string;
    country?: string;
    streetName?: string;
    buildingNumber?: string;
    city?: string;
    postalCode?: string;
  };
  vaults?: number[];                // Array of vault IDs
  trPrimaryPurpose?: string;        // Travel rule primary purpose enum
  discoverable?: string;            // "discoverable", "hidden", or "anonymous"
}
```

**Response (200):**

```typescript theme={"system"}
{
  id: string;
  discoverable: string;
  shortName: string;
  fullLegalName: string;
  geographicAddress: object;
  countryOfRegistration: string;
  nationalIdentification: string;
  dateOfIncorporation: Date;
  trPrimaryPurpose: string;
  createDate: Date;
  lastUpdate: Date;
  vaults: number[];
}
```

**SDK Example:**

```typescript theme={"system"}
const customerId = "12345678-1234-1234-1234-123456789abc";

const { data: updatedLegalEntity } = await fireblocks.trLink.updateTRLinkCustomer(customerId, {
  shortName: "ACME Corp Updated",
  fullLegalName: "ACME Corporation Ltd - Updated",
  vaults: [0, 1, 2]
});

console.log(`Legal entity updated: ${updatedLegalEntity.shortName}`);
```

#### Delete a Legal Entity

Permanently deletes a legal entity and all associated data, including integrations, TRMs, and configuration. This is a destructive operation that cannot be undone. Use this endpoint when a legal entity is no longer operating or when cleaning up test data. All active integrations for this legal entity will be disconnected, and any pending TRMs may fail. Ensure all transactions are complete before deleting a legal entity.

**Endpoint:**

```sql theme={"system"}
DELETE /v1/screening/trlink/customers/:customerId
```

**Path Parameters:**

* `customerId` (string, UUID) - The legal entity ID

**Response (204):** No content

**SDK Example:**

```typescript theme={"system"}
const customerId = "12345678-1234-1234-1234-123456789abc";
await fireblocks.trLink.deleteTRLinkCustomer(customerId);

console.log('Legal entity deleted successfully');
```

### Legal Entity Integrations

Legal entity integration endpoints manage the connections between legal entities and the TRP partners. Each integration represents a configured connection to a specific TRP, such as Sumsub, enabling the customer to send and receive TRMs through that provider's network. An integration requires API credentials from the TRP to establish connectivity. A single customer can have multiple integrations with different partners to support various compliance networks. These endpoints handle the full lifecycle of partner connections, including creation, credential management, connectivity testing, and disconnection.

#### Create a Legal Entity Integration

Creates a new TRSupport integration that associates a legal entity with a specific TRP partner. This endpoint initializes the integration record but does not yet establish connectivity with the partner's API. After creation, you must use the `connectLegalEntityIntegration` endpoint to provide API credentials. The `partnerIdent` parameter identifies which TRP to integrate with (e.g., "Sumsub"). You can retrieve available partners using the `getPartners` endpoint. Each integration is assigned a unique `customerIntegrationId` used in subsequent API calls for TRM operations.

**Endpoint:**

```http theme={"system"}
POST /v1/screening/trlink/customers/integration
```

**Request Body:**

```typescript theme={"system"}
{
  customerId: string;     // Required - UUID of the legal entity
  partnerIdent: string;   // Required - Partner identifier (e.g., "notabene")
}
```

**Response (201):**

```typescript theme={"system"}
{
  customerIntegrationId: string;
  apiKey: string;              // Partially censored (e.g., "abc****xyz")
  secret: string;              // Censored (e.g., "***")
  createDate: Date;
  lastUpdate: Date;
  partner: {
    ident: string;
    name: string;
    description: string;
    baseUrl: string;
    active: boolean;
    isTest: boolean;
  };
  customer: {
    id: string;
    shortName: string;
    // ... other customer fields
  };
}
```

**SDK Example:**

```typescript theme={"system"}
const customerId = "12345678-1234-1234-1234-123456789abc";
const partnerIdent = "<partner ident>";

const { data: integration } = await fireblocks.trLink.createTRLinkIntegration({
  customerId: customerId,
  partnerIdent: partnerIdent
});

console.log(`Integration created with ID: ${integration.customerIntegrationId}`);
console.log(`Partner: ${integration.partner.name}`);
```

#### Connect a Legal Entity Integration

Establishes active connectivity to the TRP by supplying API credentials. This endpoint stores the API key and optional secret provided by the TRP, enabling the integration to authenticate and communicate with the partner's API. After connecting, the integration can be used for travel rule operations such as creating TRMs and querying VASPs. The credentials are securely stored and partially censored in API responses. Use the `testTRLinkIntegrationConnection` endpoint after connecting to verify that the credentials are valid and the integration is functioning properly.

**Endpoint:**

```http theme={"system"}
PUT /v1/screening/trlink/customers/integration/:customerIntegrationId
```

**Path Parameters:**

* `customerIntegrationId` (string, UUID) - The legal entity integration ID

**Request Body:**

```typescript theme={"system"}
{
  apiKey: string;      // Required - API key from the travel rule provider
  secret?: string;     // Optional - API secret from the travel rule provider
}
```

**Response (200):**

```typescript theme={"system"}
{
  customerIntegrationId: string;
  apiKey: string;              // Partially censored (e.g., "abc****xyz")
  secret: string;              // Censored (e.g., "***")
  createDate: Date;
  lastUpdate: Date;
  partner: {
    ident: string;
    name: string;
    description: string;
    baseUrl: string;
    active: boolean;
    isTest: boolean;
  };
  customer: {
    id: string;
    shortName: string;
    // ... other customer fields
  };
}
```

**SDK Example:**

```typescript theme={"system"}
const customerIntegrationId = "87654321-4321-4321-4321-123456789abc";

const { data: connectedIntegration } = await fireblocks.trLink.connectTRLinkIntegration(
  customerIntegrationId,
  {
    apiKey: "trp-api-key-12345",
    secret: "trp-secret-67890"
  }
);

console.log(`Integration connected: ${connectedIntegration.customerIntegrationId}`);
console.log(`Partner: ${connectedIntegration.partner.name}`);
```

#### Get a Legal Entity Integration

Retrieves detailed information about a specific legal entity integration, including its connection status, associated partner details, and legal entity information. The response includes partially censored API credentials for security. This endpoint is useful for displaying integration details in administrative interfaces or verifying integration configuration before performing travel rule operations. Both the legal entity ID and integration ID are required as path parameters for additional security validation.

**Endpoint:**

```http theme={"system"}
GET /v1/screening/trlink/customers/:customerId/integrations/:customerIntegrationId
```

**Path Parameters:**

* `customerId` (string, UUID) - The legal entity ID
* `customerIntegrationId` (string, UUID) - The legal entity integration ID

**Response (200):**

```typescript theme={"system"}
{
  customerIntegrationId: string;
  apiKey: string;              // Partially censored (e.g., "abc****xyz")
  secret: string;              // Censored (e.g., "***")
  createDate: Date;
  lastUpdate: Date;
  partner: {
    ident: string;
    name: string;
    description: string;
    baseUrl: string;
    active: boolean;
    isTest: boolean;
  };
  customer: {
    id: string;
    shortName: string;
    // ... other customer fields
  };
}
```

**SDK Example:**

```typescript theme={"system"}
const customerId = "12345678-1234-1234-1234-123456789abc";
const customerIntegrationId = "87654321-4321-4321-4321-123456789abc";

const { data: integration } = await fireblocks.trLink.getTRLinkCustomerIntegrationById(
  customerId,
  customerIntegrationId
);

console.log(`Integration: ${integration.customerIntegrationId}`);
console.log(`Partner: ${integration.partner.name}`);
```

#### Get Legal Entity Integrations

Retrieves all TRP integrations configured for a specific legal entity. This endpoint returns a complete list of TRP connections, including their status, partner details, and configuration. Use this to display all available TRP connections for a legal entity or to select which integration to use for a specific transaction. Legal entities may have multiple integrations to support different compliance networks or redundant provider setups.

**Endpoint:**

```http theme={"system"}
GET /v1/screening/trlink/customers/:customerId/integrations
```

**Path Parameters:**

* `customerId` (string, UUID) - The legal entity ID

**Response (200):** Array of legal entity integrations (same structure as Create legal entity integration response)

**SDK Example:**

```typescript theme={"system"}
const customerId = "12345678-1234-1234-1234-123456789abc";

const { data: integrations } = await fireblocks.trLink.getTRLinkCustomerIntegrations(customerId);

integrations.forEach(integration => {
  console.log(`Integration: ${integration.partner.name} (${integration.customerIntegrationId})`);
});
```

#### Disconnect a Legal Entity Integration

Disconnects and permanently removes a legal entity's integration with a TRP. This endpoint deletes the stored API credentials and removes the integration record. After disconnection, the integration can not be used for travel rule operations. Any pending TRMs may fail or become inaccessible. This is typically used when migrating to a different TRP, cleaning up unused integrations, or when API credentials are compromised and need to be fully removed before reconnecting with new credentials.

**Endpoint:**

```sql theme={"system"}
DELETE /v1/screening/trlink/customers/integration/:customerIntegrationId
```

**Path Parameters:**

* `customerIntegrationId` (string, UUID) - The legal entity integration ID

**Response (204):** No content

**SDK Example:**

```typescript theme={"system"}
const customerIntegrationId = "87654321-4321-4321-4321-123456789abc";

await fireblocks.trLink.disconnectTRLinkIntegration(customerIntegrationId);

console.log('Integration disconnected successfully');
```

#### Test Connection

Validates that a legal entity integration can successfully communicate with the TRP's API. This endpoint makes a test call to the TRP using the stored API credentials to verify authentication and connectivity. It returns a success indicator along with any error messages if the connection fails. This is essential after connecting or updating integration credentials to ensure the setup is correct before attempting actual travel rule operations. Regular connection testing can also be used to monitor integration health.

**Endpoint:**

```http theme={"system"}
POST /v1/screening/trlink/customers/integration/:customerIntegrationId/test_connection
```

**Path Parameters:**

* `customerIntegrationId` (string, UUID) - The legal entity integration ID

**Response (200):**

```typescript theme={"system"}
{
  success: boolean;
  message?: string;          // Error message if connection failed
  timestamp: string;         // ISO timestamp
  partnerIdent?: string;
  partnerName?: string;
}
```

**SDK Example:**

```typescript theme={"system"}
const customerIntegrationId = "87654321-4321-4321-4321-123456789abc";

const { data: result } = await fireblocks.trLink.testTRLinkIntegrationConnection(customerIntegrationId);

if (result.success) {
  console.log(`Connection successful to ${result.partnerName} at ${result.timestamp}`);
} else {
  console.error(`Connection failed: ${result.message}`);
}
```

### Travel Rule Operations

Travel rule operations manage the core compliance workflows for creating, managing, and tracking TRMs. These endpoints assess whether transactions require travel rule compliance based on thresholds and counterparty VASP identification, create and transmit TRMs containing encrypted IVMS101 customer data, and manage TRM lifecycle states, including cancellation and redirection. The operations support both outbound transactions (where you create the TRM before the blockchain transaction) and inbound transactions (where you create the TRM after receiving funds and reference an existing Fireblocks transaction).

#### Assess a Travel Rule Requirement

Determines whether a specific transaction requires travel rule compliance based on regulatory thresholds, transaction amounts, and counterparty VASP identification. This endpoint evaluates the transaction against the partner's configured travel rule policies and jurisdictional requirements. It returns a decision of `"REQUIRED"`, `"NOT_REQUIRED"`, or `"NEED_MORE_INFO"` along with an explanation.

When required, it also provides a list of mandatory IVMS101 fields that must be populated in the TRM. Use this endpoint before creating a TRM to verify compliance requirements and understand what legal entity data needs to be collected. For outbound transactions, provide transaction details explicitly. For inbound transactions, you can reference an existing Fireblocks `txId` to auto-populate transaction data.

**Endpoint:**

```http theme={"system"}
POST /v1/screening/trlink/customers/integration/:customerIntegrationId/trm/assess
```

**Path Parameters:**

* `customerIntegrationId` (string, UUID) - The legal entity integration ID

**Request Body:**

```typescript theme={"system"}
{
  txId?: string;                        // Fireblocks transaction ID (recommended for inbound)
  amount?: string;                      // Required if txId not provided
  amountUSD?: string;                   // Amount in USD
  destination?: {                       // Required if txId not provided
    type: string;                       // "ONE_TIME_ADDRESS" for outbound, "VAULT_ACCOUNT" for inbound
    id?: string;                        // Required for VAULT_ACCOUNT
    oneTimeAddress?: {
      address: string;
      tag?: string;
    };
  };
  destAddress?: string;                 // Destination address
  destTag?: string;                     // Destination tag
  source?: {                            // 
    type: string;                       // "VAULT_ACCOUNT" for outbound, "UNKNOWN" for inbound
    id?: string;                        // Required for VAULT_ACCOUNT
  };
  srcAddress?: string;                  // Source address
  assetId?: string;                     // Required if txId not provided (e.g., "ETH", "BTC")
  direction?: string;                   // "inbound" or "outbound"
  txHash?: string;                      // Blockchain transaction hash
  originatorVaspId?: string;            // Required for inbound transactions
  beneficiaryVaspId?: string;           // Required for outbound transactions
}
```

**Response (200):**

```typescript theme={"system"}
{
  decision: string;                     // "REQUIRED", "NOT_REQUIRED", or "NEED_MORE_INFO"
  reason: string;                       // Explanation of the decision
  requiredFields?: string[];            // List of required IVMS fields if travel rule is required
  missingInfo?: string[];               // List of missing fields if more info is needed
  thresholds?: {
    amount?: string;
    currency?: string;
  };
}
```

**SDK Example:**

```typescript theme={"system"}
const customerIntegrationId = "87654321-4321-4321-4321-123456789abc";

// Example 1: Assess for outbound transaction (before Fireblocks transaction)
const { data: assessment1 } = await fireblocks.trLink.assessTRLinkTravelRuleRequirement(
  customerIntegrationId,
  {
    amount: "1500",
    assetId: "ETH",
    direction: "outbound",
    source: {
      type: "VAULT_ACCOUNT",
      id: "0"
    },
    destination: {
      type: "ONE_TIME_ADDRESS",
      oneTimeAddress: {
        address: "0xabcdef1234567890abcdef1234567890abcdef12"
      }
    },
    beneficiaryVaspId: "beneficiary-vasp-456"
  }
);

if (assessment1.decision === "REQUIRED") {
  console.log(`Travel rule is required: ${assessment1.reason}`);
  console.log(`Required fields: ${assessment1.requiredFields.join(', ')}`);
} else {
  console.log(`Travel rule not required: ${assessment1.reason}`);
}

// Example 2: Assess for existing Fireblocks transaction (inbound)
const { data: assessment2 } = await fireblocks.trLink.assessTRLinkTravelRuleRequirement(
  customerIntegrationId,
  {
    txId: "12345678-1234-1234-1234-123456789abc",
    originatorVaspId: "originator-vasp-123"
  }
);

console.log(`Decision: ${assessment2.decision}`);
```

#### Create a TRM

Creates and submits a new TRM to the partner TRP containing IVMS101-compliant legal entity data for a cryptocurrency transaction. The TRM includes encrypted originator and beneficiary information, transaction details, and wallet addresses.

For outbound transactions, create the TRM before executing the blockchain transaction to ensure compliance is in place before funds move.

For inbound transactions, create the TRM after receiving the transaction and reference the existing Fireblocks `txId`.

The IVMS data must be encrypted using the partner's public key (retrieved via the `getPublicKey` endpoint). The endpoint returns a TRM ID that can be used to track the message status and should be associated with the Fireblocks transaction using the set transaction travel rule message ID endpoint.

**Endpoint:**

```http theme={"system"}
POST /v1/screening/trlink/customers/integration/:customerIntegrationId/trm
```

**Path Parameters:**

* `customerIntegrationId` (string, UUID) - The legal entity integration ID

**Request Body:**

```typescript theme={"system"}
{
  assetId?: string;                     // Required if txId not provided (e.g., "ETH", "BTC")
  amount?: string;                      // Required if txId not provided
  amountUSD?: string;                   // Optional - Force specific USD value
  source?: {                            // Required if txId not provided
    type: string;                       // "VAULT_ACCOUNT" for outbound, "UNKNOWN" for inbound
    id?: string;                        // Required for VAULT_ACCOUNT
  };
  srcAddress?: string;                  // Optional
  destination?: {                       // Required for single-destination transactions
    type: string;                       // "ONE_TIME_ADDRESS" for outbound, "VAULT_ACCOUNT" for inbound
    id?: string;                        // Required for VAULT_ACCOUNT
    oneTimeAddress?: {
      address: string;
      tag?: string;
    };
  };
  destAddress?: string;                 // Optional
  destTag?: string;                     // Optional
  txId?: string;                        // Optional - Fireblocks transaction ID (recommended for inbound)
  txHash?: string;                      // Optional - Blockchain transaction hash
  direction?: string;                   // Optional - "inbound" or "outbound"
  originatorVaspId?: string;            // Required for inbound transactions
  beneficiaryVaspId?: string;           // Required for outbound transactions
  ivms: {                               // Required - IVMS101 data
    version: string;                    // e.g., "IVMS101.2023"
    data: string;                       // Base64 encoded encrypted IVMS101 data
    filledFields: string[];             // Array of filled field paths
  };
}
```

**Response (201):**

```typescript theme={"system"}
{
  id: string;                           // TRM message ID
  version?: string;
  status?: string;                      // "PENDING", "ACCEPTED", "REJECTED"
  reason?: string;
  externalId: string;                   // Fireblocks transaction ID
  asset: {
    format: string;
    data: string;
  };
  amount: string;
  fiatValue?: {
    amount: string;
    currency: string;
  };
  direction: string;                    // "in" or "out"
  originatorVaspId?: string;
  beneficiaryVaspId?: string;
  txnInfo: {
    originatorWalletAddress: string;
    beneficiaryWalletAddress: string;
    txHash: string;
  };
  ivms101: {
    version: string;
    data: string;
    filledFields: string[];
  };
  providerData?: {
    provider?: string;
    data?: any;
  };
}
```

**SDK Example:**

```typescript theme={"system"}
const customerIntegrationId = "87654321-4321-4321-4321-123456789abc";

// Example 1: Create TRM for outbound transaction (before Fireblocks transaction)
const { data: trm1 } = await fireblocks.trLink.createTRLinkTrm(
  customerIntegrationId,
  {
    amount: "1500",
    assetId: "ETH",
    direction: "outbound",
    source: {
      type: "VAULT_ACCOUNT",
      id: "0"
    },
    destination: {
      type: "ONE_TIME_ADDRESS",
      oneTimeAddress: {
        address: "0xabcdef1234567890abcdef1234567890abcdef12"
      }
    },
    beneficiaryVaspId: "beneficiary-vasp-456",
    ivms: {
      version: "IVMS101.2023",
      data: "aGVsbG8gd29ybGQgdGhpcyBpcyBlbmNyeXB0ZWQgZGF0YQ==",
      filledFields: [
        "Beneficiary.beneficiaryPersons[].legalPerson.name.nameIdentifier",
        "Originator.originatorPersons[].legalPerson.name.nameIdentifier"
      ]
    }
  }
);

console.log(`TRM created with ID: ${trm1.id}`);
console.log(`Status: ${trm1.status}`);

// Example 2: Create TRM for existing Fireblocks transaction (inbound)
const { data: trm2 } = await fireblocks.trLink.createTRLinkTrm(
  customerIntegrationId,
  {
    txId: "12345678-1234-1234-1234-123456789abc",
    originatorVaspId: "originator-vasp-123",
    ivms: {
      version: "IVMS101.2023",
      data: "aGVsbG8gd29ybGQgdGhpcyBpcyBlbmNyeXB0ZWQgZGF0YQ==",
      filledFields: [
        "Beneficiary.beneficiaryPersons[].naturalPerson.name.nameIdentifier",
        "Originator.originatorPersons[].naturalPerson.name.nameIdentifier"
      ]
    }
  }
);

console.log(`TRM created with ID: ${trm2.id}`);
```

#### Get a TRM

Retrieves the current state and details of a specific TRM from the TRP. This endpoint fetches real-time information directly from the partner's API, including the message status (`PENDING`, `ACCEPTED`, `REJECTED`), encrypted IVMS data, transaction details, and any status reasons. Use this to monitor TRM progress, check for counterparty acceptance, or retrieve message details for audit purposes. The response includes both the original submitted data and any updated fields from the partner network.

**Endpoint:**

```http theme={"system"}
GET /v1/screening/trlink/customers/integration/:customerIntegrationId/trm/:trmId
```

**Path Parameters:**

* `customerIntegrationId` (string, UUID) - The legal entity integration ID
* `trmId` (string) - The TRM message ID

**Response (200):** Same as Create Travel Rule Message response

**SDK Example:**

```typescript theme={"system"}
const customerIntegrationId = "87654321-4321-4321-4321-123456789abc";
const messageId = "trm-12345678-1234-1234-1234-123456789abc";

const { data: trm } = await fireblocks.trLink.getTRLinkTrmById(
  customerIntegrationId,
  messageId
);

console.log(`TRM ID: ${trm.id}`);
console.log(`Status: ${trm.status}`);
console.log(`Direction: ${trm.direction}`);
console.log(`Amount: ${trm.amount} (${trm.fiatValue?.amount} ${trm.fiatValue?.currency})`);
```

#### Cancel a TRM

Cancels a previously submitted TRM and notifies the counterparty VASP of the cancellation. This endpoint should be used when a transaction is aborted, reversed, or when incorrect information was submitted and needs to be resent. The cancellation reason is transmitted to the counterparty to explain why the TRM is being cancelled. Once cancelled, the TRM cannot be reused, and a new TRM must be created if the transaction proceeds. This returns an asynchronous 202 status as the cancellation is communicated through the TRP network.

**Endpoint:**

```http theme={"system"}
POST /v1/screening/trlink/customers/integration/:customerIntegrationId/trm/:trmId/cancel
```

**Path Parameters:**

* `customerIntegrationId` (string, UUID) - The legal entity integration ID
* `trmId` (string) - The TRM message ID

**Request Body:**

```typescript theme={"system"}
{
  reason?: string;          // Optional - Cancellation reason
  cancelledBy?: string;     // Optional - User ID who cancelled
}
```

**Response (202):** Same as Create travel rule message response

**SDK Example:**

```typescript theme={"system"}
const customerIntegrationId = "87654321-4321-4321-4321-123456789abc";
const messageId = "trm-12345678-1234-1234-1234-123456789abc";

const { data: result } = await fireblocks.trLink.cancelTRLinkTrm(
  customerIntegrationId,
  messageId,
  {
    reason: "Transaction cancelled by user",
    cancelledBy: "user-123"
  }
);

console.log(`TRM cancelled: ${result.id}`);
console.log(`Status: ${result.status}`);
```

#### Redirect a TRM

Redirects an existing TRM to a subsidiary or nested VASP within a parent VASP's organization. This functionality is used in nested VASP scenarios where a parent VASP operates multiple subsidiary entities and needs to route the TRM to the specific subsidiary managing the legal entity relationship. The partner must support nested VASP capabilities for this endpoint to function. The TRM is redirected with its existing data to the specified `subsidiaryVaspId`. This returns an asynchronous 202 status as the redirection is processed through the TRP network.

**Endpoint:**

```http theme={"system"}
POST /v1/screening/trlink/customers/integration/:customerIntegrationId/trm/:trmId/redirect
```

**Path Parameters:**

* `customerIntegrationId` (string, UUID) - The legal entity integration ID
* `trmId` (string) - The TRM message ID

**Request Body:**

```typescript theme={"system"}
{
  subsidiaryVaspId: string;     // Required - ID of the subsidiary VASP
}
```

**Response (202):** Same as Create travel rule message response

**SDK Example:**

```typescript theme={"system"}
const customerIntegrationId = "87654321-4321-4321-4321-123456789abc";
const messageId = "trm-12345678-1234-1234-1234-123456789abc";

const { data: result } = await fireblocks.trLink.redirectTRLinkTrm(
  customerIntegrationId,
  messageId,
  {
    subsidiaryVaspId: "subsidiary-vasp-789"
  }
);

console.log(`TRM redirected: ${result.id}`);
console.log(`New beneficiary VASP: ${result.beneficiaryVaspId}`);
```

#### Get Required Actions

Retrieves the list of actions required to process a TRM that is in `PENDING` status. A TRM may enter PENDING when additional information is needed — for example, missing beneficiary PII data or a manual compliance review. This endpoint returns one or more required actions, each with a type, description, and action-specific data such as the list of required IVMS101 fields.

Use this endpoint after receiving a `TRLink.RequiredActions` webhook notification, or poll it to check the current state of a PENDING TRM. The same endpoint serves both automated systems and manual review workflows.

**Endpoint:**

```http theme={"system"}
GET /v1/screening/trlink/customers/integration/:customerIntegrationId/trm/:trmId/required_actions
```

**Path Parameters:**

* `customerIntegrationId` (string, UUID) - The legal entity integration ID
* `trmId` (string) - The TRM message ID

**Response (200):**

```typescript theme={"system"}
{
  actions: Array<{
    type: string;                         // "UPLOAD_BENEFICIARY_PII" or "MANUAL_REVIEW"
    description?: string;                 // Human-readable description of what's needed
    data?: {                              // Action-specific data
      beneficiaryRequiredFields?: string[]; // Required IVMS101 fields for PII upload
    };
  }>;
}
```

**Action Types:**

| Action Type              | Description                                                     | Required Data                                    |
| ------------------------ | --------------------------------------------------------------- | ------------------------------------------------ |
| `UPLOAD_BENEFICIARY_PII` | Client must provide beneficiary PII in encrypted IVMS101 format | `data.beneficiaryPii.ivms101` via Resolve Action |
| `MANUAL_REVIEW`          | Requires manual compliance review at the TRP                    | Varies (may be empty)                            |

**SDK Example:**

```typescript theme={"system"}
const customerIntegrationId = "87654321-4321-4321-4321-123456789abc";
const trmId = "trm-12345678-1234-1234-1234-123456789abc";

const { data: requiredActions } = await fireblocks.trLink.getTRLinkTrmRequiredActions(
  customerIntegrationId,
  trmId
);

console.log(`${requiredActions.actions.length} action(s) required:`);

requiredActions.actions.forEach(action => {
  console.log(`  Type: ${action.type}`);
  console.log(`  Description: ${action.description}`);

  if (action.type === "UPLOAD_BENEFICIARY_PII" && action.data?.beneficiaryRequiredFields) {
    console.log(`  Required fields:`);
    action.data.beneficiaryRequiredFields.forEach(field => {
      console.log(`    - ${field}`);
    });
  }
});
```

#### Resolve Action

Resolves a single required action on a PENDING TRM by submitting the requested data. For example, when the required action is `UPLOAD_BENEFICIARY_PII`, this endpoint accepts encrypted IVMS101 data containing the beneficiary's personally identifiable information.

The TRP processes the action synchronously and returns the updated TRM. If the action resolves the last pending requirement, the TRM status will change from PENDING to the next state (e.g., ACCEPTED). If multiple actions are required, call this endpoint once for each action — it resolves one action at a time.

After resolving an action, call `getRequiredActions` to check if additional actions remain.

**Endpoint:**

```http theme={"system"}
POST /v1/screening/trlink/customers/integration/:customerIntegrationId/trm/:trmId/resolve_action
```

**Path Parameters:**

* `customerIntegrationId` (string, UUID) - The legal entity integration ID
* `trmId` (string) - The TRM message ID

**Request Body:**

```typescript theme={"system"}
{
  type: string;                           // Required - Action type to resolve (must match one from getRequiredActions)
  data?: {                                // Action-specific data
    beneficiaryPii?: {                    // Required for UPLOAD_BENEFICIARY_PII
      ivms101: {
        version: string;                  // e.g., "IVMS101.2023"
        data: string;                     // Base64-encoded encrypted PII data
        filledFields: string[];           // List of IVMS101 fields included
      };
    };
  };
}
```

**Response (200):** Same as Create travel rule message response (returns the updated TRM).

<Note>
  The TRP also pushes the updated TRM via webhook to Fireblocks after processing. The synchronous response lets you see the immediate result, while the webhook ensures the screening pipeline is updated.
</Note>

**SDK Example:**

```typescript theme={"system"}
const customerIntegrationId = "87654321-4321-4321-4321-123456789abc";
const trmId = "trm-12345678-1234-1234-1234-123456789abc";

// Step 1: Get required actions
const { data: requiredActions } = await fireblocks.trLink.getTRLinkTrmRequiredActions(
  customerIntegrationId,
  trmId
);

const piiAction = requiredActions.actions.find(a => a.type === "UPLOAD_BENEFICIARY_PII");

if (piiAction) {
  // Step 2: Get public key for encryption
  const { data: { publicKey } } = await fireblocks.trLink.getTRLinkIntegrationPublicKey(
    customerIntegrationId
  );

  // Step 3: Encrypt beneficiary IVMS data (using your encryption implementation)
  const ivms = await encryptIVMSData(beneficiaryData, publicKey);

  // Step 4: Resolve the action
  const { data: updatedTrm } = await fireblocks.trLink.resolveActionTRLinkTrm(
    customerIntegrationId,
    trmId,
    {
      type: "UPLOAD_BENEFICIARY_PII",
      data: {
        beneficiaryPii: {
          ivms101: ivms
        }
      }
    }
  );

  console.log(`TRM updated - ID: ${updatedTrm.id}`);
  console.log(`New status: ${updatedTrm.status}`);

  // Step 5: Check if more actions are required
  const { data: remaining } = await fireblocks.trLink.getTRLinkTrmRequiredActions(
    customerIntegrationId,
    trmId
  );

  if (remaining.actions.length === 0) {
    console.log("All actions resolved.");
  } else {
    console.log(`${remaining.actions.length} more action(s) still required.`);
  }
}
```

#### Webhook: TRLink.RequiredActions

When a TRM enters PENDING status with required actions, Fireblocks sends a compliance webhook notification to the client.

**Event ID:** `Screening_TRLinkRequiredActions`

**Payload:**

```typescript theme={"system"}
{
  trmId: string;                          // TRM identifier
  customerIntegrationId: string;          // Integration to call endpoints with
  destinationScreeningId: string;         // Destination identifier (for deduplication)
  requiredActions: Array<{                // List of required actions
    type: string;
    description: string;
    data?: object;
  }>;
  screeningMessage: string;               // "Travel Rule message requires additional actions"
  messageType: string;                    // "TRLink.RequiredActions"
}
```

This notification is sent once per destination (deduplicated). Upon receiving it:

1. Optionally call `getRequiredActions` to refresh the current state
2. Collect the required data (e.g., encrypt beneficiary PII)
3. Call `resolveAction` for each required action

### TRM Operations

TRM operations manage the association between Fireblocks transactions and TRMs created with partner TRPs. These endpoints link TRM identifiers to transactions and specific destinations, enabling tracking and audit trails that connect blockchain transactions to their compliance data.

The operations support both transaction-level linking (for simple single-destination transactions) and destination-level linking (for multi-destination transactions where each output may have its own TRM). These associations are critical for maintaining compliance records and enabling automated monitoring of transaction vs. TRM status.

#### Set Transaction TRM ID

Associates a TRM ID with a Fireblocks transaction. This creates a link between the TRM and the transaction record, enabling compliance tracking and audit trails. For single-destination transactions, this single association is typically sufficient. The endpoint accepts the TRM ID as a string or null to clear an existing association. This should be called after creating a TRM to establish the compliance record link. The association enables the Fireblocks platform to display TRM status alongside transaction details and enforce any configured compliance policies.

**Endpoint:**

```http theme={"system"}
POST /v1/screening/trlink/transaction/:txId/travel_rule_message_id
```

**Path Parameters:**

* `txId` (string, UUID) - The Fireblocks transaction ID

**Request Body:**

```typescript theme={"system"}
{
  travelRuleMessageId: string | null;   // TRM ID or null to clear
}
```

**Response (200):**

```typescript theme={"system"}
{
  success: boolean;
}
```

**SDK Example:**

```typescript theme={"system"}
const txId = "12345678-1234-1234-1234-123456789abc";
const trmId = "trm-12345678-1234-1234-1234-123456789abc";

// Set TRM ID
const result1 = await fireblocks.trLink.setTRLinkTransactionTravelRuleMessageId(
  txId,
  {
    travelRuleMessageId: trmId
  }
);

console.log(`TRM ID set: ${result1.success}`);

// Clear TRM ID
const result2 = await fireblocks.trLink.setTRLinkTransactionTravelRuleMessageId(
  txId,
  {
    travelRuleMessageId: null
  }
);

console.log(`TRM ID cleared: ${result2.success}`);
```

#### Set Destination TRM ID

Associates a TRM ID with specific destinations in a multi-destination Fireblocks transaction. This endpoint supports two matching methods:

1. **Direct lookup** (recommended): Use the `destinationScreeningId` from a webhook notification (`TRLink.NoTRMessage` or `TRLink.RequiredActions`) for a direct, reliable match.
2. **Attribute matching** (legacy): Match destinations by amount and destination criteria (type, address).

For batch transactions sent to multiple counterparties, each destination may require a separate TRM. The endpoint returns a success status along with counts of successfully and unsuccessfully updated destinations, enabling error handling for partial failures. Set the TRM ID to null to clear an existing destination association.

**Endpoint:**

```http theme={"system"}
POST /v1/screening/trlink/transaction/:txId/destination/travel_rule_message_id
```

**Path Parameters:**

* `txId` (string, UUID) - The Fireblocks transaction ID

**Request Body (Option 1 — Direct Lookup via destinationScreeningId):**

```typescript theme={"system"}
{
  destinationScreeningId: string;       // From webhook notification - direct lookup
  travelRuleMessageId: string | null;   // TRM ID or null to clear
}
```

**Request Body (Option 2 — Attribute Matching):**

```typescript theme={"system"}
{
  amount: string;                       // Required - Destination amount to match
  destination: {                        // Required - Destination criteria to match
    type?: string;                      // e.g., "ONE_TIME_ADDRESS"
    id?: string;
    subType?: string;
    address?: string;
  };
  travelRuleMessageId: string | null;   // TRM ID or null to clear
}
```

When `destinationScreeningId` is provided, `amount` and `destination` are not required. The `destinationScreeningId` is a unique identifier for the destination screening record, available in webhook notifications.

**Response (200):**

```typescript theme={"system"}
{
  success: boolean;
  updatedDestinations: number;          // Number of successfully updated destinations
  failedDestinations: number;           // Number of failed updates
  errors?: string[];                    // Error messages if any failed
}
```

**SDK Example:**

```typescript theme={"system"}
const txId = "12345678-1234-1234-1234-123456789abc";
const trmId = "trm-12345678-1234-1234-1234-123456789abc";

// Option 1: Direct lookup using destinationScreeningId (recommended)
// The destinationScreeningId comes from webhook notifications
const { data: result1 } = await fireblocks.trLink.setTRLinkDestinationTravelRuleMessageId(
  txId,
  {
    destinationScreeningId: "dest-screening-id-from-webhook",
    travelRuleMessageId: trmId
  }
);

console.log(`Updated ${result1.updatedDestinations} destination(s)`);

// Option 2: Attribute matching (legacy, still supported)
const { data: result2 } = await fireblocks.trLink.setTRLinkDestinationTravelRuleMessageId(
  txId,
  {
    amount: "1500",
    destination: {
      type: "ONE_TIME_ADDRESS",
      address: "0xabcdef1234567890abcdef1234567890abcdef12"
    },
    travelRuleMessageId: trmId
  }
);

if (result2.success) {
  console.log(`Updated ${result2.updatedDestinations} destination(s)`);
} else {
  console.error(`Failed to update ${result2.failedDestinations} destination(s)`);
  console.error(`Errors: ${result2.errors?.join(', ')}`);
}
```

#### Manual Decision for Missing TRM

Allows clients to manually ACCEPT or REJECT a transaction when its destinations are waiting for a Travel Rule Message (Missing TRM state), instead of waiting for the automatic policy timeout or TRM arrival. This is useful when clients have internal compliance data (KYC status, risk scores) that allows them to make an immediate decision.

The decision applies to **all destinations currently in Missing TRM state** for the given transaction. Destinations in other states (Screen, Postscreen, Completed) are not affected and will be skipped. If no destinations are in Missing TRM state, the endpoint returns a 400 error.

Manual decisions are recorded with `source: "manual"` in the screening result, distinguishing them from automatic policy-based decisions.

**Endpoint:**

```http theme={"system"}
POST /v1/screening/trlink/customers/integration/:customerIntegrationId/transactions/:txId/manual_decision
```

**Path Parameters:**

* `customerIntegrationId` (string, UUID) - The legal entity integration ID
* `txId` (string, UUID) - The Fireblocks transaction ID

**Request Body:**

```typescript theme={"system"}
{
  action: string;                         // Required - "ACCEPT" or "REJECT"
  reason?: string;                        // Optional - Reason for audit trail (max 500 characters)
}
```

**Response (200):**

```typescript theme={"system"}
{
  action: string;                         // The action that was applied
  source: string;                         // Always "manual"
  txId: string;                           // Transaction ID
  destinationsAffected: number;           // Count of destinations where decision was applied
  destinationsSkipped: number;            // Count of destinations skipped
  details: Array<{
    destinationScreeningId: string;       // Destination identifier
    applied: boolean;                     // Whether the decision was applied to this destination
    skipReason?: string;                  // Reason if the destination was skipped
  }>;
}
```

**Override behavior:**

* If the same action is sent again for a destination already carrying that decision, the destination is skipped (idempotent).
* A different action overwrites the previous decision (last call wins).
* Once a destination has moved past the Missing TRM state, the decision cannot be changed.

**SDK Example:**

```typescript theme={"system"}
const customerIntegrationId = "87654321-4321-4321-4321-123456789abc";
const txId = "12345678-1234-1234-1234-123456789abc";

// Accept a transaction — e.g., beneficiary verified via internal KYC
const { data: result } = await fireblocks.trLink.createTRLinkManualDecision(
  customerIntegrationId,
  txId,
  {
    action: "ACCEPT",
    reason: "Beneficiary verified via internal KYC - known counterparty"
  }
);

console.log(`Action: ${result.action}`);           // "ACCEPT"
console.log(`Source: ${result.source}`);            // "manual"
console.log(`Destinations affected: ${result.destinationsAffected}`);
console.log(`Destinations skipped: ${result.destinationsSkipped}`);

result.details.forEach(dest => {
  console.log(`  ${dest.destinationScreeningId}: ${dest.applied ? "applied" : "skipped"}`);
  if (dest.skipReason) {
    console.log(`    Reason: ${dest.skipReason}`);
  }
});
```

**Webhook-driven example:**

```typescript theme={"system"}
// Listen for TRLink.NoTRMessage webhook, then decide based on internal data
app.post("/webhooks/compliance", async (req, res) => {
  const event = req.body;

  if (event.data?.messageType === "TRLink.NoTRMessage") {
    const { txId } = event.data;

    // Check internal KYC/risk system
    const internalDecision = await checkInternalCompliance(event.data.destAddress);

    const { data: result } = await fireblocks.trLink.createTRLinkManualDecision(
      customerIntegrationId,
      txId,
      {
        action: internalDecision.approved ? "ACCEPT" : "REJECT",
        reason: internalDecision.reason
      }
    );

    console.log(`${result.action}: ${result.destinationsAffected} destination(s)`);
  }

  res.sendStatus(200);
});
```

#### Get a Public Key for PII Encryption

<Note>
  **Note:**

  This endpoint applies to Sumsub integrations. GTR integrations configure public keys in GTR Dashboard. See the GTR Encryption section for details.
</Note>

Retrieves the TRP's public encryption key in JSON Web Key (JWK) format. This key must be used to encrypt IVMS101 data containing personally identifiable information (PII) before submitting TRMs. The encryption ensures that sensitive legal entity data is protected in transit and at rest, with only the partner and counterparty VASP able to decrypt it. Always fetch the current public key before encrypting IVMS data, as keys may rotate periodically. The response includes the key type (RSA), key ID (`kid`), and the public key components (modulus and exponent) needed for encryption operations.

**Endpoint:**

```http theme={"system"}
GET /v1/screening/trlink/customers/integration/:customerIntegrationId/public_key
```

**Path Parameters:**

* `customerIntegrationId` (string, UUID) - The legal entity integration ID

**Response (200):**

```typescript theme={"system"}
{
  issuer: string;
  publicKey: {
    kty: string;              // "RSA"
    e: string;                // Public exponent
    use: string;              // "enc"
    kid: string;              // Key ID
    n: string;                // Modulus
  };
}
```

**SDK Example:**

```typescript theme={"system"}
const customerIntegrationId = "87654321-4321-4321-4321-123456789abc";

const { data: { publicKey, issuer } } = await fireblocks.trLink.getTRLinkIntegrationPublicKey(customerIntegrationId);

console.log(`Issuer: ${issuer}`);
console.log(`Key ID: ${publicKey.kid}`);
console.log(`Key type: ${publicKey.kty}`);

// Use the public key to encrypt IVMS data
const encryptedData = encryptIVMSData(ivmsData, keyResponse.publicKey);
```

### VASP Operations

VASP (Virtual Asset Service Provider) operations provide access to the partner's VASP directory to discover and identify counterparties in TRM exchanges. These endpoints query the TRP's address book of registered VASPs, retrieving information about VASP identities, geographic locations, national identifiers, and public keys. This information is essential for determining whether a destination address requires travel rule compliance, obtaining VASP IDs for TRM creation, and validating counterparty information before sending TRMs.

#### List VASPs

Retrieves a paginated list of Virtual Asset Service Providers (VASPs) registered in the partner's network. This endpoint returns the partner's VASP directory containing all counterparties available for TRM exchanges. Each VASP entry includes identification details, legal names, national identifiers, and geographic addresses. Use pagination parameters to handle large VASP directories. This is useful for building VASP selection interfaces, implementing VASP search functionality, or syncing the partner's VASP directory to local storage for offline access. The `limit` parameter accepts values from 1 to 1000 VASPs per request.

**Endpoint:**

```http theme={"system"}
GET /v1/screening/trlink/customers/integration/:customerIntegrationId/vasps
```

**Path Parameters:**

* `customerIntegrationId` (string, UUID) - The legal entity integration ID

**Query Parameters:**

```typescript theme={"system"}
{
  pageSize?: number;    // Optional - Max items per page (1-100, default: 100)
  pageCursor?: string;  // Optional - Pagination cursor from previous response
}

```

**Response (200):**

```typescript theme={"system"}
{
  data: Array<{
    id: string;
    name: string;
    legalName?: string;
    nationalIdentification?: {
      identifier: string;
      type?: string;
      authority?: string;
    };
    geographicAddress?: {
      formattedAddress?: string;
      country?: string;
      streetName?: string;
      buildingNumber?: string;
      city?: string;
      postalCode?: string;
    };
  }>;
  next?: string;                      // Pagination cursor for next page
}

```

**SDK Example:**

```typescript theme={"system"}
const customerIntegrationId = "87654321-4321-4321-4321-123456789abc";

// Get first page of VASPs
const vasps1 = await fireblocks.trLink.listTRLinkVasps(customerIntegrationId, {
  pageSize: 50
});

console.log(`Page 1 VASPs: ${vasps1.data.length}`);
vasps1.data.forEach(vasp => {
  console.log(`VASP: ${vasp.name} (${vasp.id})`);
  if (vasp.geographicAddress?.country) {
    console.log(`  Country: ${vasp.geographicAddress.country}`);
  }
});

// Get next page
if (vasps1.next) {
  const vasps2 = await fireblocks.trLink.listTRLinkVasps(customerIntegrationId, {
    pageSize: 50,
    pageCursor: vasps1.next
  });

  console.log(`Page 2 VASPs: ${vasps2.data.length} VASPs`);
}
```

#### Get VASP by ID

Retrieves complete detailed information about a specific VASP by its unique identifier. This endpoint returns more comprehensive data than the list endpoint, including the VASP's public key if available. The TRP uses the public key for encrypted communication with that VASP. Use this endpoint when you have a VASP ID (e.g., from VASP attribution or address ownership verification) and need to retrieve full details about the counterparty, verify their identity information, or obtain their public key for secure messaging. This is particularly useful before creating TRMs to verify counterparty details.

**Endpoint:**

```http theme={"system"}
GET /v1/screening/trlink/customers/integration/:customerIntegrationId/vasps/:vaspId
```

**Path Parameters:**

* `customerIntegrationId` (string, UUID) - The legal entity integration ID
* `vaspId` (string) - The VASP ID

**Response (200):**

```typescript theme={"system"}
{
  id: string;
  name: string;
  legalName?: string;
  nationalIdentification?: {
    identifier: string;
    type?: string;
    authority?: string;
  };
  geographicAddress?: {
    formattedAddress?: string;
    country?: string;
    streetName?: string;
    buildingNumber?: string;
    city?: string;
    postalCode?: string;
  };
  publicKey?: string;       // VASP's public key
}
```

**SDK Example:**

```typescript theme={"system"}
const customerIntegrationId = "87654321-4321-4321-4321-123456789abc";
const vaspId = "beneficiary-vasp-456";

const { data: vasp } = await fireblocks.trLink.getTRLinkVaspById(customerIntegrationId, vaspId);

console.log(`VASP Name: ${vasp.name}`);
console.log(`Legal Name: ${vasp.legalName}`);
console.log(`Country: ${vasp.geographicAddress?.country}`);
if (vasp.nationalIdentification) {
  console.log(`National ID: ${vasp.nationalIdentification.identifier} (${vasp.nationalIdentification.type})`);
}
if (vasp.publicKey) {
  console.log(`Has public key: Yes`);
}
```

### Asset Operations

Asset operations provide access to the partner's supported cryptocurrency asset catalog and enable verification of asset support for travel rule compliance. These endpoints allow you to discover which blockchain assets and tokens are supported by a specific TRP, retrieve detailed asset information, including naming conventions and network identifiers, and determine whether the partner can handle assets not explicitly listed. This information is critical for validating transaction asset compatibility before creating TRMs and understanding the partner's asset support capabilities.

#### List Supported Assets

Retrieves a paginated list of cryptocurrency assets supported by a specific customer integration's TRP. This endpoint returns the partner's asset catalog containing asset identifiers, names, blockchain networks, and other metadata needed for travel rule messaging. Each asset entry is normalized to the Fireblocks asset format for consistency. The response includes a `partnerCanHandleAnyAsset` flag that indicates whether the partner can process TRMs for assets not explicitly listed in their catalog. Use pagination parameters to handle large asset catalogs. This is useful for validating asset support before creating TRMs, building asset selection interfaces, or syncing the partner's asset catalog for reference.

**Endpoint:**

```http theme={"system"}
GET /v1/screening/trlink/customers/integration/:customerIntegrationId/assets
```

**Path Parameters:**

* `customerIntegrationId` (string, UUID) - The legal entity integration ID

**Query Parameters:**

```typescript theme={"system"}
{
  pageSize?: number;    // Optional - Max items per page (1-100, default: 100)
  pageCursor?: string;  // Optional - Pagination cursor from previous response
}

```

**Response (200):**

```typescript theme={"system"}
{
  data: Array<{
    id: string;                       // Fireblocks asset ID (e.g., "ETH", "BTC_TEST")
    name?: string;                    // Asset display name
    type?: string;                    // Asset type (e.g., "BASE_ASSET", "ERC20_TOKEN")
    contractAddress?: string;         // Contract address for tokens
    nativeAsset?: string;             // Native blockchain asset
    decimals?: number;                // Decimal precision
    issuerAddress?: string;           // issuer address (used on SOL, and some other blockchains) 
  }>;
  next?: string;                      // Pagination cursor for next page
  partnerCanHandleAnyAsset: boolean;  // Whether partner supports unlisted assets
  note: string;                       // Support capability note
}
```

**SDK Example:**

```typescript theme={"system"}
const customerIntegrationId = "87654321-4321-4321-4321-123456789abc";

// Get first page of supported assets
const assetsPage1 = await fireblocks.trLink.listTRLinkSupportedAssets(
  customerIntegrationId,
  {
    pageSize: 50
  }
);

console.log(`Partner can handle any asset: ${assetsPage1.partnerCanHandleAnyAsset}`);
console.log(`Note: ${assetsPage1.note}`);
console.log(`\nSupported assets (page 1):`);
assetsPage1.data.forEach(asset => {
  console.log(`- ${asset.id}: ${asset.name} (${asset.type})`);
  if (asset.contractAddress) {
    console.log(`  Contract: ${asset.contractAddress}`);
  }
});

// Get next page if available
if (assetsPage1.next) {
  const assetsPage2 = await fireblocks.trLink.listTRLinkSupportedAssets(
    customerIntegrationId,
    {
      pageSize: 50,
      pageCursor: assetsPage1.next
    }
  );
  console.log(`\nPage 2: ${assetsPage2.data.length} more assets`);
}
```

#### Get a Supported Asset

Retrieves detailed information about a specific cryptocurrency asset's support status and metadata from the TRP. This endpoint validates whether a partner supports a particular asset and returns comprehensive asset details, including the Fireblocks-normalized asset data, the raw partner response, and a support status indicator. The `supported` field will be true if either the asset is explicitly listed in the partner's catalog, or if the partner can handle any asset (`partnerCanHandleAnyAsset=true`). Use this endpoint before creating TRMs to verify that the transaction's asset is supported, retrieve the correct asset identifiers and formats required by the partner, or understand asset-specific requirements for compliance messaging.

**Endpoint:**

```http theme={"system"}
GET /v1/screening/trlink/customers/integration/:customerIntegrationId/assets/:assetId
```

**Path Parameters:**

* `customerIntegrationId` (string, UUID) - The legal entity integration ID
* `assetId` (string) - The Fireblocks asset ID (e.g., "ETH", "BTC", "USDC\_ETH")

**Response (200):**

```typescript theme={"system"}
{
  fireblocksAsset: {
    id: string;                       // Fireblocks asset ID
    name?: string;                    // Asset display name
    type?: string;                    // Asset type
    contractAddress?: string;         // Contract address for tokens
    nativeAsset?: string;             // Native blockchain asset
    decimals?: number;                // Decimal precision
    issuerAddress?: string;           // issuer address (used on SOL, and some other blockchains) 
  };
  partnerResponse: {
    // Raw response from partner API with partner-specific format
    // Structure varies by partner
  };
  partnerCanHandleAnyAsset: boolean;  // Whether partner supports unlisted assets
  note: string;                       // Support capability note
  supported: boolean;                 // Whether asset is supported (true if in catalog OR partner handles any asset)
}
```

**SDK Example:**

```typescript theme={"system"}
const customerIntegrationId = "87654321-4321-4321-4321-123456789abc";

// Check if ETH is supported
const { data: ethAsset } = await fireblocks.trLink.getTRLinkSupportedAsset(
  customerIntegrationId,
  "ETH"
);

console.log(`Asset: ${ethAsset.fireblocksAsset.name} (${ethAsset.fireblocksAsset.id})`);
console.log(`Supported: ${ethAsset.supported}`);
console.log(`Partner can handle any asset: ${ethAsset.partnerCanHandleAnyAsset}`);
console.log(`Note: ${ethAsset.note}`);

if (ethAsset.supported) {
  console.log('\nAsset details:');
  console.log(`  Type: ${ethAsset.fireblocksAsset.type}`);
  console.log(`  Decimals: ${ethAsset.fireblocksAsset.decimals}`);
  if (ethAsset.fireblocksAsset.contractAddress) {
    console.log(`  Contract: ${ethAsset.fireblocksAsset.contractAddress}`);
  }

  // Asset is supported, safe to create TRM
  console.log('\nThis asset can be used for travel rule messages.');
} else {
  console.warn('\nWarning: Asset not supported by this partner.');
  console.warn('Choose a different partner or use a supported asset.');
}

// Check a custom token
const { data: customToken } = await fireblocks.trLink.getTRLinkSupportedAsset(
  customerIntegrationId,
  "CUSTOM_TOKEN_ETH"
);

if (customToken.supported) {
  console.log(`\nCustom token ${customToken.fireblocksAsset.id} is supported.`);
} else if (customToken.partnerCanHandleAnyAsset) {
  console.log(`\nCustom token not in catalog, but partner accepts any asset.`);
} else {
  console.log(`\nCustom token not supported by this partner.`);
}
```

### Partner Operations

Partner operations provide access to the catalog of available TRP partners that can be integrated with legal entities. Partners represent different TRP networks, such as Sumsub, each offering varying capabilities, geographic coverage, and supported jurisdictions. These endpoints help discover available partners and their characteristics, enabling informed decisions about which TRP to integrate for specific compliance requirements.

#### Get All Partners

Retrieves the complete catalog of TRP partners available for integration. Each partner entry includes identifying information (`ident`, `name`), a description of their services and network coverage, their API base URL, active status, and whether they're in test or production mode.

Use this endpoint during initial setup to discover available TRPs, present partner selection options to administrators, or filter partners based on environment (test vs. production). The `isTest` field helps distinguish between sandbox/testing partners and production-ready partners. Only active partners should be used for new integrations.

**Endpoint:**

```http theme={"system"}
GET /v1/screening/trlink/partners
```

**Response (200):**

```typescript theme={"system"}
Array<{
  ident: string;
  name: string;
  description: string;
  baseUrl: string;
  active: boolean;
  isTest: boolean;
}>
```

**SDK Example:**

```typescript theme={"system"}
const { data: partners } = await fireblocks.trLink.getTRLinkPartners();

console.log('Available Travel Rule Partners:');
partners.forEach(partner => {
  console.log(`- ${partner.name} (${partner.ident})`);
  console.log(`  Description: ${partner.description}`);
  console.log(`  Active: ${partner.active}`);
  console.log(`  Test Environment: ${partner.isTest}`);
  console.log('');
});

// Filter for production partners
const prodPartners = partners.filter(p => p.active && !p.isTest);
console.log(`Production partners: ${prodPartners.length}`);
```

## Error Responses

All endpoints may return the following error responses:

### 400 Bad Request

```typescript theme={"system"}
{
  message: string;
  code: number;     // e.g., 2120
}
```

### 401 Unauthorized

Returned when JWT authentication fails or API key is invalid.

### 404 Not Found

Returned when a requested resource (customer, integration, TRM, VASP) is not found.

### 500 Internal Server Error

```typescript theme={"system"}
{
  message: string;
  code: number;     // e.g., 2125
}
```

## Transaction Submission

Submit transactions for TRSupport screening using the standard Fireblocks transaction API:

```javascript theme={"system"}
const transaction = {
    assetId: 'BTC',
    source: {
        type: 'VAULT_ACCOUNT',
        id: '0'
    },
    destination: {
        type: 'ONE_TIME_ADDRESS',
        oneTimeAddress: {
            address: 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh'
        }
    },
    amount: '5000',
    note: 'TRSupport screened transaction',
    travelRuleMessageId: 'sumsub:12345'
    // TRSupport will process based on your configured policies
};

const response = await fireblocks.createTransaction(transaction);
```

### Multi-Destination Transactions

For transactions with multiple destinations:

```javascript theme={"system"}
const multiDestTransaction = {
    assetId: 'BTC',
    source: {
        type: 'VAULT_ACCOUNT',
        id: '0'
    },
    destinations: [
        {
            destination: {
                type: 'VAULT_ACCOUNT',
                id: '1'
            },
            amount: '2500',
            travelRuleMessageId: 'sumsub:qwerty'
        },
        {
            destination: {
                type: 'ONE_TIME_ADDRESS',
                oneTimeAddress: {
                    address: 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh'
                }
            },
            amount: '3000',
            travelRuleMessageId: 'sumsub:12345'
        },
    ],
    note: 'Multi-destination TRSupport transaction'
};

const response = await fireblocks.createTransaction(multiDestTransaction);
```

## Result Data Structure

### TRSupport Result Object

TRSupport returns comprehensive screening results:

```typescript theme={"system"}
interface TRSupportResult {
    // Core compliance information
    verdict: 'ACCEPT' | 'REJECT' | 'ALERT' | 'WAIT';
    status: 'completed' | 'pending' | 'bypassed' | 'failed';
    
    // Policy context
    bypassReason?: 'POLICY' | 'UNSUPPORTED_ASSET' | 'UNSUPPORTED_ROUTE';
    appliedPolicies: {
        preScreening?: PolicyRule;
        missingTRM?: PolicyRule;
        postScreening?: PolicyRule;
    };
    
    // Multi-destination intelligence
    trSupportDestinations?: TRSupportDestinationResult[];
    
    // Registration status
    trsupportRegistration?: {
        status: string;
        success: boolean;
        timestamp: number;
    };
    
    // Provider information
    provider?: string;
    trmStatus?: 'ACCEPTED' | 'REJECTED' | 'PENDING' | 'FAILED';
    
    // Metadata
    processingTime: number;
    timestamp: number;
}
```

### Per-Destination Results

For multi-destination transactions:

```typescript theme={"system"}
interface TRSupportDestinationResult {
    destRecordId: string;
    destAddress: string;
    timestamp: number;
    status: 'COMPLETED' | 'PENDING' | 'FAILED';
    verdict: 'ACCEPT' | 'REJECT' | 'ALERT' | 'WAIT';
    provider?: string;
    bypassReason?: string;
}
```

## Policy Configuration

### Screening Policy Rules

Configure which transactions require screening:

```typescript theme={"system"}
interface PreScreeningRule {
    // Matching criteria
    customerId?: string;
    direction?: 'inbound' | 'outbound';
    asset?: string;
    amount?: {
        range?: {
            min?: number;
            max?: number;
        };
        currency: 'USD' | 'NATIVE';
    };
    sourceType?: string;
    destType?: string;
    
    // Required action
    action: 'SCREEN' | 'PASS';
}
```

### Missing TRM Policy Rules

Configure timeout behaviors:

```typescript theme={"system"}
interface MissingTRMRule {
    // Matching criteria (same as screening)
    // Plus timing constraints
    validBefore?: number;  // seconds
    validAfter?: number;   // seconds
    
    // Required action
    action: 'WAIT' | 'ACCEPT' | 'REJECT';
}
```

### Post-screening Policy Rules

Configure responses to screening results:

```typescript theme={"system"}
interface PostScreeningRule {
    // Matching criteria (same as screening)
    // Plus TRM status
    trmStatus?: 'ACCEPTED' | 'REJECTED' | 'PENDING' | 'FAILED';
    
    // Timing constraints
    validBefore?: number;
    validAfter?: number;
    
    // Required action
    action: 'ACCEPT' | 'REJECT' | 'ALERT' | 'WAIT';
}
```

## Implementation Patterns

### Pattern 1: Basic Integration

```javascript theme={"system"}
class TRSupportIntegration {
    constructor(fireblocks) {
        this.fireblocks = fireblocks;
    }
    
    async submitTransaction(txData) {
        try {
            // Create transaction - TRSupport policies apply automatically
            const result = await this.fireblocks.createTransaction(txData);
            
            // Check screening result
            if (result.trsupportResult) {
                return this.handleTRSupportResult(result.trsupportResult);
            }
            
            return result;
        } catch (error) {
            console.error('Transaction failed:', error);
            throw error;
        }
    }
    
    handleTRSupportResult(trsupportResult) {
        switch (trsupportResult.verdict) {
            case 'ACCEPT':
                console.log('Transaction approved');
                break;
            case 'REJECT':
                console.log('Transaction blocked by policy');
                break;
            case 'ALERT':
                console.log('Transaction approved with monitoring');
                this.triggerAlert(trsupportResult);
                break;
            case 'WAIT':
                console.log('Waiting for Travel Rule data');
                this.scheduleRecheck(trsupportResult);
                break;
        }
        return trsupportResult;
    }
}
```

### Pattern 2: Multi-Destination Handling

```javascript theme={"system"}
class MultiDestinationHandler {
    async processMultiDestination(txData) {
        const result = await this.fireblocks.createTransaction(txData);
        
        if (result.trsupportResult?.trSupportDestinations) {
            // Analyze per-destination results
            const destinations = result.trsupportResult.trSupportDestinations;
            
            destinations.forEach(dest => {
                console.log(`Destination ${dest.destAddress}:`);
                console.log(`  Verdict: ${dest.verdict}`);
                console.log(`  Status: ${dest.status}`);
                
                if (dest.bypassReason) {
                    console.log(`  Bypassed: ${dest.bypassReason}`);
                }
            });
            
            // Overall transaction verdict
            console.log(`Transaction verdict: ${result.trsupportResult.verdict}`);
        }
        
        return result;
    }
}
```

### Pattern 3: Monitoring Integration

```javascript theme={"system"}
class TRSupportMonitoring {
    async monitorTransaction(txId) {
        const tx = await this.fireblocks.getTransaction(txId);
        
        if (tx.trsupportResult) {
            // Track metrics
            this.metrics.record({
                verdict: tx.trsupportResult.verdict,
                processingTime: tx.trsupportResult.processingTime,
                provider: tx.trsupportResult.provider,
                policyBypassed: !!tx.trsupportResult.bypassReason
            });
            
            // Monitor registration health
            if (tx.trsupportResult.trsupportRegistration) {
                this.checkProviderHealth(tx.trsupportResult.trsupportRegistration);
            }
        }
        
        return tx;
    }
    
    checkProviderHealth(registration) {
        if (!registration.success) {
            console.warn('Provider registration issue detected');
            // Alert operations team
        }
    }
}
```

## Testing and Validation

### Test Scenarios

#### Policy Bypass Testing

```javascript theme={"system"}
// Test internal transfer bypass
const internalTransfer = {
    source: { type: 'VAULT_ACCOUNT', id: '0' },
    destination: { type: 'VAULT_ACCOUNT', id: '1' },
    amount: '1000',
    assetId: 'BTC'
};
// Should bypass if configured
```

#### Threshold Testing

```javascript theme={"system"}
// Test amount thresholds
const belowThreshold = { amount: '2999', ... };  // Should bypass
const aboveThreshold = { amount: '3001', ... };  // Should screen
```

#### Multi-Destination Testing

```javascript theme={"system"}
// Test worst-result-wins logic
const mixedDestinations = {
    destinations: [
        { /* internal - should accept */ },
        { /* trusted - should accept */ },
        { /* unknown - should reject */ }
    ]
};
// Overall should reject
```

### Using Test Networks

Test with testnet assets:

* `BTC_TEST`
* `ETH_TEST5`
* `XRP_TEST`

## Error Handling

### Common Error Scenarios

```javascript theme={"system"}
class TRSupportErrorHandler {
    handleError(error) {
        if (error.code === 'TRSUPPORT_POLICY_REJECTION') {
            // Transaction blocked by policy
            return { action: 'blocked', reason: error.message };
        }
        
        if (error.code === 'TRSUPPORT_TIMEOUT') {
            // Processing timeout exceeded
            return { action: 'timeout', fallback: 'accept' };
        }
        
        if (error.code === 'PROVIDER_UNAVAILABLE') {
            // Provider connectivity issue
            return { action: 'failover', fallback: 'business_continuity' };
        }
        
        throw error;
    }
}
```

## Performance Considerations

### Processing Times

* **Policy Bypass**: \< 1 second
* **Standard Screening**: 2-10 seconds
* **Multi-Destination**: 30+ seconds
* **Extended Wait**: Hours to days (configurable)

### Optimization Tips

* **Use Bypass Rules**: Configure `PASS` actions for clear exemptions
* **Optimize Rule Order**: Most specific rules first
* **Limit Complex Matching**: Minimize multi-field rules
* **Cache Policy Results**: Store bypass decisions when applicable

## Support Resources

* **API Documentation**: Full API reference at docs.fireblocks.com
* **Policy Examples**: See Help Centre articles for configuration examples
* **Technical Support**: Contact [support@fireblocks.com](mailto:support@fireblocks.com)
* **Customer Success**: Reach out to your [Customer Success Manager](https://support.fireblocks.io/hc/en-us/requests/new?ticket_form_id=6947882197532)

## Appendix: Status Codes and Enums

### TRSupport Verdicts

* `ACCEPT`: Transaction approved
* `REJECT`: Transaction blocked
* `ALERT`: Approved with monitoring
* `WAIT`: Awaiting additional data

### Processing Statuses

* `completed`: Final verdict reached
* `pending`: Still processing
* `bypassed`: Policy bypass applied
* `failed`: Technical failure

### TRM Statuses

* `ACCEPTED`: Provider approved
* `REJECTED`: Provider blocked
* `PENDING`: Awaiting provider response
* `FAILED`: Provider technical issue

<br />


# TypeScript SDK
Source: https://developers.fireblocks.com/reference/typescript-sdk



<Note>
  **Install the Fireblocks Documentation MCP first.** Whether you're using an AI assistant or not, this makes it easy to search, reference, and keep your Fireblocks work grounded in the official docs. The setup steps are in [Getting Started](/docs/quickstart).
</Note>

# Overview

A Typescript developer can use the Fireblocks API easily with the official TypeScript SDK:

[The Fireblocks TypeScript SDK.](https://github.com/fireblocks/ts-sdk)

In this guide, you'll set up the Fireblocks SDK and see an example of a basic API script to create a vault and retrieve its data.

Additionally if you are developing on EVM chains - you might be using some of the familiar libraries, such as `web3.js` or `ethers.js` - Fireblocks is well intergrated into these libraries as described in the [Ethereum Development](doc:ethereum-development).

# Using the Fireblocks SDK

## Install Node v16 or newer

The Fireblocks JavaScript SDK requires **Node v16 or newer**. You can check which version of Node you already have installed by running the following command.

`node -v`

[Learn how to install or update Node to a newer version.](https://nodejs.org/en/download/)

## Install fireblocks/ts-sdk

The Fireblocks TypeScript SDK is open-source and is hosted on GitHub.

* **Source code:** [GitHub](https://github.com/fireblocks/ts-sdk)
* **JavaScript Package:** [NPM](https://www.npmjs.com/package/@fireblocks/ts-sdk)

Installing the latest SDK is easy with `npm`:

`npm install @fireblocks/ts-sdk`

## Your First Fireblocks TypeScript code example!

Now that you're set up, run a quick check for the API. The examples below will show you how to initialize the Fireblocks SDK, create a new vault account, query Fireblocks to get the vault accounts list and create a basic transfer transaction.

> **Use the correct API Base URL**
>
> In the following script, make sure you're using the correct value for `baseUrl` for your environment:
>
> * For US Sandbox workspaces: `https://sandbox-api.fireblocks.io`
> * For US Mainnet or Testnet workspaces: `https://api.fireblocks.io`
> * For EU Mainnet or Testnet workspaces: `https://eu-api.fireblocks.io`
> * For EU2 Mainnet or Testnet workspaces: `https://eu2-api.fireblocks.io`
>
> [Learn more about workspace differences](doc:workspace-environments).

```typescript theme={"system"}
import { readFileSync } from 'fs';
import { Fireblocks, BasePath, TransferPeerPathType } from "@fireblocks/ts-sdk";

const FIREBLOCKS_API_SECRET_PATH = "./fireblocks_secret.key";

// Initialize a Fireblocks API instance with local variables
const fireblocks = new Fireblocks({
    apiKey: "my-api-key",
    basePath: BasePath.Sandbox, // or assign directly to "https://sandbox-api.fireblocks.io/v1";
    secretKey: readFileSync(FIREBLOCKS_API_SECRET_PATH, "utf8"),
});

// creating a new vault account
async function createVault() {
    try {
        const vault = await fireblocks.vaults.createVaultAccount({
            createVaultAccountRequest: {
                name: 'My First Vault Account',
                hiddenOnUI: false,
                autoFuel: false
            }
        });
        console.log(JSON.stringify(vault.data, null, 2))
    } catch (e) {
        console.log(e);
    }
}

//retrive vault accounts
async function getVaultPagedAccounts(limit: number) {
    try {
        const vaults = await fireblocks.vaults.getPagedVaultAccounts({
            limit
        });
        console.log(JSON.stringify(vaults.data, null, 2))
    } catch (e) {
        console.log(e);
    }
}

// create a transaction
async function createTransaction(assetId, amount, srcId, destId) {
    let payload = {
        assetId,
        amount,
        source: {
            type: TransferPeerPathType.VaultAccount,
            id: String(srcId)
        },
        destination: {
            type: TransferPeerPathType.VaultAccount,
            id: String(destId)
        },
        note: "Your first transaction!"
    };
    const result = await fireblocks.transactions.createTransaction({ transactionRequest: payload });
    console.log(JSON.stringify(result, null, 2));
}

// createVault()
// getVaultPagedAccounts(10)
// createTransaction("ETH_TEST5", "0.1", "0", "1")
```


# Upload Contract Template
Source: https://developers.fireblocks.com/reference/upload-contract-template



# Upload Contract Template

This guide explains how to use the `/v1/tokenization/templates` endpoint. This endpoint allows you to upload smart contract templates to your Fireblocks workspace, using the Fireblocks Tokenization API.

## What are Contract Templates?

Contract Templates are one pillar of the Fireblocks Tokenization, built to streamline the process of deploying smart contracts. They serve as reusable blueprints for smart contracts, allowing developers and organizations to standardize their contract deployments across various projects and use cases.

Contract Templates can be used to:

* Follow upgradable patterns, where the logic contracts (implementation) are deployed once, and proxy contracts pointing to the implementation are deployed on-demand.
* Create a library of reusable token utilities for different use cases.
* Deploy a set of contracts or an entire protocol by using the Factory pattern.

***

## Prerequisites

Before using this endpoint, ensure you have:

1. Compiled your contract's code (e.g. Solidity) into bytecode (required)
2. Generated ABI (Application Binary Interface) from the compilation process (required)
3. Written NatSpec comments in your contract (optional, but recommended for better documentation)

***

## Example: Uploading a Counter Contract Template

Let's walk through uploading a simple `Counter` contract template.

### 1. Contract Code

Here's a simple Counter contract:

```solidity theme={"system"}
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.13;

/// @title A simple Counter contract
/// @notice You can use this contract to increment, set and get a counter value
contract Counter {
    uint256 private count;

    function setNumber(uint256 newNumber) public {
        count = newNumber;
    }

    /// @notice Increment the counter by 1
    function increment() public {
        count++;
    }

    /// @notice Get the current counter value
    /// @return The current count
    function getCount() public view returns (uint256) {
        return count;
    }
}
```

### 2. Bytecode

After compilation, you'll get the bytecode. Depending on the tool/framework being used (e.g. Foundry, Hardhat, solc), you may find the bytecode in different location, and in a different property inside the artifact object.

* [Foundry](https://book.getfoundry.sh/reference/forge/forge-build): Saves the contract [artifacts](https://book.getfoundry.sh/reference/forge/forge-build?highlight=artifact#artifacts) in `out/` directory.
* [Hardhat](https://hardhat.org/hardhat-runner/docs/guides/compile-contracts#artifacts): Saves the contract [artifacts](https://hardhat.org/hardhat-runner/docs/advanced/artifacts) in the `artifacts/` directory.

  For brevity, we'll use a placeholder variable :

```text theme={"system"}
0x60806040...   => artifact.bytecode
```

### 3. ABI

The ABI is also part of the compilation artifact. For the `Counter` contract it would look like this:

```json theme={"system"}
[
	{
		"type": "function",
		"name": "getCount",
		"inputs": [],
		"outputs": [{ "name": "", "type": "uint256", "internalType": "uint256" }],
		"stateMutability": "view"
	},
	{
		"type": "function",
		"name": "increment",
		"inputs": [],
		"outputs": [],
		"stateMutability": "nonpayable"
	},
	{
		"type": "function",
		"name": "setNumber",
		"inputs": [{ "name": "newNumber", "type": "uint256", "internalType": "uint256" }],
		"outputs": [],
		"stateMutability": "nonpayable"
	}
]
```

For convenience, we'll use a placeholder variable to represent the JSON ABI above:

```javascript theme={"system"}
artifact.abi;
```

### 4. Uploading the Contract Template

Here's a TypeScript example of how to upload this contract template:

```javascript theme={"system"}
import {
	ContractTemplateDto,
	ContractUploadRequest,
	ContractUploadRequestTypeEnum,
	Fireblocks,
	FireblocksResponse,
} from '@fireblocks/ts-sdk';

async function uploadContractTemplate() {
	const privateKey = '...'; // Your Fireblocks API private key
	const apiKey = '...'; // Your Fireblocks API key

	const fireblocksSdk = new Fireblocks({
		apiKey,
		secretKey: privateKey,
	});

	const template: ContractUploadRequest = {
		name: 'Simple Counter',
		description: 'A basic counter contract for demonstration',
		longDescription:
			"This contract allows incrementing a counter and retrieving its current value. It's a simple example of state management in Solidity.",
		bytecode: artifact.bytecode.object,
		sourcecode: '// SPDX-License-Identifier: MIT\npragma solidity ^0.8.13;\n\ncontract Counter {...}', // Optional: full source code
		type: ContractUploadRequestTypeEnum.TokenUtility,
		abi: artifact.abi,
		attributes: {
			useCases: ['Demo', 'Education'],
			standards: ['None'],
			auditor: {
				name: 'N/A',
				imageURL: '',
				link: '',
			},
		},
		docs: {
			details: 'A basic counter contract for demonstration purposes.',
			kind: 'user',
			version: 1,
			methods: {
				'increment()': {
					details: 'Increments the counter by 1',
				},
				'getCount()': {
					details: 'Returns the current counter value',
					returns: { '': 'The current count as a uint256' },
				},
			},
		},
	};

	try {
		const response: FireblocksResponse<ContractTemplateDto> = await sdk.contractTemplates.uploadContractTemplate({
			contractUploadRequest: template,
		});
		console.log('Template uploaded successfully. Template ID:', response.data.id);
		return response.data.id;
	} catch (error) {
		console.error('Error uploading template:', error);
	}
}

uploadContractTemplate().catch(error => {
	console.error(error);
	process.exitCode = 1;
});
```

### 5. Viewing the Uploaded Template

After uploading, you can retrieve the template using its ID:

```javascript theme={"system"}
async function getContractTemplate(templateId: string) {
	try {
		const response: FireblocksResponse<ContractTemplateDto> =
			await fireblocksSdk.contractTemplates.getContractTemplateById({
				contractTemplateId: templateId,
			});
		console.log('Retrieved template:', response.data);
	} catch (error) {
		console.error('Error retrieving template:', error);
	}
}
```

***

## Endpoint Model

### Contract Template Type

The `type` field in the template is crucial:

* Use `FUNGIBLE_TOKEN` for ERC-20 tokens
* Use `NON_FUNGIBLE_TOKEN` for ERC-721 or ERC-1155 tokens
* Use `TOKEN_UTILITY` for everything else, including generic smart contracts like our Counter example

### Documentation Field

The `docs` field is used to populate "tooltips" for constructor/initialization parameters at deploy time.

This is an example of what the tooltips look like in the Fireblocks Console:

<img alt="" />

These tooltips provide valuable context and guidance during the deployment process. In some cases, the user deploying a contract from this template are not those who created the contract. As a template publisher, you can improve the user experience and reducing potential errors by providing a comprehensive `docs` field.

***

## Gotchas and Tips

1. Ensure your bytecode is prefixed with "0x" when submitting.
2. The ABI must be a valid JSON array of function descriptions.
3. NatSpec comments in your Solidity code can be used to inform the `docs` field.
4. The `attributes` field is optional but highly recommended for better categorization and searchability in the template library.

***

## Further Reading

For more detailed information on API parameters and responses, including examples for using plain HTTP requests or in other programming languages, please have a look at the [Fireblocks API Reference](/reference/getcontracttemplates).


# Using the Communal Test Co-signer
Source: https://developers.fireblocks.com/reference/use-communal-cosigner



> 1. **IMPORTANT**: The Communal Callback handler must NOT be used for performance testing.
> 2. Due to legal regulations, Fireblocks can not take custodial responsibility for Mainnet workspaces. Therefore, this option is available only to Testnet workspaces.

## Overview

Setting up a new Co-signer from scratch can be time-consuming. To accelerate development and prepare your workspace for automation and API-driven workflows, Fireblocks offers the option to use a Communal Test Co-signer before configuring your own.

The Communal Test Co-signer is hosted and managed by Fireblocks and serves all customers with Testnet workspaces. Any workspace owner can approve pairing API users with it, generate MPC key share sets, and use it to sign transactions.

When you start testing and verifying your signing or approval automation workflows, we recommend setting up your self-hosted API Co-signer instance and replacing the Communal Test Co-signer as soon as your instance is ready. To stop using the Communal Test Co-signer, unpair or delete the API users that were paired with it.

***

## Connecting to the Communal Test Co-signer

To use the Fireblocks Communal API Co-Signer, create a new API user using the Console in a testnet workspace and select the option to connect it with the Communal Co-signer.

Selecting a user role with [Signer](https://support.fireblocks.io/hc/en-us/articles/360012832959-User-roles#h_01H9P4D2W1436XZYXESPTQE2J7) or [Admin](https://support.fireblocks.io/hc/en-us/articles/360012832959-User-roles#h_01H9P4D2W1436XZYXESPTQE2J7) privileges will allow you to test transaction signing and approving workspace changes. If you only want to test approving workspace configuration changes, you can select the [Non-Signing Admin](https://support.fireblocks.io/hc/en-us/articles/360012832959-User-roles#h_01H9P4D2W1436XZYXESPTQE2J7) user role.

In a [Sandbox workspace](https://support.fireblocks.io/hc/en-us/articles/360020612820-Workspace-types), each API user is automatically paired with the Fireblocks Communal Test Co-signer. This co-signer manages the MPC key shares for all API users in the Sandbox environment across all workspaces.

***

## Testing a Callback Handler with the Communal Test Co-Signer

* [Setup a Co-signer Callback Handler](/reference/api-cosigner-setup-callback-handler) and configure it to use a public key for JWT-encoded message authentication.
* [Submit a request to Fireblocks support](https://support.fireblocks.io/hc/en-us/requests/new?ticket_form_id=5129187878556\&tf_5465594782876=issue_test_the_fireblocks_communal_api__cosigner_cosigner_setup_and_configuration__what_are_you_trying_to_do___test_the_fireblocks_communal_api_cosigner) to implement a Callback Handler for use with the Communal Test Co-Signer and provide the following details:
  * The workspace name
  * The API user's ID (API key)
  * The Callback Handler's URL (HTTPS)
  * The Callback Handler's public key
* Once Fireblocks Support sets up your Callback Handler, you can integrate and test it.

***

## Known limitations

For UTXO transactions, such as `BTC_TEST` in testnet workspaces, the Fireblocks Communal Test Co-Signer supports a maximum of 50 transaction inputs. The first 50 inputs from the transaction source vault account are selected automatically based on the requested amount.

For all other workspaces and signing configurations, up to 250 transaction inputs are supported for Bitcoin transactions.

If a transaction signed by the Fireblocks Communal Test Co-Signer fails because it requires more than 50 inputs, the transaction substatus will be `INTERNAL_ERROR`.


# User Object
Source: https://developers.fireblocks.com/reference/user-object



## GetUsersResponse

| Parameter | Type    | Description                                                                                                                                            |
| --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| id        | string  | User ID on the Fireblocks platform                                                                                                                     |
| firstName | string  | First name                                                                                                                                             |
| lastName  | string  | Last name                                                                                                                                              |
| role      | string  | The role of the user in the workspace; one of the options as described [here](https://support.fireblocks.io/hc/en-us/articles/360012832959-User-Roles) |
| email     | string  | The email of the user                                                                                                                                  |
| enabled   | boolean | The status of the user in the workspace                                                                                                                |


# Validate ETH raw transactions
Source: https://developers.fireblocks.com/reference/validate-eth-raw-transactions



Fireblocks allows you to verify ETH transactions before they are signed by the API Co-signer. You can configure your workspace to receive the raw data of the ETH transaction as part of the payload sent to the Callback Handler.

In this article, we are going to cover how to verify Ethereum raw transactions.

## ETH - Callback Handler payload structure

First, let’s take a look at the payload that is sent from the Co-signer to the Callback Handler (a detailed spec can be found [here](/reference/approve-transactions)):

```json theme={"system"}
{
  "txId": "9c794cee-7e27-46c9-9e9a-ed68295ff06b",
  "operation": "TRANSFER",
  "sourceType": "VAULT",
  "sourceId": "0",
  "destType": "VAULT",
  "destId": "1",
  "asset": "ETH",
  "amount": 0.01,
  "amountStr": "0.010000000000000000",
  "requestedAmount": 0.01,
  "requestedAmountStr": "0.01",
  "fee": "0.000597803762241000",
  "destAddressType": "WHITELISTED",
  "destAddress": "0x5dC69B1Fbb13Bafd09af88a782F0F285772Ad5f8",
  "destinations": [
    {
      "amountNative": 0.01,
      "amountNativeStr": "0.01",
      "amountUSD": 18.74292937,
      "dstAddressType": "WHITELISTED",
      "dstId": "1",
      "dstWalletId": "",
      "dstName": "Network Deposits",
      "dstSubType": "",
      "dstType": "VAULT",
      "displayDstAddress": "0x5dC69B1Fbb13Bafd09af88a782F0F285772Ad5f8",
      "action": "ALLOW",
      "actionInfo": {
        "capturedRuleNum": 5,
        "rulesSnapshotId": 8164,
        "byGlobalPolicy": false,
        "byRule": true,
        "capturedRule": "{\"type\":\"TRANSFER\",\"transactionType\":\"TRANSFER\",\"asset\":\"*\",\"amount\":0,\"operators\":{\"wildcard\":\"*\"},\"applyForApprove\":true,\"action\":\"ALLOW\",\"src\":{\"ids\":[[\"*\"]]},\"dst\":{\"ids\":[[\"*\"]]},\"dstAddressType\":\"*\",\"amountCurrency\":\"USD\",\"amountScope\":\"SINGLE_TX\",\"periodSec\":0}"
      }
    }
  ],
  "rawTx": [
    {
      "keyDerivationPath": "[ 44, 60, 0, 0, 0 ]",
      "rawTx": "02ef0104843b9aca008506a0c1987d825208945dc69b1fbb13bafd09af88a782f0f285772ad5f8872386f26fc1000080c0",
      "payload": "77b4e74099ce90c08503c0e0bb6e672dbe1c5e3e127ce333bf22eb581cd3f6ce"
    }
  ],
  "players": [
    "21926ecc-4a8a-4614-bbac-7c591aa7efdd",
    "27900737-46f6-4097-a169-d0ff45649ed5",
    "f89cac50-c656-4e74-879f-041aff8d01b5"
  ],
  "requestId": "9c794cee-7e27-46c9-9e9a-ed68295ff06b"
}
```

The payload above contains a lot of information but we will be focusing only on some parts of it:

1. Amount (`destinations[0].amountNative`)
2. Destination Address (`destinations[0].displayDstAddress`)
3. Raw Transaction array (`rawTx`)

   RLP encoded payload (`rawTx.rawTx`)
   The hash of the raw transaction (`rawTx.payload`)

Note that the RLP encoded payload (`rawTx.rawTx`) is the actual payload that you are signing on, or to be precise, the signature is done over the keccak256 hash of the RLP encoded payload, which is exactly the hash provided in the `rawTx.payload` property.

***

## Creating the Callback Handler application

Before diving into the verification of the ETH transaction process, let’s start with spinning up our Callback Handler server. In this example I am going to use the Express.js framework:

Install Express:
`npm i express`

We will also need some additional packages to be installed:
`npm i jsonwebtoken fs body-parser @ethereumjs/tx`

Initiating the app:

```javascript theme={"system"}
const port = 8080;
const app = express();
```

Let’s set our middleware (we are using body-parser here to access the raw body sent over to our POST endpoint that we will add shortly):

```javascript theme={"system"}
const bodyParser = require("body-parser");

const app = express();
app.use(bodyParser.urlencoded({ extended: true }));
app.use(bodyParser.json())
app.use( (req) => {
    req.rawBody = "";
    req.setEncoding("utf8");
    req.on("data", (chunk) => {
      req.rawBody += chunk;
    });
    req.on("end", () => {
      req.next();
    });
  }
);
```

Defining our route for the `/v2/tx_sign_request` endpoint:

```javascript theme={"system"}
app.post("/v2/tx_sign_request", (req, res) => {
	console.log("The raw body of the HTTP request:", req.rawBody)
}
```

To understand how the `rawBody` of the HTTP request is obtained, let's break down the process:

**Mutual Authentication via Signed JWTs:**

* The Fireblocks API Co-signer does not transmit the payload in plain text. Instead, it employs an authentication mechanism using signed JSON Web Tokens (JWTs) for secure communication.
* Each request sent by the Co-signer to the Callback Handler includes a signed JWT in the request body. This JWT is signed using the Co-signer application's private key.
* Similarly, any response from the Callback Handler to the Co-signer must also be signed using the Callback Handler's private key.

**Key Exchange Requirements:**

* To enable this mutual authentication, both the Callback Handler and the Co-signer must exchange their respective public keys.
* The Callback Handler should have access to:
  * Its own private key for signing responses.
  * The Co-signer's public key to verify incoming requests.
* The Co-signer requires:
  * Its private key for signing requests.
  * The Callback Handler's public key to validate responses.

**Pre-requisite:**

It is assumed that you have completed the authentication setup and have access to the required keys:

* Callback Handler's private and public keys.
* Co-signer's public key.

By ensuring these keys are in place, the Callback Handler can securely verify and respond to requests while maintaining the integrity of communication with the Co-signer.

Loading the Callback Handler’s private key and the Co-signer's public key:

```javascript theme={"system"}
const fs = require("fs");

// Read the callback handler private key
const privateKey = fs.readFileSync("callback_private.pem");

// Read the cosigner public key (you can get it by running: ./cosigner print-public-key on the cosigner machine)
const cosignerPubKey = fs.readFileSync("cosigner_public.pem");
```

In our example, the raw body of the HTTP request will actually look like this:

```text theme={"system"}
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJ0eElkIjoiNDhmNjg3MWMtMDQ2Ny00YjU2LThjNDQtNDI2ZjNkNjQ4N2Y1Iiwib3BlcmF0aW9uIjoiVFJBTlNGRVIiLCJzb3VyY2VUeXBlIjoiVkFVTFQiLCJzb3VyY2VJZCI6IjAiLCJkZXN0VHlwZSI6IlZBVUxUIiwiZGVzdElkIjoiMSIsImFzc2V0IjoiRVRIIiwiYW1vdW50IjowLjAxMDAwMDAwLCJhbW91bnRTdHIiOiIwLjAxMDAwMDAwMDAwMDAwMDAwMCIsInJlcXVlc3RlZEFtb3VudCI6MC4wMTAwMDAwMCwicmVxdWVzdGVkQW1vdW50U3RyIjoiMC4wMSIsImZlZSI6IjAuMDAwNTg0MjYxNjA3NjU3MDAwIiwiZGVzdEFkZHJlc3NUeXBlIjoiV0hJVEVMSVNURUQiLCJkZXN0QWRkcmVzcyI6IjB4NWRDNjlCMUZiYjEzQmFmZDA5YWY4OGE3ODJGMEYyODU3NzJBZDVmOCIsImRlc3RpbmF0aW9ucyI6W3siYW1vdW50TmF0aXZlIjowLjAxMDAwMDAwLCJhbW91bnROYXRpdmVTdHIiOiIwLjAxIiwiYW1vdW50VVNEIjoxOC43NDUwMTkzNiwiZHN0QWRkcmVzc1R5cGUiOiJXSElURUxJU1RFRCIsImRzdElkIjoiMSIsImRzdFdhbGxldElkIjoiIiwiZHN0TmFtZSI6Ik5ldHdvcmsgRGVwb3NpdHMiLCJkc3RTdWJUeXBlIjoiIiwiZHN0VHlwZSI6IlZBVUxUIiwiZGlzcGxheURzdEFkZHJlc3MiOiIweDVkQzY5QjFGYmIxM0JhZmQwOWFmODhhNzgyRjBGMjg1NzcyQWQ1ZjgiLCJhY3Rpb24iOiJBTExPVyIsImFjdGlvbkluZm8iOnsiY2FwdHVyZWRSdWxlTnVtIjo1LCJydWxlc1NuYXBzaG90SWQiOjgxNjQsImJ5R2xvYmFsUG9saWN5IjpmYWxzZSwiYnlSdWxlIjp0cnVlLCJjYXB0dXJlZFJ1bGUiOiJ7XCJ0eXBlXCI6XCJUUkFOU0ZFUlwiLFwidHJhbnNhY3Rpb25UeXBlXCI6XCJUUkFOU0ZFUlwiLFwiYXNzZXRcIjpcIipcIixcImFtb3VudFwiOjAsXCJvcGVyYXRvcnNcIjp7XCJ3aWxkY2FyZFwiOlwiKlwifSxcImFwcGx5Rm9yQXBwcm92ZVwiOnRydWUsXCJhY3Rpb25cIjpcIkFMTE9XXCIsXCJzcmNcIjp7XCJpZHNcIjpbW1wiKlwiXV19LFwiZHN0XCI6e1wiaWRzXCI6W1tcIipcIl1dfSxcImRzdEFkZHJlc3NUeXBlXCI6XCIqXCIsXCJhbW91bnRDdXJyZW5jeVwiOlwiVVNEXCIsXCJhbW91bnRTY29wZVwiOlwiU0lOR0xFX1RYXCIsXCJwZXJpb2RTZWNcIjowfSJ9fV0sInJhd1R4IjpbeyJrZXlEZXJpdmF0aW9uUGF0aCI6IlsgNDQsIDYwLCAwLCAwLCAwIF0iLCJyYXdUeCI6IjAyZWYwMTA0ODQzYjlhY2EwMDg1MDY3YTUxYmU4NTgyNTIwODk0NWRjNjliMWZiYjEzYmFmZDA5YWY4OGE3ODJmMGYyODU3NzJhZDVmODg3MjM4NmYyNmZjMTAwMDA4MGMwIiwicGF5bG9hZCI6IjZjYTE4YzQ3Y2NkOGRkNDdiYjBiMGIwYzczY2M1MjM3YmJmZjlkMGVhYWU0NjljYTY1YTY3MjMyOTY0M2JmZGEifV0sInBsYXllcnMiOlsiMjE5MjZlY2MtNGE4YS00NjE0LWJiYWMtN2M1OTFhYTdlZmRkIiwiMjc5MDA3MzctNDZmNi00MDk3LWExNjktZDBmZjQ1NjQ5ZWQ1IiwiZjg5Y2FjNTAtYzY1Ni00ZTc0LTg3OWYtMDQxYWZmOGQwMWI1Il0sInJlcXVlc3RJZCI6IjQ4ZjY4NzFjLTA0NjctNGI1Ni04YzQ0LTQyNmYzZDY0ODdmNSJ9.00000000000000000000000000000000000000000000000
```

> Note that the signature part of the JWT is obfuscated as a security best practice.

If you take this JWT and parse it in jwt.io - you’ll get the same clear text JSON payload as at the beginning of this guide.

***

## JWT verification

So what should we do with this JWT? We need to verify its signature by using the Co-Signer public key and we need to decode it to JSON:

```javascript theme={"system"}
const jwt = require("jsonwebtoken");
const bodyParser = require("body-parser");

const app = express();
app.use(bodyParser.urlencoded({ extended: true }));
app.use(bodyParser.json())
app.use( (req) => {
    req.rawBody = "";
    req.setEncoding("utf8");
    req.on("data", (chunk) => {
      req.rawBody += chunk;
    });
    req.on("end", () => {
      req.next();
    });
  }
);

app.post("/v2/tx_sign_request", (req, res) => {

	try {
		// jwt.verify returns the decoded payload on successful verification
        const tx = jwt.verify(req.rawBody, cosignerPubKey);
    } catch(e) {
	    console.error(e)
        res.sendStatus(401).send();
    }
}
```

***

## Building the ETH transaction object

So now we have set the authentication, and if the token is verified, we can actually move on to the transaction validation part.Let's define a new function, validateETHTransaction. It will get the plain text payload and will build an ETH transaction object from the RLP encoded hex:

```javascript theme={"system"}
const { FeeMarketEIP1559Transaction } = require('@ethereumjs/tx');

const validateETHTransaction = (payload) => {

  try {
    // Decode RLP
    const unsignedTx = FeeMarketEIP1559Transaction.fromSerializedTx(
    Buffer.from(
      payload.rawTx[0].rawTx,
      "hex"
    ))
  } catch(e) {
    console.log("Error:", e)
  }

}
```

Basically, we are taking the RLP-encoded hex and building the transaction object using the `FeeMarketEIP1559Transaction` class from @ethereumjs/tx.

If we print the unsignedTx object, we’ll get:

```json theme={"system"}
{
  "chainId": "0x1",
  "nonce": "0x4",
  "maxPriorityFeePerGas": "0x4d4ea640",
  "maxFeePerGas": "0x7c4b19ac5",
  "gasLimit": "0x5208",
  "to": "0x5dc69b1fbb13bafd09af88a782f0f285772ad5f8",
  "value": "0x2386f26fc10000",
  "data": "0x",
  "accessList": []
}
```

***

## Verifying the transaction parameters

Now we can actually check whether the destination and the amount in the decoded transaction match the JSON values of the payload:

```javascript theme={"system"}
const { FeeMarketEIP1559Transaction } = require('@ethereumjs/tx');

const validateETHTransaction = (payload) => {

  try {
    // Decode RLP
    const unsignedTx = FeeMarketEIP1559Transaction.fromSerializedTx(
      Buffer.from(
        payload.rawTx[0].rawTx,
        "hex"
      ))

    return (
      parseFloat(unsignedTx.value, 16) / 1e18 === payload.destinations[0].amountNative
      &&
      unsignedTx.to.toString("hex") === payload.destinations[0].displayDstAddress.toLowerCase()
    )

  } catch (e) {
    console.log("Error:", e)
  }

}
```

> Note that the address in the payload is in checksum format hence we need to lower case it

We can actually add one more check - verify that the hash of the unsignedTx matches the provided hash in the payload:

```javascript theme={"system"}
const { FeeMarketEIP1559Transaction } = require('@ethereumjs/tx');

const validateETHTransaction = (payload) => {

  try {
    // Decode RLP
    const unsignedTx = FeeMarketEIP1559Transaction.fromSerializedTx(
      Buffer.from(
        payload.rawTx[0].rawTx,
        "hex"
      ))

    return (
      parseFloat(unsignedTx.value, 16) / 1e18 === payload.destinations[0].amountNative
      &&
      unsignedTx.to.toString("hex") === payload.destinations[0].displayDstAddress.toLowerCase()
      &&
      unsignedTx.getMessageToSign(true).toString("hex") == providedHash
    )

  } catch (e) {
    console.log("Error:", e)
  }

}
```

The code above extracts the hash from the payload provided by the Co-signer and compares it with the result of `unsignedTx.getMessageToSign(true)`. This method returns the hash of the unsigned transaction that is expected to be signed.

***

## Callback Handler response

The response from the Callback Handler should be in the following format (signed with `RS256` algorithm by using the Callback Handler's private key):

```json theme={"system"}
{
	action: 'APPROVE' OR 'REJECT' OR 'IGNORE',
	requestId: 'The unique identifier of the call that was received in the approval request',
	rejectionReason: (Optional) 'Free text of the rejection reason for logging purposes'
}
```

Let’s just add one more function that will generate the signed response that should be sent from the Callback Handler:

```javascript theme={"system"}
const generateSignedResponse = (action) => {

    const signedRes = jwt.sign(
        action,
        privateKey,
        { algorithm: "RS256" }
    );

    return signedRes
}
```

***

## Piecing all the parts together

```javascript theme={"system"}
const fs = require("fs");
const express = require("express");
const jwt = require("jsonwebtoken");
const bodyParser = require("body-parser");
const { FeeMarketEIP1559Transaction } = require('@ethereumjs/tx');

// Read the callback handler private key
const privateKey = fs.readFileSync("private.pem");

// Read the cosigner public key (you can get it by running: ./cosigner print-public-key on the cosigner machine)
const cosignerPubKey = fs.readFileSync("cosigner_public.pem");

// Start express app and set middleware
const port = 8080;
const app = express();

const app = express();
app.use(bodyParser.urlencoded({ extended: true }));
app.use(bodyParser.json())
app.use( (req) => {
    req.rawBody = "";
    req.setEncoding("utf8");
    req.on("data", (chunk) => {
      req.rawBody += chunk;
    });
    req.on("end", () => {
      req.next();
    });
  }
);

// Generate JWT response
const generateSignedResponse = (action) => {

    const signedRes = jwt.sign(
        action,
        privateKey,
        { algorithm: "RS256" }
    );

    return signedRes
}

// Verify that the params of the rawTx match the payload
const validateETHTransaction = (payload) => {

  try {
    // Decode RLP
    const unsignedTx = FeeMarketEIP1559Transaction.fromSerializedTx(
      Buffer.from(
        payload.rawTx[0].rawTx,
        "hex"
      ))

    return (
      parseFloat(unsignedTx.value, 16) / 1e18 === payload.destinations[0].amountNative
      &&
      unsignedTx.to.toString("hex") === payload.destinations[0].displayDstAddress.toLowerCase()
      &&
      unsignedTx.getMessageToSign(true).toString("hex") == providedHash
    )

  } catch (e) {
    console.log("Error:", e)
  }

}

// Tx Sign Request endpoint
app.post("/v2/tx_sign_request", (req, res) => {

    try {
        let response;
        const tx = jwt.verify(req.rawBody, cosignerPubKey);
        if (validateETHTransaction(tx)) {
            response = generateSignedResponse({
                action: "APPROVE",
                requestId: tx.requestId
            })
       } else {
            response = generateSignedResponse({
                action: "REJECT",
                requestId: tx.requestId,
                rejectionReason: `Failed to validate ETH transaction`
           	})
       }

        res.status(200).send(response);

    } catch(e) {
        console.error(e)
        res.sendStatus(401).send();
    }
});

console.log(`Callback is running on http://localhost:${port}`)
app.listen(port);
```


# Travel Rule with Notabene - Validate Travel Rule
Source: https://developers.fireblocks.com/reference/validate-travel-rule



# Overview

> **Note**
>
> This guide contains links to Notabene API documentation, which is password protected. If you need help accessing it, contact your Customer Success Manager.

The Travel Rule states that Virtual Asset Service Providers (VASPs), which include businesses that exchange virtual assets, must provide additional data on the senders and recipients of certain transactions. Each jurisdiction decides which transactions must adhere to the Travel Rule and what data must be included.

The Fireblocks API allows you to send your transactions to Notabene to ensure they comply with the Travel Rule. After creating a key to encrypt personally identifiable information (PII) data included in the transactions, you use the Validation API to verify all the necessary data is included for the Travel Rule check. Once these API calls are set up, you can use the Fireblocks SDK or the Fireblocks API to submit your transactions for Travel Rule validation.

The following transaction routes in Fireblocks are not subject to Travel Rule screening:

* Gas Station to Vault
* Vault to Network Connection(s)
* Vault to Exchange
* Vault to Vault

# Before you begin

Before you can validate Travel Rule transactions, you must create a dedicated DID Key for encrypting customer PII data and add it to your Notabene VASP account. With this public-private keypair, you allow other VASPs to retrieve the public key and encrypt PII data to you.

You can create a new key pair using [@notabene/cli](https://www.npmjs.com/package/@notabene/cli) and then publishing it to the Notabene directory under the pii\_didkey field.

## Creating an encryption key

1. Install the Notabene CLI tool.
   1. Install the library globally using Yarn `yarn global add @notabene/cli` or NPM `npm i -g @notabene/cli`.
   2. Ensure the path to globally installed packages is in your \$PATH environment variable.
2. Generate an M2M token.
   1. Generate an M2M token for use with the Notabene Travel Rule gateway: `notabene auth:token`.
3. Create the encryption key.
   1. You can use the CLI to generate a key that can be used to encrypt PII information to be sent as part of a Travel Rule message: `notabene keys:create`.
   2. This generates a JSON object containing an [Ed25519](https://en.wikipedia.org/wiki/EdDSA) key and metadata which can be passed to the [Notabene SDK](https://gitlab.com/notabene/open-source/notabene-nodejs) when creating transactions to encrypt the PII.

```json theme={"system"}
{
  "did":"did:key:z6MkjwpTikNZkp********************************",
  "controllerKeyId":"519b59a6b7ebf128f6c6**********************",
  "keys":\[{"type":"Ed25519","kid":"519b59a6b7eb768****************************************",
  "publicKeyHex":"519b59a6b7ebf128f6c7********************************",
  "meta":{"algorithms":["Ed25519","EdDSA"]},
  "kms":"local",
  "privateKeyHex":"0d07d8acda928f98765e4a0b80013e2be369c29564419a**********************************************"}],
  "services":\[],
  "provider":"did:key"
}
```

## Adding the encryption key to your Notabene account

After creating your encryption key, you must add it to your Notabene VASP account. Send a PUT request to `/v1/screening/travel-rule/vasp/update` with your VASP DID Key and JSON DID Key.

```javascript theme={"system"}
    const result = await fireblocks.updateVasp({
        did: "did:ethr:0x2215002eabcdabcdabcdabcdabcdabcdabcdabcd",
        encryptionKey: "did:key:z6MkgtY4abcdabcdabcdabcdabcdabcdabcdabcdabcdabcd",
    } as any)
```

Be sure to replace the example above with your VASP DID and the encryption key you created in the previous step.

# Validation and sending Travel Rule transactions

Validating transactions ensures all the necessary information is included in the Travel Rule check. After you transaction has been validated, you can send the transaction to the counterparty.

The Travel Rule transaction flow consists of four steps:

1. Initial validation
2. Collecting additional data
3. Validating the full transaction
4. Sending the Travel Rule transaction

## Step 1: Initial validation

The Transaction Validate API call checks what beneficiary details are required by your jurisdiction and the beneficiary VASP’s jurisdiction. Since Travel Rule compliance is only required for transactions above a certain threshold, the Transaction Validate API call also checks whether or not the transaction meets the threshold and must comply with the Travel Rule. Travel Rule thresholds and required data are defined by the [jurisdictions](https://intercom.help/helpnotabene/en/collections/3648427-jurisdictional-requirements) of the VASPs involved.

This API works with a [customerToken](https://devx.notabene.id/docs/customertoken) and may be used from the front end of your application.

[Learn more about how the validation API works](https://devx.notabene.id/docs/validation-api).

### Example

```json theme={"system"}
{
  "transactionAsset": "BTC",
  "destination": "bc1qxy2kgdygjrsqtzq2n0yrf1234p83kkfjhx0wlh",
  "transactionAmount": "10",
  "originatorVASPdid": "did:ethr:0x44957e75d6ce4a5bf37aae117da86422c848f7c2",
  "originatorEqualsBeneficiary": false
}
```

### Response

```json theme={"system"}
{
    "isValid": false,
    "type": "NON_CUSTODIAL",
    "beneficiaryAddressType": "UNKNOWN",
    "addressSource": "UNKNOWN",
    "errors": [
        "beneficiaryNameMissing",
        "beneficiaryOwnershipProofMissing"
    ]
}
```

The response to this initial validation step tells us:

1. If the value of this transaction is above or below the Travel Rule threshold.
2. If the destination address was identified by blockchain analytics or your address book.

If the address was not automatically identified, search and select the correct VASP from Notabene’s directory by querying [Search API](https://devx.notabene.id/docs/search). You can search using the `/v1/screening/travel_rule/vasp?q=Fireblocks` API endpoint.

### Response

```json theme={"system"}
{
    "isValid": "true" or "false",
    "type": "BELOW_THRESHOLD" or "TRAVELRULE" or "NON_CUSTODIAL",
    "beneficiaryAddressType": "UNKNOWN" or "HOSTED" or "UNHOSTED",
    "addressSource": "ADDRESS_GRAPH" or "NAME_OF_BLOCKCHAIN_ANALYTICS",
    "beneficiaryVASPname": "VASP_NAME",
    "errors": "MISSING_FIELDS_REQUIRED_BY_YOUR_JURISDICTION"
    "warnings": "MISSING_FIELDS_REQUIRED_BY_COUNTERPARTY_JURISDICTION"
}
```

[Read the Notabene API documentation for more information on the responses to the Transaction Validate API call](https://devx.notabene.id/docs/validation-api#response).

If the transaction is below the threshold, you don’t need to collect data for the Travel Rule. Depending on the initial call response, the following scenarios can happen:

1. [Known VASP (address book)](https://devx.notabene.id/docs/validation-api#known-vasp-address-book)
2. [Known VASP (blockchain analytics)](https://devx.notabene.id/docs/validation-api#known-vasp-blockchain-analytics)
3. [Known VASP (manually selected)](https://devx.notabene.id/docs/validation-api#known-vasp-manually-selected)
4. [Unknown/unlisted VASP](https://devx.notabene.id/docs/validation-api#unknownunlisted-vasp)
5. [Unhosted wallet](https://devx.notabene.id/docs/validation-api#unhosted-wallet)

## Step 2: Collecting additional data

Once you perform the initial validation step to determine if the Travel Rule data requirements apply, you have two options to collect the necessary information listed in the errors array from step 1. You can use the Notabene widget or replicate the widget's functionality using API calls.

[Read the Notabene API documentation for more information on front-end data collection](https://devx.notabene.id/docs/validate-1).

## Step 3: Validating the full transaction

After reacting to the response of the initial Transaction Validate API call and collecting the necessary information about the beneficiary, you can perform a final request to confirm that you have all the data needed for the Travel Rule.

The Transaction Validate Full API call validates the beneficiary and the originator data included in your transaction. The originator data is the information about your organization and is static.

This API requires an [accessToken](https://devx.notabene.id/docs/auth0) and must be called from the back-end of your application.

[Learn more about how the validation API works](https://devx.notabene.id/docs/validation-api).

### Example

```json theme={"system"}
{
    "transactionAsset": "ETH",
    "destination": "bc1qxy2kgdygjrsqtzq2n0yrf1234p83kkfjhx0wlh",
    "transactionAmount": "10000000000000000000",
    "originatorVASPdid": "{{vaspDID}}",
    "originatorEqualsBeneficiary": false,
    "beneficiaryVASPdid": "did:ethr:0x47463999eb42dc2aaacb29624c512603221227a1",
    "beneficiaryName": "Bruce Wayne",
    "beneficiaryAccountNumber": "bc1qxy2kgdygjrsqtzq2n0yrf1234p83kkfjhx0wlh"
}
```

### Response

```json theme={"system"}
{
    "isValid": true,
    "type": "TRAVELRULE",
    "beneficiaryAddressType": "HOSTED",
    "addressSource": "ADDRESS_GRAPH",
    "beneficiaryVASPname": "Notabene VASP US"
}
```

If all the necessary information is included, you receive the response *isValid*=**true**.

## Step 4: Sending the Travel Rule transaction

Once the full transaction is validated, move the information used in the final validation request to the back-end, add information about your customer (the originator), and create the actual Travel Rule message using the Fireblocks API or the Fireblocks SDK.

If the outgoing transaction doesn’t contain a Travel Rule message, the transaction bypasses screening.

### Fireblocks API

First, encrypt the data for the transaction using the Notabene PII SDK. This encryption ensures the privacy and security of PII data during the transaction. The PII data should only be decrypted by authorized parties.

```python theme={"system"}
import PIIsdk, { PIIEncryptionMethod } from "@notabene/pii-sdk";
import { TransactionArguments, TravelRule, TravelRuleEncryptionOptions, TravelRuleOptions } from "./types";
import * as util from "util";

const requiredFields = [
    "baseURLPII",
    "audiencePII",
    "clientId",
    "clientSecret",
    "authURL",
    "jsonDidKey",
];

export class PIIEncryption {
    public toolset: PIIsdk;

    constructor(private readonly config: TravelRuleOptions) {
        this.config = config;
        const missingFields = requiredFields.filter(
            (field) => !(field in this.config)
        );

        if (missingFields.length > 0) {
            throw new Error(
                `Missing PII configuration fields: ${missingFields.join(", ")}`
            );
        }

        this.toolset = new PIIsdk({
            piiURL: config.baseURLPII,
            audience: config.audiencePII,
            clientId: config.clientId,
            clientSecret: config.clientSecret,
            authURL: config.authURL,
        });
    }

    async hybridEncode(transaction: TransactionArguments, travelRuleEncryptionOptions?: TravelRuleEncryptionOptions) {
        const { travelRuleMessage } = transaction;
        const pii = travelRuleMessage.pii || {
            originator: travelRuleMessage.originator,
            beneficiary: travelRuleMessage.beneficiary,
        };
        const { jsonDidKey } = this.config;
        const counterpartyDIDKey = travelRuleEncryptionOptions?.beneficiaryPIIDidKey;

        let piiIvms;

        try {
            piiIvms = await this.toolset.generatePIIField({
                pii,
                originatorVASPdid: travelRuleMessage.originatorVASPdid,
                beneficiaryVASPdid: travelRuleMessage.beneficiaryVASPdid,
                counterpartyDIDKey,
                keypair: JSON.parse(jsonDidKey),
                senderDIDKey: JSON.parse(jsonDidKey).did,
                encryptionMethod: travelRuleEncryptionOptions?.sendToProvider
                    ? PIIEncryptionMethod.HYBRID
                    : PIIEncryptionMethod.END_2_END,
            });
        } catch (error) {
            const errorMessage = error.message || error.toString();
            const errorDetails = JSON.stringify(error);
            throw new Error(`Failed to generate PII fields error: ${errorMessage}. Details: ${errorDetails}`);
        }

        transaction.travelRuleMessage = this.travelRuleMessageHandler(travelRuleMessage, piiIvms);

        return transaction;
    }

    private travelRuleMessageHandler(travelRuleMessage: TravelRule, piiIvms: any): TravelRule {
        travelRuleMessage.beneficiary = piiIvms.beneficiary;
        travelRuleMessage.originator = piiIvms.originator;

        return travelRuleMessage;
    }
}
```

Then, create the transaction using the [Transaction Create](/api-reference/transactions/create-a-new-transaction) endpoint and include the information you validated with Notabene.

```javascript theme={"system"}
const travelRuleEncryptedMessage = {
  originatorVASPdid: 'did:ethr:0x44957e75d6ce4a5bf37aae117da86422c848f7c2',
  travelRuleBehavior: false,
  beneficiaryVASPdid: 'did:ethr:0xf9139d9ca3cd9824a7fb623b1d34618a155137bc',
  beneficiaryVASPname: '',
  originatorDid: '',
  beneficiaryDid: '',
  originator: {
    originatorPersons: [
      {
        naturalPerson: {
          name: [
            {
              nameIdentifier: [
                {
                  primaryIdentifier: 'QmQMWeaZVMuR4eD2YxLwLT6uEdnbNX5f5KS1V6rWWgdNN4',
                  secondaryIdentifier: 'QmQUusxQZ2GAezHKKAgMnj4ZRrRCccZfeADmeeQGxfKEwe'
                }
              ]
            }
          ],
          geographicAddress: [
            {
              streetName: 'QmdMT2uowJmQnefc1noRxGx69pAa3tvAeEvNEAsEe8aKac',

  ............
  ......
}

const transaction = {
        assetId: 'XRP_TEST',
        source: {
            type: 'VAULT_ACCOUNT',
            id: '0',
            virtualId: undefined,
            virtualType: undefined
        },
        destination: {
            type: 'ONE_TIME_ADDRESS',
            id: undefined,
            oneTimeAddress: {
                address: 'rn7tTh4Dvsc3G5k1TJo9X1vpHREG3Cac6r',
                tag: undefined
            },
            virtualId: undefined,
            virtualType: undefined
        },
        operation: 'TRANSFER',
        amount: '5.007',
        fee: undefined,
        gasPrice: undefined,
        gasLimit: undefined,
        feeLevel: undefined,
        maxFee: undefined,
        failOnLowFee: false,
        priorityFee: undefined,
        note: 'Created with love by fireblocks SDK from BDD Travel Rule TEST',
        autoStaking: undefined,
        cpuStaking: undefined,
        networkStaking: undefined,
        replaceTxByHash: '',
        extraParameters: undefined,
        destinations: undefined,
        externalTxId: undefined,
        treatAsGrossAmount: undefined,
        travelRuleMessage: travelRuleEncryptedMessage,
    }

....

apiClient.issuePostRequest("https://api.fireblocks.io/v1/transactions", transaction);
```

### Fireblocks SDK

To create a Fireblocks blockchain transaction with encrypted PII data, you must provide the necessary Notabene PII SDK credentials in the `sdkOptions` field. You can choose to use an [end-to-end encryption method](https://devx.notabene.id/docs/encryption#end-to-end-encryption) or a [hybrid encryption method](https://devx.notabene.id/docs/encryption#hybrid-encryption).

```javascript theme={"system"}
fireblocks = new FireblocksSDK(privateKey, userId, serverAddress, undefined, {
        customAxiosOptions: {
            interceptors: {
                response: {
                    onFulfilled: (response) => {
                        console.log(`Request ID: ${response.headers["x-request-id"]}`);
                        return response;
                    },
                    onRejected: (error) => {
                        console.log(`Request ID: ${error.response.headers["x-request-id"]}`);
                        throw error;
                    }
                }
            }
        },
        travelRuleOptions: {
            kmsSecretKey:
                "75099860d284bb22a2c96a6e41ee024d04171a4ba33b2f3720d2bec17d1ced78",
            authURL: "[https://auth.notabene.id"](https://auth.notabene.id"),
            baseURL: "[https://api.notabene.dev"](https://api.notabene.dev"),
            audience: "[https://api.notabene.dev"](https://api.notabene.dev"),
            baseURLPII: "[https://pii.notabene.dev"](https://pii.notabene.dev"),
            audiencePII: "[https://pii.notabene.dev"](https://pii.notabene.dev"),
            clientId: "7iQ6MNg*****************************",
            clientSecret: "1rg17YZtmFT***********************************************",
            jsonDidKey: "{\"did\":\"did:key:z6MknL8ERKo2MqArMvJdA2EdZcUWehR7t3gDDc9hsbB7TCfZ\",\"controllerKeyId\":\"75099860d284bb22a2c96a6e41ee024d04171a4ba33b2f3720d2bec17d1ced78\",\"keys\":\[{\"type\":\"Ed25519\",\"kid\":\"75099860d284bb22a2c96a6e41ee024d04171a4ba33b2f3720d2bec17d1ced78\",\"publicKeyHex\":\"75099860d284bb22a2c96a6e41ee024d04171a4ba33b2f3720d2bec17d1ced78\",\"meta\":{\"algorithms\":[\"Ed25519\",\"EdDSA\"]},\"kms\":\"local\",\"privateKeyHex\":\"c0add0d8b45f704bbc8235d05ee449dc19453dce94df2b07c7bddb36cf7de59475099860d284bb22a2c96a6e41ee024d04171a4ba33b2f3720d2bec17d1ced78\"}],\"services\":\[],\"provider\":\"did:key\"}"
        }
    });
```

Then provide the Travel Rule Message data to Fireblocks Transaction in the requested format.

```json theme={"system"}
{
    "transactionAsset": "ETH",
    "transactionAmount": "10044000000000000000",
    "originatorVASPdid": "{{vaspDID}}",
    "beneficiaryVASPdid": "did:ethr:0xc7d10be62c7a5af366a13511fe5e0584b8918114",
    "transactionBlockchainInfo": {
        "txHash": "",
        "origin": "5342b5234hioutewry87y78sdfghy783t4t34",
        "destination": "0xDB6A31EC49D5FB35EF6BA6CE0A3B071C8BA7F7F0"
    },
    "originator": {
        "originatorPersons": \[
            {
                "naturalPerson": {
                    "name": \[
                        {
                            "nameIdentifier": [
                                {
                                    "primaryIdentifier": "Wunderland",
                                    "secondaryIdentifier": "Alice"
                                }
                            ]
                        }
                    ],
                    "geographicAddress": [
                        {
                            "streetName": "Robinson road",
                            "townName": "Singapore",
                            "country": "SG",
                            "buildingNumber": "71",
                            "postCode": "123456"
                        }
                    ],
                    "nationalIdentification": {
                        "countryOfIssue": "SG",
                        "nationalIdentifier": "987654321",
                        "nationalIdentifierType": "DRLC"
                    }
                }
            }
        ],
        "accountNumber": [
            "5342b5234hioutewry87y78sdfghy783t4t34"
        ]
    },
    "beneficiary": {
        "beneficiaryPersons": \[
            {
                "naturalPerson": {
                    "name": \[
                        {
                            "nameIdentifier": [
                                {
                                    "primaryIdentifier": "Bobson",
                                    "secondaryIdentifier": "Bob"
                                }
                            ]
                        }
                    ]
                }
            }
        ],
        "accountNumber": [
            "5643jn5h34y2g7hg42jt24j890y345gfgh65"
        ]
    }
}
```

```javascript theme={"system"}
/**
 * Creates a new transaction with the specified options
 */
public async createTransaction(transactionArguments: TransactionArguments, requestOptions?: RequestOptions, travelRuleEncryptionOptions?: TravelRuleEncryptionOptions): Promise<CreateTransactionResponse> {
    const opts = { ...requestOptions };

    if (transactionArguments?.travelRuleMessage) {
        transactionArguments = await this.piiClient.hybridEncode(transactionArguments, travelRuleEncryptionOptions);
    }

    if (transactionArguments.source?.type === PeerType.END_USER_WALLET && !opts.ncw?.walletId) {
        const { walletId } = transactionArguments.source;
        opts.ncw = { ...opts.ncw, walletId };
    }

    return await this.apiClient.issuePostRequest("/v1/transactions", transactionArguments, opts);
}
```

# Get VASP details

You can use the `POST {{baseUrl}}/tx/vasp/{did}` API call to get details on a specific VASP from Notabene’s database. This API call allows you to receive your VASPdid key from Notabene. Once received, you can use it to [integrate your workspace with Notabene](https://support.fireblocks.io/hc/en-us/articles/8271611252764-Setting-up-Travel-Rule-integration#h_01GZ1S2MBYGNGZFDGG8K5087H4).

```json theme={"system"}
{
"vasps": \[
{
"did": "did:ethr:0x44957e75d6ce4a5bf37aae117da86422c848f7c2",
"name": "Fireblocks",
"verificationStatus": "PENDING",
"addressLine1": "Tel Aviv",
"addressLine2": null,
"city": "Tel Aviv",
"country": "IL",
"emailDomains": "[\"fireblocks.com\"]",
"website": "[https://fireblocks.com"](https://fireblocks.com"),
"logo": null,
"legalStructure": "CORPORATION",
"legalName": "Fireblocks Ltd",
"yearFounded": "2018",
"incorporationCountry": "IL",
"isRegulated": "NO",
"otherNames": null,
"identificationType": null,
"identificationCountry": null,
"businessNumber": null,
"regulatoryAuthorities": null,
"jurisdictions": "IL",
"street": null,
"number": null,
"unit": null,
"postCode": null,
"state": null,
"certificates": null,
"description": null,
"travelRule_OPENVASP": null,
"travelRule_SYGNA": null,
"travelRule_TRISA": null,
"travelRule_TRLIGHT": "active",
"travelRule_EMAIL": null,
"travelRule_TRP": null,
"travelRule_SHYFT": null,
"travelRule_USTRAVELRULEWG": null,
"createdAt": "2022-12-01T09:12:11.048Z",
"createdBy": "did:ethr:0x44957e75d6ce4a5bf37aae117da86422c848f7c2",
"updatedAt": "2023-04-20T21:13:46.696Z",
"updatedBy": null,
"lastSentDate": "2023-04-20T21:13:46.678Z",
"lastReceivedDate": "2023-04-18T18:36:40.331Z",
"documents": null,
"hasAdmin": true,
"isNotifiable": true,
"issuers": {
"verificationStatus": {
"issuerDid": "did:ethr:0x19b5ff8440019b635a86bbb632db854f2ea80423"
},
"emailDomains": {
"issuerDid": "did:ethr:0xf33cbc1a777bcfba6f9f66de276e8072d18fadae"
},
"travelRule_TRLIGHT": {
"issuerDid": "did:ethr:0xf33cbc1a777bcfba6f9f66de276e8072d18fadae"
},
"jurisdictions": {
"issuerDid": "did:ethr:0xf33cbc1a777bcfba6f9f66de276e8072d18fadae"
},
"country": {
"issuerDid": "did:ethr:0xf33cbc1a777bcfba6f9f66de276e8072d18fadae"
},
"city": {
"issuerDid": "did:ethr:0xf33cbc1a777bcfba6f9f66de276e8072d18fadae"
},
"addressLine1": {
"issuerDid": "did:ethr:0xf33cbc1a777bcfba6f9f66de276e8072d18fadae"
},
"isReg
```

# Additional resources

* [Notabene docs](https://devx.notabene.id/docs/using-notabene-and-fireblocks)
* [Testing transactions](https://devx.notabene.id/docs/fireblocks-testing)
* [Postman Collection](https://www.postman.com/notabene/workspace/fireblocks-notabene-integration/overview)
* [More code samples for using the PII-SDK and Fireblocks API](https://devx.notabene.id/recipes/using-the-pii-sdk-and-fireblocks-api)


# Validating webhooks
Source: https://developers.fireblocks.com/reference/validating-webhooks



## Method 2: Signature Verification

Fireblocks cryptographically signs every webhook, allowing you to verify authenticity and integrity.

### Signature methods

| Method | Header                       | Key Rotation |
| ------ | ---------------------------- | ------------ |
| JWKS   | Fireblocks-Webhook-Signature | ✅ Automatic  |
| Legacy | Fireblocks-Signature         | ❌ Manual     |

During migration, both headers are sent with each webhook.

## Validating webhooks (JWKS)

### How it works

The new signature uses Detached JWS (JSON Web Signature) format:

Fireblocks-Webhook-Signature: "\[header]..\[signature]"

The kid (key ID) is embedded in the JWS header, allowing automatic key lookup from the JWKS endpoint. The payload is sent separately in the request body (detached format).

### JWKS endpoints

Fireblocks publishes public keys in JWKS format for validating webhook signatures. Use the endpoint that matches your workspace's environment.

| Environment   | URL                                                                                                                  |
| ------------- | -------------------------------------------------------------------------------------------------------------------- |
| US Production | [https://keys.fireblocks.io/.well-known/jwks.json](https://keys.fireblocks.io/.well-known/jwks.json)                 |
| EU            | [https://eu-keys.fireblocks.io/.well-known/jwks.json](https://eu-keys.fireblocks.io/.well-known/jwks.json)           |
| EU2           | [https://eu2-keys.fireblocks.io/.well-known/jwks.json](https://eu2-keys.fireblocks.io/.well-known/jwks.json)         |
| Sandbox       | [https://sandbox-keys.fireblocks.io/.well-known/jwks.json](https://sandbox-keys.fireblocks.io/.well-known/jwks.json) |

#### Response format

```json theme={"system"}
{
  "keys": [
    {
      "kty": "RSA",
      "kid": "webhook-key-2025-01",
      "use": "sig",
      "alg": "RS512",
      "n": "0vx7agoebGcQemDqTnUt...",
      "e": "AQAB"
    }
  ]
}
```

| Field | Description                                              |
| ----- | -------------------------------------------------------- |
| kty   | Key type. Always RSA for Fireblocks webhook keys.        |
| kid   | Key ID. Matches the kid header in incoming webhook JWTs. |
| use   | Key usage. Always sig (signature verification).          |
| alg   | Algorithm. Fireblocks uses RS512 (RSA with SHA-512).     |
| n     | RSA modulus (Base64URL-encoded).                         |
| e     | RSA exponent (Base64URL-encoded).                        |

### Caching behavior

The JWKS endpoint returns caching headers to optimize performance:

* Cache-Control: public, max-age=3600, s-maxage=3600
* Access-Control-Allow-Origin: \*
* Content-Type: application/json

#### Code examples (JWKS)

```typescript theme={"system"}
import { createRemoteJWKSet, compactVerify } from 'jose';

// Initialize JWKS client (caches keys automatically)
const JWKS = createRemoteJWKSet(
  new URL('https://keys.fireblocks.io/.well-known/jwks.json')
);

async function verifyWebhookJWKS(
  rawBody: Buffer,
  jwsSignature: string
): Promise<boolean> {
  try {
    // Detached JWS format: "header..signature" (no payload)
    const [header, , sig] = jwsSignature.split('.');
    
    // Reconstruct full JWS with payload
    const payload = Buffer.from(rawBody).toString('base64url');
    const fullJws = `${header}.${payload}.${sig}`;
    
    // jose extracts kid from header and fetches correct key from JWKS
    await compactVerify(fullJws, JWKS);
    return true;
  } catch (error) {
    console.error('JWKS verification failed:', error);
    return false;
  }
}

// Usage: pass raw body and Fireblocks-Webhook-Signature header
const isValid = await verifyWebhookJWKS(rawBody, jwsSignatureHeader);
```

```python theme={"system"}
import base64
from jwcrypto import jwk, jws
from jwcrypto.common import json_decode
import requests

class FireblocksJWKSVerifier:
    def __init__(self, jwks_url: str = "https://api.fireblocks.io/.well-known/jwks.json"):
        self.jwks_url = jwks_url
        self._jwks = None
    
    def _fetch_jwks(self) -> jwk.JWKSet:
        """Fetch and cache JWKS from endpoint."""
        if self._jwks is None:
            response = requests.get(self.jwks_url)
            response.raise_for_status()
            self._jwks = jwk.JWKSet.from_json(response.text)
        return self._jwks
    
    def verify(self, raw_body: bytes, jws_signature: str) -> bool:
        """
        Verify Fireblocks webhook using JWKS.
        
        Args:
            raw_body: The raw request body as bytes
            jws_signature: The detached JWS from Fireblocks-Webhook-Signature header
        """
        try:
            # Detached JWS: "header..signature"
            parts = jws_signature.split('.')
            header, sig = parts[0], parts[2]
            
            # Reconstruct with base64url-encoded payload
            payload = base64.urlsafe_b64encode(raw_body).rstrip(b'=').decode()
            full_jws = f"{header}.{payload}.{sig}"
            
            # Verify using JWKS (kid extracted automatically from header)
            jwks = self._fetch_jwks()
            jws_obj = jws.JWS()
            jws_obj.deserialize(full_jws)
            jws_obj.verify(jwks)
            return True
        except Exception as e:
            print(f"JWKS verification failed: {e}")
            return False


# Usage
verifier = FireblocksJWKSVerifier()
is_valid = verifier.verify(raw_body, jws_signature_header)
```

```go theme={"system"}
package main

import (
	"context"
	"encoding/base64"
	"log"
	"strings"

	"github.com/lestrrat-go/jwx/v2/jwk"
	"github.com/lestrrat-go/jwx/v2/jws"
)

type JWKSVerifier struct {
	cache *jwk.Cache
	url   string
}

func NewJWKSVerifier(jwksURL string) (*JWKSVerifier, error) {
	cache := jwk.NewCache(context.Background())
	err := cache.Register(jwksURL, jwk.WithMinRefreshInterval(time.Hour))
	if err != nil {
		return nil, err
	}
	return &JWKSVerifier{cache: cache, url: jwksURL}, nil
}

// VerifyWebhookJWKS verifies Fireblocks webhook using JWKS.
// rawBody: The raw request body
// jwsSignature: The detached JWS from Fireblocks-Webhook-Signature header
func (v *JWKSVerifier) VerifyWebhookJWKS(rawBody []byte, jwsSignature string) bool {
	// Detached JWS: "header..signature"
	parts := strings.Split(jwsSignature, ".")
	if len(parts) != 3 {
		log.Println("Invalid JWS format")
		return false
	}
	header, sig := parts[0], parts[2]

	// Reconstruct with base64url-encoded payload
	payload := base64.RawURLEncoding.EncodeToString(rawBody)
	fullJws := header + "." + payload + "." + sig

	// Fetch keys and verify
	keySet, err := v.cache.Get(context.Background(), v.url)
	if err != nil {
		log.Printf("Failed to fetch JWKS: %v", err)
		return false
	}

	_, err = jws.Verify([]byte(fullJws), jws.WithKeySet(keySet))
	if err != nil {
		log.Printf("JWKS verification failed: %v", err)
		return false
	}
	return true
}

// Usage:
// verifier, _ := NewJWKSVerifier("https://api.fireblocks.io/.well-known/jwks.json")
// isValid := verifier.VerifyWebhookJWKS(rawBody, jwsSignatureHeader)

```

```java theme={"system"}
import com.nimbusds.jose.*;
import com.nimbusds.jose.crypto.RSASSAVerifier;
import com.nimbusds.jose.jwk.*;
import com.nimbusds.jose.jwk.source.*;
import java.net.URL;
import java.util.Base64;
import java.util.concurrent.TimeUnit;

public class FireblocksJWKSVerifier {
    
    private final JWKSource<SecurityContext> jwkSource;
    
    public FireblocksJWKSVerifier(String jwksUrl) throws Exception {
        // Cache JWKS for 1 hour, refresh 5 min before expiry
        var cache = new DefaultJWKSetCache(1, 5, TimeUnit.HOURS);
        this.jwkSource = new RemoteJWKSet<>(new URL(jwksUrl), null, cache);
    }
    
    public FireblocksJWKSVerifier() throws Exception {
        this("https://keys.fireblocks.io/.well-known/jwks.json");
    }
    
    public boolean verify(byte[] rawBody, String jwsSignature) throws JOSEException {
        // Reconstruct full JWS from detached format (header..signature)
        String[] parts = jwsSignature.split("\\.");
        String payload = Base64.getUrlEncoder().withoutPadding().encodeToString(rawBody);
        String fullJws = parts[0] + "." + payload + "." + parts[2];
        
        JWSObject jws = JWSObject.parse(fullJws);
        
        // Get the key by kid from JWKS (cached)
        JWKSelector selector = new JWKSelector(
            new JWKMatcher.Builder().keyID(jws.getHeader().getKeyID()).build()
        );
        RSAKey rsaKey = (RSAKey) jwkSource.get(selector, null).get(0);
        
        return jws.verify(new RSASSAVerifier(rsaKey));
    }
}

```

### JWKS caching best practices

Cache the JWKS: Most libraries handle this automatically.
Respect Cache-Control: JWKS responses include max-age=3600 (1 hour). Refresh accordingly.
Handle rotation gracefully: Multiple keys will be present; the kid in the JWS header identifies which key to use.

### Common pitfalls

| Issue                            | Solution                                                                 |
| -------------------------------- | ------------------------------------------------------------------------ |
| Body parsing before verification | Use raw body parser middleware. JSON parsing alters whitespace/ordering. |
| Wrong JWKS URL                   | Use the correct endpoint for your environment                            |
| Stale JWKS cache                 | Refresh the cache if verification fails with an unknown kid              |
| Encoding issues                  | Ensure body is read as raw bytes, not string-converted                   |

***

## Legacy Static Key Validation

<Warning>
  **Migration notice**

  This method is being replaced by JWKS-based validation. Both headers are sent until March 20th, 2026. New integrations should use JWKS.
</Warning>

### How the signature works

Fireblocks signs every webhook event with their private key. The signature is sent in the Fireblocks-Signature HTTP header:

Fireblocks-Signature: Base64(RSA512(WEBHOOK\_PRIVATE\_KEY, SHA512(eventBody)))

Breakdown:

SHA512(eventBody) — Hash the raw request body with SHA-512\
RSA512 Sign — Fireblocks signs the hash with their private RSA key (PKCS#1 v1.5)\
Base64 Encode — The signature is base64-encoded for transport

Your job: Verify the signature using Fireblocks' public key to confirm authenticity.

### Public keys by environment

#### US Mainnet & Testnet

```pem theme={"system"}
-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA0+6wd9OJQpK60ZI7qnZG
jjQ0wNFUHfRv85Tdyek8+ahlg1Ph8uhwl4N6DZw5LwLXhNjzAbQ8LGPxt36RUZl5
YlxTru0jZNKx5lslR+H4i936A4pKBjgiMmSkVwXD9HcfKHTp70GQ812+J0Fvti/v
4nrrUpc011Wo4F6omt1QcYsi4GTI5OsEbeKQ24BtUd6Z1Nm/EP7PfPxeb4CP8KOH
clM8K7OwBUfWrip8Ptljjz9BNOZUF94iyjJ/BIzGJjyCntho64ehpUYP8UJykLVd
CGcu7sVYWnknf1ZGLuqqZQt4qt7cUUhFGielssZP9N9x7wzaAIFcT3yQ+ELDu1SZ
dE4lZsf2uMyfj58V8GDOLLE233+LRsRbJ083x+e2mW5BdAGtGgQBusFfnmv5Bxqd
HgS55hsna5725/44tvxll261TgQvjGrTxwe7e5Ia3d2Syc+e89mXQaI/+cZnylNP
SwCCvx8mOM847T0XkVRX3ZrwXtHIA25uKsPJzUtksDnAowB91j7RJkjXxJcz3Vh1
4k182UFOTPRW9jzdWNSyWQGl/vpe9oQ4c2Ly15+/toBo4YXJeDdDnZ5c/O+KKadc
IMPBpnPrH/0O97uMPuED+nI6ISGOTMLZo35xJ96gPBwyG5s2QxIkKPXIrhgcgUnk
tSM7QYNhlftT4/yVvYnk0YcCAwEAAQ==
-----END PUBLIC KEY-----
```

#### EU & EU2 Mainnet & Testnet

```pem theme={"system"}
-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA6hLRQL0jPf5OEuaDYGjO
xSyaYIlv08S0+4giiwgKSfV3Onc5hn03mvE0znzaUq2ReSxi9KYDdMYFfzf1uwF7
7kYy2MY0oTYGdQb+PS4Ym4R4tgZ2otuoAXt8YRKq2maWyguFiaowMcYwwAVQv8JB
afIm6Jq1nI6v1mEDVX065ePlBlAt+BGAqr6ahPxnaIz3L4eztpuNrt5nTbSxs7eF
aqQx1p56W1nl3Hl0V3tLkaXbuVtbFNR/mGMInrkPnpsG+mt35b9vmqAOvLPI0Cx1
59uVeEs62Hj1AOCRyT6SuwIaFynRj2KnD42ioQtkodHQ0xDtgdiYGsxuwQ9vTIe7
5oLsL8gBDeX5gdcTfSZhfGjZ7RggLNJ7vCAbYKMuUOdgWVMYnJfrhNLCq3zDSZPO
+H0x5m/Yeq/Hn5o7xCmLNT3qARfwDd5IHfQyXqVYB6TMU75xqH5fdSRw0iMdoPyL
ALnr9/JT0av3qssNMRdWCXr+j9Ys3NkfcbU/a49657mg8e2QGSkl9w39csEKojnr
omUz25szIL8CcXLmc5cAmnimFCe4L7UT4mvVP3+fOo+cbc/82zqA8tsSwd2Y93/6
ueGnNZD9V5rewrKjmdPfrwoI2gntzc8QJUu+nxAWhoqHV91AQeglu6WIF/DiEJC5
WPoNk2SdlAuA6RYmgB2YyikCAwEAAQ==
-----END PUBLIC KEY-----

```

#### Developer Sandbox

```pem theme={"system"}
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApZE6wL2+7P1ohvVYSpCd
gSgtmyGwiLbUC1UoGJhn1zwfY7ZWbNH7Pg8Osk8OzZTZHSG/arcgE8HnGCmGKtbE
QBkf2XlBRBQ01FcCMlZuJQJ3nElCPaMl9N6fq0VKNEIlVSVUpDCgvag5kFhDKS/L
p3YYJLFR46/hDlVLn+vM84diO3xGyMc16YJGNz7Z4jb8dmSZQE5E2XaQMDXW6uxC
c2ChjWJ3X5H70MzRG35JsN0j58SQTwbf4Pxm0aJfhPuaIBn3mJuZL5etsuFihoFG
FDnT+qWRcgD/pRNulBFAFhJeUnFrE4fFTJ1iaHhjBrStBCrxJk6QI0pGznoapTgA
2QIDAQAB
-----END PUBLIC KEY-----

```

### Step-by-step validation process

1. Extract the signature from the Fireblocks-Signature header
2. Base64 decode the signature to get raw bytes
3. Read the raw request body (do NOT parse or modify it)
4. Hash the body with SHA-512
5. Verify using RSA PKCS#1 v1.5 with the Fireblocks public key
6. Accept or reject the webhook based on the verification result

### Code examples (Legacy)

```typescript theme={"system"}
import crypto from 'crypto';

// Select the appropriate key for your environment
const FIREBLOCKS_PUBLIC_KEY_US = `-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA0+6wd9OJQpK60ZI7qnZG
jjQ0wNFUHfRv85Tdyek8+ahlg1Ph8uhwl4N6DZw5LwLXhNjzAbQ8LGPxt36RUZl5
YlxTru0jZNKx5lslR+H4i936A4pKBjgiMmSkVwXD9HcfKHTp70GQ812+J0Fvti/v
4nrrUpc011Wo4F6omt1QcYsi4GTI5OsEbeKQ24BtUd6Z1Nm/EP7PfPxeb4CP8KOH
clM8K7OwBUfWrip8Ptljjz9BNOZUF94iyjJ/BIzGJjyCntho64ehpUYP8UJykLVd
CGcu7sVYWnknf1ZGLuqqZQt4qt7cUUhFGielssZP9N9x7wzaAIFcT3yQ+ELDu1SZ
dE4lZsf2uMyfj58V8GDOLLE233+LRsRbJ083x+e2mW5BdAGtGgQBusFfnmv5Bxqd
HgS55hsna5725/44tvxll261TgQvjGrTxwe7e5Ia3d2Syc+e89mXQaI/+cZnylNP
SwCCvx8mOM847T0XkVRX3ZrwXtHIA25uKsPJzUtksDnAowB91j7RJkjXxJcz3Vh1
4k182UFOTPRW9jzdWNSyWQGl/vpe9oQ4c2Ly15+/toBo4YXJeDdDnZ5c/O+KKadc
IMPBpnPrH/0O97uMPuED+nI6ISGOTMLZo35xJ96gPBwyG5s2QxIkKPXIrhgcgUnk
tSM7QYNhlftT4/yVvYnk0YcCAwEAAQ==
-----END PUBLIC KEY-----`;

function verifyWebhookSignature(
  rawBody: Buffer,
  signature: string,
  publicKey: string = FIREBLOCKS_PUBLIC_KEY_US
): boolean {
  try {
    const verifier = crypto.createVerify('RSA-SHA512');
    verifier.update(rawBody);
    return verifier.verify(publicKey, signature, 'base64');
  } catch (error) {
    console.error('Signature verification failed:', error);
    return false;
  }
}

/**
 * IMPORTANT:
 * This function requires the **raw request body**.
 * Do NOT use express.json() or any body parser that mutates the payload.
 *
 * Use:
 *   app.use(express.raw({ type: 'application/json' }))
 *
 * Otherwise, signature verification will fail.
 */
// Usage: pass raw request body (Buffer) and Fireblocks-Signature header value const isValid = verifyWebhookSignature(rawBody, signatureHeader);
```

```python theme={"system"}
import base64
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.backends import default_backend

# Select the appropriate key for your environment
FIREBLOCKS_PUBLIC_KEY_US = """-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA0+6wd9OJQpK60ZI7qnZG
jjQ0wNFUHfRv85Tdyek8+ahlg1Ph8uhwl4N6DZw5LwLXhNjzAbQ8LGPxt36RUZl5
YlxTru0jZNKx5lslR+H4i936A4pKBjgiMmSkVwXD9HcfKHTp70GQ812+J0Fvti/v
4nrrUpc011Wo4F6omt1QcYsi4GTI5OsEbeKQ24BtUd6Z1Nm/EP7PfPxeb4CP8KOH
clM8K7OwBUfWrip8Ptljjz9BNOZUF94iyjJ/BIzGJjyCntho64ehpUYP8UJykLVd
CGcu7sVYWnknf1ZGLuqqZQt4qt7cUUhFGielssZP9N9x7wzaAIFcT3yQ+ELDu1SZ
dE4lZsf2uMyfj58V8GDOLLE233+LRsRbJ083x+e2mW5BdAGtGgQBusFfnmv5Bxqd
HgS55hsna5725/44tvxll261TgQvjGrTxwe7e5Ia3d2Syc+e89mXQaI/+cZnylNP
SwCCvx8mOM847T0XkVRX3ZrwXtHIA25uKsPJzUtksDnAowB91j7RJkjXxJcz3Vh1
4k182UFOTPRW9jzdWNSyWQGl/vpe9oQ4c2Ly15+/toBo4YXJeDdDnZ5c/O+KKadc
IMPBpnPrH/0O97uMPuED+nI6ISGOTMLZo35xJ96gPBwyG5s2QxIkKPXIrhgcgUnk
tSM7QYNhlftT4/yVvYnk0YcCAwEAAQ==
-----END PUBLIC KEY-----"""


def verify_webhook_signature(
    raw_body: bytes,
    signature: str,
    public_key_pem: str = FIREBLOCKS_PUBLIC_KEY_US
) -> bool:
    """
    Verify Fireblocks webhook signature.
    
    Args:
        raw_body: The raw request body as bytes
        signature: The base64-encoded signature from Fireblocks-Signature header
        public_key_pem: The Fireblocks public key in PEM format
    
    Returns:
        True if signature is valid, False otherwise
    """
    try:
        public_key = serialization.load_pem_public_key(
            public_key_pem.encode(),
            backend=default_backend()
        )
        signature_bytes = base64.b64decode(signature)
        
        # Verify: RSA-SHA512 with PKCS#1 v1.5 padding
        public_key.verify(
            signature_bytes,
            raw_body,
            padding.PKCS1v15(),
            hashes.SHA512()
        )
        return True
    except Exception as e:
        print(f"Signature verification failed: {e}")
        return False


# Usage: pass raw request body (bytes) and Fireblocks-Signature header value
is_valid = verify_webhook_signature(raw_body, signature_header)

# IMPORTANT:
# Signature verification requires the **raw request body bytes**.
#
# - Flask: use request.get_data()
# - FastAPI: use await request.body()
#
# Do NOT use request.json() or request.form(),
# as they modify the payload and will invalidate the signature.
```

```java theme={"system"}
import java.security.KeyFactory;
import java.security.PublicKey;
import java.security.Signature;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;

public class FireblocksWebhookVerifier {

    // Select the appropriate key for your environment (base64-encoded, no PEM headers)
    private static final String FIREBLOCKS_PUBLIC_KEY_US = 
        "MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA0+6wd9OJQpK60ZI7qnZG" +
        "jjQ0wNFUHfRv85Tdyek8+ahlg1Ph8uhwl4N6DZw5LwLXhNjzAbQ8LGPxt36RUZl5" +
        "YlxTru0jZNKx5lslR+H4i936A4pKBjgiMmSkVwXD9HcfKHTp70GQ812+J0Fvti/v" +
        "4nrrUpc011Wo4F6omt1QcYsi4GTI5OsEbeKQ24BtUd6Z1Nm/EP7PfPxeb4CP8KOH" +
        "clM8K7OwBUfWrip8Ptljjz9BNOZUF94iyjJ/BIzGJjyCntho64ehpUYP8UJykLVd" +
        "CGcu7sVYWnknf1ZGLuqqZQt4qt7cUUhFGielssZP9N9x7wzaAIFcT3yQ+ELDu1SZ" +
        "dE4lZsf2uMyfj58V8GDOLLE233+LRsRbJ083x+e2mW5BdAGtGgQBusFfnmv5Bxqd" +
        "HgS55hsna5725/44tvxll261TgQvjGrTxwe7e5Ia3d2Syc+e89mXQaI/+cZnylNP" +
        "SwCCvx8mOM847T0XkVRX3ZrwXtHIA25uKsPJzUtksDnAowB91j7RJkjXxJcz3Vh1" +
        "4k182UFOTPRW9jzdWNSyWQGl/vpe9oQ4c2Ly15+/toBo4YXJeDdDnZ5c/O+KKadc" +
        "IMPBpnPrH/0O97uMPuED+nI6ISGOTMLZo35xJ96gPBwyG5s2QxIkKPXIrhgcgUnk" +
        "tSM7QYNhlftT4/yVvYnk0YcCAwEAAQ==";

    private final PublicKey publicKey;

    public FireblocksWebhookVerifier() throws Exception {
        this.publicKey = loadPublicKey(FIREBLOCKS_PUBLIC_KEY_US);
    }

    private PublicKey loadPublicKey(String base64Key) throws Exception {
        byte[] keyBytes = Base64.getDecoder().decode(base64Key);
        X509EncodedKeySpec spec = new X509EncodedKeySpec(keyBytes);
        KeyFactory keyFactory = KeyFactory.getInstance("RSA");
        return keyFactory.generatePublic(spec);
    }

    /**
     * Verify Fireblocks webhook signature.
     *
     * @param rawBody   The raw request body as bytes
     * @param signature The base64-encoded signature from Fireblocks-Signature header
     * @return true if signature is valid, false otherwise
     */
    public boolean verifyWebhookSignature(byte[] rawBody, String signature) {
        try {
            byte[] signatureBytes = Base64.getDecoder().decode(signature);
            
            // SHA512withRSA uses PKCS#1 v1.5 padding
            Signature verifier = Signature.getInstance("SHA512withRSA");
            verifier.initVerify(publicKey);
            verifier.update(rawBody);
            
            return verifier.verify(signatureBytes);
        } catch (Exception e) {
            System.err.println("Signature verification failed: " + e.getMessage());
            return false;
        }
    }
}

// Usage: pass raw request body (byte[]) and Fireblocks-Signature header value
// boolean isValid = verifier.verifyWebhookSignature(rawBody, signatureHeader);

// IMPORTANT:
// Signature verification requires the raw request body.
// Use:
//
//   @RequestBody byte[] rawBody
//
// Do NOT bind the request to a POJO or String before verification,
// as this will alter the payload and break signature validation.
```

```go theme={"system"}
package main

import (
	"crypto"
	"crypto/rsa"
	"crypto/sha512"
	"crypto/x509"
	"encoding/base64"
	"encoding/pem"
	"fmt"
	"log"
)

// Select the appropriate key for your environment
const fireblocksPublicKeyUS = `-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA0+6wd9OJQpK60ZI7qnZG
jjQ0wNFUHfRv85Tdyek8+ahlg1Ph8uhwl4N6DZw5LwLXhNjzAbQ8LGPxt36RUZl5
YlxTru0jZNKx5lslR+H4i936A4pKBjgiMmSkVwXD9HcfKHTp70GQ812+J0Fvti/v
4nrrUpc011Wo4F6omt1QcYsi4GTI5OsEbeKQ24BtUd6Z1Nm/EP7PfPxeb4CP8KOH
clM8K7OwBUfWrip8Ptljjz9BNOZUF94iyjJ/BIzGJjyCntho64ehpUYP8UJykLVd
CGcu7sVYWnknf1ZGLuqqZQt4qt7cUUhFGielssZP9N9x7wzaAIFcT3yQ+ELDu1SZ
dE4lZsf2uMyfj58V8GDOLLE233+LRsRbJ083x+e2mW5BdAGtGgQBusFfnmv5Bxqd
HgS55hsna5725/44tvxll261TgQvjGrTxwe7e5Ia3d2Syc+e89mXQaI/+cZnylNP
SwCCvx8mOM847T0XkVRX3ZrwXtHIA25uKsPJzUtksDnAowB91j7RJkjXxJcz3Vh1
4k182UFOTPRW9jzdWNSyWQGl/vpe9oQ4c2Ly15+/toBo4YXJeDdDnZ5c/O+KKadc
IMPBpnPrH/0O97uMPuED+nI6ISGOTMLZo35xJ96gPBwyG5s2QxIkKPXIrhgcgUnk
tSM7QYNhlftT4/yVvYnk0YcCAwEAAQ==
-----END PUBLIC KEY-----`

func loadPublicKey(pemKey string) (*rsa.PublicKey, error) {
	block, _ := pem.Decode([]byte(pemKey))
	if block == nil {
		return nil, fmt.Errorf("failed to parse PEM block")
	}
	pub, err := x509.ParsePKIXPublicKey(block.Bytes)
	if err != nil {
		return nil, fmt.Errorf("failed to parse public key: %w", err)
	}
	rsaPub, ok := pub.(*rsa.PublicKey)
	if !ok {
		return nil, fmt.Errorf("not an RSA public key")
	}
	return rsaPub, nil
}

// VerifyWebhookSignature verifies Fireblocks webhook signature.
// rawBody: The raw request body as bytes
// signatureB64: The base64-encoded signature from Fireblocks-Signature header
func VerifyWebhookSignature(rawBody []byte, signatureB64 string, publicKey *rsa.PublicKey) bool {
	signature, err := base64.StdEncoding.DecodeString(signatureB64)
	if err != nil {
		log.Printf("Failed to decode signature: %v", err)
		return false
	}
	
	hash := sha512.Sum512(rawBody)
	
	err = rsa.VerifyPKCS1v15(publicKey, crypto.SHA512, hash[:], signature)
	if err != nil {
		log.Printf("Signature verification failed: %v", err)
		return false
	}
	return true
}

// Usage:
// publicKey, _ := loadPublicKey(fireblocksPublicKeyUS)
// isValid := VerifyWebhookSignature(rawBody, signatureHeader, publicKey)

// IMPORTANT:
// Signature verification requires the raw request body bytes.
// Use:
//
//   body, err := io.ReadAll(r.Body)
//
// Do NOT decode or unmarshal the body before verification,
// as this will modify the payload and invalidate the signature.
```


# Vault Objects
Source: https://developers.fireblocks.com/reference/vault-objects



## VaultAccountsPagedResponse

| Parameter   | Type                                   | Description                                                     |
| ----------- | -------------------------------------- | --------------------------------------------------------------- |
| accounts    | Array of [VaultAccount](#vaultaccount) | List of vault account objects                                   |
| paging      | object                                 | Contains two fields: **before** (string) and **after** (string) |
| previousUrl | string                                 | URL string of the request for the previous page                 |
| nextUrl     | string                                 | URL string of the request for the next page                     |

***

## CreateVaultAssetResponse

| Parameter      | Type   | Description                                                                                                                             |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| id             | string | The ID of the vault account                                                                                                             |
| address        | string | Address of the asset in a vault account; for BTC and LTC, the address is in Segwit (Bech32) format, and the cash address format for BCH |
| legacyAddress  | string | Legacy address format for BTC, LTC, and BCH                                                                                             |
| tag            | string | Used as destination tag for XRP; `memo` for ATOM, EOS, HBAR, LUNA, LUNC, XDB, XEM; `memo_text` for XLM; `notes` for ALGO.               |
| eosAccountName | string | Returned for EOS; the account name                                                                                                      |

***

## VaultAsset

| Parameter            | Type   | Description                                                                                    |
| -------------------- | ------ | ---------------------------------------------------------------------------------------------- |
| id                   | string | The ID of the asset                                                                            |
| total                | string | Total wallet balance                                                                           |
| balance              | string | Deprecated - replaced by "total"                                                               |
| available            | string | Funds that are available for transfer, equal to the blockchain balance minus any locked amount |
| pending              | string | The cumulative balance of all pending transactions to be cleared                               |
| staked               | string | Staked funds; returned only for DOT                                                            |
| frozen               | string | Frozen by your workspace's AML policies                                                        |
| lockedAmount         | string | Funds in outgoing transactions not yet published to the network                                |
| totalStakedCPU       | string | \[optional] Deprecated                                                                         |
| totalStakedNetwork   | string | \[optional] Deprecated                                                                         |
| selfStakedCPU        | string | \[optional] Deprecated                                                                         |
| selfStakedNetwork    | string | \[optional] Deprecated                                                                         |
| pendingRefundCPU     | string | \[optional] Deprecated                                                                         |
| pendingRefundNetwork | string | \[optional] Deprecated                                                                         |
| blockHeight          | string | The height (number) of the block of the balance                                                |
| blockHash            | string | The hash of the block of the balance                                                           |

***

## VaultAccountAssetAddress

| Parameter         | Type   | Description                                                                                                                                                                                       |
| ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| assetId           | string | The ID of the asset                                                                                                                                                                               |
| address           | string | Address of the asset in a vault account; for BTC and LTC, the address is in Segwit (Bech32) format, and the cash address format for BCH                                                           |
| legacyAddress     | string | Legacy address format for BTC, LTC, and BCH                                                                                                                                                       |
| description       | string | Description of the address                                                                                                                                                                        |
| tag               | string | Used as destination tag for XRP; `memo` for EOS, HBAR, XDB `memo_text` for XLM; `notes` for ALGO; Bank Transfer Description for fiat providers                                                    |
| type              | string | Address type                                                                                                                                                                                      |
| customerRefId     | string | \[optional] The ID for AML providers to associate the owner of funds with transactions                                                                                                            |
| bip44AddressIndex | number | \[optional] The `address_index`, `addressFormat`, and `enterpriseAddress` in the derivation path of this address based on [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) |

***

## VaultAccountBalanceUpdate

| Parameter      | Type   | Description                                                      |
| -------------- | ------ | ---------------------------------------------------------------- |
| vaultAccountId | number | The ID of the vault account                                      |
| assetId        | string | The ID of the asset                                              |
| total          | string | Total wallet balance                                             |
| pending        | string | The cumulative balance of all pending transactions to be cleared |
| frozen         | string | Frozen by your workspace's AML policies                          |
| staked         | string | The amount of funds that have been staked                        |
| lockedAmount   | string | Funds in outgoing transactions not yet published to the network  |
| blockHeight    | string | The height (number) of the block of the balance                  |
| blockHash      | string | The hash of the block of the balance                             |

***

## CreateAddressResponse

| Parameter         | Type   | Description                                                                                                                                 |
| ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| address           | string | Address of the asset in a vault account; for BTC and LTC, the address is in Segwit (Bech32) format, and the cash address format for BCH     |
| legacyAddress     | string | Legacy address format for BTC, LTC, and BCH                                                                                                 |
| tag               | string | Used as destination tag for XRP; `memo` for EOS, HBAR, XDB `memo_text` for XLM; `notes` for ALGO.                                           |
| bip44AddressIndex | number | The `address_index` in the derivation path of this address based on [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) |

***

## VaultAccount

| Parameter     | Type                               | Description                                                                               |
| ------------- | ---------------------------------- | ----------------------------------------------------------------------------------------- |
| id            | string                             | The ID of the vault account                                                               |
| name          | string                             | Name of the vault account                                                                 |
| hiddenOnUI    | boolean                            | Specifies whether this vault account is visible in the Console UI                         |
| customerRefId | string                             | \[optional] The ID for AML providers to associate the owner of funds with transactions    |
| autoFuel      | boolean                            | Specifies whether this vault account's Ethereum address is auto-fueled by the Gas Station |
| assets        | Array of [VaultAsset](#vaultasset) | List of assets under this vault account                                                   |

> **Note**
>
> When the [VAULT\_ACCOUNT\_ADDED webhook](/reference/event-types#vault_account_added) is used, the VaultAccount object does not contain the `customerRefId` and `autoFuel` parameters.

***

## UnspentInputsData

| Parameter     | Type            | Description                                                 |
| ------------- | --------------- | ----------------------------------------------------------- |
| input         | [Input](#input) | An object containing the `txHash` and `index` of this input |
| address       | string          | The destination address of this input                       |
| amount        | string          | The amount of this input                                    |
| confirmations | number          | Number of confirmations for the transaction of this input   |
| status        | string          | The status is based on the status of the transaction        |

***

## PublicKey

| Parameter      | Type             | Description                                                                                                            |
| -------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------- |
| publicKey      | string           | The requested public key                                                                                               |
| algorithm      | string           | One of the [SigningAlgorithms](/reference/vault-objects#signingalgorithm)                                              |
| derivationPath | Array of numbers | Used for [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) derivation to retrieve the public key |

***

## SigningAlgorithm

| Parameter | Type   | Description                                                            |
| --------- | ------ | ---------------------------------------------------------------------- |
| algorithm | string | \[ MPC\_ECDSA\_SECP256K1, MPC\_EDDSA\_ED25519, MPC\_ECDSA\_SECP256R1 ] |


# Vault Webhooks
Source: https://developers.fireblocks.com/reference/vault-webhooks



> **Deprecation notice**
>
> Webhooks v1 will be deprecated on **June 15th, 2026**. Please use the Developer Center in the Fireblocks Console to upgrade to Webhooks V2, which offers improved reliability, performance, and observability.

This page describes all events relating to vault accounts that produce webhook notifications, and their associated data objects.

The `type` parameter is automatically set to the description name for the data objects below.

> **Not all parameters appear on responses**
>
> Not all of the parameters will appear on the response. Some of the parameters are optional. If you have any issues, please contact the customer success manager.

## Vault account created

Notification is sent when a vault account is created.

**Webhook data**

| Parameter | Type                                                  | Description                            |
| --------- | ----------------------------------------------------- | -------------------------------------- |
| type      | string                                                | VAULT\_ACCOUNT\_ADDED                  |
| tenantId  | string                                                | Unique ID of your Fireblocks workspace |
| timestamp | number                                                | Timestamp in milliseconds              |
| data      | [VaultAccount](/reference/vault-objects#vaultaccount) | Vault Account details                  |

## Asset added to vault account

Notification is sent when any asset is added to a vault account.

### Webhook data

| Parameter | Type                              | Description                            |
| --------- | --------------------------------- | -------------------------------------- |
| type      | string                            | VAULT\_ACCOUNT\_ASSET\_ADDED           |
| tenantId  | string                            | Unique ID of your Fireblocks workspace |
| timestamp | number                            | Timestamp in milliseconds              |
| data      | [AssetAddedData](#assetaddeddata) | Vault account and asset details        |

### AssetAddedData

| Parameter   | Type   | Description                                                    |
| ----------- | ------ | -------------------------------------------------------------- |
| accountId   | string | The ID of the vault account under which the wallet was added   |
| accountName | string | The name of the vault account under which the wallet was added |
| assetId     | string | Wallet's asset                                                 |

***

## Asset balance changed

Notification is sent when the asset balance of a vault account changes.

| Parameter | Type                                                                          | Description                            |
| --------- | ----------------------------------------------------------------------------- | -------------------------------------- |
| type      | string                                                                        | VAULT\_BALANCE\_UPDATE                 |
| tenantId  | string                                                                        | Unique ID of your Fireblocks workspace |
| timestamp | number                                                                        | Timestamp in milliseconds              |
| data      | [VaultAssetBalanceUpdate](/reference/vault-objects#vaultaccountbalanceupdate) | Vault account details                  |


# Validate Requests
Source: https://developers.fireblocks.com/reference/verify-requests



> **Deprecation notice**
>
> Webhooks v1 will be deprecated on **June 15th, 2026**. Please use the Developer Center in the Fireblocks Console to upgrade to Webhooks V2, which offers improved reliability, performance, and observability.

Fireblocks sends events to your webhook endpoint URL(s) associated with the workspace, as part of a POST request with a JSON payload.

### Validation

You can validate Fireblocks webhook events by validating the signature attached in the request header:

**Fireblocks-Signature:** `Base64(RSA512(_WEBHOOK_PRIVATE_KEY_, SHA512(eventBody)))`

To validate the signature in **Production workspaces**, please use the public key below:

```yaml theme={"system"}
-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA0+6wd9OJQpK60ZI7qnZG
jjQ0wNFUHfRv85Tdyek8+ahlg1Ph8uhwl4N6DZw5LwLXhNjzAbQ8LGPxt36RUZl5
YlxTru0jZNKx5lslR+H4i936A4pKBjgiMmSkVwXD9HcfKHTp70GQ812+J0Fvti/v
4nrrUpc011Wo4F6omt1QcYsi4GTI5OsEbeKQ24BtUd6Z1Nm/EP7PfPxeb4CP8KOH
clM8K7OwBUfWrip8Ptljjz9BNOZUF94iyjJ/BIzGJjyCntho64ehpUYP8UJykLVd
CGcu7sVYWnknf1ZGLuqqZQt4qt7cUUhFGielssZP9N9x7wzaAIFcT3yQ+ELDu1SZ
dE4lZsf2uMyfj58V8GDOLLE233+LRsRbJ083x+e2mW5BdAGtGgQBusFfnmv5Bxqd
HgS55hsna5725/44tvxll261TgQvjGrTxwe7e5Ia3d2Syc+e89mXQaI/+cZnylNP
SwCCvx8mOM847T0XkVRX3ZrwXtHIA25uKsPJzUtksDnAowB91j7RJkjXxJcz3Vh1
4k182UFOTPRW9jzdWNSyWQGl/vpe9oQ4c2Ly15+/toBo4YXJeDdDnZ5c/O+KKadc
IMPBpnPrH/0O97uMPuED+nI6ISGOTMLZo35xJ96gPBwyG5s2QxIkKPXIrhgcgUnk
tSM7QYNhlftT4/yVvYnk0YcCAwEAAQ==
-----END PUBLIC KEY-----
```

To validate the signature in **EU and EU2 workspaces**, use the public key below:

```yaml theme={"system"}
-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA6hLRQL0jPf5OEuaDYGjO
xSyaYIlv08S0+4giiwgKSfV3Onc5hn03mvE0znzaUq2ReSxi9KYDdMYFfzf1uwF7
7kYy2MY0oTYGdQb+PS4Ym4R4tgZ2otuoAXt8YRKq2maWyguFiaowMcYwwAVQv8JB
afIm6Jq1nI6v1mEDVX065ePlBlAt+BGAqr6ahPxnaIz3L4eztpuNrt5nTbSxs7eF
aqQx1p56W1nl3Hl0V3tLkaXbuVtbFNR/mGMInrkPnpsG+mt35b9vmqAOvLPI0Cx1
59uVeEs62Hj1AOCRyT6SuwIaFynRj2KnD42ioQtkodHQ0xDtgdiYGsxuwQ9vTIe7
5oLsL8gBDeX5gdcTfSZhfGjZ7RggLNJ7vCAbYKMuUOdgWVMYnJfrhNLCq3zDSZPO
+H0x5m/Yeq/Hn5o7xCmLNT3qARfwDd5IHfQyXqVYB6TMU75xqH5fdSRw0iMdoPyL
ALnr9/JT0av3qssNMRdWCXr+j9Ys3NkfcbU/a49657mg8e2QGSkl9w39csEKojnr
omUz25szIL8CcXLmc5cAmnimFCe4L7UT4mvVP3+fOo+cbc/82zqA8tsSwd2Y93/6
ueGnNZD9V5rewrKjmdPfrwoI2gntzc8QJUu+nxAWhoqHV91AQeglu6WIF/DiEJC5
WPoNk2SdlAuA6RYmgB2YyikCAwEAAQ==
-----END PUBLIC KEY-----
```

To validate the signature in **Sandbox workspaces**, please use the public key below:

```yaml theme={"system"}
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApZE6wL2+7P1ohvVYSpCd
gSgtmyGwiLbUC1UoGJhn1zwfY7ZWbNH7Pg8Osk8OzZTZHSG/arcgE8HnGCmGKtbE
QBkf2XlBRBQ01FcCMlZuJQJ3nElCPaMl9N6fq0VKNEIlVSVUpDCgvag5kFhDKS/L
p3YYJLFR46/hDlVLn+vM84diO3xGyMc16YJGNz7Z4jb8dmSZQE5E2XaQMDXW6uxC
c2ChjWJ3X5H70MzRG35JsN0j58SQTwbf4Pxm0aJfhPuaIBn3mJuZL5etsuFihoFG
FDnT+qWRcgD/pRNulBFAFhJeUnFrE4fFTJ1iaHhjBrStBCrxJk6QI0pGznoapTgA
2QIDAQAB
-----END PUBLIC KEY-----
```

### Check event objects

Each event is structured as an object with a type and a data sub-object that holds the transaction ID, as well as other related information. Your endpoint must check the event type and parse the payload of each event.

Example: transaction created webhook

```json theme={"system"}
{
    "type": "TRANSACTION_CREATED",
    "tenantId”:  ".........-.....-....-....-...........",
    "timestamp": 1679651214621,
    "data": {
        "id": "........-....-....-....-............",
        "createdAt": 1679651104380,
        "lastUpdated": 1679651104380,
        "assetId": "WETH_TEST3",
        "source": {
            "id": "0",
            "type": "VAULT_ACCOUNT",
            "name": "Main",
            "subType": ""
        },
        "destination": {
            "id": "12",
            "type": "VAULT_ACCOUNT",
            "name": "MintBurn",
            "subType": ""
        },
        "amount": 0.001,
        "sourceAddress": "",
        "destinationAddress": "",
        "destinationAddressDescription": "",
        "destinationTag": "",
        "status": "SUBMITTED",
        "txHash": "",
        "subStatus": "",
        "signedBy": [],
        "createdBy": ".........-.....-....-....-...........",
        "rejectedBy": "",
        "amountUSD": null,
        "addressType": "",
        "note": "",
        "exchangeTxId": "",
        "requestedAmount": 0.001,
        "feeCurrency": "ETH_TEST3",
        "operation": "TRANSFER",
        "customerRefId": null,
        "amountInfo": {
            "amount": "0.001",
            "requestedAmount": "0.001"
        },
        "feeInfo": {},
        "destinations": [],
        "externalTxId": null,
        "blockInfo": {},
        "signedMessages": [],
        "assetType": "ERC20"
    }
}
```

```json theme={"system"}
{
    "eventType": "TRANSACTION_CREATED",
    "tenantId”:  ".........-.....-....-....-...........",
 	  "resourceId”:  ".........-.....-....-....-...........",
    "eventVersion”:  1,
    "timestamp": 1679651214621,
    "data": {
        "id": "........-....-....-....-............",
        "createdAt": 1679651104380,
        "lastUpdated": 1679651104380,
        "assetId": "WETH_TEST3",
        "source": {
            "id": "0",
            "type": "VAULT_ACCOUNT",
            "name": "Main",
            "subType": ""
        },
        "destination": {
            "id": "12",
            "type": "VAULT_ACCOUNT",
            "name": "MintBurn",
            "subType": ""
        },
        "amount": 0.001,
        "sourceAddress": "",
        "destinationAddress": "",
        "destinationAddressDescription": "",
        "destinationTag": "",
        "status": "SUBMITTED",
        "txHash": "",
        "subStatus": "",
        "signedBy": [],
        "createdBy": ".........-.....-....-....-...........",
        "rejectedBy": "",
        "amountUSD": null,
        "addressType": "",
        "note": "",
        "exchangeTxId": "",
        "requestedAmount": 0.001,
        "feeCurrency": "ETH_TEST3",
        "operation": "TRANSFER",
        "customerRefId": null,
        "amountInfo": {
            "amount": "0.001",
            "requestedAmount": "0.001"
        },
        "feeInfo": {},
        "destinations": [],
        "externalTxId": null,
        "blockInfo": {},
        "signedMessages": [],
        "assetType": "ERC20"
    }
}
```

Example: transaction status updated webhook

```json theme={"system"}
{
    "type": "TRANSACTION_STATUS_UPDATED",
    "tenantId”:  ".........-.....-....-....-...........",
    "timestamp": 1679651214621,
    "data": {
        "id": "........-....-....-....-............",
        "createdAt": 1680014718734,
        "lastUpdated": 1680014729691,
        "assetId": "TRX_USDT",
        "source": {
            "id": "",
            "type": "UNKNOWN",
            "name": "External",
            "subType": ""
        },
        "destination": {
            "id": "2107",
            "type": "VAULT_ACCOUNT",
            "name": "Main",
            "subType": ""
        },
        "amount": 370,
        "networkFee": 27.2559,
        "netAmount": 370,
        "sourceAddress": "",
        "destinationAddress": "",
        "destinationAddressDescription": "",
        "destinationTag": "",
        "status": "COMPLETED",
        "txHash": "e9e1asdade125be06638c8675fdsfsdc79594dd45ff095b7683c3f03b81a9389684",
        "subStatus": "CONFIRMED",
        "signedBy": [],
        "createdBy": "",
        "rejectedBy": "",
        "amountUSD": 0,
        "addressType": "",
        "note": "",
        "exchangeTxId": "",
        "requestedAmount": 370,
        "feeCurrency": "TRX",
        "operation": "TRANSFER",
        "customerRefId": "........-....-....-....-............",
        "numOfConfirmations": 1,
        "amountInfo": {
            "amount": "370",
            "requestedAmount": "370",
            "netAmount": "370",
            "amountUSD": null
        },
        "feeInfo": {
            "networkFee": "27.2559"
        },
        "destinations": [],
        "externalTxId": null,
        "blockInfo": {
            "blockHeight": "49800684",
            "blockHash": "0000000002f7e5ece07efd8dfnjngfh76dda5f2645a9aba5e6h4534ba1bc7d97a8e2"
        },
        "signedMessages": [],
        "amlScreeningResult": {
            "screeningStatus": "BYPASSED",
            "bypassReason": "PASSED_BY_POLICY",
            "timestamp": 1680014729455
        },
        "assetType": "TRON_TRC20"
    }
}
```

```json theme={"system"}
{
    "eventType": "TRANSACTION_STATUS_UPDATED",
    "tenantId”:  ".........-.....-....-....-...........",
 	  "resourceId”:  ".........-.....-....-....-...........",
    "eventVersion”:  1,
    "timestamp": 1679651214621,
    "data": {
        "id": "........-....-....-....-............",
        "createdAt": 1679651104380,
        "lastUpdated": 1679651104380,
        "assetId": "WETH_TEST3",
        "source": {
            "id": "0",
            "type": "VAULT_ACCOUNT",
            "name": "Main",
            "subType": ""
        },
        "destination": {
            "id": "12",
            "type": "VAULT_ACCOUNT",
            "name": "MintBurn",
            "subType": ""
        },
        "amount": 0.001,
        "sourceAddress": "",
        "destinationAddress": "",
        "destinationAddressDescription": "",
        "destinationTag": "",
        "status": "SUBMITTED",
        "txHash": "",
        "subStatus": "",
        "signedBy": [],
        "createdBy": ".........-.....-....-....-...........",
        "rejectedBy": "",
        "amountUSD": null,
        "addressType": "",
        "note": "",
        "exchangeTxId": "",
        "requestedAmount": 0.001,
        "feeCurrency": "ETH_TEST3",
        "operation": "TRANSFER",
        "customerRefId": null,
        "amountInfo": {
            "amount": "0.001",
            "requestedAmount": "0.001"
        },
        "feeInfo": {},
        "destinations": [],
        "externalTxId": null,
        "blockInfo": {},
        "signedMessages": [],
        "assetType": "ERC20"
    }
}
```

### Response

The Fireblocks server will look for a response to confirm the webhook notification was received. All webhook events should receive an HTTP 200 (OK) response.

If no response is received, Fireblocks will resend the 5xx request several more times. The retry schedule (in seconds) is 5, 15, 35, 75, 155, 315, 635, 1275, 2555 for webhooks v1. For webhooks v2, the retry schedule (in seconds) is 0, 30, 120, 300, 900, 1800, 3600, 7200, 14400.


# Web3 Connection Objects
Source: https://developers.fireblocks.com/reference/web3-connection-objects



## SessionMetadata

| Parameter      | Type   | Description                                |
| -------------- | ------ | ------------------------------------------ |
| appUrl         | string | URL for Walletconnect Web3 dapp            |
| appName        | string | Display name for the Web3 dApp             |
| appDescription | string | Description of the Web3 dApp               |
| appIcon        | string | Given ticker symbol to represent the dApp. |

***

## SessionDTO

| Parameter        | Type                   | Description                                                                                              |
| ---------------- | ---------------------- | -------------------------------------------------------------------------------------------------------- |
| id               | string                 | The ID of the connection.                                                                                |
| userId           | string                 | The ID of the user that created the connection.                                                          |
| sessionMetadata  | SessionMetadata object | Metadata of the connection (provided by the dApp).                                                       |
| vaultAccountId   | string                 | The vault to connect.                                                                                    |
| feeLevel         | string                 | The default fee level. Valid values are `MEDIUM` and `HIGH`.                                             |
| chainIds         | array                  | The chains approved for the connection.                                                                  |
| connectionType   | string                 | The connection's type - Valid value: "WalletConnect".                                                    |
| connectionMethod | string                 | The method through which the connection was established. Valid values are: "DESKTOP", "MOBILE" or "API". |
| creationDate     | string                 | Timestamp of the session's creation.                                                                     |

***

## GetConnectionResponse

| Parameter | Type              | Description                                      |
| --------- | ----------------- | ------------------------------------------------ |
| data      | SessionDTO object | Array with the requested Web3 connection's data. |
| paging    | Paging            | Paging cursor settings                           |

***

## CreateConnectionRequest

| Parameter      | Type   | Description                                                      |
| -------------- | ------ | ---------------------------------------------------------------- |
| vaultAccountId | string | The ID of the vault to connect to the Web3 connection.           |
| feeLevel       | string | The default fee level. Valid values are `MEDIUM` and `HIGH`.     |
| uri            | string | The WalletConnect URI provided by the dApp.                      |
| chainIds       | array  | The ID of the blockchain network(s) used in the Web3 connection. |

***

## CreateConnectionResponse

| Parameter       | Type   | Description                                             |
| --------------- | ------ | ------------------------------------------------------- |
| id              | string | The ID of the initiated Web3 connection.                |
| sessionMetadata | array  | Metadata of the Web3 connection (provided by the dApp). |

***

## RespondToConnectionRequest

| Parameter | Type    | Description                                                             |
| --------- | ------- | ----------------------------------------------------------------------- |
| approve   | boolean | Approval of the initiated Web3 connection. The default value is "true". |


# Webhook Object
Source: https://developers.fireblocks.com/reference/webhook-object



## ResendWebhooksResponse

| Parameter     | Type   | Description                                 |
| ------------- | ------ | ------------------------------------------- |
| messagesCount | number | The number of re-sent webhook notifications |


# Protecting webhooks
Source: https://developers.fireblocks.com/reference/webhook-protection-guide



This guide covers securing your Fireblocks webhook integration through three methods of protection: IP allowlisting, signature verification and balance validation.

## Three methods

Each method is explained in detail in the linked articles below:

| Method                                                   | Purpose                     |
| -------------------------------------------------------- | --------------------------- |
| [IP Allowlisting](/reference/webhooks-ip-allowlisting)   | Network-level filtering     |
| [Signature Verification](/reference/validating-webhooks) | Cryptographic authenticity  |
| [Balance Validation](/docs/validate-balances)            | Business logic verification |

<br />


# Migration Guide
Source: https://developers.fireblocks.com/reference/webhook-v2-migration-guide



> **Deprecation notice**
>
> Webhooks v1 will be deprecated on **June 15th, 2026**. Please use the Developer Center in the Fireblocks Console to upgrade to Webhooks V2, which offers improved reliability, performance, and observability.

# Overview

The new Webhooks V2 service provides a more robust, reliable, faster, and feature-rich integration experience. While the new system introduces many enhanced capabilities, it also deprecates some existing features to streamline functionality and improve performance.

## Key benefits

* **Improved performance**: Reduced response times and increased resiliency.
* **Events catalog**: Subscribe to specific events or event categories.
* **Visibility**: New UI for notifications and send attempts.
* **Enhanced controls**: UI and API management, including notifications, resend up to 30 days.
* **No holdups**: Removed existing 10s inherent delay used in V1 to best-effort order messages.

> **Before you begin**
>
> * This page is not intended to serve as an implementation guide. It only highlights the differences between the Webhooks v1 and Webhooks v2 services and provides an event mapping table.
> * Ensure that you review *all* Webhooks v2 documentation and implement the service according to your organization's best practices.
> * If your organization requires IP addresses to be allowlisted, please note that the IP addresses required for Webhooks v2 are different from those of Webhooks v1. Learn more [here](/reference/webhooks-ip-allowlisting).

***

# Changelog

## Events

* **Event catalog & subscriptions:** Browse the event catalog and subscribe only to the categories or specific event types relevant to your use case. This lets you focus on the events you need, reduce unnecessary processing, and maintain a cleaner integration.
* **Event types:** We introduced a new syntax for event types. Use the table below to map your Webhooks v1 events to the new Webhooks v2 syntax.
* **Event ordering:** While we attempt to send notifications in order (per resource), Fireblocks doesn’t guarantee delivery of events in the order in which they’re generated. **Your endpoint shouldn’t expect the delivery of events in order.**

## Resend capability

We now allow resending events for up to 30 days from the original event timestamp.
To initiate a resend, use the **resourceId** field of the event's data object. Please note that you can only resend events once every five minutes.

## Improved retry logic

Retry attempts for failed webhook deliveries now span a longer time window to help ensure delivery success.

## Error rate monitoring & disabling

Webhooks with an error rate exceeding a specific threshold will be automatically disabled to protect the system integrity.
You should handle events asynchronously with queues and quickly return a 2xx status code to prevent performance issues in your application

***

# Notifications object differentiation

The new webhook payload format is designed for clarity and extensibility. Below is the structure of the new payload:

| Old field | New field   | Type          | Description                                                                                                            |
| --------- | ----------- | ------------- | ---------------------------------------------------------------------------------------------------------------------- |
| -         | id          | string (UUID) | Unique identifier for the webhook notification object.                                                                 |
| type      | eventType   | enum          | Description of the event (e.g., `transaction.created`).                                                                |
| -         | resourceId  | string (UUID) | (Optional) ID of the entity that triggered the event (e.g., `txid`).                                                   |
| data      | data        | object        | Contains the API resource relevant to the event (e.g., the full transaction object for a `transaction.created` event). |
| timestamp | createdAt   | number        | Webhook timestamp.                                                                                                     |
| tenantId  | workspaceId | string (UUID) | The tenant or workspace identifier associated with the event.                                                          |

> **Notification object has been updated**
>
> Although the event payload remains unchanged, the notification object has been updated, requiring some adjustments on your end for parsing. Additionally, you’ll need to register your webhook listener on Push API V2 to start using it.

## Key changes

* **id**: Unique identifier for the webhook notification object.
* **type** → **eventType**: Unified event naming for consistency.
* **resourceId**: Introduced to enable precise identification of the entity associated with the event.
* **tenantId** → **workspaceId**: The tenant/workspace identifier associated with the event.
* **timestamp** → **createdAt**: Describes when the webhook was created.

***

# Event mapping from v1 to v2

Use the table below to help you map your Webhooks v1 events to your Webhooks v2 events.

| V1 Category                          | V1 Event Type                                      | V2 Category     | V2 Event Type                                  |
| ------------------------------------ | -------------------------------------------------- | --------------- | ---------------------------------------------- |
| Transactions                         | TRANSACTION\\\_CREATED                             | Transactions    | transaction.created                            |
| Transactions                         | TRANSACTION\\\_STATUS\\\_UPDATED                   | Transactions    | transaction.status.updated                     |
| Transactions                         | TRANSACTIONS\\\_APPROVAL\\\_STATUS\\\_UPDATED      | Transactions    | transaction.approval\\\_status.updated         |
| Internal, External & Contract Wallet | EXTERNAL\\\_WALLET\\\_ASSET\\\_ADDED               | Whitelist       | external\\\_wallet.asset.added                 |
| Internal, External & Contract Wallet | EXTERNAL\\\_WALLET\\\_ASSET\\\_REMOVED             | Whitelist       | external\\\_wallet.asset.removed               |
| Internal, External & Contract Wallet | INTERNAL\\\_WALLET\\\_ASSET\\\_ADDED               | Whitelist       | internal\\\_wallet.asset.added                 |
| Internal, External & Contract Wallet | INTERNAL\\\_WALLET\\\_ASSET\\\_REMOVED             | Whitelist       | internal\\\_wallet.asset.removed               |
| Internal, External & Contract Wallet | CONTRACT\\\_WALLET\\\_ASSET\\\_ADDED               | Whitelist       | contract\\\_wallet.asset.added                 |
| Internal, External & Contract Wallet | CONTRACT\\\_WALLET\\\_ASSET\\\_REMOVED             | Whitelist       | contract\\\_wallet.asset.removed               |
| Vault                                | VAULT\\\_ACCOUNT\\\_ADDED                          | Wallet          | vault\\\_account.created                       |
| Vault                                | VAULT\\\_ACCOUNT\\\_ASSET\\\_ADDED                 | Wallet          | vault\\\_account.asset.added                   |
| Vault                                | VAULT\\\_BALANCE\\\_UPDATE                         | Wallet          | vault\\\_account.asset.balance\\\_updated      |
| NFT                                  | VAULT\\\_ACCOUNT\\\_NFT\\\_BALANCE\\\_UPDATED      | Wallet          | vault\\\_account.nft.balance\\\_updated        |
| Embedded Wallet                      | NCW\\\_STATUS\\\_UPDATED                           | Embedded Wallet | embedded\\\_wallet.status.updated              |
| Embedded Wallet                      | NCW\\\_STATUS\\\_CREATED                           | Embedded Wallet | embedded\\\_wallet.account.created             |
| Embedded Wallet                      | NCW\\\_ASSET\\\_CREATED                            | Embedded Wallet | embedded\\\_wallet.asset.added                 |
| Embedded Wallet                      | NCW\\\_BALANCE\\\_UPDATED                          | Embedded Wallet | embedded\\\_wallet.asset.balance\\\_updated    |
| Embedded Wallet                      | NCW\\\_ADD\\\_DEVICE\\\_SETUP\\\_REQUESTED         | Embedded Wallet | embedded\\\_wallet.device.added                |
| Exchange & Fiat Account              | EXCHANGE\\\_ACCOUNT\\\_ADDED                       | CeFi            | exchange\\\_account.added                      |
| Exchange & Fiat Account              | FIAT\\\_ACCOUNT\\\_ADDED                           | CeFi            | fiat\\\_account.added                          |
| Network Connection                   | NETWORK\\\_CONNECTION\\\_REMOVED                   | Network         | connection.removed                             |
| Network Connection                   | NETWORK\\\_CONNECTION\\\_ADDED                     | Network         | connection.added                               |
| Network Connection                   | WAITING\\\_FOR\\\_PEER\\\_APPROVAL                 | Network         | connection.request.waiting\\\_peer\\\_approval |
| Network Connection                   | REJECTED\\\_BY\\\_PEER                             | Network         | connection.request.rejected\\\_by\\\_peer      |
| Smart Transfer                       | TICKET\\\_CREATED                                  | Smart Transfer  | ticket.created                                 |
| Smart Transfer                       | TICKET\\\_SUBMITTED                                | Smart Transfer  | ticket.submitted                               |
| Smart Transfer                       | TICKET\\\_EXPIRED                                  | Smart Transfer  | ticket.expired                                 |
| Smart Transfer                       | TICKET\\\_CANCELED                                 | Smart Transfer  | ticket.canceled                                |
| Smart Transfer                       | TICKET\\\_FULFILLED                                | Smart Transfer  | ticket.fulfilled                               |
| Smart Transfer                       | TICKET\\\_COUNTERPARTY\\\_ADDED                    | Smart Transfer  | ticket.counterparty.added                      |
| Smart Transfer                       | TICKET\\\_COUNTERPARTY\\\_EXTERNAL\\\_ID\\\_SET    | Smart Transfer  | ticket.counterparty\\\_external\\\_id.set      |
| Smart Transfer                       | TICKET\\\_NOTE\\\_ADDED                            | Smart Transfer  | ticket.note.added                              |
| Smart Transfer                       | TICKET\\\_EXPIRES\\\_IN\\\_SET                     | Smart Transfer  | ticket.expires\\\_in.set                       |
| Smart Transfer                       | TICKET\\\_EXPIRES\\\_AT\\\_SET                     | Smart Transfer  | ticket.expires\\\_at.set                       |
| Smart Transfer                       | TICKET\\\_TERM\\\_ADDED                            | Smart Transfer  | ticket.term.added                              |
| Smart Transfer                       | TICKET\\\_TERM\\\_UPDATED                          | Smart Transfer  | ticket.term.updated                            |
| Smart Transfer                       | TICKET\\\_TERM\\\_DELETED                          | Smart Transfer  | ticket.term.deleted                            |
| Smart Transfer                       | TICKET\\\_TERM\\\_FUNDED                           | Smart Transfer  | ticket.term.funded                             |
| Smart Transfer                       | TICKET\\\_TERM\\\_MANUALLY\\\_FUNDED               | Smart Transfer  | ticket.term.manually\\\_funded                 |
| Smart Transfer                       | TICKET\\\_TERM\\\_FUNDING\\\_CANCELED              | Smart Transfer  | ticket.term.funding\\\_canceled                |
| Smart Transfer                       | TICKET\\\_TERM\\\_FUNDING\\\_FAILED                | Smart Transfer  | ticket.term.funding\\\_failed                  |
| Smart Transfer                       | TICKET\\\_TERM\\\_FUNDING\\\_COMPLETED             | Smart Transfer  | ticket.term.funding\\\_completed               |
| Smart Transfer                       | TICKET\\\_TERM\\\_TRANSACTION\\\_STATUS\\\_CHANGED | Smart Transfer  | ticket.term.transaction\\\_status\\\_changed   |
| Off Exchange                         | SETTLEMENT\\\_CREATED                              | Off Exchange    | settlement.created                             |
| Off Exchange                         | COLLATERAL\\\_SIGNER\\\_READY\\\_EVENT             | Off Exchange    | collateral.status.updated                      |

***

# FAQ

## Is it easy to revert to our original implementation if something goes wrong?

The implementation of the new webhooks is not a migration but a completely new service that runs alongside the original version (V1). You can maintain both integrations in parallel until you're confident in the new setup. This ensures a smooth transition without needing to revert.

## How long can I run both services simultaneously?

Both services will run in parallel until the Webhooks v1 service is officially sunset by June 15th, 2026.

## Are there changes to the payload or our business logic?

The payload and your business logic remain the same. However, the notification object has changed, and you will need to register your webhook server on Push API V2 to start using it.

## Are new events backwards-compatible with Webhooks v1?

No, and moving forward, new events that we develop will only be supported by the Webhooks v2 service.

## Where can I get help during the migration process?

Fireblocks Support is always available to assist you with any questions or concerns. If you need assistance, please [submit a request](https://support.fireblocks.io/hc/en-us/requests/new?ticket_form_id=360003372200).

## What happens if I don't migrate by the end-of-life (EOL) date?

We recommend you migrate to the Webhooks v2 service before then. After the EOL date, we will no longer support or provide access to the Webhooks v1 service.


# Best practices for webhooks
Source: https://developers.fireblocks.com/reference/webhooks-best-practices



Webhooks provide transaction status and balance updates. We recommend using webhooks instead of synchronously polling transaction and balance endpoints. This approach is more efficient and better supports internal reconciliation logic.

## Triggering internal logic on incoming transactions

When an incoming transaction triggers internal logic on your side (for example, sweeping), we recommend triggering that logic only after receiving the balance update webhook, rather than acting on the incoming transaction webhook alone. Additionally, verify that the wallet balance update reflects the same block height as the transaction.

> Acting on the incoming transaction webhook before the balance is confirmed can lead to reconciliation errors. Always wait for the balance update webhook and cross-check the block height before proceeding.

***

## Handle events asynchronously

Configure your handler to process incoming events with an asynchronous queue. Processing transactions synchronously can lead to long response times and potential timeouts, particularly during periods of high market volatility when transaction volumes surge.

If all events are handled synchronously, sudden surges in activity could overwhelm your system and degrade performance. Asynchronous queues allow you to manage these transaction bursts efficiently, ensuring your system processes events at a sustainable rate without bottlenecks or failures.

***

## Respond with a 2xx status promptly

Your endpoint should return a successful 2xx status code as soon as possible, before executing any time-consuming logic that might lead to a timeout. For instance, send a 200 response before processing tasks like marking a customer’s invoice as paid in your accounting system.

***

## Managing duplicate events

Your webhook endpoint may sometimes receive the same event multiple times. To prevent duplicate processing, track event IDs and ignore any that have already been handled.

Additionally, ensure you're processing the most recent event by comparing timestamps in the **createdAt** field, rather than relying solely on the event ID.

***

## Event ordering

Although Fireblocks strives to send notifications in order per resource, we cannot guarantee that events will always be delivered in the sequence they are generated. We recommend designing your endpoint to process events independently, without relying on their delivery order.

***

## Circuit breaker

Fireblocks introduces a circuit breaker mechanism for managing faulty webhook endpoints to ensure fairness and high throughput across all users. This feature helps identify and suspend endpoints that consistently fail, ensuring that system resources are optimized and reliable for everyone.

The circuit breaker monitors error rates for each webhook endpoint and applies suspension policies based on predefined thresholds. These policies vary depending on the type and severity of the errors. Webhooks with an error rate exceeding a specific threshold will be automatically disabled to protect system integrity.

To prevent performance issues in your application, handle events asynchronously with queues and quickly return a 2xx status code.

***

## Recovering from downtime

If your webhook server was offline for an hour or longer due to a deployment or network issue, you can resend all missed or failed webhook notifications for a given webhook. You can set the resend duration for up to 24 hours.


# Configuring webhooks
Source: https://developers.fireblocks.com/reference/webhooks-gettingstarted-configuringwebhooks



# Overview

There are two methods to configure webhooks using the Webhooks v2 service:

* Via the Fireblocks Console
* Via the Fireblocks API & SDKs (requires an API key with Admin-level permissions)

> **Before you begin**
>
> Please note the following:
>
> * Only Admin-level users (Owner, Admin, and Non-Signing Admin) can configure webhooks.
> * Each webhook URL must be a legal, globally available HTTPS address (e.g., [https://example.com](https://example.com)) accesible via **port 443**.
> * Webhook URLs cannot exceed 255 characters in length.
> * You can enter up to 10 webhook URLs.
>
> If you’re looking for information about Audit Event Webhooks for monitoring your workspace’s audit log, check out [this Help Center article](https://support.fireblocks.io/hc/en-us/articles/360022059440-Notification-Center) instead.

***

> **NOTE**
>
> Starting November 2025, `BALANCE_UPDATE` events are available through Webhooks V2. You can self-subscribe via the Console or API. Manual enablement by Fireblocks is no longer supported.

## Via the Console

### Creating a webhook

1. In the Fireblocks Console, go to **Developer center** > **Webhooks** and then select **Create webhook**.
2. On the Create webhook dialog, complete the following fields:
   1. **Endpoint URL:** Enter the webhook’s URL address.
   2. **Description:** Optionally, enter a short description of the webhook.
   3. **Status:** Select whether you want the webhook to be active or inactive.
   4. **Listen for:** Select an event category to listen for all its associated events, or select the specific events to listen for from each category.
3. Select **Create webhook**.

### Editing a webhook

1. In the Fireblocks Console, go to **Developer center** > **Webhooks**.
2. Find the webhook you want to edit, then select **More actions** (**...**) > **Edit webhook**.
3. On the Edit webhook dialog, make the necessary changes and then select **Save**.

### Deactivating & Activating a webhook

1. In the Fireblocks Console, go to **Developer center** > **Webhooks**.
2. Find the webhook you want to deactivate or activate, then select **More actions** (**...**) > **Deactivate webhook** or **Activate webhook**.
3. On the Deactivate or Activate webhook dialog, select **Deactivate** or **Activate**.

### Deleting a webhook

1. In the Fireblocks Console, go to **Developer center** > **Webhooks**.
2. Find the webhook you want to delete, then select **More actions** (**...**) > **Delete webhook**.
3. On the Delete webhook dialog, select **Delete**.

***

## Via the API & SDKs

### Creating a webhook

Use the **createWebhook** command, which uses the [Create a new webhook](/reference/createwebhook) endpoint.

```bash theme={"system"}
curl --request POST \
     --url 'https://api.fireblocks.io/v1/webhooks' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{"enabled":true}'
```

```typescript theme={"system"}
import { readFileSync } from 'fs';
import { Fireblocks, BasePath } from '@fireblocks/ts-sdk';
import type { FireblocksResponse, WebhooksV2ApiCreateWebhookRequest, Webhook } from '@fireblocks/ts-sdk';

// Set the environment variables for authentication
process.env.FIREBLOCKS_BASE_PATH = BasePath.Sandbox; // or assign directly to "https://sandbox-api.fireblocks.io/v1"
process.env.FIREBLOCKS_API_KEY = "my-api-key";
process.env.FIREBLOCKS_SECRET_KEY = readFileSync("./fireblocks_secret.key", "utf8");

const fireblocks = new Fireblocks();

let body: WebhooksV2ApiCreateWebhookRequest = {
  // CreateWebhookRequest
  createWebhookRequest: param_value,
  // string | A unique identifier for the request. If the request is sent multiple times with the same idempotency key, the server will return the same response as the first request. The idempotency key is valid for 24 hours. (optional)
  idempotencyKey: idempotencyKey_example,
};

fireblocks.webhooksV2.createWebhook(body).then((res: FireblocksResponse<Webhook>) => {
  console.log('API called successfully. Returned data: ' + JSON.stringify(res, null, 2));
}).catch((error:any) => console.error(error));
```

```python theme={"system"}
from fireblocks.models.create_webhook_request import CreateWebhookRequest
from fireblocks.models.webhook import Webhook
from fireblocks.client import Fireblocks
from fireblocks.client_configuration import ClientConfiguration
from fireblocks.exceptions import ApiException
from fireblocks.base_path import BasePath
from pprint import pprint

# load the secret key content from a file
with open('your_secret_key_file_path', 'r') as file:
    secret_key_value = file.read()

# build the configuration
configuration = ClientConfiguration(
        api_key="your_api_key",
        secret_key=secret_key_value,
        base_path=BasePath.Sandbox, # or set it directly to a string "https://sandbox-api.fireblocks.io/v1"
)

# Enter a context with an instance of the API client
with Fireblocks(configuration) as fireblocks:
    create_webhook_request = fireblocks.CreateWebhookRequest() # CreateWebhookRequest |
    idempotency_key = 'idempotency_key_example' # str | A unique identifier for the request. If the request is sent multiple times with the same idempotency key, the server will return the same response as the first request. The idempotency key is valid for 24 hours. (optional)

    try:
        # Create new webhook
        api_response = fireblocks.webhooks_v2.create_webhook(create_webhook_request, idempotency_key=idempotency_key).result()
        print("The response of WebhooksV2Api->create_webhook:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling WebhooksV2Api->create_webhook: %s\n" % e)
```

```java theme={"system"}
// Import classes:
import com.fireblocks.sdk.ApiClient;
import com.fireblocks.sdk.ApiException;
import com.fireblocks.sdk.ApiResponse;
import com.fireblocks.sdk.BasePath;
import com.fireblocks.sdk.Fireblocks;
import com.fireblocks.sdk.ConfigurationOptions;
import com.fireblocks.sdk.model.*;
import com.fireblocks.sdk.api.WebhooksV2Api;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;

public class Example {
    public static void main(String[] args) {
        ConfigurationOptions configurationOptions = new ConfigurationOptions()
            .basePath(BasePath.Sandbox)
            .apiKey("my-api-key")
            .secretKey("my-secret-key");
        Fireblocks fireblocks = new Fireblocks(configurationOptions);

        CreateWebhookRequest createWebhookRequest = new CreateWebhookRequest(); // CreateWebhookRequest |
        String idempotencyKey = "idempotencyKey_example"; // String | A unique identifier for the request. If the request is sent multiple times with the same idempotency key, the server will return the same response as the first request. The idempotency key is valid for 24 hours.
        try {
            CompletableFuture<ApiResponse<Webhook>> response = fireblocks.webhooksV2().createWebhook(createWebhookRequest, idempotencyKey);
            System.out.println("Status code: " + response.get().getStatusCode());
            System.out.println("Response headers: " + response.get().getHeaders());
            System.out.println("Response body: " + response.get().getData());
        } catch (InterruptedException | ExecutionException e) {
            ApiException apiException = (ApiException)e.getCause();
            System.err.println("Exception when calling WebhooksV2Api#createWebhook");
            System.err.println("Status code: " + apiException.getCode());
            System.err.println("Response headers: " + apiException.getResponseHeaders());
            System.err.println("Reason: " + apiException.getResponseBody());
            e.printStackTrace();
        } catch (ApiException e) {
            System.err.println("Exception when calling WebhooksV2Api#createWebhook");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Response headers: " + e.getResponseHeaders());
            System.err.println("Reason: " + e.getResponseBody());
            e.printStackTrace();
        }
    }
}
```

### Updating a webhook

Use the **updateWebhook** command, which uses the [Update webhook](/reference/updatewebhook) endpoint.

```bash theme={"system"}
curl --request PATCH \
     --url 'https://api.fireblocks.io/v1/webhooks/webhookId' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
```

```typescript theme={"system"}
import { readFileSync } from 'fs';
import { Fireblocks, BasePath } from '@fireblocks/ts-sdk';
import type { FireblocksResponse, WebhooksV2ApiUpdateWebhookRequest, Webhook } from '@fireblocks/ts-sdk';

// Set the environment variables for authentication
process.env.FIREBLOCKS_BASE_PATH = BasePath.Sandbox; // or assign directly to "https://sandbox-api.fireblocks.io/v1"
process.env.FIREBLOCKS_API_KEY = "my-api-key";
process.env.FIREBLOCKS_SECRET_KEY = readFileSync("./fireblocks_secret.key", "utf8");

const fireblocks = new Fireblocks();

let body: WebhooksV2ApiUpdateWebhookRequest = {
  // UpdateWebhookRequest
  updateWebhookRequest: param_value,
  // string | The unique identifier of the webhook
  webhookId: 44fcead0-7053-4831-a53a-df7fb90d440f,
};

fireblocks.webhooksV2.updateWebhook(body).then((res: FireblocksResponse<Webhook>) => {
  console.log('API called successfully. Returned data: ' + JSON.stringify(res, null, 2));
}).catch((error:any) => console.error(error));
```

```python theme={"system"}
from fireblocks.models.update_webhook_request import UpdateWebhookRequest
from fireblocks.models.webhook import Webhook
from fireblocks.client import Fireblocks
from fireblocks.client_configuration import ClientConfiguration
from fireblocks.exceptions import ApiException
from fireblocks.base_path import BasePath
from pprint import pprint

# load the secret key content from a file
with open('your_secret_key_file_path', 'r') as file:
    secret_key_value = file.read()

# build the configuration
configuration = ClientConfiguration(
        api_key="your_api_key",
        secret_key=secret_key_value,
        base_path=BasePath.Sandbox, # or set it directly to a string "https://sandbox-api.fireblocks.io/v1"
)

# Enter a context with an instance of the API client
with Fireblocks(configuration) as fireblocks:
    webhook_id = '44fcead0-7053-4831-a53a-df7fb90d440f' # str | The unique identifier of the webhook
    update_webhook_request = fireblocks.UpdateWebhookRequest() # UpdateWebhookRequest |

    try:
        # Update webhook
        api_response = fireblocks.webhooks_v2.update_webhook(webhook_id, update_webhook_request).result()
        print("The response of WebhooksV2Api->update_webhook:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling WebhooksV2Api->update_webhook: %s\n" % e)
```

```java theme={"system"}
// Import classes:
import com.fireblocks.sdk.ApiClient;
import com.fireblocks.sdk.ApiException;
import com.fireblocks.sdk.ApiResponse;
import com.fireblocks.sdk.BasePath;
import com.fireblocks.sdk.Fireblocks;
import com.fireblocks.sdk.ConfigurationOptions;
import com.fireblocks.sdk.model.*;
import com.fireblocks.sdk.api.WebhooksV2Api;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;

public class Example {
    public static void main(String[] args) {
        ConfigurationOptions configurationOptions = new ConfigurationOptions()
            .basePath(BasePath.Sandbox)
            .apiKey("my-api-key")
            .secretKey("my-secret-key");
        Fireblocks fireblocks = new Fireblocks(configurationOptions);

        UpdateWebhookRequest updateWebhookRequest = new UpdateWebhookRequest(); // UpdateWebhookRequest |
        UUID webhookId = UUID.fromString("44fcead0-7053-4831-a53a-df7fb90d440f"); // UUID | The unique identifier of the webhook
        try {
            CompletableFuture<ApiResponse<Webhook>> response = fireblocks.webhooksV2().updateWebhook(updateWebhookRequest, webhookId);
            System.out.println("Status code: " + response.get().getStatusCode());
            System.out.println("Response headers: " + response.get().getHeaders());
            System.out.println("Response body: " + response.get().getData());
        } catch (InterruptedException | ExecutionException e) {
            ApiException apiException = (ApiException)e.getCause();
            System.err.println("Exception when calling WebhooksV2Api#updateWebhook");
            System.err.println("Status code: " + apiException.getCode());
            System.err.println("Response headers: " + apiException.getResponseHeaders());
            System.err.println("Reason: " + apiException.getResponseBody());
            e.printStackTrace();
        } catch (ApiException e) {
            System.err.println("Exception when calling WebhooksV2Api#updateWebhook");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Response headers: " + e.getResponseHeaders());
            System.err.println("Reason: " + e.getResponseBody());
            e.printStackTrace();
        }
    }
}
```

### Deleting a webhook

Use the **deleteWebhook** command, which uses the [Delete a webhook](/reference/deletewebhook) endpoint.

```bash theme={"system"}
curl --request DELETE \
     --url 'https://api.fireblocks.io/v1/webhooks/webhookId' \
     --header 'accept: application/json'
```

```typescript theme={"system"}
import { readFileSync } from 'fs';
import { Fireblocks, BasePath } from '@fireblocks/ts-sdk';
import type { FireblocksResponse, WebhooksV2ApiDeleteWebhookRequest, Webhook } from '@fireblocks/ts-sdk';

// Set the environment variables for authentication
process.env.FIREBLOCKS_BASE_PATH = BasePath.Sandbox; // or assign directly to "https://sandbox-api.fireblocks.io/v1"
process.env.FIREBLOCKS_API_KEY = "my-api-key";
process.env.FIREBLOCKS_SECRET_KEY = readFileSync("./fireblocks_secret.key", "utf8");

const fireblocks = new Fireblocks();

let body: WebhooksV2ApiDeleteWebhookRequest = {
  // string | The unique identifier of the webhook
  webhookId: 44fcead0-7053-4831-a53a-df7fb90d440f,
};

fireblocks.webhooksV2.deleteWebhook(body).then((res: FireblocksResponse<Webhook>) => {
  console.log('API called successfully. Returned data: ' + JSON.stringify(res, null, 2));
}).catch((error:any) => console.error(error));
```

```python theme={"system"}
from fireblocks.models.webhook import Webhook
from fireblocks.client import Fireblocks
from fireblocks.client_configuration import ClientConfiguration
from fireblocks.exceptions import ApiException
from fireblocks.base_path import BasePath
from pprint import pprint

# load the secret key content from a file
with open('your_secret_key_file_path', 'r') as file:
    secret_key_value = file.read()

# build the configuration
configuration = ClientConfiguration(
        api_key="your_api_key",
        secret_key=secret_key_value,
        base_path=BasePath.Sandbox, # or set it directly to a string "https://sandbox-api.fireblocks.io/v1"
)

# Enter a context with an instance of the API client
with Fireblocks(configuration) as fireblocks:
    webhook_id = '44fcead0-7053-4831-a53a-df7fb90d440f' # str | The unique identifier of the webhook

    try:
        # Delete webhook
        api_response = fireblocks.webhooks_v2.delete_webhook(webhook_id).result()
        print("The response of WebhooksV2Api->delete_webhook:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling WebhooksV2Api->delete_webhook: %s\n" % e)
```

```java theme={"system"}
// Import classes:
import com.fireblocks.sdk.ApiClient;
import com.fireblocks.sdk.ApiException;
import com.fireblocks.sdk.ApiResponse;
import com.fireblocks.sdk.BasePath;
import com.fireblocks.sdk.Fireblocks;
import com.fireblocks.sdk.ConfigurationOptions;
import com.fireblocks.sdk.model.*;
import com.fireblocks.sdk.api.WebhooksV2Api;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;

public class Example {
    public static void main(String[] args) {
        ConfigurationOptions configurationOptions = new ConfigurationOptions()
            .basePath(BasePath.Sandbox)
            .apiKey("my-api-key")
            .secretKey("my-secret-key");
        Fireblocks fireblocks = new Fireblocks(configurationOptions);

        UUID webhookId = UUID.fromString("44fcead0-7053-4831-a53a-df7fb90d440f"); // UUID | The unique identifier of the webhook
        try {
            CompletableFuture<ApiResponse<Webhook>> response = fireblocks.webhooksV2().deleteWebhook(webhookId);
            System.out.println("Status code: " + response.get().getStatusCode());
            System.out.println("Response headers: " + response.get().getHeaders());
            System.out.println("Response body: " + response.get().getData());
        } catch (InterruptedException | ExecutionException e) {
            ApiException apiException = (ApiException)e.getCause();
            System.err.println("Exception when calling WebhooksV2Api#deleteWebhook");
            System.err.println("Status code: " + apiException.getCode());
            System.err.println("Response headers: " + apiException.getResponseHeaders());
            System.err.println("Reason: " + apiException.getResponseBody());
            e.printStackTrace();
        } catch (ApiException e) {
            System.err.println("Exception when calling WebhooksV2Api#deleteWebhook");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Response headers: " + e.getResponseHeaders());
            System.err.println("Reason: " + e.getResponseBody());
            e.printStackTrace();
        }
    }
}
```

***

> **Migrating to Webhooks v2 from Webhooks v1?**
>
> Start with our [Webhooks v2 Migration Guide](/reference/webhook-v2-migration-guide) to learn more about the benefits of and key changes in the Webhooks v2 service, and to find a mapping guide for converting your Webhooks v1 events to Webhooks v2 events.


# Responses & retries
Source: https://developers.fireblocks.com/reference/webhooks-gettingstarted-responsesretries



The Fireblocks server will look for a response to confirm the webhook notification was received. All webhook events should receive an HTTP 200 (OK) response.

If no response is received, Fireblocks will resend the 5xx request several more times. The retry schedule (in seconds) follows an exponential backoff of 10, 30, 120, 300, 900, 1800, 3600, 7200, and 14400.

## Retries for 4xx errors

Fireblocks will not attempt to retry sending webhook notifications for client-side errors (HTTP 4xx) except for the following cases:

* **429 - Too Many Requests**: Indicates rate limits have been exceeded.
* **408 - Request Timeout**: Indicates the server took too long to respond.

After a total of 10 failed attempts, the notification will be marked as failed, and no further retries will be made.

***


# IP allowlisting
Source: https://developers.fireblocks.com/reference/webhooks-ip-allowlisting



In some environments, firewalls or other security configurations may block incoming traffic unless it originates from approved IP addresses. If your environment requires IP addresses to be approved, you'll need to add the following outbound IP addresses used by Fireblocks to send webhooks.

Fireblocks strongly recommends validating webhook signatures instead of relying solely on IP addresses. Signature validation ensures the authenticity of the notification regardless of your network configuration.

## IP addresses by environment

### US environment

* 3.135.57.98

### EU environment

* 63.179.12.78

### EU2 environment

* 3.77.138.100

### Developer Sandbox environment

* 18.117.207.128


# Overview
Source: https://developers.fireblocks.com/reference/webhooks-overview



Webhooks allow your application to react to real-time events in your Fireblocks workspace, such as deposits, withdrawals, transaction status changes, and more by delivering structured event data directly to your servers as they happen.

They are ideal for automating operational workflows, keeping systems in sync, and reducing the need for manual processes or inefficient polling.

Fireblocks webhooks are particularly useful for:

* Triggering internal workflows on deposit confirmations or transaction completions
* Integrating with external systems such as CRMs, compliance tools, or accounting platforms
* Creating custom alerts for specific event types

Instead of continuously polling Fireblocks APIs, webhooks provide a more scalable, responsive, and performant way to receive updates as soon as they occur.

***

## Why use Fireblocks Webhooks V2?

With Webhooks V2, Fireblocks offers a modern, reliable event delivery system with advanced controls:

* **Event catalog & subscriptions:** Browse the event catalog and subscribe only to the categories or specific event types relevant to your use case. This lets you focus on the events you need, reduce unnecessary processing, and maintain a cleaner integration.
* **Resend events up to 30 days:** Missed an event? You can programmatically resend notifications for up to 30 days after the original event occurred.
* **Improved retry mechanism:** Failed webhook deliveries are retried over an extended period using exponential backoff, increasing the chance of successful delivery even during outages.
* **Structured notification format:** Webhooks are delivered in a consistent format that includes metadata, a resource identifier, and a timestamp, making integration straightforward and predictable.

***

## Webhooks vs. polling

Polling APIs involves repeatedly asking Fireblocks, “Has anything changed yet?” This process can be inefficient, slow, and make it easy to miss critical updates.

Webhooks flip that model: instead of constantly checking, your system gets notified the moment something happens. This makes webhooks ideal for real-time use cases where speed, efficiency, and reliability matter.

With polling:

* You risk missing events that happen between requests
* You consume unnecessary API quota and system resources
* You often need to write extra logic to check for changes and handle duplicates

With webhooks:

* You get immediate, push-based updates as soon as events occur
* You can subscribe only to the event types you care about
* You reduce latency, improve performance, and simplify your integration

***

## Example use cases

* Notifying your back office system of completed transactions
* Triggering a withdrawal approval workflow when a new request is initiated
* Syncing asset balances with an external accounting platform
* Sending a Slack alert when a large deposit is detected


# Resending & troubleshooting webhook notifications
Source: https://developers.fireblocks.com/reference/webhooks-resend-troubleshooting



Missed webhook notifications can occur due to various issues such as temporary downtime, connectivity problems, or unexpected errors in your webhook handler. These issues can prevent your server from acknowledging or processing events sent by Fireblocks.

To ensure no critical events are lost, Fireblocks provides multiple solutions for you to address your particular use case.

***

## Auto-retry mechanism

First, the Fireblocks server will look for a response to confirm the webhook notification was received. All webhook events should receive an HTTP 200 (OK) response.

If no response is received, Fireblocks will resend the 5xx request several more times. The retry schedule (in seconds) follows an exponential backoff of 10, 30, 120, 300, 900, 1800, 3600, 7200, and 14400.

### Retries for 4xx errors

Fireblocks will not attempt to retry sending webhook notifications for client-side errors (HTTP 4xx) except for the following cases:

* **429 - Too Many Requests:** Indicates rate limits have been exceeded.
* **408 - Request Timeout:** Indicates the server took too long to respond.

After a total of 10 failed attempts, the notification will be marked as failed, and no further retries will be made.

***

## Resending a single notification

Use this method when you need to troubleshoot or ensure the delivery of a specific event, such as a transaction update or status change.

> **Example use case**
>
> If your server fails to process a specific transaction notification, you can use this endpoint to retry only that notification, minimizing unnecessary retries.

### Via the Fireblocks Console

1. In the Fireblocks Console, go to **Developer center** > **Webhooks**, and then select the relevant endpoint URL from the Webhooks list.
2. In the Notification activity list, find the notification you want to resend and then select it.
3. On the Notification attempts dialog, select **Resend notification**.
4. Validate that you received the notification successfully.

### Via the Fireblocks API & SDKs

First, run the **getNotifications** command, which uses the [Get all notifications by webhook id](/reference/getnotifications) endpoint.

```bash theme={"system"}
curl --request GET \
     --url 'https://api.fireblocks.io/v1/webhooks/webhookId/notifications?order=DESC&pageSize=100' \
     --header 'accept: application/json'
```

```javascript theme={"system"}
import { readFileSync } from 'fs';
import { Fireblocks, BasePath } from '@fireblocks/ts-sdk';
import type { FireblocksResponse, WebhooksV2ApiGetNotificationsRequest, NotificationPaginatedResponse } from '@fireblocks/ts-sdk';

// Set the environment variables for authentication
process.env.FIREBLOCKS_BASE_PATH = BasePath.Sandbox; // or assign directly to "https://sandbox-api.fireblocks.io/v1"
process.env.FIREBLOCKS_API_KEY = "my-api-key";
process.env.FIREBLOCKS_SECRET_KEY = readFileSync("./fireblocks_secret.key", "utf8");

const fireblocks = new Fireblocks();

let body: WebhooksV2ApiGetNotificationsRequest = {
  // string
  webhookId: 44fcead0-7053-4831-a53a-df7fb90d440f,
  // 'ASC' | 'DESC' | ASC / DESC ordering (default DESC) (optional)
  order: ASC,
  // 'id' | 'createdAt' | 'updatedAt' | 'status' | 'eventType' | 'resourceId' | Sort by field (optional)
  sortBy: id,
  // string | Cursor of the required page (optional)
  pageCursor: pageCursor_example,
  // number | Maximum number of items in the page (optional)
  pageSize: 10,
};

fireblocks.webhooksV2.getNotifications(body).then((res: FireblocksResponse<NotificationPaginatedResponse>) => {
  console.log('API called successfully. Returned data: ' + JSON.stringify(res, null, 2));
}).catch((error:any) => console.error(error));
```

```python theme={"system"}
from fireblocks.models.notification_paginated_response import NotificationPaginatedResponse
from fireblocks.client import Fireblocks
from fireblocks.client_configuration import ClientConfiguration
from fireblocks.exceptions import ApiException
from fireblocks.base_path import BasePath
from pprint import pprint

# load the secret key content from a file
with open('your_secret_key_file_path', 'r') as file:
    secret_key_value = file.read()

# build the configuration
configuration = ClientConfiguration(
        api_key="your_api_key",
        secret_key=secret_key_value,
        base_path=BasePath.Sandbox, # or set it directly to a string "https://sandbox-api.fireblocks.io/v1"
)

# Enter a context with an instance of the API client
with Fireblocks(configuration) as fireblocks:
    webhook_id = '44fcead0-7053-4831-a53a-df7fb90d440f' # str |
    order = DESC # str | ASC / DESC ordering (default DESC) (optional) (default to DESC)
    sort_by = updatedAt # str | Sort by field (optional) (default to updatedAt)
    page_cursor = 'page_cursor_example' # str | Cursor of the required page (optional)
    page_size = 100 # float | Maximum number of items in the page (optional) (default to 100)

    try:
        # Get all notifications by webhook id
        api_response = fireblocks.webhooks_v2.get_notifications(webhook_id, order=order, sort_by=sort_by, page_cursor=page_cursor, page_size=page_size).result()
        print("The response of WebhooksV2Api->get_notifications:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling WebhooksV2Api->get_notifications: %s\n" % e)
```

```java theme={"system"}
// Import classes:
import com.fireblocks.sdk.ApiClient;
import com.fireblocks.sdk.ApiException;
import com.fireblocks.sdk.ApiResponse;
import com.fireblocks.sdk.BasePath;
import com.fireblocks.sdk.Fireblocks;
import com.fireblocks.sdk.ConfigurationOptions;
import com.fireblocks.sdk.model.*;
import com.fireblocks.sdk.api.WebhooksV2Api;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;

public class Example {
    public static void main(String[] args) {
        ConfigurationOptions configurationOptions = new ConfigurationOptions()
            .basePath(BasePath.Sandbox)
            .apiKey("my-api-key")
            .secretKey("my-secret-key");
        Fireblocks fireblocks = new Fireblocks(configurationOptions);

        UUID webhookId = UUID.fromString("44fcead0-7053-4831-a53a-df7fb90d440f"); // UUID |
        String order = "ASC"; // String | ASC / DESC ordering (default DESC)
        String sortBy = "id"; // String | Sort by field
        String pageCursor = "pageCursor_example"; // String | Cursor of the required page
        BigDecimal pageSize = new BigDecimal("100"); // BigDecimal | Maximum number of items in the page
        try {
            CompletableFuture<ApiResponse<NotificationPaginatedResponse>> response = fireblocks.webhooksV2().getNotifications(webhookId, order, sortBy, pageCursor, pageSize);
            System.out.println("Status code: " + response.get().getStatusCode());
            System.out.println("Response headers: " + response.get().getHeaders());
            System.out.println("Response body: " + response.get().getData());
        } catch (InterruptedException | ExecutionException e) {
            ApiException apiException = (ApiException)e.getCause();
            System.err.println("Exception when calling WebhooksV2Api#getNotifications");
            System.err.println("Status code: " + apiException.getCode());
            System.err.println("Response headers: " + apiException.getResponseHeaders());
            System.err.println("Reason: " + apiException.getResponseBody());
            e.printStackTrace();
        } catch (ApiException e) {
            System.err.println("Exception when calling WebhooksV2Api#getNotifications");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Response headers: " + e.getResponseHeaders());
            System.err.println("Reason: " + e.getResponseBody());
            e.printStackTrace();
        }
    }
}
```

After you retrieve the **id** value from the notification you want to resend, use the **resendNotificationById** command, which uses the [Resend notification by ID](/reference/resendnotificationbyid) endpoint.

```bash theme={"system"}
curl --request POST \
     --url 'https://api.fireblocks.io/v1/webhooks/webhookId/notifications/notificationId/resend' \
     --header 'accept: application/json'
```

```javascript theme={"system"}
import { readFileSync } from 'fs';
import { Fireblocks, BasePath } from '@fireblocks/ts-sdk';
import type { FireblocksResponse, WebhooksV2ApiResendNotificationByIdRequest } from '@fireblocks/ts-sdk';

// Set the environment variables for authentication
process.env.FIREBLOCKS_BASE_PATH = BasePath.Sandbox; // or assign directly to "https://sandbox-api.fireblocks.io/v1"
process.env.FIREBLOCKS_API_KEY = "my-api-key";
process.env.FIREBLOCKS_SECRET_KEY = readFileSync("./fireblocks_secret.key", "utf8");

const fireblocks = new Fireblocks();

let body: WebhooksV2ApiResendNotificationByIdRequest = {
  // string | The ID of the webhook
  webhookId: webhookId_example,
  // string | The ID of the notification
  notificationId: notificationId_example,
  // string | A unique identifier for the request. If the request is sent multiple times with the same idempotency key, the server will return the same response as the first request. The idempotency key is valid for 24 hours. (optional)
  idempotencyKey: idempotencyKey_example,
};

fireblocks.webhooksV2.resendNotificationById(body).then((res: FireblocksResponse<any>) => {
  console.log('API called successfully. Returned data: ' + JSON.stringify(res, null, 2));
}).catch((error:any) => console.error(error));
```

```python theme={"system"}
from fireblocks.client import Fireblocks
from fireblocks.client_configuration import ClientConfiguration
from fireblocks.exceptions import ApiException
from fireblocks.base_path import BasePath

# load the secret key content from a file
with open('your_secret_key_file_path', 'r') as file:
    secret_key_value = file.read()

# build the configuration
configuration = ClientConfiguration(
        api_key="your_api_key",
        secret_key=secret_key_value,
        base_path=BasePath.Sandbox, # or set it directly to a string "https://sandbox-api.fireblocks.io/v1"
)

# Enter a context with an instance of the API client
with Fireblocks(configuration) as fireblocks:
    webhook_id = 'webhook_id_example' # str | The ID of the webhook
    notification_id = 'notification_id_example' # str | The ID of the notification
    idempotency_key = 'idempotency_key_example' # str | A unique identifier for the request. If the request is sent multiple times with the same idempotency key, the server will return the same response as the first request. The idempotency key is valid for 24 hours. (optional)

    try:
        # Resend notification by id
        fireblocks.webhooks_v2.resend_notification_by_id(webhook_id, notification_id, idempotency_key=idempotency_key).result()
    except Exception as e:
        print("Exception when calling WebhooksV2Api->resend_notification_by_id: %s\n" % e)
```

```java theme={"system"}
// Import classes:
import com.fireblocks.sdk.ApiClient;
import com.fireblocks.sdk.ApiException;
import com.fireblocks.sdk.ApiResponse;
import com.fireblocks.sdk.BasePath;
import com.fireblocks.sdk.Fireblocks;
import com.fireblocks.sdk.ConfigurationOptions;
import com.fireblocks.sdk.model.*;
import com.fireblocks.sdk.api.WebhooksV2Api;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;

public class Example {
    public static void main(String[] args) {
        ConfigurationOptions configurationOptions = new ConfigurationOptions()
            .basePath(BasePath.Sandbox)
            .apiKey("my-api-key")
            .secretKey("my-secret-key");
        Fireblocks fireblocks = new Fireblocks(configurationOptions);

        String webhookId = "webhookId_example"; // String | The ID of the webhook
        String notificationId = "notificationId_example"; // String | The ID of the notification
        String idempotencyKey = "idempotencyKey_example"; // String | A unique identifier for the request. If the request is sent multiple times with the same idempotency key, the server will return the same response as the first request. The idempotency key is valid for 24 hours.
        try {
            CompletableFuture<ApiResponse<Void>> response = fireblocks.webhooksV2().resendNotificationById(webhookId, notificationId, idempotencyKey);
            System.out.println("Status code: " + response.get().getStatusCode());
            System.out.println("Response headers: " + response.get().getHeaders());
        } catch (InterruptedException | ExecutionException e) {
            ApiException apiException = (ApiException)e.getCause();
            System.err.println("Exception when calling WebhooksV2Api#resendNotificationById");
            System.err.println("Status code: " + apiException.getCode());
            System.err.println("Response headers: " + apiException.getResponseHeaders());
            System.err.println("Reason: " + apiException.getResponseBody());
            e.printStackTrace();
        } catch (ApiException e) {
            System.err.println("Exception when calling WebhooksV2Api#resendNotificationById");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Response headers: " + e.getResponseHeaders());
            System.err.println("Reason: " + e.getResponseBody());
            e.printStackTrace();
        }
    }
}
```

Lastly, validate that you received the notification successfully.

***

## Resending multiple notifications by resource ID

Use this method when you need to resend notifications for a particular resource, such as a vault account or transaction, after resolving server-side issues. This method will resend all notifications generated over the last 30 days for that resource.

> **Example use case**
>
> If your webhook server missed updates for a specific transaction due to an outage, you can use this endpoint to retrieve all missed notifications related to that transaction.

### Via the Fireblocks API & SDKs

First, run the **getNotifications** command, which uses the [Get all notifications by webhook id](/reference/getnotifications) endpoint.

```bash theme={"system"}
curl --request GET \
     --url 'https://api.fireblocks.io/v1/webhooks/webhookId/notifications?order=DESC&pageSize=100' \
     --header 'accept: application/json'
```

```javascript theme={"system"}
import { readFileSync } from 'fs';
import { Fireblocks, BasePath } from '@fireblocks/ts-sdk';
import type { FireblocksResponse, WebhooksV2ApiGetNotificationsRequest, NotificationPaginatedResponse } from '@fireblocks/ts-sdk';

// Set the environment variables for authentication
process.env.FIREBLOCKS_BASE_PATH = BasePath.Sandbox; // or assign directly to "https://sandbox-api.fireblocks.io/v1"
process.env.FIREBLOCKS_API_KEY = "my-api-key";
process.env.FIREBLOCKS_SECRET_KEY = readFileSync("./fireblocks_secret.key", "utf8");

const fireblocks = new Fireblocks();

let body: WebhooksV2ApiGetNotificationsRequest = {
  // string
  webhookId: 44fcead0-7053-4831-a53a-df7fb90d440f,
  // 'ASC' | 'DESC' | ASC / DESC ordering (default DESC) (optional)
  order: ASC,
  // 'id' | 'createdAt' | 'updatedAt' | 'status' | 'eventType' | 'resourceId' | Sort by field (optional)
  sortBy: id,
  // string | Cursor of the required page (optional)
  pageCursor: pageCursor_example,
  // number | Maximum number of items in the page (optional)
  pageSize: 10,
};

fireblocks.webhooksV2.getNotifications(body).then((res: FireblocksResponse<NotificationPaginatedResponse>) => {
  console.log('API called successfully. Returned data: ' + JSON.stringify(res, null, 2));
}).catch((error:any) => console.error(error));
```

```python theme={"system"}
from fireblocks.models.notification_paginated_response import NotificationPaginatedResponse
from fireblocks.client import Fireblocks
from fireblocks.client_configuration import ClientConfiguration
from fireblocks.exceptions import ApiException
from fireblocks.base_path import BasePath
from pprint import pprint

# load the secret key content from a file
with open('your_secret_key_file_path', 'r') as file:
    secret_key_value = file.read()

# build the configuration
configuration = ClientConfiguration(
        api_key="your_api_key",
        secret_key=secret_key_value,
        base_path=BasePath.Sandbox, # or set it directly to a string "https://sandbox-api.fireblocks.io/v1"
)

# Enter a context with an instance of the API client
with Fireblocks(configuration) as fireblocks:
    webhook_id = '44fcead0-7053-4831-a53a-df7fb90d440f' # str |
    order = DESC # str | ASC / DESC ordering (default DESC) (optional) (default to DESC)
    sort_by = updatedAt # str | Sort by field (optional) (default to updatedAt)
    page_cursor = 'page_cursor_example' # str | Cursor of the required page (optional)
    page_size = 100 # float | Maximum number of items in the page (optional) (default to 100)

    try:
        # Get all notifications by webhook id
        api_response = fireblocks.webhooks_v2.get_notifications(webhook_id, order=order, sort_by=sort_by, page_cursor=page_cursor, page_size=page_size).result()
        print("The response of WebhooksV2Api->get_notifications:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling WebhooksV2Api->get_notifications: %s\n" % e)
```

```java theme={"system"}
// Import classes:
import com.fireblocks.sdk.ApiClient;
import com.fireblocks.sdk.ApiException;
import com.fireblocks.sdk.ApiResponse;
import com.fireblocks.sdk.BasePath;
import com.fireblocks.sdk.Fireblocks;
import com.fireblocks.sdk.ConfigurationOptions;
import com.fireblocks.sdk.model.*;
import com.fireblocks.sdk.api.WebhooksV2Api;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;

public class Example {
    public static void main(String[] args) {
        ConfigurationOptions configurationOptions = new ConfigurationOptions()
            .basePath(BasePath.Sandbox)
            .apiKey("my-api-key")
            .secretKey("my-secret-key");
        Fireblocks fireblocks = new Fireblocks(configurationOptions);

        UUID webhookId = UUID.fromString("44fcead0-7053-4831-a53a-df7fb90d440f"); // UUID |
        String order = "ASC"; // String | ASC / DESC ordering (default DESC)
        String sortBy = "id"; // String | Sort by field
        String pageCursor = "pageCursor_example"; // String | Cursor of the required page
        BigDecimal pageSize = new BigDecimal("100"); // BigDecimal | Maximum number of items in the page
        try {
            CompletableFuture<ApiResponse<NotificationPaginatedResponse>> response = fireblocks.webhooksV2().getNotifications(webhookId, order, sortBy, pageCursor, pageSize);
            System.out.println("Status code: " + response.get().getStatusCode());
            System.out.println("Response headers: " + response.get().getHeaders());
            System.out.println("Response body: " + response.get().getData());
        } catch (InterruptedException | ExecutionException e) {
            ApiException apiException = (ApiException)e.getCause();
            System.err.println("Exception when calling WebhooksV2Api#getNotifications");
            System.err.println("Status code: " + apiException.getCode());
            System.err.println("Response headers: " + apiException.getResponseHeaders());
            System.err.println("Reason: " + apiException.getResponseBody());
            e.printStackTrace();
        } catch (ApiException e) {
            System.err.println("Exception when calling WebhooksV2Api#getNotifications");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Response headers: " + e.getResponseHeaders());
            System.err.println("Reason: " + e.getResponseBody());
            e.printStackTrace();
        }
    }
}
```

After you retrieve the **resourceId** value you need, run the **resendNotificationsByResourceId** command, which uses the [Resend notifications by resourceId](/reference/resendnotificationsbyresourceid) endpoint.

```bash theme={"system"}
curl --request POST \
     --url 'https://api.fireblocks.io/v1/webhooks/webhookId/notifications/resend_by_resource' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
```

```javascript theme={"system"}
import { readFileSync } from 'fs';
import { Fireblocks, BasePath } from '@fireblocks/ts-sdk';
import type { FireblocksResponse, WebhooksV2ApiResendNotificationsByResourceIdRequest } from '@fireblocks/ts-sdk';

// Set the environment variables for authentication
process.env.FIREBLOCKS_BASE_PATH = BasePath.Sandbox; // or assign directly to "https://sandbox-api.fireblocks.io/v1"
process.env.FIREBLOCKS_API_KEY = "my-api-key";
process.env.FIREBLOCKS_SECRET_KEY = readFileSync("./fireblocks_secret.key", "utf8");

const fireblocks = new Fireblocks();

let body: WebhooksV2ApiResendNotificationsByResourceIdRequest = {
  // ResendNotificationsByResourceIdRequest
  resendNotificationsByResourceIdRequest: param_value,
  // string | The ID of the webhook
  webhookId: webhookId_example,
  // string | A unique identifier for the request. If the request is sent multiple times with the same idempotency key, the server will return the same response as the first request. The idempotency key is valid for 24 hours. (optional)
  idempotencyKey: idempotencyKey_example,
};

fireblocks.webhooksV2.resendNotificationsByResourceId(body).then((res: FireblocksResponse<any>) => {
  console.log('API called successfully. Returned data: ' + JSON.stringify(res, null, 2));
}).catch((error:any) => console.error(error));
```

```python theme={"system"}
from fireblocks.models.resend_notifications_by_resource_id_request import ResendNotificationsByResourceIdRequest
from fireblocks.client import Fireblocks
from fireblocks.client_configuration import ClientConfiguration
from fireblocks.exceptions import ApiException
from fireblocks.base_path import BasePath

# load the secret key content from a file
with open('your_secret_key_file_path', 'r') as file:
    secret_key_value = file.read()

# build the configuration
configuration = ClientConfiguration(
        api_key="your_api_key",
        secret_key=secret_key_value,
        base_path=BasePath.Sandbox, # or set it directly to a string "https://sandbox-api.fireblocks.io/v1"
)

# Enter a context with an instance of the API client
with Fireblocks(configuration) as fireblocks:
    webhook_id = 'webhook_id_example' # str | The ID of the webhook
    resend_notifications_by_resource_id_request = fireblocks.ResendNotificationsByResourceIdRequest() # ResendNotificationsByResourceIdRequest |
    idempotency_key = 'idempotency_key_example' # str | A unique identifier for the request. If the request is sent multiple times with the same idempotency key, the server will return the same response as the first request. The idempotency key is valid for 24 hours. (optional)

    try:
        # Resend notifications by resource Id
        fireblocks.webhooks_v2.resend_notifications_by_resource_id(webhook_id, resend_notifications_by_resource_id_request, idempotency_key=idempotency_key).result()
    except Exception as e:
        print("Exception when calling WebhooksV2Api->resend_notifications_by_resource_id: %s\n" % e)
```

```java theme={"system"}
// Import classes:
import com.fireblocks.sdk.ApiClient;
import com.fireblocks.sdk.ApiException;
import com.fireblocks.sdk.ApiResponse;
import com.fireblocks.sdk.BasePath;
import com.fireblocks.sdk.Fireblocks;
import com.fireblocks.sdk.ConfigurationOptions;
import com.fireblocks.sdk.model.*;
import com.fireblocks.sdk.api.WebhooksV2Api;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;

public class Example {
    public static void main(String[] args) {
        ConfigurationOptions configurationOptions = new ConfigurationOptions()
            .basePath(BasePath.Sandbox)
            .apiKey("my-api-key")
            .secretKey("my-secret-key");
        Fireblocks fireblocks = new Fireblocks(configurationOptions);

        ResendNotificationsByResourceIdRequest resendNotificationsByResourceIdRequest = new ResendNotificationsByResourceIdRequest(); // ResendNotificationsByResourceIdRequest |
        String webhookId = "webhookId_example"; // String | The ID of the webhook
        String idempotencyKey = "idempotencyKey_example"; // String | A unique identifier for the request. If the request is sent multiple times with the same idempotency key, the server will return the same response as the first request. The idempotency key is valid for 24 hours.
        try {
            CompletableFuture<ApiResponse<Void>> response = fireblocks.webhooksV2().resendNotificationsByResourceId(resendNotificationsByResourceIdRequest, webhookId, idempotencyKey);
            System.out.println("Status code: " + response.get().getStatusCode());
            System.out.println("Response headers: " + response.get().getHeaders());
        } catch (InterruptedException | ExecutionException e) {
            ApiException apiException = (ApiException)e.getCause();
            System.err.println("Exception when calling WebhooksV2Api#resendNotificationsByResourceId");
            System.err.println("Status code: " + apiException.getCode());
            System.err.println("Response headers: " + apiException.getResponseHeaders());
            System.err.println("Reason: " + apiException.getResponseBody());
            e.printStackTrace();
        } catch (ApiException e) {
            System.err.println("Exception when calling WebhooksV2Api#resendNotificationsByResourceId");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Response headers: " + e.getResponseHeaders());
            System.err.println("Reason: " + e.getResponseBody());
            e.printStackTrace();
        }
    }
}
```

Lastly, validate that you received the notifications successfully.

> **Resource ID in the Console**
>
> You can also find a notification's resource ID in the Fireblocks Console by going to **Developer Center** > **Webhooks** and then selecting the relevant endpoint URL from the Webhooks list. Then, in the Notification activity list, you can find and copy the relevant resource ID.

***

## Resending all notifications for an endpoint

Use this method when you need to resend all the notifications for a particular endpoint after resolving server-side issues. This method will resend all notifications generated over the last 24 hours for that endpoint.

### Via the Fireblocks Console

1. In the Fireblocks Console, go to **Developer center** > **Webhooks**, and then select the relevant endpoint URL from the Webhooks list.
2. In the Notification activity list, select **Resend notifications**.
3. Validate that you received the notifications successfully.

***

## Endpoint auto-deactivated due to circuit breaker

In Webhooks V2, the circuit breaker monitors error rates for each webhook endpoint and suspends endpoints that exceed predefined thresholds. Errors include timeouts and any non-2xx status code. The circuit breaker evaluates error rates using a rolling 60-minute window, assessed on each delivery attempt.

Suspension policies vary by error rate severity:

* **50–80% error rate:** If your endpoint sustains this error rate for 4 consecutive hours, Fireblocks suspends it automatically.
* **Above 80% error rate:** If your endpoint's error rate exceeds this threshold within the rolling 60-minute window, Fireblocks suspends it immediately.

When your endpoint is suspended, Fireblocks notifies all Admin users in the workspace by email.

### Reactivating a suspended endpoint

Suspension is not automatically lifted. To reactivate your endpoint:

1. Identify and resolve the underlying issue causing delivery failures.
2. Reactivate the endpoint via the [Developer Center](https://console.fireblocks.io/v2/developer/webhooks) or by calling the [Update Webhook](/reference/updatewebhook) endpoint with `enabled` set to `true`.
3. Once reactivated, the circuit breaker immediately resumes monitoring the endpoint. If the error rate exceeds the above thresholds again, the endpoint will be suspended again.

> **No cooldown period before reactivation**
>
> There is no cooldown period before reactivation. It is your responsibility to ensure the issue is resolved *before* reactivating to avoid repeated suspension.


# CeFi events
Source: https://developers.fireblocks.com/reference/webhooks-structures-eventtypes-cefi



This page covers all Centralized Finance (CeFi) events that can trigger webhook notifications, and their associated data objects for the Webhooks v2 service.

## CeFi event types

To receive a specific event, include its **eventType** in the webhook's [notification object](/reference/webhooks-structures-notificationstructure#/).

| Event type                   | Data object returned                                     |
| ---------------------------- | -------------------------------------------------------- |
| exchange\_account.connected  | ThirdPartyWebhook (from your exchange account provider)  |
| fiat\_account.connected      | ThirdPartyWebhook (from your fiat account provider)      |
| connected\_account.connected | ThirdPartyWebhook (from your connected account provider) |


# Embedded Wallet events
Source: https://developers.fireblocks.com/reference/webhooks-structures-eventtypes-embeddedwallet



This page covers all Embedded Wallet events that can trigger webhook notifications, and their associated data objects for the Webhooks v2 service.

## Embedded Wallet event types

To receive a specific event, include its **eventType** in the webhook's [notification object](/reference/webhooks-structures-notificationstructure#/).

| Event type                              | Data object returned                                                                                                                         |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| embedded\_wallet.created                | [Non-Custodial Wallet Created](https://ncw-developers.fireblocks.com/docs/webhooks#non-custodial-wallet-created)                             |
| embedded\_wallet.status.updated         | [NCW Transaction Status Updated](https://ncw-developers.fireblocks.com/docs/webhooks#ncw-transaction-status-updated-immediate)               |
| embedded\_wallet.account\_created       | [Non-Custodial Wallet Account Created](https://ncw-developers.fireblocks.com/docs/webhooks#non-custodial-wallet-account-created)             |
| embedded\_wallet.asset.added            | [Non-Custodial Wallet Asset Created](https://ncw-developers.fireblocks.com/docs/webhooks#non-custodial-wallet-asset-created)                 |
| embedded\_wallet.asset.balance\_updated | [Non-Custodial Wallet Asset balance changed](https://ncw-developers.fireblocks.com/docs/webhooks#non-custodial-wallet-asset-balance-changed) |
| embedded\_wallet.device.added           | [Multi-Device Request ID](https://ncw-developers.fireblocks.com/docs/webhooks#multi-device-request-id)                                       |


# Network connection events
Source: https://developers.fireblocks.com/reference/webhooks-structures-eventtypes-networkconnection



This page covers all Network connection events that can trigger webhook notifications, and their associated data objects for the Webhooks v2 service.

## Network connection event types

To receive a specific event, include its **eventType** in the webhook's [notification object](/reference/webhooks-structures-notificationstructure).

| Event type                                 | Data object returned                                                                               |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| connection.added                           | [NetworkConnection](/reference/webhooks-structures-eventtypes-networkconnection#networkconnection) |
| connection.removed                         | [NetworkConnection](/reference/webhooks-structures-eventtypes-networkconnection#networkconnection) |
| connection.request.waiting\_peer\_approval | [NetworkConnection](/reference/webhooks-structures-eventtypes-networkconnection#networkconnection) |
| connection.request.rejected\_by\_peer      | [NetworkConnection](/reference/webhooks-structures-eventtypes-networkconnection#networkconnection) |

***

## Data objects

### NetworkConnection

| Parameter     | Type                                                                           | Description                       |
| ------------- | ------------------------------------------------------------------------------ | --------------------------------- |
| id            | string                                                                         | The ID of the Network Connection. |
| localChannel  | [Channel](/reference/webhooks-structures-eventtypes-networkconnection#channel) | Local channel ID.                 |
| remoteChannel | [Channel](/reference/webhooks-structures-eventtypes-networkconnection#channel) | Remote channel ID.                |

### Channel

| Parameter | Type   | Description                        |
| --------- | ------ | ---------------------------------- |
| networkId | string | The 8-character ID of the channel. |
| name      | string | The name of the channel.           |


# Off Exchange events
Source: https://developers.fireblocks.com/reference/webhooks-structures-eventtypes-offexchange



This page covers all Off Exchange events that can trigger webhook notifications, and their associated data objects for the Webhooks v2 service.

## Off Exchange event types

To receive a specific event, include its **eventType** in the webhook's [notification object](/reference/webhooks-structures-notificationstructure#/).

| Event type                | Data object returned                                                                                             |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| settlement.created        | [settlementDetails](/reference/webhooks-structures-eventtypes-offexchange?isFramePreview=true#settlementdetails) |
| collateral.status.updated | [settlementDetails](/reference/webhooks-structures-eventtypes-offexchange?isFramePreview=true#settlementdetails) |

***

## Data objects

### settlementDetails

| Parameter                                                                                              | Type          | Description                                                                                                                   |
| ------------------------------------------------------------------------------------------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| collateralAccountId                                                                                    | string        | The collateral account ID.                                                                                                    |
| settlementId                                                                                           | string        | Unique settlement ID provided by Fireblocks.                                                                                  |
| isForceSettlement                                                                                      | boolean       | A flag or condition that indicates whether a settlement should be forcibly executed, overriding normal settlement procedures. |
| [toExchange](/reference/webhooks-structures-eventtypes-offexchange?isFramePreview=true#toexchange)     | data \[array] | All settlement transaction details are required to be sent to the exchange.                                                   |
| [toCollateral](/reference/webhooks-structures-eventtypes-offexchange?isFramePreview=true#tocollateral) | data \[array] | All settlement transaction details are required to be sent to the collateral account.                                         |

### toExchange

| Parameter | Type   | Description                                                                                                                                                                                                                 |
| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| txId      | string | The transaction ID (within the main workspace).                                                                                                                                                                             |
| assetId   | string | The ID of the transaction's asset, applicable to `TRANSFER`, `MINT, BURN`, or `ENABLE_ASSET` operations. For a list of supported assets and their corresponding IDs, please refer [here](/reference/list-supported-assets). |
| amount    | string | The actual amount requested for transfer.                                                                                                                                                                                   |

### toCollateral

| Parameter | Type   | Description                                                                                                                                                                                                                 |
| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| txId      | string | The transaction ID (within the main workspace).                                                                                                                                                                             |
| assetId   | string | The ID of the transaction's asset, applicable to `TRANSFER`, `MINT, BURN`, or `ENABLE_ASSET` operations. For a list of supported assets and their corresponding IDs, please refer [here](/reference/list-supported-assets). |
| amount    | string | The actual amount requested for transfer.                                                                                                                                                                                   |


# Smart Transfer events
Source: https://developers.fireblocks.com/reference/webhooks-structures-eventtypes-smarttransfer



This page covers all Smart Transfer events that can trigger webhook notifications, and their associated data objects for the Webhooks v2 service.

## Event types

To receive a specific event, include its **eventType** in the webhook's [notification object](/reference/webhooks-structures-notificationstructure#/).

| Event type                               | Data object returned                                                                                                                      |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| ticket.created                           | [Ticket created](/reference/webhooks-structures-eventtypes-smarttransfer#/ticket-created)                                                 |
| ticket.counterparty.added                | [Ticket counterparty added](/reference/webhooks-structures-eventtypes-smarttransfer#/ticket-counterparty-added)                           |
| ticket.counterparty\_external\_id.set    | [Ticket counterparty external ID set](/reference/webhooks-structures-eventtypes-smarttransfer#/ticket-counterparty-external-id-set)       |
| ticket.note.added                        | [Ticket note added](/reference/webhooks-structures-eventtypes-smarttransfer#/ticket-note-added)                                           |
| ticket.submitted                         | [Ticket submitted](/reference/webhooks-structures-eventtypes-smarttransfer#/ticket-submitted)                                             |
| ticket.expires\_at.set                   | [Ticket expires at set](/reference/webhooks-structures-eventtypes-smarttransfer#/ticket-expires-at-set)                                   |
| ticket.expires\_in.set                   | [Ticket expires in set](/reference/webhooks-structures-eventtypes-smarttransfer#/ticket-expires-in-set)                                   |
| ticket.expired                           | [Ticket expired](/reference/webhooks-structures-eventtypes-smarttransfer#/ticket-expired)                                                 |
| ticket.fulfilled                         | [Ticket fulfilled](/reference/webhooks-structures-eventtypes-smarttransfer#/ticket-fulfilled)                                             |
| ticket.canceled                          | [Ticket canceled](/reference/webhooks-structures-eventtypes-smarttransfer#/ticket-canceled)                                               |
| ticket.term.added                        | [Ticket term added](/reference/webhooks-structures-eventtypes-smarttransfer#/ticket-term-added)                                           |
| ticket.term.updated                      | [Ticket term updated](/reference/webhooks-structures-eventtypes-smarttransfer#/ticket-term-updated)                                       |
| ticket.term.deleted                      | [Ticket term deleted](/reference/webhooks-structures-eventtypes-smarttransfer#/ticket-term-deleted)                                       |
| ticket.term.funded                       | [Ticket term funded](/reference/webhooks-structures-eventtypes-smarttransfer#/ticket-term-funded)                                         |
| ticket.term.manually\_funded             | [Ticket term manually funded](/reference/webhooks-structures-eventtypes-smarttransfer#/ticket-term-manually-funded)                       |
| ticket.term.funding\_canceled            | [Ticket term funding canceled](/reference/webhooks-structures-eventtypes-smarttransfer#/ticket-term-funding-canceled)                     |
| ticket.term.funding\_failed              | [Ticket term funding failed](/reference/webhooks-structures-eventtypes-smarttransfer#/ticket-term-funding-failed)                         |
| ticket.term.funding\_completed           | [Ticket term funding completed](/reference/webhooks-structures-eventtypes-smarttransfer#/ticket-term-funding-completed)                   |
| ticket.term.status\_transaction\_changed | [Ticket term transaction status changed](/reference/webhooks-structures-eventtypes-smarttransfer#/ticket-term-transaction-status-changed) |

***

## Data objects

### Ticket created

| Parameter              | Type   | Description                                                              |
| ---------------------- | ------ | ------------------------------------------------------------------------ |
| ticketId               | string | Unique ID for the ticket                                                 |
| type                   | string | The type of settlement for the ticket: Currently, only async             |
| status                 | string | The status of the ticket                                                 |
| createdByNetworkId     | string | The network ID of the Fireblocks Network profile that created the ticket |
| createdByNetworkIdName | string | The name of the Fireblocks Network profile that created the ticket       |
| createdAt              | date   | Time and date when the ticket was created                                |
| expiresIn              | number | Expiration of the ticket in hours                                        |

### Ticket counterparty added

| Parameter     | Type   | Description                                                 |
| ------------- | ------ | ----------------------------------------------------------- |
| ticketId      | string | Unique ID for the ticket                                    |
| networkId     | string | Network ID of the connection receiving a ticket             |
| networkIdName | string | Name of the Fireblocks Network profile receiving the ticket |

### Ticket counterparty external ID set

| Parameter     | Type   | Description                          |
| ------------- | ------ | ------------------------------------ |
| ticketId      | string | Unique ID for the ticket             |
| externalRefId | string | Any ID a customer adds to the system |

### Ticket note added

| Parameter | Type   | Description                             |
| --------- | ------ | --------------------------------------- |
| ticketId  | string | Unique ID for the ticket                |
| body      | string | Text of the note                        |
| createdAt | date   | Time and date when the note was created |

### Ticket submitted

| Parameter   | Type   | Description                           |
| ----------- | ------ | ------------------------------------- |
| ticketId    | string | Unique ID for the ticket              |
| expiresIn   | number | Expiration of the ticket in hours     |
| status      | string | Status of the ticket                  |
| expiresAt   | date   | Date and time when the ticket expires |
| submittedAt | date   | Date and time the ticket is submitted |

### Ticket expires at set

| Parameter | Type   | Description                           |
| --------- | ------ | ------------------------------------- |
| ticketId  | string | Unique ID for the ticket              |
| expiresAt | date   | Date and time when the ticket expires |

### Ticket expires in set

| Parameter | Type   | Description                       |
| --------- | ------ | --------------------------------- |
| ticketId  | string | Unique ID for the ticket          |
| expiresIn | number | Expiration of the ticket in hours |

### Ticket expired

| Parameter | Type   | Description                           |
| --------- | ------ | ------------------------------------- |
| ticketId  | string | Unique ID for the ticket              |
| status    | string | Status of the ticket                  |
| expiresAt | date   | Date and time when the ticket expired |

### Ticket fulfilled

| Parameter   | Type   | Description                                               |
| ----------- | ------ | --------------------------------------------------------- |
| ticketId    | string | Unique ID for the ticket                                  |
| fulfilledAt | date   | Date and time when the ticket was fulfilled by both sides |

### Ticket canceled

| Parameter  | Type   | Description                                |
| ---------- | ------ | ------------------------------------------ |
| ticketId   | string | Unique ID for the ticket                   |
| canceledAt | date   | Date and time when the ticket was canceled |

### Ticket term added

| Parameter     | Type   | Description                                  |
| ------------- | ------ | -------------------------------------------- |
| ticketId      | string | Unique ID for the ticket                     |
| termId        | string | Unique ID of the term                        |
| asset         | string | Asset name being sent in the term            |
| amount        | string | Amount of the asset being sent               |
| fromNetworkId | string | NetworkId from which the asset is being sent |
| toNetworkId   | string | NetworkId to which the asset is being sent   |
| status        | string | Status of the ticket                         |

### Ticket term updated

| Parameter     | Type   | Description                                  |
| ------------- | ------ | -------------------------------------------- |
| ticketId      | string | Unique ID for the ticket                     |
| termId        | string | Unique ID of the term                        |
| asset         | string | Asset name being sent in the term            |
| amount        | string | Amount of the asset being sent               |
| fromNetworkId | string | NetworkId from which the asset is being sent |
| toNetworkId   | string | NetworkId to which the asset is being sent   |

### Ticket term deleted

| Parameter | Type   | Description              |
| --------- | ------ | ------------------------ |
| ticketId  | string | Unique ID for the ticket |
| termId    | string | Unique ID of the term    |

### Ticket term funded

| Parameter           | Type   | Description                                                                                                           |
| ------------------- | ------ | --------------------------------------------------------------------------------------------------------------------- |
| ticketId            | string | Unique ID for the ticket                                                                                              |
| termId              | string | Unique ID of the term                                                                                                 |
| asset               | string | Asset name of the asset being sent to fund the term                                                                   |
| amount              | string | Amount of the asset being sent to fund the term                                                                       |
| networkConnectionId | string | Network ID funding the term                                                                                           |
| srcId               | string | vaultId if srcType is VAULT\_ACCOUNT; exchangeId if srcType is EXCHANGE; or fiatAccountId if srcType is FIAT\_ACCOUNT |
| srcType             | string | Type of the account from which the funds are originating; can be a vault, an exchange, or a fiat account              |
| note                | string | Text of the note                                                                                                      |
| fee                 | string | Amount of fee paid for the transaction funding the term                                                               |
| feeLevel            | string | Fee level being paid                                                                                                  |

### Ticket term manually funded

| Parameter | Type   | Description                                 |
| --------- | ------ | ------------------------------------------- |
| ticketId  | string | Unique ID for the ticket                    |
| termId    | string | Unique ID of the term                       |
| txHash    | string | TX hash of the transaction funding the term |

### Ticket term funding canceled

| Parameter | Type   | Description                             |
| --------- | ------ | --------------------------------------- |
| ticketId  | string | Unique ID for the ticket                |
| termId    | string | Unique ID of the term                   |
| txStatus  | string | Status of the transfer funding the term |

### Ticket term funding failed

| Parameter | Type   | Description                             |
| --------- | ------ | --------------------------------------- |
| ticketId  | string | Unique ID for the ticket                |
| termId    | string | Unique ID of the term                   |
| txStatus  | string | Status of the transfer funding the term |

### Ticket term funding completed

| Parameter | Type   | Description                                 |
| --------- | ------ | ------------------------------------------- |
| ticketId  | string | Unique ID for the ticket                    |
| termId    | string | Unique ID of the term                       |
| txSHash   | string | TX hash of the transaction funding the term |
| txStatus  | string | Status of the transfer funding the term     |

### Ticket term transaction status changed

| Parameter | Type   | Description                             |
| --------- | ------ | --------------------------------------- |
| ticketId  | string | Unique ID for the ticket                |
| termId    | string | Unique ID of the term                   |
| txStatus  | string | Status of the transfer funding the term |


# Tokenization events
Source: https://developers.fireblocks.com/reference/webhooks-structures-eventtypes-tokenization



This page covers all Tokenization events that can trigger webhook notifications, and their associated data objects for the Webhooks v2 service.

These events are part of the Fireblocks Webhooks v2 event types. For a complete list of supported webhook events, see [Event types](/reference/webhooks-structures-eventtypes).

## Tokenization event types

To receive a specific event, include its **eventType** in the webhook's [notification object](/reference/webhooks-structures-notificationstructure#/).

| Event type            | Data object returned                                                                                              |
| --------------------- | ----------------------------------------------------------------------------------------------------------------- |
| onchain\_data.updated | [OnchainDataUpdatedEventData](/reference/webhooks-structures-eventtypes-tokenization#onchaindataupdatedeventdata) |

***

## Supported blockchains

Fireblocks generates Tokenization webhook events only for managed smart contracts deployed on the following blockchains.

### Testnets

* Ethereum Sepolia (sepolia)
* Polygon Amoy (amoy)
* BNB Smart Chain Testnet (bsc\_testnet)
* Optimism Sepolia (optimism\_sepolia)
* Base Sepolia (base\_sepolia)
* Avalanche C-Chain Fuji (fuji)
* Arbitrum Sepolia (arbitrum\_sepolia)

### Mainnets

* Ethereum (ethereum)
* BNB Smart Chain (bsc)
* Polygon (polygon)
* Base (base)
* Avalanche C-Chain (avalanche)
* Optimism (optimism)
* Arbitrum (arbitrum)
* Gnosis (gnosis)
* Ethereum Hoodi (hoodi)

Tokenization events are emitted only for contracts deployed on the supported blockchains listed above.

## Data objects

### OnchainDataUpdatedEventData

| Parameter         | Type    | Description                                                             |
| ----------------- | ------- | ----------------------------------------------------------------------- |
| baseAssetId       | string  | The AssetId of the blockchain's gas token.                              |
| blockHash         | string  | Hash of the block that contains the transaction emitting the log.       |
| blockNumber       | number  | Height of the block that contains the transaction.                      |
| blockTimestamp    | number  | The time the block was mined, as indicated in the block header.         |
| chainId           | number  | EVM chain identifier (as per EIP-155).                                  |
| contractAddress   | string  | The address that emitted the log.                                       |
| cumulativeGasUsed | string  | Total gas used in the block up to and including this transaction.       |
| decodedLogs       | object  | [DecodedLog](/reference/tokenization-events#decodedlog)                 |
| effectiveGasPrice | string  | Actual price paid per gas unit for this transaction.                    |
| from              | string  | Sender of the transaction.                                              |
| gasUsed           | integer | Gas consumed by this transaction.                                       |
| logsBloom         | string  | Bloom filter summarizing addresses and topics for the transaction logs. |
| status            | string  | The status of the transaction (0x0 = failure, 0x1 = success).           |
| to                | string  | The recipient of the transaction.                                       |
| transactionHash   | string  | Hash that identifies the transaction.                                   |
| transactionIndex  | string  | Zero-based index of the transaction within the block.                   |
| type              | string  | Transaction type tag (as per EIP-2718).                                 |

### DecodedLog

| Parameter       | Type   | Description                                                       |
| --------------- | ------ | ----------------------------------------------------------------- |
| address         | string | The contract address emitting the event.                          |
| blockHash       | string | Hash of the block that contains the transaction emitting the log. |
| blockNumber     | string | Height of the block that contains the transaction.                |
| transactionHash | string | Hash that identifies the transaction.                             |
| logIndex        | string | The index of the log within the transaction.                      |
| key             | string | The decoded name of the log parameter.                            |
| value           | string | The value associated with the key.                                |


# Transaction events
Source: https://developers.fireblocks.com/reference/webhooks-structures-eventtypes-transaction



This page covers all transaction events that can trigger webhook notifications, and their associated data objects for the Webhooks v2 service.

## Transaction event types

To receive a specific event, include its **eventType** in the webhook's [notification object](/reference/webhooks-structures-notificationstructure#/).

| Event type                                         | Data object returned                                |
| -------------------------------------------------- | --------------------------------------------------- |
| transaction.created                                | [TransactionDetails](#transactiondetails)           |
| transaction.status.updated                         | [TransactionDetails](#transactiondetails)           |
| transaction.approval\_status.updated               | [TransactionDetails](#transactiondetails)           |
| transaction.network\_records.processing\_completed | [TransactionDetails](#transactiondetails)           |
| transaction.alert.stuck\_confirming                | [TransactionAlertPayload](#transactionalertpayload) |

## Transaction alert events

Transaction alert events notify you when Fireblocks detects conditions that may require intervention, such as transactions that have stalled due to fee-related issues. Use these events to build automated monitoring and remediation workflows.

<Info>
  ### Beta

  `transaction.alert.stuck_confirming` is part of the Account Traffic Control (ATC) feature and is subject to change. For more information, see [Account Traffic Control](https://support.fireblocks.io/hc/en-us/articles/27129539023004-Account-Traffic-Control).
</Info>

### transaction.alert.stuck\_confirming

Triggered when one or more transactions from a vault account and base asset are stuck in the `CONFIRMING` status on EVM blockchains, indicating potential fee-related issues that may block subsequent transactions.

#### Example payload

```json theme={"system"}
{
  "id": "39067fb9-5212-48e1-9e60-8ff1b326fdce",
  "resourceId": "9074940b-1ef7-4313-b8c0-cb8958ba945c",
  "webhookId": "072422fd-981f-496f-a926-7b506e4f0588",
  "workspaceId": "97535494-a9ff-564c-af19-6946c40ce39b",
  "eventType": "transaction.alert.stuck_confirming",
  "createdAt": 1777241007613,
  "data": {
    "issueType": "LOW_FEE_TRANSACTION_DETECTED",
    "severity": "WARNING",
    "description": "2 transactions stuck in CONFIRMING",
    "vaultAccountId": "0",
    "baseAsset": "ETH_TEST5",
    "recommendedAction": {
      "action": "BOOST_TRANSACTION",
      "description": "Speed up the oldest stuck transaction by replacing it with a higher fee.",
      "stuckTxId": "9074940b-1ef7-4313-b8c0-cb8958ba945c"
    },
    "stuckAccountDetails": {
      "blockedTransactionCount": 2,
      "lastCompletedNonce": 24,
      "blocksElapsed": 15,
      "stuckDurationSeconds": 175
    }
  }
}
```

## Data objects

### TransactionDetails

| Parameter                     | Type                                                                                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| id                            | string                                                                                   | The ID of the transaction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| index                         | integer                                                                                  | **\[Optional]** Fireblocks' internal identifier for a specific transfer within a transaction. For UTXO-based assets, this field corresponds to the UTXO's vOut index. For other blockchains, like EVM, Tron, Solana, etc., this field is derived from the sequential position of the event within the transaction's transfer list. The field is not returned when the transaction includes multiple destinations.                                                                                                                                                                                                                                                                                                                                                                    |
| logIndex                      | integer                                                                                  | Applicable to EVM blockchains only. Represents the EVM log index that indicates the order of the log within the block. This information can be verified directly on the blockchain.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| blockchainIndex               | string                                                                                   | Blockchain-native transfer identifier showing the transfer's exact position within the block data (e.g., log entry, trace path, or nested array index). - **EVM token transfers**: Uses logIndex. - **EVM internal transfers**: Uses traceAddress (e.g., \[0,1,2] → "0\_1\_2"). - **Solana**: Refers to the nested instruction position in the instruction array.                                                                                                                                                                                                                                                                                                                                                                                                                    |
| externalTxId                  | string                                                                                   | Unique transaction ID provided by the user. Fireblocks recommends setting an externalTxId for every transaction created to avoid submitting the same transaction twice.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| status                        | string                                                                                   | The current primary status of the transaction. See [Primary Transaction Statuses](https://support.fireblocks.io/hc/en-us/articles/5536566813468) for a detailed list.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| subStatus                     | string                                                                                   | **\[Optional]** See [Transaction Substatuses](https://support.fireblocks.io/hc/en-us/articles/5643077899036) for a detailed list of transaction substatuses.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| txHash                        | string                                                                                   | The hash of this transaction on the blockchain. txHash is only returned for crypto assets (not fiat) when the operation type is not `RAW` or `TYPED_MESSAGE`. This parameter exists if at least one of the following conditions is met: 1. The transaction's source type is `UNKNOWN`, `WHITELISTED_ADDRESS`, `ONE_TIME_ADDRESS`, `FIAT` or `GAS_STATION`. 2. The transaction's source type is `VAULT` and the status is CONFIRMING, COMPLETED, or was either status before changing to FAILED or REJECTED. Some transactions with the status BROADCASTING will also include the txHash. 3. The transaction's source type is `EXCHANGE` and the transaction's destination type is `VAULT`, and the status is: CONFIRMING, COMPLETED, or was either status before changing to FAILED. |
| operation                     | [TransactionOperation](#transactionoperation)                                            | The transaction operation type. The default is `TRANSFER`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| note                          | string                                                                                   | Custom note that describes this transaction in your Fireblocks workspace. This note is not sent to the blockchain.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| assetId                       | string                                                                                   | The ID of the transaction's asset, for TRANSFER, MINT, BURN, or ENABLE\_ASSET operations. [See the list of supported assets and their IDs on Fireblocks](/reference/list-supported-assets).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| assetType                     | [AssetType](/reference/supported-assets-object)                                          | One of the following: XLM\_ASSET, XDB\_ASSET, TRON\_TRC20, SOL\_ASSET, HBAR\_ERC20, FIAT, ERC721, ERC20, ERC1155, BEP20, BASE\_ASSET, ALGO\_ASSET                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| source                        | [SourceTransferPeerPathResponse](#sourcetransferpeerpathresponse)                        | The transaction's source.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| sourceAddress                 | string                                                                                   | If the status is CONFIRMING, COMPLETED, or was CONFIRMING before either FAILED or REJECTED, this parameter will contain only one source address, even if the transaction is a multi-input UTXO. This parameter is empty in any other case.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| destination                   | [DestinationTransferPeerPathResponse](#destinationtransferpeerpathresponse)              | The transaction's destination. If a transaction is sent to multiple destinations, the **destinations** parameter is used instead.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| destinations                  | Array of [DestinationsResponse](#destinationsresponse)                                   | For UTXO-based assets. All outputs are specified here.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| destinationAddress            | string                                                                                   | Address where the asset was transferred. For [Multi-destination transactions](https://support.fireblocks.io/hc/en-us/articles/360018447980-Multi-destination-transactions), this parameter will be empty, and you should refer to the destinations field instead. `destinationAddress` is populated when Fireblocks can determine a single destination address for the transaction (for example, from the transaction request). It is typically available starting from `transaction.created` for single-destination transfers. For multi-destination transactions (where `destinations` is used), `destinationAddress` is empty. In some failure scenarios or before address resolution, this field may also be empty.                                                              |
| destinationAddressDescription | string                                                                                   | Description of the address.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| destinationTag                | string                                                                                   | **\[Optional]** Destination address tag for Ripple; destination memo for Cosmos, EOS, Luna, Luna Classic, NEM, Stellar, Hedera, & DigitalBits; destination note for Algorand; bank transfer description for fiat providers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| amountInfo                    | [AmountInfo](#amountinfo)                                                                | For `TRANSFER` operations. All details of the transfer amount.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| treatAsGrossAmount            | boolean                                                                                  | When set to `true`, the fee is deducted from the requested amount for transactions initiated from this Fireblocks workspace.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| feeInfo                       | [FeeInfo](#feeinfo) object                                                               | Details of the transaction's fee.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| feeCurrency                   | string                                                                                   | The asset type used to pay the fee (ETH for ERC-20 tokens, BTC for Omni, XLM for Stellar tokens, etc.)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| networkRecords                | Array of [NetworkRecord](/reference/transaction-objects#networkrecord) objects           | A transaction in Fireblocks can aggregate several blockchain transactions, typically as part of a contract call. Network records specify all intermediate transactions that took place on the blockchain. For single transactions, this parameter is empty.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| createdAt                     | number                                                                                   | The transaction's creation date and time. Shown as a Unix timestamp.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| lastUpdated                   | number                                                                                   | The transaction's last update date and time. Shown as a Unix timestamp.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| createdBy                     | string                                                                                   | User ID of the transaction's initiator.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| signedBy                      | Array of strings                                                                         | User ID(s) of the transaction's signer(s).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| rejectedBy                    | string                                                                                   | User ID of the user who rejected the transaction. Only populated when a transaction is rejected.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| authorizationInfo             | [AuthorizationInfo](/reference/transaction-authorization-objects#authorizationinfo)      | Data object with information about your Policies. For more about Policies, refer to the [Fireblocks Help Center](https://support.fireblocks.io/hc/en-us/articles/7354983580316-About-the-TAP).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| exchangeTxId                  | string                                                                                   | If the transaction originated from an exchange, this is the exchange's ID for this transaction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| customerRefId                 | string                                                                                   | The ID for AML providers to associate the owner of the funds with the transaction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| amlScreeningResult            | [AmlScreeningResult](/reference/transaction-screening-objects#amlscreeningresult) object | The result of the AML screening.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| replacedTxHash                | string                                                                                   | The hash of the replaced transaction. Only populated if this is an RBF transaction on an EVM blockchain. [Learn more about RBF transactions](https://support.fireblocks.io/hc/en-us/articles/360018600160-Boosting-or-dropping-a-stuck-EVM-based-transaction).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| extraParameters               | [TransactionExtraParameters](#transactionextraparameters) object                         | Parameters that are specific to some transaction operation types and blockchain networks.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| signedMessages                | Array of [SignedMessage](/reference/raw-signing-objects#signedmessage) objects           | A list of signed messages returned for raw signing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| numOfConfirmations            | number                                                                                   | The number of blockchain confirmations of the transaction. The number will increase until your workspace's confirmation policy threshold is satisfied.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| blockInfo                     | [BlockInfo](/reference/transaction-objects#blockinfo) object                             | The hash and height of the block in which the transaction was mined. If an outgoing transaction uses the destinations object with more than one value in the array, **blockHash** is set to null.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| paidRent                      | string                                                                                   | The amount of rent paid in SOL to the destination token account.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| blockchainInfo                | [BlockchainInfo](/reference/transaction-objects#blockchaininfo) object                   | `blockchainInfo` is a JSON used to store additional data that is blockchain-specific. For example, in HBAR, it will have the txHash in addition to the txID.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| rewardsInfo                   | [RewardsInfo](/reference/transaction-objects#rewardsinfo) object                         | This field is relevant only for ALGO transactions. Both srcRewrds and destRewards appear only for vault-to-vault transactions. Otherwise, only your workspace side of the transaction is recorded.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| systemMessages                | Array of [SystemMessageInfo](#systemmessageinfo) objects                                 | A response from Fireblocks with details about the health of the current processes. If this object is returned with data, expect potential delays or incomplete transaction statuses.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| addressType                   | string                                                                                   | **\[Optional]** Covers all transaction events.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| requestedAmount (Deprecated)  | number                                                                                   | The amount requested by the user.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| amount (Deprecated)           | number                                                                                   | If the transfer is a withdrawal from an exchange, the actual transfer amount; otherwise, the requested amount.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| netAmount (Deprecated)        | number                                                                                   | The net amount of the transfer, after fee deduction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| amountUSD (Deprecated)        | number                                                                                   | The USD value of the requested amount.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| serviceFee (Deprecated)       | number                                                                                   | The total fee deducted by the exchange from the actual requested amount (serviceFee = amount - netAmount).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| networkFee (Deprecated)       | number                                                                                   | The fee paid to the blockchain network.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

### TransactionOperation

| Parameter | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| operation | string | Not all operations are available in all workspaces. Contact your account manager to enable additional features. `TRANSFER` - Default. Transfers funds from one account to another. UTXO blockchains allow multi-input and multi-output transfers. All other blockchains allow transfers with one source address and one destination address. `MINT` - Mints new tokens. Supported for Stellar, Ripple, and EVM-based blockchains. [Learn more about tokenization on Fireblocks](https://support.fireblocks.io/hc/en-us/articles/4725474481308). `BURN` - Burns tokens. Supported for Stellar, Ripple, and EVM-based blockchains. [Learn more about tokenization on Fireblocks](https://support.fireblocks.io/hc/en-us/articles/4725474481308). `CONTRACT_CALL` - Calls a smart contract method for web3 operations on any EVM blockchain. The [Fireblocks development libraries](/reference/evm-web3-provider#convenience-libraries) are recommended for building contract call transactions. `TYPED_MESSAGE` - An off-chain message in either Ethereum Personal Message or EIP712 format. Use it to sign specific readable messages that are not actual transactions. [Learn more about typed messages](https://support.fireblocks.io/hc/en-us/articles/4413379762450-Off-chain-message-signing#h_01FQXY26HB87NZJFRT77B1KY6Z). `RAW` - An off-chain message with no predefined format. Use it to sign any message with your private key, including protocols such as blockchains and custom transaction types that are not natively supported by Fireblocks. [Learn more about raw signing transactions](https://support.fireblocks.io/hc/en-us/articles/4413379762450-Off-chain-message-signing). `ENABLE_ASSET` - Algorand, DigitalBits, Solana, and Stellar require an on-chain transaction to create an asset wallet and enable the deposit address. This transaction is automatically created when adding assets on these blockchains to a vault account. `STAKE` - Assign assets to a staking pool managed by a staking validator. [Learn more about staking transactions and supported blockchains](/reference/staking-overview). This transaction is automatically created when performing staking operations. `UNSTAKE` - Remove assets from a staking pool managed by a staking validator. [Learn more about staking transactions and supported blockchains](/reference/staking-overview). This transaction is automatically created when performing staking operations. `APPROVE` - Approve transactions call an approve function that allows another address to spend tokens on behalf of the signer. [Learn more about Approve Transactions here](https://support.fireblocks.io/hc/en-us/articles/14144261554716-Token-approvals-for-Web3-activity#:~:text=Permit%20allowances-,Approve%20transactions,-Approve%20transactions%20call). `WITHDRAW` - Transfer assets from a dedicated staking vault account to another address. [Learn more about staking transactions and supported blockchains](/reference/staking-overview). This transaction is automatically created when performing staking operations. **Note:** Fireblocks may rename this type from WITHDRAW to a different name soon. There will be at minimum a 7-day notice regarding the new type name. |

### AmountInfo

| Parameter       | Type   | Description                                                                                                                             |
| --------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| amount          | string | If the transfer is a withdrawal from an exchange, the actual amount requested to be transferred; otherwise, it is the requested amount. |
| requestedAmount | string | The amount requested by the user.                                                                                                       |
| netAmount       | string | The net amount of the transaction, after fee deduction.                                                                                 |
| amountUSD       | string | The USD value of the requested amount.                                                                                                  |

<Info>
  ### Note

  `transaction_status_updated` webhooks contain only up to 17 digits past the decimal place when reporting balances.
</Info>

### FeeInfo

| Parameter    | Type    | Description                                                                                                |
| ------------ | ------- | ---------------------------------------------------------------------------------------------------------- |
| networkFee   | string  | The fee paid to the network.                                                                               |
| serviceFee   | string  | The total fee deducted by the exchange from the actual requested amount (serviceFee = amount - netAmount). |
| gasPrice     | string  | The amount of gas required by/paid to the network to process the transaction.                              |
| L1networkFee | string  | Layer 1 network fee for Layer 2 blockchain transactions.                                                   |
| L2networkFee | string  | Layer 2 network fee (gas price component for Layer 2 transactions).                                        |
| paidByRelay  | boolean | Indicates whether the relay paid the fee.                                                                  |
| relayType    | string  | Indicates whether the relay is the same tenant (`LOCAL`) or another tenant (`THIRD_PARTY`).                |
| relayId      | string  | The Vault account ID of the relay.                                                                         |
| relayName    | string  | The name of the tenant hosting the third-party relay.                                                      |
| feeUSD       | string  | The USD equivalent value of the fee.                                                                       |

### SourceTransferPeerPathResponse

| Parameter      | Type   | Optional | Description                                                                                                                                                                                                        |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| type           | string | No       | `VAULT_ACCOUNT`, `EXCHANGE_ACCOUNT`, `INTERNAL_WALLET`, `EXTERNAL_WALLET`, `UNMANAGED_WALLET`, `ONE_TIME_ADDRESS`, `NETWORK_CONNECTION`, `FIAT_ACCOUNT`, `GAS_STATION`, `UNKNOWN`, `CONTRACT`, `MULTI_DESTINATION` |
| id             | string | Yes      | The ID of the account. Can return as `null` if the related transaction fails due to a connectivity error.                                                                                                          |
| name           | string | Yes      | The name of the account.                                                                                                                                                                                           |
| subType        | string | Yes      | The specific account or wallet type.                                                                                                                                                                               |
| walletId       | string | Yes      | The wallet ID associated with the source.                                                                                                                                                                          |
| tradingAccount | string | Yes      | For exchange internal transfers, the type of trading account.                                                                                                                                                      |

<Info>
  ### Sources and destinations

  Learn more about [transaction sources and destinations](/reference/transaction-sources-destinations).
</Info>

### DestinationTransferPeerPathResponse

| Parameter      | Type   | Optional | Description                                                                                                                                                                                                        |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| type           | string | No       | `VAULT_ACCOUNT`, `EXCHANGE_ACCOUNT`, `INTERNAL_WALLET`, `EXTERNAL_WALLET`, `UNMANAGED_WALLET`, `ONE_TIME_ADDRESS`, `NETWORK_CONNECTION`, `FIAT_ACCOUNT`, `GAS_STATION`, `UNKNOWN`, `CONTRACT`, `MULTI_DESTINATION` |
| id             | string | Yes      | The ID of the account. Can return as `null` if the related transaction fails due to a connectivity error.                                                                                                          |
| name           | string | Yes      | The name of the account.                                                                                                                                                                                           |
| subType        | string | Yes      | The specific account or wallet type.                                                                                                                                                                               |
| walletId       | string | Yes      | The wallet ID associated with the destination.                                                                                                                                                                     |
| tradingAccount | string | Yes      | For exchange internal transfers, the type of trading account.                                                                                                                                                      |

### DestinationsResponse

| Parameter                     | Type                                                                              | Optional | Description                                                                 |
| ----------------------------- | --------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------- |
| amount                        | string                                                                            | No       | The amount to be sent to this destination.                                  |
| destination                   | [DestinationTransferPeerPathResponse](#destinationtransferpeerpathresponse)       | No       | Destination of the transaction.                                             |
| amountUSD                     | number                                                                            | Yes      | The USD value of the requested amount.                                      |
| destinationAddressDescription | string                                                                            | Yes      | Description of the address.                                                 |
| amlScreeningResult            | [AmlScreeningResult](/reference/transaction-screening-objects#amlscreeningresult) | Yes      | The result of the AML screening.                                            |
| customerRefId                 | string                                                                            | Yes      | The ID for AML providers to associate the owner of funds with transactions. |

### TransactionExtraParameters

| Parameter        | Type                                                                     | Description                                                                                                                                                                                                                                                                                                                                   |
| ---------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| inputsSelection  | [InputsSelection object](/reference/transaction-objects#inputsselection) | For UTXO-based blockchain multi-input selection, use the `inputsSelection` field with values set to the input selection structure. The inputs can be retrieved using the Retrieve Unspent Inputs endpoint.                                                                                                                                    |
| rawMessageData   | [RawMessageData object](/reference/raw-signing-objects#rawmessagedata)   | For `RAW` operations, use the rawMessageData field with the values set to the raw message data structure. Only included with raw signing transactions on Bitcoin and Ethereum. This is an opt-in feature. Please contact [Fireblocks Support](https://support.fireblocks.io/hc/en-us/requests/new) to include this feature in your workspace. |
| contractCallData | string                                                                   | For `CONTRACT_CALL` operations, use the contractCallData field with the value set to the Ethereum smart contract Application Binary Interface (ABI) payload. The [Fireblocks development libraries](/reference/evm-web3-provider#convenience-libraries) are recommended for building contract call transactions.                              |

### SystemMessageInfo

| Parameter | Type   | Description                                                                                                                                                                                                          |
| --------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type      | string | (`WARN`, `BLOCK`)                                                                                                                                                                                                    |
| message   | string | A response from Fireblocks that communicates a message about the health of the process being performed. If this object is returned with data, you should expect potential delays or incomplete transaction statuses. |

### TransactionAlertPayload

The data object returned with `transaction.alert.stuck_confirming` events.

| Field                 | Type   | Description                                                                               |
| --------------------- | ------ | ----------------------------------------------------------------------------------------- |
| `issueType`           | string | The type of issue detected. Possible values: `LOW_FEE_TRANSACTION_DETECTED`               |
| `severity`            | string | Alert severity level. Possible values: `WARNING`, `CRITICAL`                              |
| `description`         | string | Human-readable description of the issue.                                                  |
| `vaultAccountId`      | string | The ID of the affected vault account.                                                     |
| `baseAsset`           | string | The base asset of the affected wallet (e.g., `ETH`).                                      |
| `recommendedAction`   | object | The recommended action to resolve the issue. See [RecommendedAction](#recommendedaction). |
| `stuckAccountDetails` | object | Details about the stuck account state. See [StuckAccountDetails](#stuckaccountdetails).   |

### RecommendedAction

| Field         | Type   | Description                                                             |
| ------------- | ------ | ----------------------------------------------------------------------- |
| `action`      | string | The action type. Possible values: `BOOST_TRANSACTION`                   |
| `description` | string | Human-readable description of the recommended action.                   |
| `stuckTxId`   | string | The Fireblocks transaction ID of the oldest stuck transaction to boost. |

### StuckAccountDetails

| Field                     | Type    | Description                                                                 |
| ------------------------- | ------- | --------------------------------------------------------------------------- |
| `blockedTransactionCount` | integer | Number of transactions currently stuck or blocked by the stuck transaction. |
| `lastCompletedNonce`      | integer | The last nonce that completed successfully for this account.                |
| `blocksElapsed`           | integer | Number of blocks elapsed since the transaction became stuck.                |
| `stuckDurationSeconds`    | integer | Number of seconds the transaction has been stuck.                           |


# Wallet events
Source: https://developers.fireblocks.com/reference/webhooks-structures-eventtypes-wallet



This page covers all wallet events that can trigger webhook notifications, and their associated data objects for the Webhooks v2 service.

## Wallet event types

To receive a specific event, include its **eventType** in the webhook's [notification object](/reference/webhooks-structures-notificationstructure#/).

| Event type                            | Data object returned                                                            |
| ------------------------------------- | ------------------------------------------------------------------------------- |
| vault\_account.created                | [VaultAccount](/reference/vault-objects#vaultaccount)                           |
| vault\_account.asset.added            | [VaultAsset](/reference/vault-objects#vaultasset)                               |
| vault\_account.asset.balance\_updated | [VaultAccountBalanceUpdate](/reference/vault-objects#vaultaccountbalanceupdate) |
| vault\_account.nft.balance\_updated   | [BalanceObject](/reference/nft-webhooks#balanceobject)                          |


# Whitelist events
Source: https://developers.fireblocks.com/reference/webhooks-structures-eventtypes-whitelist



This page covers all whitelist (or allowlist) events that can trigger webhook notifications, and their associated data objects for the Webhooks v2 service.

## Whitelist event types

To receive a specific event, include its **eventType** in the webhook's [notification object](/reference/webhooks-structures-notificationstructure#/).

| Event type                     | Data object returned                                                                         |
| ------------------------------ | -------------------------------------------------------------------------------------------- |
| internal\_wallet.asset.added   | [WalletAssetWebhook](/reference/webhooks-structures-eventtypes-whitelist#walletassetwebhook) |
| internal\_wallet.asset.removed | [WalletAssetWebhook](/reference/webhooks-structures-eventtypes-whitelist#walletassetwebhook) |
| external\_wallet.asset.added   | [WalletAssetWebhook](/reference/webhooks-structures-eventtypes-whitelist#walletassetwebhook) |
| external\_wallet.asset.removed | [WalletAssetWebhook](/reference/webhooks-structures-eventtypes-whitelist#walletassetwebhook) |
| contract\_wallet.asset.added   | [WalletAssetWebhook](/reference/webhooks-structures-eventtypes-whitelist#walletassetwebhook) |
| contract\_wallet.asset.removed | [WalletAssetWebhook](/reference/webhooks-structures-eventtypes-whitelist#walletassetwebhook) |

***

## Data objects

### WalletAssetWebhook

| Parameter      | Type    | Description                                                                                                                                                                                                 |
| -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| assetId        | string  | The wallet's asset                                                                                                                                                                                          |
| walletId       | string  | The ID of the wallet                                                                                                                                                                                        |
| walletName     | string  | The name of the wallet                                                                                                                                                                                      |
| address        | string  | The address of the wallet                                                                                                                                                                                   |
| tag            | string  | Destination address tag for Ripple; destination memo for Cosmos, EOS, Luna, Luna Classic, NEM, Stellar, Hedera, & DigitalBits; destination note for Algorand; bank transfer description for fiat providers. |
| activationTime | integer | The time the wallet will be activated if wallet activation is postponed, according to your workspace definition                                                                                             |


# Webhook notification structure
Source: https://developers.fireblocks.com/reference/webhooks-structures-notificationstructure



The table below shows the structure of every webhook notification generated by the Fireblocks webhook service.

| Field       | Type          | Description                                                                          |
| ----------- | ------------- | ------------------------------------------------------------------------------------ |
| id          | UUID          | Unique identifier of the object.                                                     |
| resourceId  | string        | Optional: the ID of the entity that triggered the event (e.g., txId).                |
| webhookId   | UUID          | The ID of the client-side endpoint.                                                  |
| workspaceId | UUID          | The ID of the workspace that generated the webhook notification.                     |
| eventType   | string (enum) | The type of event that triggered the webhook notification.                           |
| createdAt   | timestamp     | Time at which the object was created, measured in milliseconds since the Unix epoch. |
| data        | object        | The object containing the data associated with the event.                            |

***

## Example notifications

### vault\_account.asset.added notification

```json theme={"system"}
{
  "id": "........-....-....-....-............",
  "workspaceId": "........-....-....-....-............",
  "eventType": "vault_account.asset.added",
  "createdAt": 1754494189479,
  "data": {
    "accountId": "21",
    "accountName": "test6",
    "assetId": "XRP_TEST"
  }
}
```

### transaction.created notification (with resourceId)

```json theme={"system"}
{
  "id": "........-....-....-....-............",
  "resourceId": "........-....-....-....-............",
  "webhookId": "........-....-....-....-............",
  "workspaceId": "........-....-....-....-............",
  "eventType": "transaction.created",
  "createdAt": 1754229343763,
  "data": {
    "id": "........-....-....-....-............",
    "createdAt": 1754229343505,
    "lastUpdated": 1754229343505,
    "assetId": "XRP_TEST",
    "source": {
      "id": "0",
      "type": "VAULT_ACCOUNT",
      "name": "Default",
      "subType": ""
    },
    "destination": {
      "id": "1",
      "type": "VAULT_ACCOUNT",
      "name": "1",
      "subType": ""
    },
    "amount": 11,
    "fee": -1,
    "networkFee": -1,
    "netAmount": -1,
    "sourceAddress": "",
    "destinationAddress": "",
    "destinationAddressDescription": "",
    "destinationTag": "",
    "status": "SUBMITTED",
    "txHash": "",
    "subStatus": "",
    "signedBy": [],
    "createdBy": "........-....-....-....-............",
    "rejectedBy": "",
    "amountUSD": 11,
    "addressType": "",
    "note": "",
    "exchangeTxId": "",
    "requestedAmount": 11,
    "feeCurrency": "XRP_TEST",
    "operation": "TRANSFER",
    "customerRefId": null,
    "amountInfo": {
      "amount": "11",
      "requestedAmount": "11",
      "amountUSD": "11.00"
    },
    "feeInfo": {},
    "destinations": [],
    "externalTxId": null,
    "blockInfo": {},
    "signedMessages": [],
    "assetType": "BASE_ASSET"
  }
}
```


# Webhook object structure
Source: https://developers.fireblocks.com/reference/webhooks-structures-webhookobjectstructure



The table below shows the object structure of every webhook generated by the Fireblocks webhooks service.

| Field       | Type                          | Description                                                                                                |
| ----------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
| id          | UUID                          | Unique identifier of the object.                                                                           |
| url         | string (unique per workspace) | The URL of the webhook endpoint.                                                                           |
| description | string (nullable)             | A description of the webhook.                                                                              |
| events      | array of strings (enums)      | The list of events to enable for this endpoint. An asterisk \['\*'] indicates that all events are enabled. |
| status      | string (enum)                 | The webhook's current status. Can be enabled or disabled.                                                  |
| createdAt   | number                        | Time at which the object was created, measured in milliseconds since the Unix epoch.                       |
| updatedAt   | number                        | Time at which the object was updated, measured in milliseconds since the Unix epoch.                       |

## Webhook object structure example

```json theme={"system"}
{
    "id": "........-....-....-....-............",
    "url": "https://example.com",
    "description": "example",
    "events": [
        "transaction.created",
        "vault_account.asset.added"
    ],
    "status": "ENABLED",
    "createdAt": 1754229327599,
    "updatedAt": 1754229327599
}
```


# Unstake & Withdraw
Source: https://developers.fireblocks.com/reference/withdraw-staked-assets



# Unstake

[Unstake your position](/reference/unstake) - For Solana and MATIC, you must create and sign an unstake transaction before you can withdraw your funds. For ETH, you can proceed to the next step.

```javascript theme={"system"}
const unstakeRequest = await fireblocks.executeStakingUnstake(
  "SOL", {
		id: positionId,
    txNote: "unstake 100 SOL from vaultId 1, 24 Jan 2024"
});

const position = await fireblocks.getPosition(positionId);

// Retrieve the ongoing txId by finding the only uncompleted transaction
const txId = position.relatedTransactions.find((tx) => !tx.completed)

// .. sign it
```

***

# Withdraw

[Withdraw your staking position](/reference/withdraw) - to retrieve your funds, you must execute a withdrawal. For Solana and MATIC, the process is the same as unstaking. For Ethereum, you execute an API call with no signing needed.

```javascript theme={"system"}
const unstakeRequest = await fireblocks.executeStakingWithdraw(
  "SOL", {
		id: positionId,
		txNote: "withdraw 100 SOL from vaultId 1, 24 Jan 2024"
});

// In Ethereum case you are done here (:

const position = await fireblocks.getPosition(positionId);

// Retrieve the ongoing txId by finding the only uncompleted transaction
const txId = position.relatedTransactions.find((tx) => !tx.completed)

// .. sign it
```