Migrating to OUSD

USDx is a placeholder used throughout this guide. Wherever you see usdx or USDx, substitute the stablecoin you’re actually migrating from (for example, USDB or USDC). OUSD always refers to the stablecoin you’re migrating to.

The precise technical steps vary depending on your desired migration path (same chain or cross chain) and your current model. Use the table below to determine your migration path.

Migration path	Guidance
USDx to OUSD on the same chain	Standard migration path; use the guide below.
USDx to OUSD across chains	Mimics a new operational set-up; follow the standard integration path: • Create new custodial wallet(s) / virtual account(s) on the network of your choice. • Create new payment routes (liquidation addresses, static transfer templates) directing to your new wallets / accounts. • Initiate a transfer from your existing wallet to your new wallet.

Overview

The standard migration involves six main steps. Bridge highly recommends executing them in order to ensure an issue-free migration.

Halt payments temporarily (planned downtime) — temporarily stop new activity that could increment or reduce your Bridge wallet balance (e.g. incoming deposits or outgoing withdrawals) to avoid customer payment disruption during the migration window.
Update liquidation addresses — change the destination currency from usdx to ousd.
Update static transfer templates — change the destination currency and close out any active transfers still awaiting USDx.
Update virtual accounts — change the destination currency from usdx to ousd.
Migrate wallet balances — transfer funds from USDx to OUSD by creating transfers per wallet.
Resume operations — resume new activity now that migration is complete.

Prerequisites

Before starting the migration, ensure you have the following:

Your Bridge API key
A list of all your liquidation address IDs (per customer)
A list of all your static transfer template IDs (if applicable)
A list of all your virtual account IDs (per customer, if applicable)
A list of all your wallet IDs and their associated chains
No in-flight transfers or wallet funding in progress

Prefunded wallets: Ensure you are on the updated Bridge Wallet APIs before proceeding with the migration. If you are still on the deprecated Prefunded Account APIs, moving to Bridge Wallets is a hard prerequisite. See the migration path.

Rate limits apply throughout the migration:

Limit	QPS	Burst	Scope
Reads (GET/HEAD)	50 qps	60	All API read endpoints
Writes (POST/PUT/PATCH/DELETE)	10 qps	11	All API write endpoints

Step 1: Halt active transactions

Before making any changes, stop all new activity:

Stop initiating new transfers (both on-ramp and off-ramp)
Stop funding wallets with new deposits
Wait for any in-flight transfers to reach a terminal state (payment_processed, canceled, etc.)

This prevents race conditions where a USDx transaction lands mid-migration, causing balance discrepancies.

Step 2: Update liquidation addresses

For each customer, update every liquidation address to change the destination currency from usdx to ousd.Step 2a: List your liquidation addressesRetrieve all liquidation addresses for a customer to identify which ones use USDx.API Reference: Get all liquidation addresses for a customer

Request

curl --location --request GET 'https://api.bridge.xyz/v0/customers/{customer_id}/liquidation_addresses' \
--header 'Api-Key: <API Key>'

Step 2b: Update each liquidation addressAPI Reference: Update a liquidation address

Request

curl --location --request PUT 'https://api.bridge.xyz/v0/customers/{customer_id}/liquidation_addresses/{liquidation_address_id}' \
--header 'Api-Key: <API Key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "destination": {
    "currency": "ousd"
  }
}'

You must iterate through each liquidation address for each customer. There is no bulk update endpoint.
Only the destination.currency field is being changed for a same-chain migration. The address and payment rail otherwise remain the same.
Verify the update was successful by checking that the response shows "currency": "ousd" in the destination.

Step 3: Update static transfer templates

If you use static transfer templates, update each template’s destination currency from usdx to ousd and close out any active transfers still awaiting USDx funds.Step 3a: List your static transfer templatesRetrieve all your static transfer templates to identify which ones use USDx.API Reference: Get all transfers

Request (all templates)

curl --location --request GET 'https://api.bridge.xyz/v0/transfers/static_templates' \
--header 'Api-Key: <API Key>'

Request (per customer)

curl --location --request GET 'https://api.bridge.xyz/v0/customers/{customer_id}/transfers/static_templates' \
--header 'Api-Key: <API Key>'

Step 3b: Update the destination currencyFor each static transfer template that uses USDx as the destination currency, update it to OUSD.API Reference: Update a transfer

Request

curl --location --request PUT 'https://api.bridge.xyz/v0/transfers/{transfer_id}' \
--header 'Api-Key: <API Key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "destination": {
    "currency": "ousd",
    "payment_rail": "ethereum"
  }
}'

Replace payment_rail with your preferred chain.

After updating the template, new transfers created from it will use ousd as the destination.
You must iterate through each static transfer template individually. There is no bulk update endpoint.

Step 3c: Close out active transfers awaiting USDxAny active transfers created from a static template that are still in the awaiting_funds state and expecting USDx should be deleted, since they will no longer receive USDx deposits.API Reference: Delete a transfer

Request

curl --location --request DELETE 'https://api.bridge.xyz/v0/transfers/{transfer_id}' \
--header 'Api-Key: <API Key>'

Only transfers in the awaiting_funds state can be deleted. Transfers that have progressed past this state must settle naturally.

Step 4: Update virtual accounts

If you use virtual accounts, update each virtual account’s destination currency from usdx to ousd.Step 4a: List your virtual accountsRetrieve all virtual accounts for a customer to identify which ones use USDx.API Reference: List virtual accounts by customer

Request

curl --location --request GET 'https://api.bridge.xyz/v0/customers/{customer_id}/virtual_accounts' \
--header 'Api-Key: <API Key>'

Step 4b: Update each virtual accountAPI Reference: Update a virtual account

Request

curl --location --request PUT 'https://api.bridge.xyz/v0/customers/{customer_id}/virtual_accounts/{virtual_account_id}' \
--header 'Api-Key: <API Key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "destination": {
    "currency": "ousd"
  }
}'

You must iterate through each virtual account for each customer. There is no bulk update endpoint.
Only the destination.currency field is being changed for a same-chain migration. Deposit instructions otherwise remain the same.
Verify the update was successful by checking that the response shows "currency": "ousd" in the destination.

Step 5: Migrate wallet balances

For each wallet, create a transfer that moves the full USDx balance into OUSD.Step 5a: List your walletsRetrieve all Bridge wallets for a customer to identify which ones hold a USDx balance.API Reference: Get all Bridge wallets for a customer

Request

curl --location --request GET 'https://api.bridge.xyz/v0/customers/{customer_id}/wallets' \
--header 'Api-Key: <API Key>'

Step 5b: Get each wallet’s USDx balanceAPI Reference: Get a Bridge wallet

Request

curl --location --request GET 'https://api.bridge.xyz/v0/wallets/{wallet_id}' \
--header 'Api-Key: <API Key>'

In the response, find the entry in the balances array where currency is "usdx". The balance field is the amount you will transfer.

Response (excerpt)

{
  "id": "wallet_123",
  "balances": [
    {
      "balance": "50000.00",
      "currency": "usdx",
      "chain": "ethereum"
    }
  ]
}

Step 5c: Create the transferFor each wallet with a USDx balance, create a transfer to convert the full balance from USDx to OUSD.API Reference: Create a transfer

Request

curl --location --request POST 'https://api.bridge.xyz/v0/transfers' \
--header 'Api-Key: <API Key>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: migration-wallet-123-usdx-to-ousd' \
--data-raw '{
  "on_behalf_of": "customer_abc",
  "amount": "50000.00",
  "source": {
    "currency": "usdx",
    "payment_rail": "bridge_wallet",
    "bridge_wallet_id": "wallet_123"
  },
  "destination": {
    "currency": "ousd",
    "payment_rail": "ethereum",
    "to_address": "0xYourWalletAddress"
  }
}'

Replace payment_rail with the chain your wallet is on (e.g. ethereum, solana, base, arbitrum, polygon, etc.). For a same-chain migration, this must match the wallet’s current chain.

Create one transfer per wallet per customer.
Use the full balance from the GET wallet response. Do not leave partial USDx balances.
Use a unique Idempotency-Key per transfer to safely retry on failure (e.g. migration-{wallet_id}-usdx-to-ousd).
Monitor the transfer state — wait for it to reach payment_processed before proceeding.

Step 6: Resume operations

Once liquidation addresses, static transfer templates, virtual accounts, and wallet balances have all been migrated:

Resume initiating new transfers using ousd as the currency (on the destination chain, for cross-chain migrations)
Resume wallet funding
Resume initiating prefunded transfers, if applicable — these will now use OUSD as the source currency
Verify your systems are reading ousd balances correctly

Rollback

If you need to reverse the migration, follow the steps in reverse order:

Halt transactions again
Create transfers from OUSD back to USDx for each wallet (swap source and destination currencies)
Update virtual accounts back to usdx
Update static transfer templates back to usdx
Update liquidation addresses back to usdx
Resume operations

Pending USDx deposits: Any USDx that arrives after the fact (e.g. from in-flight transactions that settle late) should be:

Excluded from your aggregated USD balance, or
Shown as a pending balance that is not yet available for transactions

Any straggler USDx must be converted to OUSD (by creating a transfer as described in Step 5) before it can be included in your total USD balance and used for new transactions. Failing to account for this may result in your system showing an inflated balance that includes funds not yet available in OUSD.

Orchestration

Wallets

Issuance

Cards

Customers

Logistics

Additional information

Migrating to OUSD

Overview

Prerequisites

Step 1: Halt active transactions

Step 2: Update liquidation addresses

Step 3: Update static transfer templates

Step 4: Update virtual accounts

Step 5: Migrate wallet balances

Step 6: Resume operations

Rollback

​Overview

​Prerequisites

Step 1: Halt active transactions

Step 2: Update liquidation addresses

Step 3: Update static transfer templates

Step 4: Update virtual accounts

Step 5: Migrate wallet balances

Step 6: Resume operations

​Rollback

Overview

Prerequisites

Rollback