Skip to main content

CO2Trust API Overview

The CO2Trust API is a RESTful API built with FastAPI that provides comprehensive access to carbon credit marketplace functionality, NFT management, order processing, and payment services.

Base URL​

  • Testnet: https://api.testnet.co2trust.earth
  • Mainnet: https://api.mainnet.co2trust.earth (when available)
  • Local Development: http://localhost:9002

API Versioning​

The API uses URL-based versioning with the format /co2trust-services/v1/ or /co2trust-payments/v1/ for different service groups.

OpenAPI Documentation​

Interactive API documentation is available at:

  • Swagger UI: https://api.testnet.co2trust.earth/docs
  • ReDoc: https://api.testnet.co2trust.earth/redoc

Architecture​

The API is organized into several router modules:

Core Services (/co2trust-services/v1/)​

  • Authentication: User authentication and authorization
  • Products: Carbon credit product listings and management
  • Orders: Order creation, management, and fulfillment
  • NFTs: Non-fungible token management for carbon credits
  • Suppliers: Carbon credit supplier information
  • Traders: Trader information and management
  • Impact Partners: Impact partner data and management
  • Bundle Orders: Bundled order management
  • Product Orders: Product-order relationships
  • Sync: Blockchain synchronization endpoints
  • Upsert: Generic create/update endpoints
  • Dropdown: Dropdown option endpoints
  • Mailing List: Mailing list management

Payment Services (/co2trust-payments/v1/)​

  • Payment Stats: Payment statistics and analytics
  • Payment Transactions: Payment transaction history
  • Bank Accounts: Bank account management
  • Transfers: Transfer operations

Puro Integration (/puro/)​

  • Inventory: Carbon credit inventory from Puro registry
  • Retirement: Retirement transaction data
  • Sales Channel Services: Puro sales channel API integration

System Endpoints​

  • Health Check: /health - System health status
  • Root: / - API information

Response Format​

All API responses follow a consistent format:

Success Response​

{
  "data": { ... },
  "message": "Success"
}

Paginated Response​

{
  "items": [ ... ],
  "total": 100,
  "page": 1,
  "size": 20,
  "pages": 5
}

Error Response​

{
  "detail": "Error message",
  "status_code": 400
}

Pagination​

Most list endpoints support pagination with the following query parameters:

  • page: Page number (default: 1)
  • size: Items per page (default: 20)
  • order: Sort direction - asc or desc (default: desc)

Rate Limiting​

Rate limiting may be applied to prevent abuse. Check response headers for rate limit information.

CORS​

The API supports Cross-Origin Resource Sharing (CORS) for configured origins. CORS headers are automatically included in responses.

Data Models​

The API uses Pydantic models for request/response validation. TypeScript types are generated from these models and available in the /types directory of the backend repository.

Next Steps​