The ECO carbon retirement API simplifies interacting with on-chain carbon markets by facilitating seamless, atomic purchase and retirement of a growing number of supported tokenized carbon offsets.
Programmatic Retirement Lifecycle
To complete the atomic retirement of an arbitrary amount of carbon, you must implement the following programmatic lifecycle:
id of the Network where the retire carbon smart contract and designated pool and source token assets are deployed
description
String
internal description summarizing the carbon retirement
value*
Float
the amount of carbon to purchase and retire, in metric tons, when retire_by is carbon, or the human-readable amount of source token to spend to complete the retirement when retire_by is source
source_token_contract_address
String
contract address of the asset being used to purchase and retire the specified value in pool token on behalf of the named beneficiary; defaults to the network-specific USDC contract address
pool_token_contract_address*
String
contract address of the carbon offset pool token, with value amount specified in carbon or source token, being purchased and retired on behalf of the named beneficiary
beneficiary_address*
String
address of the named beneficiary of the retired carbon
beneficiary_name*
String
human-readable name of the entity or individual associated with the given beneficiary_address
retirement_message
String
optional on-chain description summarizing the carbon retirement
project_token_contract_address
String
contract address of the carbon project token, with value amount specified in carbon or source token, being purchased and retired on behalf of the named beneficiary
max_source_bid
Float
the maximum bid, specified as the human-readable amount of source token, to spend when attempting to purchase and retire the specified value; this parameter is required when retire_by is carbon
retire_by
String
if provided, must be set to carbon or source
{"id":"90638fe9-1433-4a09-89c6-4585ffde8ddf","created_at":"2023-07-05T17:22:05.879751777Z","application_id":"00000000-0000-0000-0000-000000000000","organization_id":"00000000-0000-0000-0000-000000000000","user_id":"40bc70bf-1140-4978-99bc-b8b800672842","network_id":"2fd61fde-5031-41f1-86b8-8a72e2945ead", "data": "c8b9467e0000000000000000000000002791bca1f2de4661ed88a30c99a7a9449aa841740000000000000000000000002f800db0fdb5223b3c3f354886d907a671414a7f000000000000000000000000225b28c1a77fd4493196db19c538a44801243537000000000000000000000000000000000000000000000000000000000000343a00000000000000000000000000000000000000000000000000000000000001200000000000000000000000001480320db0aa1bbef15f847981e28776e7d2c442000000000000000000000000000000000000000000000000000000000000016000000000000000000000000000000000000000000000000000000000000001a00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000750726f7669646500000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000750726f7669646500000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000003048656c6c6f2066726f6d207468652050726f766964652045434f20636172626f6e207265746972656d656e742041504900000000000000000000000000000000",
"hashed_data":"92437f706229414c6099d133f0a404dd9561dd5165e6b4055e635823ad438c75","provider":"klima","tx_hash":null,"pool_token_contract_address":"0x2f800db0fdb5223b3c3f354886d907a671414a7f","source_token_contract_address":"0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174","project_token_contract_address":"0x225b28c1a77fd4493196db19c538a44801243537","beneficiary_address":"0x1480320Db0aa1Bbef15f847981E28776E7D2c442","beneficiary_name":"Provide","description":"Hello from the Provide ECO carbon retirement API","retire_by":"source","retirement_message":"Hello from the Provide ECO carbon retirement API","value":0.01337}
Sign
After creating a parameterized request that can be used to retire the specified amount of carbon, the transaction needs to be signed. We designed the API in this manner to ensure users can enable self-custody in their implementations. The signature over the transaction data returned by the parameterize request provides flexibility for (i) broadcasting the transaction and bearing the network transaction costs or (ii) leveraging the Managed Transactions API to broadcast the transaction while maintaining the ability to verify the original signer (e.g., by using ecrecover).
Broadcast
This final step in the process to programmatically retire carbon enables flexibility in systems and applications that would otherwise struggle to assemble, encode and broadcast transactions to the targeted network. The broadcast API accepts the unsigned data as returned by the Parameterize call and a hex-encoded signature.
The following code demonstrates how to broadcast parameterized and signed ECO transactions:
The broadcast method provides guarantees around atomicity and double-spend protection, ensuring each parameterized carbon retirement request is only executed once. Subsequent attempts to broadcast the same request will fail with a 422 status code. Here is an example response to an API call attempting to retire a parameterized transaction:
{"message":"retire carbon request has already been broadcast; tx hash: 584205679a00025e927fc24ef0a3a5e726017392395e7d027b3936d7e644d0ca"}
Fetch Carbon Retirement
You can retrieve details related to an existing RetireCarbonRequest, including links to generated certificates and verifiable credentials, if applicable.
Retrieve details related to an existing retire carbon request
id of the RetireCarbonRequest for which to retrieve details
{"id": "90638fe9-1433-4a09-89c6-4585ffde8ddf","created_at": "2023-07-05T17:22:05.879752Z","application_id": "00000000-0000-0000-0000-000000000000","organization_id": "00000000-0000-0000-0000-000000000000","user_id": "40bc70bf-1140-4978-99bc-b8b800672842","network_id": "2fd61fde-5031-41f1-86b8-8a72e2945ead","provider": "klima","tx_hash": "0xc93d7ce4c67a238fb1a2b83d607405798b7ec20e3e5bad7f824af80783338f7c","pool_token_contract_address": "0x2f800db0fdb5223b3c3f354886d907a671414a7f","source_token_contract_address": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174","project_token_contract_address": "0x225b28c1a77fd4493196db19c538a44801243537","beneficiary_address": "0x1480320Db0aa1Bbef15f847981E28776E7D2c442","beneficiary_name": "Provide","description": "Hello from the Provide ECO carbon retirement API","retire_by": "source","retirement_message": "Hello from the Provide ECO carbon retirement API","value": 0.01337,"certificate_href": "https://www.carbonmark.com/en/retirements/0x1480320Db0aa1Bbef15f847981E28776E7D2c442/3","certificate_href_alt": "https://klimadao.finance/en/retirements/0x1480320Db0aa1Bbef15f847981E28776E7D2c442/3"}
Note that the returned RetireCarbonRequest details will contain a non-null tx_hash and cardinality if the request has been successfully broadcast to the network for settlement. The returned cardinality represents the serial position of the completed carbon retirement for the provider for the associated beneficiary_address.
Similarly, the certificate_href and verifiable_credentials_href fields will only be included in the response if the underlying RetireCarbonRequest has been successfully retired and the provider supports those resources on the settlement network.
Some provider implementations may support an additional certificate_href_alt field.
An integrated code sample will be provided here shortly. You can see how we leverage the to sign transactions for EVM-based networks .
