TzPro API Data Types

We use the following data types and encoding conventions throughout the API:

Type	Description
string	unstructured ASCII/UTF-8 text
bytes	binary data encoded as hex string
date-time	UTC timestamps as long or short versions of ISO 8601/RFC3339 strings 2018-09-06T15:00:00Z
duration	signed 64bit integers with second precision
boolean	a binary value, either as string or number true (1) or false (0)
float64	an IEEE-754 64-bit floating-point number
int64	a signed 64-bit integer (Range: -9,223,372,036,854,775,807 through 9,223,372,036,854,775,807)
uint64	an unsigned 64-bit integer (Range: 0 through 18,446,744,073,709,551,615)
enum	enumerable values as strings
hash	on-chain hashes as base58 strings
address	wallets or contracts addresses as base58 strings
contract-address	contract addresses (KT1 only) base58 strings
token-address	token addresses of form {contract}_{tokenId}
bigint	big integers as strings used for raw token amounts (without decimals)
fixed	fixed-point numbers as strings (used for prices and percentages)

Timestamps can have multiple formats:

• full RFC3339 strings with timezone
• UNIX timestamp in seconds or milliseconds, so 1536246000 and 1536246000000 are equal
• dates without time, i.e. 2018, 2018-09, 2018-09-06 represents midnight at the first day of month and/or month of year
• labels such as now, today, or yesterday to reference a relative points in time
• expressions using now with truncation / offsets, eg. now/d means start of today, now/d-30d means start of day 30 days ago (time units are s, m, h, d)

Status Codes

The TzPro API returns one of the following HTTP status codes. In case of errors, the response body contains additional information encoded as JSON object.

• 200 OK Success
• 400 Bad Request Missing required fields of malformed request data, your fault
• 404 Not Found No such object (account, token, event has not yet been included in a finalized block)
• 405 Method Not Allowed Unsupported request method
• 429 Too Many Requests Request limit exceeded
• 500 Internal Server Something went wrong on our end, not your fault
• 502 Bad Gateway Our backend is overloaded or down for maintenance, wait a while before retry
• 503 Service Unavailable Our backend is overloaded or down for maintenance, wait a while before retry
• 504 Gateway Timeout Your request has reached a timeout and was canceled, try reduce limit or time range for your request

Error Responses

All error messages are JSON encoded.

Fields	Description
status int	The HTTP status code, duplicated for convenience.
message string	A textual representation of the error status.
scope string	The name of the API call that has failed.
detail string	A detailed text description of the error.
code int	An internal error code.
request_id string	Unique call id that helps us trace failed requests.

Response

{
  "errors": [
    {
      "code": 1007,
      "status": 400,
      "message": "incorrect request syntax",
      "scope": "StreamTable",
      "detail": "unknown column 'balance'",
      "request_id": "BW-a935b7fedf6beefcedc94e539cfe320cc551c5b3",
    }
  ]
}