Skip to main content

Convert

Implement guaranteed 1:1 conversions between USD and Paxos-issued stablecoins.

Next, use the Stablecoin Conversion API to easily convert USD to any supported asset, and vice verse, without any fees. Keep track of all your conversions with List Stablecoin Conversions or lookup a single conversion.

If you've already authenticated and have USD and USDG balances in a Profile, skip ahead to the request a conversion step.

➊ Authenticate​

Include the following scopes when authenticating:

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, contact Support.

➋ Deposit USD and USDG​

Use 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 if you've already set up a Fiat Account.

curl --request POST \
--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"
}'

➌ Request Conversion​

Request a conversion using Create Stablecoin 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, you must also specify identity_id and account_id. Values for identity_id and account_id default to 00000000-0000-0000-0000-000000000000 when the fields are not part of the request.

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".

{
    "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",
    ...
}

➍ Confirm the Conversion​

Use List Stablecoin Conversions to check the conversion status. The request requires the profile_id query parameter.

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.

{
    "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​

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 AssetMaximum Decimal PrecisionExample Conversion Precision
USD0.01 (1e-2)USD → USDG = 0.01 (1e-2)
PYUSD0.000001 (1e-6)PYUSD → USD = 0.01 (1e-2)
USDG0.00000001 (1e-8)USDG → USD = 0.01 (1e-2)
USDP0.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 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.

Best Practice
  • Build a pending conversion settlement workflow for edge cases where the conversion does not settle immediately. This is especially important for subledgered customers, where the user will be unable to sell or transfer the assets until the conversion has settled and the asset has been credited to their Profile.
  • 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.