{"openapi":"3.1.0","info":{"title":"x402 Carbon Retirement API","version":"1.3.6","description":"Retire tokenized carbon credits on Base through Klima Protocol and the Carbonmark marketplace, and resolve the public Carbonmark certificate. Discovery, quotes and certificates are free. Retiring is paid: each retirement costs the credit price plus a fee, sent from your own wallet (GET /api/prepare/retire) or funded by a signed authorization and relayed non-custodially (POST /api/actions/retire, which adds executor gas). GET /api/catalog is a $0.001 x402 snapshot of the most liquid supply.","contact":{"name":"Carbonmark","url":"https://us.bigin.online/org894283421/forms/klima-contact-us","email":"info@carbonmark.com"},"x-guidance":"Base mainnet (chainId 8453). Paid ($0.001, standard x402 exact USDC): GET /api/catalog returns the most liquid supply with links to the flow below. Free: GET /api/discover lists all supply (retire by `carbonClass` or `listingId`); GET /api/quote prices it. Self-submitted: GET /api/prepare/retire returns an [approve, retire] batch to send from your wallet. Relayed (x402): GET /api/prepare-auth returns typedData, sign it exactly as returned, then POST `actionsRetireRequest` to /api/actions/retire with `authPayload.signature` set. GET /api/certificate?txHash= resolves the certificate. Error codes and remedies: /.well-known/x402-errors.json."},"x-agentcash-guidance":{"llmsTxtUrl":"https://x402.klimalabs.com/llms.txt"},"servers":[{"url":"https://x402.klimalabs.com"}],"externalDocs":{"description":"Integration documentation","url":"https://github.com/KlimaDAO/Klima-Protocol-x402-MCP-documentation/blob/main/README.md"},"tags":[{"name":"Catalog","description":"Find and price carbon supply."},{"name":"Retirement","description":"Build, pay for and verify retirements."},{"name":"Service","description":"Index, health and machine-readable metadata."}],"paths":{"/api/catalog":{"get":{"operationId":"catalog","tags":["Catalog"],"summary":"API entry point: endpoints and top supply snapshot (paid, $0.001)","description":"Entry point to the x402 Carbon Retirement API on Base. Returns every endpoint you need plus a live snapshot of the top 3 carbon classes and marketplace listings by liquidity. Discover, quote and certificate are free. Retiring is paid: each retirement costs the credit price plus a fee, sent from your own wallet (prepare/retire) or relayed from a signed USDC authorization (prepare-auth + POST actions/retire). Full spec at /openapi.json. Paid per call with a standard x402 v2 `exact` USDC payment on Base, settled by the Coinbase facilitator. GET /api/discover returns the full catalog for free.","security":[],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.001"},"protocols":[{"x402":{}}]},"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogResponse"}}}},"402":{"description":"Payment Required. The x402 v2 challenge is in the `PAYMENT-REQUIRED` header (base64 JSON). Pay in USDC on Base (eip155:8453) with the `exact` scheme and retry with the `PAYMENT-SIGNATURE` header."},"500":{"description":"`error` is one of: internal_error. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["internal_error"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`error` is one of: payment_unavailable. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["payment_unavailable"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/discover":{"get":{"operationId":"discover","tags":["Catalog"],"summary":"List retirable carbon credits with live prices","description":"Use to find carbon supply to retire on Base. Returns `carbonClasses[]` (pooled protocol supply, retire by `carbonClass`) and `marketplaceListings[]` (a seller's fixed ask, retire by `listingId`), each with USDC-per-tonne prices, liquidity and project metadata. Filters are AND-combined. Free.","security":[],"parameters":[{"name":"source","in":"query","required":false,"description":"Keep only protocol supply or only marketplace listings.","schema":{"type":"string","enum":["protocol","marketplace"]}},{"name":"carbonClass","in":"query","required":false,"description":"Carbon class address from /api/discover `carbonClasses[]`. Provide exactly one of `carbonClass`, `listingId` or `credit`.","schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},{"name":"creditToken","in":"query","required":false,"description":"Credit token address. Narrows credit resolution within a carbon class.","schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},{"name":"project","in":"query","required":false,"description":"Project id (\"1234\") or registry-qualified key (\"VCS-1234\"); comma-separated for several.","schema":{"type":"string","minLength":1}},{"name":"credit","in":"query","required":false,"description":"Project-vintage id (\"VCS-1044-2011\"). On /api/discover, a comma-separated list filters by it.","schema":{"type":"string","minLength":1}},{"name":"vintage","in":"query","required":false,"description":"Vintage year (2020) or YYYYMMDD date (20200417).","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"country","in":"query","required":false,"description":"Project country.","schema":{"type":"string","minLength":1}},{"name":"category","in":"query","required":false,"description":"Project category.","schema":{"type":"string","minLength":1}},{"name":"methodology","in":"query","required":false,"description":"Methodology code; comma-separated for several.","schema":{"type":"string","minLength":1}},{"name":"maxUsdcPricePerTonne","in":"query","required":false,"description":"Keep supply priced at or below this many USDC per tonne (\"20\").","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscoverResponse"}}}},"400":{"description":"`error` is one of: schema_validation. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["schema_validation"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`error` is one of: internal_error. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["internal_error"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/quote":{"get":{"operationId":"quote","tags":["Catalog"],"summary":"Price a retirement","description":"Use before retiring to show the cost. Returns the retirement price, fee, total and a suggested maximum input, for `amount` tonnes of one `carbonClass`, `listingId` or `credit`. Free.","security":[],"parameters":[{"name":"chainId","in":"query","required":true,"description":"Chain id. Base mainnet is 8453.","schema":{"type":"integer","enum":[8453,84532]}},{"name":"inputToken","in":"query","required":true,"description":"Payment token address: USDC or kVCM. Marketplace listings settle in USDC only.","schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},{"name":"amount","in":"query","required":true,"description":"Tonnes to retire, as a decimal string (\"1.5\"). Puro and ECO credits retire in whole tonnes.","schema":{"type":"string","minLength":1}},{"name":"carbonClass","in":"query","required":false,"description":"Carbon class address from /api/discover `carbonClasses[]`. Provide exactly one of `carbonClass`, `listingId` or `credit`.","schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},{"name":"listingId","in":"query","required":false,"description":"Marketplace listing id (bytes32) from /api/discover `marketplaceListings[]`.","schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"}},{"name":"credit","in":"query","required":false,"description":"Project-vintage id (\"VCS-1044-2011\"). On /api/discover, a comma-separated list filters by it.","schema":{"type":"string","pattern":"^[A-Za-z]+-[A-Za-z0-9]+-\\d+$"}},{"name":"creditToken","in":"query","required":false,"description":"Credit token address. Narrows credit resolution within a carbon class.","schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},{"name":"vintage","in":"query","required":false,"description":"Vintage year (2020) or YYYYMMDD date (20200417).","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"tokenId","in":"query","required":false,"description":"ERC-1155 token id; with `creditToken`, pins one exact credit.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteResponse"}}}},"400":{"description":"`error` is one of: schema_validation, unsupported_chain_id, unsupported_input_token, vintage_not_found, marketplace_requires_usdc. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["schema_validation","unsupported_chain_id","unsupported_input_token","vintage_not_found","marketplace_requires_usdc"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`error` is one of: no_candidates, credit_not_found, listing_not_found. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["no_candidates","credit_not_found","listing_not_found"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`error` is one of: credit_ambiguous. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["credit_ambiguous"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`error` is one of: insufficient_liquidity, amount_not_whole_tonnes, amount_below_increment, contract_revert, listing_expired, below_min_fill, insufficient_listing_supply. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["insufficient_liquidity","amount_not_whole_tonnes","amount_below_increment","contract_revert","listing_expired","below_min_fill","insufficient_listing_supply"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`error` is one of: internal_error. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["internal_error"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/prepare/retire":{"get":{"operationId":"prepareRetire","tags":["Retirement"],"summary":"Build a self-submitted retirement transaction batch","description":"Use when the caller's own wallet will send the transaction (e.g. Base MCP `send_calls`). Returns an ordered [approve, retire] batch of unsigned calls plus the authoritative quote. Paid: sending the batch retires the credits, costing the credit price plus a fee collected inside the retirement (see `quote.total`). This call only builds the batch; nothing is broadcast.","security":[],"parameters":[{"name":"chainId","in":"query","required":true,"description":"Chain id. Base mainnet is 8453.","schema":{"type":"integer","enum":[8453,84532]}},{"name":"inputToken","in":"query","required":true,"description":"Payment token address: USDC or kVCM. Marketplace listings settle in USDC only.","schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},{"name":"amount","in":"query","required":true,"description":"Tonnes to retire, as a decimal string (\"1.5\"). Puro and ECO credits retire in whole tonnes.","schema":{"type":"string","minLength":1}},{"name":"carbonClass","in":"query","required":false,"description":"Carbon class address from /api/discover `carbonClasses[]`. Provide exactly one of `carbonClass`, `listingId` or `credit`.","schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},{"name":"listingId","in":"query","required":false,"description":"Marketplace listing id (bytes32) from /api/discover `marketplaceListings[]`.","schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"}},{"name":"credit","in":"query","required":false,"description":"Project-vintage id (\"VCS-1044-2011\"). On /api/discover, a comma-separated list filters by it.","schema":{"type":"string","pattern":"^[A-Za-z]+-[A-Za-z0-9]+-\\d+$"}},{"name":"creditToken","in":"query","required":false,"description":"Credit token address. Narrows credit resolution within a carbon class.","schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},{"name":"vintage","in":"query","required":false,"description":"Vintage year (2020) or YYYYMMDD date (20200417).","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"tokenId","in":"query","required":false,"description":"ERC-1155 token id; with `creditToken`, pins one exact credit.","schema":{"type":"string","minLength":1}},{"name":"maxInputTokenIn","in":"query","required":false,"description":"Budget ceiling in atomic units of `inputToken`; overrides the default slippage ceiling.","schema":{"type":"string","minLength":1}},{"name":"details","in":"query","required":false,"description":"URL-encoded JSON object of retirement attribution (beneficiaryString, beneficiaryAddress, retirementMessage, ...). Strict: unknown keys are rejected.","schema":{"type":"string","contentMediaType":"application/json","contentSchema":{"type":"object","properties":{"retiringAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"retiringEntityString":{"type":"string"},"beneficiaryAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"beneficiaryString":{"type":"string"},"retirementMessage":{"type":"string"},"beneficiaryLocation":{"type":"string"},"consumptionCountryCode":{"type":"string"},"consumptionPeriodStart":{"anyOf":[{"type":"string"},{"type":"number"}]},"consumptionPeriodEnd":{"anyOf":[{"type":"string"},{"type":"number"}]}},"additionalProperties":false}}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrepareRetireResponse"}}}},"400":{"description":"`error` is one of: schema_validation, unsupported_chain_id, unsupported_input_token, vintage_not_found, puro_details_required, marketplace_requires_usdc. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["schema_validation","unsupported_chain_id","unsupported_input_token","vintage_not_found","puro_details_required","marketplace_requires_usdc"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`error` is one of: no_candidates, credit_not_found, listing_not_found. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["no_candidates","credit_not_found","listing_not_found"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`error` is one of: credit_ambiguous. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["credit_ambiguous"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`error` is one of: insufficient_liquidity, amount_not_whole_tonnes, amount_below_increment, contract_revert, listing_expired, below_min_fill, insufficient_listing_supply. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["insufficient_liquidity","amount_not_whole_tonnes","amount_below_increment","contract_revert","listing_expired","below_min_fill","insufficient_listing_supply"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`error` is one of: internal_error. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["internal_error"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/prepare-auth":{"get":{"operationId":"prepareAuth","tags":["Retirement"],"summary":"Build the authorization to sign for a relayed retirement","description":"Use to pay for a retirement without sending a transaction. Returns EIP-712 `typedData` (EIP-3009 for USDC, EIP-2612 permit for kVCM) and a ready-to-send `actionsRetireRequest`. Sign `typedData` exactly as returned, set `authPayload.signature`, and POST the request to /api/actions/retire. Requires `details.beneficiaryAddress` or `beneficiaryIsPayer=true`. Paid: the signed authorization funds the retirement, costing the credit price plus a fee and executor gas.","security":[],"parameters":[{"name":"chainId","in":"query","required":true,"description":"Chain id. Base mainnet is 8453.","schema":{"type":"integer","enum":[8453,84532]}},{"name":"inputToken","in":"query","required":true,"description":"Payment token address: USDC or kVCM. Marketplace listings settle in USDC only.","schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},{"name":"amount","in":"query","required":true,"description":"Tonnes to retire, as a decimal string (\"1.5\"). Puro and ECO credits retire in whole tonnes.","schema":{"type":"string","minLength":1}},{"name":"carbonClass","in":"query","required":false,"description":"Carbon class address from /api/discover `carbonClasses[]`. Provide exactly one of `carbonClass`, `listingId` or `credit`.","schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},{"name":"listingId","in":"query","required":false,"description":"Marketplace listing id (bytes32) from /api/discover `marketplaceListings[]`.","schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"}},{"name":"credit","in":"query","required":false,"description":"Project-vintage id (\"VCS-1044-2011\"). On /api/discover, a comma-separated list filters by it.","schema":{"type":"string","pattern":"^[A-Za-z]+-[A-Za-z0-9]+-\\d+$"}},{"name":"creditToken","in":"query","required":false,"description":"Credit token address. Narrows credit resolution within a carbon class.","schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},{"name":"vintage","in":"query","required":false,"description":"Vintage year (2020) or YYYYMMDD date (20200417).","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"tokenId","in":"query","required":false,"description":"ERC-1155 token id; with `creditToken`, pins one exact credit.","schema":{"type":"string","minLength":1}},{"name":"maxInputTokenIn","in":"query","required":false,"description":"Budget ceiling in atomic units of `inputToken`; overrides the default slippage ceiling.","schema":{"type":"string","minLength":1}},{"name":"details","in":"query","required":false,"description":"URL-encoded JSON object of retirement attribution (beneficiaryString, beneficiaryAddress, retirementMessage, ...). Strict: unknown keys are rejected.","schema":{"type":"string","contentMediaType":"application/json","contentSchema":{"type":"object","properties":{"retiringAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"retiringEntityString":{"type":"string"},"beneficiaryAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"beneficiaryString":{"type":"string"},"retirementMessage":{"type":"string"},"beneficiaryLocation":{"type":"string"},"consumptionCountryCode":{"type":"string"},"consumptionPeriodStart":{"anyOf":[{"type":"string"},{"type":"number"}]},"consumptionPeriodEnd":{"anyOf":[{"type":"string"},{"type":"number"}]}},"additionalProperties":false}}},{"name":"from","in":"query","required":true,"description":"Payer wallet address; the signer of the authorization.","schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},{"name":"timeToLiveSeconds","in":"query","required":false,"description":"Authorization lifetime in seconds. Capped at 5 minutes for marketplace listings.","schema":{"type":"integer","exclusiveMinimum":0,"maximum":86400}},{"name":"beneficiaryIsPayer","in":"query","required":false,"description":"Set true to credit the paying wallet when `details.beneficiaryAddress` is omitted.","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrepareAuthResponse"}}}},"400":{"description":"`error` is one of: schema_validation, unsupported_chain_id, unsupported_input_token, vintage_not_found, puro_details_required, attribution_required, marketplace_requires_usdc. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["schema_validation","unsupported_chain_id","unsupported_input_token","vintage_not_found","puro_details_required","attribution_required","marketplace_requires_usdc"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`error` is one of: no_candidates, credit_not_found, listing_not_found. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["no_candidates","credit_not_found","listing_not_found"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`error` is one of: credit_ambiguous. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["credit_ambiguous"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`error` is one of: insufficient_liquidity, amount_not_whole_tonnes, amount_below_increment, contract_revert, listing_expired, below_min_fill, insufficient_listing_supply. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["insufficient_liquidity","amount_not_whole_tonnes","amount_below_increment","contract_revert","listing_expired","below_min_fill","insufficient_listing_supply"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`error` is one of: internal_error. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["internal_error"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`error` is one of: gas_estimate_unavailable. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["gas_estimate_unavailable"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/actions/retire":{"post":{"operationId":"actionsRetire","tags":["Retirement"],"summary":"Retire carbon credits, paid with a signed x402 authorization","description":"Use to retire carbon credits and receive the Carbonmark certificate in one call. Non-custodial: the payer's signed USDC (EIP-3009) or kVCM (EIP-2612) authorization funds the settlement contract directly, and the service only relays it. POST without `authPayload` to receive the 402 challenge; POST again with the signature in `authPayload`, posting `actionsRetireRequest` verbatim (including `salt`). Cost is the retirement price + fee + executor gas, all inside the signed budget; any unspent budget is refunded in the same transaction.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"chainId":{"anyOf":[{"type":"number","const":8453},{"type":"number","const":84532}]},"inputToken":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"amount":{"type":"string","minLength":1},"carbonClass":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"listingId":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"},"credit":{"type":"string","pattern":"^[A-Za-z]+-[A-Za-z0-9]+-\\d+$"},"creditToken":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"vintage":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^\\d+$"}]},"tokenId":{"type":"string","minLength":1},"maxInputTokenIn":{"type":"string","minLength":1},"details":{"type":"object","properties":{"retiringAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"retiringEntityString":{"type":"string"},"beneficiaryAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"beneficiaryString":{"type":"string"},"retirementMessage":{"type":"string"},"beneficiaryLocation":{"type":"string"},"consumptionCountryCode":{"type":"string"},"consumptionPeriodStart":{"anyOf":[{"type":"string"},{"type":"number"}]},"consumptionPeriodEnd":{"anyOf":[{"type":"string"},{"type":"number"}]}},"additionalProperties":false},"from":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"timeToLiveSeconds":{"type":"integer","exclusiveMinimum":0,"maximum":86400},"beneficiaryIsPayer":{"anyOf":[{"type":"boolean"},{"type":"string","enum":["true","false"]}]},"authPayload":{"anyOf":[{"type":"object","properties":{"from":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"to":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"value":{"anyOf":[{"type":"string"},{"type":"number"}]},"validAfter":{"anyOf":[{"type":"string"},{"type":"number"}]},"validBefore":{"anyOf":[{"type":"string"},{"type":"number"}]},"nonce":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"},"signature":{"type":"string","pattern":"^0x([a-fA-F0-9]{2}){1,2048}$"},"v":{"type":"integer","minimum":0,"maximum":255},"r":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"},"s":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"}},"required":["from","to","value","validAfter","validBefore","nonce"],"additionalProperties":false},{"type":"object","properties":{"from":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"to":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"value":{"anyOf":[{"type":"string"},{"type":"number"}]},"deadline":{"anyOf":[{"type":"string"},{"type":"number"}]},"signature":{"type":"string","pattern":"^0x[a-fA-F0-9]{130}$"},"v":{"type":"integer","minimum":0,"maximum":255},"r":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"},"s":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"}},"required":["from","to","value","deadline"],"additionalProperties":false}]},"salt":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"}},"required":["chainId","inputToken","amount","from"],"additionalProperties":false},"example":{"chainId":8453,"inputToken":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","carbonClass":"0x0008f35758a4318942ecb5d5414116ce7b1ede2d","amount":"1","from":"0x000000000000000000000000000000000000dEaD","beneficiaryIsPayer":true,"details":{"beneficiaryString":"Example beneficiary"}}}}},"responses":{"200":{"description":"Retirement settled (or confirmed and awaiting indexing: `status: pending_index`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionsRetireResponse"}}}},"400":{"description":"`error` is one of: invalid_json, schema_validation, unsupported_chain_id, unsupported_input_token, invalid_input_token, vintage_not_found, puro_details_required, attribution_required, invalid_auth_payload, insufficient_authorized_value, params_mismatch, marketplace_requires_usdc. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["invalid_json","schema_validation","unsupported_chain_id","unsupported_input_token","invalid_input_token","vintage_not_found","puro_details_required","attribution_required","invalid_auth_payload","insufficient_authorized_value","params_mismatch","marketplace_requires_usdc"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment Required: sign `accepts[0].extra.typedData` and resubmit with `authPayload`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"404":{"description":"`error` is one of: no_candidates, credit_not_found, listing_not_found. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["no_candidates","credit_not_found","listing_not_found"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`error` is one of: credit_ambiguous. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["credit_ambiguous"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`error` is one of: insufficient_liquidity, amount_not_whole_tonnes, amount_below_increment, contract_revert, transaction_reverted, listing_expired, below_min_fill, insufficient_listing_supply. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["insufficient_liquidity","amount_not_whole_tonnes","amount_below_increment","contract_revert","transaction_reverted","listing_expired","below_min_fill","insufficient_listing_supply"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`error` is one of: internal_error. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["internal_error"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`error` is one of: gas_estimate_unavailable, gas_limit_exceeds_cap. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["gas_estimate_unavailable","gas_limit_exceeds_cap"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/certificate":{"get":{"operationId":"certificate","tags":["Retirement"],"summary":"Resolve the Carbonmark certificate for a retirement transaction","description":"Use after a retirement confirms. Returns one entry per retirement in the transaction, each with its public `certificateUrl`. A 404 right after confirmation means the subgraph has not indexed it yet; retry after a few seconds. Free.","security":[],"parameters":[{"name":"txHash","in":"query","required":false,"description":"Confirmed retirement transaction hash.","schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"}},{"name":"transactionHash","in":"query","required":false,"description":"Alias of `txHash`.","schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"}},{"name":"index","in":"query","required":false,"description":"Select one retirement from a multi-retirement transaction.","schema":{"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"retirementIndex","in":"query","required":false,"description":"Alias of `index`.","schema":{"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertificateResponse"}}}},"400":{"description":"`error` is one of: schema_validation. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["schema_validation"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`error` is one of: retirement_not_found. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["retirement_not_found"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`error` is one of: internal_error. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["internal_error"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api":{"get":{"operationId":"apiIndex","tags":["Service"],"summary":"Action index","description":"Lists the actions and links the manifest, changelog, error registry and docs. Free.","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Signpost"}}}}}},"post":{"operationId":"dispatchAction","tags":["Service"],"summary":"Action multiplexer","description":"Legacy single-URL form of every action: POST a JSON body with an `action` field. Posting `action: \"actions/retire\"` here behaves exactly like POST /api/actions/retire. Prefer the per-action paths.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"action":{"type":"string","const":"discover"},"source":{"type":"string","enum":["protocol","marketplace"]},"carbonClass":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"creditToken":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"project":{"anyOf":[{"type":"string","minLength":1},{"minItems":1,"type":"array","items":{"type":"string","minLength":1}}]},"credit":{"anyOf":[{"type":"string","minLength":1},{"minItems":1,"type":"array","items":{"type":"string","minLength":1}}]},"vintage":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^\\d+$"}]},"country":{"anyOf":[{"type":"string","minLength":1},{"minItems":1,"type":"array","items":{"type":"string","minLength":1}}]},"category":{"anyOf":[{"type":"string","minLength":1},{"minItems":1,"type":"array","items":{"type":"string","minLength":1}}]},"methodology":{"anyOf":[{"type":"string","minLength":1},{"minItems":1,"type":"array","items":{"type":"string","minLength":1}}]},"maxUsdcPricePerTonne":{"type":"string","minLength":1}},"additionalProperties":false,"required":["action"]},{"type":"object","properties":{"action":{"type":"string","const":"quote"},"chainId":{"anyOf":[{"type":"number","const":8453},{"type":"number","const":84532}]},"inputToken":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"amount":{"type":"string","minLength":1},"carbonClass":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"listingId":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"},"credit":{"type":"string","pattern":"^[A-Za-z]+-[A-Za-z0-9]+-\\d+$"},"creditToken":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"vintage":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^\\d+$"}]},"tokenId":{"type":"string","minLength":1}},"required":["action","chainId","inputToken","amount"]},{"type":"object","properties":{"action":{"type":"string","const":"prepare/retire"},"chainId":{"anyOf":[{"type":"number","const":8453},{"type":"number","const":84532}]},"inputToken":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"amount":{"type":"string","minLength":1},"carbonClass":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"listingId":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"},"credit":{"type":"string","pattern":"^[A-Za-z]+-[A-Za-z0-9]+-\\d+$"},"creditToken":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"vintage":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^\\d+$"}]},"tokenId":{"type":"string","minLength":1},"maxInputTokenIn":{"type":"string","minLength":1},"details":{"type":"object","properties":{"retiringAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"retiringEntityString":{"type":"string"},"beneficiaryAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"beneficiaryString":{"type":"string"},"retirementMessage":{"type":"string"},"beneficiaryLocation":{"type":"string"},"consumptionCountryCode":{"type":"string"},"consumptionPeriodStart":{"anyOf":[{"type":"string"},{"type":"number"}]},"consumptionPeriodEnd":{"anyOf":[{"type":"string"},{"type":"number"}]}},"additionalProperties":false}},"required":["action","chainId","inputToken","amount"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","const":"prepare-auth"},"chainId":{"anyOf":[{"type":"number","const":8453},{"type":"number","const":84532}]},"inputToken":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"amount":{"type":"string","minLength":1},"carbonClass":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"listingId":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"},"credit":{"type":"string","pattern":"^[A-Za-z]+-[A-Za-z0-9]+-\\d+$"},"creditToken":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"vintage":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^\\d+$"}]},"tokenId":{"type":"string","minLength":1},"maxInputTokenIn":{"type":"string","minLength":1},"details":{"type":"object","properties":{"retiringAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"retiringEntityString":{"type":"string"},"beneficiaryAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"beneficiaryString":{"type":"string"},"retirementMessage":{"type":"string"},"beneficiaryLocation":{"type":"string"},"consumptionCountryCode":{"type":"string"},"consumptionPeriodStart":{"anyOf":[{"type":"string"},{"type":"number"}]},"consumptionPeriodEnd":{"anyOf":[{"type":"string"},{"type":"number"}]}},"additionalProperties":false},"from":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"timeToLiveSeconds":{"type":"integer","exclusiveMinimum":0,"maximum":86400},"beneficiaryIsPayer":{"anyOf":[{"type":"boolean"},{"type":"string","enum":["true","false"]}]}},"required":["action","chainId","inputToken","amount","from"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","const":"actions/retire"},"chainId":{"anyOf":[{"type":"number","const":8453},{"type":"number","const":84532}]},"inputToken":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"amount":{"type":"string","minLength":1},"carbonClass":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"listingId":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"},"credit":{"type":"string","pattern":"^[A-Za-z]+-[A-Za-z0-9]+-\\d+$"},"creditToken":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"vintage":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^\\d+$"}]},"tokenId":{"type":"string","minLength":1},"maxInputTokenIn":{"type":"string","minLength":1},"details":{"type":"object","properties":{"retiringAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"retiringEntityString":{"type":"string"},"beneficiaryAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"beneficiaryString":{"type":"string"},"retirementMessage":{"type":"string"},"beneficiaryLocation":{"type":"string"},"consumptionCountryCode":{"type":"string"},"consumptionPeriodStart":{"anyOf":[{"type":"string"},{"type":"number"}]},"consumptionPeriodEnd":{"anyOf":[{"type":"string"},{"type":"number"}]}},"additionalProperties":false},"from":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"timeToLiveSeconds":{"type":"integer","exclusiveMinimum":0,"maximum":86400},"beneficiaryIsPayer":{"anyOf":[{"type":"boolean"},{"type":"string","enum":["true","false"]}]},"authPayload":{"anyOf":[{"type":"object","properties":{"from":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"to":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"value":{"anyOf":[{"type":"string"},{"type":"number"}]},"validAfter":{"anyOf":[{"type":"string"},{"type":"number"}]},"validBefore":{"anyOf":[{"type":"string"},{"type":"number"}]},"nonce":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"},"signature":{"type":"string","pattern":"^0x([a-fA-F0-9]{2}){1,2048}$"},"v":{"type":"integer","minimum":0,"maximum":255},"r":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"},"s":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"}},"required":["from","to","value","validAfter","validBefore","nonce"],"additionalProperties":false},{"type":"object","properties":{"from":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"to":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"value":{"anyOf":[{"type":"string"},{"type":"number"}]},"deadline":{"anyOf":[{"type":"string"},{"type":"number"}]},"signature":{"type":"string","pattern":"^0x[a-fA-F0-9]{130}$"},"v":{"type":"integer","minimum":0,"maximum":255},"r":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"},"s":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"}},"required":["from","to","value","deadline"],"additionalProperties":false}]},"salt":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"}},"required":["action","chainId","inputToken","amount","from"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","const":"certificate"},"txHash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"},"transactionHash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"},"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"retirementIndex":{"type":"integer","minimum":0,"maximum":9007199254740991}},"additionalProperties":false,"required":["action"]}]}}}},"responses":{"200":{"description":"The action's success response.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/DiscoverResponse"},{"$ref":"#/components/schemas/QuoteResponse"},{"$ref":"#/components/schemas/PrepareRetireResponse"},{"$ref":"#/components/schemas/PrepareAuthResponse"},{"$ref":"#/components/schemas/ActionsRetireResponse"},{"$ref":"#/components/schemas/CertificateResponse"}]}}}},"400":{"description":"`error` is one of: invalid_json, unknown_action, schema_validation, unsupported_chain_id, unsupported_input_token, invalid_input_token, vintage_not_found, puro_details_required, attribution_required, invalid_auth_payload, insufficient_authorized_value, params_mismatch, marketplace_requires_usdc. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["invalid_json","unknown_action","schema_validation","unsupported_chain_id","unsupported_input_token","invalid_input_token","vintage_not_found","puro_details_required","attribution_required","invalid_auth_payload","insufficient_authorized_value","params_mismatch","marketplace_requires_usdc"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Returned for `action: \"actions/retire\"` without `authPayload`. See POST /api/actions/retire.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"404":{"description":"`error` is one of: no_candidates, credit_not_found, retirement_not_found, listing_not_found. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["no_candidates","credit_not_found","retirement_not_found","listing_not_found"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`error` is one of: credit_ambiguous. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["credit_ambiguous"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`error` is one of: insufficient_liquidity, amount_not_whole_tonnes, amount_below_increment, contract_revert, transaction_reverted, listing_expired, below_min_fill, insufficient_listing_supply. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["insufficient_liquidity","amount_not_whole_tonnes","amount_below_increment","contract_revert","transaction_reverted","listing_expired","below_min_fill","insufficient_listing_supply"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`error` is one of: internal_error. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["internal_error"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`error` is one of: gas_estimate_unavailable, gas_limit_exceeds_cap, payment_unavailable. Meaning and remedy per code: /.well-known/x402-errors.json","x-error-codes":["gas_estimate_unavailable","gas_limit_exceeds_cap","payment_unavailable"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/health":{"get":{"operationId":"health","tags":["Service"],"summary":"Liveness probe","description":"Always 200 while the service is up. Free.","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/api/changelog":{"get":{"operationId":"changelog","tags":["Service"],"summary":"Release history","description":"Machine-readable changelog, newest first. Same document as /.well-known/x402-changelog.json. Free.","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Changelog"}}}}}}},"/api/errors":{"get":{"operationId":"errorCodes","tags":["Service"],"summary":"Error-code registry","description":"Every `error` code the API returns, with status, retryability, meaning and remedy. Same document as /.well-known/x402-errors.json. Free.","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRegistry"}}}}}}}},"components":{"schemas":{"DiscoverResponse":{"type":"object","properties":{"carbonClasses":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","const":"protocol"},"carbonClassId":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"methodologies":{"type":"array","items":{}},"isRegistered":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"priceUsdcPerTonne":{"anyOf":[{"type":"string"},{"type":"null"}]},"priceUsdcPerTonneFormatted":{"anyOf":[{"type":"string"},{"type":"null"}]},"credits":{"type":"array","items":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},"creditsDetailed":{"type":"array","items":{"type":"object","properties":{"tokenAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"tokenStandard":{"anyOf":[{"type":"string"},{"type":"null"}]},"tokenId":{"type":"number"},"registry":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"creditId":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectName":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"methodologies":{"type":"array","items":{"type":"string"}},"isExAnte":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"vintage":{"anyOf":[{"type":"number"},{"type":"null"}]},"liquidity":{"type":"string"},"liquidityFormatted":{"type":"string"}},"required":["tokenAddress","tokenStandard","tokenId","registry","projectId","projectKey","creditId","projectName","country","region","category","methodologies","isExAnte","vintage","liquidity","liquidityFormatted"],"additionalProperties":false}},"minRetirementTonnes":{"type":"string"},"minRetirementTonnesFormatted":{"type":"string"},"minRetirementNote":{"type":"string"}},"required":["source","carbonClassId","name","category","country","region","methodologies","isRegistered","priceUsdcPerTonne","priceUsdcPerTonneFormatted","credits","creditsDetailed","minRetirementTonnes","minRetirementTonnesFormatted","minRetirementNote"],"additionalProperties":false}},"marketplaceListings":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","const":"marketplace"},"listingId":{"type":"string"},"seller":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"creditToken":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"tokenId":{"type":"number"},"tokenStandard":{"anyOf":[{"type":"string"},{"type":"null"}]},"carbonClassId":{"anyOf":[{"type":"string"},{"type":"null"}]},"registry":{"anyOf":[{"type":"string"},{"type":"null"}]},"vintage":{"anyOf":[{"type":"number"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"creditId":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectName":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"methodologies":{"type":"array","items":{"type":"string"}},"isExAnte":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"priceUsdcPerTonne":{"anyOf":[{"type":"string"},{"type":"null"}]},"priceUsdcPerTonneFormatted":{"anyOf":[{"type":"string"},{"type":"null"}]},"leftToSell":{"type":"string"},"leftToSellFormatted":{"type":"string"},"minFill":{"type":"string"},"minFillFormatted":{"type":"string"},"expiration":{"type":"string"},"expirationIso":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","listingId","seller","creditToken","tokenId","tokenStandard","carbonClassId","registry","vintage","projectId","projectKey","creditId","projectName","country","region","category","methodologies","isExAnte","priceUsdcPerTonne","priceUsdcPerTonneFormatted","leftToSell","leftToSellFormatted","minFill","minFillFormatted","expiration","expirationIso"],"additionalProperties":false}},"filterDiagnostics":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"matched":{"type":"number"},"excludedNoMatch":{"type":"number"},"excludedAttributeNull":{"type":"number"}},"required":["matched","excludedNoMatch","excludedAttributeNull"],"additionalProperties":false}},"marketplaceEnabled":{"type":"boolean"},"contracts":{"type":"object","properties":{"retirementAggregator":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"klimaProtocolAAM":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"kVCM":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"USDC":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},"required":["retirementAggregator","klimaProtocolAAM","kVCM","USDC"],"additionalProperties":false},"supportedInputTokens":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"decimals":{"type":"number"}},"required":["symbol","address","decimals"],"additionalProperties":false}},"supportedCreditTypes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"standard":{"type":"string"},"bridge":{"type":"string"},"status":{"type":"string"}},"required":["type","standard","bridge"],"additionalProperties":false}},"x402FacilitatorVersion":{"type":"number"},"note":{"type":"string"}},"required":["carbonClasses","marketplaceListings","marketplaceEnabled","contracts","supportedInputTokens","supportedCreditTypes","x402FacilitatorVersion","note"],"additionalProperties":false},"QuoteResponse":{"type":"object","properties":{"tonnes":{"type":"string"},"tonnesFormatted":{"type":"string"},"retirementPrice":{"type":"string"},"retirementPriceFormatted":{"type":"string"},"fee":{"type":"string"},"feeFormatted":{"type":"string"},"total":{"type":"string"},"totalFormatted":{"type":"string"},"suggestedMaxInput":{"type":"string"},"suggestedMaxInputFormatted":{"type":"string"},"pricePerTonne":{"type":"string"},"pricePerTonneFormatted":{"type":"string"},"maxUsdcPricePerTonne":{"type":"string"},"maxUsdcPricePerTonneFormatted":{"type":"string"},"inputTokenSymbol":{"type":"string"},"inputTokenDecimals":{"type":"number"},"slippageBps":{"type":"number"},"humanSummary":{"type":"string"},"relayExecutorGas":{"anyOf":[{"type":"string"},{"type":"null"}]},"relayExecutorGasFormatted":{"anyOf":[{"type":"string"},{"type":"null"}]},"relayTotal":{"anyOf":[{"type":"string"},{"type":"null"}]},"relayTotalFormatted":{"anyOf":[{"type":"string"},{"type":"null"}]},"resolvedCredit":{"type":"object","properties":{"creditToken":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"tokenId":{"type":"number"},"vintage":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["creditToken","tokenId","vintage"],"additionalProperties":false},"alternatives":{"type":"array","items":{"type":"object","properties":{"tokenId":{"type":"number"},"vintage":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["tokenId","vintage"],"additionalProperties":false}}},"required":["tonnes","tonnesFormatted","retirementPrice","retirementPriceFormatted","fee","feeFormatted","total","totalFormatted","suggestedMaxInput","suggestedMaxInputFormatted","pricePerTonne","pricePerTonneFormatted","maxUsdcPricePerTonne","maxUsdcPricePerTonneFormatted","inputTokenSymbol","inputTokenDecimals","slippageBps","humanSummary","relayExecutorGas","relayExecutorGasFormatted","relayTotal","relayTotalFormatted","resolvedCredit","alternatives"],"additionalProperties":false},"PrepareRetireResponse":{"type":"object","properties":{"to":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"data":{"type":"string","pattern":"^0x[a-fA-F0-9]*$"},"chainId":{"anyOf":[{"type":"number","const":8453},{"type":"number","const":84532}]},"chain":{"type":"string"},"transactions":{"type":"array","items":{"type":"object","properties":{"step":{"type":"string"},"to":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"value":{"type":"string"},"data":{"type":"string","pattern":"^0x[a-fA-F0-9]*$"},"chainId":{"anyOf":[{"type":"number","const":8453},{"type":"number","const":84532}]}},"required":["step","to","value","data","chainId"],"additionalProperties":false}},"quote":{"type":"object","properties":{"tonnes":{"type":"string"},"tonnesFormatted":{"type":"string"},"retirementPrice":{"type":"string"},"retirementPriceFormatted":{"type":"string"},"fee":{"type":"string"},"feeFormatted":{"type":"string"},"total":{"type":"string"},"totalFormatted":{"type":"string"},"suggestedMaxInput":{"type":"string"},"suggestedMaxInputFormatted":{"type":"string"},"pricePerTonne":{"type":"string"},"pricePerTonneFormatted":{"type":"string"},"maxUsdcPricePerTonne":{"type":"string"},"maxUsdcPricePerTonneFormatted":{"type":"string"},"inputTokenSymbol":{"type":"string"},"inputTokenDecimals":{"type":"number"},"slippageBps":{"type":"number"},"humanSummary":{"type":"string"}},"required":["tonnes","tonnesFormatted","retirementPrice","retirementPriceFormatted","fee","feeFormatted","total","totalFormatted","suggestedMaxInput","suggestedMaxInputFormatted","pricePerTonne","pricePerTonneFormatted","maxUsdcPricePerTonne","maxUsdcPricePerTonneFormatted","inputTokenSymbol","inputTokenDecimals","slippageBps","humanSummary"],"additionalProperties":false},"approvalRequired":{"type":"boolean","const":true},"approvalInstructions":{"type":"object","properties":{"token":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"spender":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"amount":{"type":"string"},"amountFormatted":{"type":"string"},"note":{"type":"string"}},"required":["token","spender","amount","amountFormatted","note"],"additionalProperties":false}},"required":["to","data","chainId","chain","transactions","quote","approvalRequired","approvalInstructions"],"additionalProperties":false},"PrepareAuthResponse":{"type":"object","properties":{"scheme":{"type":"string","enum":["eip3009","eip2612"]},"chainId":{"anyOf":[{"type":"number","const":8453},{"type":"number","const":84532}]},"chain":{"type":"string"},"inputToken":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"spender":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"authValue":{"type":"string"},"authValueFormatted":{"type":"string"},"executorGas":{"type":"string"},"executorGasFormatted":{"type":"string"},"quote":{"type":"object","properties":{"tonnes":{"type":"string"},"tonnesFormatted":{"type":"string"},"retirementPrice":{"type":"string"},"retirementPriceFormatted":{"type":"string"},"fee":{"type":"string"},"feeFormatted":{"type":"string"},"total":{"type":"string"},"totalFormatted":{"type":"string"},"suggestedMaxInput":{"type":"string"},"suggestedMaxInputFormatted":{"type":"string"},"pricePerTonne":{"type":"string"},"pricePerTonneFormatted":{"type":"string"},"maxUsdcPricePerTonne":{"type":"string"},"maxUsdcPricePerTonneFormatted":{"type":"string"},"inputTokenSymbol":{"type":"string"},"inputTokenDecimals":{"type":"number"},"slippageBps":{"type":"number"},"humanSummary":{"type":"string"}},"required":["tonnes","tonnesFormatted","retirementPrice","retirementPriceFormatted","fee","feeFormatted","total","totalFormatted","suggestedMaxInput","suggestedMaxInputFormatted","pricePerTonne","pricePerTonneFormatted","maxUsdcPricePerTonne","maxUsdcPricePerTonneFormatted","inputTokenSymbol","inputTokenDecimals","slippageBps","humanSummary"],"additionalProperties":false},"resolvedCredit":{"type":"object","properties":{"creditToken":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"tokenId":{"type":"number"},"vintage":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["creditToken","tokenId","vintage"],"additionalProperties":false},"typedData":{"type":"object","properties":{"domain":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"types":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"}},"required":["name","type"],"additionalProperties":false}}},"primaryType":{"type":"string"},"message":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["domain","types","primaryType","message"],"additionalProperties":false},"actionsRetireRequest":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"onChainDetails":{"type":"object","properties":{"retiringAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"retiringEntityString":{"type":"string"},"beneficiaryAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"beneficiaryString":{"type":"string"},"retirementMessage":{"type":"string"},"beneficiaryLocation":{"type":"string"},"consumptionCountryCode":{"type":"string"},"consumptionPeriodStart":{"type":"string"},"consumptionPeriodEnd":{"type":"string"}},"required":["retiringAddress","retiringEntityString","beneficiaryAddress","beneficiaryString","retirementMessage","beneficiaryLocation","consumptionCountryCode","consumptionPeriodStart","consumptionPeriodEnd"],"additionalProperties":false},"note":{"type":"string"},"x402FacilitatorVersion":{"type":"number"}},"required":["scheme","chainId","chain","inputToken","spender","authValue","authValueFormatted","executorGas","executorGasFormatted","quote","resolvedCredit","typedData","actionsRetireRequest","onChainDetails","note","x402FacilitatorVersion"],"additionalProperties":false},"ActionsRetireResponse":{"type":"object","properties":{"status":{"type":"string","enum":["settled","pending_index"]},"transactionHash":{"type":"string"},"chainId":{"anyOf":[{"type":"number","const":8453},{"type":"number","const":84532}]},"chain":{"type":"string"},"quote":{"type":"object","properties":{"tonnes":{"type":"string"},"tonnesFormatted":{"type":"string"},"retirementPrice":{"type":"string"},"retirementPriceFormatted":{"type":"string"},"fee":{"type":"string"},"feeFormatted":{"type":"string"},"total":{"type":"string"},"totalFormatted":{"type":"string"},"suggestedMaxInput":{"type":"string"},"suggestedMaxInputFormatted":{"type":"string"},"pricePerTonne":{"type":"string"},"pricePerTonneFormatted":{"type":"string"},"maxUsdcPricePerTonne":{"type":"string"},"maxUsdcPricePerTonneFormatted":{"type":"string"},"inputTokenSymbol":{"type":"string"},"inputTokenDecimals":{"type":"number"},"slippageBps":{"type":"number"},"humanSummary":{"type":"string"}},"required":["tonnes","tonnesFormatted","retirementPrice","retirementPriceFormatted","fee","feeFormatted","total","totalFormatted","suggestedMaxInput","suggestedMaxInputFormatted","pricePerTonne","pricePerTonneFormatted","maxUsdcPricePerTonne","maxUsdcPricePerTonneFormatted","inputTokenSymbol","inputTokenDecimals","slippageBps","humanSummary"],"additionalProperties":false},"retirementCount":{"type":"number"},"retirements":{"type":"array","items":{"type":"object","properties":{"retirementId":{"type":"string"},"retirementIndex":{"type":"number"},"certificateUrl":{"type":"string"},"amountInTonnes":{"type":"string"},"beneficiaryAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"beneficiaryName":{"type":"string"},"beneficiaryLocation":{"type":"string"},"message":{"type":"string"},"projectId":{"type":"string"},"creditId":{"type":"string"},"retiringAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"timestamp":{"type":"number"}},"required":["retirementId","retirementIndex","certificateUrl","amountInTonnes","beneficiaryAddress","beneficiaryName","beneficiaryLocation","message","projectId","creditId","retiringAddress","timestamp"],"additionalProperties":false}},"note":{"type":"string"},"x402FacilitatorVersion":{"type":"number"}},"required":["status","transactionHash","chainId","chain","quote","retirementCount","retirements","note","x402FacilitatorVersion"],"additionalProperties":false},"CertificateResponse":{"type":"object","properties":{"transactionHash":{"type":"string"},"retirementCount":{"type":"number"},"retirements":{"type":"array","items":{"type":"object","properties":{"retirementId":{"type":"string"},"retirementIndex":{"type":"number"},"certificateUrl":{"type":"string"},"amountInTonnes":{"type":"string"},"beneficiaryAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"beneficiaryName":{"type":"string"},"beneficiaryLocation":{"type":"string"},"message":{"type":"string"},"projectId":{"type":"string"},"creditId":{"type":"string"},"retiringAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"timestamp":{"type":"number"}},"required":["retirementId","retirementIndex","certificateUrl","amountInTonnes","beneficiaryAddress","beneficiaryName","beneficiaryLocation","message","projectId","creditId","retiringAddress","timestamp"],"additionalProperties":false}}},"required":["transactionHash","retirementCount","retirements"],"additionalProperties":false},"CatalogResponse":{"type":"object","properties":{"asOf":{"type":"string"},"endpoints":{"type":"object","properties":{"note":{"type":"string"},"discover":{"type":"object","properties":{"url":{"type":"string"},"method":{"type":"string","enum":["GET","POST"]}},"required":["url","method"],"additionalProperties":false},"quote":{"type":"object","properties":{"url":{"type":"string"},"method":{"type":"string","enum":["GET","POST"]}},"required":["url","method"],"additionalProperties":false},"prepareRetire":{"type":"object","properties":{"url":{"type":"string"},"method":{"type":"string","enum":["GET","POST"]}},"required":["url","method"],"additionalProperties":false},"prepareAuth":{"type":"object","properties":{"url":{"type":"string"},"method":{"type":"string","enum":["GET","POST"]}},"required":["url","method"],"additionalProperties":false},"actionsRetire":{"type":"object","properties":{"url":{"type":"string"},"method":{"type":"string","enum":["GET","POST"]}},"required":["url","method"],"additionalProperties":false},"certificate":{"type":"object","properties":{"url":{"type":"string"},"method":{"type":"string","enum":["GET","POST"]}},"required":["url","method"],"additionalProperties":false},"openapi":{"type":"object","properties":{"url":{"type":"string"},"method":{"type":"string","enum":["GET","POST"]}},"required":["url","method"],"additionalProperties":false},"manifest":{"type":"object","properties":{"url":{"type":"string"},"method":{"type":"string","enum":["GET","POST"]}},"required":["url","method"],"additionalProperties":false}},"required":["note","discover","quote","prepareRetire","prepareAuth","actionsRetire","certificate","openapi","manifest"],"additionalProperties":false},"classes":{"type":"array","items":{"type":"object","properties":{"carbonClassId":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"priceUsdcPerTonne":{"type":"string"},"priceUsdcPerTonneFormatted":{"type":"string"},"priceBasis":{"type":"string","const":"indicative"},"liquidityTonnes":{"type":"string"},"creditCount":{"type":"number"}},"required":["carbonClassId","name","category","country","priceUsdcPerTonne","priceUsdcPerTonneFormatted","priceBasis","liquidityTonnes","creditCount"],"additionalProperties":false}},"listings":{"type":"array","items":{"type":"object","properties":{"listingId":{"type":"string"},"projectName":{"anyOf":[{"type":"string"},{"type":"null"}]},"creditId":{"anyOf":[{"type":"string"},{"type":"null"}]},"registry":{"anyOf":[{"type":"string"},{"type":"null"}]},"vintage":{"anyOf":[{"type":"number"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"priceUsdcPerTonne":{"anyOf":[{"type":"string"},{"type":"null"}]},"priceUsdcPerTonneFormatted":{"anyOf":[{"type":"string"},{"type":"null"}]},"priceBasis":{"type":"string","const":"firm"},"leftToSellTonnes":{"type":"string"},"minFillTonnes":{"type":"string"},"expiresAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["listingId","projectName","creditId","registry","vintage","country","category","priceUsdcPerTonne","priceUsdcPerTonneFormatted","priceBasis","leftToSellTonnes","minFillTonnes","expiresAt"],"additionalProperties":false}},"catalogNote":{"type":"string"}},"required":["asOf","endpoints","classes","listings","catalogNote"],"additionalProperties":false},"PaymentRequired":{"description":"x402 challenge. `accepts[0].extra.typedData` is the authorization to sign; the rest of the body is identical to a GET /api/prepare-auth response.","allOf":[{"type":"object","required":["x402Version","error","accepts"],"properties":{"x402Version":{"type":"integer"},"error":{"type":"string","const":"payment_required"},"accepts":{"type":"array","minItems":1,"items":{"type":"object","required":["scheme","network","maxAmountRequired","payTo","asset"],"properties":{"scheme":{"type":"string","enum":["exact-eip3009","exact-eip2612"]},"network":{"type":"string","examples":["eip155:8453"]},"maxAmountRequired":{"type":"string","description":"Authorized budget in atomic units of `asset`: retirement price + fee + executor gas."},"resource":{"type":"string"},"description":{"type":"string"},"mimeType":{"type":"string"},"payTo":{"type":"string","description":"Settlement contract the authorization is signed to."},"maxTimeoutSeconds":{"type":"integer"},"asset":{"type":"string"},"extra":{"type":"object","properties":{"typedData":{"type":"object"}}}}}}}},{"$ref":"#/components/schemas/PrepareAuthResponse"}]},"Error":{"type":"object","required":["error","x402FacilitatorVersion"],"properties":{"error":{"type":"string","description":"Stable error code; see /.well-known/x402-errors.json."},"message":{"type":"string"},"x402FacilitatorVersion":{"type":"integer"}},"additionalProperties":true},"Health":{"type":"object","required":["ok","version"],"properties":{"ok":{"type":"boolean"},"service":{"type":"string"},"version":{"type":"string"},"x402FacilitatorVersion":{"type":"integer"}}},"Signpost":{"type":"object","description":"Action index with links to the manifest, changelog, error registry and docs.","properties":{"service":{"type":"string"},"apiVersion":{"type":"string"},"actions":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"Changelog":{"type":"object","properties":{"apiVersion":{"type":"string"},"releases":{"type":"array","items":{"type":"object"}}},"additionalProperties":true},"ErrorRegistry":{"type":"object","properties":{"apiVersion":{"type":"string"},"codes":{"type":"array","items":{"type":"object"}}},"additionalProperties":true}}}}