Developer docs

DeGov API Docs

Live-verified upstream behavior for DeGov and the matching PubFi gateway route conventions.

Overview

This document captures the current DeGov upstream behavior verified on 2026-05-21 against https://agent-api.degov.ai, and the corresponding PubFi gateway integration shape.

Gateway adapter

Provider: degov
Upstream base URL: https://agent-api.degov.ai
Upstream auth header injected by the server: x-degov-api-token: $DEGOV_KEY
PubFi gateway route shape: /api/gateway/{provider}/{network}/{endpoint...}
Recommended DeGov network placeholder: global

Example free route through PubFi:

textExample

/api/gateway/degov/global/v1/daos

Example paid route through PubFi:

textExample

/api/gateway/degov/global/v1/activity

Environment

Add the upstream key to the server environment:

envExample

DEGOV_KEY=

Never expose DEGOV_KEY to the browser. The client only sends the PubFi API key.

Verified endpoints

`GET /health`

Purpose:

Basic service health check.
Access: free

Verified upstream response:

jsonExample

{
  "ok": "<boolean>",
  "service": "<string>"
}

Gateway example:

bashExample

curl --location 'https://pubfi.ai/api/gateway/degov/global/health' \
  --header 'Authorization: Bearer pf_sk_live_xxx'

`GET /v1/meta/pricing`

Purpose:

Returns the current x402 pricing table for DeGov paid endpoints.
Access: free

Verified upstream response:

jsonExample

{
  "request": {
    "endpoint": "<string>"
  },
  "pricing": {
    "token": "<string>",
    "network": "<string>",
    "entries": {
      "daos": {
        "endpoint": "<string>",
        "method": "<string>",
        "path": "<string>",
        "price": null,
        "token": "<string>",
        "network": "<string>",
        "paid": "<boolean>"
      },
      "activity": {
        "endpoint": "<string>",
        "method": "<string>",
        "path": "<string>",
        "price": "<string>",
        "token": "<string>",
        "network": "<string>",
        "paid": "<boolean>"
      },
      "governanceEvents": {
        "endpoint": "<string>",
        "method": "<string>",
        "path": "<string>",
        "price": "<string>",
        "token": "<string>",
        "network": "<string>",
        "paid": "<boolean>"
      },
      "freshness": {
        "endpoint": "<string>",
        "method": "<string>",
        "path": "<string>",
        "price": "<string>",
        "token": "<string>",
        "network": "<string>",
        "paid": "<boolean>"
      },
      "brief": {
        "endpoint": "<string>",
        "method": "<string>",
        "path": "<string>",
        "price": "<string>",
        "token": "<string>",
        "network": "<string>",
        "paid": "<boolean>"
      },
      "item": {
        "endpoint": "<string>",
        "method": "<string>",
        "path": "<string>",
        "price": "<string>",
        "token": "<string>",
        "network": "<string>",
        "paid": "<boolean>"
      }
    }
  }
}

Gateway example:

bashExample

curl --location 'https://pubfi.ai/api/gateway/degov/global/v1/meta/pricing' \
  --header 'Authorization: Bearer pf_sk_live_xxx'

`GET /v1/daos`

Purpose:

Lists covered DAOs and freshness metadata.
Access: free

Verified upstream response shape:

jsonExample

{
  "request": {
    "endpoint": "<string>"
  },
  "freshness": {
    "generatedAt": "<number>",
    "dataAsOf": "<number>",
    "cacheStatus": "<string>"
  },
  "data": {
    "items": [
      {
        "daoId": "<string>",
        "daoName": "<string>",
        "sourceType": "<string>",
        "sourceRef": "<string>",
        "sourceEndpoint": "<string>",
        "forumUrl": null,
        "hasForum": "<boolean>",
        "freshness": {
          "governanceLastSuccessAt": "<number | null>",
          "forumLastSuccessAt": null
        }
      }
    ],
    "total": "<number>"
  }
}

Notes:

The live response contained 886 DAO records at verification time.
items is a large array, so the snippet above is trimmed to representative entries.

Gateway example:

bashExample

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

`GET /v1/activity`

Access:

paid
Verified through the PubFi gateway
Current gateway behavior returns a successful 200 response with PubFi metadata and upstream activity data

Example gateway response:

jsonExample

{
  "ok": "<boolean>",
  "data": {
    "request": {
      "endpoint": "<string>",
      "daoId": null,
      "governanceOnly": "<boolean>",
      "hours": "<number>",
      "limit": "<number>",
      "kinds": ["<string>"]
    },
    "freshness": {
      "generatedAt": "<number>",
      "dataAsOf": "<number>",
      "cacheStatus": "<string>"
    },
    "data": {
      "items": [
        {
          "id": "<string>",
          "kind": "<string>",
          "dao": {
            "daoId": "<string>",
            "daoName": "<string>"
          },
          "title": "<string>",
          "summary": "<string>",
          "whyRelevant": "<string>",
          "sourceUrl": "<string>",
          "discussionUrl": "<string | null>",
          "status": "<string>",
          "isGovernanceRelated": "<boolean>",
          "timestamps": {
            "createdAt": "<number>",
            "updatedAt": "<number>",
            "startAt": "<number | null>",
            "endAt": "<number | null>",
            "lastSeenAt": "<number>"
          },
          "evidenceRef": {
            "kind": "<string>",
            "externalId": "<string>"
          }
        }
      ],
      "total": "<number>",
      "windowHours": "<number>"
    }
  },
  "meta": {
    "requestId": "<string>",
    "provider": "<string>",
    "network": "<string>",
    "endpoint": "<string>",
    "method": "<string>",
    "timestamp": "<string>",
    "upstream": {
      "status": "<number>",
      "latencyMs": "<number>",
      "rateLimit": {
        "limit": null,
        "remaining": null,
        "reset": null,
        "retryAfter": null
      }
    }
  }
}

Notes:

The live response returned 25 items for the default 24 hour window.
The example above is trimmed to representative proposal entries from the full payload.

`GET /v1/system/freshness`

Access:

paid
Verified through the PubFi gateway
Current gateway behavior returns a successful 200 response with PubFi metadata and upstream freshness data

Example gateway response:

jsonExample

{
  "ok": "<boolean>",
  "data": {
    "request": {
      "endpoint": "<string>"
    },
    "freshness": {
      "generatedAt": "<number>",
      "dataAsOf": "<number>",
      "cacheStatus": "<string>"
    },
    "data": {
      "summary": {
        "daoCount": "<number>",
        "proposalCount": "<number>",
        "forumTopicCount": "<number>",
        "governanceTopicCount": "<number>",
        "failedSyncCount": "<number>"
      },
      "sources": {
        "governance": {
          "latestSuccessfulSyncAt": "<number>"
        },
        "discourse": {
          "latestSuccessfulSyncAt": "<number>"
        }
      }
    }
  },
  "meta": {
    "requestId": "<string>",
    "provider": "<string>",
    "network": "<string>",
    "endpoint": "<string>",
    "method": "<string>",
    "timestamp": "<string>",
    "upstream": {
      "status": "<number>",
      "latencyMs": "<number>",
      "rateLimit": {
        "limit": null,
        "remaining": null,
        "reset": null,
        "retryAfter": null
      }
    }
  }
}

Notes:

The live response returns system-wide aggregate counts and latest successful sync timestamps.
This example preserves the current gateway envelope while hiding concrete values behind schema-style placeholders.

`GET /v1/daos/:daoId/brief`

Access:

paid
Verified through the PubFi gateway
Current gateway behavior returns a successful 200 response with PubFi metadata and upstream DAO summary data

Example gateway response:

jsonExample

{
  "ok": "<boolean>",
  "data": {
    "request": {
      "endpoint": "<string>",
      "daoId": "<string>",
      "activityLimit": "<number>"
    },
    "freshness": {
      "generatedAt": "<number>",
      "dataAsOf": "<number>",
      "cacheStatus": "<string>"
    },
    "data": {
      "dao": {
        "daoId": "<string>",
        "daoName": "<string>",
        "sourceType": "<string>",
        "sourceRef": "<string>",
        "sourceEndpoint": "<string>",
        "forumUrl": "<string | null>",
        "hasForum": "<boolean>"
      },
      "overview": {
        "proposalCount": "<number>",
        "forumTopicCount": "<number>"
      },
      "sync": {
        "governanceLastSuccessAt": "<number | null>",
        "forumLastSuccessAt": "<number | null>",
        "overallStatus": "<string>",
        "lastErrorMessage": "<string | null>"
      },
      "highlights": {
        "proposals": [
          {
            "id": "<string>",
            "kind": "<string>",
            "dao": {
              "daoId": "<string>",
              "daoName": "<string>"
            },
            "title": "<string>",
            "summary": "<string>",
            "whyRelevant": "<string>",
            "sourceUrl": "<string>",
            "discussionUrl": "<string | null>",
            "status": "<string>",
            "isGovernanceRelated": "<boolean>",
            "timestamps": {
              "createdAt": "<number>",
              "updatedAt": "<number>",
              "startAt": "<number | null>",
              "endAt": "<number | null>",
              "lastSeenAt": "<number>"
            },
            "evidenceRef": {
              "kind": "<string>",
              "externalId": "<string>"
            }
          }
        ],
        "discussions": [
          {
            "id": "<string>",
            "kind": "<string>",
            "dao": {
              "daoId": "<string>",
              "daoName": "<string>"
            },
            "title": "<string>",
            "summary": "<string>",
            "whyRelevant": "<string>",
            "sourceUrl": "<string>",
            "discussionUrl": "<string | null>",
            "status": "<string>",
            "isGovernanceRelated": "<boolean>",
            "timestamps": {
              "createdAt": "<number>",
              "updatedAt": "<number>",
              "startAt": "<number | null>",
              "endAt": "<number | null>",
              "lastSeenAt": "<number>"
            },
            "evidenceRef": {
              "kind": "<string>",
              "externalId": "<string>"
            }
          }
        ]
      }
    }
  },
  "meta": {
    "requestId": "<string>",
    "provider": "<string>",
    "network": "<string>",
    "endpoint": "<string>",
    "method": "<string>",
    "timestamp": "<string>",
    "upstream": {
      "status": "<number>",
      "latencyMs": "<number>",
      "rateLimit": {
        "limit": null,
        "remaining": null,
        "reset": null,
        "retryAfter": null
      }
    }
  }
}

Notes:

The live response includes DAO identity, summary counts, sync health, and recent highlighted proposals or discussions.
This example preserves the nested response shape while hiding concrete values behind schema-style placeholders.

`GET /v1/items/:kind/:externalId`

Access:

paid
Verified through the PubFi gateway
Current gateway behavior returns a successful 200 response with PubFi metadata and upstream item detail data

Example gateway response:

jsonExample

{
  "ok": "<boolean>",
  "data": {
    "request": {
      "endpoint": "<string>",
      "kind": "<string>",
      "externalId": "<string>"
    },
    "freshness": {
      "generatedAt": "<number>",
      "dataAsOf": "<number>",
      "cacheStatus": "<string>"
    },
    "data": {
      "item": {
        "kind": "<string>",
        "externalId": "<string>",
        "dao": {
          "daoId": "<string>",
          "daoName": "<string>"
        },
        "title": "<string>",
        "summary": "<string>",
        "whyRelevant": "<string>",
        "sourceUrl": "<string>",
        "discussionUrl": "<string | null>",
        "status": "<string>",
        "timestamps": {
          "createdAt": "<number>",
          "updatedAt": "<number>",
          "startAt": "<number | null>",
          "endAt": "<number | null>",
          "lastSeenAt": "<number>"
        },
        "cacheStatus": "<string>",
        "live": {
          "source": "<string>",
          "daoId": "<string>",
          "externalId": "<string>",
          "title": "<string>",
          "state": "<string>",
          "created": "<number>",
          "start": "<number | null>",
          "end": "<number | null>",
          "discussion": "<string | null>",
          "link": "<string>",
          "registryUrl": "<string>"
        }
      }
    }
  },
  "meta": {
    "requestId": "<string>",
    "provider": "<string>",
    "network": "<string>",
    "endpoint": "<string>",
    "method": "<string>",
    "timestamp": "<string>",
    "upstream": {
      "status": "<number>",
      "latencyMs": "<number>",
      "rateLimit": {
        "limit": null,
        "remaining": null,
        "reset": null,
        "retryAfter": null
      }
    }
  }
}

Notes:

The live response includes the normalized item record together with a nested live payload from the upstream source.
This example preserves the current gateway envelope and nested item shape while hiding concrete values behind schema-style placeholders.

Notes:

5000 base units maps to the 0.005 USDC price reported by /v1/meta/pricing.
10000 base units maps to the 0.01 USDC price reported by /v1/meta/pricing.
The upstream service also returns a payment-required response header containing an encoded x402 descriptor.

Gateway example:

bashExample

curl --location 'https://pubfi.ai/api/gateway/degov/global/v1/activity' \
  --header 'Authorization: Bearer pf_sk_live_xxx'

PubFi gateway behavior for DeGov

From the client point of view, DeGov follows the same PubFi envelope as other providers:

Client auth: Authorization: Bearer pf_sk_live_xxx or X-PubFi-Api-Key
Upstream auth: injected server-side as x-degov-api-token
Success: 200 with { ok: true, data, meta }
Upstream paid or failed response: surfaced as gateway.upstream_error

Expected gateway error example for a paid endpoint without x402 settlement:

jsonExample

{
  "ok": false,
  "error": {
    "code": "gateway.upstream_error",
    "message": "The upstream provider returned an error.",
    "details": {
      "error": "Payment required",
      "paymentRequired": {
        "scheme": "exact",
        "network": "eip155:8453",
        "amount": "5000",
        "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "payTo": "0x81a29baAb452D14D878762dcf9a51bc9062113DF"
      }
    },
    "docsUrl": "https://agent-api.degov.ai/v1/meta/pricing"
  }
}