OpenParable
Skip to content
← Back to skills

Resolve API URL

Apps & Automation
resolve-api-url

Resolve API URL is an Agent Skill for apps & automation published in the blockscout/frontend repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Resolve the real request URL of an API resource on a live Blockscout instance (`service:name` + instance → full URL). Use whenever a request must be made to, or a sample response fetched from, a deployed instance's API.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/blockscout/frontend/blob/HEAD/.agents/skills/resolve-api-url/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/resolve-api-url, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Resolve a resource's real request URL

A request URL is assembled as <endpoint><basePath><resource.path> (+ compiled path params,

  • query string): the path template lives in the repo, while endpoint / basePath come from the target instance's runtime config. So resolution means reading the repo to learn which env vars apply, then reading the instance's config to get their values. Background facts: How a request URL is assembled in src/api/CONTEXT.md.

Rule of thumb: never guess. Don't guess hosts, and don't transcribe src/api/config.ts logic from memory — read the files each time (they change).

Step 0 — Inputs

The service:name resource key and the target instance (a tools/dev-server/registry.json alias or a full URL). Ask if either is missing.

Step 1 — Repo → path template

Find the resource in its service registry file under src/api/resources/services/** (see src/api/resources/index.ts); the entry gives the path template and its :param placeholders:

// src/api/resources/services/core/token.ts
token: { path: '/api/v2/tokens/:hash', pathParams: [ 'hash' ] }

The service: prefix (core:, contractInfo:, stats:, …) selects which service config applies in the next step (getResourceParams in src/api/utils/get-resource-params.ts resolves it).

Step 2 — Repo → which env vars build the URL

In src/api/config.ts, find the block for the service and read which env vars feed the URL-relevant fields:

  • endpoint — the origin. Sometimes a single host var; sometimes assembled from a protocol/host/port trio. Read the block to see which.
  • basePath — an optional path prefix prepended before resource.path. Present on some services, absent on others. Don't drop it when present.
  • instanceId — fills an :instanceId path param on services that have one. Note the fallback chains expressed in the file (e.g. a service-specific id var falling back to NEXT_PUBLIC_NETWORK_ID).

Collect the exact NEXT_PUBLIC_* names the block references for these fields.

Step 3 — Instance → host + real values

Host — map the instance alias to its base URL via tools/dev-server/registry.json. Use it rather than guessing: many instances don't follow the <name>.blockscout.com pattern (e.g. explorer.immutable.com, www.shibariumscan.io, zetascan.com). It lists ~30 common instances, not all of them — if yours is absent, ask for the URL; don't assume the hostname.

Values — fetch GET <host>/node-api/config and look up the env names from Step 2 in its envs object. This is the canonical, deterministic source — always re-fetch it; never reuse values remembered from another instance or an earlier session.

Step 4 — Assemble

Concatenate <endpoint><basePath><resource.path>, fill the :param placeholders, append the query string. Always use this direct URL — never the /node-api/proxy form: that rewrite exists only as a browser-CORS workaround in dev/review environments, and a Node/server-side request doesn't need it. Sanity check when feasible: a GET should return a 2xx with valid JSON — on a 404, the most common miss is a dropped basePath.