This section provides definitions and explanations for key concepts in the Hoseki API: account holders, accounts, and records.

Account Holder

An account holder refers to the entity or individual that owns or controls an account. This is the primary user or customer utilizing Hoseki's services. Account holders can manage multiple accounts and establish various connections to digital asset service providers or wallets.

Account

An account represents an entity with an overall balance that requires a connection. Accounts can be specific to Bitcoin (e.g., XPUB, Multisig wallet, address) or associated with exchanges (e.g., connection to Coinbase). An account encapsulates the broader context in which balances are managed.

• Examples:

  • Exchange Account: A Coinbase account is accessed through a username and password. Within this account, separate balances exist for assets like Bitcoin, USDT, and USD.

  • Self-Custodial Bitcoin Account: A connection to an XPUB or Multisig wallet, where the derived addresses from the XPUB collectively hold the Bitcoin balance.

Balances are typically read at the account level rather than the record level to provide a comprehensive view of the account's assets.

Record

A record refers to individual data entries stored within an account. Records represent the specific entities holding balances, which are aggregated to form the overall account balance.

• Examples:

  • Exchange Record: Separate balances for Bitcoin, USDT, and USD are considered records in a Coinbase account. So if you had balances in those three entities on Coinbase, your Coinbase account in Hoseki would have three records corresponding to the balances in those respective entities.

  • Self-Custodial Bitcoin Record: If you connect an XPUB, each Individual address derived from that XPUB holds part of the Bitcoin balance for that account. These addresses collectively represent the account's total balance. Each address derived from that XPUB would be considered a record for the connected XPUB account. This works similarly for self-custodial multisig wallets.

    • Note: Using multiple addresses for a Bitcoin wallet is recommended for security and privacy, as opposed to consolidating all funds in a single address.

Special Cases

Single Address Account: An account can also be a single address if the account holder chooses to expose only one address to a particular institution. In this scenario, the account will always have only one record, and that will be the same Bitcoin address.