Skip to main content

User Onboarding

Before a customer can trade or move money, they need an enterprise, a verified identity, and a Go Account.

Step 1 — Create Enterprise​

Register the enterprise for your customer. Each customer gets their own enterprise.

Keep both IDs from enterprise creation

The enterpriseId identifies the customer record, while the returned userId is the access user attached to that enterprise. You will typically use enterpriseId as the main reference, but you should keep both because later identity requests also use the enterprise userId.

The API manages the target organization

For enterprise creation, the {organizationId} path segment resolves to the organization configured for your account. Treat it as a routing placeholder rather than a customer-specific value you control.

See Core Concepts for more on what an enterprise represents.

Step 2 — Submit Identity (KYC)​

Submit the customer's personal information for identity verification.

  • POST /api/evs/v1/identity
  • Requires the enterpriseId and userId from Step 1
  • Always use transactionType: "institutionalIndividual" for standard onboarding
  • For corporations, additional KYB documents may be required

Example identity payload (individual):

{
  "nameFirst": "Jane",
  "nameLast": "Doe",
  "phoneNumber": "+15555551234",
  "birthdate": "1990-01-15",
  "occupation": "Agriculture",
  "countryOfCitizenship": "US",
  "countryOfResidence": "US",
  "govIdCountryOfIssuance": "US",
  "politicallyExposedPerson": false,
  "addressStreet1": "123 Main St",
  "addressCity": "San Francisco",
  "addressSubdivision": "CA",
  "addressPostalCode": "94102",
  "country": "US",
  "identificationNumber": "123-45-6789",
  "transactionType": "institutionalIndividual",
  "enterpriseId": "<enterpriseId>",
  "userId": "<userId>"
}
organizationId is managed by the API

The generated API schema may still show organizationId, but the API injects it from your account configuration for this flow. In practice, provide the customer-specific fields plus enterpriseId and userId.

caution

Avoid using paygo, unverified user, or starterSignup transaction types. Always use institutionalIndividual.

Step 3 — Upload Documents (if required)​

Only needed for non-US citizens or when there's a data mismatch during verification.

Only upload documents when the identity requests them

This step is conditional. If you upload documents before the identity reaches awaiting document upload, you may be sending files for a customer who does not need them.

Sandbox flows can skip the document-upload state

In current API behavior, an identity can move directly to awaiting signature or awaiting review without ever stopping at awaiting document upload. Treat the current identity status as the source of truth before uploading documents.

Verification usually takes seconds, but can take up to 24 hours if manual review is needed.

Step 4 — Sign Terms​

The enterprise must sign the legal agreements before an account can be opened.

Sandbox contract version

The current sandbox contract version is 3.2.26. Make sure to use this value for contractVersion when testing in sandbox.

Example signatures payload:

[
  {
    "contractSignerNameFull": "Jane Doe",
    "contractSignedDate": "2025-01-15T00:00:00.000Z",
    "contractSignedIPAddress": "127.0.0.1",
    "contractType": "csa",
    "contractVersion": "3.2.26",
    "userAgreesToTerms": true
  }
]

Step 5 — Poll Identity Status​

Wait for the identity to be approved before creating the Go Account.

Signature submitted does not mean onboarding is complete

After Step 4, the identity can still remain in review. Treat approved as the only status that unlocks Go Account creation.

Step 6 — Create Go Account​

Once KYC is approved, create the Go Account wallet. This is the multi-asset wallet that handles both fiat and crypto.

A trading Go Account already provisions the needed asset wallets

For the standard flow, you do not need to create separate BTC and USD wallets after approval. Creating the Go Account with type: "trading" handles that for you.

A new Go Account may not be immediately ready everywhere

Right after creation, trading balances/products and address-generation calls can lag briefly while the account finishes initializing. If a newly created Go Account is not ready yet, retry instead of treating the first non-ready response as a permanent failure.

Example payload:

{
  "type": "trading",
  "enterprise": "<enterpriseId>",
  "label": "Customer Go Account",
  "passphrase": "<passphrase>",
  "passcodeEncryptionCode": "<passcodeEncryptionCode>"
}

Putting It Together​

Next Steps​

  • Funding — Link a bank account, deposit USD or receive Bitcoin
  • Conversions — Buy or sell Bitcoin