> ## Documentation Index
> Fetch the complete documentation index at: https://developers.fireblocks.com/llms.txt
> Use this file to discover all available pages before exploring further.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://developers.fireblocks.com/feedback
```json
{
"path": "/api-reference/off-exchanges/add-collateral",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Add Collateral
> 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.
## OpenAPI
````yaml https://docs.fireblocks.com/api/v1/swagger.yaml post /off_exchange/add
openapi: 3.0.0
info:
title: Fireblocks API
description: >
Fireblocks provides a suite of applications to manage digital asset
operations and a complete development platform to build your business on the
blockchain.
- Visit our website for more information: [Fireblocks
Website](https://fireblocks.com)
- Visit our developer docs: [Fireblocks
DevPortal](https://developers.fireblocks.com)
version: 1.6.2
contact:
email: developers@fireblocks.com
servers:
- url: https://api.fireblocks.io/v1
description: Fireblocks Production Environment Base URL
- url: https://sandbox-api.fireblocks.io/v1
description: Fireblocks Sandbox Environment Base URL
security: []
paths:
/off_exchange/add:
post:
tags:
- Off exchanges
summary: Add Collateral
description: >-
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.
operationId: addOffExchange
parameters:
- $ref: '#/components/parameters/X-Idempotency-Key'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AddCollateralRequestBody'
responses:
'200':
description: A transaction object
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTransactionResponse'
default:
$ref: '#/components/responses/Error'
x-codeSamples:
- lang: TypeScript
source: >-
const response:
Promise> =
fireblocks.offExchanges.addOffExchange(offExchangesApiAddOffExchangeRequest);
- lang: Java
source: >-
CompletableFuture> response =
fireblocks.offExchanges().addOffExchange(addCollateralRequestBody,
idempotencyKey);
- lang: Python
source: >-
response =
fireblocks.off_exchanges.add_off_exchange(add_collateral_request_body,
idempotency_key);
components:
parameters:
X-Idempotency-Key:
name: Idempotency-Key
in: header
description: >-
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.
required: false
schema:
type: string
schemas:
AddCollateralRequestBody:
type: object
properties:
transactionRequest:
$ref: '#/components/schemas/TransactionRequest'
isSrcCollateral:
type: boolean
description: optional
CreateTransactionResponse:
type: object
properties:
id:
type: string
description: The ID of the transaction.
status:
type: string
description: >-
The primary status of the transaction. For details, see [Primary
transaction statuses.]
(https://developers.fireblocks.com/reference/primary-transaction-statuses)
systemMessages:
type: array
items:
$ref: '#/components/schemas/SystemMessageInfo'
TransactionRequest:
type: object
properties:
operation:
$ref: '#/components/schemas/TransactionOperation'
note:
type: string
description: >-
Custom note, not sent to the blockchain, to describe the transaction
at your Fireblocks workspace.
example: Ticket 123
externalTxId:
type: string
description: >-
This parameter allows you to add a unique ID of your own to help
prevent duplicate transactions. No specific format is required for
this parameter.
After you submit a transaction with an external ID, Fireblocks will
automatically reject all future transactions with the same ID. Using
an external ID primarily helps in situations where, even though a
submitted transaction responds with an error due to an internet
outage, the transaction was still sent to and processed on the
blockchain. Use the [Get a specific transaction by external
transaction
ID](https://developers.fireblocks.com/reference/gettransactionbyexternalid)
endpoint to validate whether these transactions have been processed.
example: 00000000-0000-0000-0000-000000000000
assetId:
type: string
description: >-
The ID of the asset to transfer, for `TRANSFER`, `MINT` or `BURN`
operations. [See the list of supported assets and their IDs on
Fireblocks.](https://developers.fireblocks.com/reference/gettrlinksupportedasset#/)
x-fb-entity: asset
example: ETH
source:
$ref: '#/components/schemas/SourceTransferPeerPath'
destination:
$ref: '#/components/schemas/DestinationTransferPeerPath'
destinations:
type: array
description: >-
For UTXO based blockchains, you can send a single transaction to
multiple destinations.
items:
$ref: '#/components/schemas/TransactionRequestDestination'
amount:
description: >-
For `TRANSFER` operations, the requested amount to transfer, in the
asset’s unit. Fireblocks recommends using a numeric string for
accurate precision. Although a number input exists, it is
deprecated.
oneOf:
- type: string
description: Numeric string (recommended)
example: '0.02'
- type: number
description: Number (deprecated)
example: 0.02
treatAsGrossAmount:
type: boolean
description: >-
"When set to `true`, the fee will be deducted from the requested
amount."
**Note**: This parameter can only be considered if a transaction’s
asset is a base asset, such as ETH or MATIC. If the asset can’t be
used for transaction fees, like USDC, this parameter is ignored and
the fee is deducted from the relevant base asset wallet in the
source account.
example: false
forceSweep:
type: boolean
description: >-
For Polkadot, Kusama and Westend transactions only. When set to
true, Fireblocks will empty the asset wallet.
**Note:** If set to true when the source account is exactly 1 DOT, the transaction will fail. Any amount more or less than 1 DOT succeeds. This is a Polkadot blockchain limitation.
example: false
feeLevel:
type: string
description: >-
For UTXO, EVM-based, or Solana blockchains only. Defines the
blockchain fee level which will be payed for the transaction.
Alternatively, specific fee estimation parameters exist below.
enum:
- LOW
- MEDIUM
- HIGH
example: MEDIUM
fee:
description: >-
For UTXO-based blockchains, the fee per bytes in the asset’s
smallest unit (Satoshi, Latoshi, etc.). For Ripple, the fee for the
transaction. Fireblocks recommends using a numeric string for
accurate precision. Although a number input exists, it is
deprecated.
oneOf:
- type: string
description: Numeric string (recommended)
- type: number
description: Number (deprecated)
priorityFee:
description: >-
For Ethereum-based blockchains only, the fee for EIP-1559
transaction pricing mechanism. Value is in Gwei. Fireblocks
recommends using a numeric string for accurate precision. Although a
number input exists, it is deprecated.
oneOf:
- type: string
description: Numeric string (recommended)
example: '2'
- type: number
description: Number (deprecated)
example: 2
failOnLowFee:
type: boolean
description: >-
When set to `true`, in case the current `MEDIUM` fee level is higher
than the one specified in the transaction, the transaction will fail
to avoid getting stuck with no confirmations.
maxFee:
description: >-
The maximum fee (gas price or fee per byte) that should be payed for
the transaction. In case the current value of the requested
`feeLevel` is higher than this requested maximum fee. Represented
by a numeric string for accurate precision.
type: string
example: '120'
maxTotalFee:
description: >-
For BTC-based blockchains only. The maximum fee (in the units of the
fee-paying asset) that should be paid for the transaction.
type: string
example: '88'
gasLimit:
description: >-
For EVM-based blockchains only. Units of gas required to process the
transaction. Note: Only two of the three arguments can be specified
in a single transaction: `gasLimit`, `gasPrice` and `networkFee`.
Fireblocks recommends using a numeric string for accurate precision.
Although a number input exists, it is deprecated.
oneOf:
- type: string
description: Numeric string (recommended)
example: '21000'
- type: number
description: Number (deprecated)
example: 21000
gasPrice:
description: >-
For non-EIP-1559, EVM-based transactions. Price per gas unit (in
Ethereum this is specified in Gwei). Note: Only two of the three
arguments can be specified in a single transaction: `gasLimit`,
`gasPrice` and `networkFee`. Fireblocks recommends using a numeric
string for accurate precision. Although a number input exists, it
is deprecated.
oneOf:
- type: string
description: Numeric string (recommended)
- type: number
description: Number (deprecated)
networkFee:
description: >-
For EVM-based blockchains only. The total transaction fee in the
blockchain’s largest unit. Note: Only two of the three arguments can
be specified in a single transaction: `gasLimit`, `gasPrice` and
`networkFee`. Fireblocks recommends using a numeric string for
accurate precision. Although a number input exists, it is
deprecated. - The transaction blockchain fee.
- For Ethereum, you can't pass gasPrice, gasLimit and networkFee all
together.
- A numeric value representation is required.
oneOf:
- type: string
description: Numeric string (recommended)
- type: number
description: Number (deprecated)
replaceTxByHash:
type: string
description: >-
For EVM-based blockchains only. In case a transaction is stuck,
specify the hash of the stuck transaction to replace it by this
transaction with a higher fee, or to replace it with this
transaction with a zero fee and drop it from the blockchain.
example: 00000000-0000-0000-0000-000000000000
extraParameters:
$ref: '#/components/schemas/ExtraParameters'
utxoSelectionParams:
$ref: '#/components/schemas/UtxoSelectionParams'
customerRefId:
type: string
description: >-
The ID for AML providers to associate the owner of funds with
transactions.
example: abcdef
travelRuleMessage:
$ref: '#/components/schemas/TravelRuleCreateTransactionRequest'
travelRuleMessageId:
type: string
description: >-
The ID of the travel rule message from any travel rule provider.
Used for travel rule supporting functionality to associate
transactions with existing travel rule messages.
example: trm_12345678-1234-1234-1234-123456789012
autoStaking:
type: boolean
description: This feature is no longer supported.
deprecated: true
networkStaking:
deprecated: true
description: This feature is no longer supported.
oneOf:
- type: string
description: Numeric string (recommended)
- type: number
description: Number (deprecated)
cpuStaking:
deprecated: true
description: This feature is no longer supported.
oneOf:
- type: string
description: Numeric string (recommended)
- type: number
description: Number (deprecated)
useGasless:
type: boolean
description: '- Override the default gasless configuration by sending true\false'
SystemMessageInfo:
type: object
properties:
type:
type: string
enum:
- WARN
- BLOCK
message:
type: string
description: >-
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.
example: Slow transaction processing. Outgoing transactions might be stuck.
ErrorSchema:
type: object
properties:
message:
type: string
code:
type: number
TransactionOperation:
type: string
default: TRANSFER
enum:
- TRANSFER
- BURN
- CONTRACT_CALL
- PROGRAM_CALL
- MINT
- RAW
- TYPED_MESSAGE
- APPROVE
- ENABLE_ASSET
description: >
* `TRANSFER` - The default value for an operation. 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](https://developers.fireblocks.com/docs/ethereum-development#convenience-libraries)
are recommended for building contract call transactions.
* `PROGRAM_CALL` - Execute multiple instructions on Solana blockchain.
The @solana/web3.js library is recommended for building program 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://developers.fireblocks.com/docs/typed-message-signing).
* `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://developers.fireblocks.com/docs/raw-message-signing)
* `APPROVE` - Enables the approve function for a smart contract or
wallet to withdraw from a designated wallet. [Learn
more](https://support.fireblocks.io/hc/en-us/articles/4404616097426-Amount-Cap-for-Approve-transactions).
* `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 at a vault account.
SourceTransferPeerPath:
type: object
description: The source of the transaction.
properties:
type:
$ref: '#/components/schemas/TransferPeerPathType'
subType:
$ref: '#/components/schemas/TransferPeerPathSubType'
id:
type: string
name:
type: string
walletId:
type: string
format: uuid
isCollateral:
type: boolean
example: true
description: indicate if the source is collateral account
required:
- type
DestinationTransferPeerPath:
type: object
description: The destination of the transaction.
properties:
type:
$ref: '#/components/schemas/TransferPeerPathType'
subType:
$ref: '#/components/schemas/TransferPeerPathSubType'
id:
type: string
name:
type: string
walletId:
type: string
format: uuid
oneTimeAddress:
$ref: '#/components/schemas/OneTimeAddress'
isCollateral:
type: boolean
example: true
description: indicate if the destination is collateral account
required:
- type
TransactionRequestDestination:
type: object
properties:
amount:
type: string
destination:
$ref: '#/components/schemas/DestinationTransferPeerPath'
travelRuleMessageId:
type: string
description: >-
The ID of the travel rule message from any travel rule provider.
Used for travel rule supporting functionality to associate
transactions with existing travel rule messages.
example: trm_12345678-1234-1234-1234-123456789012
customerRefId:
type: string
description: >-
The ID for AML providers to associate the owner of funds with
transactions.
example: abcdef
ExtraParameters:
type: object
description: >
Additional protocol / operation specific key-value parameters:
For UTXO-based blockchain input selection, add the key `inputsSelection`
with the value set to the [input selection
structure.](https://developers.fireblocks.com/reference/transaction-objects#inputsselection)
The inputs can be retrieved from the [Retrieve Unspent Inputs
endpoint.](https://developers.fireblocks.com/reference/getunspentinputs)
For `RAW` operations, add the key `rawMessageData` with the value set to
the [raw message data
structure.](https://developers.fireblocks.com/reference/raw-signing-objects#rawmessagedata)
For `CONTRACT_CALL` operations, add the key `contractCallData` with the
value set to the Ethereum smart contract Application Binary Interface
(ABI) payload. The Fireblocks [development
libraries](https://developers.fireblocks.com/docs/ethereum-development#convenience-libraries)
are recommended for building contract call transactions.
For **exchange compliance (e.g., Binance) and Travel Rule purposes**,
include the key `piiData` containing a **custom JSON structure** with
Personally Identifiable Information (PII) relevant to the transaction.
This data must be fully **encrypted by the sender** before being
submitted to the Fireblocks API. The recommended encryption method is
**hybrid encryption** using AES-256-GCM for the payload and RSA-OAEP for
key exchange, with the recipient exchange's public key. [development
libraries](https://developers.fireblocks.com/docs/a-developers-guide-to-constructing-encrypted-pii-messages-for-binance-via-fireblocks)
**Note:** `rawMessageData`, `contractCallData`, and `inputsSelection`
cannot be used together in the same call.
additionalProperties: true
properties:
nodeControls:
description: >-
Configure special node requirements. For routing transactions to a
custom node: Set `type` to `NODE_ROUTER` and `tag` to the
pre-configured tag value. **For MEV protection:** Set only the
`type` property to `MEV` (tag is not required at this stage).
**Note:** This is a premium feature that should be enabled in your
workspace. Please contact your Customer Success Manager/Fireblocks
Support for more info.
anyOf:
- type: object
additionalProperties: true
- enum:
- null
rawMessageData:
description: >-
Object containing messages for raw signing and the algorithm to be
used. The value should be set to the [raw message data
structure.](https://developers.fireblocks.com/reference/raw-signing-objects#rawmessagedata)
anyOf:
- type: object
additionalProperties: true
- enum:
- null
contractCallData:
description: >-
Hex encoded contract call data as a string. For `CONTRACT_CALL`
operations, the value should be set to the Ethereum smart contract
Application Binary Interface (ABI) payload. The Fireblocks
[development
libraries](https://developers.fireblocks.com/docs/ethereum-development#convenience-libraries)
are recommended for building contract call transactions.
anyOf:
- type: string
- enum:
- null
programCallData:
description: BASE64 encoded Solana unsigned serialized transaction object.
anyOf:
- type: string
- enum:
- null
inputsSelection:
description: >-
For UTXO based blockchains, selections of inputs for the
transaction. The value should be set to the [input selection
structure.](https://developers.fireblocks.com/reference/transaction-objects#inputsselection)
The inputs can be retrieved from the [Retrieve Unspent Inputs
endpoint.](https://developers.fireblocks.com/reference/get_vault-accounts-vaultaccountid-assetid-unspent-inputs)
anyOf:
- type: object
additionalProperties: true
- enum:
- null
allowBaseAssetAddress:
description: >-
Transfers to unmanaged wallets only. When true, if the destination
doesn't have a whitelisted address for the requested asset, we'll
use the destination's whitelisted address of the base asset (e.g.,
use the ETH address for an ERC-20). If the requested asset's
whitelisted address exists, it is used.
**Note:** This is a premium feature that should be enabled in your
workspace. Please contact your Customer Success Manager or
Fireblocks Support for more information.
anyOf:
- type: boolean
- enum:
- null
piiData:
description: >-
For exchange compliance (e.g., Binance) and Travel Rule purposes,
contains a custom JSON structure with Personally Identifiable
Information (PII) relevant to the transaction. This data must be
fully encrypted by the sender before being submitted to the
Fireblocks API. The recommended encryption method is hybrid
encryption using AES-256-GCM for the payload and RSA-OAEP for key
exchange, with the recipient exchange's public key. [Learn
more](https://developers.fireblocks.com/docs/a-developers-guide-to-constructing-encrypted-pii-messages-for-binance-via-fireblocks)
anyOf:
- type: object
additionalProperties: true
- enum:
- null
UtxoSelectionParams:
type: object
description: >
For UTXO-based blockchains only. Controls which UTXOs are used for
automatic selection. Cannot be used together with
extraParameters.inputsSelection. This feature is currently in beta and
might be subject to changes.
properties:
filters:
$ref: '#/components/schemas/UtxoSelectionFilters'
inputSelection:
$ref: '#/components/schemas/UtxoInputSelection'
TravelRuleCreateTransactionRequest:
type: object
properties:
originatorVASPdid:
type: string
description: >-
The Decentralized Identifier (DID) of the exchange (VASP) that is
sending the virtual assets. This identifier is unique to the
exchange and is generated when the exchange's account is created in
the Notabene network.
example: did:ethr:0x44957e75d6ce4a5bf37aae117da86422c848f7c2
beneficiaryVASPdid:
type: string
description: >-
The Decentralized Identifier (DID) of the exchange (VASP) that is
receiving the virtual assets. This identifier is unique to the
exchange and is generated when the exchange's account is created in
the Notabene network.
example: did:ethr:0x17fe2dd11a2daa7f6c1fdf22532a4763f963aea6
originatorVASPname:
type: string
description: The name of the VASP acting as the transaction originator.
example: Originator VASP Ltd.
beneficiaryVASPname:
type: string
description: The name of the VASP acting as the transaction beneficiary.
example: Beneficiary VASP Inc.
beneficiaryVASPwebsite:
type: string
description: The website of the VASP acting as the transaction beneficiary.
example: https://www.beneficiaryvasp.com
transactionBlockchainInfo:
$ref: '#/components/schemas/TravelRuleTransactionBlockchainInfo'
originator:
$ref: '#/components/schemas/TravelRulePiiIVMS'
beneficiary:
$ref: '#/components/schemas/TravelRulePiiIVMS'
encrypted:
type: string
description: Encrypted data related to the transaction.
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
protocol:
type: string
enum:
- IVMS101
- TRLight
- TRP
- OpenVASP
- GTR
description: The protocol used to perform the travel rule.
example: IVMS101
targetProtocol:
type: string
description: The target protocol for GTR (Global Travel Rule) transfers.
example: GTR
skipBeneficiaryDataValidation:
type: boolean
description: Whether to skip validation of beneficiary data.
example: false
travelRuleBehavior:
type: boolean
description: >-
Whether to check if the transaction complies with the travel rule in
the beneficiary VASP's jurisdiction.
example: true
originatorRef:
type: string
description: A reference ID related to the originator of the transaction.
example: ORG123456
beneficiaryRef:
type: string
description: A reference ID related to the beneficiary of the transaction.
example: BEN654321
travelRuleBehaviorRef:
type: string
description: A reference ID related to the travel rule behavior.
example: TRB987654
originatorProof:
$ref: '#/components/schemas/TravelRuleOwnershipProof'
beneficiaryProof:
$ref: '#/components/schemas/TravelRuleOwnershipProof'
beneficiaryDid:
type: string
description: >-
The Decentralized Identifier (DID) of the person at the receiving
exchange (VASP). This identifier is generated when the customer is
registered in the Notabene network, or automatically created based
on the `beneficiaryRef`. - If neither `beneficiaryRef` nor
`beneficiaryDid` is provided in the `txCreate` payload,
a new random DID is generated for every transaction.
example: did:key:z6Mkf67890Zghijkl67890
originatorDid:
type: string
description: >-
The Decentralized Identifier (DID) of the person at the exchange
(VASP) who is requesting the withdrawal. This identifier is
generated when the customer is registered in the Notabene network or
automatically created based on the `originatorRef`. - If neither
`originatorRef` nor `originatorDid` is provided in the `txCreate`
payload,
a new random DID is generated for every transaction.
example: did:key:z6Mkf12345Zabcdef12345
isNonCustodial:
type: boolean
description: Indicates if the transaction involves a non-custodial wallet.
example: true
required:
- originator
- beneficiary
TransferPeerPathType:
type: string
enum:
- VAULT_ACCOUNT
- EXCHANGE_ACCOUNT
- CONNECTED_ACCOUNT
- INTERNAL_WALLET
- EXTERNAL_WALLET
- CONTRACT
- NETWORK_CONNECTION
- FIAT_ACCOUNT
- COMPOUND
- GAS_STATION
- ONE_TIME_ADDRESS
- UNKNOWN
- END_USER_WALLET
- PROGRAM_CALL
- MULTI_DESTINATION
- OEC_PARTNER
TransferPeerPathSubType:
type: string
enum:
- BINANCE
- BINANCEUS
- BITFINEX
- BITHUMB
- BITMEX
- BITSO
- BITSTAMP
- BITTREX
- BLINC
- BYBIT
- CIRCLE
- COINBASEEXCHANGE
- COINBASEPRO
- COINMETRO
- COINSPRO
- CRYPTOCOM
- DERIBIT
- GEMINI
- HITBTC
- HUOBI
- INDEPENDENTRESERVE
- KORBIT
- KRAKEN
- KRAKENINTL
- KUCOIN
- LIQUID
- OKCOIN
- OKEX
- PAXOS
- POLONIEX
- External
- Internal
- VIRTUAL_ACCOUNT
OneTimeAddress:
type: object
properties:
address:
type: string
tag:
type: string
required:
- address
UtxoSelectionFilters:
type: object
description: >
Narrow the UTXO candidate pool. All specified filters are AND-ed
together. This feature is currently in beta and might be subject to
changes.
properties:
includeAllLabels:
type: array
items:
type: string
description: Only include UTXOs that have ALL of these labels.
example:
- cold-storage
includeAnyLabels:
type: array
items:
type: string
description: Only include UTXOs that have at least one of these labels.
example:
- vip
- high-value
excludeAnyLabels:
type: array
items:
type: string
description: Exclude UTXOs that have any of these labels.
example:
- deprecated
address:
type: string
description: Only include UTXOs from this specific address.
example: 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa
minAmount:
type: string
description: Minimum UTXO amount in the asset's base unit (e.g., BTC).
example: '0.001'
maxAmount:
type: string
description: Maximum UTXO amount in the asset's base unit (e.g., BTC).
example: '9.999'
useChange:
type: boolean
description: Set to false to exclude change UTXOs. Default is true.
example: true
useCoinbase:
type: boolean
description: Set to false to exclude coinbase UTXOs. Default is true.
example: true
UtxoInputSelection:
type: object
description: >
Explicitly control which UTXOs to include or exclude. This feature is
currently in beta and might be subject to changes.
properties:
inputsToSpend:
type: array
items:
$ref: '#/components/schemas/UtxoInput'
description: Force-include specific UTXOs by txHash and vout.
inputsToExclude:
type: array
items:
$ref: '#/components/schemas/UtxoInput'
description: Exclude specific UTXOs from selection.
fillFeeForSelectedInputs:
type: boolean
description: >
When true and inputsToSpend is provided, automatically add more
UTXOs to cover the transaction fee. Requires inputsToSpend.
example: true
TravelRuleTransactionBlockchainInfo:
type: object
description: Information about the blockchain transaction.
properties:
txHash:
type: string
description: The hash of the transaction
example: 6.685730843558756e+76
origin:
type: string
description: The origin address of the transaction
example: 8.41132469470587e+47
destination:
type: string
description: The destination address of the transaction
example: 8.41132469470587e+47
TravelRulePiiIVMS:
type: object
description: Personal identifiable information related to the transaction
properties:
originatorPersons:
type: array
description: Information about the originator of the transaction
items:
$ref: '#/components/schemas/TravelRulePerson'
beneficiaryPersons:
type: array
description: Information about the beneficiary of the transaction
items:
$ref: '#/components/schemas/TravelRulePerson'
accountNumber:
type: array
description: Beneficiary account number. The value must be encrypted.
items:
type: string
example: QmNkEt9VdnhjefQMXo3ZaZAs765ugoWiazaqcY9skHMjCt
TravelRuleOwnershipProof:
type: object
description: Ownership proof related to the originator of the transaction.
properties:
type:
type: string
description: >-
The type of ownership proof. Example values: - `eip-191`: Ethereum
signature proof - `eip-712`: Ethereum typed data signature proof -
`bip-137`: Bitcoin signature proof - `microtransfer`:
Microtransaction (Satoshi test) - `screenshot`: Uploaded screenshot
of the wallet - `self-declaration`: Checkbox attestation of
ownership
example: eip-191
proof:
type: string
description: >-
The cryptographic signature, transaction hash, or other proof
depending on the type. Examples: - For `eip-191`:
`0x3dd4a17a...ce4a2bcd1b` - For `microtransfer`: The transaction
hash `H3V8GXBy39Dz...tr3TSTkY=`
example: 0x3dd4a17a...ce4a2bcd1b
attestation:
type: string
description: >-
A human-readable statement of wallet ownership. Required for
signature proofs and self-declarations. Examples: - `I certify that
ETH account 0x896B...0b9b belongs to me.` - `I hereby declare that
the blockchain address 0xa437bEed902AF9338B7DEB23848e195d85019510 is
under my control.`
example: I certify that ETH account 0x896B...0b9b belongs to me.
address:
type: string
description: >-
The wallet address being verified. Examples: - For Ethereum:
`0x896B...0b9b` - For Bitcoin: `1442...dxhsQ`
example: 0x896B...0b9b
wallet_provider:
type: string
description: >-
The wallet provider or method used for verification. Examples: - For
Metamask: `Metamask` - For manual signature: `manual`
example: Metamask
url:
type: string
description: >-
The URL for the uploaded screenshot (for `screenshot` proof types
only). Example: `https://example.com/uploaded_image.png`
example: https://example.com/uploaded_image.png
did:
type: string
description: >-
The Decentralized Identifier (DID) associated with the ownership
proof.
example: did:key:z6Mkf12345Zabcdef12345
status:
type: string
description: The status of the ownership proof verification.
example: verified
confirmed:
type: boolean
description: >-
Whether the user confirmed ownership of the wallet (for
`self-declaration` proofs). Example: `true`
example: true
UtxoInput:
type: object
properties:
txHash:
type: string
example: b34f0c3ce612f1e5a5c19d6b1e6b5e3e7f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c
vout:
type: integer
example: 0
required:
- txHash
- vout
TravelRulePerson:
type: object
properties:
naturalPerson:
$ref: '#/components/schemas/TravelRuleNaturalPerson'
legalPerson:
$ref: '#/components/schemas/TravelRuleLegalPerson'
TravelRuleNaturalPerson:
type: object
properties:
name:
type: array
items:
$ref: '#/components/schemas/TravelRuleNaturalPersonNameIdentifier'
description: >-
An array of structured name identifiers for the natural person,
referencing the TravelRuleNaturalPersonNameIdentifier schema.
geographicAddress:
type: array
items:
$ref: '#/components/schemas/TravelRuleGeographicAddress'
description: >-
An array of geographic addresses associated with the natural person,
referencing the TravelRuleGeographicAddress schema.
nationalIdentification:
$ref: '#/components/schemas/TravelRuleNationalIdentification'
dateAndPlaceOfBirth:
$ref: '#/components/schemas/TravelRuleDateAndPlaceOfBirth'
customerIdentification:
type: string
description: >-
A unique identifier for the customer within the organization's
context. The value must be encrypted.
example: QmTJsK3sc3fPEVwvAp97UUiVoFhjzQhYX3sCda1JxuCnXj
countryOfResidence:
type: string
description: >-
The ISO-3166 Alpha-2 country code of the natural person's residence.
The value must be encrypted.
example: QmTJsK3sc3fPEVwvAp97UUiVoFhjzQhYX3sCda1JxuCnXj
customerNumber:
type: string
description: >-
A distinct identifier that uniquely identifies the customer within
the organization. The value must be encrypted.
example: QmTJsK3sc3fPEVwvAp97UUiVoFhjzQhYX3sCda1JxuCnXj
TravelRuleLegalPerson:
type: object
properties:
name:
$ref: '#/components/schemas/TravelRuleLegalPersonNameIdentifier'
geographicAddress:
type: array
items:
$ref: '#/components/schemas/TravelRuleGeographicAddress'
description: The array of geographic addresses associated with the legal person.
nationalIdentification:
$ref: '#/components/schemas/TravelRuleNationalIdentification'
customerIdentification:
type: string
description: >-
A unique identifier that identifies the customer in the
organization's context. The value must be encrypted.
example: QmRY9AA4Uit2JRTxDzfzshrJdTK86Kf5HriA3dXDnihDmy
customerNumber:
type: string
description: >-
A distinct identifier that uniquely identifies the customer within
the organization. The value must be encrypted.
example: QmXvyML3AJUFpBbJqL5NVp7Vn7xNkuedTsSMk93duLCNW8
countryOfRegistration:
type: string
description: >-
The ISO-3166 Alpha-2 country code where the legal person is
registered. The value must be encrypted.
example: QmeoTk6UPruEAYNbJEAHdQYc53ap9BXmpnPMcuvs8wutdr
TravelRuleNaturalPersonNameIdentifier:
type: object
properties:
nameIdentifier:
type: array
items:
$ref: '#/components/schemas/TravelRuleNaturalNameIdentifier'
localNameIdentifier:
type: array
items:
$ref: '#/components/schemas/TravelRuleNaturalNameIdentifier'
phoneticNameIdentifier:
type: array
items:
$ref: '#/components/schemas/TravelRuleNaturalNameIdentifier'
TravelRuleGeographicAddress:
type: object
properties:
streetName:
type: string
description: Name of a street or thoroughfare. The value must be encrypted.
example: QmZGXXsKPk5iPS97LLjXB5e8Qs555ocdzcpbPMXvt84Ji9
townName:
type: string
description: >-
Name of a built-up area, with defined boundaries, and a local
government. The value must be encrypted.
example: QmNkEt9VdnhjefQMXo3ZaZAs765ugoWiazaqcY9skHMjCt
country:
type: string
description: >-
Nation with its own government (ISO-3166 Alpha-2 country code). The
value must be encrypted.
example: QmRGHdoxQfSi6tevyvaYGzs8BVStfqJqEyrMYqUfzXxkmm
buildingNumber:
type: string
description: >-
Number that identifies the position of a building on a street. The
value must be encrypted.
example: QmUFpNkxdsVtebDSUz5eP51kzoysXmqj2gBgeH11PD7SVP
postCode:
type: string
description: >-
Identifier consisting of a group of letters and/or numbers added to
a postal address to assist the sorting of mail. The value must be
encrypted.
example: QmTJsK3sc3fPEVwvAp97UUiVoFhjzQhYX3sCda1JxuCnXj
addressType:
type: string
description: >-
Specifies the type of address. Acceptable values are: - 'HOME':
Residential, the home address - 'BIZZ': Business, the business
address - 'GEOG': Geographic, an unspecified physical (geographical)
address The value must be encrypted.
example: Qmdr9LcChZsoivS6uAhe7Qk7cGLDAx73wBZTVvq4WoU71H
department:
type: string
description: >-
Identification of a division of a large organisation or building.
The value must be encrypted.
example: QmN7fb65x5MyA7RKyhbXaUKvJ7U4Y9eqpEZTmJYpNyEG8
subDepartment:
type: string
description: >-
Identification of a sub-division of a large organisation or
building. The value must be encrypted.
example: QmTkfyGh54tXNqFxyEGK9NyTJZYpQ6RZ9zpNykxykME8s
buildingName:
type: string
description: Name of the building or house. The value must be encrypted.
example: QmXJfGk85t6RKyhbXaEK9Nz4MEeMKypq6EY9zpJyC9nM9
floor:
type: string
description: Floor or storey within a building. The value must be encrypted.
example: QmZP5G7fhZpMyQxXnT9KyR6ybXaEM9zpJy4ME9MkTJGE1
postBox:
type: string
description: Numbered box in a post office. The value must be encrypted.
example: QmTkfYRGK54xFqXyJYNZyE9kY9zpMKytJnXy5z9EME9sJ
room:
type: string
description: Building room number. The value must be encrypted.
example: QmRYXnT9KyhbXaEMZpMyxMkZ9zpYNYTJ4ME5kCGE7fhMJ
townLocationName:
type: string
description: Specific location name within the town. The value must be encrypted.
example: QmNpZTyXJXnT9K6EYZpQxYNYMkC5p4kGEfhnkMJzpYT9Jm
districtName:
type: string
description: >-
Identifies a subdivision within a country subdivision. The value
must be encrypted.
example: QmT9p6ERKyNYXnTyhbpMYJ4zpYT9kMJZT9QmEMGZ5kMhCy
countrySubDivision:
type: string
description: >-
Identifies a subdivision of a country such as state, region, or
province. The value must be encrypted.
example: QmK9yTbXaZpMYJYTYp6NT9QmEMGZT9p9kMJfhyGE4Z7k5C
addressLine:
type: array
items:
type: string
description: >-
Information that locates and identifies a specific address,
presented in free format text. Each item must be encrypted.
example:
- QmNp9kMjfhGZ5kMJzpNYXZTy6NQmZYEMGZ4kZT9Y6pNYT
TravelRuleNationalIdentification:
type: object
description: Represents a national identifier for a person or entity
properties:
countryOfIssue:
type: string
description: >-
Country that issued the national identifier (ISO-3166 Alpha-2
country code). The value must be encrypted.
example: QmRGHdoxQfSi6tevyvaYGzs8BVStfqJqEyrMYqUfzXxkmm
nationalIdentifier:
type: string
description: >-
National identifier (max 35 characters). The value must be
encrypted.
example: QmdR6qLnZ7Kwf5cBaXG8QFQenEvRg9JNZeoPranVuGd63z
nationalIdentifierType:
type: string
description: >-
Type of national identifier. Acceptable values include: -
'PASSPORT': Passport number - 'NATIONAL_ID': National identification
number - 'TAX_ID': Tax identification number - 'SOCIAL_SECURITY':
Social security number The value must be encrypted.
example: QmUKTg3aFJFhMz1o9gPqA3MgTRwd2LvDLwWTPHYUoMEYVi
registrationAuthority:
type: string
description: >-
Registration authority (format -> RA followed by 6 digits). The
value must be encrypted.
example: QmV9KJMyT9RJzpYfhME5xNCZ4G67fEkzTpRMyJzp9kTNYk
TravelRuleDateAndPlaceOfBirth:
type: object
description: Represents the date and place of birth for a natural person
properties:
dateOfBirth:
type: string
description: Date of birth. The value must be encrypted.
example: QmNkEt9VdnhjefQMXo3ZaZAs765ugoWiazaqcY9skHMjCt
placeOfBirth:
type: string
description: Place of birth. The value must be encrypted.
example: QmNkEt9VdnhjefQMXo3ZaZAs765ugoWiazaqcY9skHMjCt
TravelRuleLegalPersonNameIdentifier:
type: object
properties:
legalPersonName:
type: string
description: >-
Name by which the legal person is known. The value must be
encrypted.
example: QmVXXj5BJchhqQTU27uEkeghYMnxR6aVjZxJP9jS6uCg9Q
legalPersonNameIdentifierType:
type: string
description: >-
Specifies the type of name for a legal person. Acceptable values
are: - 'REGISTERED': The official registered name. - 'TRADE': A
trading name or DBA (Doing Business As) name. - 'OTHER': Any other
type of name. The value must be encrypted.
example: QmPevsa5xdkxf6Lgt7f9YweRBdgseeAkWVaYyssKF3Q86e
TravelRuleNaturalNameIdentifier:
type: object
properties:
primaryIdentifier:
type: string
description: The primary identifier of the name. The value must be encrypted.
example: QmP6wx8bx3SVNG3hd3SZKnS5pDjUan4y9H1VtyRqu7tsAv
secondaryIdentifier:
type: string
description: The secondary identifier of the name. The value must be encrypted.
example: QmP6wx8bx3SVNG3hd3SZKnS5pDjUan4y9H1VtyRqu7tsAv
nameIdentifierType:
type: string
description: >-
The type of the name identifier. The value must be encrypted. The
value must be one of the following: [LEGL, DBA, TRAD, NICK, ALIA,
MAID, FORM, PREV, BORN, OTHR].
example: QmP6wx8bx3SVNG3hd3SZKnS5pDjUan4y9H1VtyRqu7tsAv
responses:
Error:
description: Error Response
headers:
X-Request-ID:
$ref: '#/components/headers/X-Request-ID'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
headers:
X-Request-ID:
schema:
type: string
description: >-
Unique ID correlated to the API request. Please provide it in any
support ticket you create or on Github issues related to Fireblocks SDKs
````