Retire carbon with x402
Use the x402 Carbon Retirement API to discover carbon, retrieve a live quote, submit an unsigned approve + retire batch from your own wallet, and resolve the public certificate.
This page walks through the build-your-own path: reads are free, and the retirement is paid in the transaction you sign and broadcast yourself on Base mainnet. If you would rather have a relay submit the transaction and pay gas for you, see Gasless retirement (paid relay).
All requests target Base mainnet (chainId=8453). Every action endpoint accepts GET with query parameters or POST JSON to /api with an action field; both return the same responses.
Before you begin
You will need:
A wallet on Base with a balance of an accepted input token (USDC or kVCM)
Enough native ETH on Base to pay gas for the retirement transaction
The ability to submit an atomic
approve+retirebatch (for example, via Base MCPsend_calls)
See x402 reference for input token addresses, amount rules, and fees.
Step 1: Discover what's retirable
Call /discover to see everything retirable. It returns two arrays, one per supply source, plus supported input tokens and contract addresses:
carbonClasses[]— pooled protocol supply. Each class carries a reference USDC/tonne price and the credits inside it (registry, vintage, token, available liquidity).marketplaceListings[]— one entry per open marketplace listing: the seller, the exact credit, a firmpriceUsdcPerTonne, and how much of it you can take (leftToSell,minFill,expiration). Sellers and asks are per listing, so two listings of the same credit are two entries, not one.
Every entry in either array is tagged with source ("protocol" or "marketplace"), and marketplaceEnabled tells you whether marketplace supply was searched at all — so an empty marketplaceListings[] means "nothing listed", not "turned off".
Filters are optional and AND-combined, and apply to both arrays: source, carbonClass, creditToken, project, vintage, country, category, methodology, maxUsdcPricePerTonne. For example, maxUsdcPricePerTonne=20 returns only supply at or below $20/tonne from either source, and source=marketplace returns listings alone. A per-credit filter also trims a matched class down to its matching credits. chainId is not accepted on this endpoint.
Project metadata (country, category, methodologies) is joined per credit, not per class — a class spans projects, so its own attributes are an aggregate. Both arrays therefore carry the same attribute set, and every filter resolves against it.
Example request:
The POST equivalent sends the same optional filters:
Step 2: Get a live quote
Call /quote with your input token, carbon class, and amount to get the real cost of your tonnage.
Required parameters:
chainId(8453)inputTokenamount(decimal tonne string)exactly one supply source:
carbonClassorlistingId
Optional parameters: creditToken, vintage, tokenId. When you do not pin a specific credit, the API selects the most liquid credit in the class that can cover the requested amount.
Two supply sources
discover returns both, each entry tagged with source. They are addressed differently and the choice belongs in the request:
carbonClass (source: "protocol")
listingId (source: "marketplace")
What it is
Pooled supply, priced by the protocol AMM
One seller's fixed ask for one credit
Which credit
The API picks the most liquid in the class, or you pin one
Fixed by the listing
Price
Moves with the pool; quotes carry a slippage buffer
unitPrice exactly, or the fill reverts
suggestedMaxInput
total plus 4% slippage
total exactly, no buffer
Input token
USDC or kVCM
USDC only
Amount limits
The class's liquidity
The listing's minFill and leftToSell
Quote lifetime
Authorizations valid up to an hour
Authorizations capped at 5 minutes
Pass one or the other, never both: a listing already names its credit, so there is no class to route through. Sending both, or neither, returns 400 schema_validation.
A listing fill can fail in ways pooled supply cannot, because the seller controls the terms and other buyers compete for the same supply: listing_not_found, listing_expired, below_min_fill, insufficient_listing_supply. Each is documented in the error reference with the field to adjust.
Example request:
The response returns the retirement price, the on-chain fee, the total (price + fee), a suggestedMaxInput (total plus 4% slippage on the protocol path; exactly total for a listing, which has no price impact to buffer against), a humanSummary, the resolvedCredit the server selected, and any alternatives. A listing quote returns an empty alternatives: it is one seller's ask, so there is nothing to offer instead.
To quote a marketplace listing, swap carbonClass for a listingId from discover.marketplaceListings[]:
Example response (trimmed for readability):
Step 3: Prepare the retirement
Call /prepare/retire with the same core parameters as /quote. The endpoint re-quotes on-chain and returns an ordered batch: an ERC-20 approve followed by the retirement, to be submitted atomically (for example, via Base MCP send_calls).
Optional parameters include maxInputTokenIn and details (a URL-encoded JSON object for certificate metadata; see below).
Example request:
Certificate metadata (details)
details is an optional URL-encoded JSON object. The schema is strict — unknown keys return 400.
retiringAddress
Address performing the retirement
beneficiaryAddress
Address credited on the certificate. Defaults to the payer on this self-submit path; required on the relay path unless beneficiaryIsPayer: true
beneficiaryString
Beneficiary display name — shows on the certificate
retiringEntityString
Retiring-entity display name
retirementMessage
Public message on the certificate
beneficiaryLocation, consumptionCountryCode, consumptionPeriodStart, consumptionPeriodEnd
Toucan Puro only — required for Puro credits
Step 4: Submit the batch
Submit the returned approve + retire batch atomically from your wallet on Base. This transaction pays for the retirement: the credit price plus a fee, settled on-chain, and the contract refunds any unused slippage budget in the same transaction.
Step 5: Resolve the certificate
After the transaction confirms, call /certificate with the transaction hash to resolve the shareable Carbonmark certificate URL(s).
Use the optional index parameter to select one retirement out of a multi-retirement transaction; omit it to return all.
Example request:
Example response (trimmed for readability):
Notes
Target Base mainnet only (
chainId=8453).Reference prices from
/discoverapproximate spot; always confirm real cost with/quote.When you do not pin a credit, the API picks the most liquid credit in the class that can cover your
amount.Read the Settlement Contract address from the
/prepare/retireresponse rather than hard-coding it.Set
beneficiaryStringandretirementMessagebefore retiring — certificates cannot be edited afterward.Retirement is irreversible once the transaction confirms.
Last updated

