Finassets API Documentation (1.0.0)

Download OpenAPI specification:Download

Introduction

API Endpoints

Authentication

Finassets uses API keys to authenticate all requests. You can request API keys by contacting support.

All requests must contain:

  • Query parameter:
    • request_uuid - Request unique identifier as a string (max 50 chars)
  • Headers:
    • API-Key - The API key
    • Api-Signature - Value of Base64Encode(HMAC-SHA512 on string(request_uuid + request_type + request_uri_part) using SECRET_KEY)

Api-Signature generation example:

  • request_uuid - 'db2f924d-b3bb-4f73-a4c1-7a144f6f01cd'
  • request_type - 'GET'
  • request_uri_part - 'api/v1/account/address'
  • secret_key - 'dcdbbd81b36d1ae66ec8b381b272ae7c/IgzXNJ9K2BfCHkQ'
  • Api-Signature - 74gjMlNjIFoIJSjAL9k7s1yHHzkojNp2Np5EnWHv7NaROKhaGk4S025hjJzil9BQk+6VyhImgsIorfjTRe2g7w==

PHP: base64_encode(hash_hmac('sha512', $request_uuid . $request_type . $request_uri_part, $secret_key, true))
Python: base64.b64encode(hmac.new(Secret.encode('utf-8'), (request_uuid+request_type+request_uri_part).encode('utf-8'), hashlib.sha512).digest()).decode()

IP Whitelisting

Finassets supports restriction of API calls to be accepted only from a specific IP address per API key. If you wish to whitelist your IP address, please contact support.

Limitations

Finassets allows up to 100 requests per minute.

Account

Get account information

Retrieve account information and balance.

query Parameters
request_uuid
required
string <= 50 characters

Request unique identifier.

Responses

Response samples

Content type
application/json
{
  • "keyword": "TEST1",
  • "active": true,
  • "deposit": true,
  • "withdraw": false,
  • "depositFee": "1.00",
  • "withdrawFee": "2.00",
  • "balances": [
    ],
  • "depositBalances": [ ],
  • "exchangeBalances": [ ]
}

Get available assets

View information of all assets.

query Parameters
request_uuid
required
string <= 50 characters

Request unique identifier.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get deposit address

Retrieve deposit address for a specific user.

query Parameters
request_uuid
required
string <= 50 characters

Request unique identifier.

asset
required
string

Name of the asset.

userId
required
string <= 45 characters

User unique ID.

Responses

Response samples

Content type
application/json
{
  • "userId": "1234567",
  • "asset": "BTC_TEST",
  • "address": "tb1qvwe700h2q4n3urcjyh7c4xs35zmjj6sm9kh48a",
  • "legacyAddress": "mpc8i5gpjYyaoV5Jvtux7nmb6H8qHKx2yU"
}

Sweeping

Sweep funds from your deposit wallets.

query Parameters
request_uuid
required
string <= 50 characters

Request unique identifier.

Request Body schema: application/json
asset
string

Name of the asset.

feeLevel
string or null
Default: "MEDIUM"
Enum: "LOW" "MEDIUM" "HIGH"

Blockchain fee level.

to
string or null
Default: "withdrawal"
Enum: "withdrawal" "exchange"

Destination wallet type.

Responses

Request samples

Content type
application/json
{
  • "asset": "string",
  • "feeLevel": "LOW",
  • "to": "withdrawal"
}

Response samples

Content type
application/json
{
  • "success": true
}

Transactions

List all transactions

View all transactions.

query Parameters
request_uuid
required
string <= 50 characters

Request unique identifier.

status
string
Enum: "COMPLETED" "FAILED" "SUBMITTED" "CONFIRMING"

Transaction status.

type
string
Enum: "deposit" "withdraw"

Type of the transaction.

asset
string

Name of the asset.

limit
integer [ 10 .. 250 ]
Default: 10

Maximum number of transactions to be returned.

offset
integer
Default: 0

Offset the result set by a specific number of items.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a transaction

Create a new withdrawal transaction.

query Parameters
request_uuid
required
string <= 50 characters

Request unique identifier.

Request Body schema: application/json
asset
required
string

Name of the asset.

amount
required
string

Amount to withdraw. Number format: 123.456 (up to 8 decimal places).

address
required
string

Destination address.

tag
string

Destination tag for XRP (Ripple) and TON.

feeLevel
string
Default: "MEDIUM"
Enum: "LOW" "MEDIUM" "HIGH"

Blockchain fee level.

refId
string <= 45 characters

Reference ID.

userId
string <= 45 characters

User unique ID.

includeFee
boolean
Default: false

If set to true the network fee will be deducted from the requested amount.

Responses

Request samples

Content type
application/json
{
  • "asset": "string",
  • "amount": "string",
  • "address": "string",
  • "tag": "string",
  • "feeLevel": "LOW",
  • "refId": "string",
  • "userId": "string",
  • "includeFee": false
}

Response samples

Content type
application/json
{
  • "id": 56789
}

Retrieve a transaction

View a specific transaction by ID.

path Parameters
id
required
integer

Transaction ID.

query Parameters
request_uuid
required
string <= 50 characters

Request unique identifier.

Responses

Response samples

Content type
application/json
{
  • "id": 56789,
  • "asset": "ETH_TEST",
  • "amount": "0.02",
  • "networkFee": "0.0000281",
  • "feeAsset": "ETH_TEST",
  • "sourceAddress": "0x883437edFbd974gg1eA88a30c7580d2d4def7058",
  • "destinationAddress": "0x70Fecd618b6844A166f08Ea72DFaF4882D3F080a",
  • "txId": "80c39a0262e67b78a39c6cfa45ddc2478492ac8fb987910559450d918335c472",
  • "status": "COMPLETED",
  • "subStatus": "",
  • "type": "withdraw",
  • "refId": "123",
  • "userId": "123456",
  • "createdAt": "2022-01-10 16:14:11",
  • "updatedAt": "2022-01-10 16:14:55"
}

Set a reference ID

Set refId for a deposit transaction.

path Parameters
id
required
integer

Transaction ID.

query Parameters
request_uuid
required
string <= 50 characters

Request unique identifier.

Request Body schema: application/json
refId
string <= 45 characters

Reference ID.

required
any

Responses

Request samples

Content type
application/json
{
  • "refId": "string",
  • "required": null
}

Response samples

Content type
application/json
{
  • "success": true
}

Invoices

List all invoices

View all invoices.

query Parameters
request_uuid
required
string <= 50 characters

Request unique identifier.

status
string
Enum: "ACTIVE" "PAID" "UNDERPAID" "EXPIRED" "CLOSED" "PENDING_APPROVAL"

Invoice status.

project
string

Project key.

limit
integer [ 10 .. 250 ]
Default: 10

Maximum number of transactions to be returned.

offset
integer
Default: 0

Offset the result set by a specific number of items.

Responses

Response samples

Content type
application/json
Example

List of invoices.

[
  • {
    }
]

Create an invoice

Create a new invoice.

query Parameters
request_uuid
required
string <= 50 characters

Request unique identifier.

Request Body schema: application/json
key
required
string

Project key.

required
Array of objects (InvoiceItem) <= 10 items

Invoice items.

Array (<= 10 items)
name
string

Name of the item.

quantity
integer

Amount of items.

price
string

Price of the item.

orderId
string

Reference order ID.

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "items": [
    ],
  • "orderId": "string"
}

Response samples

Content type
application/json
Example

Live invoice url example.

{}

Retrieve an invoice

View a specific invoice by ID.

path Parameters
id
string

Invoice ID.

query Parameters
request_uuid
required
string <= 50 characters

Request unique identifier.

Responses

Response samples

Content type
application/json
{
  • "id": "vq29J0gYWG3nM4UWTiC7UmC8IdJoBu",
  • "amount": "5.1",
  • "received": "0",
  • "currency": "USD",
  • "items": [
    ],
  • "status": "ACTIVE",
  • "project": "QUbO2DU9gzkfEeWbF9X2",
  • "orderId": "ORDER12345",
  • "dueDate": "2023-04-26 17:35:26",
  • "createdAt": "2023-04-24 17:35:26",
  • "updatedAt": "2023-04-24 17:35:26"
}

Webhooks

Setup Webhooks

Setting a webhook will allow you to get notifications for events such as incoming/outgoing transactions. In order to connect a Webhook to your Fireblocks workspace please contact Support and provide your Webhook's URL. Once your webhook endpoint has been set up then any supported events that occur will trigger an HTTP POST call to your endpoint.

All webhooks will be sent with the following header:

  • Finassets-Signature - Value of Base64Encode(HMAC-SHA512 on json body using SECRET_KEY)

We consider a webhook attempt successful when you return a 200 HTTP status code within 30 seconds. A response body is not required. Any other status codes will be considered a failure. If a webhook attempt fails then we will resend the request after [1, 5, 10, 20, 40, 60, 120, 240, 360, 480, 600] minutes.

Transaction created Webhook

Transaction created.

Request Body schema: application/json
type
string
Enum: "TRANSACTION_CREATED" "TRANSACTION_UPDATED" "TRANSACTION_FAILED" "INVOICE_CREATED" "INVOICE_UPDATED"

Webhook type.

request_uuid
string

Webhook unique identifier.

datetime
string

Webhook date (UTC).

object (TransactionWebhook)
id
integer

Transaction unique ID.

asset
string

Name of the asset.

amount
string

Transaction amount.

networkFee
string

The fee paid to the network.

feeAsset
string

The asset in which the network fee was paid.

sourceAddress
string

The source address of the transaction.

destinationAddress
string

The address where the funds were sent.

txId
string

Blockchain transaction hash.

status
string

Current transaction status.

subStatus
string

Detailed status for FAILED transactions.

type
string

Type of the transaction (deposit or withdraw).

refId
string

Reference ID. Empty string by default, can be set via API.

userId
string or null

User unique ID. Can be NULL if the tag for XRP (Ripple) is invalid.

Request samples

Content type
application/json
{
  • "type": "TRANSACTION_CREATED",
  • "request_uuid": "b5eda2ac-d397-425c-b162-4ae0727f88a4",
  • "datetime": "2022-01-23 14:20:33",
  • "transaction": {
    }
}

Transaction updated Webhook

Transaction updated.

Request Body schema: application/json
type
string
Enum: "TRANSACTION_CREATED" "TRANSACTION_UPDATED" "TRANSACTION_FAILED" "INVOICE_CREATED" "INVOICE_UPDATED"

Webhook type.

request_uuid
string

Webhook unique identifier.

datetime
string

Webhook date (UTC).

object (TransactionWebhook)
id
integer

Transaction unique ID.

asset
string

Name of the asset.

amount
string

Transaction amount.

networkFee
string

The fee paid to the network.

feeAsset
string

The asset in which the network fee was paid.

sourceAddress
string

The source address of the transaction.

destinationAddress
string

The address where the funds were sent.

txId
string

Blockchain transaction hash.

status
string

Current transaction status.

subStatus
string

Detailed status for FAILED transactions.

type
string

Type of the transaction (deposit or withdraw).

refId
string

Reference ID. Empty string by default, can be set via API.

userId
string or null

User unique ID. Can be NULL if the tag for XRP (Ripple) is invalid.

Request samples

Content type
application/json
{
  • "type": "TRANSACTION_UPDATED",
  • "request_uuid": "b5eda2ac-d397-425c-b162-4ae0727f88a4",
  • "datetime": "2022-01-23 14:20:33",
  • "transaction": {
    }
}

Transaction failed Webhook

Transaction failed.

Request Body schema: application/json
type
string
Enum: "TRANSACTION_CREATED" "TRANSACTION_UPDATED" "TRANSACTION_FAILED" "INVOICE_CREATED" "INVOICE_UPDATED"

Webhook type.

request_uuid
string

Webhook unique identifier.

datetime
string

Webhook date (UTC).

object (TransactionWebhook)
id
integer

Transaction unique ID.

asset
string

Name of the asset.

amount
string

Transaction amount.

networkFee
string

The fee paid to the network.

feeAsset
string

The asset in which the network fee was paid.

sourceAddress
string

The source address of the transaction.

destinationAddress
string

The address where the funds were sent.

txId
string

Blockchain transaction hash.

status
string

Current transaction status.

subStatus
string

Detailed status for FAILED transactions.

type
string

Type of the transaction (deposit or withdraw).

refId
string

Reference ID. Empty string by default, can be set via API.

userId
string or null

User unique ID. Can be NULL if the tag for XRP (Ripple) is invalid.

Request samples

Content type
application/json
{
  • "type": "TRANSACTION_FAILED",
  • "request_uuid": "b5eda2ac-d397-425c-b162-4ae0727f88a4",
  • "datetime": "2022-01-23 14:20:33",
  • "transaction": {
    }
}

Invoice created Webhook

Invoice created.

Request Body schema: application/json
type
string
Enum: "TRANSACTION_CREATED" "TRANSACTION_UPDATED" "TRANSACTION_FAILED" "INVOICE_CREATED" "INVOICE_UPDATED"

Webhook type.

request_uuid
string

Webhook unique identifier.

datetime
string

Webhook date (UTC).

object (InvoiceWebhook)
id
string

Invoice unique ID.

amount
string

Invoice total amount.

received
string

Received amount.

currency
string

Fiat currency in which the invoice amount is calculated.

Array of objects (InvoiceItem)

Invoice item list.

Array
name
string

Name of the item.

quantity
integer

Amount of items.

price
string

Price of the item.

status
string

Current invoice status.

project
string

Project key.

orderId
string or null

Reference order ID.

dueDate
string

Invoice due date (UTC).

Request samples

Content type
application/json
{
  • "type": "INVOICE_CREATED",
  • "request_uuid": "b5eda2ac-d397-425c-b162-4ae0727f88a4",
  • "datetime": "2022-01-23 14:20:33",
  • "invoice": {
    }
}

Invoice updated Webhook

Invoice updated.

Request Body schema: application/json
type
string
Enum: "TRANSACTION_CREATED" "TRANSACTION_UPDATED" "TRANSACTION_FAILED" "INVOICE_CREATED" "INVOICE_UPDATED"

Webhook type.

request_uuid
string

Webhook unique identifier.

datetime
string

Webhook date (UTC).

object (InvoiceWebhook)
id
string

Invoice unique ID.

amount
string

Invoice total amount.

received
string

Received amount.

currency
string

Fiat currency in which the invoice amount is calculated.

Array of objects (InvoiceItem)

Invoice item list.

Array
name
string

Name of the item.

quantity
integer

Amount of items.

price
string

Price of the item.

status
string

Current invoice status.

project
string

Project key.

orderId
string or null

Reference order ID.

dueDate
string

Invoice due date (UTC).

Request samples

Content type
application/json
{
  • "type": "INVOICE_UPDATED",
  • "request_uuid": "b5eda2ac-d397-425c-b162-4ae0727f88a4",
  • "datetime": "2022-01-23 14:20:33",
  • "invoice": {
    }
}

Resend failed

Resend all failed webhooks.

query Parameters
request_uuid
required
string <= 50 characters

Request unique identifier.

Responses

Response samples

Content type
application/json
{
  • "webhookCount": 2
}

Resend a transaction

Resend all webhooks for a specific transaction.

path Parameters
id
required
integer

Transaction ID.

query Parameters
request_uuid
required
string <= 50 characters

Request unique identifier.

Responses

Response samples

Content type
application/json
{
  • "webhookCount": 2
}