> For the complete documentation index, see [llms.txt](https://en.wiki.zks.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://en.wiki.zks.org/interact-with-zkswap/restful-api.md).

# RESTful API

## Get Contract Address

<mark style="color:blue;">`GET`</mark> `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. |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}
{% endtabs %}

## Get Token List

<mark style="color:blue;">`GET`</mark> `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. |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "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
        }
    ]
}
```

{% endtab %}
{% endtabs %}

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

<mark style="color:blue;">`GET`</mark> `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. |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "success": true,
    "data": [
        {
            "id": 0,
            "price": "2968.1483043140707263"
        },
        {
            "id": 10,
            "price": "0.7862725980605806"
        },
        {
            "id": 32,
            "price": "0"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

| Field | Type   | Comment          |
| ----- | ------ | ---------------- |
| id    | number | The unique ID.   |
| price | string | The unit is USD. |

## Get Pair List

<mark style="color:blue;">`GET`</mark> `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. |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "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
        }
    ]
}
```

{% endtab %}
{% endtabs %}

| 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

<mark style="color:blue;">`GET`</mark> `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.网 |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "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"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

| 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

<mark style="color:blue;">`GET`</mark> `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.      |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}
{% endtabs %}

## Get Account Info

<mark style="color:blue;">`GET`</mark> `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.      |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}
{% endtabs %}

## Get Account Fee

<mark style="color:blue;">`GET`</mark> `https://api.zks.app/:version/:network/account/:address/fee`

&#x20;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.      |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}
{% endtabs %}

## Get Transaction List

<mark style="color:blue;">`GET`</mark> `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.                                                                             |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "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"
            }
        ]
    }
}
```

{% endtab %}
{% endtabs %}

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

<mark style="color:blue;">`GET`</mark> `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.                                  |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}
{% endtabs %}

## Submit Transaction

<mark style="color:green;">`POST`</mark> `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                                                   |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}
{% endtabs %}

Click [here](https://app.gitbook.com/@zkswap-1/s/zkswap-en/interact-with-zkswap/make-transaction) to see how to make a transaction.