Mapping Public Addresses


One of the key utilities of the FIO Protocol is the ability to send crypto using a FIO Address, instead of complicated Native Blockchain Public Address (NBPA) such as 0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B on Ethereum.

A wallet can very easily look-up the NBPA using the /get_pub_address method.

However, before this can happen the wallet hosting the FIO Address must first map the NBPA to the FIO Address.

Mapping NBPAs to FIO Address

To map NBPA to a FIO Address use the /add_pub_address method.

You may pass up to 5 public addresses in a single call. The call is eligible for bundled transactions, so in most cases there will not be a fee to the user.

Each NBPA is identified with:

  • chain_code identifies the blockchain, such as Bitcoin (BTC), or Ethereum (ETH).
  • token_code identifies the token on that blockchain, for example USDC represents ERC20 token on Ethereum.

For blockchains that only have one token use the same value for blockchain and token, e.g. for Bitcoin use chaincode: BTC, tokencode: BTC.

FIO does not currently maintain a list of “approved” codes as those change often and are typically maintained by other sources such as SLIP-44, Coin Market Cap, or specific blockchain, e.g. ERC-20 tokens on Ethereum

Multi-level Addressing

Certain blockchains, or accounts on those blockchains, require the use of Multi-level Addressing, when, in addition to public address, additional piece of information is required to properly route a transaction.

The following are examples:

  • Destination Tags on Ripple
  • Memos on Stellar
  • Payment ID on Monero

There is not a clear standard on how to properly communicate these additional properties. One approach is the use of integrated (aka extended) addresses, which encodes the additional properties into the public address string. The FIO Protocol will support both integrated addresses as well as URI Scheme as follows:

  • Integrated Address - an integrated address may be passed in just like standard public address. The FIO protocol does not perform validation on the passed string.
  • URI Scheme - the FIO Protocol will support the formatting of public addresses using URI Schemes, where certain attributes are appended to the public address following a ‘?’ and delimited with ‘&’.

URI Parameters

Parameter Blockchain using
dt Ripple
memo Any - use as generic memo field
memo_id Stellar
memo_text Stellar
memo_hash Stellar
memo_return Stellar
payment_id Monero


Currently NBPA mappings are stored on the FIO Chain unencrypted. It is therefore possible for an observer to connect multiple NBPAs via their parent FIO Address.

It is therefore important that integrating wallets clearly communicate this to their users, so that they can make an educated decision on which NBPAs to map. In addition users should understand that due to the nature of blockchain once NBPA has been published on the blockchain it will be accessible indefinitely, even if it is later “removed” from current mappings.

For inspiration, please review sample Wallet UX screens for Connecting NBPAs.

Changing or removing NBPAs

NBPA mappings can be changed or removed. This is achieved using the same /add_pub_address method.

It is currently not possible to remove or even reset the NBPA to an empty string. This is being urgently addressed in FIP-4. Until then, to remove the NBPA set it to 0.

FIO Public Key mapping

The FIO Public key which was used to register FIO Address is automatically added to that address’ mapping for chaincode: FIO, tokencode: FIO.

This mapping serves two distinct purposes:

  • When another user wants to send FIO tokens to that FIO Address, the mapped public key will be returned in /get_pub_address to enable that transfer.
  • When another user is sending new_funds_request or record_obt_data to that FIO Address, the mapped public key will be used to encrypt the data. It is therefore critical that:
    • The associate private key is accessible and available in the wallet to decrypt that data. Wallets should not allow users to map a random FIO Public Key.
    • If a user tries to remove FIO Public key mapping, they should be advised that they will not be able to receive a FIO Request or Record OBT Data in the future until a valid FIO Public key is added back.

Mapping FIO Address to bank accounts

FIO Address can also be mapped to bank account information required to route fiat transactions. For this purpose chain_code: FIAT should be used and token_code should correspond to the banking standard used.

For example to map FIO Address to a ACH bank account:

	"chain_code": "FIAT",
	"token_code": "ACH",
	"public_address": "{'aba':'102000076','acc':'1234567890'}"

To map FIO Address to an IBAN bank account:

	"chain_code": "FIAT",
	"token_code": "IBAN",
	"public_address": "{'iban':'DE89370400440532013000'}"