API Documentation

MyCO2 Suite turns transactions, activities, flights, freight and imports into verified CO₂e numbers — with the methodology, source, licence, gas basis and GWP version on every response. One base URL, one auth header, JSON in and out.

🤖 AI agent? Everything on this page is also machine-readable: /llms.txt (summary + endpoints), the MCP server (call tools directly), and an A2A agent card. Every JSON response includes meta._links and meta._hints for autonomous navigation.

Base URL

https://api.myco2suite.io/v1

Quickstart

Get a free Sandbox key (1,000 calls/month, no card), then make your first call:

Your first calculation — 500 kWh of German grid electricity

curl https://api.myco2suite.io/v1/activity \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "activity_type": "electricity",
    "quantity": 500,
    "country": "DE"
  }'

# → { "co2e_kg": 164.8, "factor": { "id": "a99fb920-…", "source": "Ember …", "licence": "CC BY 4.0" } }

Authentication

Every request needs your API key in the x-api-key header. Keys look like myco2_live_… and are shown once at creation — store them server-side, never in browser code.

Header

x-api-key: myco2_live_xxxxxxxxxxxxxxxx

Pay-per-call for agents (x402)

AI agents can pay per call in USDC on Base — no signup, no API key — using the x402 protocol. Call any billable endpoint with no key and you get 402 Payment Required with machine-readable payment instructions. Your x402 client pays and retries automatically; the result comes back with an X-PAYMENT-RESPONSE settlement receipt. $0.003 per standard call, $0.008 per CBAM call, charged from the first call (batch endpoints bill per item). Prefer a key + subscription? That's the human path — grab a free Sandbox key instead.

1) Call with no key → 402 with payment requirements (network eip155:8453 = Base)

{
  "x402Version": 2,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "3000",
    "payTo": "0x…",
    "maxTimeoutSeconds": 300,
    "extra": { "name": "USD Coin", "version": "2" }
  }]
}

2) Pay + retry automatically with an x402 client (Node)

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const client = new x402Client();
registerExactEvmScheme(client, { signer: privateKeyToAccount(process.env.WALLET_KEY) });
const fetch402 = wrapFetchWithPayment(fetch, client);

const res = await fetch402("https://api.myco2suite.io/v1/transaction", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ mcc: "5411", spend_amount: 100, currency: "USD", country: "US" }),
});
// → 200 with the carbon result; USDC settled on Base, receipt in X-PAYMENT-RESPONSE

Errors

Errors return a consistent envelope with a machine-readable code, a human message, and — where possible — the offending field and a suggested fix (useful for agents to self-correct).

Error envelope

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One of mcc, bea_code, naics, isic, sic, or nace is required",
    "field": "mcc",
    "fix": "Provide any one industry classification code."
  }
}

Status	Code	Meaning
200	OK	Success
401	UNAUTHORIZED	Missing or invalid API key
402	PAYMENT_REQUIRED	No API key — pay per call in USDC via x402 (the body carries the payment requirements)
403	FORBIDDEN	Key lacks the required scope (e.g. CBAM-only key on a carbon endpoint)
404	NOT_FOUND	No matching factor / unknown code
422	VALIDATION_ERROR	Invalid or missing request fields
429	RATE_LIMIT_EXCEEDED	Monthly call quota exhausted — upgrade or wait for reset
500	INTERNAL_ERROR	Something failed on our side — safe to retry with backoff

How Factor Resolution Works

Every calculation resolves your input to one licensed emission factor, deterministically:

Step	Behaviour
Matching	Activity input is typo-tolerant — close matches resolve to the nearest catalogued activity; exact matches always win over fuzzy ones
Country scoping	With a `country`, country-specific factors are preferred; if none exists, resolution falls back to regional then global factors — the response's coverage metadata tells you which tier answered
Year	Pass `year` to pin a data year; the nearest available year is used and echoed back. Same inputs + same year = the same factor — reproducible for audit
GWP	`gwp_version` (AR4 / AR5 / AR6) converts gas-level data to your reporting standard; the applied version is always stated in the response
Audit	Every response carries a permanent `factor.id` (re-fetch the exact factor any time via `/v1/factor?id=`) and `meta.dataset_release` — record both and any number can be reproduced later

Versioning & Data Releases

API stability: everything lives under /v1. Changes are additive — new endpoints, new optional parameters, new response fields. Anything breaking ships as a new version path with notice; /v1 keeps working.

Data releases: the factor database is updated in waves. Every response tells you exactly which release answered via meta.dataset_release, and the exact factor used via factor.id — record both and any number can be reproduced and defended later (re-fetch the factor any time with /v1/factor?id=).

Release	What changed
2026.07current	223,850 licensed factors · DEFRA 2025 conversion factors · refrigerants exact to IPCC AR6 Table 7.SM.7 with AR4/AR5/AR6 selection · CBAM default values per IR (EU) 2025/2621 (22,292 rows, all in-scope goods computable) · universal electricity coverage (every country resolves to its own grid average or the world average) · permanent factor IDs on every response

POST

/v1/transaction

Spend-based emissions (Scope 3.1). Provide a spend amount, currency, country, and any one industry classification code — mcc, bea_code, naics, isic, sic or nace. (For Canada, a plain commodity description also works.)

Request

{
  "spend_amount": 100.50,
  "currency": "USD",
  "country": "US",
  "mcc": "5411"
}

Parameter	Type	Description
spend_amountrequired	number	Spend in the given currency
currencyrequired	string	ISO 4217 code (USD, EUR, GBP…)
countryrequired	string	ISO 3166-1 alpha-2 country code
mcc	string	Merchant Category Code (4 digits). Provide any one of mcc / bea_code / naics / isic / sic / nace.
bea_code	string	US BEA input-output sector (5–7 alphanumeric)
naics	string	NAICS (6 digits)
isic	string	ISIC (4 digits)
sic	string	SIC (2–5 digits)
nace	string	NACE (e.g. 47.11)
commodity	string	Plain-language commodity description (Canada only)
spend_year	number	Year the money was spent — enables inflation adjustment
adjust_for_inflation	boolean	Deflate spend to the factor's price year (World Bank deflators)
display_currency	string	Return converted amounts in this currency
gwp_version	string	AR4, AR5 or AR6 — report on the GWP standard you need

Try it out

x-api-key

spend_amount

currency

country

mcc

Response

{
  "co2e_kg": 12.76,
  "factor": {
    "id": "f874f0e4-9922-428a-9202-b6c81d883ffe",   // permanent — re-fetch via /v1/factor?id=
    "value": 0.127, "unit": "kgCO2e/USD",
    "methodology": "US EPA EEIO v2.0",
    "source": "EPA 2025",
    "licence": "CC BY 4.0",
    "gas_basis": "CO2e",
    "gwp_version": "IPCC AR6"
  },
  "meta": { "dataset_release": "2026.07", "_links": { ... }, "_hints": { ... } }
}

POST

/v1/activity

Activity-based emissions from a physical quantity — litres of fuel, kWh of electricity, kg of material — across 1,000+ activity types. Input is typo-tolerant: close matches resolve to the nearest licensed factor.

Request

{
  "activity_type": "diesel",
  "quantity": 40,
  "country": "GB",
  "gwp_version": "AR6"
}

Parameter	Type	Description
activity_typerequired	string	What happened — e.g. `diesel`, `electricity`, `natural_gas`. Browse via /v1/activity-types
quantityrequired	number	Amount, in the activity's native unit (litres, kWh, kg — shown on the factor)
country	string	ISO 3166-1 alpha-2 — selects country-specific factors (recommended)
year	number	Data year — nearest available year is used
gwp_version	string	AR4, AR5 or AR6

Try it out

x-api-key

activity_type

quantity

country

gwp_version

GET

/v1/factor

Look up the underlying emission factor itself — value, unit, methodology, source, licence, gas basis and GWP version — without running a calculation. Query by activity type, any industry code, or re-fetch an exact factor by its id.

Request

GET /v1/factor?activity_type=electricity&country=DE

# by industry code:
GET /v1/factor?mcc=5411&country=US

# exact re-fetch for audit — the factor.id from any calculation response:
GET /v1/factor?id=a99fb920-ff2c-4fe5-a74b-450f337fa0c6

Parameter	Type	Description
id	uuid	Exact re-fetch of the factor a previous response used — the same `id` always returns the same factor (audit reproducibility)
activity_type	string	Activity slug (or use an industry code below)
mcc / bea_code / naics / isic / sic / nace	string	Any one industry classification code
country	string	ISO country code
year	number	Data year
gwp_version	string	AR4, AR5 or AR6

Try it out

x-api-key

activity_type

country

POST

/v1/flight

Great-circle flight emissions between two airports (IATA codes) or coordinates, with cabin class, passenger count and optional radiative forcing.

Request

{
  "origin": "LHR",
  "destination": "JFK",
  "cabin_class": "economy",
  "passengers": 1,
  "trip_type": "round_trip",
  "include_radiative_forcing": true
}

Parameter	Type	Description
originrequired	string	IATA airport code (or `origin_lat` + `origin_lon`)
destinationrequired	string	IATA airport code (or `destination_lat` + `destination_lon`)
cabin_class	string	economy, premium_economy, business, first
passengers	number	Number of passengers (default 1)
trip_type	string	one_way (default) or round_trip
include_radiative_forcing	boolean	Apply the radiative-forcing uplift for high-altitude effects

Try it out

x-api-key

origin

destination

cabin_class

passengers

POST

/v1/freight

Freight emissions by mode — road, rail, sea or air — from origin/destination (or coordinates) and cargo weight. Multi-leg journeys supported via legs.

Request

{
  "mode": "road",
  "origin": "Rotterdam",
  "destination": "Munich",
  "weight_kg": 12000,
  "vehicle_type": "hgv"
}

Parameter	Type	Description
moderequired	string	road, rail, sea or air
origin / destinationrequired	string	Place names, or `_lat`/`_lon` coordinates
weight_kgrequired	number	Cargo weight in kilograms
vehicle_type	string	Mode-specific vehicle/vessel option
legs	array	Multi-leg journeys — an array of leg objects (mode + points per leg)

Try it out

x-api-key

mode

weight_kg

origin

destination

GET

/v1/activity-types

Search and browse the activity catalogue — what you can calculate, in which countries and units. Useful as a discovery step before calling /v1/activity.

Request

GET /v1/activity-types?q=cement&country=DE&limit=20

Parameter	Type	Description
q	string	Free-text search
category	string	Filter by category (fuels, electricity, materials…)
country	string	Only types available for this country
year	number	Only types with data for this year
limit	number	Max results

Try it out

x-api-key

country

limit

POST

/v1/activity/batch

Up to 100 activity calculations in one request. Each item is billed as one API call and returns its own result or error — one bad item never fails the batch.

Request

{
  "calculations": [
    { "id": "a1", "activity_type": "diesel", "quantity": 40, "country": "GB" },
    { "id": "a2", "activity_type": "electricity", "quantity": 500, "country": "DE" }
  ]
}

CBAM has its own batch at POST /v1/cbam/batch — same pattern with a shipments array (max 100). See CBAM.

POST

/v1/budget

Running total of the emissions calculated with your API key over a period, compared against a science-based ~2 tCO2e/year budget. Best suited to tracking a single entity's own footprint.

Request

{ "period": "month" }   // day | week | month | year

POST

/v1/cbam

EU CBAM import liability from a CN code, country of origin and weight — covering iron & steel, aluminium, cement, fertilisers and hydrogen. Uses official default values, or your verified MRV data; nets off carbon prices already paid at origin (Art. 9); can project liability across the 2026–2034 phase-in.

Request

{
  "cn_code": "72083900",
  "origin_country": "IN",
  "weight_tonnes": 25,
  "year": 2026,
  "carbon_price_paid_eur_per_tonne": 0,
  "project": true
}

Parameter	Type	Description
cn_coderequired	string	8-digit EU Combined Nomenclature code (see CN Codes)
origin_countryrequired	string	ISO 3166-1 alpha-2 country of origin
weight_tonnesrequired	number	Net mass of the imported goods
year	number	Import year — drives the phase-in factor
actual_emissions_tco2e_per_t	number	Your verified MRV emissions intensity (otherwise official defaults apply)
carbon_price_paid_eur_per_tonne	number	Carbon price already paid at origin (deducted, Art. 9)
carbon_price_rebate_eur_per_tonne	number	Rebates received — the deducted price must be net of rebates
project	boolean	Return a year-by-year 2026–2034 liability projection

CBAM calls are included in Pro and Scale subscriptions, or $0.008/call pay-as-you-go on any tier. Electricity imports are excluded (source-licence restrictions) — the five covered sectors are iron & steel, aluminium, cement, fertilisers and hydrogen.

Try it out

x-api-key

cn_code

origin_country

weight_tonnes

year

GET

/v1/cbam/cn-codes

Search the EU CN 2026 catalogue (9,800+ codes) and check which goods are in CBAM scope.

Request

GET /v1/cbam/cn-codes?q=steel&cbam_only=true&limit=20

Parameter	Type	Description
q	string	Search by code prefix or description
sector	string	Filter by CBAM sector
cbam_only	boolean	Only return in-scope goods
limit	number	Max results

Try it out

x-api-key

cbam_only

limit

GET

/v1/cbam/carbon-prices

Reference carbon prices — live EU ETS plus national carbon-price schemes — for Art. 9 deductions and scenario modelling.

Request

GET /v1/cbam/carbon-prices?country=EU&type=ets

Try it out

x-api-key

country

For AI Agents

MyCO2 Suite is agent-native: an AI agent can discover, understand and call the API without human integration. Three protocols are live, plus /llms.txt for discovery. Responses carry meta._links (related actions) and meta._hints (what to do next), and error responses include a fix field agents can act on.

MCP Server

Streamable-HTTP Model Context Protocol server exposing 11 tools. Authenticate with your API key in the x-api-key header.

MCP endpoint + tools

https://api.myco2suite.io/v1/mcp

Tools:
  calculate_emissions_transaction    calculate_emissions_activity
  calculate_emissions_activity_batch calculate_emissions_flight
  calculate_emissions_freight        calculate_cbam_liability
  calculate_cbam_batch               lookup_cbam_cn_codes
  lookup_cbam_carbon_prices          lookup_emission_factors
  list_activity_types

A2A — Agent Card

A published agent card describes the service's capabilities for agent-to-agent discovery.

Agent card

GET https://api.myco2suite.io/.well-known/agent-card.json

ACP — Agent Communication Protocol

ACP endpoints live under /v1/acp/* — agent discovery plus the same calculation capabilities over the ACP envelope.

ACP root

GET https://api.myco2suite.io/v1/acp