Skip to main content

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:

CodeMeaning
200Success
400Bad request — missing or invalid parameters
404Resource not found
500Internal server error
503Service 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:

ParameterTypeDescription
networkstringavalanche, ethereum, or xrpl

GET /api/certificates/:serialNumber​

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

Query parameters:

ParameterTypeDescription
networkstringNetwork 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:

ParameterTypeDescription
networkstringavalanche, ethereum, or xrpl
statusstringpending, 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:

ParameterTypeDescription
networkstringNetwork 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​

Register a new account on-chain.

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:

ParameterTypeDescription
periodstring24h, 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:

ParameterTypeDescription
networkstringavalanche, ethereum, or xrpl
asset_typenumberFilter by asset type ID (0–9)
statusnumber0=ACTIVE, 1=SOLD, 2=CANCELLED, 3=EXPIRED
sellerstringFilter by seller address
qstringFree-text search (project name, country, methodology)
sort_bystringlisting_id | price_per_token | amount_remaining | created_at
sort_dirstringasc | desc
limit / offsetnumberPagination (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:

ParameterTypeDescription
networkstringNetwork
buyerstringFilter by buyer address
sellerstringFilter by seller address
aggregatorstringFilter by aggregator address
listing_idnumberFilter 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:

ParameterTypeDescription
registrystringverra, goldstandard, or isometric
projectIdstringExact project ID (e.g. 981, GS12282, prj_1K3VWSDS61S0QKV7)
namestringProject 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:

ParameterTypeDescription
registrystringverra, goldstandard, or isometric
projectIdstringProject 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 fieldSource
Project ID, Name, Description, CountryProject metadata
VintagePer-issuance vintage year
VolumeIssuance quantity (Verra) or estimatedAnnualCredits (GS)
Crediting PeriodcreditingPeriodStart / creditingPeriodEnd
SDG GoalssdgGoals array (goal numbers 1–17)
Serial NumberVerra 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:

ParameterTypeDescription
project_idstringVerra project ID (numeric, e.g. 1735)
methodstringauto (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:

ParameterTypeDescription
project_idstringRegistry project ID (numeric for Verra; prj_XXXX for Isometric)
registrystringverra (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:

ParameterTypeDescription
asset_type_codenumberAsset 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:

ParameterTypeDescription
regionstringAfrica, 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.