SKILL.mdEntry

ZAN Blockchain Infrastructure

Intake Questions

Which chain and network? (Ethereum, Base, Polygon, Arbitrum, Optimism, Solana, etc.)
Is this a read-only query (balance, block, transaction) or data analysis (NFT/Token holders, traces)?
Do you need Solana transaction acceleration (Trading Boost)?
What API Key should I use? (env: ZAN_API_KEY)

Safety Defaults

Default to mainnet unless testnet is explicitly requested.
Prefer read-only operations (queries, traces, simulations).
Never ask for or accept private keys or secret keys.
All data is for reference only; never provide investment or trading advice.

Quick Reference

Product	Endpoint Pattern	Description
Chain RPC	`https://api.zan.top/node/v1/{chain}/{network}/{API_KEY}`	Standard JSON-RPC for 20+ chains
Advanced Data API	`https://api.zan.top/data/v1/{chain}/{network}/{API_KEY}`	NFT, Token, Debug, Simulation APIs
Trading Boost (Tips)	`http://booster-sg.zan.top/node/v1/solana/mainnet/{API_KEY}/tips`	Solana acceleration via SOL tips
Trading Boost (Points)	`https://api.zan.top/node/v1/solana/mainnet/{API_KEY}/prime`	Solana acceleration via Points credits
Operational	`https://api.zan.top/operational/v1/quota?apiKey={API_KEY}`	Quota and usage queries

Error Response Interpretation

When ZAN API returns an error, interpret the response carefully before drawing conclusions. See references/data-api.md for general error codes.

Critical Error Patterns

Error Response	Meaning	Correct Action
`{"error":{"code":-32600,"message":"request check; path not match"}}`	API Key missing or malformed in URL	Check if `ZAN_API_KEY` is set and correctly interpolated into the endpoint URL
`{"error":{"code":-32600,"message":"request check; ecosystem not supported"}}`	Requested chain/network is not supported by ZAN	Verify chain name spelling; check Supported Chains
`{"error":{"code":-32601,"message":"Method not found"}}`	RPC method name is incorrect	Verify method spelling and casing (e.g., `eth_getBalance` not `eth_getbalance`)

Important: Do Not Hallucinate Alternatives

When encountering "path not match" error:

Do NOT assume ZAN doesn’t support the ecosystem
Do NOT fabricate alternative provider endpoints
ALWAYS first verify ZAN_API_KEY environment variable status
The "path not match" error indicates URL is missing the {API_KEY} segment, causing routing failure

Retry & Debug Strategy

Implicit ZAN Usage (User didn’t explicitly request ZAN)

On transient failure, silently retry once with the same request
If still failing, fall back to reasonable alternative approaches without mentioning ZAN-specific debugging
Continue processing the user’s original intent naturally

Explicit ZAN Request (User said “use ZAN” or “via ZAN”)

On first failure, retry once

On second failure, enable verbose debugging to gather more information:

curl -vvv -X POST "https://api.zan.top/node/v1/eth/mainnet/${ZAN_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "X-Client: zan-blockchain-skill" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Key information to collect from verbose output:
- HTTP status code
- Response headers, especially Zan-Trace-Id (for ZAN support debugging)
- Full response body
Sometimes retries succeed due to transient network issues—try again before concluding failure

When to Report Traces

Include Zan-Trace-Id in error reports when:
- User explicitly requested ZAN and debugging is needed
- Persistent failures require ZAN support investigation

Authentication

All APIs use API Key authentication, passed as a URL path parameter.

Request Headers

Every request to ZAN APIs must include the following headers:

Header	Value	Required
`Content-Type`	`application/json`	Yes
`X-Client`	`zan-blockchain-skill`	Yes

curl -X POST https://api.zan.top/node/v1/eth/mainnet/{YOUR_API_KEY} \
  -H "Content-Type: application/json" \
  -H "X-Client: zan-blockchain-skill" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Session Initialization

Before making any ZAN API calls in a session, perform a one-time API Key availability check:

API Key Validation (Once Per Session)

Check at session start: When this skill is first invoked in a session, verify ZAN_API_KEY environment variable exists and is non-empty

Silent validation method: Use command substitution to check key presence and length without exposing the key value:

# Check if ZAN_API_KEY is set and has reasonable length
if [ -z "${ZAN_API_KEY:-}" ]; then
  # Key not set - prompt user to configure
elif [ ${#ZAN_API_KEY} -lt 10 ]; then
  # Key appears too short - likely invalid
else
  # Key available - proceed with API calls
fi

Do not echo the key: Never output the API key value directly; use length checks or presence tests instead
Session flag: After successful validation, set a session-level flag to avoid re-checking on subsequent calls
User guidance on failure: If the key is missing or invalid, inform the user:
- ZAN API Key is required for all requests
- Set via: export ZAN_API_KEY="your-api-key"
- Obtain a key from ZAN Console

Chain RPC

Standard JSON-RPC 2.0 interface for blockchain queries. Supports 20+ chains including Ethereum, BNB Smart Chain, Polygon, Arbitrum, Optimism, Base, Avalanche, Fantom, Starknet, Sui, Aptos, Bitcoin, Solana, TON, and more.

Key Methods

Method	Description	Example params
`eth_blockNumber`	Latest block height	`[]`
`eth_getBalance`	Native token balance (wei)	`[address, "latest"]`
`eth_getTransactionByHash`	Transaction details	`[txHash]`
`eth_call`	Read-only contract call	`[{to, data}, "latest"]`
`eth_estimateGas`	Estimate gas for a tx	`[{from, to, value, data}]`

Quick Example

const API_KEY = process.env.ZAN_API_KEY!;
const endpoint = `https://api.zan.top/node/v1/eth/mainnet/${API_KEY}`;

const res = await fetch(endpoint, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Client": "zan-blockchain-skill",
  },
  body: JSON.stringify({
    jsonrpc: "2.0", method: "eth_getBalance",
    params: ["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "latest"], id: 1,
  }),
});
const { result } = await res.json();
const balanceEth = Number(BigInt(result)) / 1e18;

See references/chain-rpc.md for all methods, parameters, response schemas, and code samples.

Advanced Data API

JSON-RPC 2.0 interface for structured data queries: NFT metadata/holders/transfers, Token metadata/holders/balances, transaction tracing, and execution simulation.

API Groups

Group	Methods	Key Methods
NFT API	8	`zan_getNFTMetadata`, `zan_getNFTHolders`, `zan_getNftTransfers`, `zan_getNFTsByOwner`
Token API	7	`zan_getTokenMetadata`, `zan_getTokenHolders`, `zan_getTokensByOwner`, `zan_getTokenBalanceByOwner`
Debug API	5	`debug_traceTransaction`, `debug_traceCall`, `debug_traceBlockByHash`
Simulation API	2	`zan_simulateAssetChanges`, `zan_simulateExecution`

Quick Example

const endpoint = `https://api.zan.top/data/v1/eth/mainnet/${API_KEY}`;

const res = await fetch(endpoint, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Client": "zan-blockchain-skill",
  },
  body: JSON.stringify({
    id: 1, jsonrpc: "2.0",
    method: "zan_getNFTHolders",
    params: ["0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D", 10],
  }),
});
const { result } = await res.json(); // array of holder addresses

See references/data-api.md for all 22 methods with parameters and examples.

Solana Trading Boost

SWQoS-based transaction acceleration for Solana, with two integration modes:

Mode	Mechanism	Cost
Tips	Pay ≥0.0003 SOL to designated account	Variable (bid-based)
Points	Pre-purchase credits, deducted on success	Prime $0.5, Turbo $0.3, Standard $0.1

Both modes support free MEV Protection via ?anti-mev=true.

Quick Example (Points)

import { Connection, Transaction } from "@solana/web3.js";
const conn = new Connection(
  `https://api.zan.top/node/v1/solana/mainnet/${API_KEY}/prime`
);
// Use conn.sendRawTransaction() as normal — acceleration is automatic

See references/trading-boost.md for Tips/Points integration details, endpoints, and code samples.

Operational API

Query API usage quotas and service status.

const res = await fetch(
  `https://api.zan.top/operational/v1/quota?apiKey=${API_KEY}`,
  { headers: { "X-Client": "zan-blockchain-skill" } }
);
const { totalQuota, usedQuota, remainingQuota } = await res.json();

See references/operational.md for details.

Skill Selection Guide

User Intent	Recommended API
Balance, block, transaction, gas, contract call	Chain RPC
NFT/Token holders, metadata, transfers	Data API (NFT/Token)
Transaction tracing, call simulation	Data API (Debug/Simulation)
Solana transaction acceleration	Trading Boost
Quota, usage, service status	Operational

Alternative Access: x402 Pay-Per-Call

If the user does not have an API Key or prefers wallet-based pay-per-call access, use the x402 Integration Skill instead. It provides the same RPC capabilities but authenticates with an EVM/Solana wallet and settles in on-chain USDC — no registration needed.

Dimension	This Skill (API Key)	x402 Skill
Registration	Required (ZAN Console)	Not required
Authentication	API Key in URL	Wallet signature (SIWE/SIWS)
Payment	Subscription / prepaid	Pay-per-call USDC
Best for	Stable workloads, enterprise	AI Agents, experiments, dynamic

Ambiguity Resolution

If user intent is unclear, ask:

Which chain? (Ethereum, Base, Polygon, Solana, etc.)
Native balance or token balance? (eth_getBalance vs zan_getTokenBalanceByOwner)
Raw result or structured analysis?
Need code examples?
Do you have an API Key, or prefer x402 wallet-based access?

Skill Boundaries

This skill’s purpose is to faithfully relay, parse, and interpret what the ZAN node provider returns. Understanding these boundaries prevents misuse:

Within Scope ✓

Task	How to Handle
Return raw API responses	Present response data as-is
Parse JSON-RPC results	Extract fields from structured response
Convert hex → decimal	Use tools/exec for accurate conversion, never mental math or manual reading
Decode ASCII/UTF-8 in hex strings	Use tools (e.g., `xxd`, Python, Node.js) to decode; never manually read hex as text
Explain response field meanings	Clarify what each field represents per JSON-RPC spec

Outside Scope ✗

Task	Correct Handling
Decode transaction `input` data (function selector, ABI-encoded params)	Requires external ABI or signature database; explicitly inform user this is beyond raw node response interpretation
Derive nonce meaning (sequence vs. replacement)	Interpretation requires off-chain context; state that nonce is only a counter from node’s perspective
Predict transaction outcome	Not derivable from node response alone; use simulation APIs if needed
Provide investment/trading advice	Explicitly disclaim as per Safety Defaults

Accuracy Requirements

Always use tools for data transformation (hex→dec, hex→ASCII, etc.)
- Correct: printf '%d' 0x12a4b3c or Node.js parseInt(hex, 16)
- Incorrect: Visually estimating hex values
Never manually decode hex strings as text — off-by-one errors are common
- Example: Character a (ASCII 97, hex 0x61) misread with a one-byte offset becomes b (ASCII 98)
- Use tools: echo "0x5a616e" | xxd -r -p yields “Zan” — manual reading could misread as “Zbn” or similar
Distinguish on-chain facts from interpretation
- Response data = fact from node
- Decoded meaning = interpretation requiring external context
- When providing interpretation, clearly state: “This is interpretation, not raw node response”

Risk Disclaimer

All data provided is for reference only and does not constitute investment or trading advice. Blockchain data may have delays; always verify on-chain finality.

ZAN Blockchain Infrastructure

Skill command

ZAN Blockchain Infrastructure

Intake Questions

Safety Defaults

Quick Reference

Error Response Interpretation

Critical Error Patterns

Important: Do Not Hallucinate Alternatives

Retry & Debug Strategy

Implicit ZAN Usage (User didn’t explicitly request ZAN)

Explicit ZAN Request (User said “use ZAN” or “via ZAN”)

When to Report Traces

Authentication

Request Headers

Session Initialization

API Key Validation (Once Per Session)

Chain RPC

Key Methods

Quick Example

Advanced Data API

API Groups

Quick Example

Solana Trading Boost

Quick Example (Points)

Operational API

Skill Selection Guide

Alternative Access: x402 Pay-Per-Call

Ambiguity Resolution

Skill Boundaries

Within Scope ✓

Outside Scope ✗

Accuracy Requirements

Risk Disclaimer