API Reference

Table of Contents

hub.proto

Hub

Method Name Request Type Response Type Description
CreateUser CreateUserRequest CreateUserReply Creates a new user on the Hub
GetBalance GetBalanceRequest GetBalanceReply Returns the available balance for a user
GetDepositAddress GetDepositAddressRequest GetDepositAddressReply Creates a new deposit address for a user
UserWithdraw UserWithdrawRequest UserWithdrawReply Submits a withdrawal request for a user.
UserWithdrawCancel UserWithdrawCancelRequest UserWithdrawCancelReply Attempts to cancel a user's withdrawal request. Only possible as long as sweep hasn't started yet.
GetUserHistory GetUserHistoryRequest GetUserHistoryReply Returns a user's full balance change history as recorded by the Hub
ProcessTransferBatch ProcessTransferBatchRequest ProcessTransferBatchReply Processes a batch of buys/sells from the exchange Note that the amounts of this batch must sum to 0!
BalanceSubscription BalanceSubscriptionRequest BalanceEvent Produces a stream of all balance changes as they appear since the provided timestamp
GetStats StatsRequest StatsReply Provides statistics about the Hub
SweepSubscription SweepSubscriptionRequest SweepEvent Produces a stream of all sweeps since the provided timestamp
GetAddressInfo GetAddressInfoRequest GetAddressInfoReply Provides information on an address if it's owned by the Hub
SweepInfo SweepInfoRequest SweepEvent Provides information on the sweep for the given withdrawal or bundle hash
SignBundle SignBundleRequest SignBundleReply Provides a signature for a bundle hash
SweepDetail SweepDetailRequest SweepDetailReply Provides detailed information on the sweep for the bundle hash

messages.proto

BalanceEvent

Field Type Label Description
userAccountEvent UserAccountBalanceEvent
userAddressEvent UserAddressBalanceEvent
hubAddressEvent HubAddressBalanceEvent

BalanceSubscriptionRequest

Field Type Label Description
newerThan uint64 Balances newer than this time (MS since epoch) will be retrievd

CreateUserReply

Reply for creating a new user.
Currently unused.

CreateUserRequest

Request for creating a new user.
Field Type Label Description
userId string

Error

The generic Error that will be used to return an error code on, e.g. Status::CANCELLED.
The error will be serialised and stored in the Status' detail field.
Field Type Label Description
code ErrorCode

GetAddressInfoReply

Field Type Label Description
userId string The user identifier who owns an address

GetAddressInfoRequest

Field Type Label Description
address string The address to look up

GetBalanceReply

Reply containing a user's currently available balanc.e
Field Type Label Description
available int64 User balance that is currently available for withdrawal / trades

GetBalanceRequest

Request for requesting a user's currently available balance.
Field Type Label Description
userId string

GetDepositAddressReply

Reply containing the new deposit address.
Field Type Label Description
address string Newly created deposit address

GetDepositAddressRequest

Request for creating a new deposit address for a user.
Field Type Label Description
userId string
includeChecksum bool

GetUserHistoryReply

Field Type Label Description
events UserAccountBalanceEvent repeated List of all user balance events for given user

GetUserHistoryRequest

Field Type Label Description
userId string UserId
newerThan uint64 Records newer than this time (MS since epoch) will be retrievd

HubAddressBalanceEvent

Field Type Label Description
hubAddress string
amount int64
reason HubAddressBalanceReason
sweepBundleHash string
timestamp uint64

ProcessTransferBatchReply

ProcessTransferBatchRequest

This request contains a netted transfer batch. UserIds must be unique.
Field Type Label Description
transfers ProcessTransferBatchRequest.Transfer repeated

ProcessTransferBatchRequest.Transfer

Field Type Label Description
userId string
amount int64

SignBundleReply

Field Type Label Description
signature string The resulting signature

SignBundleRequest

Field Type Label Description
address string The Hub-owned IOTA address that should be signed. (without checksum)
bundleHash string The bundle hash that should be signed.
authentication string Authentication token
validateChecksum bool should command validate address

StatsReply

Field Type Label Description
totalBalance uint64 Total balance currently managed by the hub.

StatsRequest

SweepDetailReply

Field Type Label Description
confirmed bool Sweep's confirmation status
trytes string repeated Sweep's transactions trytes
tailHash string repeated Sweep's tails hashes (multiple reattachment for each bundle)

SweepDetailRequest

Field Type Label Description
bundleHash string Sweep's bundle hash

SweepEvent

Field Type Label Description
bundleHash string
timestamp uint64
withdrawalUUID string repeated

SweepInfoRequest

Field Type Label Description
withdrawalUUID string WIthdrawal UUID to look up
bundleHash string Sweep's bundle hash

SweepSubscriptionRequest

Field Type Label Description
newerThan uint64 Sweeps newer than this time (MS since epoch) will be retrievd

UserAccountBalanceEvent

Field Type Label Description
userId string
timestamp uint64 Time since epoch in MS when the balance change occured
type UserAccountBalanceEventType
amount int64
sweepBundleHash string Will contain sweep bundle hash on deposit Will contain withdrawal uuid on withdrawal or withdrawal cancel
withdrawalUUID string

UserAddressBalanceEvent

Field Type Label Description
userId string
userAddress string
amount int64
reason UserAddressBalanceReason
hash string Depositing bundle's tail (if reason == DEPOSIT) Bundle hash of sweep (if reason == SWEEP)
timestamp uint64

UserWithdrawCancelReply

Reply for withdrawal cancellation.
Field Type Label Description
success bool True if withdrawal could be canceled

UserWithdrawCancelRequest

Request to cancel an already submitted withdrawal.
Field Type Label Description
uuid string Withdrawal UUID that is to be canceled

UserWithdrawReply

Field Type Label Description
uuid string This withdrawal's UUID

UserWithdrawRequest

Requests a user-submitted withdrawal.
This will fail if the user does not have sufficient balance available.
Field Type Label Description
userId string
payoutAddress string Address the user requests payout to. Should be without checksum.
amount uint64 Requested withdrawal amount
tag string Tag for withdrawal
validateChecksum bool should command validate address

ErrorCode

Error codes that can be returned by the hub.
Name Number Description
EC_UNKNOWN 0 Unused.
USER_EXISTS 1 UserId already exists.
USER_DOES_NOT_EXIST 2 UserId does not exist.
INSUFFICIENT_BALANCE 3 The user has insufficient balance for this operation.
BATCH_INVALID 4 The batch is invalid (does not sum to 0 or user ids not unique)
BATCH_INCONSISTENT 5 The batch is inconsistent (attempt to remove funds from a user's account without sufficient balance)
BATCH_AMOUNT_ZERO 6 The amount associated with the transfer is invalid (should be greater or less than 0)
UNKNOWN_ADDRESS 7 The address is not known to the hub
WITHDRAWAL_CAN_NOT_BE_CANCELLED 8 Either the withdrawal has been swept or cancelled already
INELIGIBLE_ADDRESS 9 Address was not eligible for the requested operation.
INVALID_AUTHENTICATION 10 Provided authentication token was invalid.
CHECKSUM_INVALID 11 Provided address contained invalid checksum
SIGNING_FAILED 12 Call to rpc signing_server failed (GetSignatureForUUID)
GET_ADDRESS_FAILED 13 Call to rpc signing_server failed (GetAddressForUUID)
GET_SECURITY_LEVEL_FAILED 14 Call to rpc signing_server failed (GetSecurityLevel)

HubAddressBalanceReason

Name Number Description
HUB_UNKNOWN 0
INBOUND 1 Sweep inbound (used as reminader address)
OUTBOUND 2 Sweep outbound (used as input)

UserAccountBalanceEventType

Name Number Description
UAB_UNKNOWN 0 Unused
DEPOSIT 1 Deposit into user account (positive amount)
BUY 2 User received tokens as part of a transfer batch (positive amount)
WITHDRAWAL 3 User withdrawal request (negative amount)
WITHDRAWAL_CANCELED 4 Cancelled user withdrawal request (positive amount)
SELL 5 User lost tokens as part of a transfer batch (negative amount)

UserAddressBalanceReason

Name Number Description
UADD_UNKNOWN 0
UA_DEPOSIT 1 New user deposit tracked
UA_SWEEP 2 Hub-sweep.

Scalar Value Types

.proto Type Notes C++ Type Java Type Python Type
double double double float
float float float float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long
uint32 Uses variable-length encoding. uint32 int int/long
uint64 Uses variable-length encoding. uint64 long int/long
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long
sfixed32 Always four bytes. int32 int int
sfixed64 Always eight bytes. int64 long int/long
bool bool boolean boolean
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode
bytes May contain any arbitrary sequence of bytes. string ByteString str