> ## Documentation Index
> Fetch the complete documentation index at: https://paxos-0ac97319-jg-test-1.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboarding an Institution for Crypto Brokerage

> Create an Institution Identity, Account and Profile to provide Buy, Hold and Sell Crypto Brokerage for Institutions

This guide walks through setting up a [Fiat and Crypto Subledger](/guides/crypto-brokerage/ledger-type#fiat-and-crypto-subledger) crypto brokerage integration for institutions,
creating an Institution [Identity](/api-reference/endpoints/identity) and a related [Account](/api-reference/endpoints/accounts) and [Profile](/api-reference/endpoints/profiles) to book orders using the [Order API](/api-reference/endpoints/orders). First, we will
create an [Identity](/api-reference/endpoints/identity) to represent the institution's KYC information on the Paxos Platform. Then we will create an [Account](/api-reference/endpoints/accounts) which sets
up the structure of the brokerage account. Then we will create a [Profile](/api-reference/endpoints/profiles) that represents the institution's fiat and crypto asset holdings. Then we will integrate with the [Order](/api-reference/endpoints/orders) API to
set up a simple Buy, Hold and Sell integration. This guide should take around 30 minutes.

## Prerequisites

* Sign up to the [Paxos Dashboard](/guides/dashboard/account) in Sandbox
* Reach out to [Support](https://support.paxos.com) to provision access to the [Identity API](/api-reference/endpoints/identity)

## Authenticate in Sandbox

Create an [API Key](/guides/dashboard/admin/api) on the Sandbox [Paxos Dashboard](/guides/dashboard/account) with the following scopes to access the [Identity](/api-reference/endpoints/identity),
[Account](/api-reference/endpoints/accounts) and [Order](/api-reference/endpoints/orders) 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:

```shell
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.

```json
{
 "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"
}
```

<Tip>
  Include the Authorization header with the bearer token on all API requests `-H "Authorization: Bearer $TOKEN"`.
</Tip>

## Creating an Institution Identity and Account

Institution identities are used to represent all non-person entities. Details for institution identity type are recorded in institution\_details. An institution identity also has institution\_members associated with it. This defines persons or other entities that have some relationship to the institution.

For detailed information about institution types, subtypes, and required fields, please refer to the [Institution Required Details](/guides/identity/required-details#required-institution-details) documentation.

### ➊ Creating Person Identities for Institution Members

Before creating an institution identity, you need to create person identities that will be associated with the [institution as members](/guides/identity/institution-types#member-roles) (e.g.
beneficial owners, authorized users, management control persons, etc.).
You'll need to create at least one person identity, but typically you'll create multiple identities for different roles within the institution.

<Tip>
  The required fields for each [institution member role](/guides/identity/institution-types#member-roles) are different. Please reach out to [Support](https://support.paxos.com) for more information.
</Tip>

```shell
# Create a person identity
curl --location "https://api.sandbox.paxos.com/v2/identity/identities" \
--header "Authorization: Bearer {access_token}" \
--header "Content-Type: application/json" \
--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": "1980-01-01",
    "nationality": "USA",
    "address": {
      "address1": "123 Main St",
      "city": "New York",
      "province": "NY",
      "country": "USA",
      "zip_code": "10001"
    },
    "cip_id": "073-05-1127",
    "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"
  }
}'
```

Check the response to find the `identity_id` of the newly created person identity. You'll need this ID when creating the institution identity.

```json
{
  "id": "{person_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": {
    // ...
  }
}
```

### ➋ Creating an Institution Identity

To create an institution identity, you'll need to provide:

* The details of the institution according to the [Institution Required Details](/guides/identity/required-details#required-institution-details)
* Information about institution members and their roles

Here's an example of creating a institution (see API documentation for full request details):

```shell
# Example API call to create an institution identity
curl --location "https://api.sandbox.paxos.com/v2/identity/identities" \
--header "Authorization: Bearer {access_token}" \
--header "Content-Type: application/json" \
--data '{
  "institution_members": [
    {
      "identity_id": "{person_identity_id}",
      "roles": ["BENEFICIAL_OWNER", "AUTHORIZED_USER", "MANAGEMENT_CONTROL_PERSON"]
    }
  ],
  "institution_details": {
    "name": "Foogle",
    "business_address": {
      "country": "United States",
      "address1": "1 Example St",
      "city": "New York",
      "province": "NY",
      "zip_code": "10001"
    },
    "email": "johndoe@foogle.com",
    "institution_type": "CORPORATION",
    "institution_sub_type": "HEDGE_FUND",
    "cip_id": "12-3456789",
    "cip_id_type": "EIN",
    "cip_id_country": "USA",
    "govt_registration_date": "2021-04-14T00:00:00Z",
    "incorporation_address": {
      "country": "United States",
      "address1": "1 Example St",
      "city": "New York",
      "province": "NY",
      "zip_code": "10001"
    },
    "regulation_status": "US_REGULATED",
    "trading_type": "PUBLIC",
    "listed_exchange": "NASDAQ",
    "ticker_symbol": "FOOG",
    "regulator_name": "SEC",
    "regulator_jurisdiction": "USA",
    "regulator_register_number": "12-3456789",
    "business_description": "Foo"
  },
  "ref_id": "{your_inst_end_user_ref_id}"
}'
```

<Tip>
  The above example is a simplified version. For production use, you'll need to provide additional details based on your institution type. Refer to the [Institution Required Details](/guides/identity/required-details#required-institution-details) documentation for complete requirements.
</Tip>

<Warning>
  The `cip_id` of an [Identity](/api-reference/endpoints/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 institutions that have a duplicate `cip_id`
  * If they are confirmed to be the same [Identity](/api-reference/endpoints/identity), create a new [Account](/api-reference/endpoints/accounts) to represent each institution account.
</Warning>

Check the response to find the `identity_id` of the newly created [Identity](/api-reference/endpoints/identity) and notice the status of the [Identity](/api-reference/endpoints/identity) is `PENDING`.
Paxos will make an [Onboarding Decision](/guides/identity/statuses#onboarding-decision) and asynchronously update the status to either `DENIED` or `APPROVED`.

```json
{
    "id": "{institution_identity_id}",
    "status": "PENDING",
    "created_at": "2021-06-16T09:28:14Z",
    "updated_at": "2021-06-16T09:28:14Z",
    "ref_id": "{your_inst_end_user_ref_id}",
    "institution_details": {
        // ...
    }
}
```

<Info>
  An [Identity](/api-reference/endpoints/identity) might stay in `PENDING` due to being deemed high risk by Paxos. This [Identity](/api-reference/endpoints/identity) will be
  required to undergo [Enhanced Due Diligence](/guides/identity/edd). See [how to automate document collection](/guides/identity/edd) to
  allow `HIGH` risk customers to onboard to Paxos.
</Info>

### ➌ Wait for the Identity to be Approved

<Warning>
  You'll need to reach out to [Support](https://support.paxos.com) as by default the institution will be stuck in `PENDING` due to
  waiting for document verification, depending on your integration type document verification may not be required - but it
  is by default.
</Warning>

You can check the status of the institution identity by calling the [Get Identity](/api-reference/endpoints/identity/get-identity) endpoint:

```shell
# Check identity status
curl --location "https://api.sandbox.paxos.com/v2/identity/identities/{institution_identity_id}" \
--header "Authorization: Bearer {access_token}"
```

<Tip>
  * Use a [Webhook](/guides/webhooks) integration to asynchronously process [`identity.approved`](/api-reference/webhooks) and [`identity.denied`](/api-reference/webhooks)
    events to notify users when they have been onboarded to Paxos.
</Tip>

### ➍ Creating an Account and Profile

Now we are ready to make an [Account](/api-reference/endpoints/accounts) and [Profile](/api-reference/endpoints/profiles) for the institution [Identity](/api-reference/endpoints/identity). An [Account](/api-reference/endpoints/accounts) logically relates to an institution's brokerage account,
an [Identity](/api-reference/endpoints/identity) therefore can have one or many [Accounts](/api-reference/endpoints/accounts).

```shell
# Create account and profile
curl --location "https://api.sandbox.paxos.com/v2/identity/accounts" \
--header "Authorization: Bearer {access_token}" \
--header "Content-Type: application/json" \
--data '{
  "create_profile": true,
  "account": {
    "identity_id": "{institution_identity_id}",
    "name": "Institution Brokerage Account",
    "type": "CRYPTO_BROKERAGE"
  }
}'
```

When you create an account, a profile is automatically created and associated with it. You'll need the profile ID to book orders, so you should retrieve it after creating the account:

```shell
# Get the profile ID associated with the account
curl --location "https://api.sandbox.paxos.com/v2/profiles?account_id={account_id}" \
--header "Authorization: Bearer {access_token}"
```

## Booking an Order

We will use the [Order](/api-reference/endpoints/orders) API to create buy and sell orders. We recommend also
taking a look at the [FIX](/guides/crypto-brokerage/fix) and [WebSocket](/api-reference/websockets/overview) 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](/guides/developer/fiat-transfers/quickstart) guide to learn how to fund institution assets using
a [Fiat Deposit](/api-reference/endpoints/fiat-transfers).

For this guide, we will use the sandbox-only Test Funds feature in [Dashboard](https://dashboard.sandbox.paxos.com/) to fund the [Identity](/api-reference/endpoints/identity) with \$10,000 USD. First,
navigate to the [Dashboard Landing Page](https://dashboard.sandbox.paxos.com/) and locate the `Fund` button.
![Fund button in Dashboard](https://mintlify.s3.us-west-1.amazonaws.com/paxos-0ac97319-jg-test-1/images/identity-guide-fund-account-button.png)

Then select the [Profile](/api-reference/endpoints/profiles) related to the [Account](/api-reference/endpoints/accounts) created and fund for \$10,000 USD
![Funding the Account](https://mintlify.s3.us-west-1.amazonaws.com/paxos-0ac97319-jg-test-1/images/identity-guide-fund-account.png)

### ➋ Creating an 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`)*.

### Buy

```shell
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": "{institution_identity_id}",
    "identity_account_id": "{account_id}"
}'
```

### Sell

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

You can check the status of the order by calling

```shell
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 for institutions with Paxos!