Skip to main content

Onboarding an Individual for Crypto Brokerage

Create an Identity, Account and Profile to provide Buy, Hold and Sell Crypto Brokerage for Users

This guide walks through setting up a Fiat and Crypto Subledger crypto brokerage integration, creating an Individual Identity and a related Account and Profile to book orders using the Order API. First, we will create an Identity to represent the user's kyc information on the Paxos Platform. Then we will create an Account which sets up the structure of the brokerage account. Then we will create a Profile that represents the users fiat and crypto asset holdings. Then we will integrate with the Order API to set up a simple Buy, Hold and Sell integration. This guide should take around 30 minutes.

Prerequisites​

Authenticate in Sandbox​

Create an API Key on the Sandbox Paxos Dashboard with the following scopes to access the Identity, Account and Order APIs needed for this guide

  • identity:read_identity
  • identity:read_account
  • identity:write_identity
  • identity:write_account
  • funding:read_profile
  • funding:write_profile
  • exchange:read_order
  • exchange:write_order

Run below to get the access_token from OAuth

curl --location 'https://oauth.sandbox.paxos.com/oauth2/token' \
--form grant_type=client_credentials \
--form client_id=${paxos_client_id} \
--form client_secret=${paxos_secret} \
--form scope='identity:read_identity identity:read_account identity:write_identity identity:write_account funding:read_profile funding:write_profile exchange:read_order exchange:write_order'

Confirm the response includes requisite scopes and save the access_token to use in the request authorization header throughout this guide.

{
 "access_token": "{access_token}",
 "expires_in": 3599,
 "scope": "identity:read_identity identity:read_account identity:write_identity identity:write_account funding:read_profile funding:write_profile exchange:read_order exchange:write_order",
 "token_type": "bearer"
}
note

Include the Authorization header with the bearer token on all API requests -H "Authorization: Bearer $TOKEN".

Creating an Individual Identity and Account​

➊ Creating an Identity with Passthrough Verification​

To create an individual identity, Paxos requires both

Set verifier_type to PASSTHROUGH and then provide details about how and when IDV was conducted for this user by setting:

  • passthrough_verifier_type - the company of the IDV provider
  • passthrough_verified_at - when IDV was completed for the user
  • passthrough_verification_id - external id for the IDV record in the IDV provider's system
  • passthrough_verification_status - the current status of IDV, APPROVED if verified
  • passthrough_verification_fields - the set of fields used to verify the user during IDV

All above attributes are required when verifier_type is set to PASSTHROUGH.

curl --location "https://api.sandbox.paxos.com/v2/identity/identities" \
--request "POST" \
--header "Authorization: Bearer ${access_token}" \
--data '{
    "ref_id": "{your_end_user_ref_id}",
    "person_details": {
        "verifier_type": "PASSTHROUGH",
        "passthrough_verifier_type": "JUMIO",
        "passthrough_verified_at": "2021-06-16T09:28:14Z",
        "passthrough_verification_id": "775300ef-4edb-47b9-8ec4-f45fe3cbf41f",
        "passthrough_verification_status": "APPROVED",
        "passthrough_verification_fields": ["FULL_LEGAL_NAME", "DATE_OF_BIRTH"],

        "first_name": "Billy",
        "last_name": "Duncan",
        "date_of_birth": "1960-01-01",
        "address": {
            "address1": "123 Main St",
            "city": "New York",
            "province": "NY",
            "country": "USA",
            "zip_code": "10001"
        },
        "nationality": "USA",
        "cip_id": "073-05-1120",
        "cip_id_type": "SSN",
        "cip_id_country": "USA",
        "phone_number": "+1 555 678 1234",
        "email": "example@somemail.org"
    },
    "customer_due_diligence": {
        "estimated_yearly_income": "INCOME_50K_TO_100K",
        "expected_transfer_value": "TRANSFER_VALUE_25K_TO_50K",
        "source_of_wealth": "EMPLOYMENT_INCOME",
        "employment_status": "FULL_TIME",
        "employment_industry_sector": "ARTS_ENTERTAINMENT_RECREATION"
    }
}'
caution

The cip_id of an Identity is required to be unique. If a 409 duplicate cip_id error occurs, handle it by either:

  • Refusing to support crypto brokerage services for customers who have a duplicate cip_id
  • If they are confirmed to be the same Identity, create a new Account to represent each user account.

Check the response to find the identity_id of the newly created Identity and notice the status of the Identity is PENDING. Paxos will make an Onboarding Decision and asynchronously update the status to either DENIED or APPROVED.

{
    "id": "{identity_id}",
    "status": "PENDING",
    "created_at": "2021-06-16T09:28:14Z",
    "updated_at": "2021-06-16T09:28:14Z",
    "ref_id": "{your_end_user_ref_id}",
    "person_details": {
        // ...
    }
}
info

An Identity might stay in PENDING due to being deemed high risk by Paxos. This Identity will be required to undergo Enhanced Due Diligence. See how to automate document collection to allow HIGH risk customers to onboard to Paxos.

➋ Wait for the Identity to be Approved​

Using the above details should result in auto-approval of the Identity. You can immediately call the Get Identity endpoint and see the summary_status is APPROVED.

curl --location "https://api.sandbox.paxos.com/v2/identity/identities/${identity_id}" \
--request "GET" \
--header "Authorization: Bearer ${access_token}"
tip

➌ Creating an Account and Profile​

Now we are ready to make an Account and Profile for the Identity. An Account logically relates to a user's brokerage account, an Identity therefore can have one or many Accounts.

The create_profile flag must be set to true, this will ensure a Profile is created for the Account. This is how to create accounts and profiles for a Fiat and Crypto Subledger integration.

curl --location "https://api.sandbox.paxos.com/v2/identity/accounts" \
--request "POST" \
--header "Authorization: Bearer ${access_token}" \
--data '{
    "create_profile": true,
    "account": {
        "identity_id": "'"${identity_id}"'",
        "ref_id": "{your_account_ref}",
        "type": "BROKERAGE",
        "description": "Brokerage account for Billy Duncan"
    }
}'

Booking an Order​

We will use the Order API to create buy and sell orders. We recommend also taking a look at the FIX and WebSocket solutions and using the best combination of APIs for the specific use case.

➊ Fund the Account​

In a complete integration, follow the Fiat Transfers Funding Flow guide to learn how to fund user assets using a Fiat Deposit.

For this guide, we will use the sandbox-only Test Funds feature in Dashboard to fund the Identity with $10,000 USD. First, navigate to the Dashboard Landing Page and locate the Fund button

Fund button in Dashboard

Then select the Profile related to the Account created and fund for $10,000 USD

Funding the Account

➋ Creating a Order​

To book an order, specify the profile_id which is linked to the account_id created above (if one exists, else the omnibus profile_id).

curl --location "https://api.sandbox.paxos.com/v2/profiles/${profile_id}/orders" \
--request "POST" \
--header "Authorization: Bearer ${access_token}" \
--data '{
    "side": "BUY",
    "market": "ETHUSD",
    "type": "LIMIT",
    "price": "1814.8",
    "base_amount": "1",
    "identity_id": "'"${identity_id}"'",
    "identity_account_id": "'"${account_id}"'"
}'

You can check the status of the order by calling

curl --location "https://api.sandbox.paxos.com/v2/profiles/${profile_id}/orders/${order_id}" \
--request "GET" \
--header "Authorization: Bearer ${access_token}"

And that is it, congratulations on completing your first end-to-end crypto brokerage integration with Paxos!