NAV
Im token logo imToken API Documentation DApp-SDK Tokenlon-Onboarding Tokenlon-MMSK Tokenlon-MMProxy Tokenlon-JSSDK Tokenlon-Open-API
  • 介绍
  • 安装
  • 使用与初始化
  • Market API
  • Tokenlon Data API
  • Tokenlon Trade API
  • Tokenlon Chain API
  • Errors
  • 中文

    介绍

    欢迎使用 Tokenlon-Jssdk,本文档是 Tokenlon-Jssdk 的唯一官方文档,Tokenlon-Jssdk 提供的能力将会在本文档持续更新,请及时关注。

    本文档将介绍如何使用我们提供的 JS 工具对接 Tokenlon Trading API。通过本文档你将可以了解到 Tokenlon 所提供的能力,例如,获取对应的报价并使用 Tokenlon 系统进行交易等。

    安装

    考虑到安全因素,未发布至npm,需要用户手动下载 Release 最新版

    用户需检查下载的 zip 文件 sha256 是否与 Release 版本一致。例如:shasum -a 256 /path/to/file

    检查完成,解压该zip包,将该 tokenlon-jssdk 文件夹,放入你的项目,并 cd YOUR_RELATIVE_PATH/tokenlon-jssdk && yarn 安装依赖包。

    使用与初始化

    import JssdkClient, { genPersonalSign, genSignRawTransaction } from 'YOUR_RELATIVE_PATH/tokenlon-jssdk'
    // const JssdkClient = require('YOUR_RELATIVE_PATH/tokenlon-jssdk')
    // const { genPersonalSign, genSignRawTransaction } = JssdkClient
    
    const personalSignFn = genPersonalSign('YOUR PRIVATE KEY')
    const signRawTransactionFn = genSignRawTransaction('YOUR PRIVATE KEY')
    
    const jssdkClient = JssdkClient({
      debug: false,
      address: 'YOUR ADDRESS',
      providerUrl: 'PROVIDER URL',
      personalSignFn,
      signRawTransactionFn,
    })
    

    debug

    默认为 false,注意,如果设置为 trueproviderUrl 也需要同步设置为 kovan 的节点地址。

    address

    用于交易的钱包地址

    providerUrl

    可通过 https://infura.io/ 申请

    personalSignFn

    personalSignFn 方法,接受 message 作为参数,返回 签名后的 string

    signRawTransactionFn

    signRawTransactionFn 方法,接受参数类型 SignRawTransactionFnParams,返回签名结果 sign string,注意,此返回结果可用于 eth_sendRawtransaction 广播交易

    参数类型

    interface SignRawTransactionFnParams {
      to: string
      data: string
      from: string
      nonce: string
      gasLimit: string
      gasPrice: string
      value: string
    }
    

    参数举例

    {
      to: '0xdd974d5c2e2928dea5f71b9825b8b646686bd200',
      data:
       '0x095ea7b300000000000000000000000041f8d14c9475444f30a80431c68cf24dc9a8369a0000000000000000000000000000000000000000000000056bc75e2d63100000',
      from: '0xd7a0d7889577ef77c11ab5cc00817d1c9ade6b36',
      nonce: '0x9bd',
      gasLimit: '0x186a0',
      gasPrice: '0x12a05f200',
      value: '0x0',
    }
    

    返回结果举例

    '0xf8ac8209c085012a05f200830186a094dd974d5c2e2928dea5f71b9825b8b646686bd20080b844095ea7b300000000000000000000000041f8d14c9475444f30a80431c68cf24dc9a8369affffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff1ba0035b6dc663577dbe878aaaef80721ca5855226227fb9c835f6e4366365ff23e0a071ebc0e28c4f59298ed3d2c41da6de97b7e948a9a2a23f1fc8833d9dadc78fc2'
    

    补充说明

    关于 personalSignFnsignRawTransactionFn 这两个方法的实现

    1. 对区块链有经验的开发者可以参考 TODO 进行自行实现
    2. 或者开发者也可以通过 tokenlon-jssdk 提供的 genPersonalSign('YOUR PRIVATE KEY')genSignRawTransaction('YOUR PRIVATE KEY') 这两个方法,进行便捷地生成
    3. 对安全性有更高要求的团队或个人,可以采用 KMS 方式进行钱包管理
      • GCP KMS:https://cloud.google.com/kms
      • AWS KMS:https://amazonaws-china.com/kms
      • Cosmos KMS:https://github.com/tendermint/kms

    Market API

    此部分接口,为 Tokenlon Open APIJavaScript 封装实现,详细 API 文档见 Tokenlon Open API

    getPairs

    example call

    const pairs = await jssdkClient.getPairs()
    console.log('pairs', pairs)
    

    example result

    [
      "ELF_ETH",
      "ETH_TUSD",
      "ETH_USDT",
      "KNC_ETH",
      "MANA_ETH",
      "OMG_ETH",
      "OMG_USDT",
      "SNT_ETH",
      "TUSD_USDT",
      "USDC_ETH",
      "USDC_TUSD",
      "USDC_USDT",
      "ZRX_ETH",
      "ZRX_USDT"
    ]
    

    getTicker

    example call

    const ticker = await jssdkClient.getTicker({
      pairs: 'ETH_USDT',
      period: '1M',
    })
    console.log('ticker', JSON.stringify(ticker, null, 2))
    

    example result

    {
      "timestamp": 1579593604,
      "period": "1M",
      "pairs": "ETH_USDT",
      "lastTimestamp": 1579228568,
      "last": 165.35,
      "high": 167.2000379,
      "low": 143.29,
      "ask": 166.6300080649,
      "mid": 166.5550040324,
      "bid": 166.48,
      "vol": 21.19617002,
      "txs": 67,
      "wallet": 10,
      "change": 0.0226
    }
    

    getTickerHistory

    example call

    const tickerHistory = await jssdkClient.getTickerHistory({
      pairs: 'KNC_ETH',
      beginTimestamp: now - 86400 * 30,
      endTimestamp: now,
    })
    console.log('tickerHistory', JSON.stringify(tickerHistory, null, 2))
    

    example result

    [
      {
        "date": "2020-01-16",
        "period": "24H",
        "pairs": "KNC_ETH",
        "last": 0.001557100002,
        "high": 0.00168504,
        "low": 0.00126427,
        "vol": 359.91195154,
        "txs": 14,
        "wallet": 5
      },
      // ...
    ]
    

    getTradeCap

    example call

    const tradeCap = await jssdkClient.getTradeCap({
      currency: 'USD',
      period: '24H',
    })
    console.log('tradeCap', JSON.stringify(tradeCap, null, 2))
    

    example result

    {
      "timestamp": 1579593345,
      "period": "24H",
      "vol": 12.6222969804,
      "txs": 6,
      "wallet": 2,
      "currency": "USD"
    }
    

    getTradeCapHistory

    example call

    const tradeCapHistory = await jssdkClient.getTradeCapHistory({
      currency: 'USD',
      beginTimestamp: now - 86400 * 7,
      endTimestamp: now,
    })
    console.log('tradeCapHistory', JSON.stringify(tradeCapHistory, null, 2))
    

    example result

    [
      {
        "date": "2020-01-21",
        "period": "24H",
        "vol": 12.6222969804,
        "txs": 6,
        "wallet": 2,
        "currency": "USD"
      },
      // ...
    ]
    

    Tokenlon Data API

    getTokens

    example call

    const tokens = await jssdkClient.getTokens()
    console.log('tokens', JSON.stringify(tokens, null, 2))
    

    example result

    [
      {
        "symbol": "ETH",
        "contractAddress": "0x0000000000000000000000000000000000000000",
        "decimal": 18,
        "precision": 4,
        "minTradeAmount": 1e-7,
        "maxTradeAmount": 10,
        "opposites": [
          "KNC",
          "USDT"
        ]
      },
      // ...
    ]
    

    Parameter

    none

    Return Token Item

    Name Type Description
    symbol String
    contractAddress String
    decimal Number
    precision Number
    minTradeAmount Number 系统默认最小可交易数量
    maxTradeAmount Number 系统默认最大可交易数量
    opposites String[] 支持兑换的 Token Symbol

    getOrderState

    example call

    const orderState = await jssdkClient.getOrderState('0x21755702165de6d55dbab44eeb92d3d4a31a8182ee315c50f86c5db790fdd4fd')
    

    example result

    {
      "status": "success",
      "order": {
        "from": "0x974afc6906cdeb17f163b7a5a2d2a59aa488b94e",
        "to": "0xd7a0d7889577ef77c11ab5cc00817d1c9ade6b36",
        "fromToken": {
          "symbol": "KNC",
          "contractAddress": "0x25570c5f2058efc52ff34e47631f41b5f6595d42",
          "decimal": 18,
          "precision": 4,
          "minTradeAmount": 1e-7,
          "maxTradeAmount": 50000
        },
        "toToken": {
          "symbol": "ETH",
          "contractAddress": "0x0000000000000000000000000000000000000000",
          "decimal": 18,
          "precision": 4,
          "minTradeAmount": 1e-7,
          "maxTradeAmount": 10
        },
        "fromTokenAmountUnit": "0.01",
        "toTokenAmountUnit": "0.00001452",
        "executeTxHash": "0x21755702165de6d55dbab44eeb92d3d4a31a8182ee315c50f86c5db790fdd4fd",
        "txHash": "0xd8054f86c9f76eec3304f99ebcb1c68ef71eb99b8854d4f5d2d729e038af8bd4",
        "status": "success",
        "blockNumber": 15867119,
        "timestamp": 1578020919,
        "finishedTimestamp": 1578020931,
        "feeFactor": 30,
        "feeTokenSymbol": "ETH",
        "feeTokenAmountUnit": "0.00000004356",
        "actualTokenSymbol": "ETH",
        "actualTokenUnit": "0.00001447644"
      }
    }
    

    Parameter

    交易订单的 executeTxHash 字段,详见 trade API

    Return Order

    Name Type Description
    from String
    to String
    fromToken Object 用户转出的 Token,具体字段见上方
    toToken Object 用户收到的 Token,具体字段见上方
    fromTokenAmountUnit String 用户转出 Token 数量
    toTokenAmountUnit String 用户交易应获得的 Token 数量(未扣除手续费)
    executeTxHash String 订单交易后获得的唯一标识符
    txHash String 订单上链交易的 txHash
    status String 订单状态,见下方
    blockNumber Number 该笔交易被打包的区块高度
    timestamp Number 该笔交易提交到系统的时间
    finishedTimestamp Number 该笔交易最终完成的时间
    feeFactor Number 手续费率,30,代表 30/10000=0.3% (千分之三的费率)
    feeTokenSymbol String 手续费收取的 Token Symbol
    feeTokenAmountUnit String 手续费收取数量
    actualTokenSymbol String 用户实际收到的 Token 名称
    actualTokenUnit String 用户实际收到的 Token 数量(已扣除手续费)

    order 相应的 status 存在情况:

    status description
    unbroadcast 该笔订单尚未经 机器人 进行上链
    pending 该笔交易正在打包中
    success 上链交易成功
    failed 上链交易失败
    timeout 上链交易超时
    invalid 该笔订单无效
    abandoned 该笔订单未被采用

    getOrdersHistory

    example call

    const ordersHistory = await jssdkClient.getOrdersHistory({
      page: 1,
      perpage: 10,
    })
    console.log('ordersHistory', JSON.stringify(ordersHistory, null, 2))
    

    example result

    [
      {
        "from": "0x974afc6906cdeb17f163b7a5a2d2a59aa488b94e",
        "to": "0xd7a0d7889577ef77c11ab5cc00817d1c9ade6b36",
        "fromToken": {
          "symbol": "KNC",
          "logo": "https://aws-v2-cdn.token.im/app-mainnet-production/exchange-pairs/kyber.png",
          "contractAddress": "0x25570c5f2058efc52ff34e47631f41b5f6595d42",
          "decimal": 18,
          "precision": 4,
          "minTradeAmount": 1e-7,
          "maxTradeAmount": 50000
        },
        "toToken": {
          "symbol": "ETH",
          "logo": "https://v2-cdn.token.im/app-mainnet-production/tokens/icons/eth%403x.png",
          "contractAddress": "0x0000000000000000000000000000000000000000",
          "decimal": 18,
          "precision": 4,
          "minTradeAmount": 1e-7,
          "maxTradeAmount": 10
        },
        "fromTokenAmountUnit": "8.14157458",
        "toTokenAmountUnit": "0.011",
        "executeTxHash": "0xd0271b7f7202f7f7a4968745b7f2e1456f23591e5567948e7edc226c831d34fa",
        "txHash": "0x2f516d0eab28d460197bf188964d5058a8d25e1823a2e4676b2c0e028a8245ba",
        "status": "success",
        "blockNumber": 16258131,
        "timestamp": 1579589963,
        "finishedTimestamp": 1579589975,
        "feeFactor": 30,
        "feeTokenSymbol": "ETH",
        "feeTokenAmountUnit": "0.000033",
        "actualTokenSymbol": "ETH",
        "actualTokenUnit": "0.010967"
      },
      // ...
    ]
    

    Parameter

    Name Type Description
    page Number
    perpage Number

    Return

    order[],订单数组,数组项同上方 order

    Tokenlon Trade API

    getQuote

    example call

    const quoteResult = await jssdkClient.getQuote({
      base: 'ETH',
      quote: 'KNC',
      side: 'BUY',
      amount: 0.011,
    })
    

    example result

    {
      base: 'ETH',
      quote: 'KNC',
      side: 'BUY',
      amount: 0.12,
      quoteAmount: 39.792548182,
      quoteId: '3--TD-200303-100712-VHMpwdH',
      price: 331.60456818333336,
      feeSymbol: 'ETH',
      feeAmount: 0.0024,
      transferTokenSymbol: 'KNC',
      transferTokenAmount: 39.792548182,
      receiveTokenSymbol: 'ETH',
      receiveTokenAmount: 0.1176,
      priceExcludeFee: 338.37200835034014,
      timestamp: 1583230034,
      minAmount: 0.000309419,
      maxAmount: 4.5127910248,
    }
    

    Parameter

    Name Type Description
    base String
    quote String
    side String 'BUY' or 'SELL'
    amount Number 永远指代 base Token 数量

    补充说明:

    1. base 代表交易对中的基础币种,quote 代表交易对中的报价币种,ETH/USDT 中的 base 是 ETH,quote 是 USDT;USDT/ETH 中的base 是 USDT,quote 是 ETH
    2. 还是以 ETH 和 USDT 为例
      1. ETH/USDT side BUY 的 price 可能为 250 (1ETH = 250 USDT),代表购买1个ETH 需要 250 USDT
      2. ETH/USDT SELL 的 price 可能为 200 (1ETH = 200 USDT),代表卖出1个ETH 可以获得 200 USDT
    3. 因为 Tokenlon 交易只有 A 币种 兑换 B币种,没有买卖方向,所以我们也支持 USDT/ETH 这样的交易对(大家只要关注主流的交易对例如 ETH/USDT 即可
      1. USDT/ETH side BUY 的 price 可能为 0.005(1 USDT = 0.005 ETH),代表购买一个USDT,需要0.005ETH;即购买200个USDT,需要1个ETH;等同于卖出一个1ETH,可以获得 200USDT;等同于 ETH/USDT SELL 的 price 为 200 (1ETH = 200 USDT)
      2. USDT/ETH side SELL 的 price 可能为 0.004(1 USDT = 0.004 ETH),代表卖出一个USDT,可以获得0.004ETH;即卖出250个USDT,可以获得1个ETH;等同于买入一个1ETH,需要 250USDT;等同于 ETH/USDT BUY 的 price 为 250 (1ETH = 250 USDT)
    4. base/quote,side 如何与我们的 Tokenlon UI 对应?
      1. ETH -> USDT,当用户输入 ETH 数量,代表用户想要卖出 ETH,此时的对应关系为 { base: 'ETH', quote: 'USDT', side: 'SELL', amount: inputAmount }
      2. ETH -> USDT,当用户输入 USDT 数量,代表用户想要购买 USDT,此时的对应关系为 { base: 'USDT', quote: 'ETH', side: 'BUY', amount: inputAmount }
      3. USDT -> ETH,当用户输入 ETH 数量,代表用户想要购买 ETH,此时的对应关系为 { base: 'ETH', quote: 'USDT', side: 'BUY', amount: inputAmount }
      4. USDT -> ETH,当用户输入 USDT 数量,代表用户想要卖出 USDT,此时的对应关系为 { base: 'USDT', quote: 'ETH', side: 'SELL', amount: inputAmount }

    Return

    Name Type Description
    base String
    quote String
    side String 'BUY' or 'SELL'
    amount Number 永远指代 base Token 数量
    quoteAmount Number 对应的 quote Token 数量
    quoteId String 订单交易前的唯一标识符,用于 trade API
    price Number 永远指代 base 相对于 quote 的价格
    feeSymbol String 手续费收取代币名称
    feeAmount Number 手续费收取代币数量
    transferTokenSymbol String 转出的 Token 名称
    transferTokenAmount Number 转出的 Token 数量
    receiveTokenSymbol String 得到的 Token 名称
    receiveTokenAmount Number 得到的 Token 名称
    priceExcludeFee Number 排除手续费后的价格
    timestamp Number 订单返回时间,需要注意,该笔订单需要在 10s 通过 trade 进行交易才有效
    minAmount Number 此笔订单返回时做市商返回的最小可交易数量
    maxAmount Number 此笔订单返回时做市商返回的最大可交易数量

    trade

    example call

    const tradeResult = await jssdkClient.trade(quoteResult.quoteId)
    

    example result

    {
      "success": true,
      "message": null,
      "txHash": null,
      "executeTxHash": "0x140e519ffb81ce2bf23a55ba213b12193e0547d880637c909fafb4e13005ced8"
    }
    

    Parameter

    quoteId,为 getQuote API 返回

    Return

    Name Type Description
    success Boolean
    message String 错误消息
    txHash String 仅在用户交易此笔订单时,转出的Token 为 ETH 时,才会返回(用户上链);当转出的Token 为 erc20 Token 时,此交易由 Tokenlon 系统上链,用户不需要支付矿工费
    executeTxHash String 订单交易提交后,返回的唯一标识符

    补充说明:

    1. 当用户交易此笔订单,转出的Token 为 ETH 时,才会由用户上链并支付矿工费
    2. 矿工费 gasPrice 目前基于订单价值
    3. 考虑到订单成交的时效性与准确性,暂不支持 gasPrice 的自行设置
    4. 当用户交易此笔订单,转出的Token 为 erc20 token 时,此笔订单会由 Tokenlon 系统上链,用户不需要支付矿工费

    Tokenlon Chain API

    getBalance

    example call

    const balance = await jssdkClient.getBalance('ETH')
    

    example result

    4.06410224837175
    

    Parameter

    Token Symbol String

    Return

    Token Balance Number

    getBalances

    example call

    const balances = await jssdkClient.getBalances()
    

    example result

    [
      {
        "symbol": "ETH",
        "balance": 4.06410224837175
      },
      {
        "symbol": "KNC",
        "balance": 965.450009029981
      },
      {
        "symbol": "USDT",
        "balance": 0.848815
      }
    ]
    

    getAllowance

    example call

    const allowance = await jssdkClient.getAllowance('KNC')
    

    example result

    1.157920892373162e+59
    

    Parameter

    Token Symbol String

    Return

    该 Token 授权数量

    isAllowanceEnough

    example call

    const allowance = await jssdkClient.isAllowanceEnough('KNC')
    

    example result

    true
    

    Parameter

    Token Symbol String

    Return

    该 Token 授权数量是否超过其余额

    setAllowance

    example call

    const allowanceTx = await jssdkClient.setAllowance('KNC', 100)
    

    example result

    '0xb6c02a4d7f137762196934f761a671807ac2c94fc46d8f99a0f19668f7f3e7c3'
    

    Parameter

    Token Symbol String 与 需要授权的数量

    Return

    该笔授权交易的 txHash

    setUnlimitedAllowance

    example call

    const unlimitedAllowanceTx = await jssdkClient.setUnlimitedAllowance('KNC')
    

    example result

    '0x36a6f49af84309a7c878a4e266c00e8f69eea81c8b20f3a9c0d322de56adf8cb'
    

    Parameter

    Token Symbol String

    Return

    该笔全量授权的交易 txHash

    closeAllowance

    example call

    const closeAllowanceTx = await jssdkClient.closeAllowance('KNC')
    

    example result

    '0x36a6f49af84309a7c878a4e266c11e8f69eea81c8b20f3a9c0d322de56adf8cb'
    

    Parameter

    Token Symbol String

    Return

    该笔关闭授权的交易 txHash

    Errors

    Name Description
    UNSUPPORTED_TRADE_PAIR 不支持的交易对
    REQUEST_5S_TIMEOUT 订单获取 5s 超时未返回
    LESS_THAN_SYSTEM_MIN_TRADE_AMOUNT 小于系统最小可交易 Token 数量
    GREATER_THAN_SYSTEM_MAX_TRADE_AMOUNT 大于系统最大可交易 Token 数量
    LESS_THAN_MM_MIN_TRADE_AMOUNT 小于做市商最小可交易 Token 数量
    GREATER_THAN_MM_MAX_TRADE_AMOUNT 大于做市商最大可交易 Token 数量
    CAN_NOT_RESOLVE_EXCHANGE 当前不支持此交易
    NO_DATA_RESPONSED 无订单数据返回
    INVALID_QUOTE_ID_PARAM quoteId 参数错误
    QUOTE_DATA_10S_EXPIRED quoteId 对应的订单已 10s 过期
    PARAMS_ERROR 参数错误
    TOKEN_NOT_FOUND 不支持的 Token
    NONCE_CONFLICT nonce 冲突
    CONNECT_FAILED 连接失败
    ALREADY_CONNETING 连接中
    BALANCE_NOT_ENOUGH 余额不足
    ALLOWANCE_NOT_ENOUGH 授权数量不足