RESTful API

Get Contract Address

GET https://api.zks.app/:version/:network/contract-address

Returns the contracts being used for deposit, etc. In most time, the response won't be changed.

Path Parameters

Name	Type	Description
network	number	The network number. 1 for mainnet, 3 for ropsten, etc.

200

{
    "success": true,
    "data": {
        "gov": "0x86E527BC3C43E6Ba3eFf3A8CAd54A7Ed09cD8E8B",
        "main": "0x6dE5bDC580f55Bc9dAcaFCB67b91674040A247e3"
    }
}

Get Token List

GET https://api.zks.app/:version/:network/tokens

Returns all tokens which have been listed on ZKSwap.

Query Parameters

Name	Type	Description
network	number	The network number. 1 for mainnet, 3 for ropsten, etc.

200

{
    "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 Token Prices

GET https://api.zks.app/:version/:network/tokens/price

Returns all tokens' prices on ZKSwap.

Path Parameters

Name	Type	Description
network	number	The network number. 1 for mainnet, 3 for ropsten, etc.

200

{
    "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 Pair List

GET https://api.zks.app/:version/:network/pairs

Returns all pairs which have been added on ZKSwap.

Path Parameters

Name	Type	Description
network	number	The network number. 1 for mainnet, 3 for ropsten, etc.

200

{
    "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 Pair Prices

GET https://api.zks.app/:version/:network/pairs/price

Returns all pairs' prices on ZKSwap.

Path Parameters

Name	Type	Description
network	number	The network number. 1 for mainnet, 3 for ropsten, etc.网

200

{
    "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 Account Balance

GET https://api.zks.app/:version/: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.

Path Parameters

Name	Type	Description
network	number	The network number. 1 for mainnet, 3 for ropsten, etc.
address	string	The account's address, which is case insensitive.

200

{
    "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 Account Info

GET https://api.zks.app/:version/: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.

Path Parameters

Name	Type	Description
network	number	The network number. 1 for mainnet, 3 for ropsten, etc.
address	string	The account's address, which is case insensitive.

200

{
    "success": true,
    "data": {
        "id": 2,
        "nonce": 1256,
        "pub_key_hash": "sync:e4762290aa804636fd63ee25fe91497a8ea01dea"
    }
}

Get Account Fee

GET https://api.zks.app/:version/:network/account/:address/fee

All fees are in USD.

Path Parameters

Name	Type	Description
network	number	The network number. 1 for mainnet, 3 for ropsten, etc.
address	string	The account's address, which is case insensitive.

200

{
    "success": true,
    "data": {
        "transfer": "0",
        "withdraw": "5",
        "add_liquidity": "0",
        "remove_liquidity": "0"
    }
}

Get Transaction List

GET https://api.zks.app/:version/:network/txs

Returns the list of transactions.

Path Parameters

Name	Type	Description
network	number	The network number. 1 for mainnet, 3 for ropsten, etc.

Query Parameters

Name	Type	Description
address	string	The transaction address. No matter it's sender or receiver.
types	string	The list of types, seperated with |. See below for all types. e.g. AddLiquidity|RemoveLiquidity
token	number	The unique ID of a token
start	number	Default 0.
limit	number	Default 50. Maximum 50.

200

{
    "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 Transaction

GET https://api.zks.app/:version/:network/tx/:tx_hash

Return the transaction data.

Path Parameters

Name	Type	Description
network	number	The network number. 1 for mainnet, 3 for ropsten, etc.
tx_hash	string	The transaction hash.

200

{
    "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
    }
}

Submit Transaction

POST https://api.zks.app/:network/tx

Submit the transaction to ZKSwap Layer-2. Returns the transaction hash if it's accepted.

Path Parameters

Name	Type	Description
network	number	The network number. 1 for mainnet, 3 for ropsten, etc.

Request Body

Name	Type	Description
tx	object	The signed transaction data.
signature	object	Layer1 signature. For ChangePubKey, it should be null.
fastProcessing	boolean	null

200

{
    "success": true,
    "data": "sync-tx:26fc8afdd61d944489e2139aea900bbd34fc71eaad9a741e7e66320b46993f4d"
}

Click here to see how to make a transaction.