# Liquidity

> Providing liquidity on Qoq: registering for shares, adding and removing liquidity in the ratio of a pool's balances, taking the pool's fees in either asset, collecting and withdrawing them.

This page is part of the Qoq docs. Qoq is the DEX `slimedragon.near/amp` on the Intear DEX contract, `dex.intear.near`, and every call goes to that contract. https://docs.intear.tech/qoq/llms-full.txt has all of its pages in one file, and https://docs.intear.tech/llms.txt lists every page of the Intear docs.

Anyone can add liquidity to any Qoq pool, and gets shares of it. Liquidity goes in and comes out in the ratio of the pool's balances, so it doesn't need the oracle and doesn't move the price. All calls on this page are [`dex_call`](https://docs.intear.tech/intear-dex/guides/dexes.md#dex_call)s from your inner balance, with Borsh arguments in base64.

The examples run as alice.near after a [storage deposit](https://docs.intear.tech/intear-dex/guides/storage.md#accounts), registering NEAR, USDt and USDC, and depositing 0.01 NEAR for storage and 10 USDt and 10 USDC. They use pool 1, USDt/USDC. Together they're [one script](#the-whole-script).

```sh
near contract call-function as-transaction dex.intear.near storage_deposit \
  json-args '{}' \
  prepaid-gas '30.0 Tgas' attached-deposit '0.01 NEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send

near contract call-function as-transaction dex.intear.near register_assets \
  json-args '{
    "asset_ids": [
      "near",
      "nep141:usdt.tether-token.near",
      "nep141:17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1"
    ]
  }' \
  prepaid-gas '30.0 Tgas' attached-deposit '1 yoctoNEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send

near contract call-function as-transaction dex.intear.near deposit_near \
  json-args '{}' \
  prepaid-gas '30.0 Tgas' attached-deposit '0.01 NEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send

near contract call-function as-transaction usdt.tether-token.near ft_transfer_call \
  json-args '{"receiver_id": "dex.intear.near", "amount": "10000000", "msg": ""}' \
  prepaid-gas '50.0 Tgas' attached-deposit '1 yoctoNEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send

near contract call-function as-transaction 17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1 ft_transfer_call \
  json-args '{"receiver_id": "dex.intear.near", "amount": "10000000", "msg": ""}' \
  prepaid-gas '50.0 Tgas' attached-deposit '1 yoctoNEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send
```

The whole file, tested in CI: https://docs.intear.tech/snippets/cli/qoq-liquidity.sh

## Register

Before your first addition to a pool, register for its shares with `register_liquidity`. Its argument is the pool ID, a Borsh `u32`. Attach NEAR for the storage: Qoq uses what it needs and sends the rest to your wallet. `AQAAAA==` is pool 1:

```sh
near contract call-function as-transaction dex.intear.near dex_call \
  json-args '{
    "dex_id": "slimedragon.near/amp",
    "method": "register_liquidity",
    "args": "AQAAAA==",
    "attached_assets": {"near": "10000000000000000000000"}
  }' \
  prepaid-gas '100.0 Tgas' attached-deposit '1 yoctoNEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send
```

The whole file, tested in CI: https://docs.intear.tech/snippets/cli/qoq-liquidity.sh

Registering again does nothing. The creator of a pool is registered already.

## Add

`add_liquidity` takes:

```rust
struct AddLiquidityArgs {
    pool_id: u32,
    /// Fail if the addition would mint fewer shares
    min_shares_received: Option<u128>,
}
```

Attach both assets of the pool. Qoq mints shares for the amounts in the ratio of the pool's balances, limited by the asset you attached less of, takes what that needs of each, and sends the rest to your wallet. It rounds in the pool's favor: 1 unit of each asset more than the shares are worth. `AQAAAAA=` is pool 1 with no minimum:

```sh
near contract call-function as-transaction dex.intear.near dex_call \
  json-args '{
    "dex_id": "slimedragon.near/amp",
    "method": "add_liquidity",
    "args": "AQAAAAA=",
    "attached_assets": {
      "nep141:usdt.tether-token.near": "10000000",
      "nep141:17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1": "10000000"
    }
  }' \
  prepaid-gas '100.0 Tgas' attached-deposit '1 yoctoNEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send
```

The whole file, tested in CI: https://docs.intear.tech/snippets/cli/qoq-liquidity.sh

Pool 1 holds more USDt than USDC, so the addition took all 10 USDt and less USDC, and sent the rest of the USDC back. Set `min_shares_received` to fail if the balances changed before your call.

A pool whose liquidity was all removed has `total_shares` `None` and both balances at 0. Adding to it works differently: all of both attached amounts go in, you get 10<sup>18</sup> shares, and `min_shares_received` must be `None`.

## Your shares

`get_pool_shares` takes a list of pool IDs and an account, and returns a Borsh `Vec<Option<u128>>`: the shares in each pool, or `None` if the account isn't registered for it.

```sh
near contract call-function as-read-only dex.intear.near dex_view \
  json-args '{
    "dex_id": "slimedragon.near/amp",
    "method": "get_pool_shares",
    "args": "AQAAAAEAAAAKAAAAYWxpY2UubmVhcg=="
  }' \
  network-config mainnet now
```

The whole file, tested in CI: https://docs.intear.tech/snippets/cli/qoq-liquidity.sh

Your part of the pool is `shares / total_shares` of each of its balances. [`get_pool`](https://docs.intear.tech/qoq/reference/methods.md#views) returns `total_shares` and the balances.

## Fees

80% of a pool's fee goes to its providers, in proportion to their shares, and the other 20% to Qoq. Each provider chooses how it takes its part, with a `FeePayoutType`:

| Payout | What you get |
| --- | --- |
| `KeepBoth` (0) | The fee in the asset each swap paid in, so some of both. New providers start with it |
| `ConvertToFirstAsset` (1), `ConvertToSecondAsset` (2) | All of it in one of the pool's assets. The pool swaps the fees paid in the other asset into it, on its curve at the swap's price, without fees |

Fees wait in the pool until you collect them. Adding liquidity, removing it, changing the payout and `collect_liquidity_fees` all collect them to your collected fees, which `withdraw_fees` moves to your inner balance. What the pool can't split evenly between providers, after rounding, stays in its liquidity.

`set_liquidity_fee_payout` takes the pool ID and the new payout. It collects what you earned so far first. `AQAAAAI=` is pool 1 and `ConvertToSecondAsset`, USDC:

```sh
# Take this pool's fees in USDC, its second asset, from now on
near contract call-function as-transaction dex.intear.near dex_call \
  json-args '{
    "dex_id": "slimedragon.near/amp",
    "method": "set_liquidity_fee_payout",
    "args": "AQAAAAI=",
    "attached_assets": {}
  }' \
  prepaid-gas '100.0 Tgas' attached-deposit '1 yoctoNEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send
```

The whole file, tested in CI: https://docs.intear.tech/snippets/cli/qoq-liquidity.sh

`get_liquidity_position` takes the pool ID and an account, and returns a Borsh `Option<LiquidityPositionView>`, `None` if the account isn't registered for the pool:

```rust
struct LiquidityPositionView {
    payout_type: FeePayoutType,
    /// Fees in each asset of the pool that aren't collected yet
    uncollected_fees: (u128, u128),
}
```

```sh
near contract call-function as-read-only dex.intear.near dex_view \
  json-args '{
    "dex_id": "slimedragon.near/amp",
    "method": "get_liquidity_position",
    "args": "AQAAAAoAAABhbGljZS5uZWFy"
  }' \
  network-config mainnet now
```

The whole file, tested in CI: https://docs.intear.tech/snippets/cli/qoq-liquidity.sh

`collect_liquidity_fees` takes the pool ID and collects your fees without changing anything else:

```sh
# Move the pool's fees earned so far to the fees that withdraw_fees withdraws
near contract call-function as-transaction dex.intear.near dex_call \
  json-args '{
    "dex_id": "slimedragon.near/amp",
    "method": "collect_liquidity_fees",
    "args": "AQAAAA==",
    "attached_assets": {}
  }' \
  prepaid-gas '100.0 Tgas' attached-deposit '1 yoctoNEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send
```

The whole file, tested in CI: https://docs.intear.tech/snippets/cli/qoq-liquidity.sh

`withdraw_fees` takes a Borsh `Vec<AssetId>` and moves your collected fees in those assets to your inner balance. Assets with nothing collected are skipped. `get_pending_fees` takes your account and the assets, and returns how much is collected in each. Qoq's protocol fee is collected for `qoq.intear.near` the same way.

```sh
# The collected fees in USDt and USDC, to alice.near's inner balance
near contract call-function as-transaction dex.intear.near dex_call \
  json-args '{
    "dex_id": "slimedragon.near/amp",
    "method": "withdraw_fees",
    "args": "AgAAAAEWAAAAdXNkdC50ZXRoZXItdG9rZW4ubmVhcgFAAAAAMTcyMDg2MjhmODRmNWQ2YWQzM2YwZGEzYmJiZWIyN2ZmY2IzOThlYWM1MDFhMzFiZDZhZDIwMTFlMzYxMzNhMQ==",
    "attached_assets": {}
  }' \
  prepaid-gas '100.0 Tgas' attached-deposit '1 yoctoNEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send
```

The whole file, tested in CI: https://docs.intear.tech/snippets/cli/qoq-liquidity.sh

## Remove

`remove_liquidity` takes:

```rust
struct RemoveLiquidityArgs {
    pool_id: u32,
    /// None removes all of your shares
    shares_to_remove: Option<u128>,
    /// Fail if you would get less of either asset
    min_assets_received: Option<(u128, u128)>,
}
```

Don't attach anything. Your part of both assets, rounded down, is sent to your wallet, after your fees are collected. `AQAAAAAA` removes all of your liquidity from pool 1, without minimums:

```sh
near contract call-function as-transaction dex.intear.near dex_call \
  json-args '{
    "dex_id": "slimedragon.near/amp",
    "method": "remove_liquidity",
    "args": "AQAAAAAA",
    "attached_assets": {}
  }' \
  prepaid-gas '100.0 Tgas' attached-deposit '1 yoctoNEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send
```

The whole file, tested in CI: https://docs.intear.tech/snippets/cli/qoq-liquidity.sh

You stay registered for the pool, with 0 shares.

## Events

Adding and removing liquidity log [`LiquidityAdded`](https://docs.intear.tech/qoq/reference/events.md#liquidityadded) and [`LiquidityRemoved`](https://docs.intear.tech/qoq/reference/events.md#liquidityremoved), with the amounts, the shares, and what the provider owns after, and a [`PoolUpdated`](https://docs.intear.tech/qoq/reference/events.md#poolupdated). Collecting fees logs [`LiquidityFeesCollected`](https://docs.intear.tech/qoq/reference/events.md#liquidityfeescollected), and registering or a new payout logs [`LiquidityFeePayoutSet`](https://docs.intear.tech/qoq/reference/events.md#liquidityfeepayoutset).

## The whole script

```sh
#!/usr/bin/env bash
# Adds liquidity to the USDt/USDC pool on Qoq, chooses how to take its fees, and
# removes it. alice.near holds USDt and USDC in the wallet and has never used
# Intear DEX.
set -euo pipefail

near contract call-function as-transaction dex.intear.near storage_deposit \
  json-args '{}' \
  prepaid-gas '30.0 Tgas' attached-deposit '0.01 NEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send

near contract call-function as-transaction dex.intear.near register_assets \
  json-args '{
    "asset_ids": [
      "near",
      "nep141:usdt.tether-token.near",
      "nep141:17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1"
    ]
  }' \
  prepaid-gas '30.0 Tgas' attached-deposit '1 yoctoNEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send

near contract call-function as-transaction dex.intear.near deposit_near \
  json-args '{}' \
  prepaid-gas '30.0 Tgas' attached-deposit '0.01 NEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send

near contract call-function as-transaction usdt.tether-token.near ft_transfer_call \
  json-args '{"receiver_id": "dex.intear.near", "amount": "10000000", "msg": ""}' \
  prepaid-gas '50.0 Tgas' attached-deposit '1 yoctoNEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send

near contract call-function as-transaction 17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1 ft_transfer_call \
  json-args '{"receiver_id": "dex.intear.near", "amount": "10000000", "msg": ""}' \
  prepaid-gas '50.0 Tgas' attached-deposit '1 yoctoNEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send

near contract call-function as-transaction dex.intear.near dex_call \
  json-args '{
    "dex_id": "slimedragon.near/amp",
    "method": "register_liquidity",
    "args": "AQAAAA==",
    "attached_assets": {"near": "10000000000000000000000"}
  }' \
  prepaid-gas '100.0 Tgas' attached-deposit '1 yoctoNEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send

near contract call-function as-transaction dex.intear.near dex_call \
  json-args '{
    "dex_id": "slimedragon.near/amp",
    "method": "add_liquidity",
    "args": "AQAAAAA=",
    "attached_assets": {
      "nep141:usdt.tether-token.near": "10000000",
      "nep141:17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1": "10000000"
    }
  }' \
  prepaid-gas '100.0 Tgas' attached-deposit '1 yoctoNEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send

near contract call-function as-read-only dex.intear.near dex_view \
  json-args '{
    "dex_id": "slimedragon.near/amp",
    "method": "get_pool_shares",
    "args": "AQAAAAEAAAAKAAAAYWxpY2UubmVhcg=="
  }' \
  network-config mainnet now

# Take this pool's fees in USDC, its second asset, from now on
near contract call-function as-transaction dex.intear.near dex_call \
  json-args '{
    "dex_id": "slimedragon.near/amp",
    "method": "set_liquidity_fee_payout",
    "args": "AQAAAAI=",
    "attached_assets": {}
  }' \
  prepaid-gas '100.0 Tgas' attached-deposit '1 yoctoNEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send

near contract call-function as-read-only dex.intear.near dex_view \
  json-args '{
    "dex_id": "slimedragon.near/amp",
    "method": "get_liquidity_position",
    "args": "AQAAAAoAAABhbGljZS5uZWFy"
  }' \
  network-config mainnet now

# Move the pool's fees earned so far to the fees that withdraw_fees withdraws
near contract call-function as-transaction dex.intear.near dex_call \
  json-args '{
    "dex_id": "slimedragon.near/amp",
    "method": "collect_liquidity_fees",
    "args": "AQAAAA==",
    "attached_assets": {}
  }' \
  prepaid-gas '100.0 Tgas' attached-deposit '1 yoctoNEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send

# The collected fees in USDt and USDC, to alice.near's inner balance
near contract call-function as-transaction dex.intear.near dex_call \
  json-args '{
    "dex_id": "slimedragon.near/amp",
    "method": "withdraw_fees",
    "args": "AgAAAAEWAAAAdXNkdC50ZXRoZXItdG9rZW4ubmVhcgFAAAAAMTcyMDg2MjhmODRmNWQ2YWQzM2YwZGEzYmJiZWIyN2ZmY2IzOThlYWM1MDFhMzFiZDZhZDIwMTFlMzYxMzNhMQ==",
    "attached_assets": {}
  }' \
  prepaid-gas '100.0 Tgas' attached-deposit '1 yoctoNEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send

near contract call-function as-transaction dex.intear.near dex_call \
  json-args '{
    "dex_id": "slimedragon.near/amp",
    "method": "remove_liquidity",
    "args": "AQAAAAAA",
    "attached_assets": {}
  }' \
  prepaid-gas '100.0 Tgas' attached-deposit '1 yoctoNEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send
```
