Offsets API
The Offsets API provides access to the marketplace project catalogue, your organisation's credit wallet and the retirement lifecycle.
Projects
List offset projects
GET /api/v1/offsets/projects
Query parameters
| Parameter | Type | Description |
|---|---|---|
standard |
string | vcs, gold_standard, cdm, plan_vivo, corsia |
type |
string | redd_plus, afforestation, renewable_energy, methane_capture, blue_carbon, etc. |
minAvailable |
decimal | Minimum available credits (tCO₂e) |
maxPrice |
decimal | Maximum price per credit (USD) |
country |
string | ISO 3166-1 alpha-2 country code |
sdg |
integer | SDG number (1–17) |
page |
integer | |
pageSize |
integer | Max 100 |
Response
{
"data": [
{
"id": "proj_abc123",
"name": "Amazon Forest Protection REDD+",
"country": "BR",
"standard": "vcs",
"type": "redd_plus",
"availableCredits": 50000.0,
"pricePerCredit": 12.50,
"currency": "USD",
"sdgs": [13, 15, 1],
"verified": true,
"registryId": "VCS-1234"
}
]
}
Get a project
GET /api/v1/offsets/projects/{projectId}
Returns full project details including vintage pricing and verification report URLs.
Credits wallet
Get wallet balance
GET /api/v1/offsets/wallet
{
"data": {
"totalAvailable": 500.0,
"totalReserved": 100.0,
"totalRetired": 1240.5,
"currency": "USD",
"holdings": [
{
"projectId": "proj_abc123",
"projectName": "Amazon Forest Protection REDD+",
"vintage": 2023,
"available": 250.0,
"reserved": 0.0,
"pricePerCredit": 12.50
}
]
}
}
Purchases
Create a purchase order
POST /api/v1/offsets/orders
{
"items": [
{
"projectId": "proj_abc123",
"vintage": 2023,
"quantity": 100
}
],
"paymentMethod": "invoice",
"purchaseOrderNumber": "PO-2024-999"
}
Response (201)
{
"data": {
"orderId": "ORD-2024-000123",
"status": "pending_payment",
"totalUsd": 1250.00,
"items": [ ... ],
"invoiceUrl": "https://storage.alchemos.io/invoices/..."
}
}
List orders
GET /api/v1/offsets/orders
Get an order
GET /api/v1/offsets/orders/{orderId}
Retirements
Initiate a retirement
POST /api/v1/offsets/retirements
{
"projectId": "proj_abc123",
"vintage": 2023,
"quantity": 100,
"purpose": "net_zero_claim",
"beneficiaryName": "ACME Corporation Ltd",
"periodStart": "2024-01-01",
"periodEnd": "2024-12-31",
"emissionEntryIds": ["em_001", "em_002"],
"notes": "FY2024 annual net-zero retirement"
}
| Field | Type | Required | Description |
|---|---|---|---|
projectId |
string | ✅ | Project to retire from |
vintage |
integer | ✅ | Credit vintage year |
quantity |
decimal | ✅ | Credits to retire (tCO₂e) |
purpose |
string | ✅ | net_zero_claim, carbon_neutral_product, voluntary, cdr |
beneficiaryName |
string | ✅ | Legal name for registry |
periodStart |
date | ✅ | Period being offset |
periodEnd |
date | ✅ | Period being offset |
emissionEntryIds |
string[] | Optional | Link to specific entries |
notes |
string | Optional | Max 500 chars |
Response (201)
{
"data": {
"id": "ret_xyz789",
"status": "pending",
"quantity": 100,
"registryStatus": "pending_submission",
"estimatedConfirmationDate": "2024-11-06"
}
}
List retirements
GET /api/v1/offsets/retirements
Get a retirement
GET /api/v1/offsets/retirements/{retirementId}
Returns the full retirement record including serialNumbers once the registry confirms.
Retirement statuses
| Status | Description |
|---|---|
pending |
Retirement initiated; not yet submitted to registry |
submitted |
Instruction sent to registry |
confirmed |
Registry confirmed; serial numbers assigned |
failed |
Registry submission failed; retry pending |