Adapter Reference
The Fireblocks Adapter mirrors the Fireblocks REST paths and payloads listed below. Every call is translated into a Vault operation and evaluated by the Policy Engine.
Supported Endpoints
Vault accounts
| Method | Path | Description |
|---|---|---|
POST | | Create a vault account |
GET | | Get a vault account |
GET | | List vault accounts |
POST | | Hide a vault account |
POST | | Unhide a vault account |
Vault assets
| Method | Path | Description |
|---|---|---|
POST | | Activate an asset |
GET | | Get asset balance |
GET | | List asset addresses |
Transactions
| Method | Path | Description |
|---|---|---|
POST | | Create a transaction |
POST | | Estimate a transaction fee |
GET | | Get a transaction |
Whitelists
| Method | Path | Description |
|---|---|---|
GET | | List external wallets |
Assets
| Method | Path | Description |
|---|---|---|
POST | | Supported assets |
Webhook Events
| Event | Trigger |
|---|---|
transaction.created | A deposit was detected on one of your vault accounts |
transaction.status.updated | An outgoing transaction moved to a new status: awaiting approval, signed, broadcast, confirmed or failed |
test.ping | A synthetic event sent from the console to verify the endpoint |
Every delivery goes through a persistent outbox with retries. The console shows each attempt, its status and the last error, so a broken endpoint becomes visible to you before it becomes visible to your customers.
Authentication and Base URL
- Base URL: the adapter endpoint for your environment, in the form
https://<your-stand>/fb-gateway. Your account manager provides the exact URL. - Authentication: the API key, sent in the
X-API-Keyheader.
Idempotency
POST /v1/vault/accounts and POST /v1/transactions accept the Fireblocks
Idempotency-Key header. The header is optional, at most 40 characters, valid
UTF-8; otherwise the adapter answers 400 and creates nothing. A key is scoped
to your integration and answers for 24 hours.
- Vault accounts. A retry with the same key returns the vault account created by the first request. No second account is created.
- Transactions. A retry with the same key returns the transfer created by the
first request, with its current status. The same applies to
externalTxId, without a time limit. A retry must ask for the same transfer: the amount, asset, source and destination have to match.
| Situation | Response |
|---|---|
A transfer is already recorded for the key or externalTxId | 200 with that transfer and its current status |
The key or externalTxId was used for a different transfer | 422 |
| The first request is still being processed | 409; retry later. If it persists, contact your account manager |
Send an Idempotency-Key or an externalTxId with every transaction request, so
that a retry is safe. If a request failed before anything was created, a retry
with the same key runs again.