Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Retire carbon with x402

Use the x402 Endpoint 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 you sign and broadcast the retirement transaction 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 + retire batch (for example, via Base MCP send_calls)

See x402 reference for input token addresses, amount rules, and fees.

Step 1: Discover what's retirable

Call /discover to list carbon classes and credits. Each class returns a reference USDC/tonne price, the credits inside it (registry, vintage, token, available liquidity), supported input tokens, and contract addresses.

Filters are optional and AND-combined — for example, maxUsdcPricePerTonne=20 returns only classes at or below $20/tonne. chainId is not accepted on this endpoint.

Example request:

# List carbon classes (optional filters)
curl "https://x402.klimalabs.com/api/discover?maxUsdcPricePerTonne=15"

The POST equivalent sends the same optional filters:

Reference price is not the price at size. priceUsdcPerTonne is the marginal (spot) price and is accurate near 1 tonne. Large orders walk up the AAM curve — for example, a credit quoted at roughly $107.82/t for 1 t can cost roughly $386.61/t for 100 t once it consumes a large share of pool liquidity. Always call /quote for the true cost of your size.

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)

  • inputToken

  • carbonClass

  • amount (decimal tonne string)

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.

Example request:

The response returns the retirement price, the on-chain fee, the total (price + fee), a suggestedMaxInput (total plus 4% slippage), a humanSummary, the resolvedCredit the server selected, and any alternatives.

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:

The to field and approvalInstructions.spender in the response are both the Settlement Contract. Read them from the response rather than hard-coding an address.

Certificate metadata (details)

details is an optional URL-encoded JSON object. The schema is strict — unknown keys return 400.

Field
Meaning

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

Set attribution up front. beneficiaryString and retirementMessage are what make a certificate named, and the certificate cannot be edited after the retirement confirms. Note that the certificate's on-chain retiringAddress reflects an internal settlement/relayer address, not the details.retiringAddress you pass.

Step 4: Submit the batch

Submit the returned approve + retire batch atomically from your wallet on Base. API calls are free; the protocol fee is settled on-chain inside this transaction, 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):

A 404 retirement_not_found immediately after confirmation usually means the subgraph has not indexed the transaction yet. Wait a few seconds and retry.

Notes

  • Target Base mainnet only (chainId=8453).

  • Reference prices from /discover approximate 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/retire response rather than hard-coding it.

  • Set beneficiaryString and retirementMessage before retiring — certificates cannot be edited afterward.

  • Retirement is irreversible once the transaction confirms.

PreviousIntroduction to Carbonmark's x402 EndpointNextGasless retirement (paid relay)

Last updated