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
Entry
Global Unit
Global Unit List
Ledger Row
Session
Side
Tx Version List
Tree Node
Type
User

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

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

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

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

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

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

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

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

Returns

Root Type

JSON Array

Object Structure

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