# PubFi Agents

> Agent-readable guide for using public PubFi Discovery and Gateway resources.

Source: public site content, product metadata, Discovery catalog fixtures, and OpenAPI files in this repository.
Format: text/markdown; charset=utf-8
Scope: public docs, public Discovery exports, public OpenAPI schemas, and auth-required gateway examples.
Private-data rule: dashboard routes, account usage, API keys, billing state, provider credentials, and supplier procurement records are not exposed here.

## Start Here
- [Agents guide](https://pubfi.ai/agents.md): public. Markdown guide for agents using PubFi public docs, OpenAPI schemas, capability routes, and auth-required gateway routes.
- [LLMs index](https://pubfi.ai/llms.txt): public. Concise index of public PubFi pages, documentation, Discovery exports, and integration resources.
- [PubFi Discovery full export](https://pubfi.ai/llms-full.txt): public. Expanded Discovery export generated from public catalog fixtures and publication gates.
- [Capability discovery JSON](https://pubfi.ai/discovery/agent-capabilities.json): public. Contract-derived capability, input schema, envelope, provenance, freshness, and dry-run planning artifact.
- [PubFi Capability OpenAPI](https://pubfi.ai/openapi/pubfi-capabilities-openapi.json): public. OpenAPI 3.1 schema for capability discovery and dry-run route planning over PubFi contracts. Runtime calls use /api/capabilities/{capability_id}.
- [PubFi Discovery](https://pubfi.ai/discovery): public. Public crypto API directory with provider, chain, category, capability, commercial, and claim-safe status metadata.

## API Auth
- Capability runtime route pattern: `/api/capabilities/{capability_id}`. Supported v1 ids: `wallet.token_balances`, `market.token_price`, and `governance.proposals`.
- Preferred repeated-use surface: call PubFi capability routes when one matches the task; inspect `meta.provenance.gateway_route` only as selected-provider provenance.
- Lower-level gateway route pattern: auth-required `/api/gateway/{provider}/{network}/{endpoint...}`.
- Accepted auth headers: Authorization: Bearer <PubFi API key> or X-PubFi-Api-Key: <PubFi API key>.
- Live capability and gateway calls require a PubFi API key when they execute an upstream provider route.
- Capability runtime responses use `pubfi.capability.response.v1` normalized envelopes with request id, provenance, freshness, route metadata, upstream metadata when observed, and explicit warnings for degraded or fixture-backed responses.
- Capability OpenAPI describes dry-run `/v1/capabilities` and `/v1/plan` surfaces generated from checked-in capability contracts; runtime capability calls use `/api/capabilities/{capability_id}`.
- Upstream provider credentials, supplier payment details, billing state, and procurement approval state stay server-side.
- Dashboard pages are authenticated account UI and are not public agent-readable data sources.

## Public OpenAPI And Docs
- [Gateway quickstart](https://pubfi.ai/docs/quickstart): public. PubFi API-key authentication, gateway headers, route shape, credits, and response contract.
- [PubFi Capability OpenAPI](https://pubfi.ai/openapi/pubfi-capabilities-openapi.json): public. OpenAPI 3.1 schema for capability discovery and dry-run route planning. Runtime capability calls use /api/capabilities/{capability_id}; provider routes remain lower-level details.
- [DeGov OpenAPI](https://pubfi.ai/openapi/degov-openapi.json): public. OpenAPI 3.1 schema for DeGov gateway routes. Gateway calls require a PubFi API key.
- [DeGov docs](https://pubfi.ai/docs/degov-api): public. Docs for DeGov gateway use. Gateway calls are auth-required.
- [Subscan OpenAPI](https://pubfi.ai/openapi/subscan-openapi.json): public. OpenAPI 3.1 schema for Subscan gateway routes. Gateway calls require a PubFi API key.
- [Subscan docs](https://pubfi.ai/docs/quickstart): public. Docs for Subscan gateway use. Gateway calls are auth-required.

## Capability Runtime Examples
- Wallet balances: `POST /api/capabilities/wallet.token_balances` with `wallet_address`, `network`, and optional `chain`.
- Market price: `GET /api/capabilities/market.token_price?asset_id=polkadot:dot&quote_currency=USD`; currently fixture-backed and marked `contract_ready`.
- Governance proposals: `GET /api/capabilities/governance.proposals?chain=polkadot&network=global&governance_system=degov_dao_directory`; currently fixture-backed and marked `contract_ready`.
- Do not convert provider paths into durable public tool names; provider identity belongs in response provenance.

## Current Gateway Examples
### Subscan API

Subscan API gives your app or agent a reliable way to read chain activity and account state across 70+ chains, including Polkadot, Kusama, Moonbeam, Midnight, and more, so you can ship user-facing crypto features without building core indexing first.

- Access: auth-required gateway calls.
- Product route example: /api/gateway/subscan/polkadot/api/scan/account/tokens
- Product page: https://pubfi.ai/products/subscan-api
- Product docs: https://support.subscan.io/doc-362600
- PubFi docs: https://pubfi.ai/docs/quickstart
- OpenAPI schema: https://pubfi.ai/openapi/subscan-openapi.json

Recommended for product integration. Call the PubFi gateway with your own PubFi API key, and keep usage tracking unified in the dashboard.

```bash
curl --location 'https://pubfi.ai/api/gateway/subscan/polkadot/api/scan/account/tokens' \
  --header 'Authorization: Bearer pf_sk_live_xxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "address": "13YMK2efcJncYrXsaJCvHbaaDt3vfubdn75r4hdVxcggU4n2"
  }'
```

### DeGov API

DeGov API helps your product explain what is happening in a DAO and who is driving outcomes, making governance easier to monitor, analyze, and automate.

- Access: auth-required gateway calls.
- Product route example: /api/gateway/degov/global/v1/daos
- Product page: https://pubfi.ai/products/degov-api
- Product docs: https://agent-api.degov.ai/v1/meta/pricing
- PubFi docs: https://pubfi.ai/docs/degov-api
- OpenAPI schema: https://pubfi.ai/openapi/degov-openapi.json

Use the PubFi gateway route with the fixed `global` network segment for DeGov endpoints. Upstream x-degov-api-token auth stays server-side.

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

## Discovery Gateway Readiness
- Discovery direct gateway examples are gated by the gateway readiness catalog, not by provider existence or category membership.
- Non-routeable Discovery sources use request, procurement, or demand-signal guidance and must not receive inferred PubFi gateway call examples.
- Routeable Discovery sources with examples: Subscan API.
- Non-routeable Discovery sources without direct gateway examples: DotLake API, SubSquid, SubQuery Network, Polkassembly, OnFinality, Alchemy, Infura, QuickNode, Ankr, Chainstack, Blockdaemon, GetBlock, NOWNodes, Pokt Network, Blast API, CoinGecko API, CoinMarketCap API, CryptoCompare, Kaiko, Amberdata, Moralis, Covalent, Bitquery, Dune API, Zerion API, The Graph, DeFiLlama, Helius, Shyft, Hello Moon.

### Subscan API

- Discovery Markdown: https://pubfi.ai/discovery/api/subscan.md
- Raw claim-safe status: gateway_available.
- Effective agent availability: needs_reverification.
- PubFi gateway readiness: gateway_available (PubFi gateway route documented; reverify before live use).
- Guidance: The gateway readiness catalog has a production-callable PubFi route for this source, but the Discovery source profile is not current. Agents should reverify upstream docs, commercial terms, and gateway behavior before live use.
- Direct PubFi gateway examples:
  - Current block time: GET /api/gateway/subscan/polkadot/api/now (network polkadot; upstream /api/now)

```bash
curl --location 'https://pubfi.ai/api/gateway/subscan/polkadot/api/now' \
  --header 'Authorization: Bearer <PubFi API key>'
```

  - Account tokens: POST /api/gateway/subscan/polkadot/api/scan/account/tokens (network polkadot; upstream /api/scan/account/tokens)

```bash
curl --location 'https://pubfi.ai/api/gateway/subscan/polkadot/api/scan/account/tokens' \
  --header 'Authorization: Bearer <PubFi API key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "address": "13YMK2efcJncYrXsaJCvHbaaDt3vfubdn75r4hdVxcggU4n2"
}'
```

  - Account tokens on Acala: POST /api/gateway/subscan/acala/api/scan/account/tokens (network acala; upstream /api/scan/account/tokens)

```bash
curl --location 'https://pubfi.ai/api/gateway/subscan/acala/api/scan/account/tokens' \
  --header 'Authorization: Bearer <PubFi API key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "address": "13YMK2efcJncYrXsaJCvHbaaDt3vfubdn75r4hdVxcggU4n2"
}'
```

## Discovery Export Status
- Public Discovery detail records in the expanded export: 31.
- Public demand-led Discovery records in the expanded export: 3.
- Raw claim-safe status counts: evaluation_comparison_only: 2, gateway_available: 1, integration_requested: 1, public_source_profile: 27.
- Effective agent availability counts: evaluation_comparison_only: 1, integration_requested: 1, needs_reverification: 3, public_source_profile: 26.
- Effective callable/tooling records: 0.
- Discovery detail pages enter the expanded export and Markdown mirror set when the canonical public page is indexable.
- Raw claim-safe statuses are preserved for provenance. Effective agent availability decides whether agents should treat a route as actionable.
- Degraded pages can remain public and machine-readable, but agents must reverify before live use even when the raw status names gateway, x402, or MCP availability.
- [Subscan API Markdown detail](https://pubfi.ai/discovery/api/subscan.md): public. Public Discovery detail for Subscan API. Raw claim-safe status: gateway_available. Effective agent availability: needs_reverification.
- [DotLake API Markdown detail](https://pubfi.ai/discovery/api/dotlake-api.md): public. Public Discovery detail for DotLake API. Raw claim-safe status: public_source_profile. Effective agent availability: public_source_profile.
- [SubSquid Markdown detail](https://pubfi.ai/discovery/api/subsquid.md): public. Public Discovery detail for SubSquid. Raw claim-safe status: public_source_profile. Effective agent availability: public_source_profile.
- [SubQuery Network Markdown detail](https://pubfi.ai/discovery/api/subquery.md): public. Public Discovery detail for SubQuery Network. Raw claim-safe status: public_source_profile. Effective agent availability: public_source_profile.
- [Polkassembly Markdown detail](https://pubfi.ai/discovery/api/polkassembly.md): public. Public Discovery detail for Polkassembly. Raw claim-safe status: public_source_profile. Effective agent availability: public_source_profile.
- [Crypto Data APIs for AI Agents Markdown detail](https://pubfi.ai/discovery/topic/crypto-data-api-for-ai-agents.md): public. Public Discovery demand-led page. Availability status: Request integration.
- [MCP Crypto Data API Source Fit Markdown detail](https://pubfi.ai/discovery/topic/mcp-crypto-data-api.md): public. Public Discovery demand-led page. Availability status: Roadmap signal.
- [x402 Crypto Data API Source Fit Markdown detail](https://pubfi.ai/discovery/topic/x402-crypto-data-api.md): public. Public Discovery demand-led page. Availability status: Request integration.

## Discovery Machine-Native Demand
- Agent data API demand: use https://pubfi.ai/discovery/topic/crypto-data-api-for-ai-agents to compare crypto data sources for `crypto data API for AI agents` and `blockchain data API for AI agents` by coverage, auth model, pricing posture, provenance, freshness evidence, claim-safe status, and current PubFi availability.
- MCP crypto data demand: use https://pubfi.ai/discovery/topic/mcp-crypto-data-api, provider Markdown mirrors, and this guide to compare public MCP or tooling evidence; PubFi does not publish a public MCP server, MCP discovery manifest, or payable MCP tool today.
- x402 crypto data demand: use https://pubfi.ai/discovery/topic/x402-crypto-data-api to compare x402 or machine-payment-readiness signals and request integration interest; PubFi does not publish a payment endpoint, payment requirement, facilitator URL, asset/network allowlist, or supplier payment execution flow today.
- Future demand-led Discovery pages or protocol-specific manifests should only appear when their public route, export, crawler, and claim-safe availability labels are defined from the same source records as the canonical Discovery pages.

## MCP And Machine Payment Status
- PubFi does not publish a public MCP discovery manifest at `/.well-known/mcp.json` today.
- Do not configure a PubFi MCP server from this file; use the OpenAPI schemas and documented gateway routes above.
- This file does not publish a x402 payment endpoint, payment requirement, facilitator URL, asset/network allowlist, or payable MCP tool.
- A future MCP or x402 surface should appear here only after the public product can support it and the manifest or payment route is real.

## Contact
- [Contact PubFi](mailto:hello@pubfi.ai): Contact PubFi for API access, product questions, deployment planning, or custom backend collaboration.