Retirements
Retirements
List retirements
Callable by any access token regardless of permissions. This endpoint returns all retirements, both on platform and off - if a retirement has not been claimed by a KYBd organization the only data shown is the amount and the project and a pdf can not be generated.
This endpoint returns all retirements, both on platform and off - if a retirement has not been claimed by a KYBd organization the only data shown is the amount and the project and a pdf can not be generated.
The amount of items to skip
10
The number of elements to return
0
API version
2023-06-16
GET /retirements/list HTTP/1.1
Host: api.carbonregistry.com
Accept: */*
{
"retirements": [
{
"createdAt": "2025-07-04T05:25:49.660Z",
"id": "123e4567-e89b-12d3-a456-426614174000",
"isClaimed": true,
"reason": "Reached retirement age",
"comment": "Congratulations on your retirement!",
"beneficiary": "John Doe",
"organizationId": "123e4567-e89b-12d3-a456-426614174000",
"organizationOwner": {
"total": 100,
"currentPage": 1,
"pageCount": 10,
"nextPage": 2,
"prevPage": 0
},
"serialization": "ICR-ISL-354-78040-14-R-0-2021",
"vintage": "2020",
"amount": 1000,
"project": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"fullName": "Project 1",
"url": "https://api.carbonregistry.com/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
"publicUrl": "https://carbonregistry.com/explore/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
"num": "713"
}
}
]
}
curl -X 'GET' \
'https://api.carbonregistry.com/retirements/list' \
-H 'accept: application/json' \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
-H 'x-icr-api-version: 2023-06-16'
Get retirement
Callable by any access token regardless of permissions. This endpoint returns the data connected to a particular retirement.
Callable by any access token regardless of permissions.
This endpoint returns a json object with the retirement information.
The ICR id of the retirement.
2
API version
2023-06-16
GET /retirements HTTP/1.1
Host: api.carbonregistry.com
Accept: */*
{
"createdAt": "2025-07-04T05:25:49.660Z",
"id": "123e4567-e89b-12d3-a456-426614174000",
"isClaimed": true,
"reason": "Reached retirement age",
"comment": "Congratulations on your retirement!",
"beneficiary": "John Doe",
"organizationId": "123e4567-e89b-12d3-a456-426614174000",
"organizationOwner": {
"total": 100,
"currentPage": 1,
"pageCount": 10,
"nextPage": 2,
"prevPage": 0
},
"serialization": "ICR-ISL-354-78040-14-R-0-2021",
"vintage": "2020",
"amount": 1000,
"project": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"fullName": "Project 1",
"url": "https://api.carbonregistry.com/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
"publicUrl": "https://carbonregistry.com/explore/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
"num": "713"
}
}
Get retirement pdf
Given an id of the retirement this is an endpoint that downloads the certificate.
Callable by any access token regardless of permissions.
This endpoint returns a specificretirement as a pdf
API version
2023-06-16
GET /retirements/{retirementId}/pdf HTTP/1.1
Host: api.carbonregistry.com
Accept: */*
File content
No content
Finalize a retirement
Callable by any access token regardless of permissions. This endpoint finalizes
a given retirement certificate by setting the beneficiary, reason and comment for the certificate to become finalized
. This is mainly for retirements that happened off platform - onchain. See here for more info.
This endpoint can be used by owners of an onchain retirement to finalize their retirement certificate - a certificate is only available for finalization if the retirement was made onchain and the beneficiary is missing.
API version
2023-06-16
The signer address.
0xA0022c05501007281acAE55B94AdE4Fc3dd59ec3
The signature. This a standard signature created by signing the data as a string in the following format - with double ";;" between each field - "beneficiary;;comment;;reason;;projectAddress;;tokenId" for info on how to sign strings see -> https://docs.ethers.org/v6/cookbook/signing/#cookbook-signing-messages
0xf76145d74ff1a3e70ca51e44063b6a90cf5e5d82e11941d3691e9dee197d124f748b6fcd8d3ecc7a45e08fe698be6f9e24685b5d8e270612e727380ede19c3321c
The signed retirement data object.
POST /retirements/finalize HTTP/1.1
Host: api.carbonregistry.com
Content-Type: application/json
Accept: */*
Content-Length: 398
{
"signer": "0xA0022c05501007281acAE55B94AdE4Fc3dd59ec3",
"signature": "0xf76145d74ff1a3e70ca51e44063b6a90cf5e5d82e11941d3691e9dee197d124f748b6fcd8d3ecc7a45e08fe698be6f9e24685b5d8e270612e727380ede19c3321c",
"signedData": {
"comment": "This retirement is for a sustainability project.",
"reason": "Corsia",
"tokenId": "47",
"projectAddress": "0x49a88d0dd5f316556794877940d515d1a9b2c3c3",
"beneficiary": "Jane Doe"
}
}
{
"createdAt": "2025-07-04T05:25:49.660Z",
"id": "123e4567-e89b-12d3-a456-426614174000",
"isClaimed": true,
"reason": "Reached retirement age",
"comment": "Congratulations on your retirement!",
"beneficiary": "John Doe",
"organizationId": "123e4567-e89b-12d3-a456-426614174000",
"organizationOwner": {
"total": 100,
"currentPage": 1,
"pageCount": 10,
"nextPage": 2,
"prevPage": 0
},
"serialization": "ICR-ISL-354-78040-14-R-0-2021",
"vintage": "2020",
"amount": 1000,
"project": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"fullName": "Project 1",
"url": "https://api.carbonregistry.com/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
"publicUrl": "https://carbonregistry.com/explore/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
"num": "713"
}
}
Last updated