USAGE GUIDELINES FOR LLMs
=======================
1. This documentation is compiled specifically for LLM assistance with Paxos product development
2. Each section maintains its original file path for reference
3. Code examples and API references are preserved for accurate implementation
4. Use the table of contents to navigate to relevant sections
5. Tags and descriptions help identify relevant content for your use case
6. When writing code, always refer to the latest API documentation for current endpoints and parameters
PAXOS DOCUMENTATION FOR LLM ASSISTANCE
Generated: 2025-05-02T13:59:06.061954
Version: 1.0
TABLE OF CONTENTS
=================
- DEVELOPER
- Mint
- Create Developer Account
- Configure API Credentials
- Reports
- Redeem
- Rate Limits
- Convert
- Request Signing
- Sandbox
- Authenticate
- Make First API Request
- Fiat Transfers
- Statuses
- Fiat Transfers FAQ
- Fiat Transfers Quickstart
- API Breaking Change Policy
- API
- Migrate from v1 to v2 API
- WebSocket API Reference
- STABLECOIN
- Integrate with PYUSD on Ethereum
- Stablecoins Overview
- BUSD
- USDP Overview
- USDP on Test Networks
- USDP on Main Networks
- USDL Overview
- USDL on Test Networks
- USDL on Main Networks
- Documentation Moved
- PYUSD Overview
- PYUSD on Test Networks
- PYUSD on Main Networks
- USDG Overview
- USDG on Test Networks
- USDG on Main Networks
- CRYPTO-BROKERAGE
- Orders & Quotes FAQ
- Orders, Precision and Rounding
- Crypto Brokerage
- Connect to the WebSocket Market Data Feed
- Commissions and Rebates FAQ
- Choosing a Ledgering Strategy
- Held Rate Quotes (HRQ)
- HRQ Quickstart
- FIX
- FIX Best Practices
- FIX Certification
- FIX Onboarding
- PAYMENTS
- Stablecoin Payments
- Connect to the WebSocket Stablecoin Price Feed
- Payments FAQ
- Stablecoin Pay-ins Quickstart
- Statuses
- SETTLEMENTS
- Settlements
- Notifications
- FAQ
- Quickstart
- Statuses
- IDENTITY
- Periodic KYC Refresh
- Enhanced Due Diligence
- Identity
- Statuses
- Onboarding an Individual for Crypto Brokerage
- Required Details
================================================================================
SECTION: DEVELOPER
================================================================================
## Mint
Description: Deposit USD. Convert or convert-and-transfer in one API call.
Tags: Stablecoin Operations
Path: developer/mint.mdx
[stablecoins]: blockchains.mdx#stablecoins
[CreateFiatDepositInstructions]: /api/v2#tag/Fiat-Transfers/operation/CreateFiatDepositInstructions
[fiat-transfers]: /api/v2#tag/Fiat-Transfers
[conversion]: /api/v2#tag/Stablecoin-Conversion/operation/CreateStablecoinConversion
[withdrawal]: /api/v2#tag/Crypto-Withdrawals/operation/CreateCryptoWithdrawal
[token]: developer/authenticate.mdx
[create-sandbox-deposit]: /api/v2#tag/Sandbox-Deposits/operation/CreateSandboxDeposit
[First API Request]: developer/request.mdx
[convert stablecoin]: developer/convert.mdx
[List Profile Balances]: /api/v2#tag/Profiles/operation/ListProfileBalances
[`SETTLED`]: developer/convert.mdx#stablecoin-conversion-statuses
[list-transfers]: /api/v2#tag/Transfers/operation/ListTransfers
Minting a [Paxos-issued stablecoin][stablecoins] starts by depositing USD on the Paxos platform using the [Fiat Transfers APIs][fiat-transfers] (**A** in the diagram).
Depending on the use case, you can either convert USD to a stablecoin and keep the asset on the Paxos platform using [Create Stablecoin Conversion][conversion] (option **B**) or use [Create Crypto Withdrawal][withdrawal] to convert and transfer with the same API request (**C**).
> If you've already authenticated and have a USD balances in a Profile, skip ahead to the [convert](#mint-hold) or [convert and transfer](#mint-transfer) step.
## ➊ Authenticate
Include the following scopes when [authenticating][token]:
```shell
conversion:read_conversion_stablecoin conversion:write_conversion_stablecoin funding:read_profile transfer:write_crypto_withdrawal
```
> If you don't see all the scopes when [creating or editing API credentials](/developer/credentials), contact [Support](https://support.paxos.com).
## ➋ Deposit USD
Use [Create Sandbox Deposit][create-sandbox-deposit] to add USD to the Profile (`profile_id`) you want the minting process to be associated with.
See the [First API Request] guide for help retrieving Profile IDs.
You can also use the [Fiat Transfers funding flow][fiat-transfers] if you've already set up a Fiat Account.
```shell
curl --request POST \
// highlight-next-line
--location 'https://api.sandbox.paxos.com/v2/sandbox/profiles/0d3172c5-8840-4bae-bdd4-30688f0268fc/deposit' \
--header 'Authorization: Bearer {access_token}' \
--data '{
"asset": "USD",
"amount": "1000"
}'
```
## ➌ Convert USD to Stablecoin {#mint-hold}
See the [convert stablecoin] guide for details on using [Create Stablecoin Conversion][conversion] to mint a [Paxos-issued stablecoin][stablecoins].
Once the conversion is [`SETTLED`], use [List Profile Balances] to check updated balances.
To check balances of the assets you are interested in, include the `assets` query parameter in the request.
```shell
// highlight-next-line
curl --location 'https://api.sandbox.paxos.com/v2/profiles/0d3172c5-8840-4bae-bdd4-30688f0268fc/balances?assets=USD&assets=PYUSD&assets=USDG' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access_token}'
```
The response includes the updated USD and Paxos-issued stablecoin balances.
```json
{
"items": [
{
"asset": "USD",
"available": "600",
"trading": "0"
},
{
"asset": "PYUSD",
"available": "100",
"trading": "0"
},
{
"asset": "USDG",
"available": "100",
"trading": "0"
}
]
}
```
## ➍ Convert and Transfer {#mint-transfer}
Use [Create Crypto Withdrawal][withdrawal] to transfer the Paxos-issued stablecoin to an address off the Paxos platform with a single request.
To automatically convert fiat (USD) to stablecoin and transfer to an external address with a single request, set the `asset` to the stablecoin you want to mint, the `balance_asset` to `USD`, and the `crypto_network` to the desired network.
```shell
curl --location 'https://api.sandbox.paxos.com/v2/transfer/crypto-withdrawals' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{
"profile_id": "0d3172c5-8840-4bae-bdd4-30688f0268fc",
"asset": "USDG",
"destination_address": "0x9acb61E5fcE9B5BdA7B44635d86be19d2790D9a9",
"crypto_network": "ETHEREUM",
"ref_id": "cw_usdg_eth_293a8f7c-bcb6-483f-919b-8661ae65f0e6",
"balance_asset": "USD",
"amount": "100"
}'
```
```shell
curl --location 'https://api.sandbox.paxos.com/v2/transfer/crypto-withdrawals' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{
"profile_id": "0d3172c5-8840-4bae-bdd4-30688f0268fc",
"asset": "PYUSD",
"destination_address": "BtXdwoYSWPprQT88ZCLuQcXuTz4dFHB1AJFYqr5uXoAd",
"crypto_network": "SOLANA",
"ref_id": "cw_pyusd_293a8f7c-bcb6-483f-919b-8661ae65f0e6",
"balance_asset": "USD",
"amount": "100"
}'
```
The request confirmation response has a `status` of `PENDING`, since the on-chain transaction has not yet been confirmed.
```json
{
"id": "7c223577-832b-4235-a77e-ebf36dfe9860",
"customer_id": "8cbc1177-d982-4750-a435-3c7f36245452",
"profile_id": "0d3172c5-8840-4bae-bdd4-30688f0268fc",
"ref_id": "cw_usdg_eth_293a8f7c-bcb6-483f-919b-8661ae65f0e6",
"amount": "100",
"total": "126.96",
"fee": "26.96",
"asset": "USDG",
"balance_asset": "USD",
"direction": "DEBIT",
"type": "CRYPTO_WITHDRAWAL",
// highlight-next-line
"status": "PENDING",
...
"destination_address": "0x9acb61E5fcE9B5BdA7B44635d86be19d2790D9a9",
"crypto_network": "ETHEREUM",
"auto_conversion": {}
}
```
```json
{
"id": "e655c587-e057-4cf2-88d9-7e19ae13f2ee",
"customer_id": "8cbc1177-d982-4750-a435-3c7f36245452",
"profile_id": "0d3172c5-8840-4bae-bdd4-30688f0268fc",
"ref_id": "cw_pyusd_sol_293a8f7c-bcb6-483f-919b-8661ae65f0e6",
"amount": "100",
"total": "100",
"fee": "0",
"asset": "PYUSD",
"balance_asset": "USD",
"direction": "DEBIT",
"type": "CRYPTO_WITHDRAWAL",
// highlight-next-line
"status": "PENDING",
...
"destination_address": "BtXdwoYSWPprQT88ZCLuQcXuTz4dFHB1AJFYqr5uXoAd",
"crypto_network": "SOLANA",
"auto_conversion": {}
}
```
To check the transaction status on the Paxos platform, use [List Transfers][list-transfers].
You can create a recurring request that look for completed transactions in the Profile.
For example, filter on `type=CRYPTO_WITHDRAWAL` and `status=COMPLETED` parameters to find all the completed transactions.
```shell
curl --location 'https://api.sandbox.paxos.com/v2/transfer/transfers?type=CRYPTO_WITHDRAWAL&status=COMPLETED' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access_token}'
```
By default, the response includes transactions from newest to oldest.
```json
{
"items": [
{
"id": "7c223577-832b-4235-a77e-ebf36dfe9860",
"customer_id": "8cbc1177-d982-4750-a435-3c7f36245452",
"profile_id": "0d3172c5-8840-4bae-bdd4-30688f0268fc",
"ref_id": "cw_usdg_eth_293a8f7c-bcb6-483f-919b-8661ae65f0e6",
"amount": "100",
"total": "126.96",
"fee": "26.96",
"asset": "USDG",
"balance_asset": "USD",
"direction": "DEBIT",
"type": "CRYPTO_WITHDRAWAL",
// highlight-next-line
"status": "COMPLETED",
...
"destination_address": "0x9acb61E5fcE9B5BdA7B44635d86be19d2790D9a9",
"crypto_network": "ETHEREUM",
"crypto_tx_hash": "0x2a0bac30de037b62502540c18ac22b6d75312cd1508c1df3eb6e38f8b7503f1a",
"auto_conversion": {}
},{
"id": "e655c587-e057-4cf2-88d9-7e19ae13f2ee",
"customer_id": "8cbc1177-d982-4750-a435-3c7f36245452",
"profile_id": "0d3172c5-8840-4bae-bdd4-30688f0268fc",
"ref_id": "cw_pyusd_293a8f7c-bcb6-483f-919b-8661ae65f0e6",
"amount": "100",
"total": "100",
"fee": "0",
"asset": "PYUSD",
"balance_asset": "USD",
"direction": "DEBIT",
"type": "CRYPTO_WITHDRAWAL",
// highlight-next-line
"status": "COMPLETED",
...
"destination_address": "BtXdwoYSWPprQT88ZCLuQcXuTz4dFHB1AJFYqr5uXoAd",
"crypto_network": "SOLANA",
"crypto_tx_hash": "3ShgmRdcuj2usV3tmLvb3BUrEvhAXNWbUseYgRt24Muyv1tiPkohn8ZQAAdS5KeYNLKR6PhmwUta6CW2ZCAuxHt5",
"crypto_tx_index": "0",
"auto_conversion": {}
},
],
"next_page_cursor": "CAESCwiP-OazBhDgzZYyGLSOkw0"
}
```
----------------------------------------
## Create Developer Account
Description: Sign Up for access to the Sandbox environment.
Tags: Quickstart
Path: developer/account.mdx
[Support]: https://support.paxos.com
[create API credentials]: developer/credentials.mdx
[passkey]: https://www.passkeys.com/what-are-passkeys
[compatible-devices]: https://www.passkeys.io/compatible-devices
[submit-request]: https://support.paxos.com/hc/en-us/requests/new
[em]: dashboard/roles.mdx#entity-manager
[Developer]: dashboard/roles.mdx#developer
[api]: https://dashboard.sandbox.paxos.com/admin/api
To create an account you will need an email address, the business name and country of incorporation, as well as a way to create a [passkey] using a [compatible device][compatible-devices].
> Sandbox developer accounts are usually approved in less than one business day and take under an hour to create and onboard.
## ➊ Sign Up in Sandbox
Before you begin, ensure you are able to create and store a [passkey] on your device.
All modern [operating systems and browsers][compatible-devices] support passkeys.
1. Go to https://dashboard.sandbox.paxos.com, select **Sign Up** and provide a name and email address to create an _Institutional (Business) account_. Individual account holders are not eligible for API access via the Dashboard.
1. Retrieve the verification code from the welcome email from Paxos and enter the code in the browser. If you don't get an email within a few minutes, check email filters and Spam/Junk folders for an email from `@paxos.com`. Contact [Support] if the email never arrives.
1. Create a passkey.
1. Provide basic business information. The **Country of Incorporation** and **What do you plan to use your account for?** fields determine which assets you will have access to.
## ➋ Onboard Developer Account
You have a choice:
1. **skip onboarding** which takes you directly to an approved account, or
1. experience the entire onboarding process, which you'd have to undergo in production
### Skip Onboarding
If you choose to **skip onboarding** then click the "Bypass Onboarding" button which appears on the overall progress page next to the "Get Started" button.
Then proceed to the ➍ **Enable Developer Access** instructions on this page.
### Experience the Onboarding Process
Otherwise, click the "Get Started" button and complete the first six onboarding steps.
:::note
Use stubbed (fake) text when entering data.
The information provided will not be used when creating the production account.
:::
1. **Business Details**. Selecting **Corporation** as the institution type provides the quickest experience. The country field is pre-populated with the information you provided when creating the account.
1. **Funding Details**. Select **No** for the trust structure and nominee shareholder options.
1. Some account types will require you to fill out the **Suitability Assessment**. If you are not presented with this option, go to the next step. If you see the assessment: Select **Yes** and **Advanced** for the first two options.
1. **Business Members**. Open the edit dialog for the name you gave during account creation and provide the required fields. You can use fake (dummy) text.
- **Beneficial Owner Designation**. Ensure **Yes** is selected. Give information. The **% ot Ownership** should be `100`.
- For **Authorized User Designation**, **Persons with Management Control Designation** and **Director Designation**, select **Yes**.
1. Accept the **Terms & Conditions** and **Pricing & Fees** then complete **Review & Verify**.
:::note
Stop the onboarding process. Do not upload documents and go through ID verification.
:::
## ➌ Contact Support
[Support] must activate your Developer account before you can use it.
To ensure a smooth process, include your email address and business (organization) name when [submitting a request][submit-request].
You will receive an email from support confirming your Developer Sandbox account is good to go.
> Occasionally, [Support](https://support.paxos.com/hc/en-us) may reach out to you via email requesting additional information or if there is an issue creating the account.
## ➍ Enable Developer Access
Once the account is activated, you are assigned the [Entity Manager][em] role by default.
However, this role does not have write access to [Admin > API][api], where credentials are configured.
You will need to add the [Developer] role to your user.
1. Go to [**Admin > Team Management > Users**](https://dashboard.sandbox.paxos.com/admin/team-management/users).
1. Under the **Actions** column, open the **Edit Status** dropdown and select **Edit Roles**.
1. Click in the **Edit Roles** form and select **Developer**.
1. Log out and sign in to start a new session.
> Once your user has the **Developer** role, you can [create API credentials].
----------------------------------------
## Configure API Credentials
Description: Create and updated an OAuth2 client.
Tags: Quickstart
Path: developer/credentials.mdx
[convert]: developer/convert.mdx
[authenticate in Sandbox]: developer/authenticate.mdx
[mint]: developer/mint.mdx
[redeem]: developer/redeem.mdx
1. Go to **Admin > API Management** to add new credentials.
1. Create a **Label** for your API credentials and select the **Scopes** for your **Client ID**. For example, the following scopes (space delimited) should be adequate to [mint], [redeem] and [convert] Paxos-issued stablecoins:
1. Save the credentials.
1. Copy the **Client ID** and **Client Secret** and store them in a safe place. The secret will not be displayed in the UI again and will have to be reset if forgotten.
Once you have the **Client ID** and **Client Secret**, you can [authenticate in Sandbox].
----------------------------------------
## Reports
Description: View monthly balances and download daily balance and transaction reconciliation reports.
Tags: Dashboard
Path: developer/reports.mdx
[reports]: https://dashboard.paxos.com/admin/reports
Go to [Admin > Reports][reports] to [activate](#activate), view and download daily reconciliation reports as CSV or PDF.
## Onboard to Reporting {#activate}
< ReportsOnboard />
## Reporting Data Dictionary
This data dictionary provides a full list and definition of balance types.
### Profile Balances Report Fields {#ProfileBalancesReport}
< ReportsProfileBalances />
### Profile Transactions Report Fields {#ProfileTransactionReport}
< ReportsProfileTransactions />
### BalanceType Values and Definitions {#BalanceTypeValuesDefinitions}
< ReportsBalanceType />
### Resource Values and Definitions{#ResourceValuesDefinitions}
< ReportsResources />
### ResourceTransferType Values and Definitions {#ResourceTransferTypeValuesDefinitions}
< ReportsResourceTransferType />
### TransactionType Values and Definitions {#TransactionTypeValuesDefinitions}
< ReportsTransactionType />
----------------------------------------
## Redeem
Description: Deposit stablecoin and convert to USD in one API call. Transfer USD to your bank.
Tags: Stablecoin Operations
Path: developer/redeem.mdx
[stablecoins]: blockchains.mdx#stablecoins
[deposit-address]: /api/v2#tag/Deposit-Addresses/operation/CreateDepositAddress
[conversion-api]: /api/v2#tag/Stablecoin-Conversion/operation/CreateStablecoinConversion
[conversion guide]: developer/convert.mdx
[fiat-withdraw]: /api/v2#tag/Fiat-Transfers/operation/CreateFiatWithdrawal
[fiat withdrawal guide]: developer/fiat-transfers/quickstart.mdx#withdrawal
[List Transfers]: /api/v2#tag/Transfers/operation/ListTransfers
[List Deposit Addresses]: /api/v2#tag/Deposit-Addresses/operation/ListDepositAddresses
[token]: developer/authenticate.mdx
To redeem a [Paxos-issued stablecoin][stablecoins], use [Create Deposit Address][deposit-address] to add the appropriate address on the Paxos platform. Next, initiate a stablecoin transfer from your external address (**A** in the diagram).
If you set `conversion_target_asset` to `USD` when creating the address, Paxos automatically credits your USD balance once the on-chain transfer is confirmed (**B**).
Then, use [Create Fiat Withdrawal][fiat-withdraw] to send USD to your bank account (**C**).
:::tip
- To redeem stablecoins you already hold on the Paxos platform, you can use [Create Stablecoin Conversion][conversion-api] to easily convert to USD. See the [conversion guide] for details.
- To send USD to your bank account, you'll need to first save your external banking information on the Paxos platform. See the [fiat withdrawal guide] for details.
:::
## ➊ Authenticate
Include the following scopes when [authenticating][token]:
```shell
funding:read_profile transfer:read_deposit_address transfer:read_transfer transfer:write_deposit_address
```
> If you don't see all the scopes when [creating or editing API credentials](/developer/credentials), contact [Support](https://support.paxos.com).
## ➋ Create Deposit Address {#add-deposit-address}
Use [Create Deposit Address][deposit-address] to add a wallet address to the designated Profile.
Include the appropriate `crypto_network` for the source stablecoin.
Set `conversion_target_asset` to `USD` to automatically convert the stablecoin to USD when the transaction is complete.
```shell
curl --location 'https://api.sandbox.paxos.com/v2/transfer/deposit-addresses' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access_token} \
--data '{
"profile_id": "0d3172c5-8840-4bae-bdd4-30688f0268fc",
"crypto_network": "ETHEREUM",
"ref_id": "r_usdg_8f91a9c5-0a6e-46dc-ad68-17bc8fb4eafb",
"conversion_target_asset": "USD"
}'
```
```shell
curl --location 'https://api.sandbox.paxos.com/v2/transfer/deposit-addresses' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{
"profile_id": "0d3172c5-8840-4bae-bdd4-30688f0268fc",
"crypto_network": "SOLANA",
"ref_id": "r_pyusd_8f91a9c5-0a6e-46dc-ad68-17bc8fb4eafb",
"conversion_target_asset": "USD"
}'
```
Capture the `address` and `compatible_crypto_networks` values from the response.
Also store the `id` to use when looking up transactions.
```json
{
// highlight-next-line
"id": "078eb145-1bbc-4e1d-999d-92845dc31df4",
"profile_id": "0d3172c5-8840-4bae-bdd4-30688f0268fc",
"customer_id": "8cbc1177-d982-4750-a435-3c7f36245452",
"crypto_network": "ETHEREUM",
"identity_id": "00000000-0000-0000-0000-000000000000",
"ref_id": "r_usdg_8f91a9c5-0a6e-46dc-ad68-17bc8fb4eafb",
// highlight-next-line
"address": "0xdCB1481afaabf9dAc1B2A8218067252D533Ae1a7",
"account_id": "00000000-0000-0000-0000-000000000000",
"conversion_target_asset": "USD",
// highlight-next-line
"compatible_crypto_networks": [
"ETHEREUM",
"POLYGON_POS",
"ARBITRUM_ONE"
]
}
```
```json
{
// highlight-next-line
"id": "8488990c-2cc0-441f-a26c-24d01c40a402",
"profile_id": "0d3172c5-8840-4bae-bdd4-30688f0268fc",
"customer_id": "8cbc1177-d982-4750-a435-3c7f36245452",
"crypto_network": "SOLANA",
"identity_id": "00000000-0000-0000-0000-000000000000",
"ref_id": "r_pyusd_8f91a9c5-0a6e-46dc-ad68-17bc8fb4eafb",
// highlight-next-line
"address": "AufgJhf3DW83MUKgCKyrMyNjdCzhcy4LrcXcQsCDQRb2",
"account_id": "00000000-0000-0000-0000-000000000000",
"conversion_target_asset": "USD",
// highlight-next-line
"compatible_crypto_networks": [
"SOLANA"
]
}
```
## ➌ Transfer Stablecoin to the Paxos Platform
Initiate an on-chain transfer from your external wallet to the `address` included in the response from the [previous step](#add-deposit-address) or from [List Deposit Addresses].
Use [List Transfers] to check the status of transfer on the Paxos platform.
Using the `type=CRYPTO_DEPOSIT` and `status=COMPLETED` query parameters, in conjunction with `crypto_tx_hashes`, filters the results.
```shell
curl --location 'https://api.sandbox.paxos.com/v2/transfer/transfers?crypto_tx_hashes=0x768ac1e892985165885140c80f08ee0197ff6e175f9a9ed4b7f1b09c3b49baca' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access_token}'
```
```shell
curl --location 'https://api.sandbox.paxos.com/v2/transfer/transfers?crypto_tx_hashes=3LnaTGt2hmLGFwRkZyh7bGPj8UyYFjJauTS2c4PZ6YQfqwBqTmN8Z6j3LhFrqgTRX7ZcyJrF2NrrJxztAX3n3uL9' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access_token}'
```
Depending on the network, it may take some time for the transaction to update on the Paxos platform.
Once the status is `COMPLETED`, the USD balance updates.
```json
{
"items": [
{
"id": "d72363d9-52bb-4acd-ba35-b5b1e212ac26",
"customer_id": "8cbc1177-d982-4750-a435-3c7f36245452",
"profile_id": "0d3172c5-8840-4bae-bdd4-30688f0268fc",
"amount": "100",
"total": "100",
"fee": "0",
"asset": "USDG",
"balance_asset": "USD",
"direction": "CREDIT",
"type": "CRYPTO_DEPOSIT",
"status": "COMPLETED",
...
"destination_address": "0xdCB1481afaabf9dAc1B2A8218067252D533Ae1a7",
"crypto_network": "ETHEREUM",
"crypto_tx_hash": "0x768ac1e892985165885140c80f08ee0197ff6e175f9a9ed4b7f1b09c3b49baca",
"crypto_tx_index": "132",
"auto_conversion": {}
}
],
"next_page_cursor": "CAESDAjJq_a3BhCI9LaXAhjwhN8N"
}
```
```json
{
"items": [
{
"id": "54235f7e-585c-4c08-b170-15bb10f74c1e",
"customer_id": "8cbc1177-d982-4750-a435-3c7f36245452",
"profile_id": "0d3172c5-8840-4bae-bdd4-30688f0268fc",
"amount": "100",
"total": "100",
"fee": "0",
"asset": "PYUSD",
"balance_asset": "USD",
"direction": "CREDIT",
"type": "CRYPTO_DEPOSIT",
"status": "COMPLETED",
...
"destination_address": "AufgJhf3DW83MUKgCKyrMyNjdCzhcy4LrcXcQsCDQRb2",
"crypto_network": "SOLANA",
"crypto_tx_hash": "3LnaTGt2hmLGFwRkZyh7bGPj8UyYFjJauTS2c4PZ6YQfqwBqTmN8Z6j3LhFrqgTRX7ZcyJrF2NrrJxztAX3n3uL9",
"crypto_tx_index": "4",
"auto_conversion": {}
}
],
"next_page_cursor": "CAESDAi7n_a3BhCIkuKsAxisgt8N"
}
```
## ➍ Transfer USD to Bank Account
Use [Create Fiat Withdrawal][fiat-withdraw] to send USD to your bank account.
You'll need to first save your external banking information on the Paxos platform.
See the [fiat withdrawal guide] for details.
----------------------------------------
## Rate Limits
Description: Review REST, WebSocket and FIX limits.
Tags: Developer Guide
Path: developer/rate-limits.mdx
Paxos implements REST and WebSocket limits to help ensure platform stability.
All integrations should observe the stated rate limits to prevent disruptions.
## REST Limits
Paxos sets rate limits per endpoint and IP address, based on the average number of requests per second during a five (5) minute window.
If you hit a rate limit on a specific endpoint, you will receive a `429` response status code. All requests from the offending IP are then throttled for five (5) minutes.
Minimally, Paxos recommends gracefully handling limits by watching for `429` status codes and building retry functionality.
The retry mechanism should include a backoff schedule that takes volume into consideration.
There are a number of open source tools available to help handle rate limits.
## WebSocket Limits
Market and execution data services have a rate limit of one (1) subscription per second from the same IP address.
If the rate limit is exceeded, no error message is sent.
Rather, each client must wait one (1) second before receiving data.
For example, if 20 new clients connect from the same IP address, it will take about 20 seconds for all the clients to receive data.
> When connecting a large number of clients, some may fail and close the connection before receiving a response from the server.
Paxos recommends all clients implement a single `wss://` connection at the server level (multiplexing).
Multiple connections can create logistical and update issues without providing appreciable performance gains.
To support integration and platform stability and maintenance, each implementation should:
- Ensure all application clients can easily rollout platform updates to users through a single mechanism.
- Have a centralized reconnection mechanism to recover from any feed disruptions.
- Have a reconnection mechanism in case of server disconnection.
- Observe the WebSocket rate limits.
Paxos support may reach out to you if your client does not implement this guidance.
## FIX Limits
Maximum 150 messages per second, per session.
----------------------------------------
## Convert
Description: Implement guaranteed 1:1 conversions between USD and Paxos-issued stablecoins.
Tags: Stablecoin Operations
Path: developer/convert.mdx
[asset]: developer/convert.mdx#assets
[convert]: /api/v2#tag/Stablecoin-Conversion/operation/CreateStablecoinConversion
[list]: /api/v2#tag/Stablecoin-Conversion/operation/ListStablecoinConversions
[get]: /api/v2#tag/Stablecoin-Conversion/operation/GetStablecoinConversion
[usdg]: stablecoin/usdg/index.mdx
[usdp]: stablecoin/usdp/index.mdx
[pyusd]: stablecoin/pyusd/index.mdx
[cancel]: /api/v2#tag/Stablecoin-Conversion/operation/CancelStablecoinConversion
[support]: https://support.paxos.com
[client]: developer/credentials.mdx
[token]: developer/authenticate.mdx
[conversion-list-conversion]: /api/v2#tag/Stablecoin-Conversion/operation/ListStablecoinConversions
[create-sandbox-deposit]: /api/v2#tag/Sandbox-Deposits/operation/CreateSandboxDeposit
[First API Request]: developer/request.mdx
[conversion-create-conversion]: /api/v2#tag/Stablecoin-Conversion/operation/CreateStablecoinConversion
[3p-integrations]: /crypto-brokerage/ledger-type.mdx#fiat-and-crypto-subledger
[conversion status]: developer/convert.mdx#statuses
[fiat-transfers]: developer/fiat-transfers/quickstart.mdx#funding
Next, use the [Stablecoin Conversion API][convert] to easily convert USD to any [supported asset][asset], and vice verse, without any fees.
Keep track of all your conversions with [List Stablecoin Conversions][list] or [lookup a single conversion][get].
> If you've already authenticated and have USD and USDG balances in a Profile, skip ahead to the [request a conversion](#request-conversion) step.
## ➊ Authenticate
Include the following scopes when [authenticating][token]:
```shell
conversion:read_conversion_stablecoin conversion:write_conversion_stablecoin funding:read_profile
```
> If you don't see all the scopes when [creating or editing API credentials](/developer/credentials), contact [Support](https://support.paxos.com).
## ➋ Deposit USD and USDG
Use [Create Sandbox Deposit][create-sandbox-deposit] to add USD to the Profile (`profile_id`) you want the conversion to be associated with. See the [First API Request] guide for help retrieving Profile IDs.
This guide also includes examples for the USDG → USD conversion, so if you are following along make sure you add some USDG to the Profile.
You can also use the [Fiat Transfers funding flow][fiat-transfers] if you've already set up a Fiat Account.
```shell
curl --request POST \
// highlight-next-line
--location 'https://api.sandbox.paxos.com/v2/sandbox/profiles/0d3172c5-8840-4bae-bdd4-30688f0268fc/deposit' \
--header 'Authorization: Bearer {access_token}' \
--data '{
"asset": "USD",
"amount": "1000"
}'
```
```shell
curl --location 'https://api.sandbox.paxos.com/v2/sandbox/profiles/0d3172c5-8840-4bae-bdd4-30688f0268fc/deposit' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{
"asset": "USDG",
"amount": "100",
"crypto_network": "ETHEREUM"
}'
```
## ➌ Request Conversion {#request-conversion}
Request a conversion using [Create Stablecoin Conversion][conversion-create-conversion].
Include the following body parameters in your request to convert the `source_asset` of $100 USD into the `target_asset`.
For [Third-party integrations][3p-integrations], you must also specify `identity_id` and `account_id`.
```shell
curl --location 'https://api.sandbox.paxos.com/v2/conversion/stablecoins' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{
"ref_id": "sc_usdg_a284608c-4cf0-4605-ae0a-5c1f7ff109d3",
"profile_id": "0d3172c5-8840-4bae-bdd4-30688f0268fc",
"amount": "100",
"source_asset": "USDG",
"target_asset": "USD",
}'
```
The acknowledgement response includes the `id`, which can be used to lookup the transaction, and the status will always be `CREATED`.
The `source_asset` is immediately debited from the associated `profile_id` balance.
The `target_asset` will not be credited until the [conversion status] is `"status": "SETTLED"`.
```json
{
"id": "ea284608c-4cf0-4605-ae0a-5c1f7ff109d3",
"profile_id": "0d3172c5-8840-4bae-bdd4-30688f0268fc",
"amount": "100",
"source_asset": "USDG",
"target_asset": "USD",
"status": "CREATED",
"ref_id": "sc_usdg_a284608c-4cf0-4605-ae0a-5c1f7ff109d3",
...
}
```
```shell
curl --location 'https://api.sandbox.paxos.com/v2/conversion/stablecoins' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{
"ref_id": "sc_pyusd_8f91a9c5-0a6e-46dc-ad68-17bc8fb4eafb",
"profile_id": "0d3172c5-8840-4bae-bdd4-30688f0268fc",
"amount": "100",
"source_asset": "USD",
"target_asset": "PYUSD",
}'
```
The acknowledgement response includes the `id`, which can be used to lookup the transaction, and the status will always be `CREATED`.
The `source_asset` is immediately debited from the associated `profile_id` balance.
The `target_asset` will not be credited until the [conversion status] is `"status": "SETTLED"`.
```json
{
"id": "f190b163-208f-4d73-8deb-4fb8b24add00",
"profile_id": "0d3172c5-8840-4bae-bdd4-30688f0268fc",
"amount": "100",
"source_asset": "USD",
"target_asset": "PYUSD",
"status": "CREATED",
"ref_id": "sc_pyusd_8f91a9c5-0a6e-46dc-ad68-17bc8fb4eafb",
...
}
```
## ➍ Confirm the Conversion
Use [List Stablecoin Conversions][conversion-list-conversion] to check the conversion status.
The request requires the `profile_id` query parameter.
```shell
curl --location 'https://api.sandbox.paxos.com/v2/conversion/stablecoins?profile_id=0d3172c5-8840-4bae-bdd4-30688f0268fc&order=DESC' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access_token}'
```
The returned array includes the `settled_at` parameter and the status is `SETTLED` for all conversions executed for the given Profile.
```json
{
"items": [
{
"id": "08f67bca-fb30-4006-8ed2-d46750dd1293",
"profile_id": "0d3172c5-8840-4bae-bdd4-30688f0268fc",
"amount": "100",
"source_asset": "USDG",
"target_asset": "USD",
"status": "SETTLED",
...
"settled_at": "2024-09-25T15:07:56.076853Z"
},
{
"id": "9f458a60-8b9b-4b3c-b5a4-ee57bc795086",
"profile_id": "0d3172c5-8840-4bae-bdd4-30688f0268fc",
"amount": "100",
"source_asset": "USD",
"target_asset": "PYUSD",
"status": "SETTLED",
...
"settled_at": "2024-09-25T15:07:21.548903Z"
},
]
}
```
## Stablecoin Conversion Asset Precision {#assets}
You can convert USD to any supported asset and vice versa.
However, you cannot convert one stablecoin to another.
All conversions use the lowest maximum precision among the asset pairs.
| Supported Asset | Maximum Decimal Precision | Example Conversion Precision |
| --- | --- | -- |
| USD | 0.01 (1e-2) | USD → USDG = 0.01 (1e-2) |
| [PYUSD][pyusd] | 0.000001 (1e-6) | PYUSD → USD = 0.01 (1e-2) |
| [USDG][usdg] | 0.00000001 (1e-8) | USDG → USD = 0.01 (1e-2) |
| [USDP][usdp] | 0.00000001 (1e-8) | USDP → USD = 0.01 (1e-2) |
## Stablecoin Conversion Statuses
There are three conversion statuses:
- `CREATED`: The conversion has been submitted successfully but has not yet settled.
- `SETTLED`: The conversion has been completed.
- `CANCELLED`: The conversion was stopped [using the cancel endpoint][cancel] for the pending conversion.
When a conversion is in `CREATED` status, the `source_asset` (for example, fiat for acquiring stablecoin) will be debited from the `profile_id` balance.
The `target_asset` (for example, USDG for acquiring stablecoin) will not be credited until the order has `SETTLED`.
:::tip Best Practice
- Build a pending conversion settlement workflow for edge cases where the conversion does not settle immediately. This is especially - Log the transaction details from each conversion in a database.
- Cache Profile balances. Balances should be updated once there has been a change to the Profile balance (for example, after a conversion) and then perform a reconciliation to confirm the updated balance matches the client's internal calculation.
- Create a polling workflow to query the results in ascending order. Keep track of the `created_at` timestamp of the most recent conversion in the paged results.
:::
----------------------------------------
## Request Signing
Description: Use JWS to add an additional layer of security to every request.
Path: developer/request-signing.mdx
[mTLS]: https://www.cloudflare.com/learning/access-management/what-is-mutual-tls/
[SSH]: https://www.ssh.com/academy/ssh/public-key-authentication
[Support]: https://support.paxos.com
[Sandbox]: developer/sandbox.mdx
[PyJWT]: https://pypi.org/project/PyJWT/
[openssl]: https://openssl-library.org/
[admin-api-sandbox]: https://dashboard.sandbox.paxos.com/admin/api
[admin-api-production]: https://dashboard.paxos.com/admin/api
Request signing adds an additional layer of security to every request you send to Paxos, and can help protect your account should your Paxos API Client ID and Secret become compromised.
Once request signing is enabled on your account, Paxos rejects all unsigned requests to authenticated endpoints.
> Request signing must be activated by Paxos. Contact [Support] to get started.
Signed requests use your own private key, similar to [mTLS] or [SSH] public authentication, and then attach the signature to the request as the `Paxos-Signature HTTP header`, using the JSON Web Signature (JWS) format.
## Set Up Signed Request
To get started, you will need to have the **Client ID** and **Secret** available for constructing the payload.
Additionally, install the JOSE/JWS library in the language of your choice, for example [PyJWT][PyJWT] which includes support for crypto.
> Never share your private keys with anyone, especially for Production deployments.
> Using an HSM, secrets manager, or key-management service may provide an additional layer of protection.
### ➊ Generate Key Pair
Generate the JWS signature with your private key using a combination of the base64url encoded header and payload, using either the EdDSA (ed25519) or the ES256 algorithm.
> To use the EdDSA (ed25519) algorithm when generating key pairs, install [OpenSSL 3][openssl] using the package manager of your choice.
> Older versions of OpenSSL do not support the EdDSA (ed25519) algorithm.
To generate a new ES256 private key using the terminal:
1. Ensure OpenSSL 3 is installed:`openssl version`
1. Create a new ES256 private key in the current working directory:`openssl ecparam -name prime256v1 -genkey -noout -out my-private-ec.pem`
1. Generate the public key in the current working directory:`openssl ec -in my-private-ec.pem -pubout > my-public-ec.pem`
The process for EdDSA (ed25519) keys is similar:
1. Ensure OpenSSL 3 is installed:`openssl version`
1. `openssl genpkey -algorithm ed25519 -outform PEM -out my-private-key.pem`
1. `openssl pkey -in my-private-key.pem -pubout > my-public-key.pem`
> Never share your private keys with anyone, especially for Production deployments.
> Using an HSM, secrets manager, or key-management service may provide an additional layer of protection.
### ➋ Add Public Key to Your Paxos Account
Go to ** Admin > API** in either [Sandbox][admin-api-sandbox] or [Production][admin-api-production] and find the **API Credentials** that require request signing.
> Request signing must be activated by Paxos. Contact [Support] to get started.
Scroll down and use **Edit API Credentials** to make changes.
Switch **Request Signing** to open the edit dialogue and add your _Public Key_.
Once you **Save Changes**, contact [Support] to get started.
### ➌ Generate Signed Request
Use a JOSE/JWS library such as [PyJWT] to generate the signature.
#### Construct Header
The header must include the following:
| Header Item | Description |
| --- | --- |
| **kid** | The Key ID of the configured Public Key. Retrieve from Admin > API > API Cretentials. |
| **alg** | The algorithm used to generate the Key. The value must be: EdDSA or ES256. Retrieve from Admin > API > API Cretentials. |
| **paxos.com/timestamp** | The current timestamp in UNIX time format. Signatures remain valid for 30 minutes after the specified timestamp. |
| ** paxos.com/request-method** | The POST and PUT methods also require the JWS payload in the body bytes. |
| **paxos.com/request-path** | The endpoint path, including query parameters. |
Putting it together, your header should look similar to the following:
```json
{
"kid" : "5498f424-78aa-414b-a515-13929e6951db",
"alg" : "ES256",
"paxos.com/timestamp" : "1645503272",
"paxos.com/request-method" : "POST",
"paxos.com/request-path" : "/v2/transfer/deposit-addresses"
}
```
When using a `POST` or `PUT` method, include the JWS payload in the body bytes:
```json
{"profile_id":"42bb1a2e-a68e-44d7-b5f1-59ccc5c13e91","crypto_network":"ETHEREUM"}
```
#### Create Signature
Use a library such as [PyJWT] to generate the request signature.
First, install the library and start a new session.
For example:
```shell
pip3 install "pyjwt[crypto]" && python3
```
Then generate the JWT signature:
```py
>>> >>> payload = b'{"profile_id":"42bb1a2e-a68e-44d7-b5f1-59ccc5c13e91","crypto_network":"ETHEREUM"}'
>>> with open('./my-private-ec.pem', 'rb') as f: key = f.read()
...
>>> alg = "ES256" if key.find('BEGIN EC PRIVATE'.encode('ascii')) > 0 else "EdDSA"
>>> headers = {"kid": "5498f424-78aa-414b-a515-13929e6951db", "alg": alg,
"paxos.com/timestamp": "1645503272",
"paxos.com/request-method" : "POST",
"paxos.com/request-path": "/v2/transfer/deposit-addresses"}
>>> signature = jwt.api_jws.encode(payload=payload, key=key, headers=headers,algorithm=alg)
>>> print(signature)
eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjU0OThmNDI0LTc4YWEtNDE0Yi1hNTE1LTEzO
TI5ZTY5NTFkYiIsInBheG9zLmNvbS90aW1lc3RhbXAiOiIxNjQ1NTAzMjcyIiwicGF4b3MuY29tL3JlcX
Vlc3QtbWV0aG9kIjoiUE9TVCIsInBheG9zLmNvbS9yZXF1ZXN0LXBhdGgiOiIvdjIvdHJhbnNmZXIvZGV
wb3NpdC1hZGRyZXNzZXMifQ.eyJwcm9maWxlX2lkIjoiNDJiYjFhMmUtYTY4ZS00NGQ3LWI1ZjEtNTljY
2M1YzEzZTkxIiwiY3J5cHRvX25ldHdvcmsiOiJFVEhFUkVVTSJ9.7x8b_4j1dFMd1XWcmpGaf5OiyU0lo
2fbGlbe8epuiAJFpFziwxhhKHbc7-DaqKMV9MTTARX8VM3d2YSugPEAow
>>> exit()
```
### ➍ Send Signed Request
Use the generated signature to send a signed request to Paxos.
First, authenticate with the APIs.
For example:
```shell
curl https://oauth.sandbox.paxos.com/oauth2/token \
-F grant_type=client_credentials \
-F client_id={client_id} \
-F client_secret={secret} \
-F scope="transfer:write_deposit_address"
```
Then send the signed API request:
```shell
curl -X POST https://api.sandbox.paxos.com/v2/transfer/deposit-addresses
-H "Authorization: Bearer {access_token}"
-H "Paxos-Signature: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjU0OThmNDI0LTc4Y
WEtNDE0Yi1hNTE1LTEzOTI5ZTY5NTFkYiIsInBheG9zLmNvbS90aW1lc3RhbXAiOiIxNjQ1NTAzMjcyIiw
icGF4b3MuY29tL3JlcXVlc3QtbWV0aG9kIjoiUE9TVCIsInBheG9zLmNvbS9yZXF1ZXN0LXBhdGgiOiIvd
jIvdHJhbnNmZXIvZGVwb3NpdC1hZGRyZXNzZXMifQ.eyJwcm9maWxlX2lkIjoiNDJiYjFhMmUtYTY4ZS00
NGQ3LWI1ZjEtNTljY2M1YzEzZTkxIiwiY3J5cHRvX25ldHdvcmsiOiJFVEhFUkVVTSJ9.7x8b_4j1dFMd1
XWcmpGaf5OiyU0lo2fbGlbe8epuiAJFpFziwxhhKHbc7-DaqKMV9MTTARX8VM3d2YSugPEAow"
-d '{"profile_id":"42bb1a2e-a68e-44d7-b5f1-59ccc5c13e91","crypto_network":"ETHEREUM"}'
```
## Manage Signed Requests
For Production environments, you may want to create multiple API Credentials with different permissions and authentication.
For example, you may want to sign all order and identity requests but not requests for historical data.
To do this, you can create multiple API Credentials and then enable request signing for only those users or applications dealing with sensitive information.
- **Use Multiple Request Signing Keys**. It is also possible for you to simultaneously use multiple request signing keys with a single API Credential. Once you add an additional request signing key, it is immediately available for use, along with any existing key, for the API Credential. Used in this way, you can assign different request signing keys to different users or applications that use the same API Credential. This can come in handy if you need to revoke access for an application or user with a specific key: The API Credentials remain active, along with the other keys.
- **Rotate API Credentials**. If your API Credentials needs to be changed, the Rotate Credentials option regenerates a new Secret, leaving the Client ID unchanged. When you rotate credentials, you will need to update any implementation that uses the Client ID. Once that is done, your request signing keys work with the new Secret.
----------------------------------------
## Sandbox
Description: Use the Sandbox environment to mock flows, execute transfers and test integrations.
Tags: Developer Guide
Path: developer/sandbox.mdx
[v2-api]: /api/v2
[sandbox-account]: https://dashboard.sandbox.paxos.com/
[create-sandbox-deposit]: /api/v2#tag/Sandbox-Deposits/operation/CreateSandboxDeposit
[create-deposit-address]: /api/v2#tag/Deposit-Addresses/operation/CreateDepositAddress
[crypto-withdrawal]: /api/v2#tag/Crypto-Withdrawals/operation/CreateCryptoWithdrawal
[identity]: /api/v2#tag/Identity
[sandbox-identity]: /api/v2#tag/Sandbox-Identity/operation/SandboxSetIdentityStatus
[fiat]: /api/v2#tag/Fiat-Transfers
[sandbox-fiat]: /api/v2#tag/Sandbox-Fiat-Transfers
[fiat-instructions]: /api/v2#tag/Fiat-Transfers/operation/ListFiatDepositInstructions
[fiat-guide]: developer/fiat-transfers/quickstart.mdx#2-send-fiat-to-paxos
[credentials]: developer/credentials.mdx
[authenticate]: developer/authenticate.mdx
[Support]: https://support.paxos.com
The Developer Sandbox replicates core [v2 API][v2-api] functionality with an automated system that uses test fund to simulate normal activities, including a few Sandbox-only endpoints.
> To start using the Sandbox environment, [create a Developer account][sandbox-account].
## Sandbox Testnets and Devnets
When you use [Create Sandbox Deposit][create-sandbox-deposit] to fund a Profile, the platform creates the asset on the testing network.
The asset can then be [transferred][crypto-withdrawal] to any off-platform address that supports the test network.
Similarly, when using [create a deposit address][create-deposit-address] in Sandbox, the generated address can be used to transfer test assets to the Paxos platform.
| Crypto Network | Supported Testnet/Devnet |
| --- | --- |
| Arbitrum One | Sepolia |
| Bitcoin | Testnet3 |
| Bitcoin Cash | Testnet |
| Ethereum | Sepolia |
| Litecoin | Testnet |
| Polygon POS | Sepolia |
| Solana | Devnet |
## Sandbox Identity Testing
When testing the [Identity APIs][identity] in Sandbox, you may be blocked by a verification process.
If this is the case, use [Sandbox Set Identity Status][sandbox-identity] to change `id_verification_status` and `sanctions_verification_status` to `"APPROVED"`and enable an individual identity to transact during Sandbox testing.
To enable the Institution to transact during Sandbox testing, set `sanctions_verification_status` to `"APPROVED"`.
## Sandbox Fiat Transfer Testing
To test [Fiat Transfers API][fiat] in Sandbox, the [Initiate Sandbox Fiat Deposit][sandbox-fiat] endpoint starts test fiat deposit that will be processed based on the `memo_id` from a previous [Fiat Deposit Instructions][fiat-instructions] response.
Learn more in the [Fiat Transfer Guide][fiat-guide].
> When [creating API credentials][credentials] via the Dashboard, the `transfer:write_sandbox_fiat_deposit` scope may not appear in the UI.
> Including the scope when [authenticating][authenticate] may result in an `invalid_scope` error.
> Contact [Support] if you run into any issues using this scope.
----------------------------------------
## Authenticate
Description: Generate an authentication token.
Tags: Quickstart
Path: developer/authenticate.mdx
[credentials]: developer/credentials.mdx
[login]: https://dashboard.paxos.com
[support]: https://support.liftdollar.com
[oauth2]: https://oauth.net/code
[convert]: developer/convert.mdx
[make an API call in Sandbox]: developer/request.mdx
[mint]: developer/mint.mdx
[redeem]: developer/redeem.mdx
The APIs use industry standard OAuth2 for authentication.
Most users find success with one of the libraries on the [OAuth2 website][oauth2].
The following URLs can be used when using an off-the-shelf OAuth2 library:
| Environment | Root URL | Full Path |
| --- | --- | --- |
| Sandbox | https://oauth.sandbox.paxos.com | https://oauth.sandbox.paxos.com/oauth2/token |
| Production | https://oauth.paxos.com | https://oauth.paxos.com/oauth2/token |
## ➊ Add Scopes (Client Permissions)
When authenticating, include the scopes (**Client Permissions**) necessary for the client to complete the intended actions.
> Scopes for each endpoint are listed in the **Authorizations** section in the [API Reference docs](/api/v2).
> The [Market Data](/api/v2#tag/Market-Data) and most [Pricing](/api/v2#tag/Pricing) endpoints do not require authorization.
For example, the following scopes (space delimited) should provide sufficient permissions to [mint], [redeem], and [convert] Paxos-isssued stablecoins:
## ➋ Get Access Token {#token}
Every endpoint that requires a **Scope** must be accompanied by an `"Authorization"` header
with a value that follows the `"Bearer {access_token}"` schema.
To authenticate with https://oauth.sandbox.paxos.com/oauth2/token, use your [credentials][credentials] to create a bearer token.
The authentication request must include `{client_id}` (**Client ID**) and `{client_secret}` (**Client Secret**) configured for your [API credentials][credentials].
Include sufficient `{client_scopes}` (**Client Permissions**).
```shell
curl --location 'https://oauth.sandbox.paxos.com/oauth2/token' \
--form grant_type=client_credentials \
--form client_id={client_id} \
--form client_secret={client_secret} \
// highlight-next-line
--form scope='{client_scopes}'
```
To authenticate with https://oauth.paxos.com/oauth2/token, use your [credentials][credentials] to create a bearer token.
The authentication request must include the `{client_id}` (**Client ID**) and `{client_secret}` (**Client Secret**) configured for your [API credentials][credentials].
Include sufficient `{client_scopes}` (**Client Permissions**).
```shell
curl --location 'https://oauth.paxos.com/oauth2/token' \
--form grant_type=client_credentials \
--form client_id={client_id} \
--form client_secret={client_secret} \
// highlight-next-line
--form scope='{client_scopes}'
```
Confirm the response includes the requisite scopes and save the `access_token` to use in the request authorization header (`-H "Authorization: Bearer {access_token}"`).
```json
{
"access_token": "{access_token}",
// highlight-next-line
"expires_in": 3599, // Seconds (59 Minutes and 59 Seconds)
// highlight-next-line
"scope": "{client_scopes}",
"token_type": "bearer"
}
```
Once you have the `access_token`, [make an API call in Sandbox].
----------------------------------------
## Make First API Request
Description: Use the access token to retrieve a list of Profiles.
Tags: Quickstart
Path: developer/request.mdx
[access token]: /developer/authenticate.mdx#token
[adding scopes]: /developer/authenticate.mdx#scopes
[Profile]: /api/v2#tag/Profiles
[List Profiles]: /api/v2#tag/Profiles/operation/ListProfiles
[credentials]: /developer/credentials.mdx
[authentication]: /developer/authenticate.mdx
[Support]: https://support.paxos.com
Since every account has a `DEFAULT` [Profile], sending a request using [List Profiles] will always return a result, assuming the `funding:read_profile` scope was included when [adding scopes] to the client.
Include the [access token] from the authentication request in the authorization header.
```shell
curl --location 'https://api.sandbox.paxos.com/v2/profiles?order=ASC&order_by=CREATED_AT' \
--header 'Accept: application/json' \
// highlight-next-line
--header 'Authorization: Bearer {access_token}'
```
```shell
curl --location 'https://api.paxos.com/v2/profiles?order=ASC&order_by=CREATED_AT' \
--header 'Accept: application/json' \
// highlight-next-line
--header 'Authorization: Bearer {access_token}'
```
A successful response includes all Profiles the client has access to.
Using the `?order=ASC&order_by=CREATED_AT` parameters ensures the `DEFAULT` Profile is first in the list.
```json
{
"items": [
// highlight-start
{
"id": "0d3172c5-8840-4bae-bdd4-30688f0268fc",
"nickname": "default",
"type": "DEFAULT"
},
// highlight-end
{
"id": "7437da4d-c114-4a1f-8659-ceeaf868a1eb",
"nickname": "Mint",
"type": "NORMAL"
},
{
"id": "4bdfed80-ed0d-461b-bfee-0ff5011a9db5",
"nickname": "Redeem",
"type": "NORMAL"
},
]
}
```
If you get an error, run through the [credentials] and [authentication] guides and ensure your setup is correct.
If things are still not working, contact [Support].
----------------------------------------
## Fiat Transfers
Description: Move USD on and off the Paxos Platform via wire transfer or CUBIX.
Tags: Fiat Transfers
Path: developer/fiat-transfers/index.mdx
## Fiat Deposits and Withdrawals
Paxos credits your USD wire deposit as soon as it is received by our bank.
Domestic wire withdrawals are processed via the FedWire system and may take 1-3 business days to settle. International wire withdrawals may take 1-5 days to reach the beneficiary bank.
Paxos can accept wires from or send wires to a bank account, even if the bank account owner is not the same as the individual or institution onboarded with Paxos.
This means Paxos allows wire transfers involving third-party bank accounts, subject to applicable compliance and regulatory checks.
CUBIX USD transfers are processed 24/7; however, longer processing time may occasionally be required.
CUBIX deposits are not subject to any limits.
:::note
- Deposits with missing or incorrect information will be returned.
- USD wire transfers are not processed on weekends and on US banking holidays. CUBIX transfers are processed 24/7.
:::
----------------------------------------
## Statuses
Description: Learn more about Fiat Transfers statuses.
Tags: Fiat Transfers
Path: developer/fiat-transfers/statuses.mdx
[create-fiat-account]: /api/v2#tag/Fiat-Transfers/operation/CreateFiatAccount
[create-fiat-Withdrawal]: /api/v2#tag/Fiat-Transfers/operation/CreateFiatWithdrawal
[list-transfers]: /api/v2#tag/Transfers/operation/ListTransfers
The Fiat Transfers workflow includes five (5) statuses:
- `PENDING`: Initial state. The [Create Fiat Account][create-fiat-account] or [Create Fiat Withdrawal][create-fiat-Withdrawal] request is under review.
- `APPROVED`: The [Create Fiat Account][create-fiat-account] request passed internal review. Can be used for withdrawals.
- `REJECTED`: The [Create Fiat Account][create-fiat-account] request did not pass internal review. Cannot be used for withdrawals.
- `COMPLETED`: For deposits, the corresponding `profile_id` has been credited. For withdrawals, the transfer has been sent to the external bank account.
- `FAILED`: The deposit or withdrawal did not pass internal requirements.
----------------------------------------
## Fiat Transfers FAQ
Description: Get answers to common questions about the Fiat Transfers API.
Tags: Fiat Transfers
Path: developer/fiat-transfers/fiat-transfers-faq.mdx
[transfers-fees]: https://cryptobrokerage.paxos.com/hc/en-us/articles/360042321231-Deposit-Withdrawal-Fees
[jws-request-signing]: https://cryptobrokerage.paxos.com/hc/en-us/articles/6716212970516-How-to-Use-Request-Signing
[list-fiat-accounts]: /api/v2#tag/Fiat-Transfers/operation/ListFiatAccounts
[get-fiat-account]: /api/v2#tag/Fiat-Transfers/operation/GetFiatAccount
[identity-api]: /api/v2#tag/Identity
## What can I do with the Fiat Transfers API?
- Paxos can accept wires from or send wires to a bank account, even if the bank account owner is not the same as the individual or institution onboarded with Paxos. This means Paxos allows wire transfers involving third-party bank accounts, subject to applicable compliance and regulatory checks.
- Fund your Paxos corporate account or withdraw your funds to an external bank account.
- Enable your users to directly fund their account or withdraw their funds to an external bank account.
## How do I get the Identity ID required in requests?
- Paxos will send you the Identity ID for your corporate account.
- For user-based funding, Integrate the [Identity API][identity-api] and use the corresponding endpoints.
## How do I input the routing number (ABA) for US wires (Fedwire)?
Use `routing_number_type` = `ABA`. For US domestic wires, set `fiat_network` = `WIRE` and `routing_number_type` = `ABA`.
## How do I input the SWIFT/BIC code for SWIFT wires?
Use `routing_number_type` = `SWIFT`. For SWIFT wires, set `fiat_network` = `WIRE` and `routing_number_type` = `SWIFT`.
## Do I need JWS request signing?
It is recommended to have [JWS request signing][jws-request-signing] for fiat withdrawals.
JWS request signing uses a public-key cryptography with a client-controlled private key.
It adds an additional layer of security to withdrawals.
It can prevent malicious withdrawals even if the API key secret is compromised.
When used, all API calls with this key will require a JWS signature.
## How do I retrieve fiat account information?
Use [Get Fiat Account][get-fiat-account] to get complete details of the fiat account.
[List Fiat Account][list-fiat-accounts] excludes beneficiary name and address details and only includes the last four (4) digits of the account number.
## Are there fees associated with fiat transfers?
For withdrawals, fees are in addition to the requested amount.
For deposits, fees are deducted from the received amount.
See [Deposit & Withdrawal Fees][transfers-fees] for the current fee structure.
----------------------------------------
## Fiat Transfers Quickstart
Description: Set up fiat funding and withdraw flows in the Sandbox environment.
Tags: Fiat Transfers
Path: developer/fiat-transfers/quickstart.mdx
[authenticate]: developer/authenticate.mdx
[credentials]: developer/credentials.mdx
[api-management]: https://dashboard.sandbox.paxos.com/admin/api
[sandbox-account]: https://dashboard.sandbox.paxos.com
[get-transfer]: /api/v2#tag/Transfers/operation/GetTransfer
[list-transfers]: /api/v2#tag/Transfers/operation/ListTransfers
[create-fiat-deposit-instructions]: /api/v2#tag/Fiat-Transfers/operation/CreateFiatDepositInstructions
[get-profile-balance]: /api/v2#tag/Profiles/operation/GetProfileBalance
[create-fiat-account]: /api/v2#tag/Fiat-Transfers/operation/CreateFiatAccount
[get-fiat-account]: /api/v2#tag/Fiat-Transfers/operation/GetFiatAccount
[list-fiat-accounts]: /api/v2#tag/Fiat-Transfers/operation/ListFiatAccounts
[initiate-sandbox-fiat-deposit]: /api/v2#tag/Sandbox-Fiat-Transfers/operation/InitiateSandboxFiatDeposit
[create-fiat-withdrawal]: /api/v2#tag/Fiat-Transfers/operation/CreateFiatWithdrawal
[update-fiat-account]: /api/v2#tag/Fiat-Transfers/operation/UpdateFiatAccount
[jws-request-signing]: https://cryptobrokerage.paxos.com/hc/en-us/articles/6716212970516-How-to-Use-Request-Signing
[fiat-transfers]: /api/v2#tag/Fiat-Transfers
[transfers]: /api/v2#tag/Transfers
[profiles]: /api/v2#tag/Profiles
[Support]: https://support.paxos.com
This guides walks you through the steps to [send fiat to the Paxos Platform](#funding) as well as [move money to an external bank account](#withdrawal) using the [Fiat Transfers][fiat-transfers], [Transfers][transfers] and [Profiles][profiles] APIs.
Once completed, similar workflows can be implemented in Production.
If you already have a [Sandbox Account][sandbox-account], this guide should take less than one hour to complete.
## Authenticate in Sandbox {#authenticate}
Both the [funding](#funding) and [withdrawal](#withdrawal) flows require the same scopes, so for simplicity one authentication call should be all you need to complete both flows.
> When [creating API credentials][credentials] via the Dashboard, the `transfer:write_sandbox_fiat_deposit` scope may not appear in the UI.
> Including the scope when [authenticating][authenticate] may result in an `invalid_scope` error.
> Contact [Support] if you run into any issues using this scope.
Add the `transfer:read_fiat_account`, `transfer:write_fiat_account`, `transfer:read_fiat_deposit_instructions`, `transfer:write_fiat_deposit_instructions`, `transfer:write_fiat_withdrawal`, `transfer:write_sandbox_fiat_deposit`, `transfer:read_transfer` and `funding:read_profile` scopes to your [Sandbox Account][sandbox-account]
under the [API Management][api-management] setting and then authenticate in Sandbox using the scopes.
```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} \
// highlight-next-line
--form scope='transfer:read_fiat_account transfer:write_fiat_account transfer:read_fiat_deposit_instructions transfer:write_fiat_deposit_instructions transfer:write_fiat_withdrawal transfer:write_sandbox_fiat_deposit transfer:read_transfer funding:read_profile'
```
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}",
// highlight-next-line
"expires_in": 3599, // Seconds (59 Minutes and 59 Seconds)
// highlight-next-line
"scope": "transfer:read_fiat_account transfer:write_fiat_account transfer:read_fiat_deposit_instructions transfer:write_fiat_deposit_instructions transfer:write_fiat_withdrawal transfer:write_sandbox_fiat_deposit transfer:read_transfer funding:read_profile",
"token_type": "bearer"
}
```
:::note
You must include the Authorization header with your bearer token on all API requests `-H "Authorization: Bearer $TOKEN"`.
:::
## Funding Flow {#funding}
We'll be following the recommended fiat deposit workflow:
- [Authenticate in Sandbox](#authenticate).
- Get instructions from Paxos on how to deposit fiat using [Create Fiat Deposit Instructions][create-fiat-deposit-instructions].
- Send a wire (SWIFT, Fedwire) or CUBIX transfer to Paxos, referencing the `memo_id` provided in the deposit instructions.
- Check the status of the deposit using [List Transfers][list-transfers].
- View updated balances using [Get Profile Balance][get-profile-balance].
### ➊ Create Fiat Deposit Instructions
Get instructions from Paxos on how to deposit fiat using [Create Fiat Deposit Instructions][create-fiat-deposit-instructions].
:::info
- For wires, use `fiat_network` “WIRE”. Specify international (SWIFT) or US (Fedwire) by setting `routing_number_type`
to “ABA” (for Fedwire) or “SWIFT” (for SWIFT).
- For CUBIX, use `fiat_network` CUBIX. Do not use `routing_number_type`.
:::
Retrieve the `profile_id` and `identity_id` (optioinal) from your records. Use your omnibus `profile_id` and optionally your corporate `identity_id` created for you by Paxos.
Create deposit instructions for international wires. Include the following body parameters in the request:
```shell
curl --location 'https://api.sandbox.paxos.com/v2/transfer/fiat-deposit-instructions' \
--request 'POST' \
--header 'Authorization: Bearer {access_token}' \
--data '{
//highlight-next-line
"profile_id": "5fc6d191-193c-4e28-94fa-656bbdbdfaad",
"fiat_network": "WIRE",
//highlight-next-line
"identity_id": "8a398cb6-4e3b-4868-9cea-a1c567856e68", // Optional.
"ref_id": "idempotence_id",
"routing_number_type": "SWIFT",
"metadata": {
"my_id": "4024ee50-eefb-4f2e-85c7-e7899c0b7da5"
}
}'
```
Upon successful request, the acknowledgment response confirms your request has been received.
```json
{
"id": "f190b163-208f-4d73-8deb-4fb8b24add00",
"profile_id": "5fc6d191-193c-4e28-94fa-656bbdbdfaad",
"identity_id": "8a398cb6-4e3b-4868-9cea-a1c567856e68", // Optional.
"created_at": "2024-01-28T04:23:11.738801Z",
"ref_id": "idempotence_id",
"status": "VALID",
// highlight-next-line
"memo_id": "9CFXQSCMSPLFHXLZ",
"fiat_network_instructions": {
"wire": {
"account_number": "7339119",
"fiat_account_owner_address": {
"country": "US",
"address1": "450 Lexington Ave. #3952",
"city": "New York",
"province": "NY",
"zip_code": "10163"
},
"routing_details": {
"routing_number_type": "SWIFT",
"routing_number": "031302971",
"bank_name": "Customers Bank",
"bank_address": {
"country": "USA",
"address1": "701 Reading Avenue",
"city": "West Reading",
"province": "PA",
"zip_code": "19611"
}
}
},
"fiat_account_owner": {
"institution_details": {
"name": "Paxos Trust Company, LLC"
}
},
"metadata": {
"my_id": "4024ee50-eefb-4f2e-85c7-e7899c0b7da5"
}
}
}
```
You will need the `memo_id` from the response on the next step in order to fund the Profile.
Retrieve the user’s `profile_id`, `identity_id` and `account_id` from your records.
Create deposit instructions for international wires (SWIFT) for end user funding.
Include the following body parameters in the request:
```shell
curl --location 'https://api.sandbox.paxos.com/v2/transfer/fiat-deposit-instructions' \
--request 'POST' \
--header 'Authorization: Bearer {access_token}' \
--data '{
"profile_id": "5fc6d191-193c-4e28-94fa-656bbdbdfaad",
"fiat_network": "WIRE",
"identity_id": "8a398cb6-4e3b-4868-9cea-a1c567856e68",
"account_id": "91f91384-30d4-46c2-9118-7f3cec676a2c",
"ref_id": "idempotence_id",
"routing_number_type": "SWIFT",
"metadata":
{
"my_id": "4024ee50-eefb-4f2e-85c7-e7899c0b7da5"
}
}'
```
Upon successful request, the acknowledgment response confirms your request has been received.
```json
{
"id": "f190b163-208f-4d73-8deb-4fb8b24add00",
"profile_id": "5fc6d191-193c-4e28-94fa-656bbdbdfaad",
"identity_id": "8a398cb6-4e3b-4868-9cea-a1c567856e68",
"account_id": "91f91384-30d4-46c2-9118-7f3cec676a2c",
"created_at": "2024-01-28T04:23:11.738801Z",
"ref_id": "idempotence_id",
"status": "VALID",
"memo_id": "9CFXQSCMSPLFHXLY",
"fiat_network_instructions": {
"wire": {
"account_number": "7339119",
"fiat_account_owner_address": {
"country": "US",
"address1": "450 Lexington Ave. #3952",
"city": "New York",
"province": "NY",
"zip_code": "10163"
},
"routing_details": {
"routing_number_type": "SWIFT",
"routing_number": "031302971",
"bank_name": "Customers Bank",
"bank_address": {
"country": "USA",
"address1": "701 Reading Avenue",
"city": "West Reading",
"province": "PA",
"zip_code": "19611"
}
}
},
"fiat_account_owner": {
"institution_details": {
"name": "Paxos Trust Company, LLC"
}
},
"metadata": {
"my_id": "4024ee50-eefb-4f2e-85c7-e7899c0b7da5"
}
}
}
```
You will need the `memo_id` from the response to fund the Profile.
### ➋ Send Fiat to Paxos
Send a wire (SWIFT, Fedwire) or CUBIX transfer to Paxos, referencing the `memo_id` to fund your Profile.
For Sandbox environment emulate the wire deposit using [Initiate Sandbox Fiat Deposit][initiate-sandbox-fiat-deposit].
```shell
curl --location 'https://api.sandbox.paxos.com/v2/sandbox/fiat-deposits' \
--request 'POST' \
--header 'Authorization: Bearer {access_token}' \
--data '{
"amount": "150.33",
"asset": "USD",
"memo_id": "9CFXQSCMSPLFHXLZ",
"fiat_network_instructions": {
"wire": {
"account_number": "1234567",
"fiat_account_owner_address": {
"country": "US",
"address1": "456 Main Street",
"city": "New York",
"province": "NY",
"zip_code": "10101"
},
"routing_details": {
"routing_number_type": "SWIFT",
"routing_number": "031302971",
"bank_name": "Customers Bank",
"bank_address": {
"country": "USA",
"address1": "123 Bank Street",
"city": "New York",
"province": "NY",
"zip_code": "10101"
}
}
}
},
"fiat_account_owner": {
"institution_details": {
"name": "Paxos Trust Company, LLC"
}
}
}'
```
You should get an empty response with `200` status code.
It can take a minute to process the deposit on the backend.
:::note
In production, send a real wire (SWIFT, Fedwire) or CUBIX transfer to Paxos, referencing the production `memo_id` (not sandbox) to fund your Profile.
:::
### ➌ Check Status of Deposit
Find the deposit using [List Transfers][list-transfers].
Include the `profile_id` query parameter to filter out transfers to all other Profiles.
```shell
curl --location 'https://api.sandbox.paxos.com/v2/transfer/transfers?order=DESC&type=WIRE_DEPOSIT&limit=2&profile_ids=5fc6d191-193c-4e28-94fa-656bbdbdfaad&limit=1' \
--request 'GET' \
--header 'Authorization: Bearer {access_token}'
```
Response:
```json
{ "items": [
{ "account_id": "91f91384-30d4-46c2-9118-7f3cec676a2c",
"amount": "150.33",
"asset": "USD",
"auto_conversion": {},
"balance_asset": "USD",
"created_at": "2024-01-28T00:48:00.222744Z",
"customer_id": "4eaffe58-df0e-4559-8dec-fdae231684e9",
"direction": "CREDIT",
"fee": "30",
"id": "cca46bf3-2dab-4ab5-a4f1-7b1b75956a29",
"identity_id": "8a398cb6-4e3b-4868-9cea-a1c567856e68",
"profile_id": "5fc6d191-193c-4e28-94fa-656bbdbdfaad",
"status": "COMPLETED",
"total": "120.33",
"type": "WIRE_DEPOSIT",
"updated_at": "2024-01-28T00:48:00.332602Z"
}
],
"next_page_cursor": "TAISDAiA-9qtBhCQtcyeARjCwa8M"
}
```
Include the `identity_id` query parameter to filter out transfers to all other Identities.
```shell
curl --location 'https://api.sandbox.paxos.com/v2/transfer/transfers?order=DESC&type=WIRE_DEPOSIT&identity_ids=8a398cb6-4e3b-4868-9cea-a1c567856e68&limit=1' \
--request 'GET' \
--header 'Authorization: Bearer {access_token}'
```
Response:
```json
{ "items": [
{ "account_id": "91f91384-30d4-46c2-9118-7f3cec676a2c",
"amount": "150.33",
"asset": "USD",
"auto_conversion": {},
"balance_asset": "USD",
"created_at": "2024-01-28T00:48:00.222744Z",
"customer_id": "4eaffe58-df0e-4559-8dec-fdae231684e9",
"direction": "CREDIT",
"fee": "30",
"id": "cca46bf3-2dab-4ab5-a4f1-7b1b75956a29",
"identity_id": "8a398cb6-4e3b-4868-9cea-a1c567856e68",
"profile_id": "5fc6d191-193c-4e28-94fa-656bbdbdfaad",
"status": "COMPLETED",
"total": "120.33",
"type": "WIRE_DEPOSIT",
"updated_at": "2024-01-28T00:48:00.332602Z"
}
],
"next_page_cursor": "TAISDAiA-9qtBhCQtcyeARjCwa8Q"
}
```
### ➍ View Updated Balances
View updated balances using [Get Profile Balance][get-profile-balance].
```shell
curl --location 'https://api.sandbox.paxos.com/v2/profiles/5fc6d191-193c-4e28-94fa-656bbdbdfaad/balances/USD' \
--request 'GET' \
--header 'Authorization: Bearer {access_token}'
```
Response:
```json
{
"asset": "USD",
"available": "120.33",
"trading": "0"
}
```
## Withdrawal Flow {#withdrawal}
We'll be following the recommended fiat withdrawal workflow:
- [Authenticate in Sandbox](#authenticate).
- Save your external bank account information on Paxos using [Create Fiat Account][create-fiat-account]. If needed, you can update bank account information using [Update Fiat Account][update-fiat-account].
- Confirm sufficient funds in the associated Profile to process the withdrawal using [Get Profile Balance][get-profile-balance].
- Retrieve the ID for your external bank account using [List Fiat Accounts][list-fiat-accounts].
- Initiate a fiat withdrawal from Paxos into your external bank account using [Create Fiat Withdrawal][create-fiat-withdrawal].
- Check the status of the withdrawal using [List Transfers][list-transfers].
- View updated balances using [Get Profile Balance][get-profile-balance].
### ➊ Create Fiat Account
Save your external bank account information on Paxos using [Create Fiat Account][create-fiat-account].
:::note
For CUBIX, the `wallet_address` on `fiat_network_instructions` is not a crypto wallet address, it is a Customers Bank
account wallet address.
:::
Include the following body parameters in your request to create fiat accounts for US domestic wires:
```shell
curl --location 'https://api.sandbox.paxos.com/v2/transfer/fiat-accounts' \
--request 'POST' \
--header 'Authorization: Bearer {access_token}' \
--data '{
"ref_id": "idempotence_id",
"identity_id": "8a398cb6-4e3b-4868-9cea-a1c567856e68", // Optional.
"fiat_account_owner": {
"institution_details": {
"name": "Company"
}
},
"fiat_network_instructions": {
"wire": {
"account_number": "74600021314512",
"fiat_account_owner_address": {
"country": "USA",
"address1": "456 Main Street, NY",
"city": "New York",
"province": "NY",
"zip_code": "10101"
},
"routing_details": {
"routing_number_type": "ABA",
"routing_number": "031302971",
"bank_name": "Customers Bank",
"bank_address": {
"country": "USA",
"address1": "123 Bank Street",
"city": "New York",
"province": "NY",
"zip_code": "10101"
}
}
}
},
"metadata": {
"test_ref_id": "47aa7538-e2d2-47b3-8600-44a7965dd357",
"key_2": "2"
}
}'
```
Upon successful request, the acknowledgment response confirms your request has been received.
```json
{
// highlight-next-line
"id": "cc1b6606-a8a3-4a8f-8b9b-5456d96448bf",
"ref_id": "idempotence_id",
"identity_id": "8a398cb6-4e3b-4868-9cea-a1c567856e68", // Optional.
"fiat_account_owner": {
"person_details": {
"name": "Company"
},
"fiat_network_instructions": {
"wire": {
"account_number": "74600021314512",
"fiat_account_owner_address": {
"country": "USA",
"address1": "456 Main Street, NY",
"city": "New York",
"province": "NY",
"zip_code": "10101"
},
"routing_details": {
"routing_number_type": "ABA",
"routing_number": "031302971",
"bank_name": "Customers Bank",
"bank_address": {
"country": "USA",
"address1": "123 Bank Street",
"city": "New York",
"province": "NY",
"zip_code": "10101"
}
}
}
}
},
// highlight-next-line
"status": "PENDING",
"metadata": {
"test_ref_id": "47aa7538-e2d2-47b3-8600-44a7965dd357",
"key_2": "2"
},
"created_at": "2024-01-28T22:14:25.731494Z"
}
```
Note the `id` in the response, it will be required to check the Account status in the next steps.
Include the following body parameters in your request to create fiat accounts for SWIFT (international) wires:
```shell
curl --location 'https://api.sandbox.paxos.com/v2/transfer/fiat-accounts' \
--request 'POST' \
--header 'Authorization: Bearer {access_token}' \
--data '{
"ref_id": "idempotence_id",
"identity_id": "8a398cb6-4e3b-4868-9cea-a1c567856e68",
"account_id": "91f91384-30d4-46c2-9118-7f3cec676a2c",
"fiat_account_owner": {
"person_details": {
"first_name": "Megan",
"last_name": "Snow"
}
},
"fiat_network_instructions": {
"wire": {
"account_number": "74600021314512",
"fiat_account_owner_address": {
"country": "USA",
"address1": "2600 Tully St",
"city": "Washington",
"province": "DC",
"zip_code": "10010"
},
"routing_details": {
"routing_number_type": "SWIFT",
"routing_number": "JINABVU1773",
"bank_name": "First Bank",
"bank_address": {
"country": "Brazil",
"address1": "Awesome ct",
"city": "Sao Paulo",
"province": "Sao Paulo",
"zip_code": "33445"
}
},
"intermediary_routing_details": {
"routing_number_type": "ABA",
"routing_number": "123456789",
"bank_name": "Ubium Bank",
"bank_address": {
"country": "USA",
"address1": "Great str",
"city": "Walnut Creek",
"province": "CA",
"zip_code": "59610"
}
}
}
},
"metadata": {
"key_1": "1",
"key_2": "two"
}
}'
```
Upon successful request, the acknowledgment response confirms your request has been received.
```json
{
// highlight-next-line
"id": "cc1b6606-a8a3-4a8f-8b9b-5456d96448bf",
"ref_id": "idempotence_id",
"identity_id": "8f22e593-5f51-40cc-8bb0-5245d051c1da",
"account_id": "38fc5a41-12a5-43f4-a2de-4733dcd1dee6",
"fiat_account_owner": {
"person_details": {
"first_name": "Megan",
"last_name": "Snow"
}
},
"fiat_network_instructions": {
"wire": {
"account_number": "XXXXXXXXXX4512",
"fiat_account_owner_address": {
"country": "USA",
"address1": "2600 Tully St",
"city": "Washington",
"province": "DC",
"zip_code": "10010"
},
"routing_details": {
"routing_number_type": "SWIFT",
"routing_number": "JINABVU1773",
"bank_name": "First Bank",
"bank_address": {
"country": "Brazil",
"address1": "Awesome ct",
"city": "Sao Paulo",
"province": "Sao Paulo",
"zip_code": "33445"
}
},
"intermediary_routing_details": {
"routing_number_type": "ABA",
"routing_number": "123456789",
"bank_name": "Ubium Bank",
"bank_address": {
"country": "USA",
"address1": "Great str",
"city": "Walnut Creek",
"province": "CA",
"zip_code": "59610"
}
}
}
},
// highlight-next-line
"status": "PENDING",
"metadata": {
"key_1": "1",
"key_2": "two"
},
"created_at": "2024-03-13T00:50:08.902618Z"
}
```
Note the `id` in the response, it will be required to check the Account status in the next steps.
### ➋ Confirm Sufficient Funds
Confirm sufficient funds in the profile to process the withdrawal using [Get Profile Balance][get-profile-balance].
```shell
curl --location 'https://api.sandbox.paxos.com/v2/profiles/5fc6d191-193c-4e28-94fa-656bbdbdfaad/balances/USD' \
--request 'GET' \
--header 'Authorization: Bearer {access_token}'
```
Response:
```json
{
"asset": "USD",
"available": "120.33",
"trading": "0"
}
```
### ➌ Retrieve Bank Account Status
Retrieve the status of your external bank account using [Get Fiat Account][get-fiat-account] and providing the `id`
from the [Create Fiat Account][create-fiat-account] response.
:::info
There are three statuses for Fiat Accounts: `"PENDING"`, `"APPROVED"`, `"REJECTED"`. While on `"PENDING"`, Paxos is
processing your fiat account. Fiat Account status needs to be `"APPROVED"` before Fiat Account can be used for withdrawals.
:::
Request:
```shell
curl --request 'GET' --location 'https://api.sandbox.paxos.com/v2/transfer/fiat-accounts/cc1b6606-a8a3-4a8f-8b9b-5456d96448bf'
```
Response:
```json
{
"account_id": "91f91384-30d4-46c2-9118-7f3cec676a2c",
"created_at": "2024-01-28T22:14:25.731494Z",
"fiat_account_owner": {
"person_details": {
"name": "Company"
}
},
"fiat_network_instructions": {
"wire": {
"account_number": "74600021314512",
"fiat_account_owner_address": {
"country": "USA",
"address1": "456 Main Street, NY",
"city": "New York",
"province": "NY",
"address2": "",
"zip_code": "10101"
},
"routing_details": {
"routing_number_type": "ABA",
"routing_number": "031302971",
"bank_name": "Customers Bank",
"bank_address": {
"country": "USA",
"address1": "123 Bank Street",
"city": "New York",
"province": "NY",
"zip_code": "10101"
}
}
}
},
"id": "cc1b6606-a8a3-4a8f-8b9b-5456d96448bf",
"identity_id": "8a398cb6-4e3b-4868-9cea-a1c567856e68",
"ref_id": "idempotence_id",
// highlight-next-line
"status": "APPROVED",
"metadata": {
"test_ref_id": "47aa7538-e2d2-47b3-8600-44a7965dd357",
"key_2": "2"
}
}
```
From the response find the `id` of the bank record for the user. It must be in `APPROVED` status.
### ➍ Create Fiat Withdrawal
Initiate a fiat withdrawal from Paxos into your external bank account using [Create Fiat Withdrawal][create-fiat-withdrawal].
Initiate a CUBIX withdrawal. Specify the `fiat_account_id` of the Fiat Account from the [Create Fiat Account][create-fiat-account] response.
```shell
curl --location 'https://api.sandbox.paxos.com/v2/transfer/fiat-withdrawals' \
--request 'POST' \
--header 'Authorization: Bearer {access_token}' \
--data '{
"ref_id": "idempotence_id",
"amount": "120",
"asset": "USD",
// highlight-next-line
"fiat_account_id": "cc1b6606-a8a3-4a8f-8b9b-5456d96448bf",
"profile_id": "5fc6d191-193c-4e28-94fa-656bbdbdfaad",
"identity_id": "8a398cb6-4e3b-4868-9cea-a1c567856e68", // Optional.
"metadata": {
"custom_key": "custom_value"
}
}'
```
Response:
```json
{
"amount": "100",
"asset": "USD",
"auto_conversion": {},
"balance_asset": "USD",
"created_at": "2024-01-28T22:39:02.279268Z",
"customer_id": "4eaffe58-df0e-4559-8dec-fdae231684e1",
"direction": "DEBIT",
"fee": "20",
"fiat_account_id": "cc1b6606-a8a3-4a8f-8b9b-5456d96448bf",
"id": "11a6f6e9-4219-4698-9d79-abfc1e346246",
"identity_id": "8a398cb6-4e3b-4868-9cea-a1c567856e68", // Optional.
"metadata": {
"custom_key": "custom_value"
},
"profile_id": "5fc6d191-193c-4e28-94fa-656bbdbdfaad",
"ref_id": "idempotence_id",
"status": "PENDING",
"total": "120",
"type": "CUBIX_WITHDRAWAL",
"updated_at": "2024-01-28T22:39:02.279268Z"
}
```
Initiate an international wire withdrawal (SWIFT). Specify the `fiat_account_id` from the [Create Fiat Account][create-fiat-account] response.
```shell
curl --location 'https://api.sandbox.paxos.com/v2/transfer/fiat-withdrawals' \
--request 'POST' \
--header 'Authorization: Bearer {access_token}' \
--data '{
"ref_id": "idempotence_id",
"amount": "120",
"asset": "USD",
// highlight-next-line
"fiat_account_id": "cc1b6606-a8a3-4a8f-8b9b-5456d96448bf",
"profile_id": "5fc6d191-193c-4e28-94fa-656bbdbdfaad",
"identity_id": "8a398cb6-4e3b-4868-9cea-a1c567856e68",
"account_id": "91f91384-30d4-46c2-9118-7f3cec676a2c",
"metadata": {
"custom_key": "custom_value"
}
}'
```
Response:
```json
{
"account_id": "91f91384-30d4-46c2-9118-7f3cec676a2c",
"amount": "100",
"asset": "USD",
"auto_conversion": {},
"balance_asset": "USD",
"created_at": "2024-01-28T22:39:02.279268Z",
"customer_id": "4eaffe58-df0e-4559-8dec-fdae231684e1",
"direction": "DEBIT",
"fee": "20",
"fiat_account_id": "cc1b6606-a8a3-4a8f-8b9b-5456d96448bf",
"id": "11a6f6e9-4219-4698-9d79-abfc1e346246",
"identity_id": "8a398cb6-4e3b-4868-9cea-a1c567856e68",
"metadata": {
"custom_key": "custom_value"
},
"profile_id": "5fc6d191-193c-4e28-94fa-656bbdbdfaad",
"ref_id": "idempotence_id",
"status": "PENDING",
"total": "120",
"type": "WIRE_WITHDRAWAL",
"updated_at": "2024-01-28T22:39:02.279268Z"
}
```
:::tip
It is recommended to have [JWS request signing][jws-request-signing] for Fiat Withdrawals.
JWS request signing uses a public-key cryptography with a client-controlled private key.
It adds an additional layer of security to withdrawals.
It can prevent malicious withdrawals even if the API key is compromised.
When used, all API calls with this key will require a JWS signature.
:::
### ➎ Check Status of Withdrawal
Check the status of the withdrawal using [Get Transfer][get-transfer] with the `id` from the previous step.
```shell
curl --location 'https://api.sandbox.paxos.com/v2/transfer/transfers/11a6f6e9-4219-4698-9d79-abfc1e346246' \
--request 'GET' \
--header 'Authorization: Bearer {access_token}'
```
Response:
```json
{ "account_id": "91f91384-30d4-46c2-9118-7f3cec676a2c",
"amount": "100",
"asset": "USD",
"auto_conversion": {},
"balance_asset": "USD",
"created_at": "2024-01-28T22:39:02.279268Z",
"customer_id": "4eaffe58-df0e-4559-8dec-fdae231684e1",
"direction": "DEBIT",
"fee": "20",
"fiat_account_id": "cc1b6606-a8a3-4a8f-8b9b-5456d96448bf",
"id": "11a6f6e9-4219-4698-9d79-abfc1e346246",
"identity_id": "8a398cb6-4e3b-4868-9cea-a1c567856e68",
"metadata": {
"custom_key": "custom_value"
},
"profile_id": "5fc6d191-193c-4e28-94fa-656bbdbdfaad",
"ref_id": "idempotence_id",
// highlight-next-line
"status": "COMPLETE",
"total": "120",
"type": "WIRE_WITHDRAWAL",
"updated_at": "2024-01-28T22:39:05.613881Z"}
```
### ➏ View Updated Balances
View updated balances using [Get Profile Balance][get-profile-balance] and passing the `profile_id` and `USD` asset in the endpoint's path.
```shell
curl --location 'https://api.sandbox.paxos.com/v2/profiles/5fc6d191-193c-4e28-94fa-656bbdbdfaad/balances/USD \'
--request 'GET' \
--header 'Authorization: Bearer {access_token}'
```
Response:
```json
{
"asset": "USD",
"available": "0.33",
"trading": "0"
}
```
----------------------------------------
## API Breaking Change Policy
Description: Learn about what qualifies as a breaking change and the what happens when one is necessary.
Path: developer/breaking-change/policy.mdx
[Changelog]: /changelog
The policy below applies only to Partners with a fully executed and active SLA.
Paxos will make commercially reasonable efforts to notify users without a service agreement of breaking changes.
:::note
See the [Changelog] for current breaking changes.
:::
## Definitions
**"Core Platform Services”** means the services provided by Paxos that enable End Users to (i) onboard onto the Paxos platform (if applicable given the integration utilized by the Customer) and (ii) submit and execute Orders to buy and sell certain Cryptocurrency Assets from or to other individuals via the Exchange Platform or Paxos' liquidity providers using U.S. dollars or other Cryptocurrency Assets, and (iii) transfer Cryptocurrency Assets to and from the Exchange Platform.
The Core Platform Services include (a) market and order data streams provided via websockets, (b) the Paxos FIX Service (if applicable given the API integration utilized by the Customer), (c) Reconciliation Reports and (d) the following v2 REST API services: Profiles, Markets, Orders, Quotes, Quote Executions, Pricing, Identity, Transfers and Accounts.
For the avoidance of doubt, any service designated as a "Preview, “Beta” or “Alpha” in Paxos's API documentation is not included as part of the Core Platform Services.
**“Exchange Platform”** means Paxos' cryptocurrency exchange platform and services whereby individuals can buy or sell certain Cryptocurrency Assets from or to other individuals or liquidity providers using U.S. dollars or other Cryptocurrency Assets.
**“Paxos FIX Service”** means the Paxos service that allows Customer to send messages to and receive messages from the Exchange Platform using the FIX protocol.
## Breaking Changes
In the normal course of business, Paxos may need to make changes that will require Customer to adjust its integration with Paxos (**“Breaking Changes”**). When Paxos makes a Breaking Change to the Core Platform Services, Exchange Platform, or FIX Service, Paxos will ensure the previous functionality remains available to Customer for at least ninety (90) days to provide Customer time to make necessary changes.
When Paxos makes a Breaking Change to Reconciliation Reports, Paxos will either allow Customer to immediately opt-in to the new version, or provide Customer with both the new and old version of the Reconciliation Reports for at least ninety (90) days (the **“Change Policy”**).
## Breaking Change Notifications
When Paxos makes a Breaking Change to the Core Platform Services or FIX Service, Paxos will issue a Breaking Change notification.
Such notification will be sent at least ninety (90) days ahead of the change to all registered Customer Service Contacts via email and include **“Breaking Change Notification”** in the subject.
## Types of Breaking Changes
For reference, the following changes qualify as examples of Breaking Changes:
- Removing or renaming an API service.
- Removal of a field or enumerated value from an API response.
- Removing or renaming a column in the Reconciliation Reports.
- Change of a request field or parameter from non-mandatory to mandatory.
- Change of a field or parameter name.
- Addition of new validation rules to a field, resulting in previously accepted requests being rejected.
- Modification of the data type of a field (for example, converting a single object to a list of objects).
This list is non-exhaustive and Paxos may identify additional Breaking Changes in its discretion.
## Backwards Compatible Changes
Backwards compatible changes are any changes that (i) are not explicitly identified by Paxos as Breaking Changes, (ii) do not materially reduce any functionality with respect to the Core Platform Services and (iii) do not materially change the schema or query parameters with respect to the Core Platform Services (collectively, **“Backwards Compatible Changes”**).
All users of Paxos APIs should expect and manage identified Backwards Compatible Changes without error.
For reference, the following changes are considered Backwards Compatible Changes:
- Addition of a new API service.
- Addition of a method to an API service.
- Addition of a new non-mandatory field, parameter, or header to an API request or response.
- Changing the length or format of a field identified as a string in the API reference documentation.
- Addition of new enumerated values, including but not limited to status codes or error codes.
- Changes to error messages.
- Addition of a new report to the Reconciliation Reports.
- Addition of a new column to the Reconciliation Reports.
- Modification of the order of columns to the Reconciliation Reports.
- Deprecation of a field in a request or response without removing it.
- Change in order of fields in an object, or objects in an array.
- Addition of a new FIX tag.
This list is non-exhaustive and Paxos may identify additional Backwards Compatible Changes in its discretion.
## End of Life
If Paxos decides to entirely remove or no longer support a Core Platform Service, Paxos will provide Customer Service Contacts with an **“End of Life”** notification at least ninety (90) days in advance of the change.
## Exceptions
This policy only applies to services listed as Core Platform Services.
Paxos will use commercially reasonable efforts to provide advance notice of changes to other services over email to all Customer Service Contacts.
## Required Changes
Paxos may make breaking changes without notice in order to fix material defects or to comply with legal obligations.
In addition, Paxos may throttle requests or disable access to any or all components of the Core Platform Services if Paxos determines that a Customer's usage of the service poses a risk to the stability of the platform.
In the case where Paxos manually throttles requests or disables access, Paxos will immediately notify all registered Customer Service Contacts within forty-five (45) minutes of taking such action.
----------------------------------------
================================================================================
SECTION: API
================================================================================
## Migrate from v1 to v2 API
Description: Learn how to migrate your REST integrations.
Tags: Developer Guide
Path: api/migrate.mdx
[v1]: https://developer.paxos.com/docs/#paxos-api
[v2]: /api/v2
[sandbox]: https://dashboard.sandbox.paxos.com/
[guide]: developer/credentials.mdx
[oauth]: https://oauth.net/2/
[authentication]: /api/v2#section/Authentication
[get-activities]: https://developer.paxos.com/docs/#getactivities
[get-activity]: https://developer.paxos.com/docs/#getactivity
[list-transfers]: /api/v2#tag/Transfers/operation/ListTransfers
[list-auto-conversions]: https://developer.paxos.com/docs/#listautoconversions
[get-transfer]: /api/v2#tag/Transfers/operation/GetTransfer
[list-bank-accounts]: https://developer.paxos.com/docs/#listbankaccounts
[list-fiat-accounts]: /api/v2#tag/Fiat-Transfers/operation/ListFiatAccounts
[create-bank-account]: https://developer.paxos.com/docs/#createbankaccount
[create-fiat-account]: /api/v2#tag/Fiat-Transfers/operation/CreateFiatAccount
[GetBankAccount]: https://developer.paxos.com/docs/#getbankaccount
[get-fiat-account]: /api/v2#tag/Fiat-Transfers/operation/GetFiatAccount
[ArchiveBankAccount]: https://developer.paxos.com/docs/#archivebankaccount
[delete-fiat-account]: /api/v2#tag/Fiat-Transfers/operation/DeleteFiatAccount
[CreateCbitWithdrawal]: https://developer.paxos.com/docs/#createcbitwithdrawal
[create-fiat-withdrawal]: /api/v2#tag/Fiat-Transfers/operation/CreateFiatWithdrawal
[ListProfiles]: https://developer.paxos.com/docs/#listprofiles
[list-profiles]: /api/v2#tag/Profiles/operation/ListProfiles
[GetProfile]: https://developer.paxos.com/docs/#getprofile
[get-profile]: /api/v2#tag/Profiles/operation/GetProfile
[GetProfileBalances]: https://developer.paxos.com/docs/#getprofilebalances
[list-profile-balances]: /api/v2#tag/Profiles/operation/ListProfileBalances
[GetProfileDepositInstructions]: https://developer.paxos.com/docs/#getprofiledepositinstructions
[create-deposit-address]: /api/v2#tag/Deposit-Addresses/operation/CreateDepositAddress
[create-fiat-deposit-instructions]: /api/v2#tag/Fiat-Transfers/operation/CreateFiatDepositInstructions
[CreateProfileTransfer]: https://developer.paxos.com/docs/#createprofiletransfer
[create-internal-transfer]: /api/v2#tag/Internal-Transfers/operation/CreateInternalTransfer
[CreateWireWithdrawal]: https://developer.paxos.com/docs/#createwirewithdrawal
[GetCustStatus]: https://developer.paxos.com/docs/#getcuststatus
[get-identity]: /api/v2#tag/Identity/operation/GetIdentity
[ListCryptoAddresses]: https://developer.paxos.com/docs/#listcryptoaddresses
[CreatePeerTransfer]: https://developer.paxos.com/docs/#createpeertransfer
[CreateCryptoWithdrawal]: https://developer.paxos.com/docs/#createcryptowithdrawal
[create-crypto-withdrawal]: /api/v2#tag/Crypto-Withdrawals/operation/CreateCryptoWithdrawal
[create-paxos-transfer]: /api/v2#tag/Paxos-Transfers/operation/CreatePaxosTransfer
The Paxos v1 APIs have reached End of Life.
Access to all Paxos v1 APIs has been removed.
This change ensures all Paxos customers are using supported APIs.
Customers should migrate remaining usage from the v1 API as all functionality is now available in [Paxos v2 APIs][v2].
We recommend you test your integrations in Sandbox before applying the changes to your integration in Production.
To help with the transition, this guide provides suggestions on implementing similar functionality using the Paxos REST API (v2).
## Get Started in Sandbox
We recommend you test your integration in the Sandbox environment prior to deploying the changes in production.
If not already done so, [sign up for a Sandbox account][sandbox].
Then [configure API credentials][guide].
| v1 API Endpoint | v2 API Endpoint |
| --- | --- |
| GetActivities | [List Transfers][list-transfers] |
| GetActivity | [Get Transfer][get-transfer] |
| ListAutoConversions | [List Transfers][list-transfers] |
| ListBankAccounts | [List Fiat Accounts][list-fiat-accounts] |
| CreateBankAccount | [Create Fiat Account][create-fiat-account] |
| GetBankAccount | [Get Fiat Account][get-fiat-account] |
| ArchiveBankAccount | [Delete Fiat Account][delete-fiat-account] |
| CreateCbitWithdrawalCBIT is no longer supported. [Use CUBIX](https://support.paxos.com/hc/en-us/articles/31700769434004) instead. | [Create Fiat Withdrawal][create-fiat-withdrawal] |
| CreateCryptoWithdrawal | [Create Crypto Withdrawal][create-crypto-withdrawal] |
| ListProfiles | [List Profiles][list-profiles] |
| GetProfile | [Get Profile][get-profile] |
| GetProfileBalances | [List Profile Balances][list-profile-balances] |
| GetProfileDepositInstructions | [Create Deposit Address][create-deposit-address] and[Create Fiat Deposit Instructions][create-fiat-deposit-instructions] |
| CreateProfileTransfer | [Create Internal Transfer][create-internal-transfer] |
| CreateWireWithdrawal | [Create Fiat Withdrawal][create-fiat-withdrawal] |
| GetCustStatus | [Get Identity][get-identity] |
| CreatePeerTransfer | [Create Paxos Transfer][create-paxos-transfer] |
## Removed Endpoints {#removed}
The following APIs have been removed as there is no current v2 use case for them.
- ArchiveProfile
- GetCryptoAddress
- CreateCryptoAddress
- CreateSenWithdrawal
- CreateSignetWithdrawal
- CreateIntrabankWithdrawal
- GetBankAccountAutoConversionInstructions
- GetCryptoAddressAutoConversionInstructions
- UpdateCryptoDeposit
- RejectCryptoDeposit
----------------------------------------
## WebSocket API Reference
Description: Event-driven connectivity for payments and trading.
Tags: Crypto Brokerage, Trading, WebSocket
Path: api/websocket.mdx
[quickstart]: crypto-brokerage/websocket.mdx
[market-data]: api/websocket.mdx#market-data-feed
[execution-data]: api/websocket.mdx#execution-data-feed
[market-data-path-parameter]: api/websocket.mdx#market-data-path-parameter
[execution-data-path-parameter]: api/websocket.mdx#execution-data-path-parameter
[available-markets]: api/websocket.mdx#available-markets
[websocket]: https://websocket.spec.whatwg.org
[get-order-book]: api/v2#tag/Market-Data/operation/GetOrderBook
[list-recent-executions]: api/v2#tag/Market-Data/operation/ListRecentExecutions
[rate-limits]: developer/rate-limits.mdx#websocket-limits
[v2-api]: api/v2
[payments-guide]: payments/websocket.mdx
[stablecoin-data]: #stablecoin-feed
Paxos provides secure, real-time market and execution data feeds via public [WebSocket][websocket] connections
The [Stablecoin Market Price Feed][stablecoin-data] streams event-driven updates for the market index price for external stablecoins.
The [Market Data Feed][market-data] streams event-driven updates for the entire order book or for a single market.
The [Execution Data Feed][execution-data] streams event information for all markets or for a single market.
> See the Websocket [trading][quickstart] and [stablecoin payments][payments-guide] guides for a hands-on introduction.
The WebSocket connections provide a number of advantages when compared to the [v2 API][v2-api], including real-time event notifications, minimized data transfers over the network and reduced latency when compared to a polling strategy.
## Connection Details {#connection-details}
Once a secure (`wss://`) connection is established, each feed begins streaming data, subject to the [rate limits][rate-limits].
Both Production and Sandbox data feeds have a built-in, instantaneous failover.
Clients should have a reconnection mechanism in case of server disconnection.
### Sandbox Data Feeds {#sandbox-data-feeds}
```shell
wss://ws.sandbox.paxos.com/executiondata
wss://ws.sandbox.paxos.com/executiondata/{market}
wss://ws.sandbox.paxos.com/marketdata
wss://ws.sandbox.paxos.com/marketdata/{market}
wss://ws.sandbox.paxos.com/marketdata/stablecoin/{market}
```
### Production Data Feeds {#production-data-feeds}
```shell
wss://ws.paxos.com/executiondata
wss://ws.paxos.com/executiondata/{market}
wss://ws.paxos.com/marketdata
wss://ws.paxos.com/marketdata/{market}
wss://ws.paxos.com/marketdata/stablecoin/{market}
```
## Execution Data Feed
Upon secure (`wss://`) connection, you will start to receive messages for each market execution (based on the use of the market parameter).
The first message corresponds to the last execution for the market at the point of the connection.
After that, each new message represents a new execution.
If there are no executions for longer periods of time for a particular market upon connection you may not receive any message until a new execution is made.
> Upon reconnection you will receive the last execution for the market, in which case clients should handle duplicate messages. You may use a match number as an idempotent field.
### Execution Data Request
- Sandbox: `wss://ws.sandbox.paxos.com/executiondata`
- Production: `wss://ws.paxos.com/executiondata`
### Execution Data Path Parameter {#execution-data-path-parameter}
- Sandbox: `wss://ws.sandbox.paxos.com/executiondata/{market}`
- Production: `wss://ws.paxos.com/executiondata/{market}`
| Parameter | Required | Description|
| --- | --- | --- |
| `market` | No | Filter the data stream for a single market. For example, `BTCUSD` or another market from [available markets][available-markets]. |
### Execution Data Response
| Parameter | Required | Description|
| --- | --- | --- |
| `market` | Yes | One of the [available markets][available-markets] or the single market if the `market` [path parameter][execution-data-path-parameter] is specified. |
| `price` | Yes | The execution price. |
| `amount` | Yes | The execution amount. |
| `executed_at` | Yes | Timestamp of the execution. |
| `match_number` | Yes | Unique execution number. |
### Execution Data Example Response
Request URL: `wss://ws.sandbox.paxos.com/executiondata/BTCUSD`
```json
{
"market": "BTCUSD",
"price": "24228.75",
"amount": "0.00000412",
"executed_at": "2023-03-13T18:46:53.386Z",
"match_number": "6AJVAX7BTCH8"
}
...
```
## Market Data Feed
Once a secure (`wss://`) connection is established, the initial response message shows the state of the order book, including both bids and asks, in the `SNAPSHOT`.
Prices are in descending order for bids and ascending order for asks.
> When streaming data for all markets, differentiate the per-market updates using the `market` field.
### Available Markets {#available-markets}
The public feeds may contain inactive markets or markets unavailable for trading.
Availability varies depending on the environment.
For example, we may enable a market in the Sandbox environment for testing but not in Production.
Some Paxos accounts have additional trading restrictions in Production.
> [Get Order Book][get-order-book] retrieves a list of markets available for trading and [List Recent Executions][list-recent-executions] retrieve a list of all platform trades.
> However, these endpoints are not suitable for streaming order book and execution event data.
### Market Data Request
- Sandbox: `wss://ws.sandbox.paxos.com/marketdata`
- Production: `wss://ws.paxos.com/marketdata`
### Market Data Path Parameter {#market-data-path-parameter}
- Sandbox: `wss://ws.sandbox.paxos.com/marketdata/{market}`
- Production: `wss://ws.paxos.com/marketdata/{market}`
| Parameter | Required | Description|
| --- | --- | --- |
| `market` | No | Filter the data stream for a single market. For example, `BTCUSD` or another market from [available markets][available-markets]. |
### Market Data Initial Response
| Parameter | Required | Description |
| --- | --- | --- |
| `type` | Yes | The initial value of `SNAPSHOT` shows the state of the order book for both `bids` and `asks`. Subsequent messages show all executed trades, and other order book changes, in the `UPDATE` stream. |
| `market` | Yes | One of the [available markets][available-markets] or a single market if the `market` [path parameter][market-data-path-parameter] is specified. |
| `bids` | Yes | Includes `bids.price` in descending order and `bids.amount`. Each `price`-`amount` pair represents a level of the book. |
| `asks` | Yes | Includes `asks.price` in ascending order and `asks.amount`. Each `price`-`amount` pair represents a level of the book. |
| `final_snapshot` | Yes | Demarcates the end of the initial `SNAPSHOT`. Initial value always `true`. Subsequent messages in `UPDATE` format. |
### Market Data Update Response
When processing `UPDATE` messages observe the following rules:
- If `side=BUY` and `amount=0`, remove the existing entry with price `price` from the bids list.
- If `side=BUY` and an entry with price `price` already exists in the `bids` list, update the amount for the given entry in the `bids` list to `amount`.
- If `side=BUY` and no entry with price `price` exists in the `bids` list, add an entry with price `price` and amount `amount` to `bids` list.
- If `side=SELL`, apply the logic used as for `BUY` to the `asks` list.
| Parameter | Required | Description |
| --- | --- | --- |
| `type` | Yes | Value always `UPDATE`. Show all executed trades, and other order book changes, in the data stream. |
| `market` | Yes | One of the [available markets][available-markets] or the single market if the `market` [path parameter][market-data-path-parameter] is specified. |
| `side` | Yes | Value either `BUY` or `SELL`. Specifies the activity type. |
| `price` | Yes | The current price. |
| `amount` | Yes | The current amount. |
### Market Data Example Response
Request URL: `wss://ws.sandbox.paxos.com/marketdata/BTCUSD`
```json
{
"type": "SNAPSHOT",
"market": "BTCUSD",
"bids": [
{
"price": "19994.25",
"amount": "0.7755"
},
{
"price": "19993.75",
"amount": "0.83676985"
},
...
],
"asks": [
{
"price": "19994.5",
"amount": "0.97548541"
},
{
"price": "19996",
"amount": "1.135"
},
...
],
"final_snapshot": true
}
{
"type": "UPDATE",
"market": "BTCUSD",
"side": "BUY",
"price": "19958.5",
"amount": "0.62649999"
}
{
"type": "UPDATE",
"market": "BTCUSD",
"side": "SELL",
"price": "20115.25",
"amount": "0"
}
...
```
## Stablecoin Market Price Feed {#stablecoin-feed}
Once a secure (`wss://`) connection is established, the initial response message shows the market price.
The feed currently supports the USDCUSD market.
### Stablecoin Market Request
- **Sandbox**: `wss://ws.sandbox.paxos.com/marketdata/stablecoin`
- **Production**: `wss://ws.paxos.com/marketdata/stablecoin`
### Stablecoin Market Path Parameter
- **Sandbox**: `wss://ws.sandbox.paxos.com/marketdata/stablecoin/{market}`
- **Production**: `wss://ws.paxos.com/marketdata/stablecoin/{market}`
### Stablecoin Market Response
Price updates are pushed as they occur. The update frequency will typically be around 1 message per second, but may depend on market price volatility.
| Parameter | Required | Description|
| --- | --- | --- |
| `market` | Yes | One of the available markets or the single market if the market path parameter is specified.|
| `price` | Yes | The current price to 4 decimals. |
| `timestamp` | Yes | The time that the update occurred. |
### Stablecoin Market Example Response
Request URL: `wss://ws.sandbox.paxos.com/marketdata/stablecoin/USDCUSD`
```json
{"market":"USDCUSD","price":"1.0001","timestamp":"2024-11-04T18:11:09.042391267Z"}
{"market":"USDCUSD","price":"1.0001","timestamp":"2024-11-04T18:11:10.049787567Z"}
{"market":"USDCUSD","price":"1.0001","timestamp":"2024-11-04T18:11:11.042710464Z"}
...
```
----------------------------------------
================================================================================
SECTION: STABLECOIN
================================================================================
## Integrate with PYUSD on Ethereum
Description: The steps to integrate PYUSD on your platform are similar to executing smart contract functions for other ERC20 tokens.
Tags: PYUSD
Path: stablecoin/integrate-pyusd.mdx
[eip-20-standard]: https://github.com/ethereum/ercs/blob/master/ERCS/erc-20.md
A minimally viable implementation of PYUSD must:
- Allow the recipient to create an Ethereum wallet address to receive PYUSD tokens.
- Monitor the PYUSD main network address for transfers to the recipient's wallet address.
- Appropriately credit the user's balance upon confirmed transfers.
- Allow the user to transfer PYUSD tokens back to Paxos and PayPal using the contract's `transfer` or `transferFrom` functions.
When using `transferFrom`, we recommend using the `increaseApproval` and `decreaseApproval` functions rather than `approve`.
This avoids a [well known attack vector][eip-20-standard] in the standard `approve` function.
----------------------------------------
## Stablecoins Overview
Description: Use Paxos-issued stablecoins for payments, money movement and more.
Tags: Stablecoins
Path: stablecoin/index.mdx
[contact-us]: https://support.paxos.com
[pyusd]: stablecoin/pyusd/index.mdx
[usdp]: stablecoin/usdp/index.mdx
[transparency]: https://paxos.com/regulation-and-transparency/
[mint]: developer/mint.mdx
[redeem]: developer/redeem.mdx
[convert]: developer/convert.mdx
[usdg]: stablecoin/usdg/index.mdx
Paxos provides regulated, trustworthy stablecoins to make it easy for any blockchain application to add a trusted stablecoin to their product.
> See the [Paxos Developer Guides](/) to [mint], [redeem] and [convert] Paxos-issued stablecoins on the platform.**Questions?** [Contact the Stablecoin Team][contact-us].
## Global Dollar (USDG)
[Global Dollar (USDG)][usdg] is a single-currency stablecoin (SCS) pegged to the US dollar, issued by Paxos Digital Singapore Pte. Ltd. (PDS) and is compliant with the Monetary Authority of Singapore's (MAS) forthcoming stablecoin framework.
Built for payments, settlements and treasury, USDG can be used as an interoperable building block for open-source smart contracts, enabling developers to create new use-cases, products and services with USDG.
All cash and cash equivalent reserve assets are held in segregated accounts to protect user assets.
USDG is available for purchase and fully redeemable from Paxos on a one-to-one basis for US dollars (1 USDG = 1 USD).
## Pax Dollar (USDP)
[Pax Dollar (USDP)][usdp], issued by Paxos Trust Company, LLC (Paxos), is an open, U.S. dollar-denominated stablecoin.
USDP reserves are held 100% in cash and cash equivalents.
Available on multiple blockchains, USDP offers near-instant global settlements, low to no-cost transactions, and can be integrated with the most widely used exchanges, wallets, and dApps.
USDP is always fully redeemable from Paxos on a one-to-one basis for US dollars (1 USDP = 1 USD).
## PayPal USD (PYUSD)
[PayPal USD (PYUSD)][pyusd], issued by Paxos Trust Company, LLC (Paxos), is an open, fully backed, U.S. dollar-denominated stablecoin designed for payments.
Available on multiple blockchains, PYUSD offers near-instant global settlements, low to no-cost transactions, and can be integrated with the most widely used exchanges, wallets, and dApps.
The stablecoin is also used to power a number of use cases, including cross-border P2P payments, B2B transfers, global payouts, microtransactions and web3 payments.
## Regulation and Transparency
Paxos is committed to building trust in digital assets with regulated blockchain infrastructure and regulated, fully-backed USD stablecoins.
The monthly reserve reports ensure full transparency and the reliability of our financial data.
Read the [transparency reports][transparency].
----------------------------------------
## BUSD
Description: Redeem or convert BUSD on the Paxos platform.
Tags: BUSD
Path: stablecoin/busd.mdx
[contact-us]: https://support.paxos.com
[statement]: https://paxos.com/2023/02/13/paxos-will-halt-minting-new-busd-tokens/
Paxos no longer mints new BUSD, but allows customers to redeem BUSD for USD or convert their BUSD to USDP.
Read the [Paxos statement on BUSD][statement].
> **Questions?** [Contact the Stablecoin Team][contact-us].
----------------------------------------
## USDP Overview
Description: Learn more about the Fully backed, legally protected, always available Pax Dollar.
Tags: USDP
Path: stablecoin/usdp/index.mdx
[contact-us]: https://support.paxos.com
[transparency]: https://paxos.com/usdp-transparency/
[mint]: developer/mint.mdx
[redeem]: developer/redeem.mdx
[convert]: developer/convert.mdx
Pax Dollar (USDP), issued by Paxos Trust Company, LLC (Paxos), is an open, U.S. dollar-denominated stablecoin.
USDP reserves are held 100% in cash and cash equivalents.
Available on multiple blockchains, USDP offers near-instant global settlements, low to no-cost transactions, and can be integrated with the most widely used exchanges, wallets, and dApps.
USDP is always fully redeemable from Paxos on a one-to-one basis for US dollars (1 USDP = 1 USD).
> See the [Paxos Developer Guides](/) to [mint], [redeem] and [convert] USDP on the Paxos platform.**Questions?** [Contact the Stablecoin Team][contact-us].
## USDP Transparency
Paxos is committed to ensuring the public availability of reports on the USDP reserve assets.
Paxos publishes monthly reports on reserve composition as well as attestations reports issued by an independent third-party accounting firm. See the [USDP transparency reports][transparency].
----------------------------------------
## USDP on Test Networks
Description: Get the USDP testnet addresses.
Tags: USDP
Path: stablecoin/usdp/testnet.mdx
[usdp-sepolia-testnet-address]: https://sepolia.etherscan.io/token/0x513421d7fb6A74AE51f3812826Aa2Db99a68F2C9
[usdp-solana-devnet-address]: https://explorer.solana.com/address/G8iheDY9bGix5qCXEitCExLcgZzZrEemngk9cbTR3CQs?cluster=devnet
| Test Network | Contract Address |
| --- | --- |
| Ethereum Sepolia Testnet | [0x513421d7fb6A74AE51f3812826Aa2Db99a68F2C9][usdp-sepolia-testnet-address] |
| Solana Devnet | [G8iheDY9bGix5qCXEitCExLcgZzZrEemngk9cbTR3CQs][usdp-solana-devnet-address] |
----------------------------------------
## USDP on Main Networks
Description: Get the USDP mainnet addresses.
Tags: USDP
Path: stablecoin/usdp/mainnet.mdx
[usdp-ethereum-mainnet-address]: https://etherscan.io/token/0x8E870D67F660D95d5be530380D0eC0bd388289E1
[usdp-solana-mainnet-address]: https://explorer.solana.com/address/HVbpJAQGNpkgBaYBZQBR1t7yFdvaYVp2vCQQfKKEN4tM
| Network | Contract Address |
| --- | --- |
| Ethereum Mainnet | [0x8E870D67F660D95d5be530380D0eC0bd388289E1][usdp-ethereum-mainnet-address] |
| Solana Mainnet Beta | [HVbpJAQGNpkgBaYBZQBR1t7yFdvaYVp2vCQQfKKEN4tM][usdp-solana-mainnet-address] |
----------------------------------------
## USDL Overview
Description: Use Lift Dollar for payments, settlements and treasury while earning on-chain yield.
Tags: USDL
Path: stablecoin/usdl/index.mdx
[contact-us]: https://support.paxos.com
[transparency]: https://liftdollar.com/transparency/
[mint]: developer/mint.mdx
[redeem]: developer/redeem.mdx
[convert]: developer/convert.mdx
[usdl]: https://liftdollar.com
[fsra]: https://www.adgm.com/financial-services-regulatory-authority
[adgm]: https://www.adgm.com/
[USDL][usdl] is a US dollar-backed stablecoin that distributes yield to its holders every day.
USDL reserves are held in short-term, highly liquid assets.
USDL can always be redeemed at a rate of **1 USDL = 1 US dollar**.
The token is issued by Paxos Issuance MENA Ltd. (Paxos International), which is regulated by the Financial Services Regulatory Authority ([FSRA][fsra]) of the Abu Dhabi Global Market ([ADGM][adgm]).
> See the [Paxos Developer Guides](/) to [mint], [redeem] and [convert] USDL on the Paxos platform.**Questions?** [Contact the Stablecoin Team][contact-us].
## USDL Transparency
Paxos is committed to ensuring the public availability of reports on the USDL reserve assets.
To ensure transparency on USDL reserve assets, Paxos publishes monthly reports on reserve composition as well as attestations reports issued by an independent third-party accounting firm. See the [USDL transparency reports][transparency].
----------------------------------------
## USDL on Test Networks
Description: Get the USDL token addresses.
Tags: USDL
Path: stablecoin/usdl/testnet.mdx
[usdl-sepolia-testnet-address]: https://example.com
| Test Network | Token Address |
| --- | --- |
| Ethereum Sepolia Testnet | [0xB1cedD9786e8E7d47Bbe8dc3689882cc836197Ec](https://sepolia.etherscan.io/token/0xB1cedD9786e8E7d47Bbe8dc3689882cc836197Ec) |
| Arbitrum One Sepolia Testnet | [0xeba9ad3D5811580aA2281Ff88cf5Af4fCF3426Eb](https://sepolia.arbiscan.io/token/0xeba9ad3D5811580aA2281Ff88cf5Af4fCF3426Eb) |
----------------------------------------
## USDL on Main Networks
Description: Get the USDL token addresses.
Tags: USDL
Path: stablecoin/usdl/mainnet.mdx
| Network | Token Address |
| --- | --- |
| Ethereum Mainnet | [0xbdC7c08592Ee4aa51D06C27Ee23D5087D65aDbcD](https://etherscan.io/token/0xbdC7c08592Ee4aa51D06C27Ee23D5087D65aDbcD) |
| Arbitrum One Mainnet | [0x7f850b0ab1988dd17b69ac564c1e2857949e4dee](https://arbiscan.io/token/0x7f850b0ab1988dd17b69ac564c1e2857949e4dee) |
----------------------------------------
## Documentation Moved
Path: stablecoin/token-contracts/pyusd.mdx
- [PYUSD on Test Networks](stablecoin/pyusd/testnet.mdx)
- [PYUSD on Main Networks](stablecoin/pyusd/mainnet.mdx)
- [PYUSD Overview](stablecoin/pyusd/index.mdx)
----------------------------------------
## PYUSD Overview
Description: Use PayPal USD as the payments layer to build new services and products on public blockchains.
Tags: PYUSD
Path: stablecoin/pyusd/index.mdx
[contact-us]: https://support.paxos.com
[transparency]: https://paxos.com/pyusd-transparency/
[mint]: developer/mint.mdx
[redeem]: developer/redeem.mdx
[convert]: developer/convert.mdx
[pyusd-logo-png]: https://insights.paxos.com/hubfs/PYUSDLOGO.png
PayPal USD (PYUSD), issued by Paxos Trust Company, LLC (Paxos), is an open, fully backed, U.S. dollar-denominated stablecoin designed for payments.
Available on multiple blockchains, PYUSD offers near-instant global settlements, low to no-cost transactions, and can be integrated with the most widely used exchanges, wallets, and dApps.
The stablecoin is also used to power a number of use cases, including cross-border P2P payments, B2B transfers, global payouts, microtransactions and web3 payments.
> See the [Paxos Developer Guides](/) to [mint], [redeem] and [convert] PYUSD on the Paxos platform.**Questions?** [Contact the Stablecoin Team][contact-us].
## PYUSD Transparency
PayPal and Paxos are committed to ensuring the public availability of reports on the PYUSD reserve assets.
To ensure transparency on PYUSD reserve assets, Paxos publishes monthly reports on reserve composition as well as attestations reports issued by an independent third-party accounting firm. See the [PYUSD transparency reports][transparency].
----------------------------------------
## PYUSD on Test Networks
Description: Get the PYUSD testnet addresses.
Tags: PYUSD
Path: stablecoin/pyusd/testnet.mdx
[pyusd-sepolia-testnet-address]: https://sepolia.etherscan.io/token/0xcac524bca292aaade2df8a05cc58f0a65b1b3bb9
[pyusd-solana-testnet-address]: https://solscan.io/token/CXk2AMBfi3TwaEL2468s6zP8xq9NxTXjp9gjMgzeUynM?cluster=devnet
| Test Network | Token Address |
| --- | --- |
| Ethereum Sepolia Testnet | [0xCaC524BcA292aaade2DF8A05cC58F0a65B1B3bB9][pyusd-sepolia-testnet-address] |
| Solana Devnet | [CXk2AMBfi3TwaEL2468s6zP8xq9NxTXjp9gjMgzeUynM][pyusd-solana-testnet-address] |
----------------------------------------
## PYUSD on Main Networks
Description: Get the PYUSD mainnet addresses.
Tags: PYUSD
Path: stablecoin/pyusd/mainnet.mdx
[pyusd-ethereum-mainnet-address]: https://etherscan.io/token/0x6c3ea9036406852006290770bedfcaba0e23a0e8
[pyusd-solana-mainnet-address]: https://solscan.io/token/2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo
| Network | Token Address |
| --- | --- |
| Ethereum Mainnet | [0x6c3ea9036406852006290770BEdFcAbA0e23A0e8][pyusd-ethereum-mainnet-address] |
| Solana Mainnet Beta | [2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo][pyusd-solana-mainnet-address] |
----------------------------------------
## USDG Overview
Description: Use Global Dollar for payments, settlements, treasury and more.
Tags: USDG
Path: stablecoin/usdg/index.mdx
[contact-us]: https://support.paxos.com
[transparency]: https://paxos.com/usdg-transparency/
[mint]: developer/mint.mdx
[redeem]: developer/redeem.mdx
[convert]: developer/convert.mdx
Global Dollar (USDG) is a single-currency stablecoin (SCS) pegged to the US dollar, issued by Paxos Digital Singapore Pte. Ltd. (PDS) and is compliant with the Monetary Authority of Singapore's (MAS) forthcoming stablecoin framework.
Built for payments, settlements and treasury, USDG can be used as an interoperable building block for open-source smart contracts, enabling developers to create new use-cases, products and services with USDG.
All cash and cash equivalent reserve assets are held in segregated accounts to protect user assets.
USDG is available for purchase and fully redeemable from Paxos on a one-to-one basis for US dollars (1 USDG = 1 USD).
> See the [Paxos Developer Guides](/) to [mint], [redeem] and [convert] USDG on the Paxos platform.**Questions?** [Contact the Stablecoin Team][contact-us].
## USDG Transparency
Paxos is committed to ensuring the public availability of reports on the USDG reserve assets.
To ensure transparency on USDG reserve assets, Paxos publishes monthly reports on reserve composition as well as attestations reports issued by an independent third-party accounting firm. See the [USDG transparency reports][transparency].
----------------------------------------
## USDG on Test Networks
Description: Get the USDG token addresses.
Tags: USDG
Path: stablecoin/usdg/testnet.mdx
[usdg-sepolia-testnet-address]: https://sepolia.etherscan.io/address/0xfBb2A78CceEb415b00300925e464C3E44E6e06b0
[usdg-solana-testnet-address]: https://solscan.io/token/4F6PM96JJxngmHnZLBh9n58RH4aTVNWvDs2nuwrT5BP7?cluster=devnet
| Test Network | Token Address |
| --- | --- |
| Ethereum Sepolia Testnet | [0xfBb2A78CceEb415b00300925e464C3E44E6e06b0][usdg-sepolia-testnet-address] |
| Solana Devnet | [4F6PM96JJxngmHnZLBh9n58RH4aTVNWvDs2nuwrT5BP7][usdg-solana-testnet-address] |
----------------------------------------
## USDG on Main Networks
Description: Get the USDG token addresses.
Tags: USDG
Path: stablecoin/usdg/mainnet.mdx
[usdg-ethereum-mainnet-address]: https://etherscan.io/address/0xe343167631d89B6Ffc58B88d6b7fB0228795491D
[usdg-solana-mainnet-address]: https://solscan.io/token/2u1tszSeqZ3qBWF3uNGPFc8TzMk2tdiwknnRMWGWjGWH
| Network | Token Address |
| --- | --- |
| Ethereum Mainnet | [0xe343167631d89B6Ffc58B88d6b7fB0228795491D][usdg-ethereum-mainnet-address] |
| Solana Mainnet Beta | [2u1tszSeqZ3qBWF3uNGPFc8TzMk2tdiwknnRMWGWjGWH][usdg-solana-mainnet-address] |
----------------------------------------
================================================================================
SECTION: CRYPTO-BROKERAGE
================================================================================
## Orders & Quotes FAQ
Description: Get answers to common questions about Orders & Quotes.
Tags: Crypto Brokerage, FAQ
Path: crypto-brokerage/orders-vs-hrq.mdx
[quote-quickstart]: ./quotes/quickstart
[v2-orders]: ../../api/v2#tag/Orders
### What's the difference between an order and a quote?
Orders execute in part or in full depending on the market conditions and properties of the order at the time of submission.
Quotes are "held rates" offered by Paxos to buy or sell assets at a specific price for a specific period of time - for example,
the option to buy BTC within the next 30 seconds for $8,000.
### Should I use quotes or orders for my integration?
The answer is highly dependent on business needs and best discussed with [Support](https://support.paxos.com/hc/en-us).
Generally speaking, retail users appreciate the predictability of quotes while experienced traders require the flexibility and
control offered by orders to execute their specific strategy.
### Are the workflows for quotes and orders similar or different?
They are different. Please see the [HRQ Quickstart Guide][quote-quickstart] and [Orders Reference Documents][v2-orders]
for more information on each service.
### Is it possible to cancel a Created Quote Execution?
Paxos guarantees the settlement for created quote execution, there is no option to cancel an already created quote.
----------------------------------------
## Orders, Precision and Rounding
Description: Learn about tick size, precision, rounding and other recommendations.
Tags: Best Practices, Crypto Brokerage
Path: crypto-brokerage/orders-precision-rounding.mdx
[contact-support]: https://support.paxos.com
[create-order]: ../api/v2#tag/Orders/operation/CreateOrder
[list-executions]: ../api/v2#tag/Orders/operation/ListExecutions
[list-orders]: ../api/v2#tag/Orders/operation/ListOrders
[get-order]: ../api/v2#tag/Orders/operation/GetOrder
[get-ticker]: ../api/v2#tag/Market-Data/operation/GetTicker
[get-order-book]: ../api/v2#tag/Market-Data/operation/GetOrderBook
[list-historical-prices]: ../api/v2#tag/Pricing/operation/ListHistoricalPrices
[v2-api]: ../../api/v2
[fix-api]: https://developer.paxos.com/docs/itbit/fix/
We recommend that [REST and WebSocket integrations](#rest-websocket-clients) support the maximum decimal precision of 0.000001 (1e-6) for all current and future assets ([parameter precision](#additional-parameter-precision) differs for some services).
All [FIX integrations](#fix-clients) should support up to 19 decimal places 0.0000000000000000001 (1e-19) for all assets.
:::note
Tick size, miniums and other precision information is for USD markets only.
For information on other markets, [contact support][contact-support].
:::
## Order Limitations
- For market buy orders, the minimum quantity is 0.01 USD for all assets. For market sell or limit orders, the minimum size is eight ticks: 0.00000001 (1e-8).
- For market orders, the maximum notional value is 500,000 USD. For limit orders, the maximum notional value is 1,500,000 USD for XBTUSD and ETHUSD markets, and 1,000,000 USD for other markets.
- A taker order will be rejected if its limit price is 15% or more from the midpoint of the best bid and best ask.
- For a comprehensive look at order constraints, please refer to our the documentation for the [Paxos v2 REST API docs][v2-api] or the [Paxos FIX API Reference page][fix-api]
## Tick and Decimal Precision for REST and WebSocket Clients {#rest-websocket-clients}
| Market | Minimum Tick Size (USD) | Maximum Decimal Precision (USD) |
| --- | --- | --- |
| AAVEUSD | 0.01 | 0.000001 (1e-6) |
| BCHUSD | 0.05 | 0.000001 (1e-6) |
| BTCUSD | 0.25 | 0.000001 (1e-6) |
| ETHUSD | 0.05 | 0.000001 (1e-6) |
| LINKUSD | 0.01 | 0.000001 (1e-6) |
| LTCUSD | 0.01 | 0.000001 (1e-6) |
| (MATICUSD)[\*](#matic) | 0.0001 | 0.000001 (1e-6) |
| PAXGUSD | 0.01 | 0.000001 (1e-6) |
| SOLUSD | 0.01 | 0.000001 (1e-6) |
| UNIUSD | 0.01 | 0.000001 (1e-6) |
\* Effective September 17, 2024, users can no longer buy MATIC.
Users should exit their MATIC positions or transfer MATIC off-platform.
As of October 3, 2024, users can only transfer MATIC off-platform.
Contact support@paxos.com with questions or issues during the migration period.
### Additional Parameter Precision {#additional-parameter-precision}
The tick size and precision for some request and response parameters requires clients to implement differing precision.
We recommend ensuring all REST clients implement the following:
- `quote_amount` tick size of 0.01 (1e-2) for [Create Order][create-order].
- `volume_weighted_average_price` tick size of 0.00000001 (1e-8) for [Get Order][get-order] and [List Orders][list-orders].
- `average_price` precision of 0.000001 (1e-6) for [List Historical Prices][list-historical-prices].
- `commission ` and `rebate` tick size of 0.0000000000000000001 (1e-19) for [List Executions][list-executions].
- `gross_trade_amount` tick size of 0.00000000000001 (1e-14) for [List Executions][list-executions].
- `amount` precision of 0.00000001 (1e-8) for [Get Ticker][get-ticker], [Get Order Book][get-order-book] and [List Executions][list-executions].
- `base_amount` precision of 0.00000001 (1e-8) for [List Orders][list-orders], [Create Order][create-order] and [Get Order][get-order].
- `amount_filled` precision of 0.00000001 (1e-8) for [List Orders][list-orders], [Create Order][create-order] and [Get Order][get-order].
## Tick and Decimal Precision for FIX Clients {#fix-clients}
Ideally, your FIX integrations should support up to 19 decimal places, 0.0000000000000000001 (1e-19), for all assets.
Minimally, you your integrations must support 17 decimal places, 0.00000000000000001 (1e-17), for all assets.
## Rounding
Paxos uses different rounding logic for different services.
### Volume Weighted Average Price
The `volume_weighted_average_price` field is rounded using half-up logic after eight decimals.
This provides the volume-weighted average price across all underlying executions for an order within [List Executions][list-executions].
### HRQ Rounding
Rounding differs depending on the direction and side in combination with the given quote amount or base amount.
All assets are rounded to two (2) decimal points of precision except BRL.
BRL is truncated to six (6) decimal points.
- **Ceil**: Round up fully for any decimal places.
- **Floor**: Round down fully for any decimal places.
| Direction + Side | Rounding Behavior |
| --- | --- |
| Base Amount Input + BUY | Ceil (Quote Amount) |
| Base Amount Input + SELL | Floor (Quote Amount) |
| Quote Amount Input + BUY | Floor (Base Amount) |
| Quote Input Amount + SELL | Ceil (Base Amount) |
----------------------------------------
## Crypto Brokerage
Description: Add crypto to your application using REST, FIX and WebSocket APIs.
Tags: Crypto Brokerage
Path: crypto-brokerage/index.mdx
[v2-api]: ../api/v2
[market-data]: ../api/v2#tag/Market-Data
[orders]: ../api/v2#tag/Orders
[quotes]: ../api/v2#tag/Quotes
[transfers]: ../api/v2#tag/Transfers
[websocket-api]: api/websocket.mdx
[websocket-overview]: api/websocket.mdx
[websocket-quickstart]: crypto-brokerage/websocket.mdx
[fix-api]: https://developer.paxos.com/docs/itbit/fix/
[fix-onboard]: fix/onboard.mdx
[fix-certify]: fix/certify.mdx
[fix]: fix/index.mdx
Get [market data][market-data], create [orders][orders], execute [held-rate quotes][quotes] and [transfer][transfers] assets with [Paxos API v2.0][v2-api].
Leverage the [Paxos FIX API][fix-api] to trade crypto.
Learn more about [FIX][fix] and check out the [onboarding][fix-onboard] and [certification][fix-certify] guides to get started.
Construct the state of the order book and stream executed orders in real-time using the [Paxos WebSocket API][websocket-api].
Learn more about what you can do with [WebSocket][websocket-overview] or check out the [quickstart][websocket-quickstart] for a hands-on introduction.
----------------------------------------
## Connect to the WebSocket Market Data Feed
Description: Open a WebSocket connection to the Sandbox BTC Market Data feed.
Tags: Crypto Brokerage, Trading, WebSocket
Path: crypto-brokerage/websocket.mdx
[wscat]: https://github.com/websockets/wscat
[websocket-client]: https://pypi.org/project/websocket-client
[websocket-reference]: api/websocket.mdx
Use the command line to open a WebSocket connection to the Sandbox BTC Market Data Feed.
> See the [WebSocket API reference][websocket-reference] for more details.
## ➊ Install WebSocket Client
The quickest way to open a connection is by using [wscat][wscat], which runs in the terminal.
Using the Python [websocket-client][websocket-client] package requires a bit of code and the Python shell.
Open the terminal and install [wscat][wscat] using the `-g` (global) flag.
```shell
npm install -g wscat
```
Ensure [wscat][wscat] is working. If you see the version number, the module is working:
```shell
wscat --version
```
Open the terminal and install the Python3 [websocket-client][websocket-client] library.
```shell
pip3 install websocket-client
```
Start the Python3 shell and check that [websocket-client][websocket-client] was installed correctly.
If you don't see a `ModuleNotFoundError` message, the library is installed.
```py
python3
...
>>> >>>
```
Leave the terminal window open.
## ➋ Connect to Sandbox Feed
Open a long-lived connection to the Sandbox BTC Market Data Feed.
```shell
wscat --connect wss://ws.sandbox.paxos.com/marketdata/BTCUSD
```
```py
>>> >>> def on_message(wsapp, message):
... print(message)
...
>>> wsapp = websocket.WebSocketApp("wss://ws.sandbox.paxos.com/marketdata/BTCUSD", on_message=on_message)
>>> wsapp.run_forever() # Press CTRL+C to quit
```
## ➌ Review Sandbox Feed
If everything worked, you see the initial `SNAPSHOT` and then an `UPDATE` stream in the terminal.
```json title="Sandbox BTC Market Data Feed (wscat)"
Connected (press CTRL+C to quit)
< {
"type": "SNAPSHOT",
"market": "BTCUSD",
"bids": [
{
"price": "19994.25",
"amount": "0.7755"
},
{
"price": "19993.75",
"amount": "0.83676985"
},
...
],
"asks": [
{
"price": "19994.5",
"amount": "0.97548541"
},
{
"price": "19996",
"amount": "1.135"
},
...
],
"final_snapshot": true
}
< {
"type": "UPDATE",
"market": "BTCUSD",
"side": "BUY",
"price": "19958.5",
"amount": "0.62649999"
}
< {
"type": "UPDATE",
"market": "BTCUSD",
"side": "SELL",
"price": "20115.25",
"amount": "0"
}
...
```
```json title="Sandbox BTC Market Data Feed (websocket-client)"
{
"type": "SNAPSHOT",
"market": "BTCUSD",
"bids": [
{
"price": "19994.25",
"amount": "0.7755"
},
{
"price": "19993.75",
"amount": "0.83676985"
},
...
],
"asks": [
{
"price": "19994.5",
"amount": "0.97548541"
},
{
"price": "19996",
"amount": "1.135"
},
...
],
"final_snapshot": true
}
{
"type": "UPDATE",
"market": "BTCUSD",
"side": "BUY",
"price": "19958.5",
"amount": "0.62649999"
}
{
"type": "UPDATE",
"market": "BTCUSD",
"side": "SELL",
"price": "20115.25",
"amount": "0"
}
...
```
----------------------------------------
## Commissions and Rebates FAQ
Description: Get answers to common questions about commissions and rebates.
Tags: Crypto Brokerage, FAQ
Path: crypto-brokerage/commissions-rebates.mdx
### What's the difference between a commission and a rebate?
Commissions are charged by Paxos and debited from the user account. Rebates are credits from Paxos to the user account.
### In what currency are commissions and rebates charged or credited?
Commissions and rebates are charged or credited in the quote currency.
### When do you credit rebates or debit commissions?
Rebates are credited and commissions are debited when the order is executed.
### When selling, do you need additional funds to cover the commission?
No. The commissions is subtracted from the proceeds of the sale.
----------------------------------------
## Choosing a Ledgering Strategy
Description: Understand your options for ledgering fiat and cryptocurrency with Paxos.
Tags: Crypto Brokerage, Ledger, FAQ
Path: crypto-brokerage/ledger-type.mdx
[create-quote-execution]: ../api/v2#tag/Quote-Executions/operation/CreateQuoteExecution
[create-crypto-withdrawal]: ../api/v2#tag/Crypto-Withdrawals/operation/CreateCryptoWithdrawal
[create-order]: ../api/v2#tag/Orders/operation/CreateOrder
Crypto Brokerage customers have several options for how they ledger customer funds with Paxos.
:::tip
This document outlines common strategies for managing balances on Paxos. Each Crypto Brokerage partner must use a strategy consistent with their business needs and Paxos's licensing requirements.
**Please contact [Support](https://support.paxos.com/hc/en-us) before choosing a strategy and beginning your integration.**
:::
### Fiat and Crypto Omnibus
In this integration type, the Crypto Brokerage Partner relies on their own ledger for end-user’s fiat and crypto balances.
On the Paxos ledger there is one profile within the account where both fiat and crypto are held on behalf of all of the end users.
This option is typically only available in 1st-Party integrations, where the Crypto Brokerage Partner is relying exclusively on their own licensing and individual end users are not Paxos customers.
### Fiat and Crypto Subledger
In this integration type, the Crypto Brokerage Partner creates a Profile to hold the fiat and crypto balances for each individual user or account. This typically requires the use of Paxos's Identity and/or Account services. The Crypto Brokerage Partner is responsible for maintaining a mapping of individual user to their Paxos Profiles, Identities, and Accounts and passing the appropriate IDs on each request.
This is the most common integration type for 3rd-Party integrations, where the Partner is relying on Paxos's licensing and individual end users are Paxos customers.
### Fiat Omnibus and Crypto Subledger
Here, the Crypto Brokerage Partner relies on a single ledger for their fiat balances and uses a unique Paxos Profile for each end-user’s crypto balances. On the Paxos ledger there is one profile within the account where all fiat is held on behalf of all of the end users.
Crypto Brokerage Partners with Fiat Omnibus and Subledgered Crypto may leverage Directed Settlement. In Directed Settlement, the Crypto Brokerage Partner specifies ("directs") which subledgered profile should be credited or debited when a quote or trade is executed.
When buying crypto, fiat is debited from the omnibus profile and crypto is credited upon trade or quote execution. When selling crypto, crypto is debited from the specified end user Profile and fiat is credited to the omnibus profile.
### Required Fields:
The table below outlines how to populate various fields for the Ledgering Strategies defined above. For more details please see our API reference Documentation for [Orders][create-order], [Transfers][create-crypto-withdrawal] and [Quotes][create-quote-execution].
| API Parameters | Fiat Omnibus, Crypto Omnibus | Fiat Omnibus, Crypto Subledger (Directed Settlement) | Fiat and Crypto Subledger |
| --- | --- | --- | --- |
| `profile_id` | The Omnibus Profile ID | **Buy Orders:** Omnibus Profile ID **Sell Orders:** the End-User Profile ID | The profile that is funding the trade. This should be populated with the end-user profile |
| `recipient_profile_id` | Left Blank | **Buy Orders:** End User profile **Sell Orders:** Omnibus Profile ID | Left Blank |
| `identity_id` | Required in third party integrations. | Required in third party integrations. | Required in third party integrations. |
| `account_id``identity_account_id` | Potentially required in third party integrations. | Potentially required in third party integrations. | Potentially required in third party integrations. |
----------------------------------------
## Held Rate Quotes (HRQ)
Description: Held Rate Quotes (HRQ)
Tags: Crypto Brokerage, HRQ, Trading
Path: crypto-brokerage/quotes/index.mdx
[hrq-quickstart]: quotes/quickstart
[orders-hrq-faq]: orders-vs-hrq
By using the Held Rate Quote (HRQ) product, Partners can retrieve quotes ("held rates"). Quotes allow them to buy or sell assets for a specific price within a specific period of time.
- Review the [Orders & Quotes FAQ][orders-hrq-faq] to understand the differences between Orders and Quotes.
- Complete the [HRQ Quickstart Guide][hrq-quickstart] to test the HRQ workflow yourself.
----------------------------------------
## HRQ Quickstart
Description: Learn about Paxos's HRQ product and how to submit a quote in less than five minutes.
Tags: Crypto Brokerage, HRQ, Trading
Path: crypto-brokerage/quotes/quickstart.mdx
[account-paxos]: https://dashboard.paxos.com
[list-quotes]: ../../api/v2#tag/Quotes/operation/ListQuotes
[list-quote-executions]: ../../api/v2#tag/Quote-Executions/operation/ListQuoteExecutions
[create-quote-execution]: ../../api/v2#tag/Quote-Executions/operation/CreateQuoteExecution
[get-quote-execution]: ../../api/v2#tag/Quote-Executions/operation/GetQuoteExecution
[get-profile-balance]: ../../api/v2#tag/Profiles/operation/GetProfileBalance
[sandbox-deposits]: ../../api/v2#tag/Sandbox-Deposits
[orders-hrq-faq]: ../orders-vs-hrq
[ledger-type]: ../ledger-type
[required-fields]: ../ledger-type#required-fields-quote-executions
[subledgered]: ../ledger-type#fiat-omnibus-and-crypto-subledger
:::tip
**Before you begin**:
- HRQ is only available for Paxos Crypto Brokerage Partners and must be enabled before you can use the API endpoints. If you are a Paxos Crypto Brokerage Partner, you may reach out to Support for assistance enabling HRQ. If you are an Individual or Institutional User of [dashboard.paxos.com][account-paxos], please refer to the v2 Orders service for API trading.
- Make sure you can successfully authenticate with the `exchange:read_quote`, `exchange:read_quote_execution`, and
`exchange:write_quote_execution` scopes.
- Ensure you have a profile set up in Sandbox for trading. You can use the [Sandbox Deposits][sandbox-deposits]
endpoint to add fiat to your profile if you have not already.
- Please read the [Orders & Quotes FAQ][orders-hrq-faq] to ensure you understand the difference between quotes and orders.
- You may wish to review our document on [Choosing a Ledgering Strategy][ledger-type]. This guide is written assuming a
`Fiat and Crypto Omnibus` strategy.
:::
## Overview
In this quickstart guide you will learn how to submit a quote using Paxos's Held Rate Quote (HRQ) Service.
In order to purchase or sell cryptocurrency using HRQ, you must:
1. Call List Quotes to get the latest available quoted prices for the assets you want to buy or sell and record the
associated Quote ID.
2. Present the offered price to one or more end-users with a timer indicating the time to expiration.
3. If a user accepts the price, create a Quote Execution with the amount to buy or sell and the Quote ID from step 1.
4. Call Get Quote Execution to monitor for completion and know when the funds from the execution have settled.
## Step 1: Retrieve a Quote using `List Quotes`
The first step is to find the latest quote for the asset you wish to trade.
The [List Quotes][list-quotes] service will return a quote for the chosen asset that will be guaranteed for 30 seconds.
Note the `quote_id`. It will be needed to create a Quote Execution in Step 3 below.
:::tip
If Paxos is collecting a transaction fee in real time, the fee will be included in the quote automatically.
:::
### Code Samples
#### Step 1.1: Authenticate to the Paxos API.
#### Step 1.2: List quotes for BTC and ETH.
## Step 2: Present the quote to end users and await confirmation
Once quotes are retrieved, the price and expiration time can be presented to end users.
Paxos recommends creating a two-step process and allowing users to verify that they intend to purchase or sell the
specified amount at the specified price before executing the quote. The UI component is omitted here, and we will
proceed assuming confirmation was received from the end user.
:::tip
There is no limitation on the number of times a single quote can be executed. In production, quotes can and should be cached
to be presented to multiple users rather than calling List Quotes for each user.
Crypto Brokerage Partners should use multiplexing and call [List Quotes][list-quotes] via an application rather than
sending a List Quotes request every time a user wants to buy or sell an asset.
:::
## Step 3: Following confirmation, create a quote execution
The [Create Quote Execution][create-quote-execution] endpoint is used to execute on a quote for buying or selling an asset.
In the Quote Execution request, the Partner must set the amount of fiat or crypto to buy or sell based on the user's input.
This must be specified by EITHER:
- `base_amount` to specify the amount of crypto to buy or sell, OR
- `quote_amount` to specify the amount of fiat to spend or acquire.
The request will respond with a Quote Execution ID - this will need to be recorded to retrieve the quote execution in the
final step.
:::tip
- In a live integration:
- You should validate that the user has enough assets available to complete the transaction prior to
creating a quote execution. This step has been omitted for simplicity.
- In a live integration, there may be additional required fields depending on your chosen Ledgering Strategy. See
[Required Fields:][required-fields] for more information.
- The default maximum size limit of a single Quote Execution is $50K USD. Larger quotes would require multiple executions.
:::
### Code Samples
#### Step 3.1: Submitting the Quote.
Using the ID for the BTC buy Quote from step 1.2 and your omnibus `profile_id`.
## Step 4: Validate execution and settlement
The final step is to confirm that the quote execution completed and settled successfully using the
[Get Quote Execution][get-quote-execution] and [List Quote Executions][list-quote-executions] endpoints.
Quote executions typically complete in under 100ms. After creation, all quotes should be in the `CREATED` or `SETTLED`
status.
`CREATED` indicates that the Quote Execution has been submitted successfully, but has not yet settled.
When an order is in `CREATED` status, the purchasing asset (i.e. fiat for buy orders) will be debited from the profile_id.
The acquiring asset (i.e. crypto for sell orders) will be credited when the order is `SETTLED`.
Created quote can’t be canceled, Paxos guarantees settlement once a quote has been created!
`SETTLED` indicates that the venue executing the quote has confirmed completion of the trade. At this point, balances
in Paxos have been credited and debited and Partners can update their own ledgers to reflect a successful trade.
:::tip
Paxos recommends that all Crypto Brokerage Partners:
- build a pending order settlement workflow for edge cases where the order does not settle immediately. This is
especially Subledgered End Users will be unable to sell or transfer purchased Cryptocurrencies until the quote execution has `SETTLED`.
- cache profile balances. Balances should be updated once there has been a change to the profile balance (i.e. after a trade).
:::
### Code Samples
#### Checking the status of the submitted quote execution
Specify the same `profile_id` and the `id` of the quote execution in the url:
----------------------------------------
## FIX
Description: Leverage the FIX protocol for crypto trading.
Tags: Crypto Brokerage, FIX, Trading
Path: crypto-brokerage/fix/index.mdx
[fix-api]: https://developer.paxos.com/docs/itbit/fix/
FIX (Financial Information eXchange) is an electronic messaging protocol widely adopted by financial institutions to transmit trading activity such as submitting or canceling orders and receiving execution information. The [FIX API][fix-api] is based on FIX 4.2 and modeled after common Forex FIX implementations.
## Get Started
----------------------------------------
## FIX Best Practices
Description: Learn about connection management, sequence number management and testing.
Tags: Best Practices, Crypto Brokerage, FIX
Path: crypto-brokerage/fix/best-practices.mdx
[fix-certify]: certify.mdx
Paxos recommends following FIX industry best practices, in addition to the items outlined below.
## Identity Mapping
Use the following table to map Paxos identify information to the corresponding FIX tag.
| Paxos Identity | FIX Tag |
| --- | --- |
| Customer ID | Account (1) |
| Profile ID | ClientID (109) |
## Sequence Number Management
Periodically disconnecting the FIX connection.
Resetting the message sequence number promotes a stable trading environment for all users.
Paxos forces a disconnect and reset of sequence numbers weekly for all sessions.
The exact time when the disconnect and reset to sequence numbers happen is discussed during the onboarding process.
Clients must configure their FIX engines to expect a disconnect and sequence number reset at the agreed schedule, failure to do so will result in an invalid FIX session due to mismatching sequence numbers.
Schedule times follow the US Eastern Time Zone (ET), an area five hours behind Greenwich Mean Time (GMT-5) during the winter months (referred to as Eastern Standard Time or EST) and four hours behind Greenwich Mean Time (GMT-4) during the summer months (referred to as Eastern Daylight Time or EDT).
:::note
Paxos Support may contact you regarding connection practices to prevent performance degradation.
:::
## Cancel on Disconnect
Cancel on Disconnect is enabled by default.
When a disconnection occurs, the service automatically submits a cancel request for all open orders.
## Use Multiple connections
FIX supports multiple connections per trading account.
Please submit a request to support@paxos.com to request additional connections.
## Implementation Testing
Test the FIX implementation by following the [FIX certification process][fix-certify] in the Sandbox environment prior to going live in Production.
----------------------------------------
## FIX Certification
Description: Test and verify the FIX implementation in Sandbox before going to Production.
Tags: Crypto Brokerage, FIX, Trading
Path: crypto-brokerage/fix/certify.mdx
[fix-best-practices]: best-practices.mdx
Paxos recommends testing the FIX implementation by running through the following test cases.
These tests cover the most common scenarios when trading on the Paxos Platform: submitting orders for valid and invalid markets, order types, order execution and canceling orders.
:::note
If you have any questions or run into issues, contact support@paxos.com for assistance.
:::
## SYM1: Symbology - Valid Market
User submits order for each of the markets which the user expects to trade and processes corresponding confirmation response.
## SYM2: Symbology - Invalid Market
User submits order for invalid market symbol (for example, `XXXXXX`) and processes the corresponding reject response.
## LIM1: Buy Limit (Buy 1.1 @ Limit $200 XBTUSD)
User submits limit buy order for valid quantity, price and market, and the processes corresponding confirmation response.
## LIM2: Sell Limit (Sell 0.001 @ Limit $200 XBTUSD)
User submits limit sell order for valid quantity, price and market, and the processes corresponding confirmation response.
## EX1: Single Execution - Fill
User submits marketable limit order (limit price will be immediately executed, either partially or completely) and processes the corresponding confirmation and fill responses.
## CXL1: Cancel New
User submits a limit outside of current market price (so the order will not execute), processes the corresponding confirmation response, and then issues a cancel request and processes the corresponding cancel confirmation.
## CXL2: Cancel Reject
User attempts to cancel an invalid or non-existent order ID, or an order which has been previously completely filled, and processes the corresponding cancel reject response.
## OPT1: Cancel on Disconnect (Optional)
User submits multiple orders with the limit outside of current market price (so the orders will not execute), processes the corresponding confirmation responses and then disconnects their FIX session to verify all open orders are canceled.
## OPT2: Status Request (Optional)
User submits a status request for a previously submitted order and processes the corresponding status response.
## Next Steps
Read the FIX [best practices][fix-best-practices] guide.
----------------------------------------
## FIX Onboarding
Description: Set Up a Paxos Account, configure connection then certify.
Tags: Crypto Brokerage, FIX, Trading
Path: crypto-brokerage/fix/onboard.mdx
[fix-api]: https://developer.paxos.com/docs/itbit/fix/
[certify]: certify.mdx
[fix-best-practice]: best-practices.mdx
[tls-troubleshooting]: https://cryptobrokerage.paxos.com/hc/en-us/articles/17822398442516
[stunnel]: https://www.stunnel.org/
Set up and test a FIX connection in both the Sandbox and Production environments.
Connect to the Sandbox environment first for testing purposes.
Once the connection is working in Sandbox, follow a similar procedure for the Production connection.
:::tip
Learn more about [FIX Best Practices][fix-best-practice], including how to use multiple connections and managing sequence number resets.
:::
## 1. Set Up Paxos Account
To gain access, create a Paxos Account and Support will guide you through the process.
Go to https://dashboard.sandbox.paxos.com and create an **Institution** Account in the Sandbox environment.
Use an active email address when signing up: Paxos will send a verification email to the address on file.
Once the email is verified, complete the registration process.
:::info
When creating the Sandbox Account:
- Do not submit documents.
- Use placeholder (dummy) text for all text fields **except** for the email address.
:::
Contact support@paxos.com before creating a Production Account.
## 2. Generate a Certificate Signing Request (CSR)
## 3. Set Up SSL
Once complete, [test][certify] your connection to our servers.
Contact support@paxos.com with test results of for help with an alternative to [stunnel][stunnel].
## Next Steps
- Refer to this KB Article for troubleshooting issues with the FIX Connection configuration - [Troubleshooting FIX mTLS connectivity configuration][tls-troubleshooting].
- Test the FIX implementation in the Sandbox environment by running through the [certification process][certify].
- Review the [FIX best practices][fix-best-practice].
- Read the [FIX reference documentation][fix-api].
----------------------------------------
================================================================================
SECTION: PAYMENTS
================================================================================
## Stablecoin Payments
Description: Accept stablecoin pay-ins with real-time settlement. Issue on-chain refunds.
Tags: Payments
Path: payments/index.mdx
FeatureCard,
FeatureContainer,
} from "@site/src/components";
[supported-assets]: /payments/faq#supported-assets
[crypto-deposit-address]: payments/quickstart.mdx#pay-in-add-deposit-address
[reconcile]: payments/quickstart.mdx#pay-in-monitor-reconcile
[disseminate]: payments/quickstart.mdx#receive-payment
[refund-reconcile]: payments/quickstart.mdx#refund-monitor-reconcile
[initiate-withdrawal]: /payments/quickstart#refund-initiate
[send-usd]: /payments/quickstart#refund-fund-account
[withdraw USD]: /payments/quickstart#pay-in-withdraw-fiat
Use the Paxos APIs to effortlessly integrate stablecoin payment acceptance into your platform.
Features include:
- Accept PYUSD, USDC and USDP payments via on-chain transfers.
- Automatically convert the stablecoin to fiat, or opt to hold balances in stablecoin.
- Reconcile transactions on the Paxos Platform.
- Settle USD directly to your bank account.
- Issue refunds to the original Buyer via stablecoin on-chain transfers.
:::note
In the documentation, a payment is considered to be the total amount processed, including both the incoming payment (pay-in) and returned payment (refund).
:::
## Pay-ins Workflow
The pay-ins workflow involves two key personas: a Buyer purchasing goods or services using stablecoins and a Seller.
The Seller represents either a merchant that provides goods or services, or a payment processor acting as the intermediary to facilitate the transaction.
Most pay-in integrations follow a similar workflow for the Seller:
1. [Add a crypto deposit address][crypto-deposit-address] for a designated Profile, using one of the [supported blockchains][supported-assets].
1. To [use stablecoins for pay-ins][disseminate], share the crypto deposit address with Buyers as a checkout option.
1. Configure a [pay-in monitoring and reconciliation][reconcile] request to confirm Pay-in transactions on the Paxos Platform.
1. [Withdraw USD] to a bank account.
## Refunds Workflow
Issuing a refund is similar to pay-ins, except the funding flow is reversed: USD is first moved onto the Paxos Platform and then the stablecoin refund is sent to the Buyer's designated wallet.
Most refund integrations follow a similar workflow for the Seller:
1. [Send USD][send-usd] to a designated refund account.
1. [Initiate a crypto withdrawal][initiate-withdrawal] to the Buyer's designated wallet address, using one of the [supported blockchains][supported-assets].
1. Configure a [refund monitoring and reconciliation][refund-reconcile] request to confirm Pay-in transactions on the Paxos Platform.
## Get Started
Accept stablecoin pay-ins with real-time settlement. Issue on-chain refunds.
Learn more about payment statuses.
Get answers to common questions about payments.
----------------------------------------
## Connect to the WebSocket Stablecoin Price Feed
Description: Open a WebSocket connection to the Sandbox USDCUSD feed.
Tags: Payments, WebSocket
Path: payments/websocket.mdx
[wscat]: https://github.com/websockets/wscat
[websocket-client]: https://pypi.org/project/websocket-client
[websocket-reference]: api/websocket.mdx
Use the command line to open a WebSocket connection to the Sandbox USDCUSD stablecoin market price feed.
> See the [WebSocket API reference][websocket-reference] for more details.
## ➊ Install WebSocket Client
The quickest way to open a connection is by using [wscat][wscat], which runs in the terminal.
Using the Python [websocket-client][websocket-client] package requires a bit of code and the Python shell.
Open the terminal and install [wscat][wscat] using the `-g` (global) flag.
```shell
npm install -g wscat
```
Ensure [wscat][wscat] is working. If you see the version number, the module is working:
```shell
wscat --version
```
Open the terminal and install the Python3 [websocket-client][websocket-client] library.
```shell
pip3 install websocket-client
```
Start the Python3 shell and check that [websocket-client][websocket-client] was installed correctly.
If you don't see a `ModuleNotFoundError` message, the library is installed.
```py
python3
...
>>> >>>
```
Leave the terminal window open.
## ➋ Connect to Sandbox Feed
Open a long-lived connection to the Sandbox USDCUSD stablecoin market price feed.
```shell
wscat --connect wss://ws.sandbox.paxos.com/marketdata/stablecoin/USDCUSD
```
```py
>>> >>> def on_message(wsapp, message):
... print(message)
...
>>> wsapp = websocket.WebSocketApp("wss://ws.sandbox.paxos.com/marketdata/stablecoin/USDCUSD", on_message=on_message)
>>> wsapp.run_forever() # Press CTRL+C to quit
```
## ➌ Review Sandbox Feed
If everything worked, USDCUSD the pricing data streams to the terminal.
```json title="Sandbox USDCUSD stablecoin market price feed (wscat)"
Connected (press CTRL+C to quit)
{"market":"USDCUSD","price":"0.9996","timestamp":"2024-11-04T16:12:38.053038191Z"}
{"market":"USDCUSD","price":"0.9996","timestamp":"2024-11-04T16:12:39.080704227Z"}
{"market":"USDCUSD","price":"0.9996","timestamp":"2024-11-04T16:12:40.044403631Z"}
...
```
```json title="Sandbox USDCUSD stablecoin market price feed (websocket-client)"
{"market":"USDCUSD","price":"0.9998","timestamp":"2024-11-04T17:23:50.050471826Z"}
{"market":"USDCUSD","price":"0.9998","timestamp":"2024-11-04T17:23:51.064565343Z"}
{"market":"USDCUSD","price":"1.0001","timestamp":"2024-11-04T17:23:52.05566422Z"}
...
```
----------------------------------------
## Payments FAQ
Description: Get answers to common questions about payments.
Tags: Payments
Path: payments/faq.mdx
----------------------------------------
## Stablecoin Pay-ins Quickstart
Description: Accept stablecoin pay-ins with real-time settlement. Issue on-chain refunds.
Tags: Payments, Quickstart
Path: payments/quickstart.mdx
[credentials]: https://dashboard.sandbox.paxos.com/admin/api
[help-desk]: https://support.paxos.com
[pay-in-add-deposit-address]: payments/quickstart.mdx#pay-in-add-deposit-address
[create-deposit-address]: /api/v2#tag/Deposit-Addresses/operation/CreateDepositAddress
[supported-stablecoins]: payments/faq.mdx#supported-assets
[supported-tokens]: payments/faq.mdx#supported-assets
[configuring a stablecoin pay-in workflow]: payments/quickstart.mdx#payment-workflow
[setting up a refund workflow]: payments/quickstart.mdx#refunds
[list-transfers]: /api/v2#tag/Transfers/operation/ListTransfers
[contact-us]: https://support.paxos.com/hc/en-us
[login]: https://dashboard.sandbox.paxos.com/
[pay-in]: /payments/quickstart#payment-workflow
[refund]: /payments/quickstart#refunds
[onboard]: /payments/faq#seller-onboarding
[Create Profile]: /api/v2#tag/Profiles/operation/CreateProfile
[pay-in-monitor-reconcile]: /payments/quickstart/#pay-in-monitor-reconcile
[fiat-transfer-guide]: developer/fiat-transfers/index.mdx
[create a fiat account]: /api/v2#tag/Fiat-Transfers/operation/CreateFiatAccount
[fund-refunds]: /payments/quickstart#refund-fund-account
[Create Crypto Withdrawal]: /api/v2#tag/Crypto-Withdrawals/operation/CreateCryptoWithdrawal
[Create Sandbox Deposit]: /api/v2#tag/Sandbox-Deposits/operation/CreateSandboxDeposit
[Fiat Transfers]: /api/v2#tag/Fiat-Transfers
[List Profile Balances]: /api/v2#tag/Profiles/operation/ListProfileBalances
[refund-monitor-reconcile]: /payments/quickstart#refund-monitor-reconcile
This guides walks you through the steps to set up a basic payments workflow using the Paxos Platform, including [configuring a stablecoin pay-in workflow] and [setting up a refund workflow].
Once completed, similar, more robust, workflows can be implemented in production.
If you already have sandbox access, this guide should take less than one hour to complete.
## Before You Begin
- Paxos may need to enable some API functionality described in the payments guides. Contact [Support][help-desk] with any access issues.
- If you need a developer sandbox account, [contact us][contact-us] before continuing.
- The API endpoints require authentication with a **Client ID** and **Secret**.
Each **Client ID** has a specific set of allowed scopes to access API endpoints.
- To follow along with this guide, [create a new Profile][Create Profile] to represent the Seller.
However, any existing Profile can be used when setting up simple [pay-in] and [refund] workflows.
Learn more about [user onboarding requirements][onboard].
- To represent the Buyer in this guide, send enough testnet tokens to pay network fees, along with one of the [supported testnet stablecoins][supported-tokens], to an off-platform wallet.
## Set Up Stablecoin Pay-in Workflow {#payment-workflow}
To accept a pay-in on the Paxos Platform, first use [Create Deposit Address][create-deposit-address] to add a new wallet address on the public blockchain.
Then add the deposit address as a stablecoin payment option for Buyers, typically at checkout.
Once a Buyer completes a purchase, the transaction shows up in the [List Transfers][list-transfers] monitoring and reconciliation polling request.
### 1. Add Seller Stablecoin Deposit Address {#pay-in-add-deposit-address}
Use [Create Deposit Address][create-deposit-address] to add a wallet address to the Profile designated for the Seller.
The request must include one of [supported stablecoins][supported-stablecoins] networks.
Set `conversion_target_asset` to `USD` to automatically convert stablecoin pay-ins to USD on the Paxos Platform.
The example uses `SOLANA` as the `crypto_network`.
If needed, use either `ETHEREUM` or `POLYGON_POS` for `crypto_network`.
```shell
curl --location 'https://api.sandbox.paxos.com/v2/transfer/deposit-addresses' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{
// highlight-start
"profile_id": "eb1dbb95-8e22-471b-9ded-40bbfe309037",
"crypto_network": "SOLANA",
"ref_id": "da_73bcbb08-db06-4308-b0c2-2a6398012f8b",
"conversion_target_asset": "USD"
// highlight-end
}'
```
Capture the `address` and `compatible_crypto_networks` values for distribution to potential Buyers.
Also store the `id` to use when [looking up pay-ins][pay-in-monitor-reconcile].
```json
{
"id": "2d3b2366-c432-4098-ba16-83ca418c6f00",
"profile_id": "eb1dbb95-8e22-471b-9ded-40bbfe309037",
"customer_id": "8cbc1177-d982-4750-a435-3c7f36245452",
"crypto_network": "SOLANA",
"identity_id": "00000000-0000-0000-0000-000000000000",
"ref_id": "da_73bcbb08-db06-4308-b0c2-2a6398012f8b",
// highlight-next-line
"address": "7iR1TfsaZ3f1PmbsoRuPYDbV7iujxZmuHaZDDU1Uv4YX",
"account_id": "00000000-0000-0000-0000-000000000000",
"conversion_target_asset": "USD",
"compatible_crypto_networks": [
//highlight-next-line
"SOLANA"
]
}
```
Since the designated Profile has not gone through the Identity onboarding process, the default `identity_id` and `account_id` values appear in the response.
> Onboarding Questions?
> See the [onboarding FAQ][onboard] for details about user Identity and Account requirements.
> Contact [Support][contact-us] to help determine the best onboarding approach.
### 2. Receive Stablecoin Payment {#receive-payment}
Off the Paxos Platform, share the [deposit address][pay-in-add-deposit-address] with Buyers, typically on the checkout page, and start accepting stablecoin pay-ins.
Once a Buyer completes a pay-in transaction, Paxos credits the designated Profile with either stablecoin or USD, based on the deposit address configuration.
For this guide, all received pay-ins are automatically converted to USD on the Paxos Platform because we used `"conversion_target_asset": "USD"` when [creating the deposit address][pay-in-add-deposit-address].
### 3. Add Pay-in Monitoring and Reconciliation Request {#pay-in-monitor-reconcile}
Using [List Transfers][list-transfers], create a recurring request that looks for completed transactions in the Seller's Profile.
Retrieve the status for payments received in the [deposit address][pay-in-add-deposit-address] using the `profile_id`, filtered by on the `CRYPTO_DEPOSIT` type and `updated_at.gte` parameters.
:::tip Best Practice
We recommend to poll [List Transfers][list-transfers] globally at a set cadence (for example, at 1 second intervals), using slightly behind the last processed `updated_at.gte` as a synchronization checkpoint.
:::
```shell
curl --location 'https://api.sandbox.paxos.com/v2/transfer/transfers?profile_ids=eb1dbb95-8e22-471b-9ded-40bbfe309037&updated_at.gte=2024-06-24T15%3A44%3A54.383141Z&type=CRYPTO_DEPOSIT' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access_token}'
```
The response confirms that a `total` of `7.06` PYUSD (`asset`) was converted to USD (`balance_asset`) when the pay-in reached the Paxos Platform.
```json
{
"items": [
{
"id": "9d93693f-5157-49f4-ae44-4a7a8eae3d73",
"customer_id": "8cbc1177-d982-4750-a435-3c7f36245452",
"profile_id": "eb1dbb95-8e22-471b-9ded-40bbfe309037",
// highlight-start
"amount": "7.06",
"total": "7.06",
"fee": "0",
"asset": "PYUSD",
"balance_asset": "USD",
// highlight-end
"direction": "CREDIT",
"type": "CRYPTO_DEPOSIT",
"status": "COMPLETED",
"created_at": "2024-06-24T15:44:48.724648Z",
"updated_at": "2024-06-24T15:44:55.383141Z",
"destination_address": "7iR1TfsaZ3f1PmbsoRuPYDbV7iujxZmuHaZDDU1Uv4YX",
"crypto_network": "SOLANA",
"crypto_tx_hash": "4ex3dQ1bkoxQyyWKsk5UfVwNzzi2HXBcDb2Xv1BzxKLhRKZaVmfAJyM2hWochXTqTRDMsrpcfvoaFTMZrBsaaJPx",
"crypto_tx_index": "4",
"auto_conversion": {}
}
],
"next_page_cursor": "CAISDAj3qOazBhCIidm2ARijg5MN"
}
```
### 4. Move USD to Bank Account {#pay-in-withdraw-fiat}
To manage on-platform cash balances, use the [Fiat Transfers] APIs to batch withdraw USD to any designated bank account as needed.
Learn more in the [fiat transfers guide][fiat-transfer-guide].
> If you need to [create a fiat account] Paxos may need to enable some API functionality.
C> ontact [Support][contact-us] for assistance.
## Set Up a Refund Workflow {#refunds}
To process stablecoin refunds on the Paxos Platform, first [fund your account with USD][fund-refunds] then use [Create Crypto Withdrawal] to initiate a stablecoin refund to the Buyer.
Once a refund is complete, the transaction shows up in the [List Transfers][list-transfers] monitoring and reconciliation polling request.
### 1. Add USD to a Refund Account {#refund-fund-account}
Production implementations can use the [Fiat Transfers] APIs to send USD to a destination on the Paxos Platform, which is out of scope for this guide.
The [fiat transfers guide][fiat-transfer-guide] provides step-by-step instructions on setting up fiat movements.
> If you need to [create a fiat account] Paxos may need to enable some API functionality.
> Contact [Support][contact-us] for assistance.
For simplicity, this guide uses [Create Sandbox Deposit] to simulate funding the designated Seller Profile with USD.
Include the Seller's Profile ID (`profile_id`) as a path parameter, as well as the deposit `asset` and `amount` as query parameters.
```shell
curl --location 'https://api.sandbox.paxos.com/v2/sandbox/profiles/eb1dbb95-8e22-471b-9ded-40bbfe309037/deposit' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access_token} \
--data '{
"asset": "USD",
"amount": "100"
}'
```
A successful response only includes the system-generated `activity_id`.
```json
{
"activity_id": "a457f3b2-8897-4118-bc9b-216541cfc5a7"
}
```
### 1.1 Sandbox Only: Check USD Deposit
To confirm the USD deposit, use [List Profile Balances].
```shell
curl --location 'https://api.sandbox.paxos.com/v2/profiles/eb1dbb95-8e22-471b-9ded-40bbfe309037/balances?assets=USD' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access_token}'
```
The Profile USD balance is now `107.06`, reflecting both the previously received pay-in and the current USD deposit.
```json
{
"items": [
{
//highlight-start
"asset": "USD",
"available": "107.06",
// highlight-end
"trading": "0"
}
]
}
```
### 2. Initiate a Stablecoin Refund {#refund-initiate}
Use [Create Crypto Withdrawal] to send stablecoin to the Buyer's designated wallet address.
The request must include one of [supported stablecoins][supported-stablecoins] networks.
:::tip
Set `balance_asset` to `USD` to automatically convert fiat to stablecoin and issue a refund in a single request.
:::
For this guide, the refund is issued to the Buyer's original wallet address (`destination_address`) using the same stablecoin/network pair:
- The `asset` is `PYUSD`, the `balance_asset` is `USD`, and the `crypto_network` is `SOLANA`.
The funding source is the Seller's Profile (`profile_id`) used earlier.
```shell
curl --location 'https://api.sandbox.paxos.com/v2/transfer/crypto-withdrawals' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{
"profile_id": "eb1dbb95-8e22-471b-9ded-40bbfe309037",
"asset": "PYUSD",
"destination_address": "BtXdwoYSWPprQT88ZCLuQcXuTz4dFHB1AJFYqr5uXoAd",
"crypto_network": "SOLANA",
"ref_id": "cw_293a8f7c-bcb6-483f-919b-8661ae65f0e6",
"balance_asset": "USD",
"amount": "7.06"
}'
```
The initial response has a `status` of `PENDING`, since the on-chain transaction has not yet been confirmed.
Create a [refund monitoring request][refund-monitor-reconcile] to check that the refund was successful.
```json
{
"id": "c327d8b7-0c1a-4125-b73f-318924373d37",
"customer_id": "8cbc1177-d982-4750-a435-3c7f36245452",
"profile_id": "eb1dbb95-8e22-471b-9ded-40bbfe309037",
"ref_id": "cw_293a8f7c-bcb6-483f-919b-8661ae65f0e6",
"amount": "7.06",
"total": "7.06",
"fee": "0",
"asset": "PYUSD",
"balance_asset": "USD",
"direction": "DEBIT",
"type": "CRYPTO_WITHDRAWAL",
"status": "PENDING",
"created_at": "2024-06-24T18:33:51.087868Z",
"updated_at": "2024-06-24T18:33:51.087868Z",
"destination_address": "BtXdwoYSWPprQT88ZCLuQcXuTz4dFHB1AJFYqr5uXoAd",
"crypto_network": "SOLANA",
"auto_conversion": {}
}
```
### 3. Add Refund Monitoring and Reconciliation Request {#refund-monitor-reconcile}
Using [List Transfers][list-transfers], create a recurring request that looks for completed transactions in the Seller's Profile.
Retrieve the status for refunds sent by using the `profile_id`, filtering by on the `CRYPTO_WITHDRAWAL` type and `updated_at.gte` parameters.
:::tip Best Practice
We recommend to poll [List Transfers][list-transfers] globally at a set cadence (for example, at 1 second intervals), using slightly behind the last processed `updated_at.gte` as a synchronization checkpoint.
:::
```shell
curl --location 'https://api.sandbox.paxos.com/v2/transfer/transfers?profile_ids=eb1dbb95-8e22-471b-9ded-40bbfe309037&updated_at.gte=2024-06-24T15%3A44%3A54.383141Z&type=CRYPTO_WITHDRAWAL' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access_token}'
```
The response confirms that a `total` of `7.06` PYUSD (`asset`) was sent to the Buyer's wallet address.
```json
{
"items": [
{
"id": "c327d8b7-0c1a-4125-b73f-318924373d37",
"customer_id": "8cbc1177-d982-4750-a435-3c7f36245452",
"profile_id": "eb1dbb95-8e22-471b-9ded-40bbfe309037",
"ref_id": "cw_293a8f7c-bcb6-483f-919b-8661ae65f0e6",
//highlight-start
"amount": "7.06",
"total": "7.06",
"fee": "0",
"asset": "PYUSD",
"balance_asset": "USD",
"direction": "DEBIT",
"type": "CRYPTO_WITHDRAWAL",
"status": "COMPLETED",
// highlight-end
"created_at": "2024-06-24T18:33:51.105228Z",
"updated_at": "2024-06-24T18:34:24.976618Z",
"destination_address": "BtXdwoYSWPprQT88ZCLuQcXuTz4dFHB1AJFYqr5uXoAd",
"crypto_network": "SOLANA",
"crypto_tx_hash": "4xo8doZQ58W6WCrzmyjd3vyrv2SPMRjHiz4v6w8mEuCCWbAyiXjzbFADia7St6XF3jTNyQmrDmpSNH84TXdDujFU",
"crypto_tx_index": "0",
"auto_conversion": {}
}
],
"next_page_cursor": "CAISDAiw-OazBhCQhNjRAxi0jpMN"
}
```
### 3.1 Sandbox Only: Check USD Withdrawal
To confirm USD was used to fund the crypto withdrawal, use [List Profile Balances].
```shell
curl --location 'https://api.sandbox.paxos.com/v2/profiles/eb1dbb95-8e22-471b-9ded-40bbfe309037/balances?assets=USD' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access_token}'
```
The Profile USD balance is now `100.00`, where previously it was `7.06`.
```json
{
"items": [
{
//highlight-start
"asset": "USD",
"available": "100.00",
// highlight-end
"trading": "0"
}
]
}
```
----------------------------------------
## Statuses
Description: Learn more about payment statuses.
Tags: Payments
Path: payments/status.mdx
[create-identity]: /api/v2#tag/Identity/operation/CreateIdentity
[help-desk]: https://support.paxos.com
[list-transfers]: /api/v2#tag/Transfers/operation/ListTransfers
[pay-in-monitor]: /payments/quickstart#pay-in-monitor-reconcile
[fiat-withdrawal]: /api/v2#tag/Fiat-Transfers/operation/CreateFiatWithdrawal
[withdraw-usd]: /payments/quickstart#pay-in-withdraw-fiat
[fund-account]: /payments/quickstart#refund-fund-account
[refunds]: /payments/quickstart#refunds
[create-crypto-withdrawal]: /api/v2#tag/Crypto-Withdrawals/operation/CreateCryptoWithdrawal
[onboarding]: /payments/faq#seller-onboarding
## Pay-ins
- [List Transfers][list-transfers]: When [monitoring a pay-in][pay-in-monitor], a `PENDING` a transaction is being confirmed. Depending on the network, confirmation can take from seconds to minutes. Transactions with a `COMPLETED` status have received sufficient confirmations. The `FAILED` status means the transaction was denied.
- [Create Fiat Withdrawal][fiat-withdrawal]: When [withdrawing USD to a bank account][withdraw-usd], the `PENDING` status means the request has been made and is being processes. Depending on the withdrawal type, it can take up to a few days for the transaction to complete. When the transfer to the bank account is successful, the status changes to `COMPLETED`.
## Refunds
- [List Transfers][list-transfers]: When [funding a USD account for refunds][fund-account], the transfer has an initial status of `PENDING`, meaning the USD deposit has been detected and is being confirmed. The `COMPLETED` status means the USD funds have been credited to the given Profile.
- [Create Crypto Withdrawal][create-crypto-withdrawal]: When [issuing a crypto refund][refunds], the withdrawal has an initial status of `PENDING`, meaning Paxos has received the request and is processing the transaction. Depending on the network, confirmation can take from seconds to minutes. The `COMPLETED` status indicates the transaction has been broadcasted to the blockchain and received the required number of confirmations.
### Onboarding
- [Create Identity][create-identity] (if applicable): When onboarding an Identity, the initial response includes the `PENDING` status while screening takes place. If the screenings fail, the identity may be `DENIED`.
> To minimize the occurrence of denied identities, contact [Support][help-desk] when planning an Identity workflow. Learn more about [user onboarding requirements][onboarding].
----------------------------------------
================================================================================
SECTION: SETTLEMENTS
================================================================================
## Settlements
Description: Propose, approve and manage two-way atomic transfers.
Tags: Settlements
Path: settlements/index.mdx
FeatureCard,
FeatureContainer,
} from "@site/src/components";
[create]: /api/v2#operation/CreateTransaction
[affirm]: /api/v2#operation/AffirmTransaction
[notification]: settlements/notification.mdx
[status]: settlements/status.mdx
Use the Settlements API to facilitate simultaneous exchange of pre-funded assets.
Automate a variety of use cases that require two-party approval, including
net settlement of over-the-counter trades, withdrawal requests for tri-party collateral, payment requests, and bilateral settlement for marketplace end users.
The simple request-and-approval workflow supports both one-directional and bidirectional transactions to allow a user to receive an asset (for example, send USDP) or simultaneously send and receive assets (for example, send USD and receive BTC and ETH).
Only when all parties are in agreement and assets are fully funded does the Settlements API allow for change of custody.
Upon completion, all settled assets are immediately available for trading, transferring, withdrawal or other supported activities.
## Settlement Workflow {#workflow}
The settlement workflow requires two parties to complete: The Source Profile owner who [initiates][create] the transaction and the Target Profile owner who [approves][affirm] the transaction.
Most integrations follow a similar workflow:
1. Both parties agree on the transaction details and share counterparty Profile IDs outside of the Paxos Platform (for example, via email, Telegram, or other application).
1. The Source Profile owner [submits the transaction][create] to the settlement platform.
1. The Target Profile owner receives a [notification][notification], reviews the transaction details and [approves the transaction][affirm].
1. Both parties fund the associated Profiles via deposits if the requisite balances are not already present.
1. Settlement (movement of assets between Profiles) occurs soon after both parties have sufficient assets on the platform.
1. Once the transaction [settles][status], both parties can immediately utilize the new balance.
## Get Started
Set up and complete the settlement workflow in the Sandbox environment.
Learn more about settlement statuses.
Understand how settlement notifications work.
Get answers to common questions about the Settlements API.
----------------------------------------
## Notifications
Description: Understand how settlement notifications work.
Tags: Settlements
Path: settlements/notification.mdx
[status]: status.mdx
[support]: https://support.paxos.com
[create]: /api/v2#operation/CreateTransaction
By default, each Profile owner receives an email notification when a settlement transaction is [created][create] and upon each [status][status] change.
Currently, only email notifications are supported.
Websocket and desktop notifications are being considered for future releases.
> To test email notifications in Sandbox, contact [Support][support] to enable notifications.
All settlement email notifications use the same template:
----------------------------------------
## FAQ
Description: Get answers to common questions about the Settlements API.
Tags: Settlements
Path: settlements/faq.mdx
[deposit]: /api/v2#tag/Sandbox-Deposits/operation/CreateSandboxDeposit
[support]: https://support.paxos.com
[status]: status.mdx
[assets]: blockchains.mdx
Do I need to have the right amount of assets before creating the transaction?
No.
You can create and approve the transaction first and then deposit [assets] when ready.
Settlement only takes place when the transaction is [affirmed][status] and all the required assets have been deposited.
Why am I not receiving email notifications when testing in Sandbox?
Notifications are off by default in Sandbox. Contact [Support][support] to turn them on.
Which assets are supported for Sandbox testing?
You can fund your Sandbox Account with the supported [assets] or those listed in [Create Sandbox Deposit][deposit].
For most setups, use the assets you can trade, transfer or withdraw for testing.
----------------------------------------
## Quickstart
Description: Set up and complete the settlement workflow in the Sandbox environment.
Tags: Quickstart, Settlements
Path: settlements/quickstart.mdx
[create-sandbox-deposit]: /api/v2#tag/Sandbox-Deposits/operation/CreateSandboxDeposit
[settlement-api]: /api/v2#tag/Settlement
[settle-faq]: settlements/faq.mdx
[api-management]: https://dashboard.sandbox.paxos.com/admin/api
[sandbox-account]: https://dashboard.sandbox.paxos.com
[workflow]: /settlements#workflow
[profiles]: /api/v2#tag/Profiles
[create-profile]: /api/v2#tag/Profiles/operation/CreateProfile
[fund]: #fund
[propose]: #propose
[profile-balances]: /api/v2#tag/Profiles/operation/ListProfileBalances
[get-profile-balance]: /api/v2#tag/Profiles/operation/GetProfileBalance
[approve]: #approve
[get-transaction]: /api/v2#operation/GetTransaction
[set-up-profiles]: #set-up-profiles
[create-transaction]: /api/v2#operation/CreateTransaction
[list-transactions]: /api/v2#operation/ListTransactions
[cancel-transaction]: /api/v2#operation/CancelTransaction
[status]: status.mdx
[faq-assets]: faq.mdx#assets
[affirm]: /api/v2#operation/AffirmTransaction
[authenticate]: #authenticate
[status-list-transactions]: status.mdx#list-transactions
[support]: https://support.paxos.com
[check-status]: #check-status
[Entity Manager]: dashboard/roles.mdx#entity-manager
The [settlement workflow][workflow] requires [two Profiles][set-up-profiles], referred to in this guide as Source Profile (`source_profile_id`) and Target Profile (`target_profile_id`).
The Profiles are under the same Sandbox Account for simplicity and to allow completion of the steps with a single [authentication][authenticate].
This guild also [funds][fund] the Source Profile with BTC and ETH for the `DELIVER` leg and USD in the Target Profile for the `RECEIVE` leg before [creating the transaction request][propose].
> Contact your [Entity Manager] or [Support][support] if you run into any issues or don't have access to a Sandbox Account.
## 1. Authenticate {#authenticate}
Add the `settlement:read_transaction` and `settlement:write_transaction` scopes to your [Sandbox Account][sandbox-account] under the [API Management][api-management] setting and then authenticate in Sandbox using the scopes.
Also include `funding:read_profile` and `funding:write_profile` for creating and funding [Profiles][profiles].
```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} \
// highlight-next-line
--form scope='settlement:read_transaction settlement:write_transaction funding:read_profile funding:write_profile'
```
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}",
// highlight-next-line
"expires_in": 3599, // Seconds (59 Minutes and 59 Seconds)
// highlight-next-line
"scope": "settlement:read_transaction settlement:write_transaction funding:read_profile funding:write_profile",
"token_type": "bearer"
}
```
## 2. Set Up Profiles {#set-up-profiles}
[Create][create-profile] two new Profiles in the Sandbox Account, one with `Source Profile` and the second with `Target Profile` as the `nickname`.
```shell
curl --location 'https://api.sandbox.paxos.com/v2/profiles' \
--header 'Authorization: Bearer {access_token}' \
--data '{
// highlight-next-line
"nickname": "Source Profile"
}'
```
You will need the `id` from the response to [fund the Profile][fund] and [propose a transaction][propose].
```json
{
// highlight-next-line
"id": "{profile_id}", // The source_profile_id in the Transaction object
"nickname": "Source Profile",
"type": "NORMAL"
}
```
```shell
curl --location 'https://api.sandbox.paxos.com/v2/profiles' \
--header 'Authorization: Bearer {access_token}' \
--data '{
// highlight-next-line
"nickname": "Target Profile"
}'
```
You will need the `id` from the response to [fund the Profile][fund] and [propose a transaction][propose].
```json
{
// highlight-next-line
"id": "{profile_id}", // The target_profile_id in the Transaction object
"nickname": "Target Profile",
"type": "NORMAL"
}
```
## 3. Fund Profiles {#fund}
Next, use [Create Sandbox Deposit][create-sandbox-deposit] to fund the Profiles.
:::note
This guide pre-funds all accounts prior to [creating a settlement request][propose] for simplicity.
However, it is possible to create and approve a settlement request [before the funds are available][faq-assets].
:::
Deposit crypto into the Source Profile.
First, Bitcoin:
```shell
curl --location 'https://api.sandbox.paxos.com/v2/sandbox/profiles/{profile_id}' \
--header 'Authorization: Bearer {access_token}' \
--data '
{
"asset": "BTC",
"amount": "2",
"crypto_network": "BITCOIN"
}'
```
Then add some Ethereum:
```shell
curl --location 'https://api.sandbox.paxos.com/v2/sandbox/profiles/{profile_id}' \
--header 'Authorization: Bearer {access_token}' \
--data '
{
"asset": "ETH",
"amount": "10",
"crypto_network": "ETHEREUM"
}'
```
Use [List Profile Balances][profile-balances] to retrieve the Source Profile balance.
Include the `assets` query parameter to filter out all other assets.
```shell
curl --location 'https://api.sandbox.paxos.com/v2/profiles/{profile_id}/balances?assets=BTC&assets=ETH' \
--header 'Authorization: Bearer {access_token}'
```
Confirm the Source Profile has at least 1 BTC and 5 ETH available for trading.
```json
{
"items": [
{
"asset": "BTC",
// highlight-next-line
"available": "2",
"trading": "0"
},
{
"asset": "ETH",
// highlight-next-line
"available": "10",
"trading": "0"
}
]
}
```
Deposit USD into the Target Profile.
```shell
curl --location 'https://api.sandbox.paxos.com/v2/sandbox/profiles/{profile_id}' \
--header 'Authorization: Bearer {access_token}' \
--data '
{
"asset": "USD",
"amount": "100000"
}'
```
Use [Get Profile Balance][get-profile-balance] to retrieve the Target Profile USD balance.
```shell
curl --location 'https://api.sandbox.paxos.com/v2/profiles/{profile_id}/balances/USD' \
--header 'Authorization: Bearer {access_token}'
```
Confirm the Target Profile has at least $50,000 USD available for trading.
```json
{
"asset": "USD",
// highlight-next-line
"available": "100000",
"trading": "0"
}
```
## 4. Propose Transaction {#propose}
Using the Source Profile and Target Profile `profile_id` [created earlier][set-up-profiles], use [Create Transaction][create-transaction] to propose exchanging 1 BTC and 5 ETH (in the Source Profile balance) for $50,000 USD (in the Target Profile balance). The `ref_id` must be unique. The settlement window defaults apply if `settlement_window_start` and/or `settlement_window_end` are not specified.
```shell
curl --location 'https://api.sandbox.paxos.com/v2/settlement/transactions' \
--header 'Authorization: Bearer {access_token}' \
--data '{
// highlight-next-line
"ref_id": "required_idempotence_id",
// highlight-next-line
"settlement_window_start": "YYYY-MM-DDT00:00:00Z",
// highlight-next-line
"settlement_window_end": "YYYY-MM-DDT00:00:00Z",
"source_profile_id": "{profile_id}",
"target_profile_id": "{profile_id}",
"legs": [
{
"direction": "DELIVER",
"asset": "BTC",
"amount": "1.00"
},
{
"direction": "DELIVER",
"asset": "ETH",
"amount": "5"
},
{
"direction": "RECEIVE",
"asset": "USD",
"amount": "50000.00"
}
]
}'
```
The acknowledgement response confirms the request has been received and provides the `Transaction` object.
The unique transaction `id` is used to [approve] and [retrieve][check-status] the transaction, and the Source Profile owner can use the `id` to [cancel][cancel-transaction] the `PENDING` transaction.
The transaction [status] can be used used by either party to [retrieve a list of filtered transactions][status-list-transactions].
```json
{
// highlight-next-line
"id": "{unique_transaction_id}",
"ref_id": "required_idempotence_id",
"settlement_window_start": "YYYY-MM-DDT00:00:00Z", // Defaults to current time
"settlement_window_end": "YYYY-MM-DDT00:00:00Z", // Defaults to settlement_window_start plus 24 hours
"source_profile_id": "{profile_id}",
"target_profile_id": "{profile_id}",
"legs": [
{
"id": "{unique_leg_1_id}",
"direction": "DELIVER", // From Source Profile
"asset": "BTC",
"amount": "1"
},
{
"id": "{unique_leg_2_id}",
"direction": "DELIVER", // From Source Profile
"asset": "ETH",
"amount": "5"
},
{
"id": "{unique_leg_3_id}",
"direction": "RECEIVE", // From Target Profile
"asset": "USD",
"amount": "50000"
}
],
// highlight-next-line
"status": "PENDING",
"created_at": "YYYY-MM-DDT00:00:00Z",
"updated_at": "YYYY-MM-DDT00:00:00Z"
}
```
## 5. Approve Transaction {#approve}
The Target Profile owner [approves (affirms)][affirm] the transaction.
:::note
Since the same Paxos Account is used for both counterparty Profiles in this guide, you can use the same [authentication][authenticate].
:::
Use the `Transaction.id` from the [propose step][propose] as the `transaction_id`.
You can also [look up a transaction by status][status-list-transactions] to find the `id`.
```shell
curl --location --request PUT 'https://api.sandbox.paxos.com/v2/settlement/transactions/{transaction_id}/affirm' \
--header 'Authorization: Bearer {access_token}'
```
The acknowledgement response includes transaction information and the `AFFIRMED` [status] and `updated_at` timestamp.
```json
{
"id": "{unique_transaction_id}",
"ref_id": "required_idempotence_id",
"settlement_window_start": "YYYY-MM-DDT00:00:00Z",
"settlement_window_end": "YYYY-MM-DDT00:00:00Z",
"source_profile_id": "{profile_id}",
"target_profile_id": "{profile_id}",
// highlight-next-line
"status": "AFFIRMED",
"created_at": "YYYY-MM-DDT00:00:00Z",
// highlight-next-line
"updated_at": "YYYY-MM-DDT00:00:00Z"
}
```
## 6. Check Transaction Status {#check-status}
Settlement of the `AFFIRMED` transaction occurs only when both counterparties fully fund their Profiles.
:::note
Since both Profiles in this guide are [pre-funded][set-up-profiles], the transaction settled within a few seconds.
:::
Either party can use [Get Transaction][get-transaction] to check the [status][status].
```shell
curl --location 'https://api.sandbox.paxos.com/v2/settlement/transactions/{transaction_id}' \
--header 'Authorization: Bearer {access_token}'
```
The response includes the complete `Transaction` object.
When the transaction completes, the [status][status] and `updated_at` timestamp reflect the most recent activity.
```json
{
"id": "{unique_transaction_id}",
"ref_id": "required_idempotence_id",
"settlement_window_start": "YYYY-MM-DDT00:00:00Z",
"settlement_window_end": "YYYY-MM-DDT00:00:00Z",
"source_profile_id": "{profile_id}",
"target_profile_id": "{profile_id}",
"legs": [
{
"id": "{unique_leg_1_id}",
"direction": "DELIVER",
"asset": "BTC",
"amount": "1"
},
{
"id": "{unique_leg_2_id}",
"direction": "DELIVER",
"asset": "ETH",
"amount": "5"
},
{
"id": "{unique_leg_3_id}",
"direction": "RECEIVE",
"asset": "USD",
"amount": "50000"
}
],
// highlight-next-line
"status": "SETTLED",
"created_at": "YYYY-MM-DDT00:00:00Z",
// highlight-next-line
"updated_at": "YYYY-MM-DDT00:00:00Z"
}
```
## Next Steps
- Create a settlement transaction before funding the Profiles.
- Learn more in the Settlements [FAQ][settle-faq].
- Explore settlement methods and objects in the [Settlements API][settlement-api].
----------------------------------------
## Statuses
Description: Learn more about settlement statuses.
Tags: Settlements
Path: settlements/status.mdx
[create]: /api/v2#operation/CreateTransaction
[cancel]: /api/v2#operation/CancelTransaction
[affirm]: /api/v2#tag/Settlement/operation/AffirmTransaction
[list]: /api/v2#operation/ListTransactions
[workflow]: index.mdx#workflow
The [settlement workflow][workflow] includes five statuses:
- `PENDING`: Initial state of a settlement transaction upon creation by the Source Profile owner (`source_profile_id`).
- `AFFIRMED`: The settlement transaction has been approved by the Target Profile owner (`target_profile_id`) and will be eligible for settlement once within the transaction window (`settlement_window_start` → `settlement_window_end`).
- `SETTLED`: The assets in the transaction have successfully been transferred.
- `EXPIRED`: The settlement transaction is no longer eligible for settlement.
- `CANCELED`: The settlement transaction was canceled by the Source Profile owner.
When a settlement transactions is [created][create], it starts in `PENDING` status.
The assets do not need to be available in the Profiles at this stage.
In the `PENDING` state, two actions can be taken:
- The Source Profile owner [cancels][cancel] the transaction. Status transitions to `CANCELLED`.
- The Target Profile owner [approves][affirm] the transaction. Status transitions to `AFFIRMED`.
Once the required asset balances are in the respective Profiles, settlement occurs. Status transactions to `SETTLED` when complete.
```mermaid
flowchart LR
A[PENDING] ==> | Target Profile owner approves | B[AFFIRMED] ==>C[SETTLED]
A --> | Settlement window expires | D[EXPIRED]
A --> | Source Profile owner cancels | E[CANCELLED]
B --> D
```
Transactions in the `PENDING` or `AFFIRMED` state at the end of the settlement window (`settlement_window_end`) automatically transition to `EXPIRED`.
## Find Transactions by Status {#list-transactions}
Either involved party can use [List Transactions][list] to retrieve all the transactions they are counterparty to.
Use the `statuses` query parameter to filter based on status.
:::note
You must specify the `limit` of items per page or an error returns.
:::
```shell
curl --location 'https://api.sandbox.paxos.com/v2/settlement/transactions?statuses=PENDING&statuses=AFFIRMED&limit=2' \
--header 'Authorization: Bearer {access_token}'
```
Based on the request parameters, the response contains the two most recent open transactions.
```json
{
"items": [
{
"id": "{unique_transaction_id}",
"ref_id": "required_idempotence_id_1",
"settlement_window_start": "YYYY-MM-DDT00:00:00Z",
"settlement_window_end": "YYYY-MM-DDT00:00:00Z",
"source_profile_id": "{profile_id}",
"target_profile_id": "{profile_id}",
"legs": [
{
"id": "{unique_leg_1_id}",
"direction": "DELIVER",
"asset": "BTC",
"amount": "1"
},
{
"id": "{unique_leg_2_id}",
"direction": "DELIVER",
"asset": "ETH",
"amount": "5"
},
{
"id": "{unique_leg_3_id}",
"direction": "RECEIVE",
"asset": "USD",
"amount": "40000"
}
],
// highlight-next-line
"status": "PENDING",
"created_at": "YYYY-MM-DDT00:00:00Z",
"updated_at": "YYYY-MM-DDT00:00:00Z"
},
{
"id": "{unique_transaction_id}",
"ref_id": "required_idempotence_id",
"settlement_window_start": "YYYY-MM-DDT00:00:00Z",
"settlement_window_end": "YYYY-MM-DDT00:00:00Z",
"source_profile_id": "{profile_id}",
"target_profile_id": "{profile_id}",
"legs": [
{
"id": "{unique_leg_1_id}",
"direction": "DELIVER",
"asset": "BTC",
"amount": "1"
},
{
"id": "{unique_leg_2_id}",
"direction": "DELIVER",
"asset": "ETH",
"amount": "5"
},
{
"id": "{unique_leg_3_id}",
"direction": "RECEIVE",
"asset": "USD",
"amount": "40000"
}
],
//highlight-next-line
"status": "AFFIRMED",
"created_at": "YYYY-MM-DDT00:00:00Z",
"updated_at": "YYYY-MM-DDT00:00:00Z"
}
],
//highlight-next-line
"next_page_cursor": "{page_cursor_value}"
}
```
To view more items, add the `page_cursor` query parameter to the request.
```shell
// highlight-next-line
curl --location 'https://api.sandbox.paxos.com/v2/settlement/transactions?limit=2&page_cursor={page_cursor_value}' \
--header 'Authorization: Bearer {access_token}'
```
----------------------------------------
================================================================================
SECTION: IDENTITY
================================================================================
## Periodic KYC Refresh
Description: Manage the periodic KYC refresh of an Identity on the Paxos Platform in an automated, compliant way.
Tags: Identity
Path: identity/kyc-refresh.mdx
[create-identity]: /api/v2#tag/Identity/operation/CreateIdentity
[update-identity]: /api/v2#tag/Identity/operation/UpdateIdentity
[get-identity]: /api/v2#tag/Identity/operation/GetIdentity
[webhooks]: /webhooks/quickstart.mdx
[reference]: /api/v2#tag/Events
[Support]: https://support.paxos.com
[events]: /api/v2#tag/Events
[consumer]: /webhooks/quickstart.mdx#consumer
[Get Event]: /api/v2#tag/Events/operation/GetEvent
[upload]: /api/v2#tag/Identity-Documents/operation/DocumentUpload
[List Events]: /api/v2#tag/Events/operation/ListEvents
[identity]: /api/v2#tag/Identity
To ensure that Paxos meets regulatory requirements, KYC information of end user identities that are directly onboarded
to Paxos must be periodically refreshed (every 1-3 years).
All customers that integrate with Paxos [Identity APIs][identity] are subject to this process, and must integrate with the automated workflow outlined below to support it.
Paxos streamlines KYC Refresh using a webhook-based or polling-based approach, which leverages [Paxos Webhooks][webhooks], [Events API][reference] and [Identity API][identity].
## Webhook-based Approach
### ➊ Consume KYC Refresh Events
Setup a [Webhook Consumer][consumer] to receive the following KYC refresh events for your end users:
- [`identity.kyc_refresh.started`][events]
- [`identity.kyc_refresh.completed`][events]
:::tip
Use [Get Event][Get Event] to get additional information about the KYC refresh event (`last_kyc_refresh_date`, `next_kyc_refresh_date`, etc.).
:::
### ➋ Prompt End User about Periodic Refresh
When an [`identity.kyc_refresh.started`][events] is received for your end user, prompt the user presenting their current KYC information indicating they should refresh their information if anything has changed, or continue without changes if everything is still accurate.
### ➌ Inform Paxos about the Refresh
When an end user indicates everything is still accurate, call [update-identity] with the `identity_id` specified in the request, setting the `last_kyc_refresh_date` to the timestamp the user confirmed their information is still accurate.
If an end user refreshed their information, call [update-identity] as specified above, but also include any changes the end user has made to their information.
:::info
Calling [update-identity] with only `last_kyc_refresh_date` and no other changes is considered by Paxos to be confirmation
no information has changed, therefore a completed KYC refresh.
The next KYC refresh date will be updated accordingly (1-3 years from the provided `last_kyc_refresh_date`).
:::
### ➍ Wait for Completion
Once KYC refresh is complete, a [`identity.kyc_refresh.completed`][events] will be received for the end user in question.
## Polling-based Approach
### ➊ Poll for KYC Refresh Started Events
Poll [List Events], offsetting the `created_at.gt` for each subsequent poll, fetching [`identity.kyc_refresh.started`][events] events.
:::info
We recommend you keep track of the [Event][events] ids you've processed in order to idempotently process the event.
:::
### ➋ Prompt End User about Periodic Refresh
As described [above](#-prompt-end-user-about-periodic-refresh) in the webhook-based approach.
### ➌ Inform Paxos about the Refresh
As described [above](#-inform-paxos-about-the-refresh) in the webhook-based approach.
### ➍ Poll for Completed Refreshes
Poll [List Events], offsetting the `created_at.gt` for each subsequent poll, fetching [`identity.kyc_refresh.completed`][events] events.
## Advanced
### Handling Expired Refreshes
If an [`identity.kyc_refresh.expired`][events] is received, it means Paxos did not receive an [update-identity] request in the designated window to complete the KYC refresh process _(typically 30 days)_.
If this occurs, several outcomes could be experienced:
- Paxos will restart the KYC refresh process, and a new [`identity.kyc_refresh.started`][events] event will be posted
- The Identity could be disabled (meaning the end user will only be able to Liquidate assets and withdraw fiat off platform)
### Refreshes in Compliance Review
In some cases, the Paxos compliance team might need to review the changes received from the end user as part of the
KYC refresh process.
In this case, the [`identity.kyc_refresh.completed`][events] event could experience a meaningful delay in being received.
### Backdating the Last KYC Refresh Date
If a historical record is known for the last KYC refresh dates of your end users **or** you've experienced an issue processing KYC refresh for an end-user then you can directly call [update-identity] setting the `last_kyc_refresh_date` to the known date in the past, and Paxos will accept this as the date KYC refresh was performed for the end user.
:::caution
Setting this date beyond the 1-3 year refresh period for an end user will cause an immediate [`identity.kyc_refresh.started`][events] to be triggered for the end user.
:::
----------------------------------------
## Enhanced Due Diligence
Description: Manage the enhanced due diligence of an Identity on the Paxos Platform.
Tags: Identity
Path: identity/edd.mdx
[create-identity]: /api/v2#tag/Identity/operation/CreateIdentity
[update-identity]: /api/v2#tag/Identity/operation/UpdateIdentity
[get-identity]: /api/v2#tag/Identity/operation/GetIdentity
[list-identity]: /api/v2#tag/Identity/operation/ListIdentities
[reference]: /api/v2#tag/Events
[Support]: https://support.paxos.com/
[events]: /api/v2#tag/Events
[webhooks]: /webhooks/index.mdx
[Get Event]: /api/v2#tag/Events/operation/GetEvent
[List Events]: /api/v2#tag/Events/operation/ListEvents
[upload]: /api/v2#tag/Identity-Documents/operation/DocumentUpload
[consumer]: /webhooks/quickstart.mdx
To ensure that Paxos meets regulatory requirements, when an identity is deemed high risk according to Paxos risk rating methodology, Paxos initiates a process called Enhanced Due Diligence (EDD).
This can occur during onboarding, or during the lifecycle of an active identity (for example, if identity information changes that impacts risk rating; if suspicious transaction patterns occur on the account).
When an identity enters the EDD process, Paxos requires the collection of documentary evidence supporting the initial KYC information provided.
Paxos streamlines the collection of EDD information using a webhook-based or polling-based approach, which leverages [Paxos Webhooks][webhooks], [Events API][reference] and [Document Upload API][upload].
## Webhook-based Approach
### ➊ Consume Documents Required Events
Setup a [Webhook Consumer][consumer] to receive `identity.documents_required` [events] for your end users.
### ➋ Fetch Required Documents
Call [Get Event] to fetch the event's `identity_documents_required` object, which will allow you to understand which documents are required.
### ➌ Upload the Required Documents
For the event's associated `identity_id`, call [Document Upload][upload] to upload the required documents, either synchronously if you already have the documents, or asynchronously if you need to reach back out to your customer for them to provide.
### ➍ Wait for Approval or Denial
This will be followed by an `identity.approved` or `identity.denied` event based on the onboarding decision for that end user (this might take up to 1 full business day to complete).
## Polling-based Approach
### ➊ Poll for Documents Required Events
Poll [List Events], offsetting the `created_at.gt` filter for each subsequent poll, fetching all `identity.documents_required` events.
:::info
Paxos recommends you keep track of the [Event][events] ids you've processed in order to idempotently process the event.
:::
### ➋ Upload the Required Documents
For the event's associated `identity_id`, call [Document Upload][upload] to upload the required documents, either synchronously if you already have the documents, or asynchronously if you need to reach back out to your customer for them to provide.
----------------------------------------
## Identity
Description: Onboard users directly to the Paxos Platform to accelerate speed to market and outsource your compliance needs.
Path: identity/index.mdx
FeatureCard,
FeatureContainer,
} from "@site/src/components";
## Get Started
Onboarding an Individual for Crypto Brokerage
Automate document collection to unblock onboarding high risk identities
Automate periodic kyc refresh to prevent users from losing access to trade
[webhooks]: /webhooks/index.mdx
[reference]: /api/v2#tag/Events
[edd]: /identity/edd.mdx
[kycrefresh]: /identity/kyc-refresh.mdx
[events]: /api/v2#tag/Events
----------------------------------------
## Statuses
Description: Learn more about Identity statuses and sub-statuses
Tags: Identity
Path: identity/statuses.mdx
[create-identity]: /api/v2#tag/Identities/operation/CreateIdentity
[onboarding-decision]: /identity/statuses#onboarding-decision
[automate-enhanced-due-diligence-guide]: /identity/edd
## Summary Status
An [Identity][create-identity] has five (5) statuses:
- `PENDING`: Initial state. The [Identity][create-identity] is waiting for an [Onboarding Decision][onboarding-decision] and is under review.
- `APPROVED`: The [Identity][create-identity] passed internal review. It can be used with integrations, for example, creating orders.
- `DENIED`: The [Identity][create-identity] failed internal review. It cannot be used with integrations.
- `DISABLED`: The [Identity][create-identity] was `APPROVED` but has been off-boarded. It can only perform sell operations.
- `ERROR`: The [Identity][create-identity] has been frozen for compliance reasons. It cannot be used with integrations.
This status drives what actions the identity can perform across the platform according to the grid below:
| Status | Hold Assets | Create Buy Orders | Create Sell Orders | Execute Open Orders | Create Crypto Deposit Address | Create Crypto Withdrawal | Receive Crypto Deposits |
|----------|-------------|-------------------|---------------------|----------------------|-------------------------------|--------------------------|--------------------------|
| `PENDING` | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `DENIED` | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `APPROVED` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `DISABLED` | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌* |
| `ERROR` | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌* |
_*Crypto deposits received to identities in disabled or error status will be held for review._
## Sub Statuses
The following sub-statuses are returned in identity responses and can be used to help explain why an [Identity][create-identity] is in a given summary status.
### Sanctions Verification Status (Individuals & Institutions)
- **Field**: `sanctions_verification_status`
- **`PENDING`**: Sanctions check in progress.
- **`DENIED`**: Sanctions hit found, cannot proceed.
- **`APPROVED`**: No sanctions hit found, cleared to proceed.
- **`ERROR`**: Possible sanctions hit, held for manual review.
### Additional Screening Status (Individuals & Institutions)
- **Field**: `additional_screening_status`
- **`PENDING`**: Additional screening checks are in progress.
- **`DENIED`**: Failed additional screening checks.
- **`APPROVED`**: Passed all additional screening checks.
- **`ERROR`**: Possible screening hit, held for manual review.
:::note
Additional screening includes checking for negative news or politically exposed persons, but explicitly excludes any sanctions checks (covered by the above `sanctions_verification_status`).
:::
### ID Verification Status (Individuals Only)
- **Field**: `id_verification_status`
- **`PENDING`**: Verification is in progress. Checking the identity of the individual.
- **`DENIED`**: Verification failed. Unable to verify the identity of the individual.
- **`APPROVED`**: Verification successful. The identity of the individual is confirmed.
:::note
When using passthrough IDV, the `id_verification_status` will reflect the `passthrough_verification_status` that was set. Note
that `passthrough_verification_status` can only ever be set to a terminal IDV status of `APPROVED` or `DENIED`.
:::
## Onboarding Decision {#onboarding-decision}
The onboarding decision is made based on the identities risk rating and the set of verifications (as exposed in sub-statuses above).
Once there is sufficient information to make a decision, the [Identity][create-identity] will be `APPROVED` and able to trade or `DENIED` and rejected services.
In the happy path where an [Identity][create-identity] is `LOW` or `MEDIUM` risk and all verifications automatically pass, the [Identity][create-identity] should be automatically `APPROVED` within seconds.
:::note
[Create Identity][create-identity] will always return an [Identity][create-identity] with a `PENDING` status as verifications are completed asynchronously. Poll until `APPROVED` or listen
to identity status update webhook events to get notified when the onboarding decision is made.
:::
If certain verifications fail (e.g. if there is a true sanctions hit), this will lead to a manual review and a `DENIED` decision. The standard SLA to come to a decision is 24 hours, make
sure to plan for this when building integrations.
When an [Identity][create-identity] is deemed `HIGH` risk, the [Identity][create-identity] will remain in `PENDING` until documents are provided and verified. See more on this topic in the [Automate Enhanced Due Diligence Guide][automate-enhanced-due-diligence-guide].
----------------------------------------
## Onboarding an Individual for Crypto Brokerage
Description: Create an Identity, Account and Profile to provide Buy, Hold and Sell Crypto Brokerage for Users
Tags: Identity
Path: identity/individual-crypto-brokerage.mdx
[Enhanced Due Diligence]: /identity/edd
[edd-guide]: /identity/edd
[Get Identity]: /api/v2#tag/Identity/operation/GetIdentity
[Identity]: /api/v2#tag/Identity
[identity-api]: /api/v2#tag/Identity
[identity-required-details]: /identity/required-details#required-individual-details
[identity-onboarding-decision]: /identity/statuses#onboarding-decision
[identity-status]: /identity/statuses
[Account]: /api/v2#tag/Accounts
[Add Account Members]: /api/v2#tag/Account-Members/operation/AddAccountMembers
[Remove Account Members]: /api/v2#tag/Account-Members/operation/DeleteAccountMember
[account-api]: /api/v2#tag/Accounts
[Profile]: /api/v2#tag/Profiles
[crypto-brokerage-fix]: /fix
[crypto-brokerage-websocket]: /api/websocket
[crypto-brokerage-fiat-crypto-subledger]: /crypto-brokerage/ledger-type#fiat-and-crypto-subledger
[crypto-brokerage-fiat-crypto-omnibus]: /crypto-brokerage/ledger-type#fiat-and-crypto-omnibus
[order-api]: /api/v2#tag/Orders
[fiat-transfers-quickstart]: /developer/fiat-transfers/quickstart
[fiat-transfers-api]: /api/v2#tag/Fiat-Transfers
[dashboard-signup]: /dashboard/account
[dashboard-create-api-key]: /dashboard/admin/api
[webhook]: /webhooks
[webhook-event]: /api/v2#tag/Events
[support]: https://support.paxos.com
This guide walks through setting up a [Fiat and Crypto Subledger][crypto-brokerage-fiat-crypto-subledger] crypto brokerage integration,
creating an Individual [Identity] and a related [Account] and [Profile] to book orders using the [Order API][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][account-api] 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][order-api] 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][dashboard-signup] in Sandbox
- Reach out to [Support][support] to provision access to the [Identity API][identity-api]
## Authenticate in Sandbox {#authenticate}
Create an [API Key][dashboard-create-api-key] on the Sandbox [Paxos Dashboard][dashboard-signup] with the following scopes to access the [Identity][identity-api],
[Account][account-api] and [Order][order-api] 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"
}
```
:::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
- The details of the person according to the [Individual Required Details Grid][identity-required-details]
- Data on who has completed identity verification (IDV) of the person.
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`.
```shell
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][identity-onboarding-decision] and asynchronously update the status to either `DENIED` or `APPROVED`.
```json
{
"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][edd-guide] 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`.
```shell
curl --location "https://api.sandbox.paxos.com/v2/identity/identities/${identity_id}" \
--request "GET" \
--header "Authorization: Bearer ${access_token}"
```
:::tip
- If the [Identity] is stuck in `PENDING`, read the [Identity Status][identity-status] guide to help pinpoint why. If you have further questions, you can reach out to [Support][support].
- Use a [Webhook][webhook] integration to asynchronously process [`identity.approved`][webhook-event] and [`identity.denied`][webhook-event]
events to notify users when they have been onboarded to Paxos.
:::
### ➌ 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][account-api].
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][crypto-brokerage-fiat-crypto-subledger] integration.
```shell
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"
}
}'
```
For accounts with more than one owner, for example a joint brokerage account, both owners are required to have an [Identity] created on the Paxos
Platform. An [Account] and [Profile] is then created for a designated primary account owner with any additional owners being set in `members` with the
`BENEFICIAL_OWNER` role.
[Identities][identity-api] can be added or removed from an [Account] after creation using the [Add Account Members] and [Remove Account Members] endpoints respectively
```shell
curl --location "https://api.sandbox.paxos.com/v2/identity/accounts" \
--request "POST" \
--header "Authorization: Bearer ${access_token}" \
--data '{
"create_profile": true,
"account": {
"identity_id": "'"${billy_duncan_identity_id}"'",
"ref_id": "{your_account_ref_id}",
"type": "BROKERAGE",
"description": "Brokerage account for Billy and Sarah Duncan",
"members": [{
"identity_id": "'"${sarah_duncan_identity_id}"'",
"roles": ["BENEFICIAL_OWNER"]
}]
}
}'
```
## Booking an Order
We will use the [Order][order-api] API to create buy and sell orders. We recommend also
taking a look at the [FIX][crypto-brokerage-fix] and [WebSocket][crypto-brokerage-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][fiat-transfers-quickstart] guide to learn how to fund user assets using
a [Fiat Deposit][fiat-transfers-api].
For this guide, we will use the sandbox-only Test Funds feature in [Dashboard](https://dashboard.sandbox.paxos.com/) to fund the [Identity] with $10,000 USD. First,
navigate to the [Dashboard Landing Page](https://dashboard.sandbox.paxos.com/) and locate the `Fund` button
Then select the [Profile] related to the [Account] created and fund for $10,000 USD
### ➋ 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`)_.
```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": "'"${identity_id}"'",
"identity_account_id": "'"${account_id}"'"
}'
```
```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": "'"${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 with Paxos!
----------------------------------------
## Required Details
Description: Learn more about what details are required when creating an Identity
Tags: Identity
Path: identity/required-details.mdx
[create-identity]: /api/v2#tag/Identity
## Key
| Value | Description |
|-------|:-----------------------------------|
| ✅ | Required field |
| 🟡 | (providing details here ensures less friction during onboarding)_ |
| -- | Not applicable |
## Required Individual Details
The required details for end-user individuals being onboarded as [Identities][create-identity] depend on the
licensing arrangement and solution. See the table below:
| Field | (Crypto Brokerage) |
|----------------------------------|:-----------------------------------------------------------------:|
| `first_name` | ✅ |
| `last_name` | ✅ |
| `date_of_birth` | ✅ |
| `address` | ✅ |
| `nationality` | ✅ |
| `cip_id` | ✅ |
| `cip_id_type` | ✅ |
| `cip_id_country` | ✅ |
| `cdd.estimated_yearly_income` | ✅ |
| `cdd.expected_transfer_value` | ✅ |
| `cdd.source_of_wealth` | ✅ |
| `cdd.employment_status` | ✅ |
| `cdd.employment_industry_sector` | ✅ |
| `middle_name` | 🟡 |
| `phone_number` | 🟡 |
| `email` | 🟡 |
| `profession` | -- |
| `country_of_birth` | -- |
| `cdd.aliases` | -- |
| `cdd.estimated_net_worth` | -- |
| `cdd.customer_regions` | -- |
| `cdd.source_of_funds` | -- |
| `cdd.purpose_of_account` | -- |
----------------------------------------