How to Query Polkadot Ecosystem Governance Data with One PubFi API Key

The problem with Polkadot governance data

Polkadot governance does not live in one place. A team may need chain state from Polkadot, Kusama, Moonbeam, Acala, and other Substrate-based networks, then combine that with DAO activity, proposal context, or governance freshness from a separate source.

That fragmentation creates three problems for developers and agents:

• Different chains expose different upstream hosts and conventions.
• Governance context often needs both chain-level reads and DAO-level activity.
• Agents need structured boundaries so they do not treat every source as the same callable surface.

PubFi's gateway shape gives teams one API key and one route pattern for provider-backed reads:

/api/gateway/{provider}/{network}/{endpoint...}

This is not a single universal governance endpoint. It is a consistent gateway pattern for combining provider-backed reads. This guide uses Darwinia as the chain example, Subscan for chain-level referenda, and DeGov for DAO-level RingDAO activity.

What you need before you start

• A PubFi API key from the dashboard.
• curl or a Python environment with requests installed.
• Basic familiarity with REST APIs and JSON responses.

The examples below use a placeholder key:

pf_sk_v1_production_xxx

Never expose a production API key in client-side code, public repositories, or screenshots.

Step 1: Read referenda through Subscan

Subscan is useful when the workflow needs indexed Substrate or Polkadot ecosystem chain data. Through PubFi, the Subscan gateway route uses the network segment to select the upstream chain host. For Darwinia, the network segment is darwinia.

To query completed Darwinia referenda, send a POST request to the Subscan referenda endpoint:

curl --location 'https://pubfi.ai/api/gateway/subscan/darwinia/api/scan/referenda/referendums' \
  --header 'Authorization: Bearer pf_sk_v1_production_xxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "status": "completed",
    "page": 0,
    "row": 20
  }'

The response uses PubFi's gateway envelope. The upstream Subscan payload is returned inside data:

{
  "ok": true,
  "data": {
    "code": 0,
    "message": "Success",
    "data": {
      "count": 54,
      "list": [
        {
          "referendum_index": 53,
          "origins": "whitelisted_caller",
          "call_module": "Whitelist",
          "call_name": "dispatch_whitelisted_call_with_preimage",
          "status": "Executed",
          "approval_rate": "100",
          "approval_threshold": "99"
        }
      ]
    }
  },
  "meta": {
    "provider": "subscan",
    "network": "darwinia",
    "endpoint": "/api/scan/referenda/referendums",
    "method": "POST",
    "upstream": {
      "status": 200
    }
  }
}

For an agent, this is the chain-level read: Darwinia referenda status, origin, call module, call name, approval rate, and related block metadata.

Step 2: Read DAO activity through DeGov

Subscan helps with chain-level state. DeGov adds DAO-level governance context. In this example, the DeGov route reads a brief for ring-dao.

Use the fixed global network segment for DeGov:

curl --location 'https://pubfi.ai/api/gateway/degov/global/v1/daos/ring-dao/brief' \
  --header 'Authorization: Bearer pf_sk_v1_production_xxx'

The gateway envelope stays consistent while the inner data object remains the upstream DeGov response:

{
  "ok": true,
  "data": {
    "request": {
      "endpoint": "dao-brief",
      "daoId": "ring-dao",
      "activityLimit": 6
    },
    "data": {
      "dao": {
        "daoId": "ring-dao",
        "daoName": "RingDAO",
        "sourceType": "degov-square"
      },
      "overview": {
        "proposalCount": 7,
        "forumTopicCount": 0
      },
      "sync": {
        "overallStatus": "pending"
      },
      "highlights": {
        "proposals": [
          {
            "title": "Funds Transfer for Approved Q2 Budget",
            "status": "closed",
            "isGovernanceRelated": true
          }
        ],
        "discussions": []
      }
    }
  },
  "meta": {
    "provider": "degov",
    "network": "global",
    "endpoint": "/v1/daos/ring-dao/brief",
    "method": "GET",
    "upstream": {
      "status": 200
    }
  }
}

DeGov uses global because its upstream service has one base URL rather than one host per chain. PubFi keeps that convention explicit so agent code can route correctly instead of guessing.

Step 3: Combine chain-level reads and DAO-level activity

A Darwinia governance monitor usually needs both layers:

1. Read chain-level referenda through the Subscan Darwinia gateway route.
2. Read DAO-level context through the DeGov RingDAO brief route.
3. Decide downstream action in your own agent layer, such as sending an alert, opening an internal review task, or preparing a governance summary.

In Python, the gateway pattern can stay explicit:

import requests

API_KEY = "pf_sk_v1_production_xxx"
BASE_URL = "https://pubfi.ai/api/gateway"

headers = {"Authorization": f"Bearer {API_KEY}"}

def gateway_get(provider, network, endpoint):
    url = f"{BASE_URL}/{provider}/{network}/{endpoint.lstrip('/')}"
    response = requests.get(url, headers=headers, timeout=20)
    response.raise_for_status()
    return response.json()

def gateway_post(provider, network, endpoint, payload):
    url = f"{BASE_URL}/{provider}/{network}/{endpoint.lstrip('/')}"
    response = requests.post(url, headers=headers, json=payload, timeout=20)
    response.raise_for_status()
    return response.json()

referenda = gateway_post(
    "subscan",
    "darwinia",
    "/api/scan/referenda/referendums",
    {"status": "completed", "page": 0, "row": 20},
)

ringdao_brief = gateway_get("degov", "global", "/v1/daos/ring-dao/brief")

referendum_count = referenda.get("data", {}).get("data", {}).get("count")
proposal_count = ringdao_brief.get("data", {}).get("data", {}).get("overview", {}).get("proposalCount")

print("Darwinia referenda:", referendum_count)
print("RingDAO proposals:", proposal_count)

The agent still owns the decision policy. PubFi provides a consistent gateway surface for data reads while preserving provider boundaries.

When to use Subscan vs DeGov

Subscan and DeGov are complementary surfaces. A governance workflow should choose the source based on the question being asked, not only the ecosystem name.

Why one API key matters

Without a gateway, a production governance monitor has to manage multiple vendor keys, upstream host conventions, HTTP methods, body shapes, rate-limit behavior, and response formats. That maintenance cost grows as the agent expands from one chain-level read to DAO-level activity.

With PubFi, the caller can keep the outer integration stable:

The result is not a claim that every governance query is one endpoint. It is a cleaner integration model: one PubFi API key, one gateway route pattern, and explicit provider boundaries.

FAQs

Does this replace direct RPC? No. Direct RPC is still useful for low-level storage reads and custom runtime logic. The gateway is for teams that want provider-backed API reads without exposing upstream keys or maintaining one-off integrations.

Does Subscan cover every governance field? No. Subscan is best treated as an indexed chain and explorer-style data surface. DAO-level governance activity may require DeGov or another governance-focused provider.

Why does DeGov use global instead of darwinia? The current DeGov adapter uses a fixed upstream base URL, so PubFi uses global as the network placeholder. That keeps the route contract consistent while preserving provider-specific conventions.

Can an agent call these routes directly? Yes, if it has a valid PubFi API key and follows your team's execution policy. Agents should still read agents.md before assuming anything about gateway calls, MCP manifests, or x402 payment execution.

Where should I start? Use the PubFi gateway quickstart for gateway basics, the DeGov API docs for DAO-level surfaces, the Subscan API profile for source status, and PubFi Discovery when you need to compare crypto data APIs before routing them into an agent workflow.