Quickstart a project with carbon retirements with a few lines of code

Setting up the client

Instantiate the ToucanClient and set a signer & provider to interact with our smart contracts.

We recommend using to use ethers.js ^5.6.4 for the signer and provider.

Read the ethers.js Signer docs ->


Celo Mainnet


Celo Alfajores Testnet


Polygon Mainnet


Polygon Mumbai Testnet


import ToucanModule from "toucan-sdk";
import { ethers } from "ethers";

const ToucanClient = ToucanModule.default;

// ethers signer and provider
const provider = new ethers.providers.JsonRpcProvider(

// make sure to set your private key in your .env file
const signer = new ethers.Wallet(process.env.PRIVATE_KEY, provider);

// set signer & provider
const toucan = new ToucanClient("polygon", provider, signer);

You could also set the signer and / or provider later if you prefer that, they are optional — but you will need to set them if you want to interact with contracts. The provider is read-only, while the signer allows both writing to and reading from the blockchain.

import ToucanClient from "toucan-sdk";

const toucan = new ToucanClient("polygon");

If you don't have a signer or a provider set, you can still interact with the subgraph.

Retire Carbon Credits

To retire carbon credits on mainnet, you will need to have TCO2 tokens in your account. These can be acquired by buying carbon reference tokens from a DEX like Uniswap, then redeeming the reference tokens for TCO2s. You can then retire these TCO2 tokens through the Toucan app UI, or programmatically with the ToucanClient.retire() method.

If you already own NCT tokens, you can follow this example. Get your test tokens at the Toucan Faucet. You can find more ways to retire, and mint RetirementCertificates, in this list of all SDK functions.

Redeem your Pool Tokens and get an array of redeemed TCO2s

const tco2addresses = await toucan.redeemAuto("NCT", parseEther("1"));

Retire the TCO2 tokens

await toucan.retire(parseEther("1"), tco2addresses[0].address);

Offset Carbon Credits with the OffsetHelper

The functions in the OffsetHelper will bundle the following steps into a single transaction:

  • Exchange ERC20 tokens e.g., cUSD or USDC for pool tokens (e.g., NCT) at a DEX like Uniswap or SushiSwap, etc. (depending on the network)

  • Interact with the pool contract to redeem the tokens for TCO2

  • Interact with the TCO2 token contract to retire the TCO2 the amount purchased and redeemed

Note that if you're using the swap functionality, the exact number of TCO2 tokens retired will depend on the stablecoin : reference token exchange rate, which can vary moment to moment.

Using these functions, you can easily offset TCO2 tokens using other cryptocurrencies and stablecoins. Bear in mind that using these functions will not let you choose a specific project to retire. To specify your the project you want to retire, you'd need to use the redeemMany function, which is not supported by the OffsetHelper at this point.

const cUSD = "0x765DE816845861e75A25fCA122bb6898B8B1282a";
const tx = await toucan.autoOffsetExactInToken(cUSD, "NCT", parseEther("0.01"));

Last updated