Restful API 简介¶

为了简化DAPP的应用，MOAC以Restful API提供给应用链用户的一种接入方式。包括了对钱包，基础链，应用链，各交易查询的一系列封装。

DAPP用户当调用客户端SDK有困难时，可以通过服务端调用的方式实现对MOAC的接入。

在使用这些接口前，需要打开一个基础链节点的RPC接口和一个应用链节点的监听接口并允许外部访问。例如：基础链节点RPC接口：http://47.106.69.61:8989 应用链节点RPC接口：http://47.106.89.22:8546

为了使用应用链，需要部署好应用链，具体步骤可以参考： ProcWind 应用链部署

URL设计¶

使用http作为API的通信协议，目前采用较多的POST方法。

url格式: http(s)://server.com/api/{module}/{version}/{method}

关于version，各模块支持多版本，默认version为v1.0

POST提交格式采用form表单参数 Content-Type: application/x-www-form-urlencoded (a=name&b=666)

结构返回¶

返回体格式采用json格式

{
        "success": true,
        "message": "",
        "data": "*********"
}
success:  true - 成功    false - 失败
message： 失败时的错误信息
data：     接口返回数据

相关状态码 200 OK 403 token权限受限

接口访问控制¶

API访问控制，需先请求访问的用户名和密码，先调用auth接口请求访问token。

各api接口需要token参数调用，不然会返回403错误。

token有过期机制，目前是2小时有效。

私钥安全¶

对于账号私钥的安全提供了两种方案。

dapp注册账户后，收到返回的私钥（privatekey），后续发送交易直接传递私钥
dapp注册账户后，也会返回一个加密串（encode），后续发送交易传递加密串和账户密码，系统会解码获得私钥进行签名。

节点控制¶

测试环境地址：http://139.198.126.104:8080

测试环境获取access token，可使用测试账号：test 密码：123456

正式环境地址：https://api.moac.io:8080

正式环境获取access token，请联系开发团队：moacapi@mossglobal.net。

目前设计需要vnode节点的相关API，可通过参数传入地址和端口的方式指定连接的节点。参数传入为空的情况下，会使用平台默认的节点信息（测试环境对应testnet的默认节点，正式环境默认基础链节点）。

Restful API 接口¶

管理模块¶

API认证¶

请求访问token，提供权限调用API的其他接口

方法：auth

参数:

account:  授权账号
pwd:  授权账号密码

调用示例：

POST: http://139.198.126.104:8080/auth
BODY：account=******&pwd=******

返回数据示例

{
        "success": true,
        "message": "",
        "data": "token内容"
}

账户模块¶

账户注册¶

方法：register

参数:

pwd:  账户密码
token:  auth返回的授权token

调用示例：

POST: http://139.198.126.104:8080/api/account/v1.0/register
BODY：pwd=********&token=********************************

返回数据示例

{
        "success": true,
        "message": "",
        "address": 账户地址,
        "encode": 账户加密串,
        "keystore": 账户keystore信息,
        "privateKey": 账户私钥
}

账户登录¶

方法：login

参数:

address:  账户地址
pwd:  账户密码
encode:  账户加密串
token:  auth返回的授权token

调用示例：

POST: http://139.198.126.104:8080/api/account/v1.0/login
BODY：address=0x********&pwd=*****&encode=*******&token=************

返回数据示例

{
        "success": true,
        "message": "",
        "data": 账户地址
}

账户导入¶

方法：import 将账户通过keystore导入系统

参数:

address:  账户地址
pwd:  账户密码
keystore:  账户keystore
token:  auth返回的授权token

调用示例：

POST: http://139.198.126.104:8080/api/account/v1.0/import
BODY：address=0x********&pwd=*****&keystore={*******}&token=************

返回数据示例

{
        "success": true,
        "message": "",
        "address": 账户地址,
        "encode": 账户加密串,
        "privateKey": 账户私钥
}

基础链模块¶

账户余额¶

方法：getBalance

参数:

vnodeip:  vnode节点地址
vnodeport:  vnode节点端口
address:  账号地址
token:  auth返回的授权token

调用示例：

POST: http://139.198.126.104:8080/api/vnode/v1.0/getBalance
BODY：vnodeip=127.0.0.1&vnodeport=8545&address=0x******&token=*****************

返回数据示例

{
        "success": true,
        "message": "",
        "data": 账户余额 (单位 moac)
}

区块高度¶

方法：getBlockNumber

参数:

vnodeip:  vnode节点地址
vnodeport:  vnode节点端口
token:  auth返回的授权token

调用示例：

POST: http://139.198.126.104:8080/api/vnode/v1.0/getBlockNumber
BODY：vnodeip=127.0.0.1&vnodeport=8545&token=***************

返回数据示例

{
        "success": true,
        "message": "",
        "data": 区块高度
}

区块信息¶

方法：getBlockInfo

参数:

vnodeip:  vnode节点地址
vnodeport:  vnode节点端口
block:  区块号或者区块hash
token:  auth返回的授权token

调用示例：

POST: http://139.198.126.104:8080/api/vnode/v1.0/getBlockInfo
BODY：vnodeip=127.0.0.1&vnodeport=8545&block=2002326&token=******************

返回数据示例

{
        "success": true,
        "message": "",
        "data": 区块信息
}

交易明细¶

方法：getTransactionByHash

参数:

vnodeip:  vnode节点地址
vnodeport:  vnode节点端口
hash:  交易hash
token:  auth返回的授权token

调用示例：

POST: http://139.198.126.104:8080/api/vnode/v1.0/getTransactionByHash
BODY：vnodeip=127.0.0.1&vnodeport=8545&hash=0x**&token=******************

返回数据示例

{
        "success": true,
        "message": "",
        "data": 交易明细
}

交易详情¶

方法：getTransactionReceiptByHash

参数:

vnodeip:  vnode节点地址
vnodeport:  vnode节点端口
hash:  交易hash
token:  auth返回的授权token

调用示例：

POST: http://139.198.126.104:8080/api/vnode/v1.0/getTransactionReceiptByHash
BODY：vnodeip=127.0.0.1&vnodeport=8545&hash=0x**&token=******************

返回数据示例

{
        "success": true,
        "message": "",
        "data": 交易详情
}

转账¶

方法：sendRawTransaction

参数:

vnodeip:  vnode节点地址
vnodeport:  vnode节点端口
from:  源账号地址
to:  目标账号地址
amount:  数量（单位 moac）
method:  dapp合约方法 比如：buyMintToken(uint256)
paramtypes:  dapp合约方法对应的参数类型 比如：["uint256"]
paramvalues:  dapp合约方法对应的参数值   比如：[100000000]
privatekey:  源账号私钥 （传privatekey，可忽略参数pwd和encode，不传privatekey，则必须传pwd和encode认证）
pwd： 账户密码
encode：账户加密串
gasprice: 可选参数，默认gasprice为chain3的gasPrice，当交易堵塞时，需要传原交易的110%进行覆盖。
token:  auth返回的授权token

调用示例：

POST: http://139.198.126.104:8080/api/vnode/v1.0/sendRawTransaction
BODY：vnodeip=127.0.0.1&vnodeport=8545&from=0x**&to=0x***&amount=10&method=buyMintToken(uint256)&paramtypes=["uint256"]&paramvalues=[100000000]&privatekey=0x**&token=*******

返回数据示例

{
        "success": true,
        "message": "",
        "data": 交易hash
}

调用智能合约¶

方法：callContract

参数:

vnodeip:  vnode节点地址
vnodeport:  vnode节点端口
contractaddress:  合约地址
method:  dapp合约方法 比如：buyMintToken(uint256)
paramtypes:  dapp合约方法对应的参数类型 比如：["uint256"]
paramvalues:  dapp合约方法对应的参数值   比如：[100000000]
token:  auth返回的授权token

调用示例：

POST: http://139.198.126.104:8080/api/vnode/v1.0/callContract
BODY：vnodeip=127.0.0.1&vnodeport=8545&contractaddress=0x*****&method=buyMintToken(uint256)&paramtypes=["uint256"]&paramvalues=[100000000]0x****&token=***************

返回数据示例

{
        "success": true,
        "message": "",
        "data": 调用合约返回结果
}

erc20转账¶

方法：transferErc

参数:

vnodeip:  vnode节点地址
vnodeport:  vnode节点端口
from:  源账号地址
to:  目标账号地址
contractaddress:  erc20合约地址
amount:  erc20代币数量
privatekey:  源账号私钥（传privatekey，可忽略参数pwd和encode，不传privatekey，则必须传pwd和encode认证）
pwd： 账户密码
encode：账户加密串
token:  auth返回的授权token

调用示例：

POST: http://139.198.126.104:8080/api/vnode/v1.0/transferErc
BODY：vnodeip=&vnodeport=&from=0x**&to=0x**&contractaddress=0x**&amount=10&privatekey=0x**&token=*******

返回数据示例

{
        "success": true,
        "message": "",
        "data": 交易hash
}

ERC20余额¶

方法：getErcBalance

参数:

vnodeip:  vnode节点地址
vnodeport:  vnode节点端口
address:  账户地址
contractaddress:  erc20合约地址
token:  auth返回的授权token

调用示例：

POST: http://139.198.126.104:8080/api/vnode/v1.0/getErcBalance
BODY：vnodeip=127.0.0.1&vnodeport=8545&address=0x*****&contractaddress=0x**&token=*********

返回数据示例

{
        "success": true,
        "message": "",
        "data": 余额（最小精度，10进制）
}

erc20授权给应用链¶

方法：ercApprove

参数:

vnodeip:  vnode节点地址
vnodeport:  vnode节点端口
address:  账户地址
amount:  授权erc20数量
privatekey:  账号私钥（传privatekey，可忽略参数pwd和encode，不传privatekey，则必须传pwd和encode认证）
pwd： 账户密码
encode：账户加密串
microchainaddress                       应用链地址
contractaddress:  erc20合约地址
token:  auth返回的授权token

调用示例：

POST: http://139.198.126.104:8080/api/vnode/v1.0/ercApprove
BODY：vnodeip=127.0.0.1&vnodeport=8545&address=0x*****&amount=***&privatekey=0x***&microchainaddress=0x***&contractaddress=0x**&token=*********

返回数据示例

{
        "success": true,
        "message": "",
        "data": 交易hash
}

充值应用链 erc20兑换应用链原生币¶

方法：buyErcMintToken 注：前提是erc20对应数量已经授权给应用链

参数:

vnodeip:  vnode节点地址
vnodeport:  vnode节点端口
address:  账户地址
privatekey:  源账号私钥（传privatekey，可忽略参数pwd和encode，不传privatekey，则必须传pwd和encode认证）
pwd： 账户密码
encode：账户加密串
microchainaddress:  应用链地址
method:  dapp合约方法 默认为：buyMintToken(uint256)
paramtypes:  dapp合约方法对应的参数类型 默认为：["uint256"]
paramvalues:  dapp合约方法对应的参数值   比如：[100000000]
token:  auth返回的授权token

调用示例：

POST: http://139.198.126.104:8080/api/vnode/v1.0/buyErcMintToken
BODY：vnodeip=&vnodeport=&address=0x**&privatekey=0x**&microchainaddress=0x**&method=buyMintToken(uint256)&paramtypes=["uint256"]&paramvalues=[100000000]&token=****

返回数据示例

{
        "success": true,
        "message": "",
        "data": 交易hash
}

充值应用链 moac兑换应用链原生币¶

方法：buyMoacMintToken

参数:

vnodeip:  vnode节点地址
vnodeport:  vnode节点端口
address:  账户地址
privatekey:  源账号私钥
pwd： 账户密码
encode：账户加密串
microChainaddress:  应用链地址
method:  dapp合约方法 默认为：buyMintToken(uint256)
paramtypes:  dapp合约方法对应的参数类型 默认为：["uint256"]
paramvalues:  dapp合约方法对应的参数值   比如：[100000000]
token:  auth返回的授权token

调用示例：

POST: http://139.198.126.104:8080/api/vnode/v1.0/buyMoacMintToken
BODY：vnodeip=&vnodeport=&address=0x**&privatekey=0x**&microChainaddress=0x**&method=buyMintToken(uint256)&paramtypes=["uint256"]&paramvalues=[100000000]&token=****

返回数据示例

{
        "success": true,
        "message": "",
        "data": 交易hash
}

应用链模块¶

获得应用链区块高度¶

方法：getBlockNumber

参数:

microip:  monitor节点地址
microport:  monitor节点端口
microchainaddress:  应用链MicroChain地址
token:  auth返回的授权token

调用示例：

POST: http://139.198.126.104:8080/api/micro/v1.0/getBlockNumber
BODY：microip=127.0.0.1&microport=8546&microchainaddress=0x***&token=***********

返回数据示例

{
        "success": true,
        "message": "",
        "data": 应用链区块高度
}

获得应用链dapp地址列表¶

方法：getDappAddrList

参数:

microip:  monitor节点地址
microport:  monitor节点端口
microchainaddress:  应用链MicroChain地址
token:  auth返回的授权token

调用示例：

POST: http://139.198.126.104:8080/api/micro/v1.0/getDappAddrList
BODY：microip=127.0.0.1&microport=8546&microchainaddress=0x***&token=***********

返回数据示例

{
        "success": true,
        "message": "",
        "data": 应用链dapp地址列表（按合约注册次序）
}

获取应用链区块信息¶

方法：getBlock

参数:

microip:  monitor节点地址
microport:  monitor节点端口
microchainaddress:  应用链MicroChain地址
blocknum:  块号
token:  auth返回的授权token

调用示例：

POST: http://139.198.126.104:8080/api/micro/v1.0/getBlock
BODY：microip=127.0.0.1&microport=8546&microchainaddress=0x***&blocknum=*****&token=***********

返回数据示例

{
        "success": true,
        "message": "",
        "data": 应用链区块信息
}

获得应用链对应Hash的交易信息¶

方法：getTransactionByHash

参数:

microip:  monitor节点地址
microport:  monitor节点端口
microchainaddress:  应用链MicroChain地址
hash:  交易hash
token:  auth返回的授权token

调用示例：

POST: http://139.198.126.104:8080/api/micro/v1.0/getTransactionByHash
BODY：microip=127.0.0.1&microport=8546&microchainaddress=0x***&hash=0x**&token=***********

返回数据示例

{
        "success": true,
        "message": "",
        "data": 应用链交易信息
}

获得应用链对应Hash的交易明细¶

方法：getTransactionReceiptByHash

参数:

microip:  monitor节点地址
microport:  monitor节点端口
microchainaddress:  应用链MicroChain地址
hash:  交易hash
token:  auth返回的授权token

调用示例：

POST: http://139.198.126.104:8080/api/micro/v1.0/getTransactionReceiptByHash
BODY：microip=127.0.0.1&microport=8546&microchainaddress=0x***&hash=0x**&token=***********

返回数据示例

{
        "success": true,
        "message": "",
        "data": 应用链交易明细，其中主要字段描述如下：
                failed：交易是否成功  false表示成功
                        result：如执行合约方法，retrun的数据
                        transactionHash：应用链hash
                        contractAddress：当部署合约时，返回合约地址

}

获取应用链账户余额¶

方法：getBalance

参数:

microip:  monitor节点地址
microport:  monitor节点端口
microchainaddress:  应用链MicroChain地址
address:  账户地址
token:  auth返回的授权token

调用示例：

POST: http://139.198.126.104:8080/api/micro/v1.0/getBalance
BODY：vnodeip=&vnodeport=&microip=127.0.0.1&microport=8546&microchainaddress=0x*****&address=0x*****&token=**************

返回数据示例

{
        "success": true,
        "message": "",
        "data": 账户余额
}

应用链原生币转账¶

方法：transferCoin

注意，这个方法中用户有两种方法授权，一种是直接发送私钥（private key），简单但是有泄露风险；另一种是使用账户密码和账户加密串，需要调用帐号模块来生成后使用。

参数:

vnodeip:  vnode节点地址
vnodeport:  vnode节点端口
microip:  monitor节点地址
microport:  monitor节点端口
microchainaddress:  应用链MicroChain地址
via:  应用链收益账号
from:  源账户地址
to:  目标账户地址
amount:  原生币数量
privatekey:  源账号私钥（传privatekey，可忽略参数pwd和encode）
token:  auth返回的授权token
memo: 备注 （交易的Input Data会由目标账户地址+memo内容组成）

或者：

vnodeip:  vnode节点地址
vnodeport:  vnode节点端口
microip:  monitor节点地址
microport:  monitor节点端口
microchainaddress:  应用链MicroChain地址
via:  应用链收益账号
from:  源账户地址
to:  目标账户地址
amount:  原生币数量
pwd： 账户密码 （传参数pwd和encode，不用传privatekey）
encode：账户加密串
token:  auth返回的授权token
memo: 备注 （交易的Input Data会由目标账户地址+memo内容组成）

调用示例：

POST: http://139.198.126.104:8080/api/micro/v1.0/transferCoin
// Send Private Key
BODY：vnodeip=&vnodeport=&microip=127.0.0.1&microport=8546&microchainaddress=0x**&via=0x**&from=0x**&to=0x**&amount=**&memo=***&privatekey=0x***&token=*****

或者：

POST: http://139.198.126.104:8080/api/micro/v1.0/transferCoin
// Send pwd and encode
BODY：vnodeip=&vnodeport=&microip=127.0.0.1&microport=8546&microchainaddress=0x**&via=0x**&from=0x**&to=0x**&amount=**&memo=***&pwd=***&encode=***&token=*****

返回数据示例

{
        "success": true,
        "message": "",
        "data": 交易hash
}

应用链加签交易¶

方法：sendRawTransaction 调用dapp合约涉及修改数据的方法

参数:

vnodeip: vnode节点地址
vnodeport:  vnode节点端口
microip:  monitor节点地址
microport:  monitor节点端口
from: 发送交易账户地址
microchainaddress:  应用链MicroChain地址
via:  应用链收益账号
amount:  payable对应金额
dappaddress:  dapp合约地址
method:  dapp合约方法 比如：buyMintToken(uint256)
paramtypes:  dapp合约方法对应的参数类型 比如：["uint256"]
paramvalues:  dapp合约方法对应的参数值   比如：[100000000]
privatekey: 源账号私钥（传privatekey，可忽略参数pwd和encode，不传privatekey，则必须传pwd和encode认证）
pwd： 账户密码
encode：账户加密串
token: auth返回的授权token

调用示例：

POST: http://139.198.126.104:8080/api/micro/v1.0/sendRawTransaction
BODY：vnodeip=&vnodeport=&microip=127.0.0.1&microport=8546&from=0x**&microchainaddress=0x***&via=0x**&amount=**&dappaddress=0x***&method=buyMintToken(uint256)&paramtypes=["uint256"]&paramvalues=[100000000]&privatekey=0x***&token=*****

返回数据示例

{
        "success": true,
        "message": "",
        "data": 应用链交易hash
}

应用链合约调用¶

方法：callContract 针对public方法和变量，不涉及数据修改

参数:

microip:  monitor节点地址
microport:  monitor节点端口
microchainaddress:  应用链MicroChain地址
dappaddress:  dapp合约地址
data:  字符串数组，如合约方法getTopicList(uint pageNum, uint pageSize)，则传入["getTopicList", "0", "20"]
token:  auth返回的授权token

调用示例：

POST: http://139.198.126.104:8080/api/micro/v1.0/callContract
BODY：vnodeip=&vnodeport=&microip=127.0.0.1&microport=8546&microchainaddress=0x*****&dappaddress=0x**&data=&token=********

返回数据示例

{
        "success": true,
        "message": "",
        "data": 合约返回结果
}

应用链ERC提币¶

方法：redeemErcMintToken 原生币转erc20

参数:

vnodeip:  vnode节点地址
vnodeport:  vnode节点端口
microipHmonitor节点地址
microport:  monitor节点端口
microchainaddress:  应用链MicroChain地址
dappbaseaddress:  dappbase合约地址
via:  应用链收益账号
address:  提币账户地址
amount:  提取原生币数量
privatekey:  源账号私钥（传privatekey，可忽略参数pwd和encode，不传privatekey，则必须传pwd和encode认证）
pwd： 账户密码
encode：账户加密串
token:  auth返回的授权token

调用示例：

POST: http://139.198.126.104:8080/api/micro/v1.0/redeemErcMintToken
BODY：vnodeip=&vnodeport=&microip=127.0.0.1&microport=8546&microchainaddress=0x**&dappbaseaddress=0x**&via=0x**&address=0x**&amount=**&data=****&privatekey=0x**&token=********

返回数据示例

{
        "success": true,
        "message": "",
        "data": 交易hash
}

应用链MOAC提币¶

方法：redeemMoacMintToken 原生币转moac

参数:

vnodeip:  vnode节点地址
vnodeport:  vnode节点端口
microipHmonitor节点地址
microport:  monitor节点端口
microchainaddress:  应用链MicroChain地址
dappbaseaddress:  dappbase合约地址
via:  应用链收益账号
address:  提币账户地址
amount:  提取原生币数量
privatekey:  源账号私钥（传privatekey，可忽略参数pwd和encode，不传privatekey，则必须传pwd和encode认证）
pwd： 账户密码
encode：账户加密串
token:  auth返回的授权token

调用示例：

POST: http://139.198.126.104:8080/api/micro/v1.0/redeemMoacMintToken
BODY：vnodeip=&vnodeport=&microip=127.0.0.1&microport=8546&microchainaddress=0x**&dappbaseaddress=0x**&via=0x**&address=0x**&amount=**&data=****&privatekey=0x**&token=********

返回数据示例

{
        "success": true,
        "message": "",
        "data": 交易hash
}