Overview
BitGo is a leading custody provider for top protocols and token launches. They provide services including custody, liquidity, staking and delegation support. A number of our customers use BitGo to distribute employee and investor tokens.
Creating a New API Key
In order for Pulley to interact with your BitGo Custody account, you need to generate a new, unique API key. To do this:
In BitGo, navigate to 'Settings -> Developer Options -> Create Access Token'
This will prompt you to complete a modal, asking for:
Token Name
Valid Until Date
Permissions ('Wallet — Spend')
IP Addresses (Pulley will provide)
Lifetime Spending Limits (Some Number)
Once confirmed, record the access token to be later store into Pulley
In Pulley, navigate to Token Cap Table -> select Tokens -> Click on selected token -> Next to storage, click ‘Add’ -> Select BitGo'
There, you can add the new access token and hit 'save'
Testing Connection & Transfer
Once you successfully add in a new Access Token for BitGo, you can test that the basic access and transfer functionality works as expected in Pulley.
In the same section ('Company -> Tokens and Custodians Information -> Custodians') you should see two buttons, labelled 'Ping BitGo' and 'Test BitGo Transfer.'
Ping BitGo: This tests that your BitGo account information and access key were setup correctly. When pressed, you should see the following message appear: "BitGo wallet is setup correctly"
If you see an error message, you will likely need to generate a new API key for Pulley as the previous information was incorrect.
Test BitGo Transfer: This tests that Pulley has permission to initiate a new transfer request for your vault. When pressed, you will be prompted to enter a wallet address to transfer to, and a transfer amount.
Wallet address: This address should be whitelisted in your BitGo vault already (see below)
Transfer amount: Given this is a test transfer, this is usually a low token amount (above the minimum transaction size for the asset)
When initiated, you should see the following success message appear: "BitGo test transfer was made".
If you see an error message, double check that the wallet address is valid and whitelabelled in BitGo.
Whitelabelling Addresses
Depending on your wallet settings, you may or may not need to whitelabel all tokenholder wallet addresses to allow for token distributions.
Pulley recommends requiring whitelabelling for all transfers as an extra layer of security.
To whitelabel addresses on BitGo, navigate to: 'Assets > Wallet Name > Whitelist'
There, you can whitelabel all new tokenholder wallet addresses.
Changing a wallet address on Pulley does not automatically white label the new address on BitGo. You will need to add in all new addresses to your custodial wallet.
Setting up Webhooks
In Bitgo, you can setup webhooks that tell Pulley when transactions are completed or rejected. Setting these webhooks allows the Pulley transaction date to be synced 1:1 with your BitGo data.
In BitGo, navigate to: 'Assets -> Wallet Name -> Settings -> Add Webhook'
There, you will add two webhooks: (1) for Pulley to listen for approvals and (1) for Pulley to listen for transactions. Please contact Pulley Support for the API endpoints (URL) to enter into the Webhooks.
Running a Distribution
When running a distribution, you will be prompted to select a distribution method ('Connect Wallet').
Pressing Connect with BitGowill automatically load in the BitGo Access Token and Wallet Information you previously entered. You can then either confirm or update these details.
Once you review the information, you can submit the batch of transaction to BitGo, where it will wait for a quorum of approval from the wallet administrators. You can approve (or reject) distributions, as well as see the distribution details, under 'Transfers' in your BitGo account.
You can also see the status of all transactions within the distribution flow on Pulley. As transactions are approved (or rejected) in BitGo, Pulley will automatically update the information and transaction data.