Skip to content

feat(wallet-mcp): add Carbonmark plugin - #28

Open
drewesoa wants to merge 1 commit into
coinbase:mainfrom
drewesoa:feat/wallet-mcp-carbonmark-plugin
Open

drewesoa wants to merge 1 commit into
coinbase:mainfrom
drewesoa:feat/wallet-mcp-carbonmark-plugin

Conversation

@drewesoa

Copy link
Copy Markdown

Description

Adds a Carbonmark plugin (skills/wallet-mcp/plugins/carbonmark.md) so a Wallet MCP user can retire tokenized carbon credits on Base and receive a public certificate. No current plugin covers carbon credits.

How it works:

  1. get_wallets → wallet address.
  2. GET https://x402.klimalabs.com/api/discover → retirable supply with live USDC prices per tonne (pooled carbon classes and fixed-price marketplace listings).
  3. GET /api/quote → price, fee and total for the requested tonnes.
  4. The agent collects the name that will appear on the certificate, which cannot be edited afterwards, and confirms the input token (USDC or kVCM).
  5. GET /api/prepare/retire → an unsigned, ordered [approve, retire] batch plus the authoritative quote.
  6. The agent shows the quote summary and gets the user's confirmation, then submits the batch in one send_calls on base.
  7. After approval: get_request_status → transaction hash → GET /api/certificate → the certificate URL on app.carbonmark.com.

Frontmatter: integration: http-api, chains: [base], allowlist: [x402.klimalabs.com], auth: none, risk: [irreversible]. Every call is a GET with all parameters in the query string, so the user-paste fallback in references/custom-plugins.md works while the host is not allowlisted.

Per Contribution Scope, the diff is the plugin file plus three new tags (carbon-credits, carbon-retirement, climate) appended to the vocabulary in plugin-spec.md. The SKILL.md registry table is left to maintainers.

This replaces the earlier submission base/skills#102, which targeted the base-mcp skill before it moved to this repository. The plugin text is that file, maintained by the endpoint's developers, with the wording moved from Base MCP to Wallet MCP, the plugin renamed from klima to carbonmark, and two details corrected against the live API (the credit filter on discover, and whole-tonne minimums being per class rather than Puro-only).

Change type

  • Harness integration or metadata
  • Skill workflow
  • Bug fix
  • Documentation
  • Breaking change (describe migration)

Validation

Run, on 2026-11-17 against production (x402.klimalabs.com), with read-only calls:

  • Self-check against the plugin-spec Authoring Checklist: all required frontmatter fields, the callout first, the required sections for http-api in canonical order with canonical names, and every relative link and #anchor resolving.
  • discover: response fields named in the plugin are present (carbonClasses[], marketplaceListings[], marketplaceEnabled, creditsDetailed[].liquidityFormatted, minRetirementTonnesFormatted, leftToSellFormatted, minFillFormatted). maxUsdcPricePerTonne=15 narrowed 6 classes to 4. An unknown parameter, including chainId, returns 400 schema_validation.
  • quote: 0.001 t returned price, fee, total, suggestedMaxInput (total × 1.04), humanSummary, resolvedCredit and alternatives.
  • prepare/retire: returned chain: "base" and transactions[] of exactly approve (to USDC) then prepareRetire (to the Settlement Contract, which is also approvalInstructions.spender), both with value: "0x0", with and without a details object.
  • Errors: chainId=84532 → 400 unsupported_chain_id; chainId=1 → 400 schema_validation; 0.5 t of a whole-tonne class → 422 amount_not_whole_tonnes with nearestUpTonnes; certificate for an unknown hash → 404 retirement_not_found.
  • python3 -m unittest discover -s tests on Windows: 32 of 38 pass. The other 6 fail identically on an unmodified checkout of main (symlink privilege, CRLF checkout and code-page errors), so they are not caused by this change. Not run on Linux.

Not run:

  • No Wallet MCP session: get_wallets, send_calls and get_request_status were not exercised and no transaction was signed for this PR. The earlier submission reported the same approve + retire batch as tested under Base MCP; it has not been re-run under Wallet MCP. It is unverified whether get_request_status returns the on-chain transaction hash that /api/certificate needs.
  • Whether x402.klimalabs.com is on the web_request allowlist.
  • The plugin-review skill referenced in plugin-spec.md is not in the repository, so it was not run.

Checklist (harness and packaging items do not apply to a plugin file):

  • Generated portable manifest and MCP config validate against the vendored Agent Plugins schemas — n/a
  • Package paths and skill references remain inside each generated plugin root — n/a
  • Marketplace, skills, MCP, and icon paths are valid — n/a
  • Exactly one canonical skill library; generated copies are not committed
  • Claude compatibility metadata/endpoint and marketplace sources agree with the portable package — n/a
  • Tool schemas, authorization, and retry behavior reviewed
  • README and changelog updated; versions consistent — left to maintainers per Contribution Scope
  • No unapproved disclosures or sensitive data
  • Signed commits

Release considerations

  • Maintainers decide whether to add Carbonmark to the SKILL.md plugin table and whether to allowlist x402.klimalabs.com for web_request.
  • An end-to-end retirement through a Coinbase Wallet session is still outstanding. A 1 kg retirement of the cheapest class was quoted at 0.010043 USDC plus network gas, so it is cheap to run during review.
  • Disclosure: this is submitted on behalf of Carbonmark, which operates the endpoint. API docs: https://docs.carbonmark.com/carbonmark-x402/carbonmark-x402

🤖 Generated with Claude Code

Adds skills/wallet-mcp/plugins/carbonmark.md: retire tokenized carbon
credits on Base through Carbonmark's x402 Carbon Retirement API. The
plugin reads supply and prices over HTTP GET, fetches an unsigned
[approve, retire] batch, submits it with send_calls, and resolves the
public Carbonmark certificate for the confirmed transaction.

Appends three new tags (carbon-credits, carbon-retirement, climate) to
the tag vocabulary in plugin-spec.md, as Contribution Scope asks.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@cb-heimdall

Copy link
Copy Markdown

🟡 Heimdall Review Status

Requirement Status More Info
Reviews 🟡 0/1
Denominator calculation
Show calculation
1 if user is bot 0
1 if user is external 0
2 if repo is sensitive 0
From .codeflow.yml 1
Additional review requirements
Show calculation
Max 0
0
From CODEOWNERS 0
Global minimum 0
Max 1
1
1 if commit is unverified 0
1 if authored by an app that is not allowlisted and lacks verified human attribution 0
Sum 1

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

2 participants