Warning! Construction underway! Amatino is in an 'alpha' state. Not all features are operational. See roadmap

Primary
Account
Entity
Transaction
Derived
Balance
Ledger
Performance
Position
Recursive Balance
Recursive Ledger
Tree
Ancillary
Object
Create
Retrieve
Update
Delete
Entity List
Entry
Global Unit
Global Unit List
Ledger Row
Price
Session
Side
Tx Version List
Tree Node
Type
User
User List

Custom Unit

Custom Units are units of account created by Amatino users. Their scope is limited to the Entity in which they are created. They can be used anywhere a Global Unit would be used, allowing you to denominate Transactions and Accounts as you please.

Custom Unit identifiers need not be unique with reference to Global Units. Therefore, it is possible to create a Custom Unit substitute of a Global Unit. For example, a USD Custom Unit using a preferred source of foreign exchange rates, with higher temporal resolution, or some other desired characteristic.

The Custom Unit Object

Amatino will return Custom Unit objects to you with the following structure

Root Type

JSON Array

Object Structure

type JSON Number
example "xrp"
key "custom_unit_id"
description An integer identifier, unique within an Entity
type JSON String
example "xrp"
key "code"
description A short form name for this custom unit. Case sensitive
type JSON String
example "Ripple Coin"
key "name"
description A friendly long form name
type JSON Number
example 0
key "priority"
description A sorting hint for GUI's displaying lists of Custom Units
type JSON String
example "Ripple Coin - A cryptocurrency"
key "description"
description A long-form description
type JSON Number
example 6
key "exponent"
description The number of digits after the decimal point required to describe the smallest fraction of this Custom Unit

Create Custom Unit

API Path /custom_units
HTTP Method POST
Description Descr. Create a new Custom Unit

Required Headers

Key X-Signature
Value Your Session signature
Example "yxATCPRKAAXHNiPctNQPHEGGVJF"...
Key X-Session-ID
Value An an integer Session ID
Example 7449059267091272858

Required URL Parameters

Key entity_id
Type string
Description Descr. The entity_id of the Entity in which to create the Custom Unit
Example oB3cjSNKXklkJ4Tb
Repeatable No

Required JSON Data

Root type

JSON Array

Max Array Length

10

Object Structure

type JSON String
min char length 3
example "xrp"
max char length 64
note Codes need not be unique with reference to Global Units
key "code"
description A shorthand name. Case sensitive
type JSON String
example "Ripple Coin"
max char length 1024
key "name"
description A friendly long form name
type JSON Number or JSON Null
example 10
key "priority"
description A sorting hint for GUI's displaying lists of Custom Units
note Specifying JSON Null results in a default value of 0
type JSON String or JSON Null
example Ripple Coin - A cryptocurrency
max char length 1024
key "description"
description A long form description
type JSON Number
example 6
min 0
key "exponent"
description The number of digits after the decimal point required to describe the smallest fraction of the Custom Unit
max 6

Returns

Root Type

JSON Array

Object

Custom Unit

Retrieve Custom Unit

API Path /custom_units
HTTP Method GET
Description Descr. Retrieve metadata describing a Custom Unit, or Units.

Required Headers

Key X-Signature
Value Your Session signature
Example "yxATCPRKAAXHNiPctNQPHEGGVJF"...
Key X-Session-ID
Value An an integer Session ID
Example 7449059267091272858

Required URL Parameters

Key entity_id
Type string
Description Descr. The ID of the Entity in which the target Custom Units reside
Example oB3cjSNKXklkJ4Tb
Repeatable No
Key custom_unit_id
Type integer
Description Descr. The unique integer ID Custom Unit you wish to retrieve
Example 35
Repeatable Yes

Required JSON Data

None.

Returns

Root Type

JSON Array

Object

Custom Unit

Update Custom Unit

API Path /custom_units
HTTP Method PUT
Description Descr. Update data describing a Custom Unit or group of Custom Units

Required Headers

Key X-Signature
Value Your Session signature
Example "yxATCPRKAAXHNiPctNQPHEGGVJF"...
Key X-Session-ID
Value An an integer Session ID
Example 7449059267091272858

Required URL Parameters

Key entity_id
Type string
Description Descr. The ID of the Entity in which the target Custom Units reside
Example oB3cjSNKXklkJ4Tb
Repeatable No

Required JSON Data

Root type

JSON Array

Max Array Length

10

Object Structure

type JSON Number
example 42
key "custom_unit_id"
description The unique ID of the Custom Unit you wish to update
type JSON String
min char length 3
example "xrp"
max char length 64
key "code"
description The short form name
type JSON String
example "Ripple Coin"
max char length 1024
key "name"
description A friendly long form name
type JSON Number or JSON Null
example 10
key "priority"
description A sorting hint for GUI's displaying lists of Custom Units
note Specifying JSON Null results in a default value of 0
type JSON String or JSON Null
example Ripple Coin - A cryptocurrency
max char length 1024
key "description"
description A long form description
type JSON Number
example 6
min 0
key "exponent"
description The number of digits after the decimal point required to describe the smallest fraction of the Custom Unit
max 6

Returns

Root Type

JSON Array

Object

Custom Unit

Delete Custom Unit

API Path /custom_units
HTTP Method DELETE
Description Descr. Delete a Custom Unit or group of Custom Units. Deleted Custom Units cannot be recovered, but their codes may be re-used.

Required Headers

Key X-Signature
Value Your Session signature
Example "yxATCPRKAAXHNiPctNQPHEGGVJF"...
Key X-Session-ID
Value An an integer Session ID
Example 7449059267091272858

Required URL Parameters

Key entity_id
Type string
Description Descr. The ID of the Entity in which the target Custom Units reside
Example oB3cjSNKXklkJ4Tb
Repeatable No

Required JSON Data

Root type

JSON Array

Max Array Length

10

Object Structure

type JSON Number
example 42
key "custom_unit_id"
description The unique ID of the Custom Unit you wish to delete
type JSON String or JSON Null
example "btc"
key "account_custom_unit_replacement"
description The code of a Custom Unit that should replace the target Custom Unit in any Account or Transaction denominated by the target
note Supply at least one of either a Custom Unit replacement or Global Unit replacement, but not both
type JSON String or JSON Null
example "usd"
key "account_global_unit_replacement"
description The code of a Global Unit that should replace the target Custom Unit in any Account or Transaction denominated by the target
note Supply at least one of either a Global Unit replacement or Custom Unit replacement, but not both

Returns

Root Type

JSON Array

Object Structure

type JSON Number
example 35
key "deleted_custom_unit_id"
description The unique integer ID of a deleted custom unit
type JSON Array of JSON Numbers
example [42, 69, 101]
key "updated_accounts"
description The IDs of any accounts whose denominating unit was updated by the deletion