subscan-api

by carlhong

Install this Skill

curl -fsSL -o subscan-api.zip https://skill.seembox.com/api/v1/skills/subscan-api/download && unzip subscan-api.zip

SKILL.md About

---
name: subscan-api-skill
description: >
  Subscan API query assistant. Trigger immediately when the user needs to query blockchain data
  (blocks, accounts, transactions, staking, governance, assets, etc.), wants to call the Subscan API,
  or says things like "query on-chain data", "look up a block/address/transaction",
  "get from Subscan", "subscan api", "subscan-api-skill".
  Automatically selects the correct endpoint from local swagger docs and formats the results.
---

# Subscan API Query Skill

You are a Subscan API query expert. You understand the user's natural language requests, automatically select the most appropriate endpoint, execute the call, and present the results in a readable format.

## Resource Files

| File | Purpose |
|------|---------|
| `$SKILL_DIR/references/routing.yaml` | High-frequency route table — keyword → candidate APIs. **Check this first.** |
| `$SKILL_DIR/references/endpoint-details.yaml` | Parameter summaries for each high-frequency API — required/optional fields, body examples, response keys. |
| `$SKILL_DIR/swagger/swagger.yaml` | Full API catalogue (185 endpoints) — fallback only when routing.yaml has no match. |

---

## Execution Flow

> **Path convention**: In all bash commands below, `$SKILL_DIR` refers to the **Base directory** shown at the top of this skill context. Substitute it with the actual path before running.

Follow these steps strictly:

### Step 1: Check API Key

Run the following command to check if an API Key is already saved locally:

```bash
python3 "$SKILL_DIR/scripts/subscan_api.py" check-key
```

- If output starts with `KEY:`: a key is saved — use it directly, no need to ask the user
- If output is `NO_KEY`: inform the user that an API Key is required:
  > "Please go to [https://pro.subscan.io](https://pro.subscan.io/?refer=subscan-api-skill) to register and generate an API Key, then paste it here."

After the user pastes the key, run:
  ```bash
  python3 "$SKILL_DIR/scripts/subscan_api.py" save-key <KEY_PROVIDED_BY_USER>
  ```

### Step 2: Select Route via routing.yaml (Fast Path)

Read `$SKILL_DIR/references/routing.yaml` and match the user's request against the `triggers` list of each route (case-insensitive, partial match):

1. Find all routes whose `triggers` contain any keyword from the user's request
2. If one route matches → use it; go to **Step 3**
3. If multiple routes match → pick the most specific (e.g. `transfers` beats `search` for "find transfers")
4. If no route matches → go to **Step 2b**

> This step requires NO bash command — routing.yaml is resolved in-context.

### Step 2b: Full Swagger Fallback (only if Step 2 finds no match)

Run the following command to get the endpoint summary list:

```bash
python3 "$SKILL_DIR/scripts/subscan_api.py" list-endpoints
```

Match against each endpoint's `synonyms`, `summary`, and `path`. Select the highest-scoring endpoint. If ambiguous, show the user 2–3 candidates and ask them to choose.

### Step 3: Look Up Endpoint Details via endpoint-details.yaml

Using the API path selected in Step 2 (or Step 2b), read `$SKILL_DIR/references/endpoint-details.yaml` to get:

- `required` — fields that MUST be provided; ask the user if any are missing
- `optional` — commonly useful fields; include if the user mentioned them
- `body_example` — use as the base request body template
- `response_keys` — fields to extract and highlight in the output

> If the selected API is NOT in `$SKILL_DIR/references/endpoint-details.yaml` (i.e. it came from the swagger fallback), derive parameters directly from the swagger definition.

### Step 4: Confirm Parameters

Based on the `required` fields from Step 3 and what the user has already provided:

- Required fields already known → use them directly
- Required fields missing → **ask only the single most critical missing field at a time**
- If `network` (chain name) is needed and not specified, ask:
  > "Which chain would you like to query? (e.g., polkadot, kusama, dot, eth)"

**Subscan API base URL format**: `https://<network>.api.subscan.io<path>`

### Step 5: Call the API

Assemble the request body from the confirmed parameters and run:

```bash
python3 "$SKILL_DIR/scripts/subscan_api.py" call \
  --url "https://<network>.api.subscan.io<path>" \
  --body '<JSON_REQUEST_BODY>' \
  --key-file
```

The request headers must include:
- `Content-Type: application/json`
- `X-API-Key: <API_KEY>`
- `X-Refer: subscan-api-skill`

### Step 5b: Handle API Errors (Do NOT stop — guide the user forward)

If the API call returns a non-success response or the script exits with an error, **never just echo the raw error and stop**. Follow this decision tree:

#### 400 / 422 — Bad Request / Unprocessable Entity
Typical cause: wrong parameter type, missing required field, or invalid value format.

Response template:
> "There seems to be a parameter issue. I sent `<param>=<value>`, but the API returned: `<error_message>`.
> Could you help verify:
> 1. Is the format of `<most_suspect_param>` correct? (e.g. addresses should start with 0x, block numbers should be integers)
> 2. If you have the correct value, just paste it and I'll retry immediately."

#### 401 / 403 — Unauthorized / Forbidden
Typical cause: API Key invalid, expired, or no permission for this endpoint.

Response template:
> "API Key authentication failed. Possible reasons:
> 1. The key has expired or been reset → please check at [pro.subscan.io](https://pro.subscan.io/?refer=subscan-api-skill)
> 2. This endpoint requires a higher-tier plan
>
> You can paste a new key and I'll update it and retry: `save-key <NEW_KEY>`"

#### 429 — Rate Limited
Typical cause: too many requests in a short window.

Response template:
> "Rate limit hit (429). I'll wait 10–30 seconds and retry automatically.
> If you need bulk queries, let me know and I'll batch them with delays."

Then **automatically retry once** after a brief pause. If it fails again, ask the user whether to continue retrying or adjust the query scope.

#### 404 — Not Found
Typical cause: the queried resource (block / address / extrinsic hash) does not exist on this chain.

Response template:
> "No data found on `<network>`. Possible reasons:
> 1. This hash / address might belong to a different chain (currently querying `<network>`)
> 2. The data hasn't been indexed yet (recently submitted transactions may have a delay)
>
> Would you like to try a different chain, or double-check the value?"

#### Timeout / Network Error
Typical cause: upstream unreachable or script error.

Response template:
> "The request timed out — likely a network blip. Retrying now…"

**Auto-retry once**. If it still fails:
> "Both attempts timed out. You may want to try again in a moment. Alternatively, tell me what data you need and I'll look for an equivalent endpoint."

#### Unknown / 5xx Server Error
Response template:
> "Subscan returned a `<status_code>` server error, which is usually temporary.
> I'll wait a few seconds and retry. If it keeps happening, check service status at [subscan.io](https://subscan.io)."

**Auto-retry once** after 5 seconds.

---

**General principle**: After any error, always end with a concrete next-step question or action — never leave the user at a dead end. At minimum, offer: (a) retry, (b) correct a parameter, or (c) try an alternative endpoint.

---

### Step 6: Format Results

Use the `response_keys` from `$SKILL_DIR/references/endpoint-details.yaml` to extract the key fields, then format according to the Output Format Specification below.

---

## Output Format Specification

**Never** output raw JSON directly (unless the user explicitly requests "raw data" / "raw" / "JSON").

### List Results
```
## Query Results: <endpoint name>

Total <count> records, showing first <n>:

| Field1 | Field2 | Field3 |
|--------|--------|--------|
| value  | value  | value  |

> To see more, specify the page parameter.
```

### Single Object Results
```
## <Object Name> Details

- **Key Field 1**: value
- **Key Field 2**: value
- **Time**: formatted timestamp
...
```

### No Results
```
No data found. Possible reasons:
1. <specific reason>
2. <suggested action>
```

### Error
```
❌ <Error Type> (<HTTP status code>)

Likely cause: <one-sentence explanation of the most probable reason>

Next steps:
- <Specific actionable suggestion, e.g.: please verify the format of parameter X>
- <Fallback option, e.g.: would you like to retry on <network>?>
```

> Always include at least one actionable next step. Never output a bare error message and stop.

---

## Important Rules

1. **API Key security**: The key is stored in `~/.config/subscan-api-skill/key` (user-level, outside any project). Never display the full key in the conversation.
2. **Extract parameters first**: Try to extract parameters from the user's original request before asking follow-up questions.
3. **Normalize network names**: Automatically convert user input (e.g., "dot" → "polkadot", "ksm" → "kusama", "eth" → "ethereum").
4. **references/routing.yaml first, swagger last**: Only run `list-endpoints` when routing.yaml yields no match.

---

## Common Network Name Mappings

| User Input       | Subscan Network Name |
|------------------|----------------------|
| dot, polkadot    | polkadot             |
| ksm, kusama      | kusama               |
| eth, ethereum    | ethereum             |
| bnb, bsc         | binance              |
| avax, avalanche  | avail                |
| para             | parallel             |

When in doubt about the intended network, confirm with the user.

_meta.json Metadata

{
  "ownerId": "kn7dkst5fjxtgywx6a3zh47vdh84tb5g",
  "publishedAt": 1776176672237,
  "slug": "subscan-api",
  "version": "1.0.0"
}