Skip to main content
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.

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

​
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"
  		}'

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

​
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"
        }
      ]'

​
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" \
If you have any questions, please don’t hesitate to reach out to us via email or slack.