Coordinator HTTP API

Under Construction
This documentation is being actively worked on. Use at your own risk, or consult Rook developers directly with questions.
Introduction
HTTP endpoint
This API is API key protected and currently only provided to Keepers.  Contact us to gain access.
Headers
{
    'content-type': 'application/json',
    'Api-Key': '1243-567-890',
}
HTTP Methods
Get Keeper Stake Channel
Retrieve the payment channel for a Keeper.
GET /keeperStakeChannel
Query parameters:
stakeAddress: The address of the KSA that owns the channel.
channelNonce: The channel nonce for the channel being fetched.
Example Call:
/keeperStakeChannel?stakeAddress=0x333D1eCc55E5e27c29ad39ba4e435Bb78f6A7141&channelNonce=0
Example Response:
{
    "result": {
        "stakeAddress": "0x333d1ecc55e5e27c29ad39ba4e435bb78f6a7141",
        "channelNonce": 0,
        "stakedAmount": 1000000000000000000,
        "refundAccrued": 0,
        "latestBidAmount": 17606335671297342,
        "latestStakeAddressSignedCommitment": {
            "stakeAddress": "0x333D1eCc55E5e27c29ad39ba4e435Bb78f6A7141",
            "stakeSpent": 17606335671297342,
            "stakeNonce": 1,
            "channelNonce": 0,
            "previousCommitmentHash": "0x0000000000000000000000000000000000000000",
            "stakeAddressSignature": "0x456db65684e614577d81464fe8e85ba425dfe5517f5b3ee35e6f254b47e1567f6e4df8f335c28e52735459d033944ee2648f3e9e2f63244608d31cb42b710c401c",
            "coordinatorSignature": "0xa333e269e3dce93846fe1a1d21cb62381f7d35ea7fd01f78464d04ddfea5b34b55ae391cf731d5c14ecd2dea6ae71831b29ffcbf3bd7b702d3c64663e20860411b",
            "stakeAddressInstantWithdrawalSignature": null,
            "coordinatorInstantWithdrawalSignature": null
        },
        "latestCommitment": {
            "stakeAddress": "0x333d1ecc55e5e27c29ad39ba4e435bb78f6a7141",
            "stakeSpent": 0,
            "stakeNonce": 2,
            "channelNonce": 0,
            "previousCommitmentHash": "0xbe8454781dfc5a217358b1247e0a74946b1940ffb43bea506e9ea0f7dc74cd2c",
            "stakeAddressSignature": null,
            "coordinatorSignature": "0xeb4bc5684e6146055a525e17c306251c90e0138785684e614162fb610ae6cc5f183541b33f76fcd9be0cd6043bac3b1259044e93b45413f03472a2b59867c7421c",
            "stakeAddressInstantWithdrawalSignature": null,
            "coordinatorInstantWithdrawalSignature": null
        },
        "isOpen": true,
        "fullySettled": false
    },
    "message": "Ok"
}
refundAccrued indicates the outstanding refunds accrued in the payment channel from lost auctions and failure to fill orders.
isOpen is true if the Coordinator is still accepting bid commitments from the channel and false otherwise.
fullySettled is set to true once the KSA has withdrawn their remaining Rook for the payment channel from the staking contract and false otherwise.
latestStakeAddressSignedCommitment may not necessarily be the latest commitment. When Keepers request a refund, the Coordinator generates a new commitment with the refundAccrued subtracted from the prior commitment's stakeSpent. This commitment will only have the Coordinator's signature on it. If the Keeper wants to withdraw with this commitment, they still have everything they need.
Get Info
Retrieve relevant contract addresses, greenlight algorithm parameters, and general information about the Coordinator.
GET /info
Example Response:
{
    "result": {
        "stakeContract": "0x6662db49A05Cbe2Fb2Da2aa449f55197050E0164",
        "chainId": 1,
        "greenlightScoreWeight": {
            "bid": 4.0,
            "random": 1.0,
            "targetFillAmount": 2.0,
            "reputation": 1.0,
            "stake": 1.0
        },
        "greenlightScorePower": {
            "bid": 2.0,
            "random": 1.0,
            "targetFillAmount": 4.0,
            "reputation": 1.2,
            "stake": 1.2
        },
        "minBidThreshold_percentageOfHighestBid": 0.3,
        "bidAllocationPercentage": {
            "user": 0.8,
            "burn": 0.04,
            "stakingPool": 0.1,
            "keeperDAO": 0.06
        },
        "auctionDuration_seconds": 3,
        "keeperActionDeadline_blocks": 4
    },
    "message": "Ok"
}
Get Refund Request Message Hash
Retrieve message hash for signing that will be used to initiate an instant withdrawal request.
GET /refundRequestMessageHash
Query Parameters:
stakeAddress: The stake address withdrawing their staked Rook.
stakeNonce: The latest stake nonce of the channel being withdrawn from.
channelNonce: The channel nonce of the channel being withdrawn from.
Example Call:
refundRequestMessageHash?stakeAddress=0x333D1eCc55E5e27c29ad39ba4e435Bb78f6A7141&channelNonce=0&stakeNonce=5
Example Response:
{
    "result": "0x49e9e119ca33f3b0c46dd91c9e998701f291f3bc87660fb1fb113dc33828be65",
    "message": "Ok"
}
A Keeper can calculate the hash themselves. The message hash is calculated in python as:
keccak_256(
    eth_abi.encode_single(
        '(string,address,uint256,uint256)',
        ['refund', stakeAddress, stakeNonce, channelNonce]
    )
)
Get Stake Address Identity Registration Message Hash
Retrieve message hash for signing that will be used to register a KSA with an identity address.
GET /stakeAddressIdentityRegistrationMessageHash
Query Parameters:
stakeAddress: The stake address being registered.
identityAddress: The identity address the stake address is being registered to.
expirationTime: Unix timestamp in seconds. The signature on the hash output of this endpoint is only valid till the supplied timestamp.
Example Response:
{
    "result": "0x49e9e119ca33f3b0c46dd91c9e998701f291f3bc87660fb1fb113dc33828be65",
    "message": "Ok"
}
Register Stake Address Identity
Register a KSA to an identity address.
POST /registerStakeAddressIdentity
Query Parameters:
stakeAddress: The stake address being registered.
identityAddress: The identity address the stake address is being registered to.
expirationTime: Unix timestamp. The signature on the hash output of this endpoint is only valid till the supplied timestamp.
stakeAddressSignature: Only required if the stakeAddress is already registered to an identityAddress.
identityAddressSignature: The Ethereum signature of the identity address on the hash output from /stakeAddressIdentityRegistrationMessageHash
Get Taker Address Identity Registration Message Hash
Retrieve message hash for signing that will be used to register a KTA with an identity address.
GET /takerAddressIdentityRegistrationMessageHash
Query Parameters:
takerAddress: The taker address being registered.
identityAddress: The identity address the taker address is being registered to.
expirationTime: Unix timestamp. The signature on the hash output of this endpoint is only valid till the supplied timestamp.
Example Response:
{
    "result": "0x49e9e119ca33f3b0c46dd91c9e998701f291f3bc87660fb1fb113dc33828be65",
    "message": "Ok"
}
Register Taker Address Identity
Register a KTA to an identity address.
POST /registerTakerAddressIdentity
Query Parameters:
takerAddress: The taker address being registered.
identityAddress: The identity address the stake address is being registered to.
expirationTime: Unix timestamp. The signature on the hash output of this endpoint is only valid till the supplied timestamp.
takerAddressSignature: Only required if the takerAddress is already registered to an identityAddress.
identityAddressSignature: The Ethereum signature of the identity address on the hash output from /takerAddressIdentityRegistrationMessageHash
Get Address Identity Unregistration Message Hash
Retrieve message hash for signing that will be used to unregister a KTA or KSA from an identity address.
GET /addressIdentityUnregistrationMessageHash
Query Parameters:
identityAddress: The identity address the KTA or KSA is being unregistered from.
expirationTime: Unix timestamp. The signature on the hash output of this endpoint is only valid till the supplied timestamp.
Example Response:
{
    "result": "0x49e9e119ca33f3b0c46dd91c9e998701f291f3bc87660fb1fb113dc33828be65",
    "message": "Ok"
}
Unregister Stake Address Identity
Unregister a KSA from an identity address.
POST /unregisterStakeAddressIdentity
Query Parameters:
stakeAddress: The stake address being unregistered.
identityAddress: The identity address the stake address is being unregistered from.
expirationTime: Unix timestamp. The signature on the hash output of this endpoint is only valid till the supplied timestamp.
identityAddressSignature: The Ethereum signature of the identity address on the hash output from /addressIdentityUnregistrationMessageHash
Unregister Taker Address Identity
Unregister a KTA from an identity address.
POST /unregisterTakerAddressIdentity
Query Parameters:
takerAddress: The taker address being unregistered.
identityAddress: The identity address the taker address is being unregistered from.
expirationTime: Unix timestamp. The signature on the hash output of this endpoint is only valid till the supplied timestamp.
identityAddressSignature: The Ethereum signature of the identity address on the hash output from /addressIdentityUnregistrationMessageHash
Get Instant Withdrawal Request Message Hash
Retrieve message hash for signing that will be used to initiate an instant withdrawal request.
GET /instantWithdrawalRequestMessageHash
Query Parameters:
stakeAddress: The stake address withdrawing their staked Rook.
channelNonce: The channel nonce of the channel being withdrawn from.
Example Response:
{
    "result": "0x49e9e119ca33f3b0c46dd91c9e998701f291f3bc87660fb1fb113dc33828be65",
    "message": "Ok"
}
Initiate Instant Withdrawal
Initiate an instant withdrawal. Once fully processed, the coordinator's instant withdrawal signature can be retrieved from the /keeperStakeChannel endpoint.
POST /initiateInstantWithdrawal
Query Parameters:
stakeAddress: The stake address being unregistered.
channelNonce: The channel nonce of the channel being withdrawn from
stakeAddressSignature: The Ethereum signature of the stake address on the hash output from /instantWithdrawalRequestMessageHash
Websocket API
Message Types
The message type is specified in the JSON payload using the type field.
Subscribe
Used to subscribe to a channel to receive messages indicating when a new auction of a particular type has started.
Example Request:
{
   "channel": "limitOrder",
   "requestId": 38520892865339,
   "type": "subscribe"
}
Example Success Response:
{
    "type": "subscribe",
    "channel": "limitOrder",
    "message": "Successfully subscribed to channel",
}
Bid
Used to place a bid on one or more orders. See placing bids for how to structure the payment field. See the example below for the limit order bid format. The auctionId is the hiding book order hash.
Example Request:
{
   "bids":[
      {
         "auctionId":"0x5a23000386c7b763f77e947bd64571afbde64d848d207fa981c32587eafaec00",
         "chainId":31337,
         "channel":"limitOrder",
         "protocol":"zrxV4RFQ",
         "takerTokenTargetFillAmount":222
      }
   ],
   "payment":{
      "stakeAddress":"0xE91f7bB6C34315d50a739bb94bbDEaC916E17233",
      "stakeSpent":66159044473427503,
      "stakeNonce":1,
      "channelNonce":0,
      "previousCommitmentHash":"0x0000000000000000000000000000000000000000",
      "stakeAddressSignature":"0x29b2daf2484ad20bf31d2f4e8da5656ccb14f4f0cfac1d9742d101bec79144a95ad7cbc3c8d039823dd38a2ca384dfc762041743e908ec514fccae4b3e293d0e1b",
      "identityAddress":"0x6B2902918a10984875f7aC6Fd3eae87d1cDBb4A6",
      "takerAddress":"0x26CbC5650944a0D0454291DCC105646c52c70b00"
   },
   "requestId":29234464271939,
   "type":"bid"
}
Refund
Used to issue any outstanding refunds. Must provide a stake address, channel nonce, the latest stake nonce, and a signature from the stake address in the payload. See refunds:
Example Request:
{
   "payload":{
      "channelNonce": 0,
      "stakeAddress": "0x407EA0314F43E4cbBab28Bfd47f391e8968c9643",
      "stakeAddressSignature": "0xf293586e495027b5893c00000016040b3041f4aef9d5ae000051fe2dac7c73aa64cc127bd156beb2f9b4d69c80ab3dd2cfc494b31cbb69b83844a78dc85859711c",
      "stakeNonce": 1
   },
   "requestId": 33684210724642,
   "type": "refund"
}
Example Response:
{
   "type": "refund", 
   "requestId": "33684210724642", 
   "payload": {
      "refundCommitment": {
         "stakeAddress": "0x407ea0314f43e4cbbab28bfd47f391e8968c9643", 
         "stakeSpent": 0, 
         "stakeNonce": 2, 
         "channelNonce": 0, 
         "previousCommitmentHash": "0x38fc7f3df34366e402d8b665cba162cde3508bfbb333fa77450ce1529a539ecb",
         "stakeAddressSignature": null, 
         "coordinatorSignature": "0x5b8df00000e3a0539a042ffcd26d000002a8912e2d568a4a862126acc122aa342f12c56f4d7b01117cf6ac393464b3c4f52998c8f2b0b9725d0282c7f1e2f76d1c",
         "stakeAddressInstantWithdrawalSignature": null,
         "coordinatorInstantWithdrawalSignature": null
    }
  }
}
Auction
Used by the Coordinator to deliver information about who has been greenlit for an auction.
Example Greenlight Message:
{
   "channel":"limitOrder",
   "type":"auction",
   "requestId":82091778811918,
   "payload":{
      "auctionIdList":[
         "0xab29508897ee5a2714fa58705bd834390e8cf9979b5202680c05ca2e4459a05c"
      ],
      "identityAddress":"0x6B2902918a10984875f7aC6Fd3eae87d1cDBb4A6",
      "stakeAddress":"0xE91f7bB6C34315d50a739bb94bbDEaC916E17233",
      "takerAddress":"0x26CbC5650944a0D0454291DCC105646c52c70b00",
      "greenlit":1,
      "bidState":"locked"
   }
}
Keep Alive
Used to keep connection alive.
Example Request:
{
   "type": "keepAlive"
}
Get Info
Used to retrieve relevant contract addresses.
Example Request:
{
   "type": "info",
   "requestId": 33684210724642
}
Payment Channels Staking Contract
Structs
StakeCommitment
struct StakeCommitment {
    address stakeAddress;
    uint256 stakeSpent;
    uint256 stakeNonce;
    uint256 channelNonce;
    bytes data;
    bytes stakeAddressSignature;
    bytes coordinatorSignature;
}
See Transacting Using the Payment Channel for an explanation of each field.
Methods
getStakerState
function getStakerState(address _stakeAddress) public view returns (
    uint256 _stakedAmount, 
    uint256 _stakeNonce, 
    uint256 _stakeSpent, 
    uint256 _channelNonce, 
    uint256 _withdrawalTimelock
);
Used to retrieve the most recent settled state for a payment channel. _withdrawalTimelock will be non-zero if the payment channel is currently in the timelocked withdrawal process and will indicate the timestamp of the timelock's expiration.
stakeCommitmentHash
function stakeCommitmentHash(
    address _stakeAddress, 
    uint256 _stakeSpent, 
    uint256 _stakeNonce, 
    uint256 _channelNonce, 
    bytes memory _data
) public pure returns (bytes32);
Used to calculate the hash of a payment channel commitment for signing.
getCurrentWithdrawalTimelock
function getCurrentWithdrawalTimelock(
    address _stakeAddress
) public view returns (uint256);
Used to retrieve the current withdrawal timelock for the payment channel of the provided stake address. It will be zero if there is no timelock and will return the timestamp of the timelock's expiry otherwise.
stake
function stake(uint256 _amount) public;
Used to stake rook, adding rook to the active payment channel of msg.sender if there is one, and creating a new payment channel otherwise. Not that additional rook cannot be staked for a payment channel that is currently in a withdrawal timelock.
initiateTimelockedWithdrawal
function initiateTimelockedWithdrawal(
    StakeCommitment memory _commitment
) external;
Used to initiate the timelocked withdrawal process.
executeTimelockedWithdrawal
function executeTimelockedWithdrawal(
    address _stakeAddress
) public;
Used to complete the timelocked withdrawal process and withdraw the remaining rook in a payment channel.
executeInstantWithdrawal
function executeInstantWithdrawal(
    StakeCommitment memory _commitment
) external;
Used to complete the instant withdrawal process and withdraw the remaining rook in a payment channel.
Integration guides - Previous
HidingBook WS API
Next - Integration guides
Coordinator WS API
Last modified 5mo ago
Copy link
Outline
Introduction
HTTP endpoint
Headers
HTTP Methods
Websocket API
Message Types
Payment Channels Staking Contract
Structs
Methods