In this guide, we'll walk you through the essential processes to perform authenticated requests on Ledger Enterprise APIs as an API Operator. Follow these steps to obtain the necessary authentication token and explore some common API functionalities.
Step 1: Obtain Authentication Token
To access Ledger Enterprise Apis as an API Operator, you need to obtain an authentication token by making a POST request to the authentication endpoint. Use the following example:
This request returns an access_token, which you will use in subsequent authenticated requests.
Step 2: List Accounts
Now that you have the access token, you can use it to list the accounts you have access to of this workspace. Make a GET request to the search accounts endpoint:
This request returns a list of accounts along with their details, including balance, currency, and status. This endpoint is paginated, to learn more about how pagination work please refer the the API documentation.
Step 3: Create a Transaction
To create a transaction follow the below instructions.
Building your request payload:
To build a payload to create a new outgoing transaction request, we just need to know:
the sender account, in our case let's use one account from the previous payload; the account named ClientA COL TBTC 1 , id 2 .
the recipient address , let's use tb1q5tsjcyz7xmet07yxtumakt739y53hcttmntajq
the amount we want to send, let's say 2 tBTC
We will need to create CREATE_TRANSACTION request type for the requests endpoint. Then in data we will be passing the transaction intention following the specifications depending on each type of transaction, since we are using a bitcoin testnet account, we need to be follwing the "transaction_type": "BITCOIN_LIKE_SEND",, we know this from the account object we received earlier of "type": "Bitcoin",.
You can check the requests endpoint on how to specify the fees_strategy for each transaction_type. In our case we will follow the standard fee priotity model, FAST, to make sure our transaction is processed quickly by the node.
We also need to build up the transaction_data object, in this object you will specify more precisly your intention, it's redondent yet it allows a better security validation of the challenge later on. In our case we need to :
A currency should be the same as the one in your account in this case bitcoin_testnet , this allow the HSM to validate he is signing for the good derivation path and prevent an attacker to switch this derivation path to your main bitcoin account without you knowing.
Sender account_name wich is the unique identifier of your account on the HSM, in our case ClientA COL TBTC 1
A max_fees it's the highest amount of fees in the blockchain asset your are willing to pay for in this transaction, this is used to assert the transaction at a signature level when HSM sees that the crafted Tx is spending more in fees that what you specify here. And since fees can vary from the type you create the tx to the time it get signed by all of the other operator, it's generally good to include a buffer, the estimate fees endpoint and following section help you select this value. You can also set your own based on the max amount you are willing to pay it's acting as an extra security
The recipient , use the address you want to send BTC to tb1q5tsjcyz7xmet07yxtumakt739y53hcttmntajq
The amount you want to send in the smallest unit of this asset. You can use the get currency by name endpoint to get all of the information about the currency you are using. To convert your 2tBTC in tsat you need to get the magnitude of the currency bitcoin_testnet . In our case the tBTC magnitude is 8 it means that I need to multiply the amount in tBTC by this magnitude to get the amount for this payload in satoshis (tsat) so 2 * 10^8 = 200000000 .
The use the same payload to compute the recomended fees and maxfees by calling the [transactions/estimate-fees endpoint (/openapi/leapi/tag/Transactions/paths/~1transactions~1estimate-fees/post/) endpoint. You can also define custom fees and advanced options please refer to the fees & speed section of the help center for more informations.
If the response status is 200, the response payload will have the attribute max_fees, you can use it in your inital payload, for the following step we will refer to this value with max_fees_from_estimate_fees_endpoint.
POST Create Transaction request:
Then create the actual transaction request with the same payload except that the max_fees value must be relevant, use the one extracted in the previous step.
Once the transaction is created, it can be approved by the different opeators in the transaction rules. Transaction rules can vary from an account to the other. It'll affect how you create transactions as the amount per transaction can be limited (Amount ranges) as well as the possible list of allowed recipients (Whitelisted addresses). To find out which rules have been defined in an account, go to Accounts > Account dashboard > Rules tab.
The attribute target_id of a request in our example of type CREATE_TRANSACTION provides the id of the transaction.
Step 4: Approve a request
Once you created your transaction request following step 3, you need to approve the challenge as the request creator before other operator are notified to approve. To approve a request, you'll need to follow these steps:
Get the challenge
Given a request_id, first need to fetch the HSM challenge:
Decode the challenge to validate that the instructions HSM received is the same as the one you passed in your request:
import jwt
// decode the challenge
challenge_data_bytes = jwt.utils.base64url_decode(challenge)
import * as crypto from 'crypto';
import * as jwt from 'jsonwebtoken';
// decode the challenge
const decodedString = atob(dataToSign);
const jsonObject = JSON.parse(decodedString);
Carefully review that what you are about to sign is the right instructions matching your inital intention. This challenge is the trusted data signed by your operator that will allow the HSM to sign the true transaction. For example, if you see that the recipient is not the same address you requested this is a sign that there is a potential man in the middle attack, regardless of what the request was the true singed transaction will be send to the recipient from this challenge. Don't trust, verify.
This is an important step, when decoding the challenge from the HSM this need to be the exact same infromation the transaction creator passed in transaction_data.
And jws the signed challenge / jws object. The resulting jws consists of three parts: the JWS Header, the JWS Payload, and the JWS Signature. The three parts are base64url-encoded and concatenated in that order being separated by period ('.') characters.
Approve the request
Once you signed the challenge use it to post your approval on the approve request endpoint:
If the response status is 200, the response payload will be the request with its new status, in our case we are still waiting for another approval from a second user so the status stays in PENDING_APPROVAL.
Step 5: Additional Functionalities
Explore additional functionalities, such as getting an account balance, subscribing to Vault events via web-hooks, getting request info, and getting the number of request approvers. Refer to the provided examples for detailed instructions.
5.1. How to Get an Account Balance
To retrieve the balance of a specific account, you can make a GET request to either of the following endpoints:
Get Account & balances
To get an account balance, one can either call the get account by ID and extract balance or available_balance
5.2. How to Subscribe to Vault Events via Web-hooks
Stay informed about events related to accounts, groups, requests, transactions, users, or whitelists by subscribing to web-hooks. Configure notifications using the following example:
For more details on how to use this endpoint please refer to the API documentation.
Replace {{notification_endpoint}} with a valid HTTPS endpoint that accepts POST queries. You'll receive notifications similar to the following payload:
The attribute target_id of a request in our example of type CREATE_TRANSACTION provides the id of the transaction.
You can also search requests for example of type CREATE_TRANSACTION or in status PENDING_APPROVAL to get the list of request pending approval of some operators.
Looking at the json I can see that request id 62 is completely approved "is_complete": true,, with one approval from an operator that is anonymized from my scope, we can also see that there where 4 potential approvers for this request from the approvers array, we know that all theses approvers where part of groupe 11. From "quorum": 1, and "step_index": 0 we learn that this request only needed 1 approval out of all of the groupe members for it to be submited.
Congratulations! You've completed the first steps as an API User. Feel free to explore more functionalities and reach out if you have any questions or need further assistance. Happy coding!
