Accounts & Wallets

An account is a structure that is owned by an identity and has the underlying infratructure or connectivity to interact with stablecoins or fiat.

It is important to configure this correctly, including the web3 wallet provider choice. Please contact us if you have any questions during this process.

Accounts are ultimately linked to identities as a way to streamline and coalesce all places you may hold funds. This is generally a web3 wallet with stablecoins, but can also be your balance with a PFI in local fiat currency. Either way, an account is a flexible object to facilitate streamlined and standardized interactions with any PFI, or underlying infrastructure that suites you best.

If you’re just getting started, please check out our quick start guide.

Account structure diagram

Overview

Accounts help you group and organize multiple blockchain wallet addresses under a single logical entity, allowing you to operate on an account level rather than dealing with raw blockchain addresses directly. Accounts also facilitate seamless workflows between your blockchain wallets and your local fiat accounts held at some PFIs. Structure

Each Identity in the system is associated with: One Account and Multiple SubAccounts
Each Account (including SubAccounts) can hold multiple Assets, but an asset cannot be duplicated within the same Account.

It is important to note, Borderless is never in the flow of funds. These accounts are either custodied with the PFI, the wallet provider, or self-custodied by the identity itsself. We do not provide any form of custody and we never initiate any movement of funds on behalf of the identity.

SubAccounts

SubAccounts function the same way as standard Accounts but follow the configuration and rules defined by the Primary Account. The only difference lies in the creation process, which is covered in the sections below on Account Creation and SubAccount Creation. In all other operations — including Virtual Accounts, Withdrawals, Deposits, Transfers, and Asset Deposits — there is no difference between an Account and a SubAccount. Throughout this documentation, the term Account refers to both Accounts and SubAccounts, unless explicitly stated otherwise.

Web3 wallet infrastructure

Web3 wallet infrastructure enables your organization to interact with web3 in a fast and convenient way. We offer several integration options depending on your infrastructure setup and needs. Please click through the tabs below to explore the different options you have available.

Bring Your Own Wallet
Utila
Dfns
Fireblocks
Multi-Provider

Standalone wallet infrastructure details

Best for advanced teams with custom infrastructure, or those looking for ultimate flexibility.

We support direct blockchain address usage, allowing you to connect with any web3 infrastructure you prefer. You manage all web3 interactions yourself — we provide the necessary endpoints and flexibility.
In this setup, an Account within Borderless acts only as a wrapper around your existing blockchain addresses.
Borderless can:

Read and display on-chain data: balances, transactions
Execute asset deposits to your addresses (Deposits, Asset-Deposits)
We cannot execute any outbound transactions from your address.

Instead, for operations like withdrawals, we generate a transaction instructions, which includes all necessary transaction data, and a pre-built blockchain transaction payload.
You are responsible for executing this transaction on-chain using your own infrastructure.
Once the transaction is confirmed, the withdrawal flow continues as expected on the Borderless platform.

All outbound transaction signing happens on your side using your standalone wallet — Borderless does not manage key material or signing operations.

58bd47a7761ee720577cda86e4d1ee9a5efc78080987138759edf48cba9d277f-Standalone Sv

Web3 Accounts

Step 1: Web3 Account creation

Let’s create our first account. Please use the tabs to explore specific account creation examples for the web3 infrastructure you use. After this, we will add stablecoin assets.

Please capture account id from the response to use it as needed later.

Bring Your Own Wallet
Utila
Dfns

With this provider, Account-level configuration is not required. Blockchain addresses are linked directly to Account Assets, not the Account itself. As such, no additional fields are required for creating Accounts or SubAccounts:

Endpoint: POST /accounts

curl -X POST "https://sandbox-api.borderless.xyz/v1/accounts" \
	 -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \
	 -H "idempotency-key: 8f14e45f-e6c3-4f7e-bd56-1b9a2e46f1d6"\
	 -d '{
  			"name": "Main Account",
  			"identityId": "cm34yhws000343brvezoqdqn0"
		}'

{
  "id": "cm9db4g2s2r7ro224ra6u1qvl",
  "type": "web3",
  "pfi": null,
  "web3Provider": "Standalone",
  "name": "Main Account",
  "addresses": [
    {
      "id": "cm9db4g2s2r7ro224ra6u1qvl",
      "asset": "USDC_POLYGON",
      "address": "0xE79a68B87544ed42Cc5aA805bb056201e7942D3A"
    }
  ],
  "assets": [
    {
      "id": "cm9db4g2s2r7ro224ra6u1qvl",
      "asset": "USDC_POLYGON",
      "address": "0xE79a68B87544ed42Cc5aA805bb056201e7942D3A"
    }
  ],
  "fiats": [],
  "identityId": "cm34yhws000343brvezoqdqn0",
  "createdAt": "2025-11-19T01:10:26.466Z"
}

Enable Utila as your infrastructure provider

Before using the Utila provider, you must already have access to Utila infrastructure and it must be integrated with your system. To enable Borderless-Utila integration, follow these steps:

Go to your Utila console and open your organization.
Open the Service Accounts tab.
Create a new Service Account.
Copy the Service Account Id and private RSA Key and use them to configure your Borderless integration.
Important: Ensure you grant read-only permissions only. Do not include Write, Create, Sign, or Update permissions. Borderless does not require them and assumes no responsibility if they are granted.

To configure Borderless, use the following API endpoint:

Endpoint: PUT /organizations/integrations/utila

curl -X POST "https://sandbox-api.borderless.xyz/v1/organizations/integrations/utila" \
	 -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \
	 -H "idempotency-key: 8f14e45f-e6c3-4f7e-bd56-1b9a2e46f1d6"\
	 -d {
       "utilaServiceAccount": "sa_1234567890abcdef",
       "utilaPrivateRSAKey": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADAN..."
     }

Create account and add assets with Utila

Once you have linked your Utila account for streamlined interoperability, you can set up an account with your Utila infrastructure similarly to how you would for standalone wallets.The main difference is when adding an asset to a Borderless Account, you must include the corresponding utilaServiceAccount of a wallet that already exists in your Utila setup.When using Utila, Borderless does not link the Account entity directly to a Utila wallet.
Instead, the linkage is done at the Asset level, during asset address assignment. Therefore, no additional fields are required when creating an Account or SubAccount under Utila.

Endpoint: POST /accounts/

curl -X POST "https://sandbox-api.borderless.xyz/v1/accounts/" \
	 -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \
	 -H "idempotency-key: 8f14e45f-e6c3-4f7e-bd56-1b9a2e46f1d6"\
	 -d '{
          "vaultId": "Utila Vault id",
          "walletId": "Utila Wallet id", // optional
        
          "name": "Account Name",
          "identityId": "Id of Identity",
          
          "assets": [
            {
              "asset": AssetId
            }
          ]
        }'

Enable Dfns as your infrastructure provider

Before using the Dfns provider, you must already have access to Dfns infrastructure and it must be integrated with your system. To enable Borderless-Dfns integration, follow these steps:

Go to your Dfns console and open your organization.
From the left menu, navigate to Settings.
Open the Service Accounts tab.
Create a new Service Account (e.g. named Borderless Integration) and fill in all required fields.
Create a new Permission set including only:
“Wallets:Transactions:Read”, “Wallets:Transfers:Read”, “Wallets:ReadTransaction”, “Wallets:ReadTransfer”
Important: Ensure you grant read-only permissions only. Do not include Write, Create, Sign, or Update permissions. Borderless does not require them and assumes no responsibility if they are granted.
After creation, open the Service Account and assign Permissions.

Copy the auth token and use it along with your appId to configure your Borderless integration. To configure Borderless, use the following API endpoint:

Endpoint: PUT /organizations/integrations/dfns

curl -X POST "https://sandbox-api.borderless.xyz/v1/organizations/integrations/dfns" \
	 -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \
	 -H "idempotency-key: 8f14e45f-e6c3-4f7e-bd56-1b9a2e46f1d6"\
	 -d {
  		"dfnsAppId": "ap-66rrf-kcjqj-8ppri8f3aa4h6opn",
  		"dfnsAuthToken": "eyJ1eXAiOiJKV1QiLCJhbGciOiJFZERTQSJ9.eyJpc3MiOiJhdXRoLmRmbnMubmluamEiLCJhdWQiOiJkZm5zOmF1dGg6dXNlciIsInN1YiI6Im9yLTZydDRkLWJiNWgwLThkbGJqbjk5aWd1c3N1NTIiLCJqdGkiOiJ0by02Y3JjNC1qMHByNi05YTg4bDM3c3V0dWdwZHU4Iiwic2NvcGUiOiIiLCJwZXJtaXNzaW9ucyI6W10sImh0dHBzOi8vY3VzdG9tL3VzZXJuYW1lIjoiQm9yZGVybGVzczEiLCJodHRwczovL2N1c3RvbS9hcHBfbWV0YWRhdGEiOnsidXNlcklkIjoidXMtMzJwcnUtdnJmbTEtOWhpOWhuOTIzMmk1djUzciIsIm9yZ0lkIjoib3ItNnJ0NGQtYmI1aDAtOGRsYmpuGTlpZ3Vzc3U1MiIsInRva2VuS2luZCI6IlNlcnZpY2VBY2NvdW50In0sImlhdCI6MTczNjM2MzQ5MiwiZXhwIjoxNzk5NDM1NDkyfQ.DhsE-rZ-8cHudw2RklP9nFSbAEGgsVBN_bxjBMm_Rx_ohaT1VRlJRtpHvtd-OkrAvRbyayVzLC49UBQwPs1yBA"
		}

Create account and add assets with Dfns

Once you have linked your Dfns account for streamlined interoperability, you can set up an account with your Dfns infrastructure similarly to how you would for standalone wallets.The main difference is when adding an asset to a Borderless Account, you must include the corresponding dfnsWalletId of a wallet that already exists in your Dfns setup.When using Dfns, Borderless does not link the Account entity directly to a Dfns wallet.
Instead, the linkage is done at the Asset level, during asset address assignment. Therefore, no additional fields are required when creating an Account or SubAccount under Dfns.

Endpoint: POST /accounts/

curl -X POST "https://sandbox-api.borderless.xyz/v1/accounts/" \
	 -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \
	 -H "idempotency-key: 8f14e45f-e6c3-4f7e-bd56-1b9a2e46f1d6"\
	 -d '{
  		"name": "Account Name",
  		"identityId": "Id of Identity",
  
  		"assets": [
    		{
      		"asset": AssetId,
      		"dfnsWalletId": "wa-7jesf-pmt6i-92lbukigvpvahmki"
    		}
  		]
		}'

Step 2: Adding assets to account

With an account set up for this identity, it’s necessary to add assets to the account. Specifically, these assets are the stablecoin funds that will be used to initiate off-ramp payments into local fiat currencies. These accounts will also be used to receive funds when on-ramping payments between local fiat currencies and stablecoins. Please note that when you add new assets to your account, this is a configuration for the stablecoin wallet infrastructure to track these assets correctly. This does not mean you are sending real stablecoin funds to this account with this endpoint. Borderless is fully non-custodial, you will need to transfer your stablecoins directly to this wallet address yourself, or receive funds from an on-ramp transaction.

Please use the account id from the response to the previous request above.

Please double check the wallet’s blockchain matches the blockchain of the Asset you’re adding.
If not, the operation will fail with an error, and funds may be lost.

Please check for Tron-based assets, that the generated address is activated by sending a minimum of 0.1 TRX to it.

Endpoint: POST /accounts/{id}/assets

curl -X POST "https://sandbox-api.borderless.xyz/v1/accounts/{id}/assets" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \
     -d '{
    		"asset": "USDC_BASE",
    		"address": "0xE79a68B87544ed42Cc5aA805bb056201e7942D3A"
  		}'

{
  "id": "cm9db4g2s2r7ro224ra6u1qvl",
  "asset": "USDC_BASE",
  "address": "0xE79a68B87544ed42Cc5aA805bb056201e7942D3A"
}

Step 3: Check account balances

Once you receive funds to this account, and added the stablecoin assets to be tracked on the account, you can easily check the balances at any time. Just pass the account id as a parameter in the request, and the balance is returned.

Endpoint: GET /accounts/{id}/balances

curl -X GET "https://sandbox-api.borderless.xyz/v1/accounts/{id}/balances" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \

[
  {
    "type": "asset",
    "asset": "USDC_BASE",
    "fiat": null,
    "total": "0"
  }
]

PFI Accounts

Step 1: Account creation

Let’s create our first PFI account. After this, we will add fiat currencies.

Please capture account id from the response to use it as needed later.

Before creating a PFI Account, you must first configure Borderless access to the specific PFI you want to use. To do this, use the Integrations API request for that PFI. For example to configure Finity, use the following API endpoint:

Endpoint: PUT /organizations/integrations/finity

Once access to the PFI provider is configured, you can create a PFI Account that will operate with it. To do this, use the standard Account creation request and include the pfi property with the name of the PFI you want to link to this Account.

Make sure the fiat currency is supported by chosen PFI provider before adding it to the PFI Account.

Endpoint: POST /accounts/

curl -X POST "https://sandbox-api.borderless.xyz/v1/accounts/" \
	 -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \
	 -H "idempotency-key: 8f14e45f-e6c3-4f7e-bd56-1b9a2e46f1d6"\
	 -d '{
          "pfi": "Finity",
        
          "name": "Finity Account Name",
          "identityId": "Id of Identity",
        }'

Step 2: Adding fiat to account

With a PFI Account set up for this identity, it is necessary to add fiat currencies to the account (for example, COP, USD, BRL) that will be used to send payouts, perform exchanges into this PFI Account.

Please use the account id from the response to the previous request above.

Endpoint: POST /accounts/{id}/assets

curl -X POST "https://sandbox-api.borderless.xyz/v1/accounts/{id}/assets" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \
     -d '[
        {
          "fiat": "USD"
        },
        {
          "fiat": "COP"
        }
      ]'

[
  {
    "id": "cmi7s8wgk471upg23mlc2chms",
    "fiat": "USD"
  },
  {
    "id": "cmi7s8wgk471wpg23vjl4rhvb",
    "fiat": "COP"
  }
]

Step 3: Check account balances

Endpoint: GET /accounts/{id}/balances

curl -X GET "https://sandbox-api.borderless.xyz/v1/accounts/{id}/balances" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \

[
  {
    "type": "fiat",
    "asset": null,
    "fiat": "USD",
    "total": "0"
  },
  {
    "type": "fiat",
    "asset": null,
    "fiat": "COP",
    "total": "1405"
  }
]

If you have any questions, please don’t hesitate to reach out to us via email or slack.

Getting Started

Core Concepts

Transaction Types

Partner Solutions

Products

Accounts & Wallets

Account structure diagram

Overview

SubAccounts

Web3 wallet infrastructure

Web3 Accounts

Step 1: Web3 Account creation

Enable Utila as your infrastructure provider

Create account and add assets with Utila

Enable Dfns as your infrastructure provider

Create account and add assets with Dfns

Step 2: Adding assets to account

Step 3: Check account balances

PFI Accounts

Step 1: Account creation

Step 2: Adding fiat to account

Step 3: Check account balances

​Account structure diagram

​Overview

​SubAccounts

​Web3 wallet infrastructure

​Web3 Accounts

​Step 1: Web3 Account creation

​Enable Utila as your infrastructure provider

​Create account and add assets with Utila

​Enable Dfns as your infrastructure provider

​Create account and add assets with Dfns

​Step 2: Adding assets to account

​Step 3: Check account balances

​PFI Accounts

​Step 1: Account creation

​Step 2: Adding fiat to account

​Step 3: Check account balances

Account structure diagram

Overview

SubAccounts

Web3 wallet infrastructure

Web3 Accounts

Step 1: Web3 Account creation

Enable Utila as your infrastructure provider

Create account and add assets with Utila

Enable Dfns as your infrastructure provider

Create account and add assets with Dfns

Step 2: Adding assets to account

Step 3: Check account balances

PFI Accounts

Step 1: Account creation

Step 2: Adding fiat to account

Step 3: Check account balances