Announcing the Klima Community Hackathon

A 4-week build sprint for the Klima Protocol community. Ship new carbon retirement tooling, retire real carbon credits, and the team that retires the greatest value in credits wins.

Context

Klima's tokenomics are focused on impact. Carbon retirements are what drive value to the system.

The infrastructure is built to make carbon retirements as easy, transparent, and scalable as possible: no fees, high throughput, instant settlement, transparent and unobfuscated carbon prices.

Retirements are what make carbon markets tick. Making the market as accessible as possible for demand is the most important and impactful thing we can do.

The infrastructure is there. This hackathon is about operationalising it.

A recent internal hackathon produced several novel use cases:

• An x402 endpoint
• An "incentive to retire" mechanic for the Klima Protocol app
• Market data and analytics tools
• LLM-driven protocol insights

To scale onchain carbon markets, there are two core opportunity areas.

• Tapping into DeFi flows. DeFi is orders of magnitude larger than the carbon markets. Redirecting even a fraction of its flows can meaningfully scale carbon market impact.
• Web3 abstraction. Giving carbon market participants easy access to the benefits of blockchain infrastructure, without exposing them to the blockchain itself.

The purpose of this hackathon is to tap into community knowledge, relationships, and insights to build legitimately useful applications that scale onchain impact for carbon markets.

The challenge

Over 4 weeks, teams design and build new carbon retirement tooling — anything that makes it easier, cheaper, faster, or more transparent to permanently retire carbon credits (e.g. retirement dashboards, automated retire-on-action bots, wallet integrations, reporting widgets, on-chain analytics, gamified retirement apps, etc.).

The point isn't just to build — it's to use what you build. Every tonne of carbon your team retires through Klima Protocol's retirement aggregator on the Base blockchain during the event counts toward your score.

What "winning" means: The team with the highest total value (measured in USDC terms) of carbon tonnage retired (tCO₂e) at their registered beneficiary address when the clock runs out wins. A multiplier will be applied to use-cases that can be deemed to have high scalability and can generate retirements after the hackathon.

Build theme / focus area: DeFi-powered retirements, novel carbon retirement frontends (Web3 and Web3-abstracted).

A few things worth knowing up front:

• Builders retain their IP, are welcome to take their use case forward in future, and may apply their own fees on top of their integration. The unit economics are up to them.
• Builders may integrate a carbon retirement use case with existing applications or create completely new ones.
• At the end of the hackathon, teams must make all code available via a GitHub repo with a readme. Judges will score based on that.

The prize

🏆 Grand Prize: 70,000 KVCM tokens to the team with the highest verified carbon retirement value at the deadline.

• 1st place — 70,000 KVCM + entry on the Klima Labs 'Case Studies' page
• 2nd place — 20,000 KVCM + entry on the Klima Labs 'Case Studies' page
• 3rd place — Entry on the Klima Labs 'Case Studies' page
• Bonus / community pick — Entry on the Klima Labs 'Case Studies' page

Payouts: Teams can provide their wallet address and receive their KVCM upon completion of the competition. Note that KVCM will be paid out as locked kVCM (shortest duration lock, ~2 months) to encourage participation in the protocol.

Timeline

• Applications open — June 4th
• Applications close — July 19th
• Kickoff / build period begins — June 24th
• Build period ends (retirement cutoff) — July 22nd, 8pm UTC
• Verification & judging — July 23rd – July 29th
• Winners announced — July 30th
• Prize distributed — July 31st

Who can take part

• Conflicts of interest: Core team / judges may not compete.
• Everyone else (businesses, individuals, etc.) may compete.

How to apply

To enter, each team must:

1. Register a team. Submit the application form here.
2. Get confirmed. We'll review and confirm your entry by July 19th via email.
3. Join the hackathon channel: Klima Community Hackathon for announcements, support, and Q&A.

Setting up your Carbonmark beneficiary address

This is how your retirements get counted. Carbonmark publishes a public page for every beneficiary address showing the total tonnes of carbon that address has retired — that page is your team's live scoreboard.

Step 1 — Use a fresh, dedicated wallet

Create or designate a brand-new wallet address used only for this hackathon.

You can create your Carbonmark account at app.carbonmark.com. Once created, click 'view retirements' on the Carbon Portfolio page. You can then copy your beneficiary address (ACCOUNT ID).

Step 2 — Retire carbon and name your address as the beneficiary

You can retire three ways: through Klima's x402 endpoints, directly through Klima's retirement aggregator contract, or through the Carbonmark app. All are described below.

A) x402 endpoints

A self-hosted x402 endpoint that wraps Klima Protocol's Retirement Aggregator on Base, so your tooling can quote and retire carbon over a simple HTTP API and pay per call with USDC — no API keys or accounts.

What it is. Klima runs an x402 endpoint in front of the Retirement Aggregator. x402 is an open standard that uses the HTTP 402 Payment Required status code to charge for a single API request in stablecoins. The endpoint exposes a small set of actions — discover credits, get a quote, size a retirement to a budget, prepare calldata, and retire — and only the final retire action costs anything.

Importantly, the endpoint returns encoded transaction calldata; it does not broadcast the transaction for you. Your tool takes the calldata it returns and submits it on-chain from your own wallet. That means your team's beneficiary details are baked into the calldata you send, and the actual retirement is your own on-chain transaction.

Endpoints

• Live API base: https://x402.klimalabs.com/api
• Agent-discovery manifest: https://x402.klimalabs.com/.well-known/x402.json
• Health / liveness probe: GET https://x402.klimalabs.com/api/health

The API is publicly callable with no auth header — x402 itself is the auth layer for the one paid action.

Network & payment basics

• Payment token: USDC, paid via EIP-3009 (transferWithAuthorization).
• Facilitator: PayAI's public facilitator (facilitator.payai.network) settles the payment by default — free and unauthenticated, supporting both Base Sepolia and Base mainnet.

Actions & pricing

All actions are POSTed to /api with an action field in the JSON body (except health, which is a GET). Only retire is paid.

• discover (free) — Lists carbon classes from the protocol subgraph (optional Puro batchId lookup).
• quote (free) — Live USDC price quote; an on-chain read of quoteRetireCreditViaKlima.
• quoteByBudget (free) — Recommends a tonnage that fits a USDC budget.
• prepare (free) — Returns encoded retireCreditViaKlima calldata + approval instructions for one retirement (pure off-chain encoding, no broadcast).
• retire ($0.01 USDC) — Returns batchCall calldata for one or many retirements.

How the paid retire call works

The free actions return JSON immediately. The paid retire route follows the standard x402 flow:

1. Your tool POSTs the retire request to /api without payment.
2. The server responds with HTTP 402 and a payment-required header containing a base64-encoded challenge envelope describing the $0.01 USDC charge.
3. Your client's wallet signs the payment and retries the same request with a signed X-PAYMENT header.
4. The facilitator settles the $0.01 USDC fee, the handler runs, and you receive the batchCall calldata.
5. Your tool submits that calldata on-chain from your wallet to execute the actual retirement.

A standard x402 client wrapper can handle steps 2–3 automatically, so it feels like a single call.

A typical retirement flow

1. discover — find the credit / carbon class you want to retire. Body: { "action": "discover", "creditToken": "0x..." } (creditToken optional).
2. quote or quoteByBudget — get the live price or size the retirement to a budget. Quote body includes chainId, creditToken, amount, inputToken, carbonClass. Budget body swaps amount for budget.
3. prepare — get the encoded retireCreditViaKlima calldata and the token-approval instructions for a single retirement (free, off-chain).
4. retire — pay the $0.01 x402 fee and receive batchCall calldata for one or many retirements.
5. Submit on-chain — broadcast the returned calldata from your wallet, with the token approvals from step 3 in place.

References

• Klima Retirement Aggregator usage: github.com/KlimaDAO/retirement-aggregator (USAGE.md)
• x402 protocol: www.x402.org
• PayAI facilitator docs: docs.payai.network/x402/introduction
• Goldsky subgraphs (Base): protocol + carbon production endpoints (see RA GitHub)

B) Direct interaction with Klima's Retirement Aggregator contract

If your tooling works directly on-chain, your team can call the Retirement Aggregator smart contract yourselves. The aggregator is a deployed contract on Base that handles the retirement and emits an on-chain event recording the beneficiary. There are two paths depending on whether you already hold the credits.

Contract addresses (Base Mainnet, Chain ID 8453):

• Retirement Aggregator: 0xda0a793d7c32ab80bcdab7f8c725c96db22464f4
• Klima Protocol (AAM): 0x1C24239309398220883207681602BfF4D10fbde1
• kVCM: 0x00fbac94fec8d4089d3fe979f39454f48c71a65d
• USDC: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

A Base Sepolia testnet deployment (Chain ID 84532) is available at 0xc0309c29162f699a3445a7a9aeb0acbe568f5fe0 — use it to dry-run your integration before retiring for real.

Supported credit types: Toucan Puro TCO2, CMARK (Carbonmark Global Credit Factory), and UCR (all ERC-20); ECO (ERC-1155) is listed as coming soon.

Every retirement passes a RetireDetails struct. At minimum, set your team's beneficiary so the retirement is attributed to you:

RetireDetails({
  retiringAddress: address(0),        // defaults to msg.sender
  retiringEntityString: "",           // defaults to "Carbonmark Retirement Aggregator"
  beneficiaryAddress: 0xYourTeamAddress, // your dedicated wallet from Step 1
  beneficiaryString: "Team [NAME]",
  retirementMessage: "[EVENT NAME] retirement",
  beneficiaryLocation: "",            // REQUIRED for Toucan Puro
  consumptionCountryCode: "",         // REQUIRED for Toucan Puro
  consumptionPeriodStart: 0,          // REQUIRED for Toucan Puro (unix time)
  consumptionPeriodEnd: 0             // REQUIRED for Toucan Puro (unix time)
})

Path 1 — Direct retirement (you already own the credits):

1. Approve the aggregator to move your credit token: for ERC-20 credits call approve(RETIREMENT_AGGREGATOR_ADDRESS, amount); for ERC-1155 (ECO) call setApprovalForAll(RETIREMENT_AGGREGATOR_ADDRESS, true).
2. Call retireCredit(creditToken, tokenId, batchId, amount, details) — use tokenId = 0 for ERC-20 credits, and batchId = 0 unless retiring Toucan Puro.
3. Puro only: fetch the current batchId from the Klima CARBON subgraph before retiring (it can change between retirements).

Path 2 — Klima-mediated retirement (pay with kVCM or USDC):

1. Pick a credit and its carbon class. Each credit belongs to a carbon-class vault address you must pass in. Find it on the Klima dashboard or query the Klima PROTOCOL subgraph.
2. Get a quote with quoteRetireCreditViaKlima(creditToken, tokenId, amount, inputToken, carbonClass, 0) to learn the price and tonnage.
3. Approve the right spender — this differs by token: for kVCM, approve the Klima Protocol (AAM) address (it pulls kVCM directly); for USDC, approve the Retirement Aggregator (it pulls USDC and swaps internally).
4. Execute retireCreditViaKlima(creditToken, tokenId, batchId, amount, inputToken, carbonClass, maxInputTokenIn, 0, details). Set maxInputTokenIn as your slippage cap — if the cost exceeds it the call reverts with SlippageExceeded.

Confirming on-chain: every successful retirement emits an AggregatorRetired event with both retiringAddress and beneficiaryAddress indexed, so you (and organizers) can filter the chain for your team's beneficiary address to verify retirements independently.

C) Through the Carbonmark app (no code needed)

1. Go to app.carbonmark.com and browse / select a verified carbon project.
2. Press Retire.
3. Enter the number of tonnes, the beneficiary name (your team name), and crucially the beneficiary address (your dedicated wallet from Step 1).
4. Add a retirement message (e.g. "[EVENT NAME] — Team [NAME]") — useful for verification.
5. Pay by card or bank transfer and receive your on-chain retirement certificate.

Note: we only recommend this approach if you are building something offchain and wish to settle retirements through Klima's infrastructure onchain after receiving payment through Web2 or other means.

Step 3 — Confirm your retirements are showing

Visit your team's public retirements page:

https://app.carbonmark.com/retirements/[YOUR_BENEFICIARY_ADDRESS]

It displays Total Carbon Tonnes Retired and Total Retirement Transactions for that address. If your tonnes appear here, they're counting. Bookmark it — this is your live leaderboard position.

How retirements are counted & verified

• Metric: Total tCO₂e retired attributed to the team's registered beneficiary address. Every retirement's USDC value in KVCM terms will be computed — i.e. 1 tonne retired for a carbon credit with a $300 value will count more than 1 tonne retired for a credit that costs $0.25.
• Source of truth: The public Carbonmark beneficiary page (/retirements/[address]) plus on-chain transaction timestamps.
• Counting window: Only retirements with a confirmed on-chain timestamp after kickoff and before the cutoff are eligible. Organizers will snapshot starting balances at kickoff and final balances at cutoff; the difference is the team's score.
• One address per team. Retirements spread across multiple addresses will not be summed unless pre-registered and approved.
• Receipts: Teams may be asked to share retirement certificate links / transaction hashes for spot-checks.

Custom rules

• Eligible credits / projects: any facilitated by Klima Protocol and made available via Klima's Retirement Aggregator contract on Base.
• Minimum / maximum retirement size: no max / min size.
• Use of KVCM: Retirements can be facilitated by USDC or KVCM. Note that all retirements ultimately settle in KVCM regardless of the payment input.
• Open-source requirement: No requirement; however GitHub repos will be requested during the judging process.
• Demo / submission requirement: We may ask individuals / teams to demo their product or service during the judging process.
• AI / third-party tooling policy: Allowed.

Judging & tie-breakers

• Primary ranking: Highest verified tCO₂e value retired wins.
• Disqualification: Organizers reserve the right to disqualify entries for rule violations, gaming, or misattributed retirements.

Fair play & code of conduct

Respect other teams; no interfering with another team's wallet, infrastructure, or submissions.

FAQ

Do retirements have to be funded with KVCM? Retirements can be funded by both KVCM and USDC.

Can I retire fractions of a tonne? Yes — the following carbon classes support fractional retirements: Wind Energy – Small Scale, Solar PV – Small Scale, Ocean Alkalinity Enhancement, and Regen – CFC.

What if my retirement doesn't show on my beneficiary page? Check you used the exact registered address as the beneficiary, and allow time for on-chain confirmation.

Can a solo builder enter? Yes.

Who owns the tools we build? No intellectual property is required to be transferred during or after this hackathon. Teams retain full ownership of what they build.

Support & additional resources

• Hackathon channel: discord.gg/3GsQBWFrFK
• RA GitHub: github.com/KlimaDAO/retirement-aggregator

---

The Klima Ecosystem Hackathon is organized by Klima Protocol. By entering, participants agree to these rules.