# Subgraph interactions

Toucan SDK offers a lot of pre-defined queries. Try them out! If you don't find what you are looking for, you can also [create a custom query](#custom-queries).

## fetchTokenPriceOnDex

The `fetchTokenPriceOnDex` function fetches the price of a token on a DEX (decentralized exchange).

```typescript
function fetchTokenPriceOnDex(pool: PoolSymbol): Promise<TokenPrice>;
```

#### Params

| Name   | Type                    | Description                           |
| ------ | ----------------------- | ------------------------------------- |
| `pool` | `PoolSymbol` e.g. `NCT` | The pool token to fetch the price for |

## fetchUserBatches

The `fetchUserBatches` function fetches up to 100 batches owned by user. It returns an array of objects with different properties of the each batch.

```typescript
function fetchUserBatches(walletAddress: string): Promise<Batch[]>;
```

#### Params

| Name            | Type     | Description                                  |
| --------------- | -------- | -------------------------------------------- |
| `walletAddress` | `string` | The address of the user to fetch batches for |

#### Return Values

The query returns an array of objects, each with a batch's `id`, `tx`, `serialNumber`, `quantity`, `confirmationStatus`, `comments` and `creator`.

## fetchTCO2TokenById

The `fetchTCO2TokenById` function fetches the TCO2 token by its ID. It returns a TCO2 Detail object with properties of the TCO2 (name, address, etc).

```typescript
function fetchTCO2TokenById(id: string): Promise<TCO2Token | undefined>;
```

#### Params

| Name | Type     | Description                                                                                                                    |
| ---- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `id` | `string` | ID of the TCO2 to query for; the id happens to be the same as the address e.g.: `"0x004090eef602e024b2a6cb7f0c1edda992382994"` |

## fetchTCO2TokenByFullSymbol

The `fetchTCO2TokenByFullSymbol` function fetches properties of a TCO2 token contract by its full symbol. It returns a `TCO2Detail` object with properties of the TCO2, including `id`, `name`, `symbol`, `address`, and `projectVintage` details.

```typescript
function fetchTCO2TokenByFullSymbol(
  symbol: string
): Promise<TCO2Token | undefined>;
```

#### Params

| Name         | Type     | Description                                                               |
| ------------ | -------- | ------------------------------------------------------------------------- |
| `fullSymbol` | `string` | Full symbol of the TCO2 token to be fetched, e.g.: `"TCO2-VCS-1718-2013"` |

## fetchAllTCO2Tokens

The `fetchAllTCO2Tokens` function fetches TCO2 details of all TCO2 tokens. It returns array of TCO2 Detail objects with properties of the TCO2s, including `id`, `name`, `symbol`, `address`, and `projectVintage` details.

```typescript
function fetchAllTCO2Tokens(): Promise<TCO2Token[]>;
```

## fetchBridgedBatchTokens

The `fetchBridgedBatchTokens` function fetches data about BatchTokens that have been bridged. It returns an array of BatchTokens containing different properties like id, serialNumber or quantity. The `BatchToken` objects returned include `id`, `serialNumber`, `quantity`, `creator`, `timestamp` and `tx`.

```typescript
function fetchBridgedBatchTokens(): Promise<BridgedBatchToken[]>;
```

## fetchUserRetirements

The `fetchUserRetirements` function fetches all retirements made by a user. It returns an array of objects containing retirement properties like `id`, `creationTx`, `amount`, `token` details, `certificate` details and more.

```typescript
function fetchUserRetirements(
  walletAddress,
  first = 100,
  skip = 0
): Promise<Retirement[]>;
```

#### Params

| Name            | Type     | Description                                                   |
| --------------- | -------- | ------------------------------------------------------------- |
| `walletAddress` | `string` | The address of the user to fetch retirements                  |
| `first`         | `number` | How many retirements you want fetched; defaults to 100        |
| `skip`          | `number` | How many (if any) retirements you want skipped; defaults to 0 |

## fetchRedeems

Fetches redemptions from a given pool. It returns an array of objects with properties of the redeems like `id`, `amount`, `timestamp` and more.

```typescript
function fetchRedeems(
  pool: PoolSymbol,
  first = 100,
  skip = 0
): Promise<RedeemEvent[]>;
```

#### Params

| Name    | Type                    | Description                                               |
| ------- | ----------------------- | --------------------------------------------------------- |
| `pool`  | `PoolSymbol` e.g. `NCT` | The pool token to fetch the price for                     |
| `first` | `number`                | How many redeems you want fetched; defaults to 100        |
| `skip`  | `number`                | How many (if any) redeems you want skipped; defaults to 0 |

## fetchUserRedeems

The `fetchUserRedeems` function fetches all redeems from a given pool by a specific user. It returns an array of objects with properties of the redeems like `id`, `amount`, `timestamp` and more.

```typescript
function fetchUserRedeems(
  walletAddress: string,
  pool: PoolSymbol,
  first = 100,
  skip = 0
): Promise<RedeemEvent[]>;
```

#### Params

| Name            | Type                    | Description                                               |
| --------------- | ----------------------- | --------------------------------------------------------- |
| `walletAddress` | `string`                | The address of the user to query for                      |
| `pool`          | `PoolSymbol` e.g. `NCT` | The pool token to fetch the user redeems for              |
| `first`         | `number`                | How many redeems you want fetched; defaults to 100        |
| `skip`          | `number`                | How many (if any) redeems you want skipped; defaults to 0 |

`Promise<RedeemEvent[]>`: An array of all redeem events for the specified user.

## fetchPoolContents

The `fetchPoolContents` function fetches TCO2 tokens that are part of the given pool. It returns an array of objects representing TCO2 tokens and containing properties like `name`, `amount`, `methodology` and more.

```typescript
function fetchPoolContents(
  pool: PoolSymbol,
  first = 1000,
  skip = 0
): Promise<PoolContent[]>;
```

#### Params

| Name    | Type                    | Description                                                                |
| ------- | ----------------------- | -------------------------------------------------------------------------- |
| `pool`  | `PoolSymbol` e.g. `NCT` | The pool to fetch the contents of                                          |
| `first` | `number`                | How many TCO2 tokens you want fetched; defaults to 1000 (i.e. all of them) |
| `skip`  | `number`                | How many (if any) TCO2 tokens you want skipped; defaults to 0              |

## fetchProjectById

The `fetchProjectById` function fetches the project by its Toucan ID (not `projectId`!). The query returns an object with properties of the Project like `projectId`, `region`, standard and more.

{% hint style="info" %}
The Toucan ID refers to the token ID in [Toucan's Carbon Projects contract](https://polygonscan.com/token/0x599a978c43F5cEa1B26a399D28869Ad4690DC07d).
{% endhint %}

```typescript
function fetchProjectById(id: string): Promise<Project | undefined>;
```

#### Params

| Name | Type     | Description                                          |
| ---- | -------- | ---------------------------------------------------- |
| `id` | `string` | Toucan ID of the project to be fetched, e.g.: `"10"` |

## fetchAggregations

The `fetchAggregations` function fetches all protocol-wide aggregations, including, for example, `tco2TotalRetired`, `totalProjectsTokenized`, or `totalCarbonBridged`. It returns an array of Aggregation objects containing properties like `id`, `key`, `value`.

```typescript
function fetchAggregations(): Promise<Aggregation[]>;
```

`RegistryContract`: The registry contract instance.

## Custom queries

In case you don't find what you are looking for in the pre-build queries, you can create your own with the `fetchCustomQuery` method.

This allows you to fetch with your own queries and can be very powerful if you know GraphQL. You can also check out various example queries in our subgraph [playgrounds](/developers/subgraph.md#playground).

#### Example: Getting all infos on a project on a Carbon Credit

* `region` stands for the country

```typescript
import { gql } from "@urql/core";

const query = gql`
  query ($id: String) {
    project(id: $id) {
      projectId
      region
      standard
      methodology
      vintages {
        id
      }
    }
  }
`;

const result = await toucan.fetchCustomQuery(query, { id: "1" });
```


---

# 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://docs.toucan.earth/developers/sdk/subgraph-interactions.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.