Register
API Explorer
https://obp-api-sandbox.nmbbank.co.tz

Asset

Asset

An Asset is a unit that amounts can be held in: a currency such as EUR, a precious metal such as gold (XAU), an accounting unit such as the IMF's Special Drawing Right (XDR), a crypto asset such as ETH, or an asset a bank issues, such as a deposit token, a stablecoin, a bond or a fund share. Each Asset has a code, and that code is the value that appears in the currency field of an account, a transaction or a product fee.

The asset registry lists the Assets an OBP instance knows. It is filled automatically with every currency, metal and accounting unit in ISO 4217 and with the crypto assets XBT, ADA and ETH.

What the registry records about an Asset

  • Code: 3 to 10 letters or digits, held upper case. The registry matches codes ignoring letter case, so looking up eur finds EUR.
  • Type: FIAT, PRECIOUS_METAL, ACCOUNTING_UNIT, CRYPTO, or one of the types a bank issues: DEPOSIT_TOKEN, STABLECOIN, DEBT_SECURITY, EQUITY, FUND_SHARE, OTHER.
  • Decimal places: how many digits an amount may have after the decimal point, from 0 to 18. EUR has 2, JPY has 0.
  • Issuer: the bank that issued it, for the types a bank issues. Currencies, metals, accounting units and crypto assets have no issuer.
  • Chain identity: for a token recorded on a blockchain, the chain and network (for example CARDANO_MAINNET) and the token's identity there. A chain's own currency, such as ADA or ETH, has none.
  • Status: ACTIVE, SUSPENDED (for example frozen by a regulator) or RETIRED (for example a bond that has matured).

Assets, Products and Accounts

These are three separate things. The Asset says what the units are. A Product says what a bank offers and on what terms; an issuing bank describes an instrument, such as a bond's coupon and maturity date, with a Product and its attributes. An Account says who holds how many units: its currency is the Asset's code, and its product is the holding bank's own Product. A customer at bank B holding a bond issued by bank A has an account at B, in the bond's Asset code, under one of B's Products.

Administering bank

Every Asset is administered at exactly one bank: the issuer for the types a bank issues, and the SYS bank for everything else.

Codes OBP accepts

The registry decides which currency codes OBP accepts and how many decimal places each one has. OBP also accepts lovelace and wei, the smallest units of ADA and ETH, which are not Assets of their own.

Letter case

Currency codes are case-insensitive: eur, Eur and EUR all name the same Asset and get the same decimal places. OBP upper-cases a currency code in a request before the endpoint handles it, so it is validated, compared and stored as EUR. This applies to the fields of a JSON request body that hold a currency code (currency, from_currency_code and the like) and to query parameters named the same way. Wherever OBP compares two currency codes, it ignores letter case.

Decimal places of an amount

OBP does not round or cut off an amount. A request carrying an amount with more decimal places than its currency allows, such as 12.345 EUR or 100.5 JPY, is refused with 400 (OBP-10068). Trailing zeros do not count, so 100.00 JPY is accepted. This applies to every object in a JSON request body that holds an amount next to its currency (UK Open Banking's Amount and Currency included), and to an amount query parameter next to a currency parameter.

Endpoints

These need no authentication.