# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://en.wiki.zks.org/interact-with-zkswap/restful-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.