Coinbase Prime - Integration Setup Guide

Last updated: September 26, 2024

PREREQUISITES: The following steps must be completed prior to integrating your Coinbase Prime account with Liquifi:

1. You must have an account set up with Coinbase Prime

2. The token you are planning to distribute via Liquifi must be supported by Coinbase Prime. Visit here to learn how to determine if your token is supported.

Step 1: Assign user roles, permissions, and consensus policies

  • During your Coinbase Prime onboarding process, you should have set up the appropriate user roles, permissions, and consensus policies for your Coinbase Prime account. 

  • If you haven’t already done so, please review the Coinbase Account Security documentation and set up user roles, permissions, and consensus policies on your Coinbase account before proceeding. 

Step 2: Set up Transfer approval policies

  • The Maximum Transfer Amount represents the maximum amount of user can withdraw from their Coinbase Portfolio at once.

  • As a security precaution, it is recommended to set a finite value for the Maximum Transfer Amount to prevent loss of funds. 

Set a Maximum Transfer Amount limit:

  1. In Coinbase, navigate to Settings > Security > Transfers

  2. On the Maximum Transfer Amount row, click Edit

  3. Select a value that is greater than the maximum Liquifi payout amount.  Reach out to the Liquifi team if you are unsure what the maximum payout amount is. 

    1. [Important]: Set the Max Withdrawal amount to an amount that is greater than the maximum amount of tokens you’d pay out in 1 payout on Liquifi. Otherwise, if you try to pay out an amount that is greater than the Max Withdrawal amount, the Liquifi payout will fail. 

    2. ex., if a company will vest an additional $1m amount of tokens each month, then they should set their Maximum Withdrawal amount to a value that is higher than $1m (ex. $2m).

Step 3: Enable Trusted Address Protection

Context

Turning on Trusted Address Protection will ensure that all Transfer actions will  limit withdrawals to addresses in your Address Book only. This safeguards against any mistakes where tokens are sent to unrecognized addresses. 

To enable Trusted Address Protection: 

  1. Go to the Settings tab

  2. Click on Transfers

  3. On the Trusted Address Protection row, click Edit

  4. Enable the toggle and click Confirm Changes (see screenshot below)

Step 4: Set up Trusted Destinations

Context

If you are transferring tokens from a Coinbase Portfolio to an external address outside the Coinbase ecosystem (ex. a Metamask address), then you must allowlist this wallet address explicitly as a Trusted Address prior to distributing tokens to it. 

How to allowlist Trusted Addresses

  1. Sign into Coinbase Prime

  2. On the left side of the screen, click Settings

  3. Click Address Book

  4. Click Add Trusted Address

  5. Select the asset that matches the token that you are distributing via Liquifi 

  6. Enter the trusted address name 

  7. Enter the trusted address

  8. Review Details and click Confirm New Trusted Address

  9. Verify identity via Yubikey.

Viewing Trusted Destinations on Liquifi 

To see if a Stakeholder’s address is listed as a Trusted Destination, navigate to the Stakeholders tab on Liquifi & view the Trusted Destinations column (see screenshot). If the Stakeholder’s row has a value of Trusted, then that Stakeholder’s wallet address is allowlisted as a Trusted Destination on Coinbase. If the Stakeholder has a value of Not trusted, then the Stakeholder’s address is not in the Coinbase Address Book. Any updates to the Coinbase Address Book will be reflected automatically in the Liquifi UI as well. 

Step X: Share URL for portfolio (to record portfolio ID)

  1. Navigate to the asset you're planning to build

Step 5: Create an API Key

Context

Coinbase Instructions

Coinbase API Key

Coinbase API Overview

You must generate a Coinbase API Key via the Coinbase Prime platform for Liquifi to use. The API key’s permissions will be scoped to only the required access types needed. The API key must undergo quorum approval before it can be activated for use. The API key will be valid until either the expiration date or if it has been revoked by the client. 

  • Note: This step assumes that the user has the permissions and user roles set up for their Coinbase account. If not, please refer to the previous Account Security steps first. 

How to create an API key

  1. Sign in to your Coinbase Prime account.

  2. Select your profile photo or the default image, which is a circle with your first initial, to open the sidebar. Access your settings by selecting the gear icon in the sidebar. 

  3. Once you’ve opened the Settings dashboard, select the APIs tab.

  4. Select Create API Key.

  5. In the pop-up window, enter the following details: 

    1. Name: Liquifi API Key

    2. Access Type: Read, Transfer

    3. Expiration Date: Some date 90-180 days in the future

      1. Note: Per Coinbase Security Best Practices, an API key should expire within 90-180 days. Prior to expiration, the API key should be regenerated and rotated. The new API key value should also be given to Liquifi via a security url (ex. 1Password). 

  6. Select Continue. The action requires consensus approvals before it’s processed.

  7. Verify your identity with Yubikey.

    1. Once you have consensus approvals, your API key will appear in Pending keys and you can proceed with the next step. 

  8. Under Pending keys, find your API key. Select Activate Key and then select Activate API Key, which will display the API Key’s Access Key, Passphrase, and Signing Key (see screenshot below)

    1. [IMPORTANT] Store the Access Key, Passphrase, and Signing Key in a secure location (ex. 1Password) and share these credentials with Liquifi via a secure url (ex. one-time use links via 1Password). 

  9. Verify your identity with Yubikey.

  10. Once the API key is created, share the API Key details with Liquifi via a secure one-time-use url (ex. one-time use links via 1Password). 

Step 6: Activate the API Key for use

Context

Coinbase Instructions

After an API key is created, it must be activated before it can be used. Activating an API key will require identity verification via a Yubikey & also consensus approval on the Coinbase account. 

How to activate an API key

  1. Under Pending keys, find your API key. Select Activate Key and then select Activate API Key, which will display the API Key’s Access Key, Passphrase, and Signing Key (see screenshot below)

    1. [IMPORTANT] Store the Access Key, Passphrase, and Signing Key in a secure location (ex. 1Password) and share these credentials with Liquifi via a secure url (ex. one-time use links via 1Password).

  2.  Verify your identity with Yubikey.

  3. Once the API key is created, share the API Key details with Liquifi via a secure one-time-use url (ex. one-time use links via 1Password). 

Step 7: Share API Key with Liquifi

Context

In order for Liquifi to propose transactions to a customer’s Coinbase Prime account, it must have the API Key’s details. The Liquifi app stores these API Key credentials in AWS Secret Manager. All access requests to AWS Secret Manager require explicit approval and are logged for security and auditability purposes. 

How to share API key credentials securely

  1. Share the API Key’s Access Key, Passphrase, and Signing key with the Liquifi team via a secure URL (ex. one-time use links via 1Password). 

    1. Note: if your team does not have a way to generate secure URLs, please request a URL from Liquifi to use. 

  2. Be sure to include the following information:

    1. What is the transfer limit (if any)?

    2. What is the API key expiration time?

    3. What are the approval quorum thresholds set for this portfolio?