# API Usage

Welcome to the TAPP Exchange API documentation. This API allows you to interact with our Aptos-based decentralized exchange. You can use it to swap tokens, create liquidity pools, and query pool/token data.

## 📚 Table of Contents

* [API Access Methods](#api-access-methods)
* [Signing Write Operations](#signing-write-operations)
* [List Endpoint](#list-endpoints)
  * [Pool List](#pool-list)
  * [Token List](#token-list)
  * [Pool Info](#pool-info)
  * [Position](#position)
  * [User Transaction](#user-transaction)
  * [Swap](#swap)
  * [Create Pool and Add Liquidity](#create-pool-and-add-liquidity)
  * [Add Liquidity](#add-liquidity)
  * [Remove Liquidity](#remove-liquidity)
  * [Remove Multi Liquidity](#remove-multi-liquidity)
  * [Collect Fee](#collect-fee)

## API Access Methods

TAPP Exchange supports interaction through multiple transport layers:

* **HTTP POST** – Standard and recommended for all JSON-RPC operations
* **WebSocket** – Coming soon

All interfaces use a unified protocol: **JSON-RPC 2.0**

***

> **Base URL**: [https://api.tapp.exchange/api/v1](https://api.tapp.exchange/api/v1)

***

## Signing Write Operations

All **write operations** (such as `swap`, `create pool`, `add liquidity`, `remove liquidity` and `collect fee`) require the user to **sign the transaction** using their Aptos wallet.

The signed payload ensures authenticity and authorization.

### 🔐 Step-by-Step: Signing with Wallet

1. **Client** calls an api to get an **unsigned payload**.
2. **Client** signs and submit the payload using their wallet (Petra, Martian, etc.).

### ✅ Example: Sign and Submit Swap Transaction

#### Step 1 – Get Unsigned Payload from API

See [`public/swap`](#swap), [`public/create-pool-add-liquidity`](#create-pool-and-add-liquidity), [`public/add-liquidity`](#add-liquidity), [`public/remove-liquidity`](#remove-liquidity), [`public/remove-multi-liquidity`](#remove-multi-liquidity) and [`public/collect-fee`](#collect-fee) for generating the unsigned payload.

#### Step 2 - sign and submit transactions to the blockchain using our backend's hex string payload.

Signing Example Using `JavaScript`

```javascript
const hexPayload = "this value received from our backend"

// Convert bytes to BCS
const txSer = Deserializer.fromHex(hexPayload);

// Convert BCS to raw transaction
const rawTxn = RawTransaction.deserialize(txSer)

// Sign and Submit Transaction
const simpleTxn = new SimpleTransaction(rawTxn)
const response = await aptos.signAndSubmitTransaction({signer: sender, transaction: simpleTxn});
```

***

Signing Example Using `Golang`

```golang
payloadHex := “this value received from our backend”
txBytes, err := hex.DecodeString(payloadHex)
if err != nil { // Handle error here }

// Convert to raw transaction
deserializer := bcs.NewDeserializer(txBytes)
rawTxn := &aptos.RawTransaction{}
rawTxn.UnmarshalBCS(deserializer)
if deserializer.Error() != nil { // handle error here }

// Sign and Submit transaction
signedTxn, err := rawTxn.SignedTransaction(sender)
if err != nil { // handle error here }

submittedTxn, err := client.SubmitTransaction(signedTxn)
if err != nil { // handle error here}
```

***

Signing Example Using `Javascript (useWallet)`

```javascript
const hexPayload = "this value received from our backend"

// Convert bytes to BCS
const txSer = Deserializer.fromHex(hexPayload);

// Convert BCS to raw transaction
const rawTxn = RawTransaction.deserialize(txSer)

// Sign and Submit Transaction
const simpleTxn = new SimpleTransaction(rawTxn)

// Use the wallet's signTransaction method to get account authentication
const accAuth = await signTransaction(simpleTxn)

// Create the transaction builder
const signedTxn = new SignedTransaction(rawTxn, accAuth);

// full signed transaction
const signedTxnBytes = signedTxn.bcsToBytes(); 

// Convert to hex string
const txHex = Buffer.from(signedTxnBytes).toString('hex');

// submit the signed transaction to the backend
const response = await fetch('https://api.tapp.exchange/api/v1', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    method: 'public/sc_submit',
    jsonrpc: '2.0',
    id: 1,
    params: {
      hash: txHex
    }
  })
});

```

***

## List Endpoints

### Pool List

**Method** `public/pool`

Returns a list of available pools with pagination.

**Params**

* `poolType`: `string` Specifies pool category. Available options: AMM, CLMM, STABLE.
* `page`: `number` Specifies the page number for pagination. Default: 1.
* `pageSize`: `number` Defines the number of records per page. Default: 10.

**Request:**

```json
{
  "method": "public/pool",
  "jsonrpc": "2.0",
  "id": 3,
  "params": {
    "query": {
      "poolType": "CLMM",
      "page": 1,
      "pageSize": 20
    }
  }
}
```

***

### Token List

**Method** `public/token`

Returns a list of available tokens with pagination.

**Params**

* `keyword`: `string` Ability to search by token address, name, or symbol.
* `page`: `number` Specifies the page number for pagination. Default: 1.
* `pageSize`: `number` Defines the number of records per page. Default: 10.
* `startTime`: `number` Start timestamp for filtering tokens by creation time.
* `endTime`: `number` End timestamp for filtering tokens by creation time.

**Request:**

```json
{
  "method": "public/token",
  "jsonrpc": "2.0",
  "id": 3,
  "params": {
    "query": {
      "keyword": "APT",
      "page": 1,
      "pageSize": 20,
      "startTime": 1742428856000,
      "endTime": 1742287927782
    }
  }
}
```

***

### Pool Info

**Method** `public/pool_info`

Retrieves liquidity pool information using either two token addresses or a specific pool ID. For swap transactions, users can submit two token addresses and extract the pool ID from the response.

**Params**

* `poolId`: `string` Pool unique identifier.
* `tokenAddrs`: `string[]` An array containing exactly two token addresses that define the liquidity pool.

**Request with PoolId:**

```json
{
  "method": "public/pool_info",
  "jsonrpc": "2.0",
  "id": 3,
  "params": {
    "query": {
      "poolId": "0xpool"
    }
  }
}
```

**Request with Token Address:**

```json
{
  "method": "public/pool_info",
  "jsonrpc": "2.0",
  "id": 3,
  "params": {
    "query": {
      "tokenAddrs": [
        "0xtoken0",
        "0xtoken1"
      ]
    }
  }
}
```

***

### Position

**Method** `public/position`

Retrieves a paginated list of user's liquidity positions, organized by pool. A user may have multiple positions within a single pool.

**Params**

* `userAddr`: `string` The blockchain address of the user whose positions will be retrieved.
* `page`: `number` Specifies the page number for pagination. Default: 1.
* `pageSize`: `number` Defines the number of records per page. Default: 10.

**Request:**

```json
{
  "method": "public/position",
  "jsonrpc": "2.0",
  "id": 3,
  "params": {
    "query": {
      "userAddr": "0xuser",
      "page": 1,
      "pageSize": 10
    }
  }
}
```

***

### User Transaction

**Method** `public/txns`

Retrieves a paginated list of user transactions on the platform.

**Params**

* `userAddr`: `string` The blockchain address of the user whose positions will be retrieved.
* `txType`: `string` Filters transactions by type. Available options: Swap, Add, Remove.
* `page`: `number` Specifies the page number for pagination. Default: 1.
* `pageSize`: `number` Defines the number of records per page. Default: 10.

**Request:**

```json
{
  "method": "public/txns",
  "jsonrpc": "2.0",
  "id": 3,
  "params": {
    "query": {
      "userAddr": "0xuser",
      "txType": "Add",
      "page": 1,
      "pageSize": 10
    }
  }
}
```

***

### Swap

**Method** `public/swap`

Generates a transaction payload for client signature to perform token swaps across V2, V3, and Stable pools.

#### AMM

**Params**

* `poolId`: `string` Unique identifier of the liquidity pool to use for the swap.
* `a2b`: `boolean` Set to true when swapping from token0 to token1 in the pool.
* `fixedAmountIn`: `boolean` Indicates whether the input amount will remain fixed during the swap.
* `amountIn`: `number` Quantity of input tokens to swap, denominated in microunits.
* `amountOut`: `number` Minimum quantity of output tokens expected from the swap, denominated in microunits.
* `accountAddress`: `string` Blockchain address of the transaction sender.
* `version`: `string` Specifies the pool version protocol. Available options: v2, v3, stable.

**Request:**

```json
{
  "method": "public/swap",
  "jsonrpc": "2.0",
  "id": 1,
  "params": {
    "query": {
      "poolId": "0xpool",
      "a2b": true,
      "fixedAmountIn": true,
      "amountIn": 100000000,
      "amountOut": 295873010,
      "accountAddress": "0xaccount",
      "version": "v2"
    }
  }
}
```

#### CLMM

**Params**

* `poolId`: `string` Unique identifier of the liquidity pool to use for the swap.
* `a2b`: `boolean` Set to true when swapping from token0 to token1 in the pool.
* `fixedAmountIn`: `boolean` Indicates whether the input amount will remain fixed during the swap.
* `minAmountOut`: `number` Minimum quantity of output tokens expected from the swap, denominated in microunits.
* `sqrtPrice`: `number` Target square root price for v3.
* `amountIn`: `number` Quantity of input tokens to swap, denominated in microunits.
* `accountAddress`: `string` Blockchain address of the transaction sender.
* `version`: `string` Specifies the pool version protocol. Available options: v2, v3, stable.

**Request:**

```json
{
  "method": "public/swap",
  "jsonrpc": "2.0",
  "id": 1,
  "params": {
    "query": {
      "poolId": "0xpool",
      "a2b": true,
      "fixedAmountIn": true,
      "minAmountOut": 0,
      "sqrtPrice": 4124817371235595,
      "amountIn": 100000000,
      "accountAddress": "0xaccount",
      "version": "v3"
    }
  }
}
```

#### Stable

**Params**

* `poolId`: `string` Unique identifier of the liquidity pool to use for the swap.
* `accountAddress`: `string` Blockchain address of the transaction sender.
* `tokenIn`: `number` Index of the token which wants to be sold.
* `tokenOut`: `number` Index of the token which wants to be bought.
* `amountIn`: `number` Quantity of input tokens to swap, denominated in microunits.
* `minAmountOut`: `number` Minimum quantity of output tokens expected from the swap, denominated in microunits.
* `version`: `string` Specifies the pool version protocol. Available options: v2, v3, stable.

**Request:**

```json
{
  "method": "public/swap",
  "jsonrpc": "2.0",
  "id": 1,
  "params": {
    "query": {
      "poolId": "0xpool",
      "accountAddress": "0xaccount",
      "tokenIn": 0,
      "tokenOut": 1,
      "amountIn": 100000,
      "minAmountOut": 99000,
      "version": "stable"
    }
  }
}
```

***

### Create Pool and Add Liquidity

**Method** `public/create_pool_add_liquidity`

Generates a transaction payload for client signature to create a new liquidity pool and add initial liquidity across V2, V3, and Stable pool types.

#### AMM

**Params**

* `version`: `string` Specifies the pool version protocol. Available options: v2, v3, stable.
* `accountAddress`: `string` Blockchain address of the transaction sender.
* `coins`: `string[]` Token addresses that will form the liquidity pool.
* `amounts`: `string[]` Quantities of each token to add as initial liquidity.
* `minAmounts`: `string[]` Minimum quantities each token to add as initial liquidity.
* `fee`: `number` Fee tier for the pool. Available options: 100 (0.01%), 500 (0.05%), 3000 (0.3%), 10000 (1%).

**Request:**

```json
{
  "method": "public/create_pool_add_liquidity",
  "jsonrpc": "2.0",
  "id": 1,
  "params": {
    "query": {
      "version": "v2",
      "accountAddress": "0xaccount",
      "coins": [
        "0xcoin0",
        "0xcoin1"
      ],
      "amounts": [
        "100000",
        "200000"
      ],
      "minAmounts": [
        "0",
        "0"
      ],
      "fee": 10000
    }
  }
}
```

#### CLMM

**Params**

* `version`: `string` Specifies the pool version protocol. Available options: v2, v3, stable.
* `accountAddress`: `string` Blockchain address of the transaction sender.
* `coins`: `string[]` Token addresses that will form the liquidity pool.
* `amounts`: `string[]` Quantities of each token to add as initial liquidity.
* `minAmounts`: `string[]` Minimum quantities each token to add as initial liquidity.
* `fee`: `number` Fee tier for the pool. Available options: 100 (0.01%), 500 (0.05%), 3000 (0.3%), 10000 (1%).
* `sqrtPrice`: `string` Initial square root price of the pool.
* `lowerTick`: `string` Lower tick boundary of the price range.
* `upperTick`: `string` Upper tick boundary of the price range
* `fixedAmountA`: `boolean` Indicator whether the first token amount remains fixed during position creation.

**Request:**

```json
{
  "method": "public/create_pool_add_liquidity",
  "jsonrpc": "2.0",
  "id": 1,
  "params": {
    "query": {
      "version": "v3",
      "accountAddress": "0xaccount",
      "coins": [
        "0xcoin0",
        "0xcoin1"
      ],
      "amounts": [
        "100000",
        "200000"
      ],
      "minAmounts": [
        "0",
        "0"
      ],
      "fee": 10000,
      "sqrtPrice": "4124817371235595",
      "lowerTick": "0",
      "upperTick": "23040",
      "fixedAmountA": true
    }
  }
}
```

#### Stable

**Params**

* `version`: `string` Specifies the pool version protocol. Available options: v2, v3, stable.
* `accountAddress`: `string` Blockchain address of the transaction sender.
* `coins`: `string[]` Token addresses that will form the liquidity pool.
* `amounts`: `string[]` Quantities of each token to add as initial liquidity.
* `fee`: `number` Fee tier for the pool. Available options: 100 (0.01%), 500 (0.05%), 3000 (0.3%), 10000 (1%).
* `amplification`: `string` Between 100 to max 1000.
* `offPegMultiplier`: `string` Off peg multiplier.
* `minMintAmount`: `string` Minimum minted LP amount.

**Request:**

```json
{
  "method": "public/create_pool_add_liquidity",
  "jsonrpc": "2.0",
  "id": 1,
  "params": {
    "query": {
      "version": "stable",
      "accountAddress": "0xaccount",
      "coins": [
        "0xcoin0",
        "0xcoin1"
      ],
      "amounts": [
        "100000",
        "200000"
      ],
      "fee": 10000,
      "amplification": "1000",
      "offPegMultiplier": "20000000000",
      "minMintAmount": "0"
    }
  }
}
```

***

### Add Liquidity

**Method** `public/add_liquidity`

Generates a transaction payload for client signature to add liquidity across V2, V3, and Stable pool types.

#### AMM

**Params**

* `version`: `string` Specifies the pool version protocol. Available options: v2, v3, stable.
* `poolId`: `string` Unique identifier for the liquidity pool.
* `accountAddress`: `string` Blockchain address of the transaction sender.
* `amounts`: `string[]` Quantities of each token to add as initial liquidity.
* `minAmounts`: `string[]` Minimum quantities each token to add as initial liquidity.

**Request:**

```json
{
  "method": "public/add_liquidity",
  "jsonrpc": "2.0",
  "id": 1,
  "params": {
    "query": {
      "version": "v2",
      "poolId": "0xpool",
      "accountAddress": "0xaccount",
      "amounts": [
        "100000",
        "200000"
      ],
      "minAmounts": [
        "0",
        "0"
      ]
    }
  }
}
```

#### CLMM

**Params**

* `version`: `string` Specifies the pool version protocol. Available options: v2, v3, stable.
* `poolId`: `string` Unique identifier for the liquidity pool.
* `accountAddress`: `string` Blockchain address of the transaction sender.
* `amounts`: `string[]` Quantities of each token to add as initial liquidity.
* `minAmounts`: `string[]` Minimum quantities each token to add as initial liquidity.
* `lowerTick`: `string` Lower tick boundary of the price range.
* `upperTick`: `string` Upper tick boundary of the price range
* `fixedAmountA`: `boolean` Indicator whether the first token amount remains fixed during position creation.

**Request:**

```json
{
  "method": "public/add_liquidity",
  "jsonrpc": "2.0",
  "id": 1,
  "params": {
    "query": {
      "version": "v3",
      "poolId": "0xpool",
      "accountAddress": "0xaccount",
      "amounts": [
        "100000",
        "200000"
      ],
      "minAmounts": [
        "0",
        "0"
      ],
      "lowerTick": "0",
      "upperTick": "23040",
      "fixedAmountA": true
    }
  }
}
```

#### Stable

**Params**

* `version`: `string` Specifies the pool version protocol. Available options: v2, v3, stable.
* `poolId`: `string` Unique identifier for the liquidity pool.
* `accountAddress`: `string` Blockchain address of the transaction sender.
* `amounts`: `string[]` Quantities of each token to add as initial liquidity.
* `minMintAmount`: `string` Minimum minted LP amount.

**Request:**

```json
{
  "method": "public/add_liquidity",
  "jsonrpc": "2.0",
  "id": 1,
  "params": {
    "query": {
      "version": "stable",
      "poolId": "0xpool",
      "accountAddress": "0xaccount",
      "amounts": [
        "100000",
        "200000"
      ],
      "minMintAmount": "0"
    }
  }
}
```

***

### Remove Liquidity

**Method** `public/remove_liquidity`

Generates a transaction payload for client signature to remove liquidity across V2, V3, and Stable pool types.

#### AMM

**Params**

* `version`: `string` Specifies the pool version protocol. Available options: v2, v3, stable.
* `poolId`: `string` Unique identifier for the liquidity pool.
* `accountAddress`: `string` Blockchain address of the transaction sender.
* `positionAddress`: `string` The on-chain address identifier of the specific liquidity position to be withdrawn.
* `minAmounts`: `string[]` Minimum token amounts to receive when removing liquidity, protecting against slippage.
* `burnedShare`: `string` Amount of liquidity provider (LP) tokens or shares to burn/remove from the pool.

**Request:**

```json
{
  "method": "public/remove_liquidity",
  "jsonrpc": "2.0",
  "id": 1,
  "params": {
    "query": {
      "version": "v2",
      "poolId": "0xpool",
      "accountAddress": "0xaccount",
      "positionAddress": "0xposition",
      "minAmounts": [
        "100000",
        "200000"
      ],
      "burnedShare": "14620"
    }
  }
}
```

#### CLMM

**Params**

* `version`: `string` Specifies the pool version protocol. Available options: v2, v3, stable.
* `poolId`: `string` Unique identifier for the liquidity pool.
* `accountAddress`: `string` Blockchain address of the transaction sender.
* `positionAddress`: `string` The on-chain address identifier of the specific liquidity position to be withdrawn.
* `minAmounts`: `string[]` Minimum token amounts to receive when removing liquidity, protecting against slippage.
* `burnedShare`: `string` Amount of liquidity provider (LP) tokens or shares to burn/remove from the pool.

**Request:**

```json
{
  "method": "public/remove_liquidity",
  "jsonrpc": "2.0",
  "id": 1,
  "params": {
    "query": {
      "version": "v3",
      "poolId": "0xpool",
      "accountAddress": "0xaccount",
      "positionAddress": "0xposition",
      "minAmounts": [
        "100000",
        "200000"
      ],
      "burnedShare": "14620"
    }
  }
}
```

#### Stable

**Params**

* `version`: `string` Specifies the pool version protocol. Available options: v2, v3, stable.
* `poolId`: `string` Unique identifier for the liquidity pool.
* `accountAddress`: `string` Blockchain address of the transaction sender.
* `positionAddress`: `string` The on-chain address identifier of the specific liquidity position to be withdrawn.
* `minAmounts`: `string[]` Minimum token amounts to receive when removing liquidity, protecting against slippage.
* `burnedShare`: `string` Amount of liquidity provider (LP) tokens or shares to burn/remove from the pool.
* `type`: `number` type 1 = remove\_liquidity\_one\_coin, type 2 =remove\_liquidity\_imbalance, type 3 = remove\_liquidity\_ratio.

**Request for stable:**

```json
{
  "method": "public/remove_liquidity",
  "jsonrpc": "2.0",
  "id": 1,
  "params": {
    "query": {
      "version": "v3",
      "poolId": "0xpool",
      "accountAddress": "0xaccount",
      "positionAddress": "0xposition",
      "minAmounts": [
        "100000",
        "200000"
      ],
      "burnedShare": "14620",
      "type": 1
    }
  }
}
```

***

### Remove Multi Liquidity

**Method** `public/remove_multi_liquidity`

Generates a transaction payload for client signature to remove multiple liquidities across V2, V3, and Stable pool types.

#### AMM

**Params**

* `version`: `string` Specifies the pool version protocol. Available options: v2, v3, stable.
* `poolId`: `string` Unique identifier for the liquidity pool.
* `accountAddress`: `string` Blockchain address of the transaction sender.
* `positions`: An array of objects, each describing a position with:
  * `positionAddress`: `string` The on-chain address identifier of the specific liquidity position to be withdrawn.
  * `minAmounts`: `string[]` Minimum token amounts to receive when removing liquidity, protecting against slippage.
  * `burnedShare`: `string` Amount of liquidity provider (LP) tokens or shares to burn/remove from the pool.

**Request:**

```json
{
  "method": "public/remove_multi_liquidity",
  "jsonrpc": "2.0",
  "id": 1,
  "params": {
    "query": {
      "version": "v2",
      "poolId": "0xpool",
      "accountAddress": "0xaccount",
      "positions": [
        {
          "positionAddress": "0xposition",
          "minAmounts": [
            "100000",
            "200000"
          ],
          "burnedShare": "14620"
        }
      ]
    }
  }
}
```

#### CLMM

**Params**

* `version`: `string` Specifies the pool version protocol. Available options: v2, v3, stable.
* `poolId`: `string` Unique identifier for the liquidity pool.
* `accountAddress`: `string` Blockchain address of the transaction sender.
* `positions`: An array of objects, each describing a position with:
  * `positionAddress`: `string` The on-chain address identifier of the specific liquidity position to be withdrawn.
  * `minAmounts`: `string[]` Minimum token amounts to receive when removing liquidity, protecting against slippage.
  * `burnedShare`: `string` Amount of liquidity provider (LP) tokens or shares to burn/remove from the pool.

**Request:**

```json
{
  "method": "public/remove_multi_liquidity",
  "jsonrpc": "2.0",
  "id": 1,
  "params": {
    "query": {
      "version": "v3",
      "poolId": "0xpool",
      "accountAddress": "0xaccount",
      "positions": [
        {
          "positionAddress": "0xposition",
          "minAmounts": [
            "100000",
            "200000"
          ],
          "burnedShare": "14620"
        }
      ]
    }
  }
}
```

#### Stable

**Params**

* `version`: `string` Specifies the pool version protocol. Available options: v2, v3, stable.
* `poolId`: `string` Unique identifier for the liquidity pool.
* `accountAddress`: `string` Blockchain address of the transaction sender.
* `positions`: An array of objects, each describing a position with:
  * `positionAddress`: `string` The on-chain address identifier of the specific liquidity position to be withdrawn.
  * `minAmounts`: `string[]` Minimum token amounts to receive when removing liquidity, protecting against slippage.
  * `burnedShare`: `string` Amount of liquidity provider (LP) tokens or shares to burn/remove from the pool.
  * `type`: `number` type 1 = remove\_liquidity\_one\_coin, type 2 =remove\_liquidity\_imbalance, type 3 = remove\_liquidity\_ratio.

**Request:**

```json
{
  "method": "public/remove_multi_liquidity",
  "jsonrpc": "2.0",
  "id": 1,
  "params": {
    "query": {
      "version": "stable",
      "poolId": "0xpool",
      "accountAddress": "0xaccount",
      "positions": [
        {
          "positionAddress": "0xposition",
          "minAmounts": [
            "100000",
            "200000"
          ],
          "burnedShare": "14620",
          "type": 1
        }
      ]
    }
  }
}
```

***

### Collect Fee

**Method** `public/collect_fee`

Generates a transaction payload for client signature to collect fees for V3 pool type.

**Params**

* `version`: `string` Specifies the pool version protocol. Must be V3 for this operation.
* `poolId`: `string` Unique identifier for the liquidity pool.
* `accountAddress`: `string` The blockchain address of the account.
* `positionAddress`: `string` The on-chain address identifier of the specific liquidity position to be withdrawn.

**Request:**

```json
{
  "method": "public/collect_fee",
  "jsonrpc": "2.0",
  "id": 1,
  "params": {
    "query": {
      "version": "v3",
      "poolId": "0xpool",
      "accountAddress": "0xaccount",
      "positionAddress": "0xposition"
    }
  }
}
```
