{"openapi":"3.1.0","info":{"title":"Hydro dMRV API","version":"hydro-dmrv-engine@3.1.0","summary":"Digital MRV for grid-connected hydropower on Hedera (Verra VMR0017 with ACM0002, CDM AMS-I.D / ACM0002, VT0011 / TOOL07, TOOL03)","description":"Verify and quantify monitoring periods, read the on-chain registry, reproduce any issuance from HCS data, and prepare unsigned purchases for your own wallet. The tokens are units this registry issues. They are not Verra credits. The same capabilities are MCP tools at /api/mcp; where a tool does what an endpoint does, the operationId is the tool's name. Units: energy in Wh, emissions in g CO2e, credits in kg (1 token = 1 t CO2e). Methodology: /methodology and the MCP resource hydro-dmrv://methodology.","license":{"name":"MIT","identifier":"MIT"}},"servers":[{"url":"https://hydro-dmrv.vercel.app"}],"security":[],"externalDocs":{"description":"Guide for AI agents","url":"https://hydro-dmrv.vercel.app/llms.txt"},"tags":[{"name":"methodology","description":"Project design, TOOL07 / VT0011 grid factor, design documents"},{"name":"monitoring","description":"Sample telemetry, verification, monitoring records"},{"name":"verification","description":"VVB verification of monitoring records; only an approval issues credits"},{"name":"registry","description":"On-chain state on chain 296"},{"name":"evidence","description":"Audit and reproduction from HCS through the public mirror node"},{"name":"market","description":"Listings, unsigned purchases, retirements and certificates"},{"name":"guardian","description":"Hedera Guardian bridge: signed cross-check VCs and evidence verification (docs/GUARDIAN.md)"}],"paths":{"/api/methodology/compare":{"post":{"operationId":"compare_guardian_report","tags":["guardian"],"summary":"Recompute a Guardian monitoring figure","description":"Runs a Guardian VMR0017 monitoring report through the same integers the registry uses. Returns MATCH, MISMATCH, or NOT_COMPARABLE, plus the tonne difference. Does not mint and does not sign. No API key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"field3":{"type":["number","string"]},"field4":{"type":["number","string"]},"field5":{"type":["number","string"]},"field6":{"type":["number","string"]},"field7":{"type":["number","string"]},"field24":{"type":["number","string"]},"field25":{"type":["number","string"]},"field26":{"type":["number","string"]},"field27":{"type":["number","string"]}},"required":["field3","field4","field5","field6","field7","field24","field25","field26","field27"],"additionalProperties":{}}}}},"responses":{"200":{"description":"decision, oursT, theirsT, deltaTonnes, notes","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/methodology/assess":{"post":{"operationId":"assess_project","tags":["methodology"],"summary":"Assess a hydro project design","description":"Applicability, reservoir power density and PE_HP rate, baseline, TOOL07 or VT0011 combined margin, VT0008 additionality, TOOL03 fuel coefficient, leakage and crediting period. Returns the integers registerPlant expects and the designHash.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plantId":{"type":"string","minLength":1,"maxLength":31},"name":{"type":"string","minLength":1,"maxLength":80},"methodology":{"type":"string","enum":["ACM0002","AMS-I.D","VMR0017"]},"hostCountry":{"type":"string","pattern":"^[A-Za-z]{2}$"},"authorizedCapacityKw":{"type":"integer","minimum":0,"maximum":9007199254740991},"safeguards":{"type":"object","properties":{"environmentalImpactAssessment":{"type":"string","minLength":8,"maxLength":300},"stakeholderConsultation":{"type":"string","minLength":8,"maxLength":300},"noNetHarm":{"type":"string","minLength":8,"maxLength":300}},"required":["environmentalImpactAssessment","stakeholderConsultation","noNetHarm"]},"additionality":{"type":"object","properties":{"tool":{"type":"string","const":"VT0008"},"regulatorySurplus":{"type":"boolean"},"regulatorySurplusBasis":{"type":"string","minLength":8,"maxLength":500},"investment":{"type":"object","properties":{"analysis":{"type":"string","const":"benchmark"},"irr":{"type":"string","enum":["project","equity"]},"irrWithoutCreditsPct":{"type":"number"},"irrWithCreditsPct":{"type":"number"},"benchmarkPct":{"type":"number"},"sensitivityConfirms":{"type":"boolean"},"decisiveIncrease":{"type":"boolean"},"sensitivity":{"minItems":2,"maxItems":40,"type":"array","items":{"type":"object","properties":{"parameter":{"type":"string","minLength":1,"maxLength":80},"variationPct":{"type":"number","minimum":-100,"maximum":100},"irrPct":{"type":"number"}},"required":["parameter","variationPct","irrPct"]}},"sensitivityProbability":{"type":"string","maxLength":500}},"required":["analysis","irr","irrWithoutCreditsPct","irrWithCreditsPct","benchmarkPct","sensitivityConfirms","decisiveIncrease","sensitivity"]},"commonPractice":{"type":"object","properties":{"nAll":{"type":"integer","minimum":0,"maximum":9007199254740991},"nDiff":{"type":"integer","minimum":0,"maximum":9007199254740991},"basis":{"type":"string","minLength":1,"maxLength":500},"geographicArea":{"type":"string","minLength":1,"maxLength":200},"capacityBandPct":{"type":"number","minimum":50,"maximum":200}},"required":["nAll","nDiff","basis","geographicArea","capacityBandPct"]},"assessedBy":{"type":"string","maxLength":120},"reportUri":{"type":"string","maxLength":300}},"required":["tool","regulatorySurplus","regulatorySurplusBasis","investment","commonPractice"]},"projectType":{"type":"string","enum":["greenfield","retrofit","capacity-addition"]},"capacityKw":{"type":"integer","minimum":1,"maximum":9007199254740991},"baselineCapacityKw":{"type":"integer","minimum":0,"maximum":9007199254740991},"reservoirAreaM2":{"type":"integer","minimum":0,"maximum":9007199254740991},"baselineReservoirAreaM2":{"type":"integer","minimum":0,"maximum":9007199254740991},"historicalGenerationMwh":{"maxItems":50,"type":"array","items":{"type":"number","minimum":0}},"historicalYears":{"maxItems":50,"type":"array","items":{"type":"object","properties":{"year":{"type":"integer","minimum":1950,"maximum":2100},"mwh":{"type":"number","minimum":0}},"required":["year","mwh"]}},"baselineRetrofitDate":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"historical":{"type":"object","properties":{"commissionedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"referenceStart":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"noChange":{"type":"boolean"},"remainingLifetimeBasis":{"type":"string","minLength":1,"maxLength":500}},"required":["commissionedAt","referenceStart","noChange","remainingLifetimeBasis"]},"equipmentTransferred":{"type":"boolean"},"endOfLifeRefurbishment":{"type":"boolean"},"baselineAlternatives":{"type":"object","properties":{"p1":{"type":"boolean"},"p2":{"type":"boolean"},"p3":{"type":"boolean"},"outcome":{"type":"string","enum":["P1","P2","P3"]}},"required":["p1","p2","p3","outcome"]},"onSiteFuel":{"anyOf":[{"type":"object","properties":{"fuel":{"type":"string","enum":["crude-oil","motor-gasoline","gas-diesel-oil","residual-fuel-oil","lpg","natural-gas","anthracite","other-bituminous-coal","sub-bituminous-coal","lignite"]},"ncvGjPerT":{"type":"number","exclusiveMinimum":0},"co2KgPerTj":{"type":"number","exclusiveMinimum":0}},"required":["fuel"]},{"type":"null"}]},"crediting":{"type":"object","properties":{"start":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"years":{"anyOf":[{"type":"number","const":5},{"type":"number","const":7},{"type":"number","const":10}]},"period":{"anyOf":[{"type":"number","const":1},{"type":"number","const":2},{"type":"number","const":3}]}},"required":["start","years","period"]},"renewal":{"type":"object","properties":{"baselineValidity":{"type":"string","minLength":1,"maxLength":300},"regulatorySurplus":{"type":"string","minLength":1,"maxLength":300},"previousYears":{"anyOf":[{"type":"number","const":5},{"type":"number","const":7},{"type":"number","const":10}]},"requestedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["baselineValidity","regulatorySurplus"]},"registrationRequest":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"grid":{"oneOf":[{"type":"object","properties":{"source":{"type":"string","const":"tool07"},"input":{"type":"object","properties":{"system":{"type":"string","minLength":1,"maxLength":120},"units":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40},"source":{"type":"string","enum":["crude-oil","motor-gasoline","gas-diesel-oil","residual-fuel-oil","lpg","natural-gas","anthracite","other-bituminous-coal","sub-bituminous-coal","lignite","hydro","wind","solar","geothermal","nuclear","biomass"]},"commissioned":{"type":"integer","minimum":1900,"maximum":2100},"cdm":{"type":"boolean"},"efficiency":{"type":"number","exclusiveMinimum":0,"maximum":1},"tool09Efficiency":{"type":"number","exclusiveMinimum":0,"maximum":1},"fuels":{"maxItems":6,"type":"array","items":{"type":"string","enum":["crude-oil","motor-gasoline","gas-diesel-oil","residual-fuel-oil","lpg","natural-gas","anthracite","other-bituminous-coal","sub-bituminous-coal","lignite"]}}},"required":["id","source","commissioned"]}},"years":{"minItems":3,"maxItems":3,"type":"array","items":{"type":"object","properties":{"year":{"type":"integer","minimum":1990,"maximum":2100},"units":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"mwh":{"type":"number","minimum":0},"fuelT":{"type":"number","minimum":0},"pbwaMwh":{"type":"number","minimum":0}},"required":["mwh"]}},"lambda":{"type":"number","minimum":0,"maximum":1},"importsMwh":{"type":"number","minimum":0},"annexIImportsMwh":{"type":"number","minimum":0}},"required":["year","units"]}},"lowCostMustRunShare":{"minItems":5,"maxItems":5,"type":"array","items":{"type":"number","minimum":0,"maximum":1}},"operatingMargin":{"type":"string","enum":["simple","simple-adjusted","average"]}},"required":["system","units","years","lowCostMustRunShare","operatingMargin"]}},"required":["source","input"]},{"type":"object","properties":{"source":{"type":"string","const":"published"},"efTPerMwh":{"type":"number","exclusiveMinimum":0,"maximum":2},"omTPerMwh":{"type":"number","minimum":0,"maximum":2},"bmTPerMwh":{"type":"number","minimum":0,"maximum":2},"reference":{"type":"string","minLength":1,"maxLength":200},"validFrom":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"validTo":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"fixedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["source","efTPerMwh","reference"]}]},"hydraulics":{"type":"object","properties":{"maxFlowM3s":{"type":"number","exclusiveMinimum":0},"maxHeadM":{"type":"number","exclusiveMinimum":0},"minEfficiency":{"type":"number","exclusiveMinimum":0,"maximum":1},"maxEfficiency":{"type":"number","exclusiveMinimum":0,"maximum":1}},"required":["maxFlowM3s","maxHeadM","minEfficiency","maxEfficiency"]}},"required":["plantId","name","projectType","capacityKw","baselineCapacityKw","reservoirAreaM2","baselineReservoirAreaM2","equipmentTransferred","onSiteFuel","crediting","grid","hydraulics"]}}}},"responses":{"200":{"description":"Assessment, registration integers and designHash","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/methodology/grid-emission-factor":{"post":{"operationId":"calculate_grid_emission_factor","tags":["methodology"],"summary":"TOOL07 or VT0011 combined margin from per-unit grid data","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"system":{"type":"string","minLength":1,"maxLength":120},"units":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40},"source":{"type":"string","enum":["crude-oil","motor-gasoline","gas-diesel-oil","residual-fuel-oil","lpg","natural-gas","anthracite","other-bituminous-coal","sub-bituminous-coal","lignite","hydro","wind","solar","geothermal","nuclear","biomass"]},"commissioned":{"type":"integer","minimum":1900,"maximum":2100},"cdm":{"type":"boolean"},"efficiency":{"type":"number","exclusiveMinimum":0,"maximum":1},"tool09Efficiency":{"type":"number","exclusiveMinimum":0,"maximum":1},"fuels":{"maxItems":6,"type":"array","items":{"type":"string","enum":["crude-oil","motor-gasoline","gas-diesel-oil","residual-fuel-oil","lpg","natural-gas","anthracite","other-bituminous-coal","sub-bituminous-coal","lignite"]}}},"required":["id","source","commissioned"]}},"years":{"minItems":3,"maxItems":3,"type":"array","items":{"type":"object","properties":{"year":{"type":"integer","minimum":1990,"maximum":2100},"units":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"mwh":{"type":"number","minimum":0},"fuelT":{"type":"number","minimum":0},"pbwaMwh":{"type":"number","minimum":0}},"required":["mwh"]}},"lambda":{"type":"number","minimum":0,"maximum":1},"importsMwh":{"type":"number","minimum":0},"annexIImportsMwh":{"type":"number","minimum":0}},"required":["year","units"]}},"lowCostMustRunShare":{"minItems":5,"maxItems":5,"type":"array","items":{"type":"number","minimum":0,"maximum":1}},"operatingMargin":{"type":"string","enum":["simple","simple-adjusted","average"]},"projectKind":{"default":"hydro","type":"string","enum":["hydro","wind-solar"]},"creditingPeriod":{"default":1,"anyOf":[{"type":"number","const":1},{"type":"number","const":2},{"type":"number","const":3}]},"tool":{"default":"TOOL07","type":"string","enum":["TOOL07","VT0011"]}},"required":["system","units","years","lowCostMustRunShare","operatingMargin"]}}}},"responses":{"200":{"description":"Operating margin, build-margin sample group, weights and combined margin","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/methodology/projects":{"get":{"operationId":"list_project_designs","tags":["methodology"],"summary":"Demo design documents with the on-chain designHash check","responses":{"200":{"description":"Design documents","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/methodology/projects/{plantId}":{"get":{"operationId":"get_project_design","tags":["methodology"],"summary":"One design document","description":"`?raw=1` returns the exact bytes whose SHA-256 is the plant's on-chain designHash.","parameters":[{"name":"plantId","in":"path","required":true,"description":"Plant id, e.g. HYDRO-DEMO-01","schema":{"type":"string"}},{"name":"raw","in":"query","required":false,"description":"1 for the hashed bytes","schema":{"type":"string"}}],"responses":{"200":{"description":"Design document and assessment","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/mrv/scenarios":{"get":{"operationId":"list_scenarios","tags":["monitoring"],"summary":"Sample scenarios, demo plants and their metering records","responses":{"200":{"description":"Scenarios, plants, metering including meter addresses","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/mrv/scenarios/{name}":{"get":{"operationId":"generate_sample_telemetry","tags":["monitoring"],"summary":"Signed sample monitoring data: a ready /api/mrv/verify body","parameters":[{"name":"name","in":"path","required":true,"description":"Scenario","schema":{"type":"string","enum":["healthy","reservoir","diesel-backup","calibration-overdue","meter-drift","data-gaps","spikes","polluted","inflated","replay","tampered"]}},{"name":"hours","in":"query","required":false,"description":"Hours of hourly data (1–168)","schema":{"type":"integer","minimum":1,"maximum":168,"default":24}},{"name":"plant","in":"query","required":false,"description":"Demo plant id","schema":{"type":"string","default":"HYDRO-DEMO-01"}}],"responses":{"200":{"description":"{ plant, metering, readings, signature }","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/mrv/engines":{"get":{"operationId":"list_methodology_engines","tags":["monitoring"],"summary":"Methodology engines: documents implemented and the on-chain IMethodology module of each","responses":{"200":{"description":"{ engines: [{ id, title, documents, scope, contract }] }","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/mrv/engines/{id}":{"get":{"operationId":"get_methodology_engine","tags":["monitoring"],"summary":"One engine and a ready-to-verify example monitoring period","parameters":[{"name":"id","in":"path","required":true,"description":"Engine id","schema":{"type":"string","enum":["hydro-vmr0017","renewable-vmr0017"]}}],"responses":{"200":{"description":"{ id, title, documents, scope, contract, example }","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/mrv/engines/{id}/verify":{"post":{"operationId":"verify_with_engine","tags":["monitoring"],"summary":"Verify with one engine: decision, findings with clauses, the methodology's data and parameters table","parameters":[{"name":"id","in":"path","required":true,"description":"Engine id","schema":{"type":"string","enum":["hydro-vmr0017","renewable-vmr0017"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"{ engine, methodology, decision, reasoning, stages[], findings[], reductionG, unitsMinted, monitoring }","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/mrv/verify":{"post":{"operationId":"verify_telemetry","tags":["monitoring"],"summary":"Verify and quantify a monitoring period (writes nothing)","description":"Five stages (applicability, QA/QC including the meter signature, physics, quantification, safeguards) and ER = BE − PE − LE in exact integers. Returns the report, the HCS report message, reportHash and the hash of the data message it commits to.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"readings":{"minItems":1,"maxItems":2000,"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"intervalMinutes":{"type":"integer","exclusiveMinimum":0,"maximum":1440},"generationKwh":{"type":"number","minimum":0},"exportKwh":{"type":"number","minimum":0},"importKwh":{"type":"number","minimum":0},"checkExportKwh":{"type":"number","minimum":0},"flowRateM3s":{"type":"number","minimum":0},"headM":{"type":"number","minimum":0},"fuelKg":{"type":"number","minimum":0},"captiveKwh":{"type":"number","minimum":0},"ph":{"type":"number","minimum":0,"maximum":14},"turbidityNtu":{"type":"number","minimum":0},"temperatureC":{"type":"number","minimum":-50,"maximum":80}},"required":["timestamp","intervalMinutes","generationKwh","exportKwh","flowRateM3s","headM"]}},"plant":{"type":"object","properties":{"plantId":{"type":"string","minLength":1,"maxLength":31},"name":{"type":"string","maxLength":80},"methodology":{"type":"string","enum":["ACM0002","AMS-I.D","VMR0017"]},"design":{"type":"object","properties":{"projectType":{"type":"integer","minimum":0,"maximum":2},"methodology":{"default":0,"type":"integer","minimum":0,"maximum":1},"hostCountry":{"default":"","type":"string","pattern":"^([A-Z]{2})?$"},"capacityKw":{"type":"integer","minimum":1,"maximum":9007199254740991},"authorizedCapacityKw":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"baselineCapacityKw":{"type":"integer","minimum":0,"maximum":9007199254740991},"reservoirAreaM2":{"type":"integer","minimum":0,"maximum":9007199254740991},"baselineReservoirAreaM2":{"type":"integer","minimum":0,"maximum":9007199254740991},"efGridGPerMwh":{"type":"integer","minimum":0,"maximum":2000000},"fuelCoefGPerTonne":{"type":"integer","minimum":0,"maximum":9007199254740991},"baselineWh":{"type":"integer","minimum":0,"maximum":9007199254740991},"baselineEndsAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"creditingStart":{"type":"integer","minimum":0,"maximum":9007199254740991},"creditingEnd":{"type":"integer","minimum":0,"maximum":9007199254740991},"registrationRequestedAt":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["projectType","capacityKw","baselineCapacityKw","reservoirAreaM2","baselineReservoirAreaM2","efGridGPerMwh","fuelCoefGPerTonne","baselineWh","baselineEndsAt","creditingStart","creditingEnd"]},"hydraulics":{"type":"object","properties":{"maxFlowM3s":{"type":"number","exclusiveMinimum":0},"maxHeadM":{"type":"number","exclusiveMinimum":0},"minEfficiency":{"type":"number","exclusiveMinimum":0,"maximum":1},"maxEfficiency":{"type":"number","exclusiveMinimum":0,"maximum":1}},"required":["maxFlowM3s","maxHeadM","minEfficiency","maxEfficiency"]}},"required":["plantId","name","methodology","design","hydraulics"]},"metering":{"type":"object","properties":{"mainMeterAccuracyPct":{"type":"number","exclusiveMinimum":0,"maximum":5},"checkMeterAccuracyPct":{"type":"number","exclusiveMinimum":0,"maximum":5},"calibrationValidUntil":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"flowUncertaintyPct":{"type":"number","minimum":0,"maximum":50},"calibrationCertificateSha256":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"},"invoiceCrossCheckSha256":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"},"lastCalibrationUncertaintyPct":{"type":"number","minimum":0,"maximum":5},"deviceAddress":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},"required":["mainMeterAccuracyPct","checkMeterAccuracyPct","calibrationValidUntil","flowUncertaintyPct"]},"ledger":{"type":"object","properties":{"attestations":{"type":"integer","minimum":0,"maximum":9007199254740991},"balanceG":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"creditingYear":{"type":"integer","minimum":0,"maximum":9007199254740991},"yearNetWh":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["attestations","balanceG","creditingYear","yearNetWh"]},"signature":{"type":"string","pattern":"^0x[0-9a-fA-F]{130}$"},"domain":{"type":"object","properties":{"chainId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"registry":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"sequence":{"type":"integer","minimum":0,"maximum":4294967295}},"required":["chainId","registry"]}},"required":["readings"]}}}},"responses":{"200":{"description":"Verification report and HCS anchors","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/mrv/record":{"post":{"operationId":"record_monitoring","tags":["monitoring"],"summary":"Record a monitoring period on DmrvRegistry (issues nothing)","description":"Only for the plant operator's server: requires the MRV_API_KEY bearer token, and the server key must be the plant's operator or the reporter it named. Verifies the readings against the registered design and module ledger, checks the project's module computes the same ER, dry-runs recordMonitoring, then publishes readings and report to HCS and records the period with the meter's EIP-712 signature. Returns the record's sequence and hash-chain head.","security":[{"mrvApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"readings":{"minItems":1,"maxItems":2000,"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"intervalMinutes":{"type":"integer","exclusiveMinimum":0,"maximum":1440},"generationKwh":{"type":"number","minimum":0},"exportKwh":{"type":"number","minimum":0},"importKwh":{"type":"number","minimum":0},"checkExportKwh":{"type":"number","minimum":0},"flowRateM3s":{"type":"number","minimum":0},"headM":{"type":"number","minimum":0},"fuelKg":{"type":"number","minimum":0},"captiveKwh":{"type":"number","minimum":0},"ph":{"type":"number","minimum":0,"maximum":14},"turbidityNtu":{"type":"number","minimum":0},"temperatureC":{"type":"number","minimum":-50,"maximum":80}},"required":["timestamp","intervalMinutes","generationKwh","exportKwh","flowRateM3s","headM"]}},"plant":{"type":"object","properties":{"plantId":{"type":"string","minLength":1,"maxLength":31},"name":{"type":"string","maxLength":80},"methodology":{"type":"string","enum":["ACM0002","AMS-I.D","VMR0017"]},"design":{"type":"object","properties":{"projectType":{"type":"integer","minimum":0,"maximum":2},"methodology":{"default":0,"type":"integer","minimum":0,"maximum":1},"hostCountry":{"default":"","type":"string","pattern":"^([A-Z]{2})?$"},"capacityKw":{"type":"integer","minimum":1,"maximum":9007199254740991},"authorizedCapacityKw":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"baselineCapacityKw":{"type":"integer","minimum":0,"maximum":9007199254740991},"reservoirAreaM2":{"type":"integer","minimum":0,"maximum":9007199254740991},"baselineReservoirAreaM2":{"type":"integer","minimum":0,"maximum":9007199254740991},"efGridGPerMwh":{"type":"integer","minimum":0,"maximum":2000000},"fuelCoefGPerTonne":{"type":"integer","minimum":0,"maximum":9007199254740991},"baselineWh":{"type":"integer","minimum":0,"maximum":9007199254740991},"baselineEndsAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"creditingStart":{"type":"integer","minimum":0,"maximum":9007199254740991},"creditingEnd":{"type":"integer","minimum":0,"maximum":9007199254740991},"registrationRequestedAt":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["projectType","capacityKw","baselineCapacityKw","reservoirAreaM2","baselineReservoirAreaM2","efGridGPerMwh","fuelCoefGPerTonne","baselineWh","baselineEndsAt","creditingStart","creditingEnd"]},"hydraulics":{"type":"object","properties":{"maxFlowM3s":{"type":"number","exclusiveMinimum":0},"maxHeadM":{"type":"number","exclusiveMinimum":0},"minEfficiency":{"type":"number","exclusiveMinimum":0,"maximum":1},"maxEfficiency":{"type":"number","exclusiveMinimum":0,"maximum":1}},"required":["maxFlowM3s","maxHeadM","minEfficiency","maxEfficiency"]}},"required":["plantId","name","methodology","design","hydraulics"]},"metering":{"type":"object","properties":{"mainMeterAccuracyPct":{"type":"number","exclusiveMinimum":0,"maximum":5},"checkMeterAccuracyPct":{"type":"number","exclusiveMinimum":0,"maximum":5},"calibrationValidUntil":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"flowUncertaintyPct":{"type":"number","minimum":0,"maximum":50},"calibrationCertificateSha256":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"},"invoiceCrossCheckSha256":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"},"lastCalibrationUncertaintyPct":{"type":"number","minimum":0,"maximum":5},"deviceAddress":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},"required":["mainMeterAccuracyPct","checkMeterAccuracyPct","calibrationValidUntil","flowUncertaintyPct"]},"ledger":{"type":"object","properties":{"attestations":{"type":"integer","minimum":0,"maximum":9007199254740991},"balanceG":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"creditingYear":{"type":"integer","minimum":0,"maximum":9007199254740991},"yearNetWh":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["attestations","balanceG","creditingYear","yearNetWh"]},"signature":{"type":"string","pattern":"^0x[0-9a-fA-F]{130}$"},"domain":{"type":"object","properties":{"chainId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"registry":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"sequence":{"type":"integer","minimum":0,"maximum":4294967295}},"required":["chainId","registry"]}},"required":["readings"]}}}},"responses":{"200":{"description":"not-eligible (report) or recorded (attestationId, sequence, reductionG, chainHash, HCS links)","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/mrv/verification":{"get":{"operationId":"get_pending_verification","tags":["verification"],"summary":"The run of records a VVB verifies next, each reproduced from HCS","parameters":[{"name":"plantId","in":"query","required":false,"description":"Plant id, e.g. HYDRO-DEMO-01","schema":{"type":"string"}},{"name":"lastRecord","in":"query","required":false,"description":"Last record of the run (default: the latest)","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"{ pending: { firstRecord, lastRecord, records, recordsHash, monitoredG, unitsIfApproved } | null }","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"prepare_verification","tags":["verification"],"summary":"Publish the VVB's verification report and return the statement to sign","description":"Reproduces the pending records from HCS, publishes the verification report (decision, deduction, findings) and returns the EIP-712 VerificationStatement. The VVB signs it with its own secp256k1 key (eth_signTypedData_v4 or `yarn mrv:approve`). An approval is refused unless every record reproduces. Requires the MRV_API_KEY bearer token because it publishes.","security":[{"mrvApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plantId":{"type":"string","minLength":1,"maxLength":31},"lastRecord":{"type":"integer","minimum":0,"maximum":9007199254740991},"decision":{"type":"string","enum":["approve","reject"]},"deductionG":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"findings":{"default":"","type":"string","maxLength":280},"evidenceHash":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"}},"required":["plantId","decision"]}}}},"responses":{"200":{"description":"{ status: awaiting-signature, report, reportHash, hcs, statement, typedData }","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/mrv/verification/submit":{"post":{"operationId":"submit_verification","tags":["verification"],"summary":"Relay a VVB-signed VerificationStatement to verifyPeriod","description":"Checks the signer holds VERIFIER_ROLE and is not the operator, meter or reporter, and that the statement matches the report at its HCS anchor, then relays verifyPeriod. An approval issues credits into the operator's custody; a rejection closes the run unissued. Anyone can send the same call from their own wallet; this endpoint uses the server's gas and so needs the bearer token.","security":[{"mrvApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plantId":{"type":"string","minLength":1,"maxLength":31},"statement":{"type":"object","properties":{"firstRecord":{"type":"integer","minimum":0,"maximum":9007199254740991},"lastRecord":{"type":"integer","minimum":0,"maximum":9007199254740991},"recordsHash":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"},"deductionG":{"type":"string","pattern":"^\\d+$"},"reportHash":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"},"hcsTopicNum":{"type":"string","pattern":"^\\d+$"},"hcsSequence":{"type":"string","pattern":"^\\d+$"},"evidenceHash":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"},"decision":{"type":"integer","minimum":1,"maximum":2}},"required":["firstRecord","lastRecord","recordsHash","deductionG","reportHash","hcsTopicNum","hcsSequence","evidenceHash","decision"]},"signature":{"type":"string","pattern":"^0x[0-9a-fA-F]{130}$"}},"required":["plantId","statement","signature"]}}}},"responses":{"200":{"description":"{ status: issued | rejected, issuanceId, unitsIssued, verifier, transaction }","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/registry":{"get":{"operationId":"get_registry_overview","tags":["registry"],"summary":"Totals, plants, credit token and both oracle sources","responses":{"200":{"description":"Registry overview","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/registry/plants":{"get":{"operationId":"list_plants","tags":["registry"],"summary":"Registered plants with design and ledger","responses":{"200":{"description":"{ plants }","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/registry/plants/{plantId}":{"get":{"operationId":"get_plant","tags":["registry"],"summary":"One plant: design, ledger, totals, monitoring records and verifications","parameters":[{"name":"plantId","in":"path","required":true,"description":"Plant id, e.g. HYDRO-DEMO-02","schema":{"type":"string"}}],"responses":{"200":{"description":"Plant detail","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/registry/attestations":{"get":{"operationId":"list_attestations","tags":["registry"],"summary":"Monitoring records: monitored inputs, EG_PJ, BE, PE, LE, ER, hash chain, HCS anchors, status","parameters":[{"name":"start","in":"query","required":false,"description":"First attestation id","schema":{"type":"integer","minimum":0,"default":0}},{"name":"count","in":"query","required":false,"description":"Page size","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"{ start, attestations }","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/registry/attestations/{id}/audit":{"get":{"operationId":"audit_attestation","tags":["evidence"],"summary":"HCS report vs on-chain record","parameters":[{"name":"id","in":"path","required":true,"description":"Attestation id","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"verified | mismatch | no-anchor | unavailable, with per-field checks","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/registry/attestations/{id}/reproduce":{"get":{"operationId":"reproduce_attestation","tags":["evidence"],"summary":"Re-derive a monitoring record from the readings published to HCS","description":"Audits the report, reassembles the data message, checks its hash, the registered design and meter and the meter signature, re-runs the engine, compares every figure, and recomputes the record's hash-chain link.","parameters":[{"name":"id","in":"path","required":true,"description":"Attestation id","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"reproduced | diverged | no-data | not-auditable, with per-field checks","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/registry/issuances":{"get":{"operationId":"list_issuances","tags":["registry"],"summary":"Every VVB verification: records covered, decision, deduction, units issued, report","responses":{"200":{"description":"{ issuances }","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/registry/listings":{"get":{"operationId":"list_open_listings","tags":["market"],"summary":"Open listings with an HBAR quote for the full listing","responses":{"200":{"description":"Listings (units in kg, price in US cents per tonne, quote in tinybar)","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/market/dex":{"get":{"operationId":"get_dex_price","tags":["market"],"summary":"Settlement pair and the public mainnet WHBAR/USDC pair versus their oracles","responses":{"200":{"description":"Price, deviation in basis points, and whether a purchase may be built","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/market/prepare-purchase":{"post":{"operationId":"prepare_purchase","tags":["market"],"summary":"Unsigned buy / buyAndRetire transaction for your own wallet","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"listingId":{"type":"integer","minimum":0,"maximum":9007199254740991},"amountKg":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"retire":{"default":true,"type":"boolean"},"beneficiary":{"default":"","type":"string","maxLength":128}},"required":["listingId","amountKg"]}}}},"responses":{"200":{"description":"{ chainId, to, data, value (weibar, 1% refundable buffer), summary }","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/market/credit-pool":{"get":{"operationId":"get_credit_pool","tags":["market"],"summary":"SaucerSwap V1 WHBAR/credit pool for this registry, if it exists","responses":{"200":{"description":"{ exists, reserves, hbarPerTonne, usdPerTonne } or { exists: false, reason }","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/market/prepare-dex-retire":{"post":{"operationId":"prepare_dex_retire","tags":["market"],"summary":"Unsigned swap, deposit and retire; refused when the oracle or either pool is outside 3%","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amountKg":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"beneficiary":{"default":"","type":"string","maxLength":128},"buyer":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"slippageBps":{"default":100,"type":"integer","minimum":0,"maximum":1000}},"required":["amountKg","buyer"]}}}},"responses":{"200":{"description":"{ chainId, summary, swapCostHbar, steps[], buyer, pool }","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/checkout/listings":{"get":{"operationId":"list_checkout_listings","tags":["market"],"summary":"Open UsdCheckout listings of any HTS token, each with its Guardian trace verdict","responses":{"200":{"description":"{ checkout, listings[] } with guardian.verdict backed | none | not-backed | incomplete","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/checkout/prepare-purchase":{"post":{"operationId":"prepare_checkout_purchase","tags":["market"],"summary":"Unsigned UsdCheckout.buy; refused (409) when the token cites a Guardian record that is not backed","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"listingId":{"type":"integer","minimum":0,"maximum":9007199254740991},"amount":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["listingId","amount"]}}}},"responses":{"200":{"description":"{ chainId, to, data, value (weibar, 1% refundable buffer), summary, listing }","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/registry/retirements":{"get":{"operationId":"get_portfolio","tags":["market"],"summary":"Retirements by an account or on behalf of a beneficiary","parameters":[{"name":"account","in":"query","required":false,"description":"Retiring EVM address","schema":{"type":"string"}},{"name":"beneficiary","in":"query","required":false,"description":"Beneficiary name (exact, case-insensitive)","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"format","in":"query","required":false,"description":"json or csv","schema":{"type":"string","enum":["json","csv"],"default":"json"}}],"responses":{"200":{"description":"Portfolio with totals, or RFC 4180 CSV for ESG reporting","content":{"application/json":{"schema":{"type":"object"}},"text/csv":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/registry/retirements/{id}":{"get":{"operationId":"get_retirement_certificate","tags":["market"],"summary":"Retirement record and its HTS NFT certificate","parameters":[{"name":"id","in":"path","required":true,"description":"Retirement id","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Retirement and certificate","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/guardian/v1/cross-check":{"post":{"operationId":"guardian_cross_check","tags":["guardian"],"summary":"Cross-check a Guardian Monitoring Report VC and return a signed result VC","description":"Called by a Guardian policy's httpRequestBlock with the Monitoring Report VC (or a one-element array). Runs the dMRV engine on the mapped fields and answers with a \"DMRV Cross-Check Result\" VC signed with Ed25519Signature2018 by the bridge did:hedera key. Requires the GUARDIAN_BRIDGE_API_KEY bearer; 503 until BRIDGE_ED25519_PRIVATE_KEY, BRIDGE_DID and GUARDIAN_BRIDGE_RESULT_SCHEMA are set. Max body 1 MB, idempotent on the source VC hash. Not an MCP tool.","security":[{"guardianBridgeKey":[]}],"parameters":[{"name":"policyId","in":"query","required":false,"description":"Guardian policy id, selects the result schema and is echoed in the result","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Guardian VC document"}}}},"responses":{"200":{"description":"W3C Verifiable Credential (DMRV Cross-Check Result)","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/guardian/v1/trace":{"get":{"operationId":"trace_guardian_mint","tags":["guardian"],"summary":"Is this Guardian-minted token backed? (buyer's check)","description":"Follows a Guardian mint to its signed record using only the public mirror node and IPFS: the mint memo or NFT metadata names the VP's consensus timestamp; the VP is read from IPFS with every block checked against its CID; its Ed25519 proofs are verified with DIDs resolved from HCS; the MintToken VC must name this token and amount (NFTs: the serials citing the VP must equal it); the signer's DID-Document message must have been paid for by the token treasury. verdict is backed, not-backed or incomplete.","parameters":[{"name":"ref","in":"query","required":false,"description":"nft:<tokenId>:<serial>, ft:<tokenId>:<holder account>, or a mint transaction id","schema":{"type":"string"}}],"responses":{"200":{"description":"{ verdict, token, mint, record, mintVc, registry, sources, checks }","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/guardian/v1/evidence/{timestamp}":{"get":{"operationId":"verify_guardian_evidence","tags":["guardian"],"summary":"Verify Guardian evidence from the mirror node and IPFS","description":"Accepts a VP consensus timestamp, a mint transaction id (0.0.x@secs.nanos, followed through its memo) or nft:<tokenId>:<serial>. Checks the HCS message topic and status, fetches the VP from IPFS, verifies every signature and walks the related documents. Refuses any chain that contains a MintToken VC (the credit was already issued by Guardian) and any Monitoring Report without a MATCH cross-check.","parameters":[{"name":"timestamp","in":"path","required":true,"description":"Consensus timestamp, mint transaction id or nft:<tokenId>:<serial>","schema":{"type":"string"}},{"name":"topicIds","in":"query","required":false,"description":"Comma-separated Guardian policy topic ids; defaults to GUARDIAN_EVIDENCE_TOPIC_IDS","schema":{"type":"string"}}],"responses":{"200":{"description":"{ accepted, refusals, notes, chain, crossChecks, evidenceHash }","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"mrvApiKey":{"type":"http","scheme":"bearer","description":"MRV_API_KEY, held by the plant operator"},"guardianBridgeKey":{"type":"http","scheme":"bearer","description":"GUARDIAN_BRIDGE_API_KEY, configured in the Guardian policy's httpRequestBlock headers"}},"responses":{"Error":{"description":"Caller mistake or unavailable dependency","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"x-mcp":{"url":"https://hydro-dmrv.vercel.app/api/mcp","transport":"streamable-http"}}