> ## Documentation Index > Fetch the complete documentation index at: https://docs.borderless.xyz/llms.txt > Use this file to discover all available pages before exploring further. # 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](/docs/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.
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
Best for Organizations already working with Utila. We also support direct integration with Utila. If Utila is already part of your infrastructure, this option enables a smooth transition to our platform. Utila uses non-custodial wallets, meaning you are the sole-custodian of your assets, and Borderless does not have access at any time to move the funds on your behalf. These are also using MPC technology for additional layers of security. An MPC wallet is a multi-party computational wallet, meaning your private key, which is used to secure the wallet, is encrypted and then broken into three parts which are managed by yourself, and Utila technology separately. It's important to note, that Borderless never receives a copy of this private key, and does not gain controlling access at any point. All outbound transaction signing happens on your side using Utila — Borderless does not manage key material or signing operations. 2efa6f20bfd008b08463e5094b5357f016de03a3529ff032db916ab417cb2410 Utila Sv
Best for Organizations already working with Dfns. If you're already using Dfns as your wallet infrastructure, we offer seamless integration.\ We connect Borderless to your existing Dfns account structure with minimal configuration. Dfns uses non-custodial wallets, meaning you are the sole-custodian of your assets, and Borderless does not have access at any time to move the funds on your behalf. These are also using MPC technology for additional layers of security. An MPC wallet is a multi-party computational wallet, meaning your private key, which is used to secure the wallet, is encrypted and then broken into three parts which are managed by yourself, and Dfns technology separately. It's important to note, that Borderless never receives a copy of this private key, and does not gain controlling access at any point. All outbound transaction signing happens on your side using Dfns — Borderless does not manage key material or signing operations. B206de3d1c361f8f7f0079d8601a3111b05d34e5832148faa70306e0f10b87e5 DFNS Sv
Best for startups, and folks working through POCs - we recommend managing your own for enterprises who facilitate meaningful stablecoin payment volumes. We provide and manage a complete web3 setup for you, powered by Fireblocks. You interact with stablecoins solely through our secure API — no additional setup required, you simply delegate wallet management. Fireblocks uses non-custodial wallets, meaning you are the sole-custodian of your assets, and Borderless does not have access at any time to move the funds on your behalf. These are also using MPC technology for additional layers of security. An MPC wallet is a multi-party computational wallet, meaning your private key, which is used to secure the wallet, is encrypted and then broken into three parts which are managed by yourself, and Fireblocks technology separately. It's important to note, that Borderless never receives a copy of this private key, and does not gain controlling access at any point. To protect your account, we encrypt your MPC key shard with a passphrase which is required for all transactions that this wallet initiates. In addition to the passphrase, you must also provide a passphraseId, which must be a valid UUID. This identifier is used to back up your MPC key material and is essential for recovery purposes. Even in the event of a system failure on Borderless, having your passphrase and corresponding passphraseId allows you to restore access to your account. With this integration you can easily: * Create different blockchain wallets * View balances * Track transactions * Initiate transfers within your organization or to external blockchain addresses * Use one unified address for all EVM-compatible chains * Spin up separate addresses for all non-EVM chains We do not cache or store your passphrase on our side. If your passphrase is lost or forgotten, access to the account and its funds will be permanently lost. Please store this passphrase securely, and do not share it. All transactions performed with a valid passphrase are considered legitimate. If you suspect your passphrase has been compromised, we strongly recommend: * Creating a new account immediately (in another identity) * Transferring all assets to the new account * Contacting our support team to block the compromised account Currently, passphrase changes are not supported. If you need to rotate or change your passphrase, please contact our support team. 2fa455e92418a89a29693fb719aa6603dceb34439d5efaabfdbd705085f4b10c Passphrase Sv 12e694f5b8f1e7926341c6a2be62c6560ac75688afc07fc0a41803b711c7eea4 Fireblocks Base Sv
Best for power users needing maximum flexibility and managing multiple infrastructures. This mode allows you to assign different providers on a main account basis rather than organization-wide. While powerful, it introduces complexity in account management and is not recommended for users unfamiliar with web3 wallet management. Unlike other providers, MultiProvider does not offer its own Web3 infrastructure integration. Instead, it shifts the provider selection from the organization level to the account level. With MultiProvider, each identity account can be created using a different Web3 provider. SubAccounts automatically inherit the Web3 provider of the main Account of Identity. All outbound transaction signing happens on your side using your standalone wallet — Borderless does not manage key material or signing operations. b83c7581724359f1e08f77a38a28fb3b0de07792c1a5cbcb041143395ee00741-MultiProvider 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. 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`](/api-reference/accounts/create-a-new-account) ```bash request expandable theme={null} 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" }' ``` ```json response expandable theme={null} { "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: 1. Go to your Utila console and open your organization. 2. Open the Service Accounts tab. 3. Create a new Service Account. 4. 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`](/api-reference/integrations-config/setup-utila-integration) ```bash request expandable theme={null} 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/`](/api-reference/accounts/create-a-new-account) ```bash request expandable theme={null} 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: 1. Go to your Dfns console and open your organization. 2. From the left menu, navigate to Settings. 3. Open the Service Accounts tab. 4. Create a new Service Account (e.g. named Borderless Integration) and fill in all required fields. 5. 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. 6. After creation, open the Service Account and assign Permissions. 7. 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`](/api-reference/integrations-config/setup-dfns-integration) ```bash request expandable theme={null} 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/`](/api-reference/accounts/create-a-new-account) ```bash request expandable theme={null} 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" } ] }' ``` If you're using the Fully Managed Web3 provider, you must supply two additional fields when creating the Main Account for an Identity. These are `passphrase` and `passphraseId` which are both established during the creation of your Fireblocks self-custodial, MPC wallet. Read more about this specific configuration just above in the web3 wallet infrastructure section. Endpoint: [`POST /accounts/`](/api-reference/accounts/create-a-new-account) ```bash request expandable theme={null} 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", "passphrase": "secret-phrase", "passphraseId": "9849f5bc-bc32-4a48-a023-a89ad2c6d00b" }' ``` ### 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`](/api-reference/accounts/add-assets-to-account) ```bash request expandable theme={null} 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" }' ``` ```json response expandable theme={null} { "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`](/api-reference/accounts/get-account-balances) ```bash request expandable theme={null} curl -X GET "https://sandbox-api.borderless.xyz/v1/accounts/{id}/balances" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer your-access-token" \ ``` ```json response expandable theme={null} [ { "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/` ```bash request expandable theme={null} 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` ```bash request expandable theme={null} 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" } ]' ``` ```json response expandable theme={null} [ { "id": "cmi7s8wgk471upg23mlc2chms", "fiat": "USD" }, { "id": "cmi7s8wgk471wpg23vjl4rhvb", "fiat": "COP" } ] ``` ### 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` ```bash request expandable theme={null} curl -X GET "https://sandbox-api.borderless.xyz/v1/accounts/{id}/balances" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer your-access-token" \ ``` ```json response theme={null} [ { "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](mailto:support@borderless.xyz) or slack.