Getting Started

Subscan supports two separate onboarding paths:

Free access through PubFi: create a PubFi API key and call an eligible Subscan route through the PubFi Gateway.

Direct paid access through Subscan: purchase or upgrade a plan on the Subscan API Platform, create a new direct
Subscan API key under that plan, and call the network-specific Subscan API host.

Subscan no longer issues new free API keys from the Subscan API Platform, but the direct platform remains the supported
place to purchase, upgrade, renew, and manage paid Subscan plans and to create new direct API keys under those plans.
PubFi credentials and direct Subscan credentials are not interchangeable.

Choose an access path

Requirement	Access path
New free access	Create a PubFi account and use a PubFi API key with an eligible `:free` Subscan route.
Direct Subscan paid access	Purchase a plan on the Subscan Pricing page, then create a new direct API key and manage it on the API Service page.
Upgrade or renew an existing direct plan	Use the plan, subscription, and renewal controls on the Subscan API Platform.
PubFi metered access	Follow the selected PubFi route's current billing policy.

Free access through PubFi

This section uses the PubFi production Dashboard and API base URL:

Dashboard: pubfi.ai/dashboard

API base URL: https://api.pubfi.ai

The live Registry and Runtime OpenAPI are the authority for the routes and limits that are available at any given time.

Open the PubFi sign-in page. Use the email or Google sign-in flow to create or access your
PubFi account. After authentication, open the PubFi Dashboard.

2. Create a PubFi API key

In the Dashboard, find the API keys section.

Select Create key.

Enter a descriptive name, such as subscan-local-dev, and submit the form.

Copy the complete secret immediately and store it in a secret manager.

The complete secret is displayed only once. Later, the Dashboard shows a shortened preview rather than the full key.
API-key management requires an authenticated Dashboard session with Owner or Admin membership.

If the key is lost, revoke it from the Dashboard and create a replacement. Never put a real key in source code,
documentation, screenshots, shell history, logs, or a public issue.

3. Load the PubFi key securely

For a short local test, load the key into an environment variable. Replace the placeholder locally; never commit the
resulting value:

4. Verify the key and account binding

The following private, read-only request confirms that the key is valid and shows the billing account bound to it. It
does not create billing state:

The response has this shape; values are account-specific:

{
  "principal_id": "<stable execution principal>",
  "billing_account_id": "<billing account for this key>",
  "actor_subject_id": null
}

PubFi uses the Authorization: Bearer ... header for API-key access. The direct Subscan X-API-Key header is not a
substitute for a PubFi API key.

5. Find a current Subscan route

Before calling an endpoint, inspect the current public contracts:

Use the response to find a capability whose provider_key is subscan and whose readiness status is ready. Check
the exact HTTP method, path, request policy, and billing mode before making the request.

Do not infer execution from the Subscan Discovery page, an old example, or a saved route. Discovery is useful for
source evaluation; the live Registry and Runtime OpenAPI decide whether a route can run. See
PubFi API Key and Runtime for the current runtime contract
instead of relying on a screenshot that can become outdated.

6. Call Subscan through the PubFi Gateway

Use the exact gateway path published by the current Runtime OpenAPI. Do not construct a path by inserting the direct
Subscan network name unless that complete path is present in the runtime contract. The currently published metadata
route is:

https://api.pubfi.ai/v1/gateway/subscan/api/scan/metadata

For example, the current Runtime OpenAPI exposes a ready metadata route with a free variant. Verify that it is still
present before using it:

The literal :free suffix selects the advertised free variant. Square brackets are documentation notation only: never
send [:free] as part of a URL. Append :free only when the matching capability advertises free_rate_limit or the
matching OpenAPI operation contains x-pubfi-free-variant. A free route still requires the normal PubFi Bearer key; it
is not anonymous and it is not an x402 request.

For a route that does not advertise a free variant, use the exact path and method from the current contract and follow
its billing policy. Remove :free only when the normal route is ready and the account has the required allocation or
Credits.

Free and billed URLs

For the currently published metadata operation, use one of these complete URLs:

Free variant:
https://api.pubfi.ai/v1/gateway/subscan/api/scan/metadata:free

Billed variant:
https://api.pubfi.ai/v1/gateway/subscan/api/scan/metadata

Do not copy [:free] into a request URL. The live Registry remains authoritative for whether either exact route,
method, request policy, and billing mode is currently available.

Free-route limits

Free-route limits are controlled by PubFi and may be scoped to a provider or route. Read the current
free_rate_limit object instead of carrying forward the old Subscan free-plan limit. A free request does not consume
Credits, but it can still be rejected by the account-level request window, concurrency limit, or quota. On 429,
honor Retry-After when it is present and inspect the response code before retrying.

7. Manage and rotate PubFi keys

Use the Edit and Revoke actions in the Dashboard to manage a key. Revocation is irreversible for that key. If a
key may have been exposed, revoke it immediately, create a replacement, update the secret store, and restart clients
that use the old value.

PubFi troubleshooting

Status	Meaning in the PubFi flow	Next step
`401`	The PubFi key is missing or invalid.	Check the Bearer header and secret.
`402`	The selected route requires a billing or admission action.	Inspect the current billing mode and account allocation.
`403`	The account is not authorized for the selected route.	Recheck route readiness and account membership.
`404`	No active Registry route matches the method and path.	Fetch the current Registry and use an exact ready path.
`429`	A free-route, concurrency, or other rate limit was reached.	Honor `Retry-After` and the current limit/quota policy.
`503`/`504`	Registry, credential, health, or upstream availability/timeout issue.	Retry with backoff after checking the current runtime status.

Direct paid access through Subscan

Use this path when you need to purchase a direct Subscan plan, increase the quota of an existing direct plan, or keep
calling network-specific *.api.subscan.io hosts with a direct Subscan API key.

Open the Subscan API Platform, sign in, or create an account and complete email
verification when required.

2. Purchase or upgrade a paid plan

Review the current plans on the Subscan Pricing page. Select the plan that matches
your request quota, API-key count, page-size, history, support, and SLA requirements. The direct Developer, Advanced,
Professional, and Enterprise plan paths remain available independently of PubFi.

The Pricing page currently lists Fiat (USD) and Crypto (DOT) payment options and an annual-payment discount. Treat the
live Pricing and checkout pages as authoritative because plan names, quotas, prices, payment options, and discounts may
change.

Existing customers can use the platform's upgrade controls to move to an eligible higher plan.

Enterprise customers should use the contact option shown on the Pricing page for custom requirements.

3. Create and manage a direct Subscan API key

After the paid plan is active, open the API Service page to create a new direct
API key under that plan and review its plan and status.

Store the complete secret in a secret manager. If a key is no longer needed or may have been exposed, revoke it from
the API Service page. Revocation is irreversible for that key.

4. Call the direct Subscan API

Direct Subscan API requests use the network-specific host and the X-API-Key or x-api-key header:

The direct key's quota and endpoint access follow its active Subscan plan. Do not use a PubFi Bearer key on a direct
Subscan API host.

5. Manage subscription and renewal

Use the Subscan API Platform to manage the paid plan's subscription and renewal. The controls available to an account
depend on its current plan and payment method; use the live platform and checkout terms as the authority.

Tutorial

Getting Started

Choose an access path

Free access through PubFi

2. Create a PubFi API key

3. Load the PubFi key securely

4. Verify the key and account binding

5. Find a current Subscan route

6. Call Subscan through the PubFi Gateway

Free and billed URLs

Free-route limits

7. Manage and rotate PubFi keys

PubFi troubleshooting

Direct paid access through Subscan

2. Purchase or upgrade a paid plan

3. Create and manage a direct Subscan API key

4. Call the direct Subscan API

5. Manage subscription and renewal

Further reading

Tutorial

Getting Started#

Choose an access path#

Free access through PubFi#

1. Sign in to PubFi#

2. Create a PubFi API key#

3. Load the PubFi key securely#

4. Verify the key and account binding#

5. Find a current Subscan route#

6. Call Subscan through the PubFi Gateway#

Free and billed URLs#

Free-route limits#

7. Manage and rotate PubFi keys#

PubFi troubleshooting#

Direct paid access through Subscan#

1. Sign in to the Subscan API Platform#

2. Purchase or upgrade a paid plan#

3. Create and manage a direct Subscan API key#

4. Call the direct Subscan API#

5. Manage subscription and renewal#

Further reading#

Getting Started

Choose an access path

Free access through PubFi

1. Sign in to PubFi

2. Create a PubFi API key

3. Load the PubFi key securely

4. Verify the key and account binding

5. Find a current Subscan route

6. Call Subscan through the PubFi Gateway

Free and billed URLs

Free-route limits

7. Manage and rotate PubFi keys

PubFi troubleshooting

Direct paid access through Subscan

1. Sign in to the Subscan API Platform

2. Purchase or upgrade a paid plan

3. Create and manage a direct Subscan API key

4. Call the direct Subscan API

5. Manage subscription and renewal

Further reading