Quickstart

Set up and complete the settlement workflow in the Sandbox environment.

The settlement workflow requires two 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. This guild also funds 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.

note

Reach out to your Paxos Representative or contact Support if you run into any issues or don't have access to a Sandbox Account.

1. Authenticate

Add the settlement:read_transaction and settlement:write_transaction scopes to your Sandbox Account under the 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.

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='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.

{
  "access_token": "{access_token}",
  "expires_in": 3599, // Seconds (59 Minutes and 59 Seconds)
  "scope": "settlement:read_transaction settlement:write_transaction funding:read_profile funding:write_profile",
  "token_type": "bearer"
}

2. Set Up Profiles

Create two new Profiles in the Sandbox Account, one with Source Profile and the second with Target Profile as the nickname.

Create Source Profile

curl --location 'https://api.sandbox.paxos.com/v2/profiles' \
--header 'Authorization: Bearer {access_token}' \
--data '{
  "nickname": "Source Profile"
}'

You will need the id from the response to fund the Profile and propose a transaction.

{
    "id": "{profile_id}", // The source_profile_id in the Transaction object
    "nickname": "Source Profile",
    "type": "NORMAL"
}

Create Target Profile

curl --location 'https://api.sandbox.paxos.com/v2/profiles' \
--header 'Authorization: Bearer {access_token}' \
--data '{
  "nickname": "Target Profile"
}'

You will need the id from the response to fund the Profile and propose a transaction.

{
    "id": "{profile_id}", // The target_profile_id in the Transaction object
    "nickname": "Target Profile",
    "type": "NORMAL"
}

3. Fund Profiles

Next, use Create Sandbox Deposit to fund the Profiles.

note

This guide pre-funds all accounts prior to creating a settlement request for simplicity. However, it is possible to create and approve a settlement request before the funds are available.

Fund Source Profile

Deposit crypto into the Source Profile. First, Bitcoin:

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:

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 to retrieve the Source Profile balance. Include the assets query parameter to filter out all other assets.

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.

{
    "items": [
        {
            "asset": "BTC",
            "available": "2",
            "trading": "0"
        },
        {
            "asset": "ETH",
            "available": "10",
            "trading": "0"
        }
    ]
}

Fund Target Profile

Deposit USD into the Target Profile.

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 to retrieve the Target Profile USD balance.

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.

{
    "asset": "USD",
    "available": "100000",
    "trading": "0"
}

4. Propose Transaction

Using the Source Profile and Target Profile profile_id created earlier, use 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.

curl --location 'https://api.sandbox.paxos.com/v2/settlement/transactions' \
--header 'Authorization: Bearer {access_token}' \
--data '{
  "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": [
    {
        "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 the transaction, and the Source Profile owner can use the id to cancel the PENDING transaction. The transaction status can be used used by either party to retrieve a list of filtered transactions.

{
    "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"
        }
    ],
    "status": "PENDING",
    "created_at": "YYYY-MM-DDT00:00:00Z",
    "updated_at": "YYYY-MM-DDT00:00:00Z"
}

5. Approve Transaction

The Target Profile owner approves (affirms) the transaction.

note

Since the same Paxos Account is used for both counterparty Profiles in this guide, you can use the same authentication.

Use the Transaction.id from the propose step as the transaction_id. You can also look up a transaction by status to find the id.

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.

{
    "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}",
    "status": "AFFIRMED",
    "created_at": "YYYY-MM-DDT00:00:00Z",
    "updated_at": "YYYY-MM-DDT00:00:00Z"
}

6. Check Transaction 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, the transaction settled within a few seconds.

Either party can use Get Transaction to check the status.

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 and updated_at timestamp reflect the most recent activity.

{
    "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"
        }
    ],
    "status": "SETTLED",
    "created_at": "YYYY-MM-DDT00:00:00Z",
    "updated_at": "YYYY-MM-DDT00:00:00Z"
}

Next Steps

• Create a settlement transaction before funding the Profiles.
• Learn more in the Settlements FAQ.
• Explore settlement methods and objects in the Settlements API.