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
Price
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

type JSON Number
key "custom_unit_id"
example "xrp"
description An integer identifier, unique within an Entity
type JSON String
key "code"
example "xrp"
description A short form name for this custom unit. Case sensitive
type JSON String
key "name"
example "Ripple Coin"
description A friendly long form name
type JSON Number
key "priority"
example 0
description A sorting hint for GUI's displaying lists of Custom Units
type JSON String
key "description"
example "Ripple Coin - A cryptocurrency"
description A long-form description
type JSON Number
key "exponent"
example 6
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

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

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

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

Returns

Root Type

JSON Array

Object Structure

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