Retire Carbon
Initiate carbon retirements via a REST endpoint
Last updated
Initiate carbon retirements via a REST endpoint
Last updated
In the code examples below we use as the base URL, however, when consuming our API, be sure to prefix the API URL with a version number. For example, the base URL of version 1 would be v1.api.carbonmark.com
.
Any changes that we make to an API version are guaranteed to be backwards compatible. However, if you omit the version prefix () your application will be exposed to breaking changes because is always routed to the latest major version.
Carbonmark's API offers developers a path to initiate carbon retirements via a REST endpoint. Follow the guide below to get started:
In this guide, you will learn to:
Get access to the Carbonmark developer dashboard and get your API Key
Find a project or index product to retire
Identify the listing details
Create a quote
Create an order
Confirm carbon credit retirement
Create an account or login with your existing Carbonmark account on our .
Once logged in, visit the page to generate an API key.
You can create Test API
key's for free in a Sandbox environment. These can be used to test the API endpoints and for development access.
When you are ready to access paid Production API
key's, to be white-listed and complete onboarding.
The API Key is sensitive and can be used to create costly retirements on your behalf.
Be careful not to expose the API Key or commit it to your repository.
Note that you can create a sandbox key
for testing purposes.
Keys are generated once and not exposed in the Developer Dashboard so you must copy them to be utilized.
The /carbonProjects
endpoint allows you to retrieve an array of carbon projects filtered by desired query parameters and returns project metadata and prices. Make note of the "key
" (for example, VCS-191) of the project you are interested in.
The /products
endpoint allows you to retrieve an array of carbon index products filtered by desired query parameters and returns products metadata and prices. Make note of the "id
" (for example, mco2) of the product you are interested in.
You can also check out our various guides to discovering carbon projects or index products via our REST API.
A header is required to provide the Authorization
bearer token. The required parameters for a quote are asset_price_source_id
and quantity_tonnes
.
This is a response example, note the uuid
which will be required to generate an order.
A header is required to provide the Authorization
bearer token. The required parameters for an order request are quote_uuid
(from the /quote response), beneficiary_name
, and retirement message
.
This is a response example.
You should receive a response containing your order details including order status
of your order which will allow you to confirm your order has been SUBMITTED
and will be completed shortly.
To verify your order has been completed, send a request to https://api.carbonmark.com/orders?quote_uuid=uuid
.
Once your order status
is COMPLETED
, your order is complete and the carbon credit has been retired.
When the transaction is finalized and our system has marked the order status as “complete”, the provided URL should take you to the shareable retirement receipt.
https://app.carbonmark.com/retirements/{beneficiaryAddress}/{number}
The order will appear in your developer dashboard as well.
The cost of the order will be added to your monthly invoice.
One of our solution specialists would be happy to answer any questions you have.
Use the marketplace or to identify a project or to identify an index product you’d like to retire. The Retirement API is compatible with any credit that has a visible price.
Listing details for a project or product can be returned for an array of ID's and other query parameters. For example, api.carbonmark.com/prices?projectsIds={project key}&projectsIds={project key}
. Or api.carbonmark.com/prices?productIds={productID}
. See endpoint for details.
Note that a response may include type "listing" (i.e. seller listing) or "carbon_pool" or "product" depending on the query parameters used.
The next step is to create a "Quote" for the listing you are interested in using the endpoint .
The next step is to create an "Order" for the quote generated above using the endpoint .
Note that some registries have specific requirements. For example, creating an order for a registry credit requires consumption_metadata
to be submitted in the request.
You can follow the polygonscan_url
or view_retirement_url
URLs in the response for further confirmation that your retirement order transaction is complete.
Alternatively, you can navigate back to the and see the entry and the order status.
For example: