Oracle API Reference

The NCRB Oracle API is a REST API that serves as the primary backend for the dApp. It aggregates data from on-chain contracts and the shared PostgreSQL database, and exposes it through a set of structured JSON endpoints.

API server links: Coming soon. In the meantime, you can run the API locally by cloning ncrb-oracles and following the setup instructions in the repository README.

An interactive Swagger UI is available at /docs and the raw OpenAPI spec at /docs.json on any running instance.

Base URL (Local)

http://localhost:3001

Response Format

All endpoints return a consistent JSON envelope:

// Success
{
  "success": true,
  "data": { }
}

// Error
{
  "success": false,
  "error": "ErrorType",
  "message": "Human-readable description of what went wrong"
}

HTTP status codes used:

Code	Meaning
`200`	Success
`400`	Bad request — missing or invalid parameters
`404`	Resource not found
`500`	Internal server error
`503`	Service unhealthy (no networks configured)

Health

`GET /api/health`

Returns the current health status of the Oracle API service, including database connectivity and per-network contract configuration.

Response:

{
  "status": "healthy",
  "timestamp": "2026-03-18T00:00:00.000Z",
  "environment": "production",
  "services": { "database": true },
  "networks": {
    "avalanche": {
      "configured": true,
      "contracts": {
        "accountManager": "0x39BFC...",
        "assetRegistry": "0xc338f..."
      }
    },
    "ethereum": { "configured": true },
    "xrpl": { "configured": true }
  }
}

Status values: healthy, degraded, unhealthy (503)

Certificates

Certificates represent submitted real-world asset records, indexed from on-chain CertificateSubmitted and CertificateFinalized events.

`GET /api/certificates`

List all certificates. Optionally filter by network.

Query parameters:

Parameter	Type	Description
`network`	string	`avalanche`, `ethereum`, or `xrpl`

`GET /api/certificates/:serialNumber`

Get a single certificate by its on-chain serial number.

Query parameters:

Parameter	Type	Description
`network`	string	Network to query

`GET /api/certificates/registry/:address`

List all certificates submitted by a specific registry address.

`GET /api/certificates/asset-type/:assetType`

List all certificates for a given asset type ID (0–9, 255).

See Asset Types for the full ID reference.

`GET /api/certificates/stats/total`

Returns the total count of certificates across all networks.

Quality Assessment

`POST /api/quality/assess`

Submit a single certificate for quality assessment. The Oracle API scores it across 6 dimensions and returns a composite score (0–100) and rating band (AAA → Not Eligible).

Request body:

{
  "serialNumber": "VCS-2024-001-001",
  "assetType": 0,
  "network": "avalanche",
  "parameters": {
    "vintage": 2023,
    "methodology": "VM0015",
    "additionality": "financial",
    "cobenefits": ["CCB_GOLD", "SDG_13"]
  }
}

Response:

{
  "success": true,
  "data": {
    "serialNumber": "VCS-2024-001-001",
    "score": 78,
    "band": "AA",
    "dimensions": {
      "technicalQuality": 82,
      "additionality": 75,
      "permanence": 80,
      "certificationLevel": 70,
      "socialImpact": 85,
      "vintageCondition": 72
    }
  }
}

`POST /api/quality/assess/batch`

Submit multiple certificates for assessment in a single request.

Request body:

{
  "certificates": [ /* array of individual assess request bodies */ ],
  "network": "avalanche"
}

`GET /api/quality/methodology`

Returns the current scoring methodology — dimension weights, band thresholds, and scoring rules — for each supported asset type.

`GET /api/quality/:serialNumber`

Returns the stored quality metrics for a previously assessed certificate.

Governance Proposals

`GET /api/proposals`

List all governance proposals, optionally filtered by network.

Query parameters:

Parameter	Type	Description
`network`	string	`avalanche`, `ethereum`, or `xrpl`
`status`	string	`pending`, `approved`, `rejected`, `executed`

`GET /api/proposals/:proposalId`

Get a single proposal by ID.

`POST /api/proposals/:proposalId/execute`

Execute an approved proposal on-chain. Requires the Oracle API to be configured with a wallet that holds the appropriate governance role.

Account Management

All write operations require the ACCOUNT_MANAGER_ROLE on the AccountManager contract, held by the Oracle API's configured wallet (ACCOUNT_MANAGER_PRIVATE_KEY).

`GET /api/accounts/:address`

Get account details for an address.

Query parameters:

Parameter	Type	Description
`network`	string	Network to query

Response:

{
  "success": true,
  "data": {
    "address": "0x...",
    "accountType": "MULTISIG",
    "status": "ACTIVE",
    "name": "Verra Registry",
    "metadata": { "organization": "Verra", "website": "https://verra.org" },
    "createdAt": 1700000000
  }
}

`GET /api/accounts`

List all registered accounts, optionally filtered by network, status, or account type.

`POST /api/accounts`

Request body:

{
  "accountAddress": "0x742d35Cc...",
  "accountType": "MULTISIG",
  "name": "Verra Registry",
  "metadata": { "organization": "Verra", "website": "https://verra.org" },
  "network": "avalanche"
}

`PUT /api/accounts/:address/activate`

Activate a previously inactive or suspended account.

`PUT /api/accounts/:address/suspend`

Suspend an active account. Requires a reason in the request body.

`DELETE /api/accounts/:address`

Remove an account from the registry. Requires a reason in the request body.

`POST /api/accounts/:address/roles`

Grant a role to an account.

Request body:

{
  "role": "REGISTRY_ROLE",
  "network": "avalanche"
}

`DELETE /api/accounts/:address/roles/:role`

Revoke a role from an account.

Price Oracle

Price data is aggregated by ncrb-indexer from multiple external sources and stored in the shared database. The Oracle API reads and serves this data.

`GET /api/prices/all`

Returns the latest aggregated price for all asset types.

Response:

{
  "success": true,
  "data": {
    "0": { "assetType": 0, "name": "Carbon Credit", "price": 14.50, "currency": "USD", "unit": "tCO2e", "confidence": 0.92, "updatedAt": "..." },
    "1": { "assetType": 1, "name": "Plastic Credit", "price": 520.00, "currency": "USD", "unit": "tonne", "confidence": 0.85, "updatedAt": "..." }
  }
}

`GET /api/prices/:assetType`

Returns the latest price for a specific asset type by ID.

`GET /api/prices/:assetType/history`

Returns historical price data.

Query parameters:

Parameter	Type	Description
`period`	string	`24h`, `7d`, `30d`, `90d`, `1y`

`GET /api/prices/:assetType/sources`

Returns the configured price sources for an asset type, including reliability scores and last fetch times.

Standards

`GET /api/standards`

List all on-chain standards from StandardsRegistry.

`GET /api/standards/:standardId`

Get details for a specific standard by its bytes32 identifier.

`GET /api/standards/check/:standardId/:assetType`

Check whether a standard is applicable to a given asset type.

Compliance

`GET /api/compliance/certificate/:serial`

Get all compliance records for a certificate.

`GET /api/compliance/record/:recordId`

Get a single compliance record.

`GET /api/compliance/check/:serial/:standardId`

Check compliance status for a certificate against a specific standard.

`GET /api/compliance/effective-status/:recordId`

Returns the effective compliance status with automatic expiry evaluation applied.

Buyer Claims

Records of on-chain credit retirements, indexed from BuyerClaimsRegistry events.

`GET /api/claims/:claimId`

Get a single retirement claim by ID.

`GET /api/claims/buyer/:address`

Get all retirement claims for a buyer wallet address.

`GET /api/claims/certificate/:serial`

Get all retirement claims for a specific certificate.

Quality Profiles

`GET /api/quality-profiles/:assetType`

Returns the on-chain quality profile for an asset type — the dimension names and their weights as configured in QualityAssessment.

Response:

{
  "success": true,
  "data": {
    "assetType": 0,
    "dimensions": ["Technical Quality", "Additionality", "Permanence", "Certification Level", "Social Impact", "Vintage/Condition"],
    "weights": [25, 20, 20, 15, 12, 8]
  }
}

`GET /api/quality-profiles/:assetType/bands`

Returns the rating bands for an asset type (AAA, AA, A, BBB, Not Eligible) with their score ranges and price multipliers.

`GET /api/quality-profiles/score/:serialNumber`

Returns the quality score stored on-chain for a specific certificate.

Marketplace

The Marketplace API surfaces data from RWAMarketplace.sol. All endpoints are DB-first with on-chain RPC fallback. Listing objects include certificate metadata joined from the most recent approved certificate for the listing's asset type.

`GET /api/marketplace/listings`

List marketplace listings with optional filtering and sorting.

Query parameters:

Parameter	Type	Description
`network`	string	`avalanche`, `ethereum`, or `xrpl`
`asset_type`	number	Filter by asset type ID (0–9)
`status`	number	`0`=ACTIVE, `1`=SOLD, `2`=CANCELLED, `3`=EXPIRED
`seller`	string	Filter by seller address
`q`	string	Free-text search (project name, country, methodology)
`sort_by`	string	`listing_id` \| `price_per_token` \| `amount_remaining` \| `created_at`
`sort_dir`	string	`asc` \| `desc`
`limit` / `offset`	number	Pagination (default limit: 20)

Response includes these certificate-derived fields (null when no approved certificate exists):

certificateSerial, projectId, projectName, vintage, qualityScore, unit, methodology, country, subType, sdgGoals, projectImageUrl, latitude, longitude, correspondingAdjustment, creditMechanism

`GET /api/marketplace/listings/:listingId`

Get a single listing by its on-chain listingId. Returns the same object shape as the list endpoint.

`GET /api/marketplace/trades`

List completed trades.

Query parameters:

Parameter	Type	Description
`network`	string	Network
`buyer`	string	Filter by buyer address
`seller`	string	Filter by seller address
`aggregator`	string	Filter by aggregator address
`listing_id`	number	Filter all trades for a specific listing

`GET /api/marketplace/trades/:tradeId`

Get a single trade by ID.

`GET /api/marketplace/stats`

Returns aggregated marketplace statistics: active/total listing counts, total trade count, total volume, platform fees, aggregator fees, and a breakdown by asset type.

`GET /api/marketplace/user/:address/listings`

All listings where :address is the seller.

`GET /api/marketplace/user/:address/trades`

All trades where :address is the buyer or seller.

`GET /api/marketplace/aggregators`

List all registered aggregator addresses with royalty rates and volume stats.

`GET /api/marketplace/aggregators/:address`

Single aggregator details.

Registry Lookup

These endpoints proxy public registry APIs (Verra, Gold Standard, and Isometric) to enable the Import Certificate workflow in the dApp. Results are cached in memory (5 min) and in the database (24 h) to reduce upstream traffic.

`GET /api/registry-lookup`

Search for projects across supported registries.

Query parameters:

Parameter	Type	Description
`registry`	string	`verra`, `goldstandard`, or `isometric`
`projectId`	string	Exact project ID (e.g. `981`, `GS12282`, `prj_1K3VWSDS61S0QKV7`)
`name`	string	Project name keyword (GS name search is limited — returns most-recently-updated only)

Either projectId or name must be provided.

Response:

{
  "success": true,
  "data": {
    "projects": [
      {
        "projectId": "981",
        "name": "Tambopata-Bahuaja Forest Conservation",
        "country": "Peru",
        "status": "Registered",
        "registry": "verra"
      }
    ]
  }
}

`GET /api/registry-lookup/details`

Fetch full project detail including credit vintages and issuance batches. Used by the Import Certificate tab to pre-fill the Submit Certificate form.

Query parameters:

Parameter	Type	Description
`registry`	string	`verra`, `goldstandard`, or `isometric`
`projectId`	string	Project ID (e.g. `981`, `GS12282`, `prj_1K3VWSDS61S0QKV7`)

Response:

{
  "success": true,
  "data": {
    "projectId": "GS12282",
    "name": "Efficient Cookstoves Kenya",
    "description": "...",
    "country": "Kenya",
    "status": "Registered",
    "proponent": "South Pole",
    "creditingPeriodStart": "2019-01-01",
    "creditingPeriodEnd": "2029-01-01",
    "estimatedAnnualCredits": 1676293,
    "sdgGoals": [1, 3, 4, 5, 7, 8, 13, 15],
    "issuances": [
      {
        "serialNumber": "GS1-1-KE-GS12282-VER-2023-...",
        "vintage": 2023,
        "quantity": 84000,
        "status": "Issued",
        "issuanceDate": "2024-03-15"
      }
    ],
    "registry": "goldstandard",
    "_cached": false
  }
}

Fields pre-filled into the Submit Certificate form:

Form field	Source
Project ID, Name, Description, Country	Project metadata
Vintage	Per-issuance vintage year
Volume	Issuance `quantity` (Verra) or `estimatedAnnualCredits` (GS)
Crediting Period	`creditingPeriodStart` / `creditingPeriodEnd`
SDG Goals	`sdgGoals` array (goal numbers 1–17)
Serial Number	Verra issuance serial (GS and Isometric serials entered manually)

`GET /api/registry-lookup/issuances`

Extract issuance dates from Verra project PDFs. Downloads VCS issuance documents and scans for vintage start, vintage end, and issue date per vintage period. Uses regex pattern-matching first; falls back to AI if no structured data is found.

Query parameters:

Parameter	Type	Description
`project_id`	string	Verra project ID (numeric, e.g. `1735`)
`method`	string	`auto` (regex → AI fallback, default), `regex`, or `ai`

Response:

{
  "projectId": "1735",
  "registry": "verra",
  "documents": [
    {
      "document_name": "VCS1735_Issuance_2021.pdf",
      "uri": "https://registry.verra.org/...",
      "method": "regex",
      "vintages": [
        { "vintage_start": "2019-01-01", "vintage_end": "2019-12-31", "issue_date": "2021-04-15" }
      ]
    }
  ]
}

Verra-only. Takes 30–60 seconds on first call (PDF download + parse).

`GET /api/registry-lookup/serials`

Fetch the full list of issuance serial number blocks for a project. Verra uses a headless browser (Puppeteer) to scrape the registry page. Isometric uses the REST API directly.

Query parameters:

Parameter	Type	Description
`project_id`	string	Registry project ID (numeric for Verra; `prj_XXXX` for Isometric)
`registry`	string	`verra` (default) or `isometric`

Response: Same shape as the issuances array in /details — serialNumber, vintage, quantity, status.

Verra takes 30–60 seconds (browser launch + page render). Isometric is fast (REST API call).

Registry-Specific Notes

Verra (VCS, CCB, SD VISta, Plastic, GHG)

Project search and issuance data are available via the Verra UIAPI
Serial number format: VCS-{vintage}-{start}-{end} (varies by program)

Gold Standard

Upstream API: https://export-registry.goldstandard.org — public, no auth required
ID lookup uses a 3-call strategy: GET /credits?q=GS{id} → find matching sustaincert_id → GET /projects/{internalId} → GET /credits?project_id={internalId}
Name search returns the 25 most recently updated projects with client-side filtering — not a full-text search
SDG goals are extracted directly from the export API (sustainable_development_goals[].name) — no document parsing required
Article 6 data is not exposed by the export API and must be entered manually

Isometric

Upstream API: https://api.isometric.com/registry/v0/ — requires Authorization: Bearer <token> + x-client-secret: <secret> headers (env: ISOMETRIC_API_TOKEN, ISOMETRIC_CLIENT_SECRET)
Project IDs are in prj_XXXX format; also accepts short codes (e.g. TS26) or name search
Serials are fetched from /issuances?project_id=X → /issuances/{id}/credit_batches → supplier_credit_batches[].serial_number
Vintage derived from sequestered_on date; quantity from size.credits (tonnes CO₂e)
No PDF scanning required — API-native registry
SDG goals and Article 6 data are not available from the Isometric API

Registry Standards (Database-Driven)

`GET /api/registry-standards/registries`

List all registry organisations configured in the database (Verra, Gold Standard, ACR, CAR, ART, etc.).

`GET /api/registry-standards/methodologies/:registryId`

List methodologies available for a registry (e.g. VCS, CCB, SD VISta for Verra).

`GET /api/registry-standards/quality-parameters/:registryId/:assetTypeId`

Returns the quality parameter definitions and scoring rules for a specific registry + asset type combination.

`GET /api/registry-standards/sub-types`

Returns the available sub-types for a given asset type. Used by the /registry form Sub-Type dropdown.

Query parameters:

Parameter	Type	Description
`asset_type_code`	number	Asset type ID (0–9, 255)

Sub-types with affectsScoring: true modify the Oracle quality score. See Quality Scoring for the full bonus table.

IPFS

`POST /api/ipfs/upload`

Upload certificate metadata to IPFS. The Oracle API attempts providers in order: Filebase → Pinata → Web3.Storage → NFT.Storage.

Request: multipart/form-data with a file field.

Response:

{
  "success": true,
  "data": {
    "cid": "bafybeig...",
    "url": "ipfs://bafybeig...",
    "provider": "filebase"
  }
}

SDG Definitions

`GET /api/sdg/definitions`

Returns all 17 UN Sustainable Development Goals with names, short names, official colors, and icon URLs.

`GET /api/sdg/certificate/:serialNumber`

Returns the SDG mappings for a specific certificate — which SDGs the project contributes to.

`GET /api/sdg/stats`

Returns per-SDG adoption counts across all approved certificates, ordered by adoption rate.

Countries

`GET /api/countries`

List all countries. Optionally filter by region.

Query parameters:

Parameter	Type	Description
`region`	string	`Africa`, `Americas`, `Asia`, `Europe`, `Oceania`

`GET /api/countries/regions`

List all available region names.

Cron / Price Fetcher

`GET /api/cron`

Returns the status of the price fetcher — last run time, next scheduled run, and per-source fetch results.

The price fetcher is driven by ncrb-indexer, not the Oracle API. This endpoint reflects the state stored in the database by the indexer.

Base URL (Local)
Response Format
Health
- GET /api/health
Certificates
Quality Assessment
Governance Proposals
Account Management
Price Oracle
Standards
Compliance
Buyer Claims
Quality Profiles
Marketplace
Registry Lookup
Registry Standards (Database-Driven)
IPFS
- POST /api/ipfs/upload
SDG Definitions
Countries
- GET /api/countries
- GET /api/countries/regions
Cron / Price Fetcher
- GET /api/cron

Base URL (Local)​

Response Format​

Health​

GET /api/health​

Certificates​

GET /api/certificates​

GET /api/certificates/:serialNumber​

GET /api/certificates/registry/:address​

GET /api/certificates/asset-type/:assetType​

GET /api/certificates/stats/total​

Quality Assessment​

POST /api/quality/assess​

POST /api/quality/assess/batch​

GET /api/quality/methodology​

GET /api/quality/:serialNumber​

Governance Proposals​

GET /api/proposals​

GET /api/proposals/:proposalId​

POST /api/proposals/:proposalId/execute​

Account Management​

GET /api/accounts/:address​

GET /api/accounts​

POST /api/accounts​

PUT /api/accounts/:address/activate​

PUT /api/accounts/:address/suspend​

DELETE /api/accounts/:address​

POST /api/accounts/:address/roles​

DELETE /api/accounts/:address/roles/:role​

Price Oracle​

GET /api/prices/all​

GET /api/prices/:assetType​

GET /api/prices/:assetType/history​

GET /api/prices/:assetType/sources​

Standards​

GET /api/standards​

GET /api/standards/:standardId​

GET /api/standards/check/:standardId/:assetType​

Compliance​

GET /api/compliance/certificate/:serial​

GET /api/compliance/record/:recordId​

GET /api/compliance/check/:serial/:standardId​

GET /api/compliance/effective-status/:recordId​

Buyer Claims​

GET /api/claims/:claimId​

GET /api/claims/buyer/:address​

GET /api/claims/certificate/:serial​

Quality Profiles​

GET /api/quality-profiles/:assetType​

GET /api/quality-profiles/:assetType/bands​

GET /api/quality-profiles/score/:serialNumber​

Marketplace​

GET /api/marketplace/listings​

GET /api/marketplace/listings/:listingId​

GET /api/marketplace/trades​

GET /api/marketplace/trades/:tradeId​

GET /api/marketplace/stats​

GET /api/marketplace/user/:address/listings​

GET /api/marketplace/user/:address/trades​

GET /api/marketplace/aggregators​

GET /api/marketplace/aggregators/:address​

Registry Lookup​

GET /api/registry-lookup​

GET /api/registry-lookup/details​

GET /api/registry-lookup/issuances​

GET /api/registry-lookup/serials​

Registry-Specific Notes​

Registry Standards (Database-Driven)​

GET /api/registry-standards/registries​

GET /api/registry-standards/methodologies/:registryId​

GET /api/registry-standards/quality-parameters/:registryId/:assetTypeId​

GET /api/registry-standards/sub-types​

IPFS​

POST /api/ipfs/upload​

SDG Definitions​

GET /api/sdg/definitions​

GET /api/sdg/certificate/:serialNumber​

GET /api/sdg/stats​

Countries​

GET /api/countries​

GET /api/countries/regions​

Base URL (Local)

Response Format

Health

`GET /api/health`

Certificates

`GET /api/certificates`

`GET /api/certificates/:serialNumber`

`GET /api/certificates/registry/:address`

`GET /api/certificates/asset-type/:assetType`

`GET /api/certificates/stats/total`

Quality Assessment

`POST /api/quality/assess`

`POST /api/quality/assess/batch`

`GET /api/quality/methodology`

`GET /api/quality/:serialNumber`

Governance Proposals

`GET /api/proposals`

`GET /api/proposals/:proposalId`

`POST /api/proposals/:proposalId/execute`

Account Management

`GET /api/accounts/:address`

`GET /api/accounts`

`POST /api/accounts`

`PUT /api/accounts/:address/activate`

`PUT /api/accounts/:address/suspend`

`DELETE /api/accounts/:address`

`POST /api/accounts/:address/roles`

`DELETE /api/accounts/:address/roles/:role`

Price Oracle

`GET /api/prices/all`

`GET /api/prices/:assetType`

`GET /api/prices/:assetType/history`

`GET /api/prices/:assetType/sources`

Standards

`GET /api/standards`

`GET /api/standards/:standardId`

`GET /api/standards/check/:standardId/:assetType`

Compliance

`GET /api/compliance/certificate/:serial`

`GET /api/compliance/record/:recordId`

`GET /api/compliance/check/:serial/:standardId`

`GET /api/compliance/effective-status/:recordId`

Buyer Claims

`GET /api/claims/:claimId`

`GET /api/claims/buyer/:address`

`GET /api/claims/certificate/:serial`

Quality Profiles

`GET /api/quality-profiles/:assetType`

`GET /api/quality-profiles/:assetType/bands`

`GET /api/quality-profiles/score/:serialNumber`

Marketplace

`GET /api/marketplace/listings`

`GET /api/marketplace/listings/:listingId`

`GET /api/marketplace/trades`

`GET /api/marketplace/trades/:tradeId`

`GET /api/marketplace/stats`

`GET /api/marketplace/user/:address/listings`

`GET /api/marketplace/user/:address/trades`

`GET /api/marketplace/aggregators`

`GET /api/marketplace/aggregators/:address`

Registry Lookup

`GET /api/registry-lookup`

`GET /api/registry-lookup/details`

`GET /api/registry-lookup/issuances`

`GET /api/registry-lookup/serials`

Registry-Specific Notes

Registry Standards (Database-Driven)

`GET /api/registry-standards/registries`

`GET /api/registry-standards/methodologies/:registryId`

`GET /api/registry-standards/quality-parameters/:registryId/:assetTypeId`

`GET /api/registry-standards/sub-types`

IPFS

`POST /api/ipfs/upload`

SDG Definitions

`GET /api/sdg/definitions`

`GET /api/sdg/certificate/:serialNumber`

`GET /api/sdg/stats`

Countries

`GET /api/countries`

`GET /api/countries/regions`