Skip to content

Latest commit

 

History

History
283 lines (220 loc) · 8.18 KB

interfaces.md

File metadata and controls

283 lines (220 loc) · 8.18 KB

Interfaces for Market-Makers

The market maker needs to implement following 5 Tokenlon-MMSK interfaces:

  1. The pairs interface asks market maker for authorized trading currency pairs
  2. The indicativePrice interface asks market maker to provide a reference price for a specific trading currency pair
  3. The price interface asks the market maker quoting prices for a specific trading amount
  4. The deal interface: Once the quote confirmed by the users, the Tokenlon Server will push an order to the MMSK, and MMSK then notifies the market maker via the deal interface
  5. The exception interface: Once the order has some exception situation, the Tokenlon Server will push an exception order to the MMSK, and MMSK then notifies the market maker via the exception interface

HTTP approach

pairs interface

Request

curl 'HTTP_SERVER_ENDPOINT/pairs'

Response

// Returned in normal conditions
{
  "result": true,
  "pairs": [
    "SNT/ETH",
    "OMG/ETH",
    "DAI/ETH"
  ]
}

// Returned in other circumstances
{
  "result": false,
  "message": "Exception"
}

Request address: HTTP_SERVER_ENDPOINT/pairs

pairs array item represents a trading pair, such as "SNT/ETH" Market makers need to support { base: 'SNT', quote: 'ETH' } and { base: 'ETH', quote: 'SNT' }.

Parameter

GET

return

none

request return

Returned in normal conditions
Name Type Description
result Boolean whether normal return
pairs Array pair string array
Returned in other circumstances
Name Type Description
result Boolean whether normal return
message String possible error information

indicativePrice interface

Request

curl 'HTTP_SERVER_ENDPOINT/indicativePrice?base=SNT&quote=OMG&amount=30&side=BUY'

Response

// Returned in normal conditions
{
  "result": true,
  "exchangeable": true,
  "price": 0.00017508,
  "minAmount": 0.0002,
  "maxAmount": 100
}

// Returned in other circumstances
{
  "result": false,
  "exchangeable": false,
  "minAmount": 0.0002,
  "maxAmount": 100,
  "message": "insufficient balance"
}

Request URL: HTTP_SERVER_ENDPOINT/indicativePrice

In the indicativePrice interface，amount can be 0 or undefinedThe primary use for this is the initial price, that is displayed when the user hasn’t yet entered a quantity into the exchange frontend, and at that time, the Indicative Price need is expected to response an price without amount. After the user entered an amount into the frontend，if that amount is valid(can accept this amount's trade) the Indicative Price is expected to be close to Quotes/Deal Price

Request return

GET

Request parameters

Name Type Mandatory Description
base String YES base symbol
quote String YES quote symbol
side String YES 'BUY' or 'SELL'
amount Number NO BUY or SELL base amount

Request return

Returned in normal conditions
Name Type Description
result Boolean whether normal return
exchangeable Boolean Whether is tradable
minAmount Number The minimum amount that base token can be traded
maxAmount Number The maximum amount that base token can be traded
price Number
Returned in other circumstances
Name Type Description
result Boolean whether normal return
exchangeable Boolean Whether is tradable
minAmount Number The minimum amount that base token can be traded
maxAmount Number The maximum amount that base token can be traded
message String possible error information

price interface

Request

curl 'HTTP_SERVER_ENDPOINT/price?base=SNT&quote=OMG&amount=30&side=BUY&uniqId=dfdsfjsidf'

Response

// Returned in normal conditions
{
  "result": true,
  "exchangeable": true,
  "price": 0.00017508,
  "minAmount": 0.0002,
  "maxAmount": 100,
  "quoteId": "asfadsf-dsfsdf-ggsd-qwe-rgjty"
}

// Returned in other circumstances
{
  "result": false,
  "exchangeable": false,
  "minAmount": 0.0002,
  "maxAmount": 100,
  "message": "insufficient balance"
}

Request URL: HTTP_SERVER_ENDPOINT/price

Market maker need to lock his/her inventory - according to the uniqId (uniqId: pujft40a、uniqId: pujft40a-1、uniqId: pujft40a-2 are treated as the same uniqId) of the user. The market maker needs to return the quoteId to track orders’ life-cycle. If the order corresponding to the quoteId exceeds 30s and the deal interface does not receive the order confirmed notification corresponding to the quoteId, the quotes corresponding to the quoteId is considered invalid and the position locks can be removed.

Request return

GET

Request parameters

Name Type Mandatory Description
base String YES base symbol
quote String YES quote symbol
side String YES 'BUY' or 'SELL'
amount Number YES BUY or SELL base amount
uniqId String YES Identifies each unique user

Request return

Returned in normal conditions
Name Type Description
result Boolean whether normal return
exchangeable Boolean Whether is tradable
minAmount Number The minimum amount that base token can be traded
maxAmount Number The maximum amount that base token can be traded
price Number
quoteId String A unique value used to track the final order of the quotation and the transaction status.
Returned in other circumstances
Name Type Description
result Boolean whether normal return
exchangeable Boolean Whether is tradable
minAmount Number The minimum amount that base token can be traded
maxAmount Number The maximum amount that base token can be traded
message String possible error information

deal interface

Request

curl -X POST \
  HTTP_SERVER_ENDPOINT/deal \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{"makerToken": "SNT","takerToken":"OMG","makerTokenAmount":30,"takerTokenAmount":0.1,"quoteId":"234dsfasd-sdfasdf-sdfasf","timestamp":1231234324}'

Response

{
  "result": true
}

Request address: HTTP_SERVER_ENDPOINT/deal

Request return

POST

Request parameters

Name Type Mandatory Description
makerToken String YES token symbol
takerToken String YES token symbol
makerTokenAmount Number YES maker token's amount
takerTokenAmount Number YES taker token's amount
quoteId String YES quoteId from price interface
timestamp Number YES

Request return

Name Type Description
result Boolean We suggest you just return true. If you return false, Tokenlon will always retry to send this notification to you, and it maybe repeat your hedge.

exception interface

Request

curl -X POST \
  HTTP_SERVER_ENDPOINT/exception \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{"makerToken": "SNT","takerToken":"OMG","makerTokenAmount":30,"takerTokenAmount":0.1,"quoteId":"234dsfasd-sdfasdf-sdfasf","timestamp":1231234324,"type":"FAILED"}'

Response

{
  "result": true
}

Parameter

Name Type Mandatory Description
makerToken String YES token symbol
takerToken String YES token symbol
makerTokenAmount Number YES maker token's amount
takerTokenAmount Number YES taker token's amount
quoteId String YES quoteId from price interface
type String YES 'FAILED' means that order failed; 'TIMEOUT' means that order timeout(also failed too)；'DELAY' means that order is executed but Tokenlon didn't notify MM by deal API
timestamp Number YES

return

Name Type Description
result Boolean We suggest you just return true. If you return false, Tokenlon will always retry to send this notification to you, and it maybe repeat your processing.