# API Documentation

By visiting the API endpoint in your browser, you can explore all available queries, mutations, and types directly.

We will focus here on the core concepts and integration basics.

### Endpoints

The API provides two environments: **Mainnet** for production use and **Preview** for testing.<br>

**Mainnet**

```
https://v2.api.liqwid.finance/graphql
```

**Preview**

```
https://v2.api.preview.liqwid.dev/graphql
```

***

### Request Headers

When making requests to the API, please include the following header to help us identify your application:

```
X-App-Source: <app-name>
```

***

### Get Basic Markets

```
query GetBasicMarket($input: MarketsInput) {
  liqwid {
    data {
      markets(input: $input) {
        page
        pagesCount
        perPage
        totalCount
        results {
          id
          displayName
          supplyAPY
          borrowAPY
          lqSupplyAPY
          batching
          private
          delisting
          exchangeRate
          receiptAsset {
            currencySymbol
          }
          asset {
            price
            logo
            decimals
            currencySymbol
            hexName
          }
        }
      }
    }
  }
}
```

#### Input

```
{
  "input": {
    "perPage": 20,
    "page": 0
  }
}
```

`perPage` defaults to **20**. If you need more items per request, set a higher `perPage`, or iterate pages .

| Field                                           | Type         | Description                                                                                                                                         |
| ----------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                                              | String       | Unique market identifier                                                                                                                            |
| displayName                                     | String       | Prettified market name as displayed in Liqwid. E.g: USDC → wanUSDC.                                                                                 |
| **supplyAPY** / **borrowAPY** / **lqSupplyAPY** | Number       | Annual percentage yield values in decimal form. Multiply by `100` to get the percentage.                                                            |
| batching                                        | Boolean      | Indicates whether batching is currently happening. If `true`, you cannot interact with the market.                                                  |
| private                                         | Boolean      | If `true`, the market is private and you cannot interact with it.                                                                                   |
| delisting                                       | Boolean      | If `true`, the market is being removed. You cannot supply, only repay or withdraw.                                                                  |
| exchangeRate                                    | Number       | Used to convert qTokens to the underlying asset. Multiply this value by the number of qTokens a user holds to get the equivalent in the base asset. |
| receiptAsset.currencySymbol                     | String       | PolicyId of the qToken associated with this market.                                                                                                 |
| asset.price                                     | Number       | Price of the asset in USD.                                                                                                                          |
| asset.logo                                      | String (URL) | URL to the asset’s logo image.                                                                                                                      |
| asset.decimals                                  | Number       | Number of decimal places for the asset                                                                                                              |
| asset.currencySymbol                            | String       | PolicyId of the asset                                                                                                                               |
| asset.hexName                                   | String       | Asset name in hexadecimal format                                                                                                                    |

***

### Build a Supply Transaction

```
query GetSupplyTransactionCBOR($input: SupplyTransactionInput!) {
  liqwid {
    transactions {
      supply(input: $input) {
        cbor
      }
    }
  }
}
```

#### Input

```
{
  "input": {
    "marketId": "",
    "amount": 0,
    "address": "",
    "changeAddress": "",
    "otherAddresses": [""],
    "utxos": [""]
  }
}
```

| Input field    | Type      | Description                                                                                                                                                                   |
| -------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| marketId       | String    | The market identifier. Equals `markets.results[X].id`.                                                                                                                        |
| amount         | Number    | Amount **in base units** (no decimals). If you’re pretty-printing amounts, convert back with `amountBase = amount * 10 ** markets.results.asset.decimals`.                    |
| address        | String    | Your **main payment address** (the first from [`walletApi.getUsedAddresses()`](https://cips.cardano.org/cip/CIP-30?utm_source=chatgpt.com)), prettified as a Bech32 `addr1…`. |
| changeAddress  | String    | Address that will receive the change for this tx (usually the same main address). Bech32 `addr1…`.                                                                            |
| otherAddresses | String\[] | <p>All your addresses (Bech32 <code>addr1…, getUsedAddresses,</code></p><p><code>getUnusedAddresses</code>).</p>                                                              |
| utxos          | String\[] | Returns the UTXOs of your wallet as returned by `walletApi.getUtxos()`.                                                                                                       |

#### What you receive & how to submit

The resolver returns a **CBOR** transaction body (`cbor`) ready to be **signed** and **submitted**.

Option A — Submit via your wallet (CIP-30)

Option B — Submit via our API

```
mutation SubmitTransaction($input: SubmitTransactionInput!) {
  submitTransaction(input: $input)
}
```

#### Input

```
{
  "input": {
    "signature": "",
    "transaction": ""
  }
}
```

* **signature** — the result of `signTx()`
* **transaction** — the unsigned transaction CBOR you received from our `supply` query

***

### Build a Withdraw Transaction

```
query GetWithdrawTransactionCBOR($input: WithdrawTransactionInput!) {
  liqwid {
    transactions {
      withdraw(input: $input) {
        cbor
      }
    }
  }
}
```

#### Input

```
{
  "input": {
    "marketId": "",
    "amount": 0,
    "address": "",
    "changeAddress": "",
    "otherAddresses": [],
    "utxos": []
  }
}
```

#### Input fields (same as [**supply**](#input-1), except `amount`)

All other input fields follow exactly the same rules as for **supply**:\
`marketId`, `address`, `changeAddress`, `otherAddresses`, and `utxos`.

#### `amount` for withdraw

* The user **holds qTokens**, but `withdraw.amount` expects the **asset amount in base units (no decimals)**.
* If your UI works in **qTokens**, convert to **asset units** with the market’s `exchangeRate`, then to **base units** using `decimals`.

***

### Custom Fees

If you need to add a **specific fee** for a transaction or integration, please create a support ticket in our [Discord](https://discord.gg/PZ3GUWamY8).

***

### Issues & Complex Integrations

If you encounter any **issues** or require help with a **more complex integration**, please create a support ticket in our [Discord](https://discord.gg/PZ3GUWamY8).


---

# 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://liqwid-labs.gitbook.io/liqwid-docs/api-documentation.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.