{
 "openapi": "3.1.0",
 "info": {
  "title": "UnyKorn Carbon agents",
  "version": "1.0.0",
  "description": "Read-only agents over International Carbon Registry (ICR) public records. Not affiliated with or endorsed by ICR.",
  "contact": {
   "name": "UnyKorn LLC",
   "email": "kevan@unykorn.org"
  }
 },
 "servers": [
  {
   "url": "https://carbon.unykorn.ai"
  }
 ],
 "paths": {
  "/api/icr/project": {
   "get": {
    "operationId": "registry-reader-free",
    "summary": "One ICR project's public record, read straight from its contract on Polygon.",
    "description": "Confirms with the ICR registry contract that an address is a genuine ICR project, then returns its name, methodology, every vintage, the validated estimate, and verified and forward credits in circulation.",
    "parameters": [
     {
      "name": "address",
      "in": "query",
      "required": true,
      "description": "Project contract address on Polygon",
      "schema": {
       "type": "string"
      },
      "example": "0x3c1dec203457334d134f9013fee53776bd40149d"
     }
    ],
    "responses": {
     "200": {
      "description": "Answer with the checks that were run and a SHA-256 fingerprint of the answer.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     }
    }
   }
  },
  "/x402/icr/project": {
   "get": {
    "operationId": "registry-reader-paid",
    "summary": "One ICR project's public record, read straight from its contract on Polygon. (paid, $0.02 per call over x402)",
    "description": "Confirms with the ICR registry contract that an address is a genuine ICR project, then returns its name, methodology, every vintage, the validated estimate, and verified and forward credits in circulation. Send no payment header to receive the price in a 402 response; retry with a PAYMENT-SIGNATURE header.",
    "parameters": [
     {
      "name": "address",
      "in": "query",
      "required": true,
      "description": "Project contract address on Polygon",
      "schema": {
       "type": "string"
      },
      "example": "0x3c1dec203457334d134f9013fee53776bd40149d"
     }
    ],
    "responses": {
     "200": {
      "description": "Answer with the checks that were run and a SHA-256 fingerprint of the answer.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input or malformed payment"
     },
     "402": {
      "description": "Payment required. Price is in the PAYMENT-REQUIRED header and the body."
     },
     "503": {
      "description": "Payments unavailable"
     }
    }
   }
  },
  "/api/icr/retirement": {
   "get": {
    "operationId": "retirement-verifier-free",
    "summary": "Whether a retirement certificate is real, for how many tonnes, and in whose name.",
    "description": "Reads the retirement record for a certificate number from the project's contract on Polygon: tonnes retired, the named beneficiary, the vintage, and whether the retiree still holds the certificate.",
    "parameters": [
     {
      "name": "address",
      "in": "query",
      "required": true,
      "description": "Project contract address on Polygon",
      "schema": {
       "type": "string"
      },
      "example": "0x3c1dec203457334d134f9013fee53776bd40149d"
     },
     {
      "name": "certificate",
      "in": "query",
      "required": true,
      "description": "Retirement certificate number",
      "schema": {
       "type": "string"
      },
      "example": "1"
     }
    ],
    "responses": {
     "200": {
      "description": "Answer with the checks that were run and a SHA-256 fingerprint of the answer.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     }
    }
   }
  },
  "/x402/icr/retirement": {
   "get": {
    "operationId": "retirement-verifier-paid",
    "summary": "Whether a retirement certificate is real, for how many tonnes, and in whose name. (paid, $0.05 per call over x402)",
    "description": "Reads the retirement record for a certificate number from the project's contract on Polygon: tonnes retired, the named beneficiary, the vintage, and whether the retiree still holds the certificate. Send no payment header to receive the price in a 402 response; retry with a PAYMENT-SIGNATURE header.",
    "parameters": [
     {
      "name": "address",
      "in": "query",
      "required": true,
      "description": "Project contract address on Polygon",
      "schema": {
       "type": "string"
      },
      "example": "0x3c1dec203457334d134f9013fee53776bd40149d"
     },
     {
      "name": "certificate",
      "in": "query",
      "required": true,
      "description": "Retirement certificate number",
      "schema": {
       "type": "string"
      },
      "example": "1"
     }
    ],
    "responses": {
     "200": {
      "description": "Answer with the checks that were run and a SHA-256 fingerprint of the answer.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input or malformed payment"
     },
     "402": {
      "description": "Payment required. Price is in the PAYMENT-REQUIRED header and the body."
     },
     "503": {
      "description": "Payments unavailable"
     }
    }
   }
  },
  "/api/carbon/screen": {
   "get": {
    "operationId": "project-screener-free",
    "summary": "A first-pass screen of a project idea: likely sector, methodology routes, red flags.",
    "description": "Matches a plain-language project description against a published rule list. Returns the likely ICR sectoral scope, which methodology routes are open, and the red flags a registry or auditor will raise. Rule-based, not a language model, and not an eligibility decision.",
    "parameters": [
     {
      "name": "description",
      "in": "query",
      "required": true,
      "description": "What the project does, where, and who owns the site",
      "schema": {
       "type": "string"
      },
      "example": "reforestation of 2,000 hectares on leased land in Kenya"
     }
    ],
    "responses": {
     "200": {
      "description": "Answer with the checks that were run and a SHA-256 fingerprint of the answer.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     }
    }
   }
  },
  "/x402/carbon/screen": {
   "get": {
    "operationId": "project-screener-paid",
    "summary": "A first-pass screen of a project idea: likely sector, methodology routes, red flags. (paid, $0.1 per call over x402)",
    "description": "Matches a plain-language project description against a published rule list. Returns the likely ICR sectoral scope, which methodology routes are open, and the red flags a registry or auditor will raise. Rule-based, not a language model, and not an eligibility decision. Send no payment header to receive the price in a 402 response; retry with a PAYMENT-SIGNATURE header.",
    "parameters": [
     {
      "name": "description",
      "in": "query",
      "required": true,
      "description": "What the project does, where, and who owns the site",
      "schema": {
       "type": "string"
      },
      "example": "reforestation of 2,000 hectares on leased land in Kenya"
     }
    ],
    "responses": {
     "200": {
      "description": "Answer with the checks that were run and a SHA-256 fingerprint of the answer.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input or malformed payment"
     },
     "402": {
      "description": "Payment required. Price is in the PAYMENT-REQUIRED header and the body."
     },
     "503": {
      "description": "Payments unavailable"
     }
    }
   }
  },
  "/api/carbon/fees": {
   "get": {
    "operationId": "fee-estimator-free",
    "summary": "What ICR will charge for a project of a given size, from ICR's published fee schedule.",
    "description": "Computes account fees, monthly project fees by stage, issuance fees and the yearly total for a project, from tonnes per year and expected price. The outside auditor is not included.",
    "parameters": [
     {
      "name": "tonnes",
      "in": "query",
      "required": true,
      "description": "Credits expected per year",
      "schema": {
       "type": "string"
      },
      "example": "10000"
     },
     {
      "name": "price",
      "in": "query",
      "required": true,
      "description": "Expected price per tonne in USD",
      "schema": {
       "type": "string"
      },
      "example": "5"
     },
     {
      "name": "kind",
      "in": "query",
      "required": false,
      "description": "\"expost\" (default) or \"exante\"",
      "schema": {
       "type": "string"
      },
      "example": "expost"
     }
    ],
    "responses": {
     "200": {
      "description": "Answer with the checks that were run and a SHA-256 fingerprint of the answer.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     }
    }
   }
  },
  "/x402/carbon/fees": {
   "get": {
    "operationId": "fee-estimator-paid",
    "summary": "What ICR will charge for a project of a given size, from ICR's published fee schedule. (paid, $0.02 per call over x402)",
    "description": "Computes account fees, monthly project fees by stage, issuance fees and the yearly total for a project, from tonnes per year and expected price. The outside auditor is not included. Send no payment header to receive the price in a 402 response; retry with a PAYMENT-SIGNATURE header.",
    "parameters": [
     {
      "name": "tonnes",
      "in": "query",
      "required": true,
      "description": "Credits expected per year",
      "schema": {
       "type": "string"
      },
      "example": "10000"
     },
     {
      "name": "price",
      "in": "query",
      "required": true,
      "description": "Expected price per tonne in USD",
      "schema": {
       "type": "string"
      },
      "example": "5"
     },
     {
      "name": "kind",
      "in": "query",
      "required": false,
      "description": "\"expost\" (default) or \"exante\"",
      "schema": {
       "type": "string"
      },
      "example": "expost"
     }
    ],
    "responses": {
     "200": {
      "description": "Answer with the checks that were run and a SHA-256 fingerprint of the answer.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input or malformed payment"
     },
     "402": {
      "description": "Payment required. Price is in the PAYMENT-REQUIRED header and the body."
     },
     "503": {
      "description": "Payments unavailable"
     }
    }
   }
  },
  "/api/icr/prepare-retirement": {
   "get": {
    "operationId": "retirement-preparer-free",
    "summary": "The exact transaction and message a credit holder must sign to retire on ICR, built to ICR's documented steps.",
    "description": "Builds the retire() call for the holder's own wallet, the finalize message ICR requires, and the warnings that apply. It prepares only: the holder signs and sends. Nothing is retired by this agent.",
    "parameters": [
     {
      "name": "project",
      "in": "query",
      "required": true,
      "description": "Project contract address on Polygon",
      "schema": {
       "type": "string"
      },
      "example": "0x3c1dec203457334d134f9013fee53776bd40149d"
     },
     {
      "name": "vintageTokenId",
      "in": "query",
      "required": true,
      "description": "Token id of the vintage to retire from",
      "schema": {
       "type": "string"
      },
      "example": "1"
     },
     {
      "name": "tonnes",
      "in": "query",
      "required": true,
      "description": "Tonnes to retire",
      "schema": {
       "type": "string"
      },
      "example": "10"
     },
     {
      "name": "beneficiaryAddress",
      "in": "query",
      "required": true,
      "description": "Wallet that receives the certificate",
      "schema": {
       "type": "string"
      },
      "example": "0x0000000000000000000000000000000000000001"
     },
     {
      "name": "beneficiaryName",
      "in": "query",
      "required": true,
      "description": "Name shown on the certificate",
      "schema": {
       "type": "string"
      },
      "example": "Acme Corp"
     },
     {
      "name": "reason",
      "in": "query",
      "required": true,
      "description": "One of the reasons ICR accepts",
      "schema": {
       "type": "string"
      },
      "example": "Voluntary purposes"
     },
     {
      "name": "comment",
      "in": "query",
      "required": false,
      "description": "Comment stored on the certificate",
      "schema": {
       "type": "string"
      },
      "example": "2026 business travel"
     }
    ],
    "responses": {
     "200": {
      "description": "Answer with the checks that were run and a SHA-256 fingerprint of the answer.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     }
    }
   }
  },
  "/x402/icr/prepare-retirement": {
   "get": {
    "operationId": "retirement-preparer-paid",
    "summary": "The exact transaction and message a credit holder must sign to retire on ICR, built to ICR's documented steps. (paid, $0.05 per call over x402)",
    "description": "Builds the retire() call for the holder's own wallet, the finalize message ICR requires, and the warnings that apply. It prepares only: the holder signs and sends. Nothing is retired by this agent. Send no payment header to receive the price in a 402 response; retry with a PAYMENT-SIGNATURE header.",
    "parameters": [
     {
      "name": "project",
      "in": "query",
      "required": true,
      "description": "Project contract address on Polygon",
      "schema": {
       "type": "string"
      },
      "example": "0x3c1dec203457334d134f9013fee53776bd40149d"
     },
     {
      "name": "vintageTokenId",
      "in": "query",
      "required": true,
      "description": "Token id of the vintage to retire from",
      "schema": {
       "type": "string"
      },
      "example": "1"
     },
     {
      "name": "tonnes",
      "in": "query",
      "required": true,
      "description": "Tonnes to retire",
      "schema": {
       "type": "string"
      },
      "example": "10"
     },
     {
      "name": "beneficiaryAddress",
      "in": "query",
      "required": true,
      "description": "Wallet that receives the certificate",
      "schema": {
       "type": "string"
      },
      "example": "0x0000000000000000000000000000000000000001"
     },
     {
      "name": "beneficiaryName",
      "in": "query",
      "required": true,
      "description": "Name shown on the certificate",
      "schema": {
       "type": "string"
      },
      "example": "Acme Corp"
     },
     {
      "name": "reason",
      "in": "query",
      "required": true,
      "description": "One of the reasons ICR accepts",
      "schema": {
       "type": "string"
      },
      "example": "Voluntary purposes"
     },
     {
      "name": "comment",
      "in": "query",
      "required": false,
      "description": "Comment stored on the certificate",
      "schema": {
       "type": "string"
      },
      "example": "2026 business travel"
     }
    ],
    "responses": {
     "200": {
      "description": "Answer with the checks that were run and a SHA-256 fingerprint of the answer.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input or malformed payment"
     },
     "402": {
      "description": "Payment required. Price is in the PAYMENT-REQUIRED header and the body."
     },
     "503": {
      "description": "Payments unavailable"
     }
    }
   }
  },
  "/api/markets/overview": {
   "get": {
    "operationId": "market-snapshot-free",
    "summary": "Live carbon ETF benchmarks, Base Mainnet Klima x402 liquidity, Polygon Carbonmark listings, and verified ICR Polygon census totals.",
    "description": "Aggregates factual market telemetry across listed compliance carbon ETFs (KRBN, KCCA, GRN, ICLN, TAN — no buy/sell signals), live Base Mainnet Klima Protocol USDC pools, live Polygon Carbonmark listings, and verified ICR on-chain totals from docs/census/market-feed.json.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Answer with the checks that were run and a SHA-256 fingerprint of the answer.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     }
    }
   }
  },
  "/x402/markets/overview": {
   "get": {
    "operationId": "market-snapshot-paid",
    "summary": "Live carbon ETF benchmarks, Base Mainnet Klima x402 liquidity, Polygon Carbonmark listings, and verified ICR Polygon census totals. (paid, $0.05 per call over x402)",
    "description": "Aggregates factual market telemetry across listed compliance carbon ETFs (KRBN, KCCA, GRN, ICLN, TAN — no buy/sell signals), live Base Mainnet Klima Protocol USDC pools, live Polygon Carbonmark listings, and verified ICR on-chain totals from docs/census/market-feed.json. Send no payment header to receive the price in a 402 response; retry with a PAYMENT-SIGNATURE header.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Answer with the checks that were run and a SHA-256 fingerprint of the answer.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input or malformed payment"
     },
     "402": {
      "description": "Payment required. Price is in the PAYMENT-REQUIRED header and the body."
     },
     "503": {
      "description": "Payments unavailable"
     }
    }
   }
  },
  "/api/markets/routes": {
   "get": {
    "operationId": "route-verifier-free",
    "summary": "Queries 50 primary-source verified carbon issuance, venue, government grant, bond, and Paris Article 6 routes with citations.",
    "description": "Filters the primary-source verified carbon-routes.json dataset across Issue, Sell, Venue, Wrap, Gov, Finance, and Global/Article 6 tracks by verification status, ICR acceptance, and keyword, returning cautions, check dates, and source URLs.",
    "parameters": [
     {
      "name": "track",
      "in": "query",
      "required": false,
      "description": "Track filter: Issue, Sell, Venue, Wrap, Gov, Finance, Global",
      "schema": {
       "type": "string"
      },
      "example": "Gov"
     },
     {
      "name": "status",
      "in": "query",
      "required": false,
      "description": "Status filter: confirmed, partly, wrong, unverified",
      "schema": {
       "type": "string"
      },
      "example": "confirmed"
     },
     {
      "name": "icr",
      "in": "query",
      "required": false,
      "description": "ICR acceptance filter: yes, no, unknown",
      "schema": {
       "type": "string"
      },
      "example": "yes"
     },
     {
      "name": "q",
      "in": "query",
      "required": false,
      "description": "Keyword search across route name, summary, and caution",
      "schema": {
       "type": "string"
      },
      "example": "Texas"
     }
    ],
    "responses": {
     "200": {
      "description": "Answer with the checks that were run and a SHA-256 fingerprint of the answer.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     }
    }
   }
  },
  "/x402/markets/routes": {
   "get": {
    "operationId": "route-verifier-paid",
    "summary": "Queries 50 primary-source verified carbon issuance, venue, government grant, bond, and Paris Article 6 routes with citations. (paid, $0.05 per call over x402)",
    "description": "Filters the primary-source verified carbon-routes.json dataset across Issue, Sell, Venue, Wrap, Gov, Finance, and Global/Article 6 tracks by verification status, ICR acceptance, and keyword, returning cautions, check dates, and source URLs. Send no payment header to receive the price in a 402 response; retry with a PAYMENT-SIGNATURE header.",
    "parameters": [
     {
      "name": "track",
      "in": "query",
      "required": false,
      "description": "Track filter: Issue, Sell, Venue, Wrap, Gov, Finance, Global",
      "schema": {
       "type": "string"
      },
      "example": "Gov"
     },
     {
      "name": "status",
      "in": "query",
      "required": false,
      "description": "Status filter: confirmed, partly, wrong, unverified",
      "schema": {
       "type": "string"
      },
      "example": "confirmed"
     },
     {
      "name": "icr",
      "in": "query",
      "required": false,
      "description": "ICR acceptance filter: yes, no, unknown",
      "schema": {
       "type": "string"
      },
      "example": "yes"
     },
     {
      "name": "q",
      "in": "query",
      "required": false,
      "description": "Keyword search across route name, summary, and caution",
      "schema": {
       "type": "string"
      },
      "example": "Texas"
     }
    ],
    "responses": {
     "200": {
      "description": "Answer with the checks that were run and a SHA-256 fingerprint of the answer.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input or malformed payment"
     },
     "402": {
      "description": "Payment required. Price is in the PAYMENT-REQUIRED header and the body."
     },
     "503": {
      "description": "Payments unavailable"
     }
    }
   }
  },
  "/api/markets/quote": {
   "get": {
    "operationId": "base-quote-preparer-free",
    "summary": "Fetches a direct 0%-UnyKorn-cut Base Mainnet USDC retirement quote and unsigned calldata from KlimaLabs x402.",
    "description": "Queries x402.klimalabs.com on Base Mainnet (Chain 8453, USDC) for an authoritative retirement quote and unsigned transaction calldata with $0 UnyKorn fee or spread. Prepares only; the caller signs from their own wallet.",
    "parameters": [
     {
      "name": "listingId",
      "in": "query",
      "required": false,
      "description": "Base marketplace listingId (bytes32) from /api/markets/overview",
      "schema": {
       "type": "string"
      },
      "example": "0x2ad99c6f407872d5dc0b28605090ed97e92872cf2dba86ecfeead83a7a27bad2"
     },
     {
      "name": "carbonClass",
      "in": "query",
      "required": false,
      "description": "Klima Protocol carbonClass address (0x...) from /api/markets/overview",
      "schema": {
       "type": "string"
      },
      "example": "0x0008f35758a4318942ecb5d5414116ce7b1ede2d"
     },
     {
      "name": "tonnes",
      "in": "query",
      "required": false,
      "description": "Tonnes to quote (default 100)",
      "schema": {
       "type": "string"
      },
      "example": "100"
     }
    ],
    "responses": {
     "200": {
      "description": "Answer with the checks that were run and a SHA-256 fingerprint of the answer.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     }
    }
   }
  },
  "/x402/markets/quote": {
   "get": {
    "operationId": "base-quote-preparer-paid",
    "summary": "Fetches a direct 0%-UnyKorn-cut Base Mainnet USDC retirement quote and unsigned calldata from KlimaLabs x402. (paid, $0.05 per call over x402)",
    "description": "Queries x402.klimalabs.com on Base Mainnet (Chain 8453, USDC) for an authoritative retirement quote and unsigned transaction calldata with $0 UnyKorn fee or spread. Prepares only; the caller signs from their own wallet. Send no payment header to receive the price in a 402 response; retry with a PAYMENT-SIGNATURE header.",
    "parameters": [
     {
      "name": "listingId",
      "in": "query",
      "required": false,
      "description": "Base marketplace listingId (bytes32) from /api/markets/overview",
      "schema": {
       "type": "string"
      },
      "example": "0x2ad99c6f407872d5dc0b28605090ed97e92872cf2dba86ecfeead83a7a27bad2"
     },
     {
      "name": "carbonClass",
      "in": "query",
      "required": false,
      "description": "Klima Protocol carbonClass address (0x...) from /api/markets/overview",
      "schema": {
       "type": "string"
      },
      "example": "0x0008f35758a4318942ecb5d5414116ce7b1ede2d"
     },
     {
      "name": "tonnes",
      "in": "query",
      "required": false,
      "description": "Tonnes to quote (default 100)",
      "schema": {
       "type": "string"
      },
      "example": "100"
     }
    ],
    "responses": {
     "200": {
      "description": "Answer with the checks that were run and a SHA-256 fingerprint of the answer.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input or malformed payment"
     },
     "402": {
      "description": "Payment required. Price is in the PAYMENT-REQUIRED header and the body."
     },
     "503": {
      "description": "Payments unavailable"
     }
    }
   }
  }
 }
}