Developer docs

PubFi API Quickstart

Send your first authenticated gateway request in a few minutes.

Last updated: 2026-05-20

Overview

Use one PubFi key and one gateway route to verify the integration against Subscan or DeGov.

You'll need

A PubFi API key
Authorization header
Unified gateway route
A test request

Base route

Subscan example

DeGov example

Your key

No active API key found for this session.

Create API key

Create and store your API key

Open the dashboard, go to Manage application keys, and create a key for each environment or agent runtime. Name keys by where they run, such as production, staging, or agent runtime.

PubFi keys use the pf_sk_live_... prefix. Multiple keys under the same account share account-level credits and billing history.

Authenticate requests

Send one PubFi API key with every gateway request. Use either the Bearer header or the dedicated PubFi key header.

HTTPHeaders

Authorization: Bearer pf_sk_live_xxxx
X-PubFi-Api-Key: pf_sk_live_xxxx

Use the gateway route

Keep supplier-specific details behind the gateway adapter. Client code only needs provider, network, and endpoint segments.

RouteBase route

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

Choose a provider

PubFi keeps one gateway contract, but each provider still has its own route convention, example request, and reference docs.

subscan

Subscan API

Open Subscan docs

Use Subscan when you need chain and account data. The network segment maps to the upstream chain host, such as polkadot or acala.

Route pattern/api/gateway/subscan/{network}/{endpoint...}

Gateway auth

Send only your PubFi API key. PubFi injects the upstream X-API-Key server-side.

bashSubscan API request

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

degov

DeGov API

Open DeGov docs

Use DeGov for DAO intelligence endpoints. The network segment is fixed to global because DeGov uses one upstream base URL.

Route pattern/api/gateway/degov/global/{endpoint...}

Gateway auth

Send only your PubFi API key. PubFi injects x-degov-api-token from DEGOV_KEY on the server.

bashDeGov API request

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

Send your first request

Start with a free endpoint. For Subscan, the example below posts an account query. For DeGov, use the provider card above and start with /v1/daos or /v1/meta/pricing.

bashTest request

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

JSONSuccess envelope

{
  "ok": true,
  "meta": {
    "requestId": "...",
    "provider": "subscan",
    "network": "polkadot",
    "endpoint": "/api/scan/account/tokens",
    "method": "POST",
    "timestamp": "2026-05-20T00:00:00.000Z",
    "upstream": {
      "status": 200,
      "latencyMs": 320,
      "rateLimit": {
        "limit": null,
        "remaining": null,
        "reset": null,
        "retryAfter": null
      }
    }
  },
  "data": {
    "upstream": "response payload"
  }
  }

Understand the current API contract

ok: true responses return upstream data inside a PubFi metadata envelope and currently return HTTP 200.

ok: false responses return a normalized error object with a stable code, a human-readable message, and request metadata.

HTTP status	Error code	When it happens	Notes
`200`	`ok: true`	Gateway authenticated the request and the upstream provider returned success.	Response body includes PubFi metadata plus upstream payload.
`400`	`gateway.invalid_route`	The route shape or route segments are invalid.	Use /api/gateway/{provider}/{network}/{endpoint...}.
`401`	`gateway.missing_api_key`	No PubFi API key was sent in the request headers.	Send either Authorization or X-PubFi-Api-Key.
`401`	`gateway.invalid_api_key`	The PubFi API key is invalid, revoked, or does not match an active key.	Check the key value and confirm it still exists in your dashboard.
`402`	`gateway.insufficient_credits`	The account linked to the API key has no credits left.	Recharge at https://pubfi.ai/.
`404`	`gateway.unsupported_provider`	The provider segment is not registered in the PubFi gateway.	Current provider support is limited. Check the provider name.
`502 or upstream status`	`gateway.upstream_error`	The upstream provider returned an error or a provider-specific failure payload.	PubFi includes upstream status, latency, and rate limit metadata when available.
`502`	`gateway.fetch_failed`	PubFi could not reach the upstream provider at all.	This usually indicates a network or upstream availability problem.
`503`	`gateway.billing_unavailable`	PubFi could not verify or update the account credit balance.	This is a PubFi-side billing or balance verification failure.

Credits and request usage

Successful calls appear in dashboard usage history with provider, route, latency, status, and credits used.

New users currently receive 20 trial credits.
Each successful gateway invocation deducts 1 credit.
If your account has no credits left, the gateway returns an error telling you to recharge at https://pubfi.ai/.
The temporary conversion rule is $1 = 100 credits.
These numbers are temporary operating defaults only. Trial credits, per-request credit cost, and USD-to-credit conversion may change later as PubFi adjusts pricing, supplier costs, and product packaging.