简介
游戏金API文档
连接器
连接器列表
认证和授权
GIP0005 认证和授权
支付协议
GIP0006 支付协议
道具空投协议
GIP0009 游戏道具的空投
道具上链
GIP0001 虚拟物品的发行和交易
游戏商部署指南
部署特约全节点游戏和特约全节点的交互RPC通讯指令列表
小程序多帐号体系
Gamegold 多账户体系整改方案
RPC - 钱包
钱包相关的API
区块链浏览器 - 区块
和区块数据相关的接口
区块链浏览器 - 地址
和地址相关的接口
区块链浏览器 - 交易
和交易相关的接口
区块链浏览器 - 域名
域名查询类接口
区块链浏览器 - 辅助
系统状态查询类接口

游戏金API文档

欢迎来到游戏金公链API文档站！

本站文档采用Markdown格式书写，并通过docbox转化而来 支持 bold, emphasis, strikethrough code 等Markdown格式.

连接器列表

连接器是指协助业务点执行连接公链、发起业务请求并获取应答的流程的辅助类，目前有如下不同类型的连接器

  • 开放式连接器
  • 授权式连接器
  • 控制台连接器

开放式连接器

用于基于浏览器的应用，在未经全节点授权的情况下，访问部分脱敏API 开放式连接器采用 Restful 语法，通过 GET 或 POST 访问API并获得JSON格式的应答 开放式连接器受流量控制影响，每分钟最多100次访问

可以使用 curl 或者 Postman 等工具进行API调用测试。GET API可直接用浏览器调用， POST API可以通过浏览器插件调用

Example request

GET
http://localhost:17332/public/block/height/:height
curl http://localhost:17332/public/block/height/:height
POST
http://localhost:17332/public/block/height/:height
curl -X POST http://localhost:17332/public/block/height/{height}

Example response

{
  "hash": "14f73dfc67b3dc7939de6514b6ce230934a5b42cbeadf44038ed276c6390cdab",
  "confirmations": 3213,
  "strippedsize": 651,
  "size": 687,
  "weight": 2640,
  "height": 100,
  "version": 536870912,
  "versionHex": "20000000",
  "merkleroot": "059729c129799cf09ec07f2cf596149d59a5986251cb1143768f54de5ee30579",
  "coinbase": "0164116d696e65642062792067616d65676f6c6404c2a3b0f5080000000000000000",
  "tx": [
    "059729c129799cf09ec07f2cf596149d59a5986251cb1143768f54de5ee30579"
  ],
  "time": 1532999312,
  "mediantime": 1532996312,
  "bits": 545259519,
  "difficulty": 4.6565423739069247e-10,
  "chainwork": "00000000000000000000000000000000000000000000000000000000000000ca",
  "previousblockhash": "35f512ff035b788976714b2cbc925d990968fe1621fb40c917544dfd1b9bf33c",
  "nextblockhash": "47b85cea3ba29563171cb3d6a0e4f5c24d4e76d84e8fb2d9b4417258ffbb9744"
}

授权式连接器

用于基于浏览器的游戏客户端，或没有集成核心库的游戏服务端，向SPV节点/全节点发起API调用 授权式连接器受流量控制影响，每分钟最多1000次访问 详细案例请查阅 gamegoldmanager 项目中的 remoting 对象封装

Example request

控制台连接器

用于集成了核心库（GameGold Core）的控制台或游戏服务端，向SPV节点/全节点发起API调用 本连接器使用了核心库提供的 accessWallet 类

Example request

GIP0005 认证和授权

GIP0005 定义了玩家如何利用自己的钱包，向游戏传递互信的协议和流程，包括： 1、认证：玩家钱包向游戏签发证书，游戏可以离线验证该证书，并获得玩家的可信信息 2、授权：游戏根据证书信息，将链上资产和游戏内资产进行同步，之后玩家就可以在游戏内支配已确权的资产

token.user

游戏客户端向钱包申领指定用户的登录令牌: 输入游戏编号和玩家编号，输出令牌对象。

Property Description
game_id 游戏编号
user_id 游戏内玩家编号
acct_id 游戏内玩家归属账户

Example request

Example request body

[
  "{game_id}",
  "{user_id}",
  "{acct_id}"
]

Example response

{
  "data": {
    "cid": "{game_id}",         //CP编号，也就是游戏编号
    "uid": "{user_id}",         //玩家编号
    "time": "{timestamp}",      //时间戳
    "addr": "{user_address}",   //玩家绑定的收款地址
    "pubkey": "{user_pubkey}"   //玩家收款地址对应的公钥，验签时使用
  },
  "sig": "{token_sig}"          //数据签名，验签时使用
}

balance.all

查询账户余额。

入口参数

Property Description
acct_id 游戏内玩家归属账户

@note 对微信小程序而言，acct_id一般取值于openid，也就是说，同一个微信用户的不同游戏地址，会归类存储于同一个acct_id下

  • balance.confirmed [$acct_id] 只包括确认交易的余额
  • balance.unconfirmed [$acct_id] 包括未确认交易在内的余额

Example request

Example response

{
  "unconfirmed": 5000,    //单位尘
  "confirmed": 5000       //单位尘
}

衍生指令

0.00005   //单位石
0.00005   //单位石

queryProps

游戏向核心网发送游戏编码、玩家地址，向对等网络查询该玩家持有的道具列表。

  • 开放式连接器 Y - 授权式连接器 Y - 控制台连接器 Y -
Property Description
game_id 游戏编号
user_addr 游戏内玩家的有效地址
POST
http://localhost:17332/public/prop/query/{game_id,

可访问性

Example request

Example request body

[
  "{game_id}",
  "{user_addr}"
]

Example response

[
  {
    "pid": "{道具编号}",
    "cid": "{游戏编号}",
    "oid": "{道具原始编号}",
    "oper": "exchange",
    "prev": {
      "hash": "{转入交易的哈希}",
      "index": "{关联的输出索引}"
    },
    "current": {
      "hash": "{道具所在交易的哈希}",
      "index": "{关联的输出索引}"
    },
    "gold": "{含金量}",
    "confirm": "{确认数}",
    "root": {
      "hash": "{道具首发交易的哈希}",
      "index": "{关联的输出索引}"
    }
  }
]

GIP0006 支付协议

协议说明

Layer: Consensus

Title: Payment Protocol

Status: Draft V0.1

Author：bookman

Type: Standards Track

Created: 2018-06-19

Summary：为游戏玩家提供安全便捷的支付结算通道

业务主体描述

1、玩家 玩家在游戏提供的交互页面上选取商品并生成订单，使用自己的钱包支付订单，在订单在线兑付后确认订单流程完成

2、钱包 玩家从钱包跳转到游戏，在这个跳转过程中，送去了登录令牌，如果通过了验证，就可以顺利登录游戏 玩家登录后，可以浏览到自己已有的道具（登录地址上的所有该游戏的道具） 玩家在游戏商城里点选商品后，将形成一个订单，点击"支付"，跳回钱包 玩家在钱包内签署该订单的支付交易，订单被网络确认后开始广播，玩家的钱包将会收到交易确认消息 玩家可以在钱包中，通过检索相关订单记录，来查看相关订单支付详情 玩家回到游戏中，再次点击"查看订单列表"，可以看到订单状态发生了变化，同时订单也执行了兑付

3、游戏 游戏负责提供商品列表、购物车以帮助玩家生成订单，并提供最终的订单在线兑付功能 开放订单确认回调接口，以接收特约全节点发送的订单状态通告 对已受理订单，定期向特约全节点查询其确认数，当达到预设阀值（例如6个）时触发兑付流程

4、特约全节点 因为特约全节点是游戏自行建立的全节点，所以游戏得以获得充分的授权。 特约全节点为游戏提供订单在线兑付功能（链上道具的制备和转移），注意订单中的普通商品的兑付由游戏自行完成 特约全节点还为游戏提供交易确认通知、订单存档和历史查询等功能 特约全节点可以提供对等网络的一般性功能，也能面向游戏提供特约服务功能

5、对等网络 对等网络为各类合法交易提供中继广播、打包功能。

时序图

    玩家             钱包             游戏          特约全节点           对等网络
      |               |                |                 |                  |  
      |  make order   |                |                 |                  |  
      |———————————————+———————————————>|                 |                  |  
      |               |   send order   |                 |                  |
      |               |<———————————————|                 |                  |
      |               |   pay  order   |                 |                  |
      |               |————————————————+—————————————————+—————————————————>|
      |               |                |                 |   confirm tx     |
      |               |                |                 |<—————————————————|
      |               |                |  confirm order  |                  |
      |               |                |<————————————————|                  |
      |               |                | implement order |                  |
      |               |                |————————————————>|                  |
      |               |                |                 |   send prop      |
      |               |                |                 |—————————————————>|
      |               |                |                 |   confirm tx     |
      |               |                |                 |<—————————————————|
      |               |                | confirm prop    |                  |
      |               |                |<————————————————|                  |
      |               |  provide prop  |                 |                  |  
      |<——————————————+————————————————|                 |                  |  
      |               |                |   query order   |                  |
      |               |                |<———————————————>|                  |
      |               |                |                 |                  |  
      |               |                |                 |                  |
  • √ make order ：玩家在商城选购商品形成订单
  • √ send order ：游戏将订单转发给钱包
  • √ pay order ：钱包收到游戏转入的订单（或玩家手动输入的订单），签发订单支付交易并广播至对等网络
  • √ confirm tx ：特约全节点收到对等网络交易确认通知 池传导通知：调用游戏的订单确认回调接口，通告订单已收到 链传导通知： 1、将交易信息记录到 layout.o 条目下 2、调用游戏的订单确认回调接口，通告订单已确认，附加确认次数
  • √ confirm order ：特约全节点通知游戏订单已确认
  • √ implement order ：游戏收到订单确认回调请求，分情况刷新订单状态，例如"已收到，处理中。。。"、"已确认，确认数N"等等 1、如果是内部商品，直接兑付 2、如果是上链商品，必须向特约全节点申请订单兑付，以完成道具制备（ prop.send ）和转移（ prop.send ）等操作
  • √ send prop ：特约全节点接受了游戏的订单兑付请求，签发道具制备转移交易并广播至对等网络
  • √ confirm tx ：特约全节点收到对等网络交易确认通知
  • √ confirm prop ：特约全节点通知游戏道具已确认
  • √ provide prop ：游戏向玩家核发道具（去重处理）
  • √ query order ：游戏向特约全节点核查待处理订单实时状态：指定游戏编号、订单流水号集合，查询对应订单详情

订单状态图

        _____支付_____确认________履行____
      |           ↓         ↓           ↓
    订单生成      已支付     已确认      已履行       已过期
      |           ↓         ↓           ↓           ↑
      |       进入内存池    上链     兑付订单内容     |
      |_____________________________________________|

认证和通讯安全

  • 游戏APP和服务端通讯安全自行负责
  • 玩家钱包和对等网络间依托现有的P2P通讯方式
  • 玩家钱包登录游戏APP：送去登录令牌，令牌中包含用户私钥签署过的数据
  • 游戏服务端访问对等网络：对于脱敏操作，可以直接明文通讯，如果出于对DDOS的担心，可以考虑一些流量控制方案
  • 游戏服务端和特约全节点（远程钱包）之间采用 HMAC 签名算法，确保两者相互认证和通讯数据不可篡改 一、游戏服务端访问特约全节点（远程钱包） 1、远程钱包必须为游戏服务端分配令牌编号和令牌固定量，可以通过本地制备指令 token.auth 屏显制备内容 2、每个游戏服务端配置被分配的令牌编号和令牌固定量，并以离线手动更新方式，和远程钱包的配置保持一致 3、游戏服务端使用远程钱包RPC接口前，必须先发起命令获取自己的令牌随机量，来实现该随机量在服务端/远程钱包两端的同步 4、游戏服务端将获取的令牌随机量、本地令牌固定量合成为访问令牌，将令牌编号、访问令牌附着在业务指令中一起上传 5、远程钱包收到上传的令牌编号、访问令牌，和本地HMAC计算结果比对，一致则允许执行业务指令，否则拒绝 6、对于WebSocket模式，可以在连接认证时缓存认证结果，连接期间无需再次上传访问令牌 二、特约全节点访问游戏服务端 1、特约全节点在访问游戏服务端接口时，在参数上附加相应的令牌编号、令牌随机量，以及据此计算的访问令牌 2、游戏服务端通过本地的令牌固定量、接口上收到的令牌随机量以及参与计算的数据（事先约定）计算访问令牌，和收到的访问令牌比对，实现认证
  • 全节点RPC接口。全节点RPC接口上实现的操作指令分为三类： 1、任何连接者都可以执行的指令 2、本地连接才可以执行的指令 3、限定执行指令，例如限定钱包、限定来访者令牌等

  • 线上版本使用HTTPS协议替换所有HTTP协议

    • 可靠的证书生成工具例如 Openssl
    • ssl开启设定全局统一

order.pay

钱包接收订单、签发支付交易并广播至对等网络。 @note 采用 OP_RETURN 将订单流水和支付交易捆绑在一起，用以作为兑付凭证 @note 游戏APP可以采用 URL Schema / 二维码图像等方式，将订单内容 [{game_id} {user_id} {order_sn} {order_sum}] 传递给钱包。

  • 开放式连接器 N - 授权式连接器 Y - 控制台连接器 Y -
Property Description
game_id 游戏编号
user_id 玩家编号
order_sn 订单编号
order_sum 订单金额
account 指定结算的钱包账户，一般为微信用户的openid

可访问性

Example request

Example request body

[
  "{game_id}",
  "{user_id}",
  "{order_sn}",
  "{order_sum}",
  "{account}"
]

Example Response

order.query

查询订单支付状态。一般从游戏服务端发起请求。

  • 开放式连接器 N - 授权式连接器 Y - 控制台连接器 Y -
Property Description
game_id 游戏编号
order_group 订单流水号数组

可访问性

Example request

Example request body

[
  "{game_id}",
  "{order_group}"
]

Example response

[
  {
    "oper": "pay",
    "cid": "{游戏编号}",
    "uid": "{玩家编号}",
    "sn": "{订单号}"
  }
]

prop.order

游戏服务端制备并送出道具。

  • 开放式连接器 N - 授权式连接器 Y - 控制台连接器 Y -
Property Description
game_id 游戏编号
prop_ori_id 道具原始
prop_value 道具含金量
user_addr 游戏内玩家的有效地址

可访问性

Example request

Example request body

[
  "{game_id}",
  "{prop_ori_id}",
  "{prop_value}",
  "{user_addr}"
]

Example response

{
  "hash": "{当前道具所在交易哈希}",
  "cid": "{游戏编码}",
  "pid": "{道具编码}",
  "oid": "{道具原始编码}",
  "gold": "{道具含金量}",
  "addr": "{目标地址}",
}

GIP0009 游戏道具的空投

Layer: Consensus

Title: Bonus for Potential Game Player

Status: Draft

Author：bookman

Type: Standards Track

Created: 2018-08-15

Summary：向潜在游戏玩家分发游戏道具的解决方案

游戏道具空投流程

1、游戏厂商批量生成若干道具 2、游戏厂商查询潜在游戏玩家，向其地址投放道具 3、游戏玩家根据地址中包含的游戏信息，申领游戏专用地址 4、钱包系统将先前收到的道具转入该专用地址，以便在游戏中顺利确权 5、玩家登录游戏，使用先前获取的道具

@note 关于游戏地址 钱包按照 游戏ID + 玩家游戏内ID 的组合，为玩家分配游戏专用地址。玩家在游戏中获取的道具将会发往该地址。 空投道具的行为一般发生于玩家进入游戏前，因此游戏只能将其投放至玩家玩过的其它游戏的专用地址。 这些错位的道具无法在该专用地址对应的游戏中确权，因此当玩家真正进入目标游戏时，钱包必须主动提示用户进行道具的迁移。 当迁移完成后，用户再次登录目标游戏时，就可以对这些道具进行确权，从而在游戏中合法使用它们。

GIP0001 虚拟物品的发行和交易

Layer: Consensus

Title: Virtual Props' Publish and Trade

Status: Draft V0.1

Author：bookman

Type: Standards Track

Created: 2018-04-24

Summary：提出了涵盖虚拟物品的发行、转移、竞价销售、熔铸功能的完整解决方案，将于主链发布之日默认激活。

概述

1、CP Register：生产者注册信息 2、CP Change：生产者修改信息/转移注册信息所有权 3、VP Create：生产者发行虚拟物品，VP被制造出来，处于Produce状态，可以进入Exchange状态，也可以进入Found状态 4、VP Exchange：VP在生产者和用户、用户和用户间转移，可以在Exchange状态上自循环，也可以进入Sale或Found状态 5、VP Sale：VP被出售，进入Sale状态（竞价环节），可以自循环（通过Buy操作多轮竞价）。无论成功与否，最终都将回到Exchange状态 6、VP Found：VP被熔铸为Coin，进入零钱包，这是终极状态，VP除币值外的所有属性被不可逆转的抹除

虚拟物品状态机如下所示：

_________________________________

/ | / ↓ Produce --> Exchange --> Sale Found ↑ | | ↑ ↑ || ↑ | | | | |_|| | || | |__| | |__|

cp.list

查询系统中现有的所有CP列表：cp.list

  • 开放式连接器 N - 授权式连接器 Y - 控制台连接器 Y -
Property Description
cid CP唯一编号，由系统内部分配
name CP的名称，由注册者设定，全局唯一
url CP的URL地址
ip CP的IP地址，可以为空
current.hash 注册信息所在交易的哈希
current.index 注册信息在交易中的序列号
current.address 注册信息关联的地址
owned 是否归属于当前钱包（仅对钱包客户端有效）
status 保留字段

可访问性

Example Request

Example Response

[
  {
    "cid": "237da570-b725-11e8-a7ca-3f8b903ba033",
    "name": "hello",
    "url": "127.0.0.1",
    "ip": "",
    "current": {
      "hash": "bd3a3656b94fd9d61ca7a3721c385e29e4b12176b9efa8fe0702ee5b95ff25c4",
      "index": 0,
      "address": "tb1qr790zz32jyyje8letxkavdv93qf7dmp0wjx3s0"
    },
    "owned": true,
    "status": 1
  }
]

token.auth

终端令牌制备指令： token.auth cpids @note： cpids 为逗分字符串，可携带一条或多条CPID信息

  • 开放式连接器 N - 授权式连接器 Y - 控制台连接器 Y -

null

@note 控制台屏显内容： 1111: 038253ce66d5615a6efe9f262c2e96a305f9fab5e9ebb39688c55919b784fb8f88 2222: 024cc9367ef61ab6f5842f50c50717434255a6427e2a3e3486f39000f8d4fce2ac 3333: 03e434d1b87c191d31535a82adfb33c81fb2d1a56a3a5f9182673e92631382698b

可访问性

Example Request

Example Response

cp.create

CP注册指令：cp.create "name" "url" ["ip"]

@note: 注册成功后，生产者由系统生成的全局唯一编码 cid 所标识，称为CP编码 name 由汉字、大小写字母、数字、下划线和点组成的标识字符串，长度4~20，必须是全局唯一的，不可重复 ip是可选项，但是结合ip注册，可以得到类似域名寻址的效果，或者说，可以作为 .gamegold 的DNS替代服务使用 共识变量 registerFee 决定了注册费用，这笔费用被系统冻结无人可以花费 *该指令一般在主节点管理后台/控制台执行

  • 开放式连接器 N - 授权式连接器 Y - 控制台连接器 Y -

入口参数

Property Description
name CP名称
url CP的URL地址
[ip] CP的IP地址

可访问性

Example Request

Example Response

{
  "name": "testfellow3",                                                     //CP名称
  "url": "http://920.cc",                                                    //URL地址
  "ip": "",                                                                  //IP地址       
  "cid": "0a021c00-bb23-11e8-8848-233ceb544c5d",                             //CP编码
  "oper": "cpRegister",                                                      //操作类型
  "txid": "412408ea931b6b8942c8fd865c1a6da46899b0ef30522884ba0b05d5b704dcdc" //CP记录所在交易的哈希，小端格式
}

cp.change

CP修改/转让指令： cp.change "name" ["url" "ip" "addr"]

@note: 可以只修改名称，但修改后的名称必须全局唯一，而被修改掉的名字将可以被他人再次利用 如果输入了 addr ，则表示向该地址转让注册信息 修改、转让没有额外的手续费用 *该指令一般在主节点管理后台/控制台执行，而非在钱包上执行

入口参数

Property Description
name CP名称
newname CP的新名称，如不想改名称则复制原名称
[url] CP的URL地址，可以填写空串，如忽略则后续不可再有参数
[ip] CP的IP地址，可以填写空串，如忽略则后续不可再有参数
[addr] 新的接收地址，！！！若填充此字段，相当于转让CP所有权

Example Request

Example Response

{
  "name": "test1",                                                            //CP原有名称
  "newName": "test2",                                                         //CP新的名称
  "url": "http://gamegold.xin",                                               //CP最新的URL
  "ip": "",                                                                   //CP最新的IP
  "addr": "tb1qf0md5h9erhqwfwcrshdhkfpg93h0hz2jwk6rwm",                       //CP最新的地址
  "cid": "9c998be0-bb26-11e8-948a-33c872827589",                              //CP编码
  "oper": "cpChange",                                                         //操作类型
  "txid": "92b1ec0a161f2554d0404cce7a10f70050616e304758e3de0338a10b2f172e41"  //CP记录所在交易的哈希，小端格式
}

cp.ById

根据ID查询CP注册信息

入口参数

Property Description
cid CP编码

Example Request

Example Response

{
  "cid": "xxxxxxxx-vallnet-boss-xxxxxxxxxxxxxx",
  "name": "BOSS",
  "url": "920.cc",
  "ip": "*"
}

cp.ByName

根据名称查询CP注册信息

入口参数

Property Description
name CP名称

Example Response

{
  "cid": "xxxxxxxx-vallnet-boss-xxxxxxxxxxxxxx",
  "name": "BOSS",
  "url": "920.cc",
  "ip": "*",
  "current": {
    "hash": "f1573c53d45441e7d38b1e06ff3687bc26f716b0af06bc6cd219fb3768406087",
    "index": 0,
    "address": "tb1qpmzc83qca4snn62ee0eul8rqtzrp5a5q0f96rs"
  },
  "owned": true,
  "status": 1
}

prop.create

虚拟道具注册指令

入口参数

Property Description
cid 发行道具的CP编码
oid 发行道具的原始编码
gold 道具包含的虚拟币值，单位是尘

@note 注册时需要提供两个参数， cid 必须是有效的生产者编码， gold 表示该道具的含金量 注册完毕后，还必须等待至少一个确认，才能正式发行成功 进入道具序列的硬币，会从钱包硬币列表中消失，不可用于转账业务操作中 *该指令一般在主节点管理后台/控制台执行，而非在钱包上执行

@note 现行游戏金的单位包括：

  • d：尘(dust)，游戏金的最小计量单位
  • g：氪(gram)，相当于1000尘
  • K：金(kg)，相当于1000氪
  • S：石(stone)，相当于100金

输入参数中，统一使用尘作为单位 输出参数中，视情况使用尘或者石 UI中，视情况使用尘、氪、金、石

Property Description
oper 操作类型码
cid CP编码
oid 道具原始编码
gold 道具包含的虚拟币值，单位是尘
pid 道具编码
index 交易内索引
hash 所在交易的哈希，大端格式
txid 所在交易的哈希，小端格式

Example Request

Example Response

{
  "oper": "new",
  "cid": "b77a9b90-bbc4-11e8-9203-1ff8357db148",
  "oid": "gamemonkey0003",
  "gold": 10000,
  "pid": "15e1a160-bbc5-11e8-9203-1ff8357db148",
  "index": 0,
  "txid": "d88d0e9ed243fb767643ea1dea754af9aab53e3eab274c4c1f95067efc15135b"
}

prop.createlist

VP批量制备指令： prop.createlist "cid|oid|gold,cid|oid|gold"

prop.create 返回数据的数组形式

Example Request

Example Response

prop.send

VP转移指令： prop.send addr txid [index]

通过 prop.create 发行的VP，必须通过 prop.send 发送到某个有效地址上，之后才能成为一个全流通道具，参与拍卖、熔铸等操作

@note 输入转移的目标地址，道具所在交易的哈希、输出索引值（可选，默认0），即可将道具转移给目标地址 转移没有额外的手续费 输入参数中，标记为 hash 的，按照大端格式解释，标记为 rhash 或 txid 的，按照小端格式解释

入口参数

Property Description
addr 发送道具的目标地址
txid 道具所在的交易的哈希，小端格式
index 道具在交易输出中的索引值，默认0

Example Request

Example Response

prop.sendlist

VP批量转移指令： prop.sendList "addr|txid|index,addr|txid|index"

prop.send 数据的数组形式

Example Request

Example Response

prop.order

订购：制备道具并发放给指定地址，相当于同时执行了 prop.creae 和 prop.send

入口参数

Property Description
cid 生产者编码
oid 道具原始编码
gold 道具含金量 单位：尘
addr 目标地址

prop.found

VP 熔铸指令： prop.found hash @note 指定将要熔铸的道具所在的交易的哈希，执行指令后将永久抹除所有的道具属性，重新变为一枚普通的硬币 不需要指定地址，熔铸后形成的硬币自动回到当前钱包的可用地址上

入口参数

Property Description
txid 生产者编码
Property Description
txid 交易哈希，小端
index 交易输出索引
cid 生产者编码
pid 道具编码
oid 道具原始编码
gold 道具含金量 单位：尘

Example Request

Example Response

{
  "txid": "120fe53b49f6db9d8160588774b63974413b881f0a27f0c7dbb2dea490f4babd",
  "index": 0,
  "cid": "b77a9b90-bbc4-11e8-9203-1ff8357db148",
  "pid": "9e236880-bbdc-11e8-8f5c-0bef66529c12",
  "oid": "gamemonkey0003",
  "gold": 10000
}

prop.sale

VP 拍卖指令： prop.sale txid fixedPrice @note 指定将要拍卖的道具所在的交易的哈希，并给出拍卖一口价，将生成一个拍卖交易 进入拍卖序列的道具，会从钱包道具列表中消失，不可用于转移、熔铸等业务操作中

Example Request

Example Response

prop.buy

VP 竞拍指令： prop.buy pid price @note 指定要参与竞拍的道具的 pid ，以及自己的出价，就可以参与竞拍 如果出价高于该拍卖交易的初始价格（自身含金量）以及所有历史报价，那么将形成一个新的拍卖交易，替代之前的拍卖交易 如果出价高于该拍卖交易的一口价，那么将形成一个新的、已锁定的拍卖交易，替代之前的拍卖交易 拍卖交易的有效期截止，或者提前进入锁定状态，就会被打包到区块中，打包结束后道具发生了转移，并进入买家钱包的道具列表中，而卖家将得到一笔拍卖金 如果流拍，交易取消，道具回到原主人手中

Example Request

Example Response

address.list

查询指定账户下的有效地址。一般用来查询特定openid的微信用户名下的有效地址

[receive list, change list, nested list]

Example Request

Example Response

[
  [
    "tb1qpcu7kpx6an8nycc9qzews4fwt3xm89xm8nkmyh",
    "tb1qrx3g2p4fvtp6dgearxlaveecyreclf2yrwvet2",
    "tb1qywwa32jk65kar6nz9adkdzzs63vc89k26ngjtp",
    "tb1q9fryja72mcma9cxjmm0vq5mfrg5ugq3kk3vauc",
    "tb1q8zqszrane28827msa080al8jj0zq2r6376fg20",
    "tb1qfgjqx8dmlnnqj6kc3vselqgl9kkryegc2ym4gc",
    "tb1q2vdpp7g34hr93cjpy24fkrrdds2wk5a38m8aa7",
    "tb1qth346ed5g76xupars0t4m72cs2lfh60mkrjp9f",
    "tb1qsm9zlyqvv47tasl0mn9h0krhl5hcfv7uz5jal5",
    "tb1q5njps8h97s8d09ypcuwvs4m57jsenmsactugxm",
  ],
  [
    "tb1qqsj8dru4r46u29nhgnrgc0wn64d7py9rg8fkc2",
    "tb1qr24jr3excssn7nydrghzeca0zluj703ca79akk",
    "tb1qvmadcnkutxwahq40m6uatxnqlgk482r0t7es9y",
    "tb1qdcgcuv82rsl4epy0szkwfwpkhms59ad84333t9",
    "tb1qw7wefk0ypfuu450qa80nxzumy48alltq426r0x",
    "tb1qs84umpmrrxezpkhpv9qw7kz4pqft8r654x6xt2",
    "tb1q3ed9wenehayl30rzyc60s7nszr9y24nrw62g89",
    "tb1qhdghp7w8zezhcvljsyyslrp5hgnue4w4kuffk3",
    "tb1qcvrnh6jcumzv8rrq86w6g4lfrhqpmsaafh3ly6",
    "tb1qeq4yysu6h8x0kgafn3lxc8tde57s0ry0yleaay",
  ],
  [
    "2N3cshjtvJUbQwr6boyTTEEtWJwZM187QSR",
    "2N5twuF5CGhrnMaYB3FAM7p2Y7epmETeBTJ",
    "2N6KeGtPxpZFDTqZ7d4E5mHbgrsSEdBXfnG",
    "2N7eUi5kv2JKkF4uyg6avnUQEwBgCB2vsLo",
    "2N8SPL5pa2n6LD5VwNXm9b4RQ5dCncn7VGn",
    "2N8dTqZbwdkRVfNjVPF8qRJBPYHhyEayNux",
    "2N9AxCDcvMRckjHTxDUTSfajaQYZxP2m1dK",
    "2NAg85xswqn5vwgooitw4mAuLrUvKubrsM9",
    "2NCKSKpqSmkXD3LRrqJtxhKSBKN9digxBFE",
    "2NG8Fvtvu4g6z7mPwx1EpD2tF3pffX9MgtD",
  ]
]

prop.list

查询当前拥有的道具列表 @note prop.list 侧重于查询不同微信用户的道具列表，不区分游戏，而 queryProps 则侧重于查询用户指定的游戏专用地址中的道具列表

入口参数

Property Description
page 页码，默认1
acct 指定的钱包账户，一般为指定用户的openid

Example Request

prop.list.created

列表自己创建的道具

入口参数

Property Description
acct 指定的钱包账户，一般为指定用户的openid

Example Request

prop.list.auction

列表自己正在拍卖的道具

入口参数

Property Description
acct 指定的钱包账户，一般为指定用户的openid

Example Request

prop.list.bid

列表自己参与拍卖的道具

入口参数

Property Description
acct 指定的钱包账户，一般为指定用户的openid

Example Request

部署特约全节点

1、建立运行环境 在安装了 node 8.0 及以上版本的基础上，运行如下指令：

2、开启一个控制台窗口A，通过下述指令启动全节点，等待其同步数据完成

3、新开一个控制台窗口B，运行如下命令查询CP列表，记录自己名下CP（owned字段为true）的CPID字段：

如果自己尚未拥有CP记录，可以运行如下命令进行注册：

其中： name是CP名称，全局唯一，不可重复，名称只能含有汉字、数字、字母、下划线和点，不能以下划线和点开头和结尾，长度限制为4~40

url是CP的回调服务地址，用于对外公开相关服务接口
ip是备用IP地址，支持IPV4和IPV6两种格式，在url无效的情况下，可直接使用ip进行访问。

注册成功后，再次运行 cp.list 指令进行确认

4、在窗口A键入 Ctrl-C 关闭全节点

5、配置 gamegold.conf 文件

  • 采用包含全部CPID的逗分字符串，配置 hmac-connection 字段
  • 配置 api-key 字段

@note gamegold.conf 位于 .gamegold\$networktype\ 目录下，对测试网而言 $networktype = testnet ， 对主网而言 $networktype = main

6、在A窗口通过如下指令再次启动全节点

7、在B窗口运行 token.auth [CPID逗分列表]，A窗口会屏显授权令牌，记录并离线分发给各CP

游戏和特约全节点的交互

注：详情请参考 GIP0005 - 认证和授权，以及 GIP0006 - 支付协议

1、CP通过远程连接器，和特约全节点开展RPC通讯。CP需要将获取的授权令牌配置于它的远程连接器中，以控制台连接器为例：

@note 当前版本下，所有授权节点都将共享整个钱包系统。未来版本中，将为不同CP划分独立钱包，以实现安全隔离

2、特约全节点在特定事件（如支付确认等）发生时，会通过CP注册信息中的URL地址，向CP提交事件通知, 如下所示：

RPC通讯指令列表

客户端认证登录流程

主要涉及指令： token.user game_id user_id open_id

1、页游

泛指运行于浏览器内的页面游戏，包括Flash游戏、HTML5游戏，运行环境包括PC、手机等

  • 页游客户端将随机用户码和CP编码，打包并生成二维码并显示在屏幕上
  • 钱包APP扫码后，在本地执行 token.user 指令，将生成的令牌以GET方式送入游戏服务器
  • 微信小程序扫码后，将信息送至小程序服务端，在服务端执行 token.user 指令，再将生成的令牌以GET方式送入游戏服务器 两者的区别是： 钱包APP用HD钱包技术，本地生成并管理所有的地址。 微信小程序则在服务端采用HD钱包技术，远程管理所有的地址，用户相关地址记录于和他的openid同名的账户下。 两者的共性是： 都使用 cid+uid，通过HD钱包技术推导出专用地址，cid和uid含义、推导出的地址都是一样的
  • 游戏服务端接收 token ：

2、手游APP

运行于IOS、Android系统上的游戏类独立APP

  • 手游APP通过 URL Schema 技术，向钱包APP或者微信小程序送入cid+uid
  • 钱包APP生成token，同样以 URL Schema 将 token 送入手游APP，也可以先送入游戏服务端再下发给手游APP
  • 微信小程序通知小程序服务端，生成token送入游戏服务端
  • 游戏服务端接收 token 的流程同上
  • 游戏服务端将token下发给手游APP，手游APP允许用户登录

3、微信小游戏/内嵌式微信小游戏

运行于微信小程序环境内的游戏类小程序。内嵌式指使用WebViewer模式嵌入微信小程序中运行的游戏

  • 微信小游戏通过小程序跳转相关技术，向微信小程序钱包送入cid+uid
  • 微信小程序钱包通知小程序服务端，生成token送入游戏服务端再下发给微信小游戏
  • 游戏服务端接收 token 的流程同上
  • 游戏服务端将token下发给微信小游戏，允许用户登录

4、从钱包发起的登录认证流程 a、在钱包界面，点击游戏列表 b、点击具体游戏后面的"登录"按钮，此时钱包为该游戏生成登录token，并试图跳转到游戏客户端（APP或微信小程序） c、游戏客户端向服务端请求登录：GET /auth/:tokan d、游戏服务端捕获该路由，核实该token的有效性，执行道具确权，接着设置登录状态并通知游戏客户端 e、游戏客户端允许用户登录，使用经确权后的道具

{
    "cid": "game001",
    "uid": "user001"
}

确权流程

主要涉及指令： queryProps game_id：CP编码 user_addr：游戏用户对应该游戏的钱包地址

该指令由游戏服务端向全节点发起，用于道具确权 模拟输入：

入口参数

Property Description
game_id CP编码
user_addr 钱包地址

模拟输出：

游戏服务端收到应答后，需要做双向确权： 1、玩家背包中没有、应答中有的道具，需要发放给玩家 2、玩家背包中有、应答中没有到道具，需要从背包中扣除 @note 文中提及到道具，都是指上链道具。游戏内普通道具不受该规则影响。 目前不支持堆叠式道具，简单说每条记录不携带数量字段，都被看作是一件独立的道具

[
  {
    "pid": "{道具编号}",
    "cid": "{游戏编号}",
    "oid": "{道具原始编号}",
    "oper": "exchange",
    "prev": {
      "hash": "{转入交易的哈希}",
      "index": "{关联的输出索引}"
    },
    "current": {
      "hash": "{道具所在交易的哈希}",
      "index": "{关联的输出索引}"
    },
    "gold": "{含金量}",
    "confirm": "{确认数}",
    "root": {
      "hash": "{道具首发交易的哈希}",
      "index": "{关联的输出索引}"
    }
  }
]

订单支付

主要涉及指令：order.pay

1、用户在游戏客户端上点击"商品列表" 2、点选商品后，游戏客户端向游戏服务端发送一个请求，服务端为用户生成一笔订单，缓存在服务端 3、游戏客户端使用跳转指令，将订单送入钱包，每笔订单包括字段：游戏编号、玩家编号、原始订单号、金额 4、钱包APP执行订单支付指令：

connector.execute({method:'order.pay', params:[cid, uid, sn, price, openid]}).then(tx => {
    console.log('order.pay: ', tx);
});

5、钱包成功支付后，向全网广播交易；当游戏特约全节点收到该交易，将调用游戏服务端的订单确认回调接口 6、游戏服务端收到回调请求，将订单设置为"已确认"，处理道具发放流程，并推送给游戏客户端

7、游戏客户端将订单订单状态改为已支付，延后更新用户背包信息

订单查询

主要涉及指令：order.query

订单查询指令一般从服务端发起，用于查询一段时间后未收到回调确认的订单的真实状态

模拟输入：

入口参数

Property Description
game_id CP编码
order_group 订单编号数组，可一次性查询多条订单的状态

模拟输出：

confirm为0表示尚未确认，大于0表示已确认，达到商家设定的最小确认数时，即可向玩家制备并发放道具

[
  {
    "oper"    : "pay",
    "cid"     : "{游戏编号}",
    "uid"     : "{玩家编号}",
    "sn"      : "{订单号}",
    "confirm" : "{确认数}"
  }
]

制备并发放道具

主要涉及指令： prop.order 等同于 prop.create 和 prop.send 命令的组合，用于订单确认后，向用户快速制备发放指定的道具

入口参数

Property Description
cid CP编码
oid 道具原始编号
gold 道具含金量
addr 玩家接收道具的地址

提供道具查询接口

游戏服务端以约定的格式，对外提供道具信息查询接口

如下为道具图片查询接口范例：

Gamegold 多账户体系整改方案

为了向用户屏蔽不必要的技术细节，以降低使用门槛，微信小程序并不在本地管理钱包，而是将关键操作全部委托到远方的微信小程序服务器。 微信小程序服务器管理着一个超级钱包，其中包含了海量的账户，每个账户由个人用户的OPENID所标识，区隔开了用户的私钥、地址、道具等信息。 从某种角度来看，微信小程序服务器是一个特殊的全节点，与其目的性相对应，有一系列的函数需要完成这种相关性改造，以便该特殊节点可以携带额外的OPENID参数访问这些函数，从而营造出一个多账户系统。 与此同时，忽略这个参数的系列调用，其运作机制又回到了一个单账户体系。

需要注意的是，同样的机制可能会被用在一个游戏特约全节点需要管理不同的游戏的场景中。 在这个场景中，每一台游戏服务器都会被分配一个终端编码（等比于微信小程序用户的OPENID），从而被特约全节点映射到一个单独的账户上。

以下为参与整改的函数清单

查询钱包余额

Property Description
account 子账户名称

创建虚拟道具

Property Description
cid 游戏编码
oid 道具原生编码
gold 道具含金量
openid 子账号名称

转移虚拟道具

Property Description
addr 转移的目标地址
hash 交易哈希
index 交易输出索引
openid 子账户名称

创建用户通行证

Property Description
cid 游戏编码
uid 用户游戏内编码
openid 子账号名称

捐赠道具

收取捐赠

Property Description
raw 原始交易数据，HEX格式
openid 子账号名称

拍卖道具

Property Description
hash 道具所在交易哈希
index 输出索引。在批量转移道具的交易中，需要输出索引以指明目标道具；如果遇到拍卖交易(目前只支持单件道具拍卖)，系统将锁定 index=2 ：该交易在 index=2 的输出上携带有效载荷
fixed 一口价
openid 子账号名称

竞拍道具

Property Description
pid 道具编号
bid 竞拍价
openid 子账号名称

查询道具列表

Property Description
pageNum 道具列表的页码，从1开始
openid 子账号名称

钱包相关的API

address.create

Alias: address.receive.create

创建一个收款地址

Property Description
network 网络类型
id 钱包ID
type 支持隔离见证
address 新生成的 Bech32 格式的地址

Example Request

Example Response

{
  "network": "testnet",
  "wid": 1,
  "id": "primary",
  "name": "default",
  "account": 0,
  "branch": 0,
  "index": 2,
  "witness": true,
  "nested": false,
  "publicKey": "02c4af60a945212735abd7627c6fd96768c15389b82594447ae239f170afd38c0a",
  "script": null,
  "program": "0014ad6bdd1dd64aa3d8d8a90575518df742b06168c6",
  "type": "witness",
  "address": "tb1q444a68wkf23a3k9fq464rr0hg2cxz6xx3xxs4n"
}

tx.send

根据输入的金额和地址，创建、签署、发送一笔P2PKH类转账交易

入口参数

Property Description
addr 转账的目标地址
value 转账的金额，单位尘

Example Request

Example Response

{
  "wid": 1,
  "id": "primary",
  "hash": "589e81ebd2cde651f5d562363f5c414acc0527ea48a28a1735aa26d919304a64",
  "height": -1,
  "block": null,
  "time": 0,
  "mtime": 1537668448,
  "date": "2018-09-23T02:07:28Z",
  "size": 222,
  "virtualSize": 141,
  "fee": 2800,
  "rate": 19858,
  "confirmations": 0,
  "inputs": [
    {
      "value": 5000000000,
      "address": "tb1qdrdct4dlhh6wdulddy96h9lxgs9fekaffhyxz5",
      "path": {
        "name": "default",
        "account": 0,
        "change": false,
        "derivation": "m/0'/0/0"
      }
    }
  ],
  "outputs": [
    {
      "value": 10000,
      "address": "tb1q9msqyf7nee72gk4qw2elawa5m7kgj6u8squmjw",
      "path": {
        "name": "default",
        "account": 0,
        "change": false,
        "derivation": "m/0'/0/13"
      }
    },
    {
      "value": 4999987200,
      "address": "tb1q5ggklpp0d89mtgtk9ddn27c02wd3dxha3a37ae",
      "path": {
        "name": "default",
        "account": 0,
        "change": true,
        "derivation": "m/0'/1/1"
      }
    }
  ],
  "tx": "0100000000010160f0055f9ad850ce85956ba8755d2e7a8f918207b62e2135fd3074bc6d46c3c00000000000ffffffff0210270000000000001600142ee00227d3ce7ca45aa072b3febbb4dfac896b8700c0052a01000000160014a2116f842f69cbb5a1762b5b357b0f539b169afd02473044022075e9d8f6bacbac95ab2aabe4d0f4c9db298fe4b0e9d6427f8d25fc06b2bd8b3f02205f57035af471d8b63e5cd3cf15987f56ed43b01fe64fbeb08a0c0ce176bd3a57012102091058a8f75f971f6dbc158b4bf08027bbc6825ceeaa82800e3af66ad417be0f00000000"
}

prop.donate

生成一笔捐赠交易，并返回该交易的原始数据(HEX格式)

入口参数

Property Description
txid 准备消耗的UTXO的交易哈希，小端格式
index 准备消耗的UTXO的索引，默认为0

Example Request

Example Response

{
  "hash": "78d06fa7cd44fe8f5bb811e268ff1ea594356d2700e9bbbbed6dc01cd3c2e054",
  "txid": "54e0c2d31cc06dedbbbbe900276d3594a51eff68e211b85b8ffe44cda76fd078",
  "cid": "73fd9030-bf01-11e8-9777-7fc8c74b6df3",
  "pid": "8ef12140-bf01-11e8-9777-7fc8c74b6df3",
  "oid": "sword",
  "raw": "010000000001017bdd6e315d4214c8ecb5a22522ccf266e7f2b883fea2a5ffa3039f8f9188efb50000000000ffffffff0002483045022100aa860e3b22029574dde1b2513ac53048465c1b229ae0ec84f6c9533ad26b7f320220683ce1df4791d0d0f3ca6a19cc852af020da024ed617a9ffe8856c900c9cf24e02210317f79b1b9a0190475bbb208017524fea99f307ac4adf5ed459c86b8e7c2e88e300000000"

prop.receive

根据输入的捐赠交易的原始数据，补充、签署、发送该交易，以获得其中包含的道具

入口参数

Property Description
raw 捐赠交易的原始数据(HEX格式的字符串)

Example Request

Example Response

{
  "hash": "7cc47718a2a3da398ddc015d1bbbffeddcb4e0c95c4cc1d4fc4dc1d2a50e30c8",
  "txid": "c8300ea5d2c14dfcd4c14c5cc9e0b4dcedffbb1b5d01dc8d39daa3a21877c47c",
  "cid": "73fd9030-bf01-11e8-9777-7fc8c74b6df3",
  "pid": "8ef12140-bf01-11e8-9777-7fc8c74b6df3",
  "oid": "sword",
  "addr": "tb1qp702eg67av8ty6jl87hyfas8v6h9rzxugvz7su"
}

和区块数据相关的接口

查询区块信息

支持分页

GET
http://localhost:17332/public/blocks

Example Request

Example Response

{
    "blocks": [
      {
        "height": 544972,
        "size": 1126,
        "virtualSize": 1126,
        "hash": "000000000000000001aadeb33e33230bf35eaa6d4303c57074a8040077c7aef1",
        "time": 1535208512,
        "txlength": 5,
        "poolInfo": {}
      }, {
        "height": 544971,
        "size": 33307,
        "virtualSize": 33307,
        "hash": "000000000000000000b193ca28b0388c6900cde1ee3d77578136a4cbbe9a2d59",
        "time": 1535208493,
        "txlength": 72,
        "poolInfo": {
            "poolName": "AntMiner",
            "url": "https://bitmaintech.com/"
        }
      }
    ],
    "length": 2,
    "pagination": {
        "next": "2018-08-26",
        "prev": "2018-08-24",
        "currentTs": 1535241599,
        "current": "2018-08-25",
        "isToday": true,
        "more": false
    }
}

根据哈希查询区块

GET
http://localhost:17332/public/block/:hash

Example Request

Example Response

{
    "hash": "000000000000000001aadeb33e33230bf35eaa6d4303c57074a8040077c7aef1",
    "size": 1126,
    "height": 544972,
    "version": 536870912,
    "merkleroot": "820df9ed8f57fe6464e5032fe0a9cbf4f986d793dcf78192b8a899993ba27d4b",
    "tx": ["38f6aa1c8112d681be031ea5113c1d4ffa9d245e0515cf27ed45210307cba86f", "2b45705210e20bbcb1f8c22ab26cddca086964f0122df42cd3dc48a2e1c563aa", "382cc1a07ccfc94676aa6373c4d19ac3a8485064b665335d270713393f0d6514", "60fe5f9173a1c78f2e0cbcff2b69baef5b90ee437c7363a367cbffb0e3a3c755", "ec1e19f1e121b1650d174e322bd3b674e0c943e5db6bc4a5422d6f177ea89bf3"],
    "time": 1535208512,
    "nonce": 4137301843,
    "bits": 402788059,
    "difficulty": 534246483976,
    "chainwork": "000000000000000000000000000000000000000000bc51a0a20e00709ff0f905",
    "confirmations": 1,
    "previousblockhash": "000000000000000000b193ca28b0388c6900cde1ee3d77578136a4cbbe9a2d59",
    "reward": 12.50007423,
    "isMainChain": true,
    "poolInfo": {}
}

获取块原始数据

GET
http://localhost:17332/public/rawblock/:hash

Example Request

Example Response

{
  "rawblock":"00000020592d9abecba4368157773deee1cd00698c38b028ca93b1000000000000000000820df9ed8f57fe6464e5032fe0a9cbf4f986d793dcf78192b8a899993ba27d4b406c815bdb0e021853379af60501000000010000000000000000000000000000000000000000000000000000000000000000ffffffff5c03cc5008192f5669614254432f4d696e6564206279206e6d73393133352f2cfabe6d6d184dc8e1ef0d19eddd4581a029620e0de25eaad2d6a1787c9df61d782045f37f0400000000000000109b63d30764e69a2d914f1943512b0100ffffffff017f99814a000000001976a914f1c075a01882ae0972f95d3a4177c86c852b7d9188ac000000000100000001e19cfde39d5ce89d39200dd0e7e7bbc9a2ea8bcf3a9c74b15edb40b45c921240000000006b483045022100f06cf926c0c630f678434cb6b8eb602064d0615f41bca5ad3c2b31d87692ab470220149e26ee6d4b0fb375dcb09ef81996365b853a8538be8cc0dc61b5db9f9e71be4121038dcabe66cc702624e6c7f2a437df7c36a68962a9becaa0f5f3e68a36839b5faaffffffff01c6dffe65010000001976a9146279b5d9e239500612d4f57d9cb1383bc6957a2288ac000000000200000001e7023fd9f341275c71181dc8797c987495d8fbe12db5619ac86d8c3e2fb1c197010000006b4830450221008a4a6b2d29bb5c5d96f55db2f513f8ef584aaa313c9112c745647fbd9d104cc00220646830de592a2ccea9abd9e30b4d9ded0cacbc66515792e56ca6291f02da84dd412102e730398dca951ded3e419829579c857f956d861ad5738d032ef17ccd2ca370aeffffffff02600e4e07000000001976a914cbe7d31810af5abb158d531fce0be1048021a30a88ace6b90100000000001976a9140a061221aa52f3942e8b39ad2b2c98abf058833488ac0000000002000000017755ce1733b8f89f14feceff96c9094ed571d78554478e733fa42abdfcffb5f3010000006b483045022100a9150be4afc7c0caffeed0b8f138701fc340be8ab0a0612862e600169b738acc0220792e8e9a274debb52c7a4ff76b84dbe1bc546efac36076dbac7d2211531f111b41210346e53d43ae00387c5198579129d4cf2e03ec6a66d7aee2f3efeba10c07cd64b3ffffffff02ff54bd03000000001976a914aa1604b040a7d3c86401fba95d1731b992d366e888ac19798c0d000000001976a9143bf58baf7fb8b69f7f4ffbb1a146c54ac78873e188ac00000000010000000145213921cec40e505c6f16e649b8205944e31dc85182a843909b234da605bc42010000006b483045022100bdf5c7dcf2baf938be5d336b222591f8e3435e9d67d8330544cc0cab40c631a002207979ad560335d35596e0d0141ff1e5ba7b363ce83a84328e6b549185b8506455412103cb8a7ef04cadfdc25425d84162f553bfee89b3109e939a3998c336b2f80642f0ffffffff02abdb00000000000017a9140c1ffe16047f2177e9e55b7b22e4ab699332b0d4870f763800000000001976a91429c69c5c468eab11fc22a558d80d7c555465595c88ac00000000"
}

根据高度查询区块

GET
http://localhost:17332/public/block-index/:height

Example Request

Example Response

{
    "blockHash": "000000000000000001aadeb33e33230bf35eaa6d4303c57074a8040077c7aef1"
}

和地址相关的接口

根据地址字符串，获取相应地址的关联信息

GET
http://localhost:17332/public/addr/:addr

Example Request

Example Response

{
    "addrStr": "qzj93tjl4unastps6c4rmg0xd6tgfxmmsu83r39jac",
    "balance": 10,
    "balanceSat": 1000000000,
    "totalReceived": 21.738,
    "totalReceivedSat": 2173800000,
    "totalSent": 11.738,
    "totalSentSat": 1173800000,
    "unconfirmedBalance": 0,
    "unconfirmedBalanceSat": 0,
    "unconfirmedTxApperances": 0,
    "txApperances": 2,
    "transactions": [
      "f0a56e7eedb628e8ff5bd9399aa0f4a1cc909168bb66129e170708ca8ff7911f", 
      "b1f14329a2ce13415f2c083aadb75e78cc01315a68a8448ecadc24794b8309fd", 
      "ad0ccb3718201d7392b4d49ef0df56557dad8cee4d5ab9b9605b34fa5fc05a2c"
    ]
}

根据地址字符串，获取相应地址的UTXO集合

GET
http://localhost:17332/public/addr/:addr/utxo

Example Request

Example Response

[
  {
    "address": "qzj93tjl4unastps6c4rmg0xd6tgfxmmsu83r39jac",
    "txid": "ad0ccb3718201d7392b4d49ef0df56557dad8cee4d5ab9b9605b34fa5fc05a2c",
    "vout": 0,
    "scriptPubKey": "76a914a458ae5faf27d82c30d62a3da1e66e96849b7b8788ac",
    "amount": 10,
    "satoshis": 1000000000,
    "height": 544967,
    "confirmations": 13
  }
]

查询多个地址的UTXO合集

地址字符串采用逗分格式，最多4个

GET
http://localhost:17332/public/addrs/:addrs/utxo

Example Request

Example Response

[
  {
    "address": "qzj93tjl4unastps6c4rmg0xd6tgfxmmsu83r39jac",
    "txid": "ad0ccb3718201d7392b4d49ef0df56557dad8cee4d5ab9b9605b34fa5fc05a2c",
    "vout": 0,
    "scriptPubKey": "76a914a458ae5faf27d82c30d62a3da1e66e96849b7b8788ac",
    "amount": 10,
    "satoshis": 1000000000,
    "height": 544967,
    "confirmations": 14
  }, 
  {
    "address": "qqx4tc82a2qepfkfmsff9z9eqwtacckeuvre8x5dkf",
    "txid": "b1f14329a2ce13415f2c083aadb75e78cc01315a68a8448ecadc24794b8309fd",
    "vout": 1,
    "scriptPubKey": "76a9140d55e0eaea8190a6c9dc129288b90397dc62d9e388ac",
    "amount": 0.00058477,
    "satoshis": 58477,
    "height": 544968,
    "confirmations": 13
  }, 
  {
    "address": "qqx4tc82a2qepfkfmsff9z9eqwtacckeuvre8x5dkf",
    "txid": "b6515df332afe96975b910474101bcad9f3704e36a025cb3298a09d7df1ed174",
    "vout": 1,
    "scriptPubKey": "76a9140d55e0eaea8190a6c9dc129288b90397dc62d9e388ac",
    "amount": 10.03049683,
    "satoshis": 1003049683,
    "height": 491481,
    "confirmations": 53500
  }
]

多地址交易查询

GET
http://localhost:17332/public/addrs/:addrs/txs

Example Request

Example Response

{
    "totalItems": 6,
    "from": 0,
    "to": 6,
    "items": [{
        "txid": "4da4f78590c1b648e127c30bdf10318e8fab4fc3d735815e71b69f5fec4e021d",
        "version": 1,
        "locktime": 0,
        "vin": [{
            "txid": "efd702c094ad62f2e42a10eaa909428ec956c1d737e561ef25bbc2f523a5be7e",
            "vout": 1,
            "sequence": 4294967295,
            "n": 0,
            "scriptSig": {
                "hex": "4830450220369720a96415c40111082c9d3a2034cb09efb28843ef7ad44a9038047e0da8b7022100f5b6087747de69053490bc01fb38bd3651584b0bd322b7228793cd4d25a9d6e4014104a8f73f8cfc61dd803b472e41df3c3de487b165ac7bc13f5b9f562a5fe0aef7675b08447c7826fff031df22302095ce5084a9daec16fdc82aba3a1cbedbfde670",
                "asm": "30450220369720a96415c40111082c9d3a2034cb09efb28843ef7ad44a9038047e0da8b7022100f5b6087747de69053490bc01fb38bd3651584b0bd322b7228793cd4d25a9d6e401 04a8f73f8cfc61dd803b472e41df3c3de487b165ac7bc13f5b9f562a5fe0aef7675b08447c7826fff031df22302095ce5084a9daec16fdc82aba3a1cbedbfde670"
            },
            "addr": "qqx4tc82a2qepfkfmsff9z9eqwtacckeuvre8x5dkf",
            "valueSat": 1000000000,
            "value": 10,
            "doubleSpentTxID": null,
            "isConfirmed": null,
            "confirmations": null,
            "unconfirmedInput": null
        }],
        "valueIn": 10,
        "fees": 0.0001,
        "vout": [{
            "value": "0.50000000",
            "n": 0,
            "scriptPubKey": {
                "hex": "76a914aa064dd44a83a6592704b3e4df54be7fd5ac5a2488ac",
                "asm": "OP_DUP OP_HASH160 aa064dd44a83a6592704b3e4df54be7fd5ac5a24 OP_EQUALVERIFY OP_CHECKSIG",
                "addresses": ["qz4qvnw5f2p6vkf8qje7fh65helattz6ys2nazryw5"],
                "type": "pubkeyhash"
            },
            "spentTxId": null,
            "spentIndex": null,
            "spentHeight": null
        }, {
            "value": "9.49990000",
            "n": 1,
            "scriptPubKey": {
                "hex": "76a9140d55e0eaea8190a6c9dc129288b90397dc62d9e388ac",
                "asm": "OP_DUP OP_HASH160 0d55e0eaea8190a6c9dc129288b90397dc62d9e3 OP_EQUALVERIFY OP_CHECKSIG",
                "addresses": ["qqx4tc82a2qepfkfmsff9z9eqwtacckeuvre8x5dkf"],
                "type": "pubkeyhash"
            },
            "spentTxId": null,
            "spentIndex": null,
            "spentHeight": null
        }],
        "blockhash": "00000000000000010cc748cb7c481b2d4e2c1c142c6295b21c148fb3c0e62771",
        "blockheight": 290250,
        "confirmations": 254731,
        "time": 1394652831,
        "blocktime": 1394652831,
        "valueOut": 9.9999,
        "size": 258
    }]
}

查询指定地址余额

GET
http://localhost:17332/public/addr/:addr/balance

Example Request

Example Response

  1.99900114

查询指定地址总接收

GET
http://localhost:17332/public/addr/:addr/totalReceived

Example Request

EXample Response

  1.99900114

查询指定地址总花费

GET
http://localhost:17332/public/addr/:addr/totalSent

Example Request

Example Response

  0

查询指定地址未确认金额

GET
http://localhost:17332/public/addr/:addr/unconfirmedBalance

Example Request

Example Response

  0

和交易相关的接口

根据交易ID获取交易信息

GET
http://localhost:17332/public/tx/:txid

Example Request

Example Response

{
    "txid":"a0aa92665cd61c5c2b2fe6f26287a226fb6fea033c59881298de36775773ce70",
    "version":1,
    "locktime":0,
    "isCoinBase":true,
    "vin":[     
        {
            "coinbase":"03785708202f5669614254432f4d696e656420627920677a7867666a7a687339313330302f2cfabe6d6dcdfdf8fed333ae7546bc9a3ee4ede9d1bf98e4ef3efd7cae20d6adb23b77ac57040000000000000010d7f0b90bf326c24d7fcbc32d79300100",
            "sequence":4294967295,
            "n":0
        }
    ],
    "vout":[
        {
            "value":"12.58185276",
            "n":0,
            "scriptPubKey":{
                "hex":"76a914f1c075a01882ae0972f95d3a4177c86c852b7d9188ac",
                "asm":"OP_DUP OP_HASH160 f1c075a01882ae0972f95d3a4177c86c852b7d91 OP_EQUALVERIFY OP_CHECKSIG",
                "addresses":["qrcuqadqrzp2uztjl9wn5sthepkg22majyxw4gmv6p"],
                "type":"pubkeyhash"
            },
            "spentTxId":null,
            "spentIndex":null,
            "spentHeight":null
        }
    ],
    "blockhash":"00000000000000000076b2016cde9097d68424e238c8a60a4de552895eb1cc32",
    "blockheight":546680,
    "confirmations":1,
    "time":1536227565,
    "blocktime":1536227565,
    "valueOut":12.58185276,
    "size":184
}

根据交易ID，查询交易原始数据

GET
http://localhost:17332/public/rawtx/:txid

Example Request

Example Response

{
  "rawtx":"01000000010000000000000000000000000000000000000000000000000000000000000000ffffffff2403c85008174d696e656420627920416e74506f6f6c3426205b816995350600008e0b0100ffffffff02b957824a000000001976a9141fefe863a7e0ddc767780ce3bedc564cf5cbda6388ace51d0000000000001976a914000000000000000000000000000000000000000088ac00000000"
}

查询区块或地址相关交易列表

支持分页

入口参数

Property Description
req.query.block 区块哈希，二选一
req.query.address 地址，二选一
req.query.pageNum 页码，默认第一页
GET
http://localhost:17332/public/txs

Example Request

Example Response

{
  "pagesTotal":221,
  "txs":[
    {
      "txid":"44f814cb17bce592fffbfbc86f187c0ba67c71c37240444133ae5beda8a22a6f",
      "version":1,
      "locktime":0,
      "vin":[
        {
          "txid":"4e857cc14a3848bf424c3d3f82d75a16d7c3f3011f699f9393b5cf3e1890e668",
          "vout":10,
          "sequence":4294967295,
          "n":0,
          "scriptSig":{
            "hex":"483045022100d5d8ce5aa87d8686b4eb57c6fe97bf9fa9eade0885acd75abadac55caf7cc7fe022079eff5b52ea4ed5ff56a86b3fe8f6510d8457b202ee2c3fefc196bc8aa69ce7a0121038482c9aef4e72ee8ef2501dddf27bbca7f5711400c7a9d4adb6dba82746fd0eb",
            "asm":"3045022100d5d8ce5aa87d8686b4eb57c6fe97bf9fa9eade0885acd75abadac55caf7cc7fe022079eff5b52ea4ed5ff56a86b3fe8f6510d8457b202ee2c3fefc196bc8aa69ce7a[ALL] 038482c9aef4e72ee8ef2501dddf27bbca7f5711400c7a9d4adb6dba82746fd0eb"
          },
          "addr":"1Nde8sQVbD3MJXxSohQJvRWKZKx9Zfo4oZ",
          "valueSat":9263816813,
          "value":92.63816813,
          "doubleSpentTxID":null
        }
      ],
      "vout":[
        {
          "value":"0.00527203",
          "n":0,
          "scriptPubKey":{
            "hex":"a914b71350787646b97f2508010dd51dea5d6079773887",
            "asm":"OP_HASH160 b71350787646b97f2508010dd51dea5d60797738 OP_EQUAL",
            "addresses":["3JP2iddqvycmRyZi944oVtN9eiSP57Tmwj"],
            "type":"scripthash"
          },
          "spentTxId":null,
          "spentIndex":null,
          "spentHeight":null
        }
      ],
      "blockhash":"000000000000000000020ce5c7fb6f916e94cc8c4dcb8612eeb2fff52495ecfe",
      "blockheight":540209,
      "confirmations":1,
      "time":1536242593,
      "blocktime":1536242593,
      "valueOut":92.63780119,
      "size":648,
      "valueIn":92.63816813,
      "fees":0.00036694
    }
  ]
}
{
  "pagesTotal":1,
  "txs":[
    {
      "txid":"7f812fa570950279c0c366b25ff30a3b8fdc7f130516ca8d76794c0a4954a399",
      "version":1,
      "locktime":0,
      "vin":[
        {
          "txid":"ad0ccb3718201d7392b4d49ef0df56557dad8cee4d5ab9b9605b34fa5fc05a2c",
          "vout":0,
          "sequence":4294967295,
          "n":0,
          "scriptSig":{
            "hex":"483045022100c7b2408fd0dcffbcdd00feffad4daba55c0fc908a2ae5b1941db82904fd028e0022072a568f9d2190541c6431d92e2b1e722af1db6501cacf3e7941a99c29e4b0dff41210381c5d018624c510d551646e605596e425c80cfa1c154dad7099501ce566179f8",
            "asm":"3045022100c7b2408fd0dcffbcdd00feffad4daba55c0fc908a2ae5b1941db82904fd028e0022072a568f9d2190541c6431d92e2b1e722af1db6501cacf3e7941a99c29e4b0dff41 0381c5d018624c510d551646e605596e425c80cfa1c154dad7099501ce566179f8"
          },
          "addr":"qzj93tjl4unastps6c4rmg0xd6tgfxmmsu83r39jac",
          "valueSat":1000000000,
          "value":10,
          "doubleSpentTxID":null,
          "isConfirmed":null,
          "confirmations":null,
          "unconfirmedInput":null
        }
      ],
      "valueIn":10,
      "fees":0.00000382,
      "vout":[
        {
          "value":"1.63873531",
          "n":0,
          "scriptPubKey":{
            "hex":"76a9149cb2f21046880cadffa76f13080194f6dd70a74488ac",
            "asm":"OP_DUP OP_HASH160 9cb2f21046880cadffa76f13080194f6dd70a744 OP_EQUALVERIFY OP_CHECKSIG",
            "addresses":["qzwt9ussg6yqet0l5ah3xzqpjnmd6u98gsr6n83pqm"],
            "type":"pubkeyhash"
          },
          "spentTxId":null,
          "spentIndex":null,
          "spentHeight":null
        },
        {
          "value":"8.36126087",
          "n":1,
          "scriptPubKey":{
            "hex":"76a914a772af263fda5e95d6fc6461e6868d8aeb21499e88ac",
            "asm":"OP_DUP OP_HASH160 a772af263fda5e95d6fc6461e6868d8aeb21499e OP_EQUALVERIFY OP_CHECKSIG",
            "addresses":["qznh9tex8ld9a9wkl3jxre5x3k9wkg2fncgchnmza5"],
            "type":"pubkeyhash"
          },
          "spentTxId":null,
          "spentIndex":null,
          "spentHeight":null
        }
      ],
      "blockhash":"000000000000000001c807fe20a65c06afd7a26a57e3d909988709f357b841d7",
      "blockheight":544985,
      "confirmations":1704,
      "time":1535214645,
      "blocktime":1535214645,
      "valueOut":9.99999618,
      "size":226
    }
  ]
}

域名查询类接口

域名列表

入口参数

Property Description
page 页数，默认1
GET
http://localhost:17332/public/cps

Example Request

Example Response

{
  "list": [
    {
      "cid": "b77a9b90-bbc4-11e8-9203-1ff8357db148",                                //CP编码
      "name": "hello",                                                              //CP名称
      "url": "http://127.0.0.1",                                                    //CP域名
      "ip": "",                                                                     //CP的IP地址
      "current": {
        "hash": "00465324a3a7487ebcf7fccf0ddcd72d7142b35669c2cb3e15bfc39dbef7e96a", //记录所在哈希
        "index": 0,                                                                 //对应的输出索引
        "address": "tb1qr790zz32jyyje8letxkavdv93qf7dmp0wjx3s0"                     //记录归属地址
      }
    }
  ],
  "page": 1,  //当前页码
  "total": 1  //总的页数
}

域名查询 - 根据ID

入口参数

Property Description
id CP编码

查询成功的结果：

查询失败的结果：

GET
http://localhost:17332/public/cp/:id

Example Request

Example Response

{
  "cid": "b77a9b90-bbc4-11e8-9203-1ff8357db148",
  "name": "hello",
  "url": "http://127.0.0.1",
  "ip": "",
  "current": {
    "hash": "00465324a3a7487ebcf7fccf0ddcd72d7142b35669c2cb3e15bfc39dbef7e96a",
    "index": 0,
    "address": "tb1qr790zz32jyyje8letxkavdv93qf7dmp0wjx3s0"
  }
}
{
  "error": {
    "type": "Error",
    "message": "No message."
  }
}

域名查询 - 根据名称

入口参数

Property Description
name CP名称，非英文字符需要通过 encodeURIComponent 进行编码

查询成功的结果

查询失败的结果：

GET
http://localhost:17332/public/cp/name/:name

Example Request

Example Response

{
  "cid": "b77a9b90-bbc4-11e8-9203-1ff8357db148",
  "name": "hello",
  "url": "http://127.0.0.1",
  "ip": "",
  "current": {
    "hash": "00465324a3a7487ebcf7fccf0ddcd72d7142b35669c2cb3e15bfc39dbef7e96a",
    "index": 0,
    "address": "tb1qr790zz32jyyje8letxkavdv93qf7dmp0wjx3s0"
  }
}
{
  "error": {
    "type": "Error",
    "message": "No message."
  }
}

系统状态查询类接口

系统状态

GET
http://localhost:17332/public/status

Example Request

Example Response

{
    "info": {
        "version": "bitcore-1.1.2",
        "blocks": 544981,
        "proxy": "",
        "difficulty": 559149630057,
        "testnet": false,
        "relayfee": 0,
        "errors": "",
        "network": "livenet"
    }
}

同步状态

GET
http://localhost:17332/public/sync

Example Request

Example Response

{
    "status": "finished",
    "blockChainHeight": 544981,
    "syncPercentage": 100,
    "height": 544981,
    "error": null,
    "type": "bitcore node"
}

API版本信息

GET
http://localhost:17332/public/version

Example Request

Example Response

{
    "version":"5.0.0-beta.44"
}

连接节点信息

GET
http://localhost:17332/public/peer

Example Request

Example Response

{
    "connected": true,
    "host": "127.0.0.1",
    "port": null
}

手续费估算

GET
http://localhost:17332/public/utils/estimatefee

Example Request

Example Response

{
    "2":0.00001
}

汇率

GET
http://localhost:17332/currency

Example Request

Example Response

{
    "status": 200,
    "data": {
        "kraken": 531.4
    }
}

支持币种

GET
http://localhost:17332/explorers

Example Request

Example Response

[
  {
    "name": "Bitcoin Cash",
    "ticker": "BCH",
    "url": "https://bch-insight.bitpay.com"
  },
  {
    "name": "Bitcoin",
    "ticker": "BTC",
    "url": "https://insight.bitpay.com"
  }
]
Show examples in:
cURLcliPythonJSJavaObjCSwift
API Documentation