UUID_REGEX
UUID_REGEX = '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
The client uses this regex to validate ID values before even attempting to do a REST call.
PHP wrapper for the OST KIT REST API.
This class implements all endpoint features of the OST KIT REST API v1.0.
All API validations are also enforced client-side to provide fail-fast operations without having to wait for the REST call result.
create(string $apiKey, string $apiSecret, string $baseUrl = 'https://sandboxapi.ost.com/v1.1', boolean $debug = true) : \ostkit\OstKitClient
Static factory for OstKitClient instances. Creates a new OST KIT PHP client using your API key and secret.
| string | $apiKey | OST API key (mandatory) |
| string | $apiSecret | OST KIT API secret (mandatory) |
| string | $baseUrl | OST REST base URL |
| boolean | $debug | Enable debug logging to php://stdout (defaults to true) |
when API key, API secret and/or Base URL is missing
when initialization fails
createUser(string $name) : array|mixed
Create a user with the given name.
| string | $name | User Name (mandatory, not unique) - must be a minimum of 3 characters, a maximum of 20 characters, and can contain only letters, numbers, and spaces, along with other common sense limitations. |
when the ID is missing or the Name does not pass validation
when the HTTP call is unsuccessful
decoded JSON array of the 'user' result type
updateUser(string $id, string $name) : array|mixed
Rename an existing user.
| string | $id | User ID (mandatory) |
| string | $name | User Name (mandatory) - must be a minimum of 3 characters, a maximum of 20 characters, and can contain only letters, numbers, and spaces, along with other common sense limitations. |
when the ID is missing or the Name does not pass validation
when the HTTP call is unsuccessful
decoded JSON array of the updated 'user' result type
getUser(string $id) : array|mixed
Retrieve an existing user.
| string | $id | User ID (mandatory) |
when the ID is missing or the Name does not pass validation
when the HTTP call is unsuccessful
decoded JSON array of the updated 'user' result type
listUsers(boolean $fetchAll = false, array $filters = array(), integer $page = 1, null $airdropped = null, string $orderBy = 'created', string $order = 'desc', integer $limit = 100) : array|mixed
| boolean | $fetchAll | |
| array | $filters | |
| integer | $page | |
| null | $airdropped | |
| string | $orderBy | |
| string | $order | |
| integer | $limit |
when the HTTP call is unsuccessful
createAction(string $name, string $kind, string $currency = 'BT', double $amount = null, double $commissionPercent = null) : array|mixed
Create an action.
| string | $name | Unique Name (mandatory, unique) - must be a minimum of 3 characters, a maximum of 20 characters, and can contain only letters, numbers, and spaces, along with other common sense limitations. |
| string | $kind | Kind (mandatory) - must be one of 'company_to_user', 'user_to_company' or 'user_to_user' |
| string | $currency | Currency (mandatory) - either 'USD' (fixed) or 'BT' (floating) |
| double | $amount | Amount - 0.00001 to 100 for 'BT' or 0.01 to 100 for 'USD' - null makes the action accept arbitrary amounts |
| double | $commissionPercent | Commission Fee (only for 'user_to_user' actions) - percentage inclusive in the amount - 0 to 100 - null makes this action accept arbitrary commissions |
when the input parameters do not pass validation
when the HTTP call is unsuccessful
decoded JSON array of the updated 'action' result type
updateAction(string $id, string $name = null, string $kind = null, string $currency = null, double|null $amount = null, double|null $commissionPercent = null) : array|mixed
Update an existing action.
| string | $id | Action ID (mandatory) |
| string | $name | Name (unique) - must be a minimum of 3 characters, a maximum of 20 characters, and can contain only letters, numbers, and spaces, along with other common sense limitations. |
| string | $kind | Kind - cannot be changed after creation - used to validate and add commission percent only for 'user_to_user' actions |
| string | $currency | Currency (mandatory) - either 'USD' (fixed) or 'BT' (floating) |
| double|null | $amount | Amount - 0.00001 to 100 for 'BT' or 0.01 to 100 for 'USD' - null makes the action accept arbitrary amounts |
| double|null | $commissionPercent | Commission Fee (only for 'user_to_user' actions) - percentage inclusive in the amount - 0 to 100 - null makes this action accept arbitrary commissions |
when the input parameters do not pass validation
when the HTTP call is unsuccessful
decoded JSON array of the updated 'action' result type
listActions(boolean $fetchAll = false, array $filters = array(), integer $page = 1, string $orderBy = 'created', string $order = 'desc', integer $limit = 100) : array|mixed
| boolean | $fetchAll | |
| array | $filters | |
| integer | $page | |
| string | $orderBy | |
| string | $order | |
| integer | $limit |
executeCompanyAction(string $id, string $userId, double|null $amount = null) : array|mixed
Execute an existing 'user_to_company' or 'company_to_user' action and automatically assign the company as recipient or sender.
This method retrieves the action first to:
| string | $id | Action ID (mandatory) |
| string | $userId | User ID (mandatory) |
| double|null | $amount | Amount - 0.00001 to 100 for 'BT' or 0.01 to 100 for 'USD' - null if the amount is preset by the action |
when the requested action is 'user_to_user' or the input parameters do not pass validation
when the HTTP call is unsuccessful
decoded JSON array of the updated 'transaction' result type
executeAction(string $id, string $from, string $to, double|null $amount = null, double|null $commissionPercent = null) : array|mixed
Execute any existing action.
| string | $id | Action ID (mandatory) |
| string | $from | Sending User ID (mandatory) |
| string | $to | Receiving User ID (mandatory) |
| double|null | $amount | Amount - 0.00001 to 100 for 'BT' or 0.01 to 100 for 'USD' - null if the amount is preset by the action |
| double|null | $commissionPercent | Commission Fee (only for 'user_to_user' actions) - percentage inclusive in the amount - 0 to 100 - null if the commission percentage is preset by the action |
when the input parameters do not pass validation
when the HTTP call is unsuccessful
decoded JSON array of the updated 'transaction' result type
getTransaction(string $id) : array|mixed
Retrieve an existing transaction.
| string | $id | Transaction ID (mandatory) |
when the ID is missing
when the HTTP call is unsuccessful
decoded JSON array of the 'transaction' result type (an additional attribute 'view_url' is added that contains a hyperlink to OST View)
airdrop(integer $amount, boolean|null $airdropped = null, array $userIds = array()) : array|mixed
Execute an airdrop to provide a certain amount of Branded Tokens to a set of users.
Please note the interdependency between the $airdropped and $userIds parameters.
| integer | $amount | Number (mandatory) of Branded Tokens to airdrop - must be a positive integer value that is less than the total supply |
| boolean|null | $airdropped | Indicates whether to airdrop tokens to end-users who have been airdropped some tokens at least once (true) or to end-users who have never (false) been airdropped tokens or null to omit this filter |
| array | $userIds | Array of selected User IDs to airdrop tokens to or null to omit this filter - this filter works on top of the $airdropped filter |
when the $amount is missing
when the HTTP call is unsuccessful
decoded JSON array of the 'airdrop' result type
getAirdrop(string $id) : array|mixed
Retrieves a previously scheduled
Please note the interdependency between the $airdropped and $userIds parameters.
| string | $id | Airdrop ID |
when the $amount is missing
when the HTTP call is unsuccessful
decoded JSON array of the 'airdrop' result type
listAirdrops(boolean $fetchAll = false, integer $page = 1, string $filter = 'all', string $orderBy = 'created', string $order = 'desc', integer $limit = 10, string $optionalFilters = '') : array|mixed
| boolean | $fetchAll | |
| integer | $page | |
| string | $filter | |
| string | $orderBy | |
| string | $order | |
| integer | $limit | |
| string | $optionalFilters |
transfer(string $toAddress, integer $amount) : array|mixed
Transfer an arbitrary amount of OST⍺ Prime to an account outside of your Branded Token economy.
| string | $toAddress | Public address (mandatory) to which to transfer OST⍺ Prime |
| integer | $amount | Amount (mandatory) of OST⍺ Prime to transfer in Wei - between 0 and 10^20 (exclusive) |
when the $amount is missing
when the HTTP call is unsuccessful
decoded JSON array of the 'transfer' result type
listTransfers(boolean $fetchAll = false, integer $page = 1, string $filter = 'all', string $orderBy = 'created', string $order = 'desc', integer $limit = 10, string $optionalFilters = '') : array|mixed
| boolean | $fetchAll | |
| integer | $page | |
| string | $filter | |
| string | $orderBy | |
| string | $order | |
| integer | $limit | |
| string | $optionalFilters |
getCombinedBalance(string $id) : array|mixed
Retrieves the current Branded Token balance for a user.
The balance array is merged with the token array and countervalues in OST and USD are added.
| string | $id | User ID (mandatory) |
when the HTTP call is unsuccessful
merged decoded JSON array of the 'balance' and 'token' result types + countervalues in OST and USD
getLedger(string $id) : array|mixed
Retrieves a list of all transactions where a user has been either the sender or a recipient of tokens.
This basically is the same as calling the /transactions endpoint with a user ID filter.
Each transaction gets the following additional properties:
| string | $id | User ID (mandatory) |
when the HTTP call is unsuccessful
decoded JSON array of the 'transactions' result type
get(string $endpoint, boolean $fetchAll, array $arguments = array(), boolean $extractResultType = true) : array|mixed
Performs a GET request to the specified endpoint.
| string | $endpoint | the endpoint to call, might contain path information where applicable |
| boolean | $fetchAll | recursively retrieve all |
| array | $arguments | arguments to be passed in the request |
| boolean | $extractResultType | whether to extract the wrapped JSON result type or not |
when the HTTP call is unsuccessful
decoded JSON array of the entire result or - if $extractResultType is true - the extracted result type of the response
post(string $endpoint, array $arguments = array(), boolean $extractResultType = true) : array|mixed
Performs a POST request to the specified endpoint.
| string | $endpoint | the endpoint to call, might contain path information where applicable |
| array | $arguments | arguments to be passed in the request |
| boolean | $extractResultType | whether to extract the wrapped JSON result type or not |
when the HTTP call is unsuccessful
decoded JSON array of the entire result or - if $extractResultType is true - the extracted result type of the response
getCounterValues( $brandedTokenAmount, double $exchangeRate = null) : mixed
Countervalues in OST and USD are calculated as: - converted countervalue in OST (ost_value) - converted countervalue in USD (usd_value)
| $brandedTokenAmount | int amount in Branded Token |
|
| double | $exchangeRate | OST/USD exchange rate |
addTransactionsViewUrl( $transactions) : array
Adds a link to OST VIEW and the OST/USD exchange rate for each transaction in the array.
| $transactions | array decoded JSON array of the 'transaction' result type |
when retrieving the OST price points fails
decoded JSON array of the 'transaction' result type