Documentation

Account Opening

Account creation, editing, and document uploading

Suggest Edits

Overview

Clients can facilitate cryptocurrency access for their customers by enabling them to open accounts with Bakkt. Bakkt must collect customer information to validate and support these accounts, using API endpoints to submit and retrieve information, upload documents, make account updates, and more.

This document offers a granular walkthrough and explanation on account creation and management. To open a customer account, clients are expected to populate the necessary objects and fields, which are then submitted as a payload to an API endpoint for account creation. Bakkt verifies this information asynchronously and delivers status updates exclusively through the client’s provided webhook URL.

After an account is opened, it can be funded for cryptocurrency transactions.

Core Concepts and Functionality

KYC Compliance

Bakkt adheres to federal regulations by implementing Know Your Customer (KYC) protocols for every customer. Bakkt’s KYC process involves collecting information for Customer Identification (CID), Customer Due Diligence (CDD), and the Customer Identification Program (CIP), partnering with Socure to verify customer details and perform sanction screenings. By collecting and verifying customer personal and financial information, Bakkt upholds legal compliance and assists its compliance and operations teams in tracking trading patterns, effectively safeguarding against illicit activities.

Bakkt acknowledges that clients have diverse KYC processes and will request a meeting between compliance teams to mutually understand each other’s KYC protocols. Bakkt requests all previously collected KYC information, including uploaded documents. The previously collected KYC information facilitates the verification of the customer’s name, birth date, address, and tax ID.

In compliance with regulatory requirements, Bakkt conducts its own KYC checks through its KYC vendor. Customers that are flagged during KYC/OFAC screening may need to undergo the document verification process, which involves submitting an identifying document, such as a passport or license, and completing a facial scan, although this does not guarantee approval. This process is activated only by specific compliance criteria and is not required for all users, and includes the possibility of direct account rejection based on Bakkt's configured rules. Bakkt facilitates the document verification process through a mobile web app, providing clients with a direct link from our vendor via a webhook event. The URL for the document verification process has a built-in time-to-live; should it expire, clients will need to retrieve a new URL from Bakkt via the Retrieve KYC Document Verification Details API, which can be found in the Retrieving Information section below. Bakkt only allows 3 expirations, each URL is active for 72 hours, after that you will see the error message here for max attempts reached. See the Client Integration Testing Workflow for more details and examples.

Clients have the option to communicate this URL to customers within their own application. However, if the link expires, the client must present a refreshed URL to the customer. To avoid disruptions, clients can streamline this communication by opting for either SMS delivery of the link directly to the customer’s phone number by the KYC provider, or a direct email from Bakkt. This approach eliminates the need for clients to manage the user experience, as either the KYC vendor or Bakkt will handle it according to client preferences, adjustable at any time. Regardless of the method, clients will receive a webhook event when document verification begins. To learn more about the KYC process, see the FAQ section.

Required Fields

To support transitioning clients, some higher-level objects will not be labeled as ‘required’, though their sub-fields are required and must be completed. This is to accommodate the migration of customers with incomplete data. Migrating accounts will be granted a grace period for data collection. After this period, clients are expected to backfill this information. These fields are required immediately for new accounts being created.

For example, the Investment Profile object, although not marked required, contains required sub-object fields. Clients will be able to create accounts for migrating customers and update these details after creation.

Deprecated and Future Fields

Deprecated fields exist for backward compatibility for legacy clients but are no longer in use. New clients do not have to populate these fields. As Bakkt evolves, future fields are in place to prepare for upcoming changes. For example, in the 200 response section at the bottom of the Create Account API document, the cipClearanceState item is deprecated and the mode item is reserved for future use.

Workflow

The following concepts and workflow will guide you through the various objects and data required to successfully open an account.

Follow along on Bakkt’s Create Account API document.

Account Identification

  • Account Type
    Bakkt supports individual and entity accounts, such as trusts or custodial accounts. Clients are prompted to select the account type so that Bakkt can apply appropriate features and compliance protocols to that account. For individual accounts, clients must select the PRIMARY_OWNER role in the Owners object.

  • Entity
    To learn more about enrolling entities, please visit our entity accounts section of the documentation.

  • Client Account ID
    This is the unique identifier for the customer’s account used within the client’s system. This is provided by the client to Bakkt. Although Bakkt has another account number for internal system use, Bakkt’s system will always use the Client Account ID for any API calls and reports.

Collect Financial Information

  • Investment Profile
    This object evaluates a customer’s trading suitability by collecting financial details to monitor trading patterns and detect illicit activities. This section is mandatory for all accounts; however, the API is flexible for customer migration so it will not explicitly state that it is required. This object further branches into two sub-objects:

    • Account Goals
      This sub-object is used to characterize the customer’s account. Gathering information about a customer’s investment intentions and comparing it with their actual trading activities helps Bakkt monitor for unusual activities, reduce risk, and contribute to Anti-Money Laundering (AML) surveillance. The Investment Objective field is the only required field, but additional fields help provide insight into customer profiles. New accounts are required to have this information, see the note above about required fields for migrating accounts.

    • Customer Profile
      This sub-object collects details about the customer’s financial background to ensure investments are matched to their fiscal standing and the sources of their investment funds are clear and legitimate. The annual income range is the only required field in this object.

Collect Personal Information

  • Owner
    This object gathers essential information needed to support each account owner, including KYC related data and the account role. For INDIVIDUAL accounts, clients must select the PRIMARY_OWNER role for their successful account creation, selecting anything else will result in an unsuccessful account creation. An owner ID will be assigned to support identification within our systems. Whenever a client is creating accounts with more than one owner, they must ensure that each owner is assigned a clientOwnerId. This ID allows Bakkt and the client to uniquely track each owner and their acknowledgement of our terms of service. Several sub-objects will collect further details:

    • Identity
      This object captures KYC-related information to fulfill regulatory requirements and facilitate customer verification. This section collects essential identifying details such as full name, date of birth, and tax ID type and number, all of which are required for KYC. The email address is also required to have a line of communication with the customer. For clients with U.S. customers, Bakkt requires taxId and taxIdType for each customer onboarding the platform. In the taxIdType field, clients will need to specify between SSN,ITIN, and EIN. The taxIdCountry will default to USA and will not need to be specified on the request. For clients with international customers that have unique national identifiers, Bakkt advises that you provide the ID number in the taxId field and select NATIONALID in the taxIdType field of the account creation API. In the taxIdCountry field, please specify the issuing country for your ID in a 3 letter ISO code format (i.e. GBR for the United Kingdom). Some countries may not support a National ID. In these cases, the client is not expected to provide one and can leave the taxId, taxIdType, and taxIdCountry fields out of the account creation request. However, these will always be required for U.S. customers.

      Note: The citizenship field is in the process of being deprecated.

      While additional fields in this object are not required, there are nested sub-objects that are required for all new accounts being created, as explained in the Required Fields section. Let’s explore these objects in more detail:

      • Personal Address
        This sub-object collects a customer’s residential information which helps form a regional risk profile and determines trading permissions under local regulations.

      • Employment
        This sub-object captures employment and employer information, which is crucial for verifying the customer’s financial profile against their investment activities. This object includes a nested sub-object for the employer’s address, which is required for all new accounts.

      • Phone Number
        This is a ‘required’ field, despite not being labeled as such in the API. Our KYC process uses phone numbers during screening to ensure more accurate results for customers onboarding to the platform.

      • The Verification Results object is in the process of being deprecated.

      • The Disclosures object is in the process of being deprecated.

  • Mailing Address
    This sub-object collects a customer’s mailing address to establish an alternative contact method with customers who may be unresponsive by phone, email, or have a different mailing address from their residential one.

  • Agreements
    This sub-object records the customer’s electronic signature, signifying their consent to the crypto user agreement terms and conditions. Clients can display the user agreements in the user interface, where customers can consent by clicking the checkbox. Required fields include the agreement document’s name and version, while additional fields like eSigned Date and Text for the body of the agreement are optional. Bakkt’s legal team reviews these agreement details to activate account privileges, such as trading and transfers per the agreed terms.

Create an Account using our API

To create a new customer account using the Create Account API, compile all requisite data and submit it through the POST API endpoint provided below:

  • /apex-crypto/api/v2/accounts

Following submission, clients will immediately receive a confirmation payload. Bakkt will review submissions in the background asynchronously. Even with a successful 200 response, clients should check their webhook URL for the account’s status and any required actions. Receiving a 422 response means the call failed.

Uploading Documents

Bakkt requires document uploads for clients that have previously collected documents, for non-US accounts, or as needed per our KYC process. Clients can upload multiple documents per account and re-upload them to update expired documents, while old documents are retained for regulatory audits. Any account where the KYC was manually approved using a document should be highlighted in the payload’s description section, and that document should be uploaded as well. To get started and create a detailed code example, see the Upload Documents and Metadata API documentation.

Before uploading documents ensure the document metadata, such as document type, expiration date, account number, description (if needed), and MIME type, is correctly formatted as a JSON string for upload.

Selecting the correct document type is critical to efficiently support the account opening process and important for KYC auditability. Bakkt allows clients to upload the following document types:

  • Driver’s license – DRIVERS_LICENSE
  • ID Card – IDENTIFICATION CARD
  • Passport – PASSPORT
  • Social Security Card – SOCIAL_SECURITY_CARD
  • Trust Certification – TRUST_CERTIFICATION
  • Entity Due Diligence – ENTITY_DUE_DILIGENCE
  • Visa – VISA
  • W8 – W_8BEN_FORM

When everything is collected and correctly formatted, clients can upload documents via a POST request to the Document Uploading API endpoint:

  • /apex-crypto/api/v2/documents

Upon receipt of the document upload, Bakkt immediately carries out metadata validations to ensure proper format and confirms a successful completion with a 200 response or failure with a 404 response.

Updating Customer Accounts

Customer accounts should be current, with programmatically updatable fields modified via the Create Account API endpoint. Fields involving KYC are restricted and will require requesting a manual change through Bakkt’s Operations/Compliance team. When using the Create Account API to update accounts, ensure the complete account dataset is provided with the updated information changed. Additionally, any altercations to user agreements must be mutually acknowledged before executing an account update to reflect the revised agreement.

Bakkt restricts these fields from automated updates:

  • Birth Date, Country Citizenship, Tax ID, Account Type, Enrollments, ID, and Client Account ID

Bakkt allows automatic updates for these demographic data fields using the create account POST API endpoint:

  • Update phone numbers, addresses, and names: /apex-crypto/api/v2/accounts/

After submission, clients will receive a confirmation payload instantly while updated information will be reviewed asynchronously.

Retrieving Information

To retrieve customer information, clients can use the following API calls, substituting {clientDocumentId} or {clientAccountId} with the associated unique identifier:

  • Retrieve Account Status by Account ID API – To access information on a customer account’s trading status, use the referenced API endpoint.
    • If the canTradeCrypto field is false in the response, trades/transfers are disabled. Even if the response is true, clients must monitor for webhook events, as they provides details on the complete account status and potential restrictions not visible in this API. This API will be expanded in the future, but for now, webhook monitoring remains essential. Client's should not be using CIPClearanceState to make a determination on the account's KYC standing.
  • Download Document API – To download a document, use the referenced API endpoint.
  • Retrieve Metadata for Specific Document API – To retrieve document metadata, including its creation date-time and the Bakkt internal ID, use the referenced API endpoint.
  • Retrieve Account Payload by Account ID API – To obtain complete account data and creation status, use the referenced API endpoint.
  • Retrieve KYC Document Verification Details– Clients must provide the partnerId and partnerPartyRef (account ID) for the account to retrieve document verification for the party details using the following endpoint:
    GET /partner/v1/partner/{partnerId}/party/{partnerPartyRef}/kyc/documentVerificationDetails

Listening for Account Status Updates Via Webhook Events

For account status updates and notifications including creation, suspension, and documentation requests, see the Webhooks section.

Updated 2 months ago