RESTful API

get
Get Contract Address

https://api.zks.app/v2/:network/contract-address
Returns the contracts being used for deposit, etc. In most time, the response won't be changed.
Request
Response
Request
Path Parameters
network
required
number
The network number. 1 for mainnet, 3 for ropsten, etc.
Response
200: OK
{
"success": true,
"data": {
"gov": "0x86E527BC3C43E6Ba3eFf3A8CAd54A7Ed09cD8E8B",
"main": "0x6dE5bDC580f55Bc9dAcaFCB67b91674040A247e3"
}
}

get
Get Token List

https://api.zks.app/v2/:network/tokens
Returns all tokens which have been listed on ZKSwap.
Request
Response
Request
Query Parameters
network
required
number
The network number. 1 for mainnet, 3 for ropsten, etc.
Response
200: OK
{
"success": true,
"data": [
{
"id": 0,
"address": "0x0000000000000000000000000000000000000000",
"decimals": 18,
"symbol": "ETH",
"icon": "https://s.zks.app/icons/v2/0x0000000000000000000000000000000000000000.png",
"approved": true
},
{
"id": 10,
"address": "0xe4815ae53b124e7263f08dcdbbb757d41ed658c6",
"decimals": 18,
"symbol": "ZKS",
"icon": "https://s.zks.app/icons/v2/0xe4815ae53b124e7263f08dcdbbb757d41ed658c6.png",
"approved": true
},
{
"id": 32,
"address": "0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9",
"decimals": 18,
"symbol": "AAVE",
"icon": "https://s.zks.app/icons/v2/0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9.png",
"approved": true
}
]
}

Here's the schema of each token:

Field

Type

Comment

id

number

The unique ID starting from 0, which is native coin.

address

address

Native coin's address is 0x0000000000000000000000000000000000000000

decimals

number

The number of decimals used to get its user representation.

symbol

string

The unique symbol indicates the symbol.

icon

string

The image url shows the icon.

get
Get Token Prices

https://api.zks.app/v2/:network/tokens/price
Returns all tokens' prices on ZKSwap.
Request
Response
Request
Path Parameters
network
required
number
The network number. 1 for mainnet, 3 for ropsten, etc.
Response
200: OK
{
"success": true,
"data": [
{
"id": 0,
"price": "2968.1483043140707263"
},
{
"id": 10,
"price": "0.7862725980605806"
},
{
"id": 32,
"price": "0"
}
]
}

Field

Type

Comment

id

number

The unique ID.

price

string

The unit is USD.

get
Get Pair List

https://api.zks.app/v2/:network/pairs
Returns all pairs which have been added on ZKSwap.
Request
Response
Request
Path Parameters
network
required
number
The network number. 1 for mainnet, 3 for ropsten, etc.
Response
200: OK
{
"success": true,
"data": [
{
"id": 16384,
"address": "0xda097aa54e44e389f2acadb69027c8780a8ec852",
"decimals": 18,
"symbol": "liquidity_10_32",
"id_a": 10,
"id_b": 32,
"anchored": 10
},
{
"id": 16385,
"address": "0x9c883156e724ceb48d230da0132fab4aa721ae84",
"decimals": 18,
"symbol": "liquidity_8_10",
"id_a": 8,
"id_b": 10,
"anchored": 8
},
{
"id": 16386,
"address": "0xaa45c964e21eafb38574e9d000adbaf85acfbb80",
"decimals": 18,
"symbol": "liquidity_0_10",
"id_a": 0,
"id_b": 10,
"anchored": 0
}
]
}

Field

Type

Comment

id

number

The unique ID starting from 16384.

address

address

It's the same as the LP token on Layer-1.

decimals

number

The number of decimals used to get its user representation, it's always 18.

symbol

string

The unique symbol follows the format liquidity_{idA}_{idB}.

id_a

string

The ID of token A.

id_b

string

The ID of token B.

get
Get Pair Prices

https://api.zks.app/v2/:network/pairs/price
Returns all pairs' prices on ZKSwap.
Request
Response
Request
Path Parameters
network
required
number
The network number. 1 for mainnet, 3 for ropsten, etc.网
Response
200: OK
{
"success": true,
"data": [
{
"id": 16384,
"amount_a": "0",
"amount_b": "0",
"price": "0",
"totalSupply": "0"
},
{
"id": 16385,
"amount_a": "1464474.697055",
"amount_b": "1859053.645591589842522106",
"price": "1782999.9600978410438763",
"totalSupply": "1.642708614502310855"
},
{
"id": 16386,
"amount_a": "33.667299246695146243",
"amount_b": "127772.687849889681268329",
"price": "96.778364123199939",
"totalSupply": "2065.121436478357148901"
}
]
}

Field

Type

Comment

id

number

The unique ID.

amount_a

string

The formatted amount of token A in the pair (also known as reverse0).

amount_b

string

The formatted amount of token B in the pair (also known as reverse1).

price

string

The number indicates how much 1 LP token values.

totalSupply

string

get
Get Account Balance

https://api.zks.app/v2/:network/account/:address/balances
Returns the balances of an address. If the address never had a token/pair, it won't be listed. All the unit of asset is USD.
Request
Response
Request
Path Parameters
network
required
number
The network number. 1 for mainnet, 3 for ropsten, etc.
address
required
string
The account's address, which is case insensitive.
Response
200: OK
{
"success": true,
"data": {
"balances": {
"tokens": [
{
"id": 8,
"amount": "14.918202",
"Value": "0"
},
{
"id": 10,
"amount": "720651.4115822",
"Value": "0"
},
{
"id": 32,
"amount": "0.6027962441",
"Value": "0"
}
],
"pairs": [
{
"id": 16385,
"amount": "0.000294957624075052",
"Value": "523.4426987137814436216811147071194148"
},
{
"id": 16387,
"amount": "0.000004427188724235",
"Value": "482.09321566002294012027060109989963"
}
]
},
"asset": {
"tokens": "562353.0359099654094174914699",
"pairs": "1005.5359143738043837419517158070190448",
"total": "563358.5718243392138012334216158070190448"
}
}
}

get
Get Account Info

https://api.zks.app/v2/:network/account/:address/info
Returns the id, nonce and pubKeyHash of the account. If the address never had any asset on ZKSwap, the id is 0.
Request
Response
Request
Path Parameters
network
required
number
The network number. 1 for mainnet, 3 for ropsten, etc.
address
required
string
The account's address, which is case insensitive.
Response
200: OK
{
"success": true,
"data": {
"id": 2,
"nonce": 1256,
"pub_key_hash": "sync:e4762290aa804636fd63ee25fe91497a8ea01dea"
}
}

get
Get Account Fee

https://api.zks.app/v2/:network/account/:address/fee
All fees are in USD.
Request
Response
Request
Path Parameters
network
required
number
The network number. 1 for mainnet, 3 for ropsten, etc.
address
required
string
The account's address, which is case insensitive.
Response
200: OK
{
"success": true,
"data": {
"transfer": "0",
"withdraw": "5",
"add_liquidity": "0",
"remove_liquidity": "0"
}
}

get
Get Transaction List

https://api.zks.app/v2/:network/txs
Returns the list of transactions.
Request
Response
Request
Path Parameters
network
required
number
The network number. 1 for mainnet, 3 for ropsten, etc.
Query Parameters
address
optional
string
The transaction address. No matter it's sender or receiver.
types
optional
string
The list of types, seperated with |. See below for all types. e.g. AddLiquidity|RemoveLiquidity
token
optional
number
The unique ID of a token
start
optional
number
Default 0.
limit
optional
number
Default 50. Maximum 50.
Response
200: OK
{
"success": true,
"data": {
"pagination": {
"total": 2,
"start": 0,
"limit": 100
},
"data": [
{
"amount": "2",
"block_number": 1920,
"created_at": 1628344581,
"fail_reason": "",
"fee": "0",
"fee_token": 0,
"fee_value": "0",
"from": "0x961b513dfd3e363c238e0f98219ee02552a847bd",
"id": 6014,
"nonce": 1252,
"status": "verified",
"success": true,
"to": "0x1c65291ba1c67b539d6f957fcc2f1944c146dbc9",
"token": {
"id": 10,
"symbol": "ZKS"
},
"tx_hash": "0x3dca53000392ff1fc059f40b0a64a247d94bd7d46ec05397da13aaf592cb902e",
"tx_type": "Transfer",
"value": "1.72841"
},
{
"amount": {
"amount": "0.000004427188724235",
"amount_a": "0.1",
"amount_b": "196"
},
"block_number": 14,
"created_at": 1626329003,
"fail_reason": "",
"fee": "0",
"fee_token": 8,
"fee_value": "0",
"from": "0x961b513dfd3e363c238e0f98219ee02552a847bd",
"id": 19,
"nonce": 2,
"status": "verified",
"success": true,
"to": "0x2e35bb0d1570b1fb816255974a21b375cefe1eca",
"token": {
"id": 16387,
"id_a": 0,
"id_b": 8,
"symbol_a": "ETH",
"symbol_b": "USDT"
},
"tx_hash": "0x42453836dbe9689a75be663534a5c3de73901c38c56defb406b9135a510625b2",
"tx_type": "AddLiquidity",
"value": "392"
}
]
}
}

Each transaction contains the following fields:

Field

Type

Comment

tx_hash

string

The hash of the transaction.

tx_type

string

One of the following: Deposit, Transfer, Withdraw, Swap, AddLiquidity and RemoveLiquidity.

status

string

pending or verified

from

address

The transaction sender.

to

address

The transaction receiver. For Swap, AddLiquidity and RemoveLiquidity, the receiver is the pair address.

token

object

It always contains id. For Swap, AddLiquidity and RemoveLiquidity, it contains id_a and id_b.

amount

mixed

For Deposit, Withdraw and Transfer, it's the formatted amount. For other type, it's an object contains amount_a and amount_b.

value

string

The value of transaction in USD.

fee_token

number

The ID of transaction fee token.

fee

string

The transaction fee.

fee_value

string

The value of transaction fee in USD.

block_number

number

The block it belongs.

created_at

number

The UNIX timestamp when the transaction created.

success

boolean

Indicates the transaction is successful or not.

fail_reason

string

Only contains message when transaction failed.

nonce

number

Similar with ETH's nonce.

get
Get Transaction

https://api.zks.app/v2/:network/tx/:tx_hash
Return the transaction data.
Request
Response
Request
Path Parameters
network
required
number
The network number. 1 for mainnet, 3 for ropsten, etc.
tx_hash
required
string
The transaction hash.
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
Submit Transaction

https://api.zks.app/v2/:network/tx
Submit the transaction to ZKSwap Layer-2. Returns the transaction hash if it's accepted.
Request
Response
Request
Path Parameters
network
required
number
The network number. 1 for mainnet, 3 for ropsten, etc.
Body Parameters
tx
required
object
The signed transaction data.
signature
optional
object
Layer1 signature. For ChangePubKey, it should be null.
fastProcessing
optional
boolean
null
Response
200: OK
{
"success": true,
"data": "sync-tx:26fc8afdd61d944489e2139aea900bbd34fc71eaad9a741e7e66320b46993f4d"
}

Click here to see how to make a transaction.