Move money to and from wallets

Create a wallet

Create a new custodial wallet for an individual user or for your company treasury.

• All wallet users must have a country on file.
• U.S. users must also have their state recorded.
• To create a wallet for yourself, first create a customer ID that represents your company.

Request

curl --request POST \
     --url https://api.bridge.xyz/v0/customers/{customerId}/wallets \
     --header 'Api-Key: <API Key>' \
     --header 'Idempotency-Key: <Unique Idempotency Key>' \
     --header 'Content-Type: application/json' \
     --data '{
       "chain": "solana"
     }'

Response

{
  "id": "uuid",
  "chain": "solana",
  "address": "the-blockchain-address",
  "created_at": "2024-09-01T02:03:04.567Z",
  "updated_at": "2024-09-01T02:03:04.567Z"
}

Save the wallet id. It’s required for all future transfers or orchestration calls.

Moving money using orchestration

All fund movements into or out of a Bridge wallet can be done through orchestration APIs. You can build flexible payment workflows to and from your Bridge wallet using any of the following APIs:

• Transfers - Move money to and from a Bridge wallet. You can specify a Bridge wallet as a source or destination for a transfer.
• Liquidation Address - Auto forward funds sent to a crypto address directly to your Bridge wallet. To do so, you can specify a Bridge wallet as the destination for the liquidation address.
• Virtual Accounts - Automatically convert fiat currency sent to your customer’s virtual account and send those funds to a Bridge wallet. Check out Onramp stablecoins using Bridge Wallet & Virtual Account.

Here’s an example of a transfer sending funds to a Bridge Wallet:

Request

curl --location --request POST 'https://api.bridge.xyz/v0/transfers' \
--header 'Api-Key: <API Key>' \
--header 'Idempotency-Key: <Unique Idempotency Key>' \
--data-raw '{
  "amount": "10.0",
  "on_behalf_of": "cust_alice",
  "developer_fee": "0.5",
  "source": {
    "payment_rail": "wire",
    "currency": "usd",
  },
  "destination": {
    "payment_rail": "solana",
    "currency": "usdb",
    "bridge_wallet_id": "the-wallet-uuid"
  },
}'

Wallets that require initiation data

Some Bridge Wallets require payment initiation data when they are used as a transfer source. Fetch the wallet before creating the transfer. If the wallet response includes initiation_required: true, include an initiation object in the Create Transfer request. If the field is omitted, do not include initiation.

Send initiation only in the Create Transfer request. Bridge accepts it for compliance checks, but the field is not included in Create Transfer, Get Transfer, or List Transfers responses.

Bridge Wallet response

{
  "id": "wallet_123",
  "chain": "solana",
  "address": "the-blockchain-address",
  "initiation_required": true,
  "created_at": "2024-09-01T02:03:04.567Z",
  "updated_at": "2024-09-01T02:03:04.567Z"
}

Transfer request

{
  "amount": "10.0",
  "on_behalf_of": "cust_alice",
  "source": {
    "payment_rail": "bridge_wallet",
    "currency": "usdb",
    "bridge_wallet_id": "wallet_123"
  },
  "destination": {
    "payment_rail": "ach",
    "currency": "usd",
    "external_account_id": "external_account_123"
  },
  "initiation": {
    "channel": "other_mobile_payment",
    "subchannel": "remote",
    "attestations": {
      "sca": {
        "outcome": "sca_used",
        "auth_factors": [
          {
            "category": "possession",
            "authenticated_at": "2026-05-21T16:00:00Z",
            "reference": "auth_session_123"
          },
          {
            "category": "knowledge",
            "authenticated_at": "2026-05-21T16:00:05Z",
            "reference": "pin_check_456"
          }
        ]
      }
    }
  }
}

Use the same initiation payload when retrying a Create Transfer request with the same idempotency key.

---

Get Wallet Balance

Retrieve the balance of a specific wallet.

Request

curl --request GET  
     --url <https://api.bridge.xyz/v0/customers/customerId/wallets/walletId>  
     --header 'Api-Key: <API Key>'  
     --header 'accept: application/json'

Response

{  
  "id": "uuid",  
  "chain": "solana",  
  "address": "the-blockchain-address",  
  "created_at": "2024-09-01T02:03:04.567Z",  
  "updated_at": "2024-09-01T02:03:04.567Z",  
  "balances": [  
    {
      "balance": "123.456789",
      "currency": "usdb",  
      "chain": "solana",
      "contract_address": "ENL66PGy8d8j5KNqLtCcg4uidDUac5ibt45wbjH9REzB",  
    }  
  ]  
}

Get Total Wallet Balance

Fetch the aggregate balance of all wallets under your developer account.

Request

curl --request GET  
     --url <https://api.bridge.xyz/v0/wallets/total_balances>  
     --header 'Api-Key: <API Key>'  
     --header 'accept: application/json'

Response

[  
  {  
    "balance": "123.456789",
    "currency": "usdb",  
    "chain": "solana",
    "contract_address": "ENL66PGy8d8j5KNqLtCcg4uidDUac5ibt45wbjH9REzB"
  }  
]

List All Wallets

Allows you to get all the wallets associated with your developer id.

List all wallets

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

List all wallets for a specific customer

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

Track Wallet Activity

Use the Bridge Wallet history endpoint to retrieve deposits, direct deposits, withdrawals, returns, and undeliverables for a wallet in one consistent activity model.

You can enable webhook delivery for wallet activity by creating or updating a webhook endpoint subscribed to bridge_wallet.activity.

Request

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

You can pair this endpoint with Bridge Wallet activity webhooks to monitor new activity without polling.