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. Discover retirement options.

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

Lists protocol carbon classes, marketplace listings and their associated credits, each with a reference USDC/tonne price. Filters are optional and AND-combined (maxUsdcPricePerTonne=20 means ≤ $20/tonne).

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. Returns prepared retirement 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. The approval transaction for the credit's token standard followed by the retirement to be submitted atomically. 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. Returns public proof of retirement.

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

After the retirement confirms, returns 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 Retirement 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 required.

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 when published. The API is the same). 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 (except for catalog which is for indexing purposes and not required for any part of the workflow). Each retirement bakes in a fee max(floor, feeBps% of cost), floor denominated in USDC (converted to kVCM via the pool when paying in kVCM) which is 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 to the user 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).