APIP2V1_BasicInfoOnChain(zh-CN)



  • APIP2: BasicInfoOnChain
    Version: 1
    Language: zh-CN
    Author: C_armX
    Status: draft
    Created date: 2021-10-30
    Updata:2021-11-26
    File hash: ""
    TXid: 
    

    APIP2V1_BasicInfoOnChain(zh-CN)


    目录

    摘要

    什么是APIP

    APIP协议的共识

    本协议的基本共识

    [1. 余额接口](#1. 余额接口)

    [2. 最小币天utxo接口](#2. 最小币天utxo接口)

    [3. 币天筛选utxo接口](#3. 币天筛选utxo接口)

    [4. 交易信息接口](#4. 交易信息接口)

    [5. 交易列表接口](#5. 交易列表接口)

    [6. 未确认交易接口](#6. 未确认交易接口)

    [7. 向导接口](#7. 向导接口)


    摘要

    Type: APIP
    SerialNumber: 2
    ProtocolName: BasicInfoOnChain
    Version: 1
    Description : Freecash主链基础信息API规范.
    Author: C_armX
    Language: zh-CN
    tags: APIP, API, Basic information
    preVersionHash:""
    

    什么是APIP

    1. APIP是自由共识生态协议的一种类型,用于创建开放的API文档,并且按照《FEIP1_FreeProtocol》的规则发布在Freecash主链上。

    2. “自由共识”是基于去中心化的密码身份的开放生态,APIP协议为该生态构建去中心化的API市场。

    3. 任何人可按照某个APIP协议开发和提供相应的API服务。

    4. 各种密码应用(CAPP)在开发时只根据需要选用APIP协议,运行时可动态选择该协议的任何一个API服务实例。

    5. CAPP指的是采用椭圆曲线算法的公私钥作为身份系统的各种应用程序。

    APIP协议的共识

    1. 按照APIP类型发布的接口的唯一标识为:接口名称@PID#[接口协议的PID]。示例:

    txList@PID#855fa18ea748a558404dba9fffde10691feac325a6e8fbdc7fc3a0afe84e736d

    1. API的URL路径由服务商按照《FEIP29_Service》协议在“url”字段发布上链。

    2. APIP协议涉及的时间戳,若无特定说明,默认为13位,精确到毫秒。

    3. 采用HTTP/HTTPS协议POST方法请求时,参数采用JSON格式,请求头部包含:Content-type: application/json

    4. 无特殊说明,哈希算法采用两次sha256算法,即:sha256(sha256([message])).

    5. 请求参数的筛选字段:

      • 筛选字段在原字段名前加filter,如:以cd为筛选条件的字段为filterCd

      • 数字类型:"filterCd": "-2, 3, 4-5, 7-"

        对cd字段进行筛选,选择值小于2(不含2)、或等于3、或4与5之间(含4和5)、或大于4(不含4)的所有条目。

      • 字符串类型:

        • 模糊查询: "filterCid": "C_arm"

          不区分大小写,查询cid字段所有包含“C_arm”的条目,如“C_ARmX”。

        • 非空查询: "filterOpReturn":"not_null"

          查询opReturn字段非空的所有条目。

        • 为空查询:"filterOpReturn":"null"

          查询opReturn字段为空的所有条目。

      • 布尔类型: "filterStatus": 0

      • 多个筛选字段时,筛选关系为“与”,即满足所有筛选条件。

        {
          "filterCd": "7-",
          "filterCid": "arm"
        }  //查询cd大于7,且cid包含"arm"的条目。
    
    1. 请求参数的排序字段:

      • 排序字段在原字段名前加sort,如以cd排序的字段名为sortCd

      • 排序字段的值为up(升序)或down(降序):

        "sortCd": "up"

        即:以cd字段升序排序

      • 每次请求的排序字段唯一,不支持多级排序。

    2. 请求批量数据时,以count字段给出每次请求的条目数,sequence字段给出当前请求第几批次。sequence从0开始,缺省默认为第0批。如:

    {
        "count":100,
        "sequence":3
    }
    //即:请求排序为第201至300项,共100项数据。
    
    1. CAPP向API服务请求连接和请求数据的方式遵循《APIP1_OpenAPI》协议。流程概述如下:

      • 请求方通过connect接口请求连接API服务,成功后获得对称密钥secretKey用于数据请求和验证。

      • 请求数据时,在请求参数中加入timestamp,采用POST方法时,还需加入API的url

      • 所有请求参数按字母升序排列,不区分大小写。

      • secretKey追加至末尾然后经两次sha256哈希获得签名sign

      • 签名后,删除secretKey字段,将requestersign追加至末尾。

      • API服务方验证requester授权、signtimestamp、POST方法url等均有效或正确后予以响应。

      • 响应参数按字母升序排序压缩后,加入secretKey后哈希签名,再用sign替换secretKey后响应请求。

      • 请求方获得数据后,用secretKey替换sign后哈希签名,值与sign值一致则接受数据。

    本协议的基本共识

    1. 本协议接口提供Freecash主链上的主要信息。

    2. 本协议接口的数据来源涉及以下协议:

      • coindays:《FIPA4_Coindays》
      • guide:《FIPA6_Guide》
    3. 本协议接口数据采用JSON格式。

    4. 示例数据:

    requester: FEk41Kqjar45fLDriztUDTUkdki7mmcjWK
    
    requester的公钥: 030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a
    
    requester的私钥: L2bHRej6Fxxipvb4TiR5bu1rkT3tRp8yWEsUy4R1Zb8VMm2x7sd8
    
    requester的secretKey: d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09
    
    api URL: https://www.sign.cash/api/
    

    1. 余额接口

    名称

    balance

    说明

    获取FCH地址的FCH余额、币天余额、累计销毁币天总额。

    请求参数

    name type description
    address string FCH address
    • 示例

    查询FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts的fch余额和币天余额。

    参数

    {
    	"address": "FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
    	"timestamp": 1635513688254
    }
    

    GET

    - unsignedRequest:
    
    https://www.sign.cash/api/balance?address=FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts&timestamp=1635513688254
    
    - sign = sha256(sha256(https://www.sign.cash/api/balance?address=FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts&timestamp=1635513688254&secretKey=d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09))=1111111111111110000000000000000000000
    
    - signedRequest:
    
    https://www.sign.cash/api/balance?address=FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts&timestamp=1635513688254&requester=FEk41Kqjar45fLDriztUDTUkdki7mmcjWK&sign=1111111111111110000000000000000000000
    

    POST

    - URL:https://www.sign.cash/api/balance
    
    - unsignedRequest:
    
    {"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","timestamp":1635513688254,"url":"https://www.sign.cash/api/balance"}
    
    - sign = sha256(sha256({"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","timestamp":1635513688254,"url":"https://www.sign.cash/api/balance","secretKey":"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"}))=2435ecb3af20d3694c1d5e1e6dd3c6b6030a1e70c824cff33c6877a0f1ab2a22
    
    - signedRequest:
    
    {"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","timestamp":1635513688254,"url":"https://www.sign.cash/api/balance","requester":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","sign":"2435ecb3af20d3694c1d5e1e6dd3c6b6030a1e70c824cff33c6877a0f1ab2a22"}
    

    响应参数

    name type description
    fchBalance uint64 Fch balance of the address in units of "satoshi".
    changeUnconfirmed int64 Unconfirmed balance changes。Negative value means a decrease in the amount.
    cdBalance uint64 Coindays balance of the address.
    cdDestroyed uint64 Coindays destroyed of this address
    height uint The latest block height when getting the data.
    • 示例
    
    {
        "cdBalance": 2100000000,
        "cdDestroyed": 342742273400,
        "changeUnconfirmed":-110000000, //总额为1.1fch的支出尚未被确认。
        "fchBalance": 210000000,  //单位为satoshi,即2.1fch。
        "heignt": 963667
    }
    
    排序、压缩、签名后:
    
    {"cdBalance":2100000000,"cdDestroyed":342742273400,"changeUnconfirmed":-110000000,"fchBalance":210000000,"heignt":963667,"sign":"8dc6959ad19fa0ee1a46f092e278fda26c3a1c32b964f7993736940e194439cd"}
    
    

    返回值

    返回值 类型 必填 说明
    code uint Y 返回码
    msg string Y 返回信息
    data object N 相关数据
    • 返回信息详情
    code msg 说明 data字段
    0 OK 请求成功
    1 Unknown error. 未知错误 signedRequest
    2000 The address has not been used. 地址从未被使用 address
    • 示例
    {
        "code":2000,
        "msg":"The address has not been used.",
        "data":{
            "address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts"
        }
    }
    

    2. 最小币天utxo接口

    名称

    utxoWithMinCd

    说明

    获取满足支付金额,且销毁最小币天所需的utxo列表。

    请求参数

    name type description
    address string FCH address
    amount uint64 The amount of fch to be paid in unit of satoshi.
    • 示例

    查询从FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts地址支付1.2fch,消耗最小币天所需要的utxo列表。

    参数

    {
    	"address": "FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
    	"amount": "120000000",
    	"timestamp": 1635513688254,
    }
    

    GET

    
    - unsignedRequest:
    
    https://www.sign.cash/api/utxoWithMinCd?address=FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts&amount=120000000&timestamp=1635513688254
    
    - sign = sha256(sha256(https://www.sign.cash/api/utxoWithMinCd?address=FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts&amount=120000000&timestamp=1635513688254&secretKey=d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09))=d173866974f8b58f4a51738d2c16f455ee2f653aa01e2ebb10f814906348156b
    
    - signedRequest:
    
    https://www.sign.cash/api/utxoWithMinCd?address=FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts&amount=120000000&timestamp=1635513688254&requester=FEk41Kqjar45fLDriztUDTUkdki7mmcjWK&sign=d173866974f8b58f4a51738d2c16f455ee2f653aa01e2ebb10f814906348156b
    

    POST

    
    - URL:https://www.sign.cash/api/utxoWithMinCd
    
    - unsignedRequest:
    
    {"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","amount":"120000000","timestamp":1635513688254,"url":"https://www.sign.cash/api/utxoWithMinCd"}
    
    - sign = sha256(sha256({"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","amount":"120000000","timestamp":1635513688254,"url":"https://www.sign.cash/api/utxoWithMinCd","secretKey":"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"}))=1fca860f831b7839031f0726d4b1853558e5d79da7dc4e1d8fed6133c7b3fd90
    
    - signedRequest:
    
    {"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","amount":"120000000","timestamp":1635513688254,"url":"https://www.sign.cash/api/utxoWithMinCd","requester":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","sign":"1fca860f831b7839031f0726d4b1853558e5d79da7dc4e1d8fed6133c7b3fd90"}
    

    响应参数

    name type description
    utxoList object The list of UTXOs returned,see below.
    height uint The latest block height when getting the data.

    utxoList:

    name type description
    共识 string The txid of the trasaction including the utxo.
    index uint The index number of the utxo in the transaction.
    amount uint The fch amount of the utxo in unit of satoshi.
    cd uint The coindays of the utxo.
    • 示例
    { 
        "utxoList": [
            {"txid":"b70afeba69341ee5c026bff348388c1f8e52a9862cf699f2f65e731890bdf186","index":2, "amount":899876,"cd",198247800},
            {"txid":"b70afeba69341ee5c026bff348388c1f8e52a9862cf699f2f65e731890bdf186","index":0, "amount":100000,"cd":0},
        ],
        "heignt": 963667
    }
    
    排序、压缩、签名
    
    {"heignt":963667,"utxoList":[{"amount":899876,"cd":198247800,"index":2,"txid":"b70afeba69341ee5c026bff348388c1f8e52a9862cf699f2f65e731890bdf186"},{"amount":100000,"cd":0,"index":0,"txid":"b70afeba69341ee5c026bff348388c1f8e52a9862cf699f2f65e731890bdf186"}],"sign":"b5ec77ddfd2ff56ecf258131f98395efc6d5151739af2d3895e308fd127e4692"}
    

    返回值

    返回值 类型 必填 说明
    code uint Y 返回码
    msg string Y 返回信息
    data object N 相关数据
    • 返回信息详情:
    code msg 说明 data字段
    0 OK 请求成功
    1 Unknown error. 未知错误 signedRequest
    2000 The address has not been used. 地址从未被使用 address
    2001 There is no UTXO at this address. 该地址没有utxo address
    2002 There is not enough balance. 该地址余额不够 address,amount
    2003 There are too many UTXOs required to pay this amount. Please merge UTXOs first. 所需UTXO太多,请先合并UTXO address,amount,maxUtxoCount
    • 示例
    {
        "code":2003,
        "msg":"There are too many UTXOs required to pay this amount. Please merge UTXOs first.",
        "data":{
            "address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
            "amount":2300000000,
            "maxUtxoCount":100
        }
    }
    

    3. 币天筛选utxo接口

    名称

    utxoFilteredByCd

    说明

    按照币天进行排序和筛选所需要的特定数量utxo。

    请求参数

    name type description
    address string FCH address
    utxoCount uint The number of the UTXOs requested.
    filterCd string Filter by the value of the cd field.
    • 示例

    请求FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts地址的币天小于等于100的2个utxo。

    参数

    {
    	"address": "FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
    	"utxoCount": 2,
    	"filterCd": "-100,100",
    	"timestamp": 1635513688254
    }
    

    GET

    - unsignedRequest:
    
    https://www.sign.cash/api/utxoFilteredByCd?address=FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts&filterCd=-100,100&timestamp=1635513688254&utxoCount=2
    
    - sign = sha256(sha256(https://www.sign.cash/api/utxoFilteredByCd?address=FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts&filterCd=-100,100&timestamp=1635513688254&utxoCount=2&secretKey=d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09))=1111111111111111111111110000000000000000
    
    - signedRequest:
    
    https://www.sign.cash/api/utxoFilteredByCd?address=FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts&filterCd=-100,100&timestamp=1635513688254&utxoCount=2&requester=FEk41Kqjar45fLDriztUDTUkdki7mmcjWK&sign=1111111111111111111111110000000000000000
    

    POST

    - URL:https://www.sign.cash/api/utxoFilteredByCd
    
    - unsignedRequest:
    
    {"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","filterCd":"-100,100","timestamp":"1635513688254","url":"https://www.sign.cash/api/utxoFilteredByCd","utxoCount":2}
    
    - sign = sha256(sha256({"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","filterCd":"-100,100","timestamp":"1635513688254","url":"https://www.sign.cash/api/utxoFilteredByCd","utxoCount":2,"secretKey":"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"}))=1111111111111111111111110000000000000000
    
    - signedRequest:
    
    {"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","filterCd":"-100,100","timestamp":"1635513688254","url":"https://www.sign.cash/api/utxoFilteredByCd","utxoCount":2,"requester":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","sign":"111111111111111000000000"}
    

    响应参数

    name type description
    utxoList object The list of UTXOs returned,see below.
    height uint The latest block height when getting the data.
    • utxoList:
    name type description
    txid string The txid of the trasaction including the utxo.
    index string The index number of the utxo in the transaction.
    amount uint The fch amount of the utxo in unit of satoshi.
    cd uint The coindays of the utxo.
    • 示例
    
    { 
        "utxoList": [
            {"txid":"b70afeba69341ee5c026bff348388c1f8e52a9862cf699f2f65e731890bdf186","index":2, "amount":899876,"cd",198247800},
            {"txid":"b70afeba69341ee5c026bff348388c1f8e52a9862cf699f2f65e731890bdf186","index":0, "amount":100000,"cd":0},
        ],
        "heignt": 963667
    }
    
    排序、压缩、签名后:
    
    {"heignt":963667,"utxoList":[{"amount":899876,"cd":198247800,"index":2,"txid":"b70afeba69341ee5c026bff348388c1f8e52a9862cf699f2f65e731890bdf186"},{"amount":100000,"cd":0,"index":0,"txid":"b70afeba69341ee5c026bff348388c1f8e52a9862cf699f2f65e731890bdf186"}],"sign":"1111111111111110000000002"}
    
    

    返回值

    返回值 类型 必填 说明
    code uint Y 返回码
    msg string Y 返回信息
    data object N 相关数据
    • 返回信息详情:
    code msg 说明 data字段
    0 OK 请求成功
    1 Unknown error. 未知错误 signedRequest
    2000 The address has not been used. 地址从未被使用 address
    2001 There is no UTXO at this address. 该地址没有utxo address
    2004 There is no UTXO that meets the conditions. 没查到符合条件的utxo address, filterCd, filter
    2005 Too many utxos are requested. 请求的utxo太多。 utxoCount, maxUtxoCount
    • 示例
    {
        "code":2004,
        "msg":"There is no UTXO that meets the conditions.",
        "data":{
            "address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
            "filterCd":100,
            "filter":1
        }
    }
    

    4. 交易信息接口

    名称

    txInfo

    说明

    获得某笔交易的详细信息。

    请求参数

    name type description
    txid string 64
    • 示例

    请求交易ID为“d689c16f8eab6cc90a0504c082f1f4c2dd9c404e242139698a41e386942174d3”的交易详情。

    参数

    {
    	"txid": "d689c16f8eab6cc90a0504c082f1f4c2dd9c404e242139698a41e386942174d3",
    	"timestamp": 1635513688254
    }
    
    

    GET

    - unsignedRequest:
    
    https://www.sign.cash/api/txInfo?&timestamp=1635513688254&txid=d689c16f8eab6cc90a0504c082f1f4c2dd9c404e242139698a41e386942174d3
    
    - sign = sha256(sha256(https://www.sign.cash/api/txInfo?&timestamp=1635513688254&txid=d689c16f8eab6cc90a0504c082f1f4c2dd9c404e242139698a41e386942174d3&secretKey=d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09))=111111111111111000000000
    
    - signedRequest:
    
    https://www.sign.cash/api/txInfo?&timestamp=1635513688254&txid=d689c16f8eab6cc90a0504c082f1f4c2dd9c404e242139698a41e386942174d3&requester=FEk41Kqjar45fLDriztUDTUkdki7mmcjWK&sign=111111111111111000000000
    

    POST

    - URL:https://www.sign.cash/api/txInfo
    
    - unsignedRequest:
    
    {"timestamp":1635513688254,"txid":"d689c16f8eab6cc90a0504c082f1f4c2dd9c404e242139698a41e386942174d3","url":"https://www.sign.cash/api/txInfo"}
    
    - sign = sha256(sha256({"timestamp":1635513688254,"txid":"d689c16f8eab6cc90a0504c082f1f4c2dd9c404e242139698a41e386942174d3","url":"https://www.sign.cash/api/txInfo","secretKey":"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"}))=c0ea9382234a11b65738cab9acda3a54729da855b879a237b2c0a5c34249ac40
    
    - signedRequest:
    
    {"timestamp":1635513688254,"txid":"d689c16f8eab6cc90a0504c082f1f4c2dd9c404e242139698a41e386942174d3","url":"https://www.sign.cash/api/txInfo","requester":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","sign":"111111111111111000000000"}
    

    响应参数

    name type description
    txTimestamp The time stamp of this transaction
    fee uint64 Transaction fee in unit of satoshi
    cdDestroyed uint64 The coindays destroyed in this transaction
    opReturn string message in OP_RETURN
    amount uint64 total amount spent
    block uint The height of the block where this transaction was written.
    input object The list of input. See below
    output object The list of output. See below
    height uint The latest block height when getting the data.
    • input
    name type description
    index uint The sequence in the input list,counting from 0.
    address string
    amount uint64 In unit of satoshi
    • output
    name type description
    index uint The sequence in the output list,counting from 0.
    address string
    amount uint64 In unit of satoshi
    • 示例
    {
    	"txTimestamp": 1636180054032,
    	"fee": 2431,
    	"cdDestroyed": 3600,
    	"opReturn": "test",
    	"amout": "210000000",
    	"block": 963220,
    	"input": [{
    			"index": 0,
    			"address": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    			"amount": 10000000
    		},
    		{
    			"index": 1,
    			"address": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    			"amount": 200000000
    		}
    	],
    	"output": [{
    			"index": 0,
    			"address": "FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
    			"amount": 10000000
    		},
    		{
    			"index": 1,
    			"address": "FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
    			"amount": 199997569
    		}
    	],
    	"heignt": 963667
    }
    
    排序、压缩、签名后:
    
    {"amout":"210000000","block":963220,"cdDestroyed":3600,"fee":2431,"heignt":963667,"input":[{"address":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","amount":10000000,"index":0},{"address":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","amount":200000000,"index":1}],"opReturn":"test","output":[{"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","amount":10000000,"index":0},{"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","amount":199997569,"index":1}],"txTimestamp":1636180054032,"sign":"111111111111111000000000"}
    

    返回值

    返回值 类型 必填 说明
    code uint Y 返回码
    msg string Y 返回信息
    data object N 相关数据
    • 返回信息详情:
    code msg 说明 data字段
    0 OK 请求成功
    1 Unknown error. 未知错误 signedRequest
    2006 No such TXID. 没有找到该txid的交易。 txid
    • 示例
    {
        "code":2006,
        "msg":"No such TXID.",
        "data":{
            "txid":"d689c16f8eab6cc90a0504c082f1f4c2dd9c404e242139698a41e386942174d3"
        }
    }
    

    5. 交易列表接口

    名称

    txList

    说明

    按条件获取某个地址的历史交易信息列表。

    请求参数

    name type description required
    address string FCH address Y
    count int How many entries the requester wants at a time. N
    sequence int The sequence of requests N
    filterOpReturn string Filter by opReturn N
    filterCdDestroyed string Filter by cdDestroyed N
    filterChangeUnconfirmed string Filter by changeUnconfirmed, "-0", "0" or "0-". N
    sortTxTimestamp string Sort by txTimestamp N
    sortCdDestroyed string Sort by cdDestroyed N
    sortAmount string Sort by amount N
    • 示例

    按照交易时间从近到远,请求地址FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts的第2批20条(即第21-40条)OP_RETURN非空,且币天销毁大于等于100的交易信息。

    参数

    {
    	"address": "FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
    	"count": "20",
    	"sequence": 2,
    	"filterOpReturn": "not_null",
    	"filterCdDestroyed": "100,100-",
    	"sortTxTimestamp": "down",
    	"timestamp": 1635513688254
    }
    

    GET

    - unsignedRequest:
    
    https://www.sign.cash/api/txList?address=FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts&count=20&filterCdDestroyed=100,100-&filterOpReturn=not_null&sequence=2&sortTxTimestamp=down&timestamp=1635513688254
    
    - sign = sha256(sha256(https://www.sign.cash/api/txList?address=FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts&count=20&filterCdDestroyed=100,100-&filterOpReturn=not_null&sequence=2&sortTxTimestamp=down&timestamp=1635513688254&secretKey=d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09))=1111111111111110000000000000000000000
    
    - signedRequest:
    
    https://www.sign.cash/api/txList?address=FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts&count=20&filterCdDestroyed=100,100-&filterOpReturn=not_null&sequence=2&sortTxTimestamp=down&timestamp=1635513688254&requester=FEk41Kqjar45fLDriztUDTUkdki7mmcjWK&sign=111111111111111000000000000000000000000000
    

    POST

    - URL:https://www.sign.cash/api/txList
    
    - unsignedRequest:
    
    {"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","count":"20","filterCdDestroyed":"100,100-","filterOpReturn":"not_null","sequence":2,"sortTxTimestamp":"down","timestamp":"1635513688254","url":"https://www.sign.cash/api/txList"}
    
    - sign = sha256(sha256({"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","count":"20","filterCdDestroyed":"100,100-","filterOpReturn":"not_null","sequence":2,"sortTxTimestamp":"down","timestamp":"1635513688254","url":"https://www.sign.cash/api/txList","secretKey":"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"}))=1111111111111000000000000000000
    
    - signedRequest:
    
    {"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","count":"20","filterCdDestroyed":"100,100-","filterOpReturn":"not_null","sequence":2,"sortTxTimestamp":"down","timestamp":"1635513688254","url":"https://www.sign.cash/api/txList","requester":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","sign":"1111111111111000000000000000000"}
    

    响应参数

    name type description
    txList object See below
    height uint The latest block height when getting the data.
    • txList
    name type description
    txTimestamp The time stamp of this transaction
    fee uint64 Transaction fee in unit of satoshi
    cdDestroyed uint64 The coindays destroyed in this transaction
    opReturn string message in OP_RETURN
    amount uint64 total amount spent
    block uint The height of the block where this transaction was written.
    input object The list of input. See below
    output object The list of output. See below
    • input
    name type description
    index uint The sequence in the input list,counting from 0.
    address string
    amount uint64 In unit of satoshi
    • output
    name type description
    index uint The sequence in the output list,counting from 0.
    address string
    amount uint64 In unit of satoshi
    • 示例
    {
    	"txList": [{
    			"txTimestamp": 1636180054032,
    			"fee": 2431,
    			"cdDestroyed": 3600,
    			"opReturn": "test in",
    			"amout": "210000000",
    			"block": 963220,
    			"input": [{
    					"index": 0,
    					"address": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    					"amount": 10000000
    				},
    				{
    					"index": 1,
    					"address": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    					"amount": 200000000
    				}
    			],
    			"output": [{
    					"index": 0,
    					"address": "FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
    					"amount": 10000000
    				},
    				{
    					"index": 1,
    					"address": "FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
    					"amount": 199997569
    				}
    			]
    		},
    
    		{
    			"txTimestamp": 1636180054239,
    			"fee": 531,
    			"cdDestroyed": 230,
    			"opReturn": "hi",
    			"amout": "110000000",
    			"block": 963233,
    			"input": [{
    					"index": 0,
    					"address": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    					"amount": 10000000
    				},
    				{
    					"index": 1,
    					"address": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    					"amount": 100000000
    				}
    			],
    			"output": [{
    					"index": 0,
    					"address": "FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
    					"amount": 10000000
    				},
    				{
    					"index": 1,
    					"address": "FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
    					"amount": 99999469
    				}
    			]
    		}
    	],
    	"heignt": 963667
    }
    排序、压缩、签名后:
    
    {"heignt":963667,"txList":[{"amout":"210000000","block":963220,"cdDestroyed":3600,"fee":2431,"input":[{"address":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","amount":10000000,"index":0},{"address":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","amount":200000000,"index":1}],"opReturn":"test in","output":[{"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","amount":10000000,"index":0},{"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","amount":199997569,"index":1}],"txTimestamp":"1636180054032"},{"amout":"110000000","block":963233,"cdDestroyed":230,"fee":531,"input":[{"address":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","amount":10000000,"index":0},{"address":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","amount":100000000,"index":1}],"opReturn":"hi","output":[{"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","amount":10000000,"index":0},{"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","amount":99999469,"index":1}],"txTimestamp":"1636180054239"}],"sign":""111111111111111000000000""}
    
    

    返回值

    返回值 类型 必填 说明
    code uint Y 返回码
    msg string Y 返回信息
    data object N 相关数据
    • 返回信息详情
    code msg 说明 data字段
    0 OK 请求成功
    1 Unknown error. 未知错误 signedRequest
    2000 The address has not been used. 地址从未被使用 address
    2001 There is no UTXO at this address. 该地址没有utxo address
    2007 No more transactions. 没有更多的交易了。 address,count,sequence
    • 示例
    {
        "code":2007,
        "msg":"No more transactions.",
        "data":{
            "address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
            "count":20,
            "sequence":2
        }
    }
    

    6. 未确认交易接口

    名称

    txUnconfirmed

    说明

    获取某个地址的未确认交易列表。

    请求参数

    name type description
    address string 34
    • 示例

    查询FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts的未确认交易列表。

    参数

    {
    	"address": "FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
    	"timestamp": 1635513688254
    }
    

    GET

    - unsignedRequest:
    
    https://www.sign.cash/api/txUnconfirmed?address=FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts&timestamp=1635513688254
    
    - sign = sha256(sha256(https://www.sign.cash/api/txUnconfirmed?address=FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts&timestamp=1635513688254&secretKey=d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09))=1111111111111110000000000000000000000
    
    - signedRequest:
    
    https://www.sign.cash/api/txUnconfirmed?address=FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts&timestamp=1635513688254&requester=FEk41Kqjar45fLDriztUDTUkdki7mmcjWK&sign=1111111111111110000000000000000000000
    

    POST

    - URL:https://www.sign.cash/api/txUnconfirmed
    
    - unsignedRequest:
    
    {"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","timestamp":1635513688254,"url":"https://www.sign.cash/api/txUnconfirmed"}
    
    - sign = sha256(sha256({"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","timestamp":1635513688254,"url":"https://www.sign.cash/api/txUnconfirmed","secretKey":"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"}))=baafb3229491f81ecb48a93b25575aea981c58d074408ae8bf2db592be5c8d6a
    
    - signedRequest:
    
    {"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","timestamp":1635513688254,"url":"https://www.sign.cash/api/txUnconfirmed","requester":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","sign":"111111111111111000000000"}
    

    响应参数

    name type description
    unconfirmedTxList object The list of the unconfirmed transactions. See below
    height uint The latest block height when getting the data.
    • unconfirmedTxList
    name type description
    txTimestamp time stamp
    fee uint64 Transaction fee in unit of satoshi
    opReturn string message in OP_RETURN
    amount uint64 total amount spent
    input object The list of input. See below
    output object The list of output. See below
    • input
    name type description
    index uint The sequence in the input list,counting from 0.
    address string
    amount uint64 In unit of satoshi
    • output
    name type description
    index uint The sequence in the output list,counting from 0.
    address string
    amount uint64 In unit of satoshi
    • 示例
    {
        "unconfirmedTxList":
    [{
    			"txTimestamp": 1636180054032,
    			"fee": 2431,
    			"opReturn": "test in",
    			"amout": "210000000",
    			"input": [{
    					"index": 0,
    					"address": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    					"amount": 10000000
    				},
    				{
    					"index": 1,
    					"address": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    					"amount": 200000000
    				}
    			],
    			"output": [{
    					"index": 0,
    					"address": "FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
    					"amount": 10000000
    				},
    				{
    					"index": 1,
    					"address": "FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
    					"amount": 199997569
    				}
    			]
    		},
    
    		{
    			"txTimestamp": 1636180054239,
    			"fee": 531,
    			"opReturn": "hi",
    			"amout": "110000000",
    			"input": [{
    					"index": 0,
    					"address": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    					"amount": 10000000
    				},
    				{
    					"index": 1,
    					"address": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    					"amount": 100000000
    				}
    			],
    			"output": [{
    					"index": 0,
    					"address": "FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
    					"amount": 10000000
    				},
    				{
    					"index": 1,
    					"address": "FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
    					"amount": 99999469
    				}
    			]
    		}
    	],
        "heignt": 963667
    }
    

    排序、压缩、签名后:

    {"heignt":963667,"unconfirmedTxList":[{"amout":"210000000","fee":2431,"input":[{"address":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","amount":10000000,"index":0},{"address":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","amount":200000000,"index":1}],"opReturn":"test in","output":[{"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","amount":10000000,"index":0},{"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","amount":199997569,"index":1}],"txTimestamp":"1636180054032"},{"amout":"110000000","fee":531,"input":[{"address":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","amount":10000000,"index":0},{"address":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","amount":100000000,"index":1}],"opReturn":"hi","output":[{"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","amount":10000000,"index":0},{"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","amount":99999469,"index":1}],"txTimestamp":"1636180054239"}],"sign":"111111111111111000000000"}
    

    返回值

    返回值 类型 必填 说明
    code uint Y 返回码
    msg string Y 返回信息
    data object N 相关数据
    • 返回信息详情
    code msg 说明 data字段
    0 OK 请求成功
    1 Unknown error. 未知错误 signedRequest
    2000 The address has not been used. 地址从未被使用 address
    2008 The address has no unconfirmed transaction. 该地址没有未确认交易。 address
    • 示例
    {
        "code":2008,
        "msg":"The address has no unconfirmed transaction.",
        "data":{
            "address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
        }
    }
    

    7. 向导接口

    名称

    guide

    说明

    获取某个地址第一笔fch来源交易的第一个输入地址,作为将该地址引入应用的向导。

    请求参数

    name type description
    address string FCH address
    • 返回参数
    name type description
    guide string The first input address of the first transaction in which requesting address get fch for the first time.
    height uint The latest block height when getting the balance
    • 示例

    查询FEk41Kqjar45fLDriztUDTUkdki7mmcjWK的向导,即第一个向其发送fch的地址。

    参数

    {
    	"address": "FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts",
    	"timestamp": 1635513688254
    }
    

    GET

    - unsignedRequest:
    
    https://www.sign.cash/api/guide?address=FEk41Kqjar45fLDriztUDTUkdki7mmcjWK&timestamp=1635513688254
    
    - sign = sha256(sha256(https://www.sign.cash/api/guide?address=FEk41Kqjar45fLDriztUDTUkdki7mmcjWK&timestamp=1635513688254&secretKey=d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09))=3076469fe7036156cabf1e65c8654fe7743eb8cb0b486287665c8e0245631f91
    
    - signedRequest:
    
    https://www.sign.cash/api/guide?address=FEk41Kqjar45fLDriztUDTUkdki7mmcjWK&timestamp=1635513688254&requester=FEk41Kqjar45fLDriztUDTUkdki7mmcjWK&sign=3076469fe7036156cabf1e65c8654fe7743eb8cb0b486287665c8e0245631f91
    

    POST

    - URL:https://www.sign.cash/api/guide
    
    - unsignedRequest:
    
    {"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","timestamp":1635513688254,"url":"https://www.sign.cash/api/guide"}
    
    - sign = sha256(sha256({"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","timestamp":1635513688254,"url":"https://www.sign.cash/api/guide","secretKey":"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"}))=9c2f069edabe125350e8387175f1b48298a35308ed26811303c5433259f72cf1
    
    - signedRequest:
    
    {"address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts","timestamp":1635513688254,"url":"https://www.sign.cash/api/guide","requester":"FEk41Kqjar45fLDriztUDTUkdki7mmcjWK","sign":"111111111111111000000000"}
    
    

    响应参数

    name type description
    guide string The first input address of the first transaction in which the requested address get fch for the first time.
    height uint The latest block height when getting the balance
    • 示例
    {
        "guide": "FPL44YJRwPdd2ipziFvqq6y2tw4VnVvpAv",
        "heignt": 963667
    }
    
    排序、压缩、签名后:
    
    {"guide":"FPL44YJRwPdd2ipziFvqq6y2tw4VnVvpAv","heignt":963667,"sign":"111111111111111000000000"}
    
    

    返回值

    返回值 类型 必填 说明
    code uint Y 返回码
    msg string Y 返回信息
    data object N 相关数据
    • 返回信息详情
    code msg 说明 data字段
    0 OK 请求成功
    1 Unknown error. 未知错误 signedRequest
    2000 The address has not been used. 地址从未被使用 address
    • 示例
    {
        "code":2000,
        "msg":"The address has not been used.",
        "data":{
            "address":"FTqiqAyXHnK7uDTXzMap3acvqADK4ZGzts"
        }
    }
    

Log in to reply