RESTful API

get
获取合约地址

https://api.zks.app/:network/contract-address
返回用于充值的合约地址,大多数情况下该地址不变。
Request
Response
Request
Path Parameters
network
required
number
network = 1对应主网,network = 3对应 ropsten 测试网
Response
200: OK
{
"success": true,
"data": {
"gov": "0x02ecef526f806f06357659fFD14834fe82Ef4B04",
"main": "0x8ECa806Aecc86CE90Da803b080Ca4E3A9b8097ad"
}
}

get
获取 Token 列表

https://api.zks.app/:network/tokens
返回 ZKSwap 中所有 token 的列表。
Request
Response
Request
Query Parameters
network
required
number
network = 1对应主网, network = 3对应 ropsten 测试网
Response
200: OK
{
"success": true,
"data": [
{
"id": 29,
"address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
"decimals": 6,
"symbol": "USDT",
"icon": "https://s.zks.app/icons/USDT.png"
},
{
"id": 0,
"address": "0x0000000000000000000000000000000000000000",
"decimals": 18,
"symbol": "ETH",
"icon": "https://s.zks.app/icons/ETH.png"
},
{
"id": 1,
"address": "0xe4815ae53b124e7263f08dcdbbb757d41ed658c6",
"decimals": 18,
"symbol": "ZKS",
"icon": "https://s.zks.app/icons/ZKS.png"
}
]
}

token 字段构成如下:

Field

Type

Comment

id

number

从 0(ETH) 开始的唯一 ID。

address

address

ETH 的地址是 0x0000000000000000000000000000000000000000

decimals

number

用于获得预设值的小数位数

symbol

string

标识 token 的唯一符号

icon

string

图标 url 路径

get
获取代币价格

https://api.zks.app/:network/tokens/price
返回 ZKSwap 上所有代币的价格。
Request
Response
Request
Path Parameters
network
required
number
network = 1对应主网, network = 3对应 ropsten 测试网
Response
200: OK
{
"success": true,
"data": [
{
"id": 1,
"price": "2.976453475636384"
},
{
"id": 0,
"price": "1815.0342358082221711"
},
{
"id": 29,
"price": "1"
}
]
}

Field

Type

Comment

id

number

唯一的 ID

price

string

计价单位: USD(美元)

get
获取交易对列表

https://api.zks.app/:network/pairs
返回已添加到 ZKSwap 上的所有交易对。
Request
Response
Request
Path Parameters
network
required
number
network = 1对应主网, network = 3对应 ropsten 测试网
Response
200: OK
{
"success": true,
"data": [
{
"id": 128,
"address": "0xf005ab93a5ede376de898f0980cc63b460273e3d",
"decimals": 18,
"symbol": "liquidity_1_29",
"id_a": 1,
"id_b": 29,
"icon": ""
},
{
"id": 129,
"address": "0xe2e321995a4b7cff33f9683a4df71bb01f4e73c3",
"decimals": 18,
"symbol": "liquidity_0_29",
"id_a": 0,
"id_b": 29,
"icon": ""
},
{
"id": 158,
"address": "0xc6f8a2d663250ad86c6c58fc310238e1e5e457d6",
"decimals": 18,
"symbol": "liquidity_0_1",
"id_a": 0,
"id_b": 1,
"icon": ""
}
]
}

Field

Type

Comment

id

number

从 128 开始的唯一 ID

address

address

与 Layer-1 上的 LP token 一样

decimals

number

用于获得预设值的小数位数,此处 decimals 恒等于 18

symbol

string

唯一标识符格式:liquidity_{idA}_{idB}

id_a

string

token A 的 ID

id_b

string

token B 的 ID

icon

string

图标 url 路径

get
获取交易对价格

https://api.zks.app/:network/pairs/price
返回 ZKSwap 上的所有交易对的价格。
Request
Response
Request
Path Parameters
network
required
number
network = 1对应主网,network = 3对应 ropsten 测试网
Response
200: OK
{
"success": true,
"data": [
{
"id": 128,
"amount_a": "3927387.371952108042173401",
"amount_b": "12632930.441588",
"price": "15832216.6136153725252923",
"totalSupply": "1.595851136943635068"
},
{
"id": 129,
"amount_a": "8350.498763294378497644",
"amount_b": "16300589.333348",
"price": "90716923.2626106764865417",
"totalSupply": "0.359372623036618122"
},
{
"id": 158,
"amount_a": "6078.874270166717020624",
"amount_b": "3715204.937177018697447186",
"price": "174.3184048310910203",
"totalSupply": "136627.480452166905325656"
},
]
}

Field

Type

Comment

id

number

唯一 ID

amount_a

string

交易对中 token A 的数量(也被称为 reverse0)

amount_b

string

交易对中 token B 的数量(也被称为 reverse1)

price

string

表示 1 LP token 值多少

totalSupply

string

总供应

get
获取账户余额

https://api.zks.app/:network/account/:address/balances
返回一个地址的余额。如果一个地址未持有任何代币或交易对,将不会被显示。所有资产的计价单位为 USD(美元)。
Request
Response
Request
Path Parameters
network
required
number
network = 1对应主网, network = 3对应 ropsten 测试网
address
required
string
账户地址,注意区分大小写
Response
200: OK
{
"success": true,
"data": {
"balances": {
"tokens": [
{
"id": 1,
"amount": "163.850170000240526635"
},
{
"id": 29,
"amount": "421.342263"
}
],
"pairs": [
{
"id": 128,
"amount": "0.009171849735891207"
}
]
},
"asset": {
"tokens": "950.231852570053484922321931242533217",
"pairs": "145482.12859050287003815706093845640114920031857182312416",
"total": "146432.36044307292352307938286969893436620031857182312416"
}
}
}

get
获取账户信息

https://api.zks.app/:network/account/:address/info
返回账户的 id,nonce,pubKeyHash 字段信息。若该地址在 ZKSwap 上无任何资产,则 id = 0
Request
Response
Request
Path Parameters
network
required
number
network = 1对应主网, network = 3对应 ropsten 测试网
address
required
string
账户地址,注意区分大小写
Response
200: OK
{
"success": true,
"data": {
"id": 15481,
"nonce": 11,
"pub_key_hash": "sync:862de014ebec20974e22e8593bb21bdd214fa754"
}
}

get
Get Account Fee 获取账户费用

https://api.zks.app/:network/account/:address/fee
Request
Response
Request
Path Parameters
network
required
number
network = 1对应主网, network = 3对应 ropsten 测试网
address
required
string
账户地址,注意区分大小写
Response
200: OK

get
获取交易列表

https://api.zks.app/:network/txs
返回交易列表
Request
Response
Request
Path Parameters
network
required
number
network = 1对应主网, network = 3对应 ropsten 测试网
Query Parameters
address
optional
string
发送方或接受方的账户地址。
types
optional
string
类型集合,用分割开表示, 例如:AddLiquidity | RemoveLiquidity
token
optional
number
某个 token 的唯一 id
start
optional
number
默认 0
limit
optional
number
默认 50,上限 50
Response
200: OK
{
"success": true,
"data": {
"pagination": {
"total": 586459,
"start": 0,
"limit": 50
},
"data": [
{
"id": 586459,
"tx_hash": "0x13c524f822bc92e9195bf7ec50db9bc6b33a2d269a78188e019d2870d5042630",
"tx_type": "Withdraw",
"status": "pending",
"from": "0x5bd9dee999fe2c4e6efdbab2c395b4685b0c00d0",
"to": "0x1be4acc82a1b8c6b57ebf56f4da57981c7a09453",
"token": {
"id": 0,
"symbol": "ETH"
},
"amount": "44.99999999",
"value": "87796.22185",
"fee": "0.00256",
"fee_value": "4.99463",
"fee_b": "0",
"fee_b_value": "0",
"block_number": 41449,
"created_at": 1617299567,
"success": true,
"fail_reason": "",
"nonce": 1231
},
{
"id": 586458,
"tx_hash": "0x6efbb612bb445debd31e82f63282b3b075732f1d35b6f296469c444f39395a3c",
"tx_type": "Swap",
"status": "pending",
"from": "0x4d287f99aaa3afba7c372815341581304e7fa573",
"to": "0xf005ab93a5ede376de898f0980cc63b460273e3d",
"token": {
"id_a": 1,
"id_b": 29,
"symbol_a": "ZKS",
"symbol_b": "USDT"
},
"amount": {
"amount_a": "2000",
"amount_b": "6425.151371"
},
"value": "6425.15137",
"fee": "6",
"fee_value": "19.32351",
"fee_b": "0",
"fee_b_value": "0",
"block_number": 41449,
"created_at": 1617299565,
"success": true,
"fail_reason": "",
"nonce": 2876
},
{
"id": 586433,
"tx_hash": "0x9073df41def307564a8cd569cbae0c2a813b4c3d5f692e1a3a8323b7fab42d2d",
"tx_type": "AddLiquidity",
"status": "pending",
"from": "0xd6e1e53465f50d4b1a8294b052e5f972fba5ebe4",
"to": "0x5c7d7683758b449c11fcbd68da4e9a5398073f35",
"token": {
"id": 213,
"id_a": 30,
"id_b": 29,
"symbol_a": "BUSD",
"symbol_b": "USDT"
},
"amount": {
"amount": "0.000261185806411614",
"amount_a": "261.08086447",
"amount_b": "261.495942"
},
"value": "522.99188",
"fee": "0",
"fee_value": "0",
"fee_b": "0",
"fee_b_value": "0",
"block_number": 41440,
"created_at": 1617298650,
"success": true,
"fail_reason": "",
"nonce": 10
},
{
"id": 586432,
"tx_hash": "0x0495467c78bea6cbec0cd32577b5addd3a5027b9933649e64674fa800cc5ad6e",
"tx_type": "Deposit",
"status": "pending",
"from": "0x5bd9dee999fe2c4e6efdbab2c395b4685b0c00d0",
"to": "0x5bd9dee999fe2c4e6efdbab2c395b4685b0c00d0",
"token": {
"id": 3,
"symbol": "WBTC"
},
"amount": "1.59937338",
"value": "94751.42597",
"fee": "0",
"fee_value": "0",
"fee_b": "0",
"fee_b_value": "0",
"block_number": 41439,
"created_at": 1617298626,
"success": true,
"fail_reason": "",
"nonce": -1
},
{
"id": 586420,
"tx_hash": "0x7f361e10e54161c0e0f293d477e2782d0d4c3df0631f06fc679697891301a57e",
"tx_type": "Transfer",
"status": "pending",
"from": "0xc79fb0c8b40ae5d6059925235a56a5aa95ace891",
"to": "0x3c035b69e4307ba3af475e526c7111dc1131f51a",
"token": {
"id": 1,
"symbol": "ZKS"
},
"amount": "108.10066477",
"value": "350.91789",
"fee": "0",
"fee_value": "0",
"fee_b": "0",
"fee_b_value": "0",
"block_number": 41435,
"created_at": 1617298091,
"success": true,
"fail_reason": "",
"nonce": 5256
}
]
}
}

每个交易包含如下字段信息:

Field

Type

Comment

id

number

交易 ID,不直接使用,使用 tx_hash 代替该字段

tx_hash

string

交易 hash

tx_type

string

交易类型,包括 Deposit, Transfer, Withdraw, Swap, AddLiquidity, RemoveLiquidity

status

string

状态,包括 pendingverified

from

address

交易发送方

to

address

交易接受方,对于 Swap, AddLiquidity 和 RemoveLiquidity 交易类型,接受方是一个交易对地址

token

object

包含 id 字段,对于 Swap, AddLiquidity 和 RemoveLiquidity 交易类型,还包含 id_a 和 id_b 字段

amount

mixed

对于 Deposit(充值), Withdraw(提现) 和 Transfer(转账), amount 表示格式化过的数量;对于其他交易类型,amount 是一个包含 amount_a amount_b 的对象

value

string

交易额(以 USD 计算)

fee

string

手续费

fee_value

string

手续费(以 USD 计算)

fee_b

string

手续费 B ,仅当添加 / 移除流动性时有该字段

fee_b_value

string

手续费 B (以 USD 计算),仅当添加 / 移除流动性时有该字段

block_number

number

区块编号

created_at

number

创建时间(UNIX timestamp)

success

boolean

标志交易是否成功

fail_reason

string

交易失败信息,仅当交易失败时该字段有内容

nonce

number

类似于 ETH 的 nonce

get
获取交易信息

https://api.zks.app/:network/tx/:tx_hash
返回某个交易的信息
Request
Response
Request
Path Parameters
network
required
number
network = 1对应主网, network = 3对应 ropsten 测试网
tx_hash
required
string
交易哈希值
Response
200: OK
{
"success": true,
"data": {
"id": 586433,
"tx_hash": "0x9073df41def307564a8cd569cbae0c2a813b4c3d5f692e1a3a8323b7fab42d2d",
"tx_type": "AddLiquidity",
"status": "verified",
"from": "0xd6e1e53465f50d4b1a8294b052e5f972fba5ebe4",
"to": "0x5c7d7683758b449c11fcbd68da4e9a5398073f35",
"token": {
"id": 213,
"id_a": 30,
"id_b": 29,
"symbol_a": "BUSD",
"symbol_b": "USDT"
},
"amount": {
"amount": "0.000261185806411614",
"amount_a": "261.08086447",
"amount_b": "261.495942"
},
"value": "522.99188",
"fee": "0",
"fee_value": "0",
"fee_b": "0",
"fee_b_value": "0",
"block_number": 41440,
"created_at": 1617298650,
"success": true,
"fail_reason": "",
"nonce": 10
}
}

post
交易提交

https://api.zks.app/:network/tx
向 ZKSwap Layer-2 发起交易提交,若 ZKSwap 接受则返回交易 hash
Request
Response
Request
Path Parameters
network
required
number
network = 1对应主网, network = 3对应 ropsten 测试网
Body Parameters
tx
required
object
签名的交易信息
signature
optional
object
Layer1签名,对于 ChangePubKey 应该为null
fastProcessing
optional
boolean
null
Response
200: OK
{
"success": true,
"data": "sync-tx:26fc8afdd61d944489e2139aea900bbd34fc71eaad9a741e7e66320b46993f4d"
}

Click here to see how to make a transaction.