{"openapi":"3.1.0","info":{"title":"Regen Compute — Developer API","description":"REST API for embedding ecological credit retirement, browsing, and footprint estimation into your applications. Powered by Regen Network.","version":"1.0.0","contact":{"name":"Regen Compute","url":"https://github.com/regen-network/regen-compute"},"license":{"name":"Apache-2.0","url":"https://www.apache.org/licenses/LICENSE-2.0"}},"servers":[{"url":"https://compute.regen.network/api/v1","description":"Regen Compute API"}],"security":[{"BearerAuth":[]}],"paths":{"/retire":{"post":{"operationId":"retireCredits","summary":"Retire ecocredits on Regen Network","description":"Execute an on-chain credit retirement. When a wallet is configured, credits are purchased and retired via MsgBuyDirect. Otherwise, returns a marketplace link for manual purchase.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetireRequest"}}}},"responses":{"200":{"description":"Retirement result (success or marketplace fallback)","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/RetireSuccess"},{"$ref":"#/components/schemas/RetireMarketplace"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/credits":{"get":{"operationId":"browseCredits","summary":"Browse available ecocredits","description":"Returns live marketplace data including credit class listings, active sell orders, and recent marketplace orders.","parameters":[{"name":"type","in":"query","description":"Filter by credit type: 'all', 'carbon', or 'biodiversity'","schema":{"type":"string","enum":["all","carbon","biodiversity"],"default":"all"}},{"name":"max_results","in":"query","description":"Maximum number of items to return per category (max 50)","schema":{"type":"integer","default":10,"maximum":50}}],"responses":{"200":{"description":"Available credits data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/footprint":{"get":{"operationId":"estimateFootprint","summary":"Estimate AI session ecological footprint","description":"Provides a heuristic estimate of the ecological footprint of an AI session based on duration and tool call count.","parameters":[{"name":"session_minutes","in":"query","required":true,"description":"Duration of the AI session in minutes","schema":{"type":"number","minimum":0.1}},{"name":"tool_calls","in":"query","description":"Number of tool calls made during the session","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Footprint estimate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FootprintResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/certificates/{id}":{"get":{"operationId":"getCertificate","summary":"Get retirement certificate","description":"Retrieve a retirement certificate by its node ID or transaction hash.","parameters":[{"name":"id","in":"path","required":true,"description":"Retirement node ID (e.g. WyJy...) or transaction hash","schema":{"type":"string"}}],"responses":{"200":{"description":"Retirement certificate details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertificateResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/accounting":{"get":{"operationId":"getAccounting","summary":"Get financial accounting summary","description":"Admin-only endpoint. Returns a complete financial summary including revenue, Stripe fees, credit/burn/ops allocation splits, credit spending, REGEN burns, subscriber stats, and monthly breakdown. Previously CLI-only.","responses":{"200":{"description":"Financial accounting summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Forbidden — admin access required"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/pool/history":{"get":{"operationId":"getPoolHistory","summary":"Get pool retirement history","description":"Returns the history of monthly pool retirement runs with revenue, credit retirements, burn allocations, and per-subscriber attributions for the most recent run.","parameters":[{"name":"limit","in":"query","description":"Maximum number of pool runs to return (max 50)","schema":{"type":"integer","default":10,"maximum":50}}],"responses":{"200":{"description":"Pool run history with attributions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PoolHistoryResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/usage":{"get":{"operationId":"getUsage","summary":"Get your API usage stats","description":"Returns API usage statistics for the authenticated user, including per-endpoint breakdown and recent request log. Scoped to the calling API key only.","parameters":[{"name":"limit","in":"query","description":"Maximum number of recent requests to return (max 500)","schema":{"type":"integer","default":100,"maximum":500}},{"name":"endpoint","in":"query","description":"Filter recent requests by endpoint path","schema":{"type":"string"}}],"responses":{"200":{"description":"API usage statistics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/burn/history":{"get":{"operationId":"getBurnHistory","summary":"Get REGEN burn history","description":"Returns the full burn ledger including pending burn budget, total REGEN burned, and individual burn transaction records.","responses":{"200":{"description":"Burn history with accumulator status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BurnHistoryResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/ecobridge/tokens":{"get":{"operationId":"getEcoBridgeTokens","summary":"List ecoBridge supported tokens","description":"Returns all tokens and chains supported by ecoBridge for cross-chain credit retirement payments. Tokens are grouped by chain with current USD prices.","parameters":[{"name":"chain","in":"query","description":"Filter by chain name (e.g., 'ethereum', 'polygon', 'base')","schema":{"type":"string"}}],"responses":{"200":{"description":"Supported tokens grouped by chain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EcoBridgeTokensResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/ecobridge/projects":{"get":{"operationId":"getEcoBridgeProjects","summary":"List ecoBridge projects","description":"Returns all ecological projects available for credit retirement via ecoBridge, including pricing and location details.","responses":{"200":{"description":"Available ecoBridge projects","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EcoBridgeProjectsResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/community/goals":{"get":{"operationId":"getCommunityGoals","summary":"Get community goals and progress","description":"Returns the active community retirement goal, progress toward it, subscriber count, total credits retired, and historical goals.","responses":{"200":{"description":"Community goals and progress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommunityGoalsResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/scheduled-retirements":{"get":{"operationId":"getScheduledRetirements","summary":"List scheduled retirements","description":"Returns scheduled retirements with status breakdown. Scheduled retirements are created from yearly subscriptions and executed on their scheduled date.","parameters":[{"name":"status","in":"query","description":"Filter by status (pending, running, completed, partial, failed)","schema":{"type":"string","enum":["pending","running","completed","partial","failed"]}},{"name":"limit","in":"query","description":"Maximum number of retirements to return (max 200)","schema":{"type":"integer","default":50,"maximum":200}}],"responses":{"200":{"description":"Scheduled retirements with status summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledRetirementsResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/impact":{"get":{"operationId":"getImpact","summary":"Get Regen Network impact summary","description":"Returns aggregate statistics about the Regen Network including credit classes, projects, retirements, and marketplace orders.","responses":{"200":{"description":"Impact summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImpactResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key obtained from Stripe checkout. Format: rfa_..."}},"schemas":{"RetireRequest":{"type":"object","properties":{"credit_class":{"type":"string","description":"Credit class abbreviation (C, BT, MBS, KSH, USS)","example":"C"},"quantity":{"type":"number","description":"Number of credits to retire","default":1,"minimum":0.000001},"beneficiary_name":{"type":"string","description":"Name to appear on the retirement certificate"},"jurisdiction":{"type":"string","description":"ISO jurisdiction code (e.g. US, BR, KE)","example":"US"},"reason":{"type":"string","description":"Reason for retirement"}}},"RetireSuccess":{"type":"object","required":["status","tx_hash","credits_retired"],"properties":{"status":{"type":"string","enum":["success"]},"tx_hash":{"type":"string"},"credits_retired":{"type":"string"},"cost":{"type":"string"},"block_height":{"type":"integer"},"certificate_id":{"type":"string","nullable":true},"certificate_url":{"type":"string","format":"uri","nullable":true},"jurisdiction":{"type":"string"},"reason":{"type":"string"},"beneficiary_name":{"type":"string","nullable":true},"remaining_balance_cents":{"type":"integer","nullable":true}}},"RetireMarketplace":{"type":"object","required":["status","marketplace_url"],"properties":{"status":{"type":"string","enum":["marketplace_link"]},"marketplace_url":{"type":"string","format":"uri"},"message":{"type":"string"}}},"CreditsResponse":{"type":"object","properties":{"marketplace_snapshot":{"type":"array","items":{"type":"object","properties":{"credit_type":{"type":"string"},"credit_type_abbreviation":{"type":"string"},"available_credits":{"type":"number"},"sell_orders":{"type":"integer"}}}},"credit_classes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"type_abbreviation":{"type":"string"},"projects":{"type":"integer"},"jurisdictions":{"type":"array","items":{"type":"string"}}}}},"sell_orders":{"type":"array","items":{"type":"object","properties":{"batch_denom":{"type":"string"},"quantity":{"type":"string"},"ask_amount":{"type":"string"},"ask_denom":{"type":"string"}}}},"recent_orders":{"type":"array","items":{"type":"object","properties":{"project_id":{"type":"string"},"credits_amount":{"type":"string"},"total_price":{"type":"string"},"ask_denom":{"type":"string"},"retired":{"type":"boolean"}}}}}},"FootprintResponse":{"type":"object","required":["session_minutes","estimated_queries","energy_kwh","co2_kg"],"properties":{"session_minutes":{"type":"number"},"estimated_queries":{"type":"integer"},"energy_kwh":{"type":"number"},"co2_kg":{"type":"number"},"co2_tonnes":{"type":"number"},"equivalent_carbon_credits":{"type":"number"},"equivalent_cost_usd":{"type":"number"},"methodology_note":{"type":"string"}}},"CertificateResponse":{"type":"object","required":["node_id","amount","batch_denom","owner","tx_hash"],"properties":{"node_id":{"type":"string"},"amount":{"type":"string"},"batch_denom":{"type":"string"},"owner":{"type":"string"},"jurisdiction":{"type":"string"},"reason":{"type":"string"},"timestamp":{"type":"string","format":"date-time","nullable":true},"block_height":{"type":"string"},"tx_hash":{"type":"string"},"certificate_url":{"type":"string","format":"uri"}}},"ImpactResponse":{"type":"object","properties":{"credit_classes":{"type":"integer"},"active_projects":{"type":"integer"},"jurisdictions":{"type":"integer"},"total_retirements":{"type":"integer","nullable":true},"total_marketplace_orders":{"type":"integer","nullable":true},"credit_types":{"type":"array","items":{"type":"object","properties":{"abbreviation":{"type":"string"},"name":{"type":"string"}}}}}},"AccountingResponse":{"type":"object","properties":{"totalGrossRevenueCents":{"type":"integer"},"totalStripeFeesCents":{"type":"integer"},"totalNetRevenueCents":{"type":"integer"},"totalCreditsBudgetCents":{"type":"integer"},"totalBurnBudgetCents":{"type":"integer"},"totalOpsBudgetCents":{"type":"integer"},"totalCreditsSpentCents":{"type":"integer"},"totalCreditsUnspentCents":{"type":"integer"},"totalCreditsRetired":{"type":"number"},"avgCostPerCredit":{"type":"integer","nullable":true},"totalBurnsPendingCents":{"type":"integer"},"totalBurnsExecutedCents":{"type":"integer"},"totalRegenBurned":{"type":"number"},"totalBurnTxCount":{"type":"integer"},"avgRegenPriceAtBurn":{"type":"number","nullable":true},"totalOpsAvailableCents":{"type":"integer"},"activeSubscriberCount":{"type":"integer"},"totalRetirementCount":{"type":"integer"},"monthlyRecurringRevenueCents":{"type":"integer"},"monthlyBreakdown":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string"},"grossRevenueCents":{"type":"integer"},"netRevenueCents":{"type":"integer"},"creditsBudgetCents":{"type":"integer"},"creditsSpentCents":{"type":"integer"},"burnBudgetCents":{"type":"integer"},"opsBudgetCents":{"type":"integer"},"creditsRetired":{"type":"number"},"retirementCount":{"type":"integer"}}}}}},"UsageResponse":{"type":"object","properties":{"stats":{"type":"object","properties":{"total_requests":{"type":"integer"},"avg_response_ms":{"type":"integer","nullable":true},"first_request":{"type":"string","nullable":true},"last_request":{"type":"string","nullable":true}}},"endpoints":{"type":"array","items":{"type":"object","properties":{"endpoint":{"type":"string"},"method":{"type":"string"},"count":{"type":"integer"},"avg_response_ms":{"type":"integer","nullable":true}}}},"recent":{"type":"array","items":{"type":"object","properties":{"endpoint":{"type":"string"},"method":{"type":"string"},"status_code":{"type":"integer"},"response_time_ms":{"type":"integer","nullable":true},"created_at":{"type":"string"}}}}}},"PoolHistoryResponse":{"type":"object","properties":{"total_runs":{"type":"integer"},"runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"run_date":{"type":"string"},"status":{"type":"string"},"dry_run":{"type":"boolean"},"subscriber_count":{"type":"integer"},"total_revenue_cents":{"type":"integer"},"total_spent_cents":{"type":"integer"},"carbon_credits_retired":{"type":"number"},"biodiversity_credits_retired":{"type":"number"},"uss_credits_retired":{"type":"number"},"burn_allocation_cents":{"type":"integer"},"ops_allocation_cents":{"type":"integer"},"carry_forward_cents":{"type":"integer"}}}},"latest_attributions":{"type":"array","items":{"type":"object","properties":{"subscriber_id":{"type":"integer"},"contribution_cents":{"type":"integer"},"carbon_credits":{"type":"number"},"biodiversity_credits":{"type":"number"},"uss_credits":{"type":"number"}}}}}},"BurnHistoryResponse":{"type":"object","properties":{"pending_burn_budget_cents":{"type":"integer"},"total_regen_burned":{"type":"number"},"total_allocation_cents":{"type":"integer"},"total_burn_transactions":{"type":"integer"},"burns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"date":{"type":"string"},"allocation_cents":{"type":"integer"},"regen_burned":{"type":"number"},"regen_price_usd":{"type":"number","nullable":true},"tx_hash":{"type":"string","nullable":true},"status":{"type":"string"},"source":{"type":"string"}}}}}},"EcoBridgeTokensResponse":{"type":"object","properties":{"total_tokens":{"type":"integer"},"chains":{"type":"array","items":{"type":"object","properties":{"chain":{"type":"string"},"tokens":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"name":{"type":"string"},"priceUsd":{"type":"number","nullable":true}}}}}}}}},"CommunityGoalsResponse":{"type":"object","properties":{"active_goal":{"type":"object","nullable":true,"properties":{"id":{"type":"integer"},"label":{"type":"string"},"target_credits":{"type":"number"},"deadline":{"type":"string","nullable":true},"progress_percent":{"type":"number","nullable":true},"completed":{"type":"boolean"},"created_at":{"type":"string"}}},"community_stats":{"type":"object","properties":{"total_credits_retired":{"type":"number"},"active_subscribers":{"type":"integer"}}},"goals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"label":{"type":"string"},"target_credits":{"type":"number"},"deadline":{"type":"string","nullable":true},"active":{"type":"boolean"},"created_at":{"type":"string"}}}}}},"EcoBridgeProjectsResponse":{"type":"object","properties":{"total_projects":{"type":"integer"},"projects":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"credit_class":{"type":"string","nullable":true},"price":{"type":"number","nullable":true},"unit":{"type":"string","nullable":true},"location":{"type":"string","nullable":true},"type":{"type":"string","nullable":true}}}}}},"ScheduledRetirementsResponse":{"type":"object","properties":{"stats":{"type":"object","properties":{"total":{"type":"integer"},"pending":{"type":"integer"},"completed":{"type":"integer"},"partial":{"type":"integer"},"failed":{"type":"integer"},"running":{"type":"integer"}}},"retirements":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"subscriber_id":{"type":"integer"},"gross_amount_cents":{"type":"integer"},"net_amount_cents":{"type":"integer"},"billing_interval":{"type":"string"},"scheduled_date":{"type":"string"},"status":{"type":"string"},"retirement_id":{"type":"integer","nullable":true},"error":{"type":"string","nullable":true},"retry_count":{"type":"integer"},"created_at":{"type":"string"},"executed_at":{"type":"string","nullable":true}}}}}},"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}}}}}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"RateLimited":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"ServiceUnavailable":{"description":"Upstream service unavailable (Regen Ledger or Indexer)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}