Subgraph interactions

SDK functions to read from the Toucan subgraph

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.

fetchTokenPriceOnDex

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

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

The Toucan ID refers to the token ID in Toucan's Carbon Projects contract.

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.

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.

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

• region stands for the country

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" });