Klima x402 Endpoint

Why x402

The endpoint is built for the x402 agent-payments ecosystem and plugs directly into Base MCP: an agent reads the catalog, prepares a retirement, and submits the batch through the user's Base Account wallet in a single approval. See the Base MCP setup guide for the connection steps.

All HTTP calls are free today. Use GET with query params on action paths (/discover, /quote, etc.) or POST JSON to /api with an action field — both return the same responses.

Two ways to retire:

• Build-your-own (free GET): discover → quote → prepare/retire hands back unsigned [approve, retire] calldata that you submit from a Base Account (e.g. via Base MCP). Reads are free; you pay gas and submit the batch yourself.
• Paid relay (sign once, no gas, no Base account): prepare-auth → sign one EIP-712 token authorization → actions/retire. A Klima executor relays the retirement on-chain and pays the gas, reimbursed from your signed budget. Any third-party wallet or agent can do this — see Paid retire (relay) below.

1. GET or POST /discover — what's retirable

GET /discover[?carbonClass=0x...][&creditToken=0x...][&maxUsdcPricePerTonne=20]
POST /api  {"action":"discover", ...same optional filters}

Lists carbon classes and credits, each with a reference USDC/tonne price, the credits inside it (registry, vintage, token, available liquidity), plus supported input tokens and contract addresses. Filters are optional and AND-combined (maxUsdcPricePerTonne=20 means ≤ $20/tonne). chainId is not accepted here.

2. GET or POST /quote — live price

GET /quote?chainId=8453&inputToken=0x...&carbonClass=0x...&amount=1.5
    [&creditToken=0x...][&vintage=2022][&tokenId=<id>]
POST /api  {"action":"quote", "chainId":8453, ...same params}

Returns the retirement price, on-chain fee, total (price + fee), suggestedMaxInput (total + 4% slippage), a humanSummary, the resolvedCredit the server selected (if no credit is specified), and alternatives.

When you don't pin a credit, the API picks the most liquid credit in the class that can cover the selected retirement amount.

{
  "tonnesFormatted": "1.5",
  "retirementPriceFormatted": "19.791336",
  "feeFormatted": "0.01",
  "totalFormatted": "19.801336",
  "suggestedMaxInputFormatted": "20.593389",
  "humanSummary": "1.5 tonnes @ 19.791336 USDC + 0.01 USDC fee = 19.801336 USDC (max 20.593389 USDC with 4% slippage)",
  "resolvedCredit": { "creditToken": "0xe662…71b8", "tokenId": 0, "vintage": 2021 }
}

3. GET or POST /prepare/retire — unsigned calldata

GET /prepare/retire?chainId=8453&inputToken=0x...&carbonClass=0x...&amount=1.5
    [&creditToken=0x...][&vintage=2022][&tokenId=<id>]
    [&maxInputTokenIn=<atomic>][&details=<urlencoded JSON>]
POST /api  {"action":"prepare/retire", "chainId":8453, ...same params}

Re-quotes on-chain and returns an ordered batch — an ERC-20 approve followed by the retirement to be submitted atomically (e.g. via Base MCP send_calls). The to field and approvalInstructions.spender are both the Settlement Contract — read them from the response rather than hard-coding.

details is an optional URL-encoded JSON object for certificate metadata. The schema is strict (unknown keys → 400):

Attribution tip: beneficiaryString and retirementMessage are what make a certificate named; the certificate cannot be edited after the retirement confirms, so set them up front. (The certificate's on-chain retiringAddress reflects an internal settlement/relayer address, not the details.retiringAddress you pass.)

4. GET or POST /certificate — public proof

GET /certificate?txHash=0x...[&index=0]
POST /api  {"action":"certificate", "txHash":"0x...", ...optional index}

After the retirement confirms, resolves the shareable Carbonmark certificate URL(s) for the transaction. index selects one retirement out of a multi-retirement transaction; omit it for all.

{
  "retirementCount": 1,
  "retirements": [{
    "certificateUrl": "https://app.carbonmark.com/retirements/id/8453-0x4a7f…f4bf-0",
    "amountInTonnes": "1",
    "beneficiaryAddress": "0x1234567890123456789012345678901234567890",
    "beneficiaryName": "testing",
    "projectId": "UCR-423",
    "creditId": "UCR-423-2022"
  }]
}

beneficiaryAddress is the address credited on-chain — check this one to verify attribution. retiringAddress on the same entry is the aggregator's settlement address, not the party the retirement was made for.

A 404 retirement_not_found right after confirmation just means the subgraph hasn't indexed yet — retry in a few seconds.

Paid retire (relay) — sign once, no gas

The relay path lets any wallet or agent retire without holding native ETH, without a prior token approval, and without a Base Account. You sign one standard EIP-712 token authorization; a Klima executor submits the on-chain transaction and is reimbursed for gas out of your signed budget.

Flow:

1. POST /api  prepare-auth   → server resolves + prices, returns:
                                 • typedData            (EIP-712 object to sign)
                                 • actionsRetireRequest (ready-to-send body,
                                     incl. `salt` on the USDC path)
2. wallet     signTypedData(typedData)        ← the ONLY signing step
3. POST /api  actions/retire (body + signature) → executor relays on-chain
4. POST /api  certificate    { txHash }       → public proof (poll if pending)

prepare-auth is the 200 alias of the 402 challenge that actions/retire returns when posted without an authPayload; either entry point gives you the same typedData. The signed budget (authValue) covers retirement + protocol fee + executor gas reimbursement, slippage-buffered. The signer needs only an input-token balance (USDC or kVCM) — no ETH.

Client SDK

The four steps are wrapped in a tiny, zero-dependency TypeScript client — sdk/klima-retire.ts. Drop the single file into your project (or npm i @klimadao/x402-retire once published — same API). It's signer-agnostic: you pass a signTypedData callback, so it works with viem, ethers, a browser wallet, or an agent's signer.

import { createClient } from "./klima-retire";
import { privateKeyToAccount } from "viem/accounts"; // or ethers, or a browser wallet

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const klima = createClient(); // https://x402.klimalabs.com, chainId 8453

const { status, transactionHash, retirements } = await klima.retire({
  from: account.address,
  amount: "1",
  carbonClass: "0xf4699531e0a5f6e9351a36de3753deaad329bf45", // from discover()
  inputToken: "usdc",                                        // or "kvcm" / an address
  details: {
    beneficiaryString: "Acme Corp",                          // shows on the certificate
    beneficiaryAddress: "0x…",                               // credited on-chain, permanent
    retirementMessage: "Net-zero 2026",
  },
  signTypedData: (td) => account.signTypedData(td as any),   // your wallet's signer
});

for (const r of retirements) console.log(r.amountInTonnes, "t →", r.certificateUrl);

retire() runs the whole flow — prepare-auth → sign → submit → poll the certificate — and returns once settled (or pending_index with a transactionHash you resolve later). The same client also exposes discover(), quote(), and certificate().

actions/retire responses

Runnable examples (USDC + kVCM) live in examples/: a read-only discover + quote, the minimal SDK retire, and a raw-HTTP protocol walkthrough.

Fees

API calls are free. Each retirement bakes in a protocol fee — max(floor, feeBps% of cost), floor denominated in USDC (converted to kVCM via the pool when paying in kVCM) — computed and collected on-chain by the Settlement Contract. It's always included in quote.fee and folded into total. The contract spends exactly retirementCost + fee and refunds any unused slippage budget in the same transaction.

Use it from an AI agent

The fastest path is the Klima Base MCP plugin — it wires this endpoint into any Base MCP–capable agent (e.g. Claude Code).

1. Install — connect Base MCP and add the Klima plugin by following the Base MCP setup guide. Plugin: plugins/klima-retire.md.
2. Ask in plain language — e.g. “Retire 2 tonnes of carbon under $15/tonne, beneficiary ‘Acme Corp’.”
3. The agent runs discover → quote → prepare/retire → shows you the cost → submits one wallet approval → returns your certificate URL.

Prefer a direct integration (no MCP)? Call the GET or POST endpoints above yourself, then sign and submit the prepare/retire batch (approve + retirement) with your own wallet on Base — or use the gasless paid relay path (sign one authorization, a Klima executor submits it).