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.

List retirements

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.

GEThttps://api.carbonregistry.com/retirements/list

Query parameters

Header parameters

Response

200

Body

application/json

retirements*array of ApiRetirementDto (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.carbonregistry.com/retirements/list?skip=0&first=0', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "retirements": [
    {
      "createdAt": "2024-12-21T13:35:08.251Z",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "isClaimed": false,
      "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

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'

Typescript

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.

Get retirement

This endpoint returns a json object with the retirement information.

GEThttps://api.carbonregistry.com/retirements

Query parameters

Header parameters

Response

200

Body

application/json

createdAt*string (date-time)

The date of when this retirement was made

id*string

The ID of the retirement

Example: "123e4567-e89b-12d3-a456-426614174000"

isClaimedboolean

Whether this retirement has been claimed - is false if the retirement happened permissionlessly on blockchain and owner has not claimed the retirement on ICR

reasonstring

The reason for the retirement

Example: "Reached retirement age"

commentstring

A comment about the retirement

Example: "Congratulations on your retirement!"

beneficiarystring

The name of the retiree

Example: "John Doe"

organizationId*string

The ID of the organization associated with the retirement

Example: "123e4567-e89b-12d3-a456-426614174000"

organizationOwnerall of

The organization that owns this credit if it is public information

serializationstring

The serialization of the carbon credits associated with the retirement

Example: "ICR-ISL-354-78040-14-R-0-2021"

vintagestring

The vintage year of the carbon credits associated with the retirement

Example: "2020"

amount*number

The amount of the retirement

Example: 1000

project*all of

The project associated with the carbon credits

Request

JavaScriptCurlPython

const response = await fetch('https://api.carbonregistry.com/retirements?id=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "createdAt": "2024-12-21T13:35:08.251Z",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "isClaimed": false,
  "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.

Get retirement pdf

This endpoint returns a specificretirement as a pdf

GEThttps://api.carbonregistry.com/retirements/{retirementId}/pdf

Path parameters

retirementId*string

Header parameters

Response

200

File content

Body

application/octet-stream

any

Request

JavaScriptCurlPython

const response = await fetch('https://api.carbonregistry.com/retirements/{retirementId}/pdf', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

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.

Finalize retirement certificate

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.

POSThttps://api.carbonregistry.com/retirements/finalize

Header parameters

Body

application/json

signer*string

The signer address.

Example: "0xA0022c05501007281acAE55B94AdE4Fc3dd59ec3"

signature*string

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

Example: "0xf76145d74ff1a3e70ca51e44063b6a90cf5e5d82e11941d3691e9dee197d124f748b6fcd8d3ecc7a45e08fe698be6f9e24685b5d8e270612e727380ede19c3321c"

signedData*all of

The signed retirement data object.

Response

200

Body

application/json

createdAt*string (date-time)

The date of when this retirement was made

id*string

The ID of the retirement

Example: "123e4567-e89b-12d3-a456-426614174000"

isClaimedboolean

Whether this retirement has been claimed - is false if the retirement happened permissionlessly on blockchain and owner has not claimed the retirement on ICR

reasonstring

The reason for the retirement

Example: "Reached retirement age"

commentstring

A comment about the retirement

Example: "Congratulations on your retirement!"

beneficiarystring

The name of the retiree

Example: "John Doe"

organizationId*string

The ID of the organization associated with the retirement

Example: "123e4567-e89b-12d3-a456-426614174000"

organizationOwnerall of

The organization that owns this credit if it is public information

serializationstring

The serialization of the carbon credits associated with the retirement

Example: "ICR-ISL-354-78040-14-R-0-2021"

vintagestring

The vintage year of the carbon credits associated with the retirement

Example: "2020"

amount*number

The amount of the retirement

Example: 1000

project*all of

The project associated with the carbon credits

Request

JavaScriptCurlPython

const response = await fetch('https://api.carbonregistry.com/retirements/finalize', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "signer": "0xA0022c05501007281acAE55B94AdE4Fc3dd59ec3",
      "signature": "0xf76145d74ff1a3e70ca51e44063b6a90cf5e5d82e11941d3691e9dee197d124f748b6fcd8d3ecc7a45e08fe698be6f9e24685b5d8e270612e727380ede19c3321c",
      "signedData": {
        "comment": "This retirement is for a sustainability project.",
        "reason": "Corsia",
        "tokenId": "47",
        "projectAddress": "0x49a88d0dd5f316556794877940d515d1a9b2c3c3",
        "beneficiary": "Jane Doe"
      }
    }),
});
const data = await response.json();

Response

200

{
  "createdAt": "2024-12-21T13:35:08.251Z",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "isClaimed": false,
  "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"
  }
}