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.

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

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

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

{
    "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.网

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

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

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

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

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

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

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

Click here to see how to make a transaction.

PreviousDefinitionNextMake Transaction

Last updated