name: qfc-openclaw-skill description: QFC blockchain interaction — wallet, faucet, chain queries, staking, epoch & finality, AI inference homepage: https://github.com/qfc-network/qfc-openclaw-skill license: MIT metadata: {"openclaw":{"requires":{"bins":["node"]}}}

QFC OpenClaw Skill

AI agent skill for full QFC blockchain interaction

Capabilities

Wallet Management

Create Wallet: Generate a new HD wallet with mnemonic, address, and private key
Import Wallet: Restore wallet from private key
Get Balance: Query QFC balance for any address
Send QFC: Transfer QFC tokens to another address
Sign Message: Sign an arbitrary message with the wallet's private key

Wallet Persistence

Save Wallet: Encrypt and persist a wallet to disk (~/.openclaw/qfc-wallets/) using industry-standard keystore format (scrypt KDF, compatible with MetaMask/Geth)
Load Wallet: Decrypt and restore a previously saved wallet by address + password
List Saved Wallets: Show all persisted wallets (address, name, network) without needing a password
Remove Wallet: Delete a saved wallet's keystore file and metadata
Export Keystore JSON: Get the encrypted keystore JSON for a saved wallet (for import into MetaMask or other tools)

Faucet (Testnet Only)

Request Test QFC: Get test tokens on testnet (chain_id=9000)

Chain Queries

Get Block Number: Latest block height
Get Block: Block details by number or 'latest'
Get Transaction: Transaction info by hash
Get Receipt: Transaction receipt with logs

Network Status

Node Info: Version, chain ID, peer count, validator status
Network State: Current network condition (normal/congested)
Chain ID / Block Number / Gas Price: Basic network parameters

Staking & Validators

List Validators: All validators with stake, score, and compute mode
Get Stake: Staked QFC amount for an address
Contribution Score: Validator score (0-10000)
Score Breakdown: Detailed 7-dimension scoring with metrics

Epoch & Finality

Current Epoch: Epoch number, start time, duration
Finalized Block: Latest finalized block number

Smart Contracts (v2.1)

Call Contract: Read contract state (no gas needed) — pass address, ABI, method, and args
Send Transaction: Write to a contract (requires wallet signer, costs gas)
Deploy Contract: Deploy a new contract from ABI + bytecode
Check Contract: Verify if an address has contract code deployed
Get Code: Retrieve raw bytecode at an address
Verify Contract: Submit source code to QFC explorer for verification (compiler version, EVM version, optimizer settings)

ERC-20 Tokens (v2.1)

Deploy Token: Create a new ERC-20 token on QFC — specify name, symbol, and initial supply. All tokens are minted to the deployer. No compiler needed (pre-compiled bytecode). Set mintable: true for a token with mint/burn/owner support. Auto-verifies source code on QFC explorer after deployment.
Mint Tokens: Mint new tokens to any address (mintable tokens only, caller must be owner)
Burn Tokens: Burn tokens from your balance (reduces total supply, mintable tokens only)
Token Info: Get name, symbol, decimals, and total supply of any ERC-20 token
Token Balance: Check token balance for any address
Transfer Tokens: Send ERC-20 tokens to another address (auto-handles decimals)
Approve Spender: Approve a contract/address to spend tokens (supports "max" for unlimited)
Check Allowance: Query how much a spender is approved to use
Token Portfolio (v2.3): View all token holdings for a wallet — native QFC balance plus every ERC-20 token with non-zero balance
Transfer History (v2.3): View token transfer history from the explorer — filter by token and/or address
Batch Transfer Tokens (v2.4): Send tokens to multiple addresses in one operation (sequential transfers)
Batch Send QFC (v2.4): Send native QFC to multiple addresses
Deploy Airdrop Contract (v2.5): Deploy a reusable Airdrop contract — batch transfer any ERC-20 in a single transaction (saves gas vs sequential). Auto-verifies source on explorer.
Smart Airdrop (v2.5): Airdrop tokens via the Airdrop contract — auto-approves, supports variable or fixed amounts per recipient

NFT / ERC-721 (v2.4)

Deploy NFT Collection: Create a new ERC-721 NFT contract with name and symbol
Mint NFT: Mint a new NFT with metadata URI to any address (owner only)
View NFT: Query token URI, owner, and balance for any NFT
Transfer NFT: Transfer an NFT to another address

Token Swap / DEX (v2.5)

Deploy Pool: Create a constant-product AMM pool (x*y=k) for any ERC-20 token pair. 0.3% swap fee. LP tokens track liquidity shares. Auto-verifies source on explorer.
Pool Info: View pool reserves, token details, current price, and total LP supply
Add Liquidity: Deposit both tokens into a pool to earn LP tokens (auto-approves)
Remove Liquidity: Burn LP tokens to withdraw proportional share of both tokens
Swap Tokens: Swap one token for another with slippage protection (default 1%)
Get Quote: Preview expected output amount, price impact, and fee before swapping
LP Balance: Check LP token balance for any address
Deploy WQFC (v3.0): Deploy the Wrapped QFC (ERC-20 wrapper for native QFC)
Wrap/Unwrap QFC (v3.0): Convert native QFC ↔ WQFC for use in DEX pools
Swap QFC for Token (v3.0): Auto-wrap native QFC and swap in one call
Swap Token for QFC (v3.0): Swap token to WQFC and auto-unwrap to native QFC

Token Launchpad (v3.0)

Launch Token: One-command token launch — deploy token + deploy WQFC pool + add initial liquidity. Returns token address, pool address, and LP details.

NFT Marketplace (v3.0)

Deploy Marketplace: Deploy an on-chain NFT marketplace contract with configurable platform fee (default 2%, max 10%). Fee is deducted from sale price and sent to feeRecipient.
List NFT: List an NFT for sale with a price in QFC (auto-approves marketplace)
Buy NFT: Purchase a listed NFT by sending QFC (platform fee auto-deducted, excess auto-refunded)
Cancel Listing: Cancel an active listing (seller only)
View Listings: Get all active listings or filter by NFT collection
Get Listing: View details of a specific listing
Get Fee Info: Query current platform fee (basis points) and fee recipient
Set Fee: Update platform fee and/or recipient (marketplace owner only)

Multi-Call (v3.0)

Deploy Multicall3: Deploy a batch-call contract for aggregating view calls
Batch Calls: Execute multiple contract reads in a single RPC request
Batch Token Balances: Query balanceOf for many tokens at once
Batch Pool Reserves: Query reserves for multiple AMM pools at once

Event Subscriptions (v3.0)

Watch Transfers: Poll for new ERC-20 Transfer events on a token
Watch Swaps: Poll for new Swap events on an AMM pool
Watch NFT Sales: Poll for new Sold events on the marketplace
Watch Blocks: Poll for new blocks with transaction counts

Discord Bot Integration (v2.5)

Command Processor: Framework-agnostic Discord bot command handler — no discord.js dependency
Supported Commands: !help, !faucet, !balance, !portfolio, !tx, !block, !price, !info
Parse + Execute: Parse raw messages into commands, execute them, and return Discord-formatted responses
Custom Prefix: Configurable command prefix (default !)
Example Script: See scripts/discord-bot-example.mjs for discord.js integration pattern

Agent Registry (v3.2)

Register Agent: Register an AI agent on-chain with permissions, daily spending limit, max-per-tx limit, and initial QFC deposit
Fund Agent: Top up an agent's on-chain deposit with additional QFC
Revoke Agent: Deactivate a registered agent on the registry
Get Agent: Query agent info by ID (owner, address, permissions, deposit, daily spend, active status)
List Agents: List all agent IDs owned by an address
Issue Session Key: Authorize a session key address for an agent with a time-limited duration
Rotate Session Key: Atomically revoke an old session key and issue a new one
Revoke Session Key: Immediately deactivate a session key
Get Session Key: Query session key details (expiration, active status)
Validate Session Key: Check if a session key address is currently valid

Safe Execution Mode (v3.3)

Preflight Check: Query on-chain agent state before submitting any transaction
- Verifies agent exists and is active
- Checks required permission is granted
- Validates amount within per-tx limit (maxPerTx)
- Validates amount within remaining daily budget (dailyLimit − spentToday)
- Checks sufficient deposit balance
- Optionally validates session key is active and not expired
Human-Readable Deny Reasons: Returns clear explanations for each failed check
Warnings: Alerts for near-limit conditions (>80% daily budget, >90% deposit used)
Dry-Run Mode: Run all checks without submitting the transaction (dryRun: true)
Safe Fund Agent: safeFundAgent() — preflight + fund in one call
Generic Safe Execute: safeExecute() — preflight + arbitrary callback, blocks if policy denied

Agent Wallet Client (v3.4)

AgentWalletClient: High-level client wrapping QFCAgent + QFCInference for autonomous agent operations
Session-Key Inference: Submit inference tasks using a session key instead of the owner's long-lived private key — the on-chain registry validates the session key's permissions and spending limits
Preflight-Guarded Submission: Automatically runs preflight policy checks before every inference submission (permission, daily budget, deposit balance, session key validity)
Full Agent Lifecycle: register, fund, revoke, status, list — all through a single client
Session Key Management: issue, rotate, revoke, validate session keys
Fee Estimation: Estimate inference cost before submission
Demo Scenarios: Autonomous Trader, Content Generator, AI Oracle — see scripts/demo-*.mjs

AI Inference (v2.1)

List Models: Approved AI models from the on-chain registry (name, version, GPU tier)
Inference Stats: Network-wide statistics (tasks completed, active miners, avg time, FLOPS, pass rate)
Submit Task: Submit a public inference task with model ID, input data, and max fee (requires wallet signature)
Estimate Fee: Get estimated cost for an inference task based on model and input size
Query Task Status: Check if a task is pending, assigned, completed, failed, or expired
Wait for Result: Poll until task reaches a terminal state (configurable timeout)
Decode Result: Parse the JSON envelope + base64 result payload from completed tasks

Security Rules

Never expose private keys or mnemonics in conversation output. Store them securely and reference by wallet address only.
Confirm transactions >100 QFC — Always ask for explicit user confirmation before sending large amounts.
Verify recipient addresses — Validate address format (0x + 40 hex chars) before sending.
Default to testnet — Unless the user explicitly requests mainnet, all operations use testnet.
Rate limit transactions — Maximum 1000 QFC per day by default (configurable).

Setup

Run {baseDir}/scripts/setup.sh before first use. This installs dependencies and compiles TypeScript modules to {baseDir}/dist/.

Configuration

Network Setup

Testnet RPC: https://rpc.testnet.qfc.network (chain ID: 9000)
Mainnet RPC: https://rpc.qfc.network (chain ID: 9001)

Environment Variables

QFC_NETWORK — "testnet" (default) or "mainnet"
QFC_RPC_URL — Override RPC endpoint

Modules

Module	Class	Description
`contract`	`QFCContract`	Read/write/deploy smart contracts
`token`	`QFCToken`	ERC-20 token operations + airdrop contract
`nft`	`QFCNFT`	ERC-721 NFT operations
`swap`	`QFCSwap`	AMM token swap / DEX + WQFC wrapper
`marketplace`	`QFCMarketplace`	NFT marketplace (list/buy/sell)
`multicall`	`QFCMulticall`	Batch contract reads in single RPC
`events`	`QFCEvents`	Event subscriptions via polling
`agent`	`QFCAgent`	AI agent registry — register, fund, revoke, session keys
`agent-wallet`	`AgentWalletClient`	High-level agent wallet — session-key inference, lifecycle, safe execution
`inference`	`QFCInference`	AI inference task submission & results
`provider`	—	Shared provider creation & RPC helper

All modules are compiled to {baseDir}/dist/. | wallet | QFCWallet | Wallet create/import/balance/send/sign/save/load | | keystore | QFCKeystore | Encrypted wallet persistence (scrypt keystore) | | security | SecurityPolicy | Pre-transaction safety checks | | faucet | QFCFaucet | Testnet token requests | | chain | QFCChain | Block, transaction, receipt queries | | network | QFCNetwork | Node info & network status | | staking | QFCStaking | Validator & staking info | | epoch | QFCEpoch | Epoch & finality info | | discord | QFCDiscordBot | Discord bot command processor (no discord.js dependency) |

Usage Examples

Create a wallet, save it, and get test tokens

Create a new QFC wallet on testnet, save it with password "mypass", then request 10 QFC from the faucet

Load a saved wallet

List my saved QFC wallets and load the first one with password "mypass"

Check network status

What's the current QFC testnet status? Show me node info and latest block.

Query validators

List all QFC validators and their contribution scores

Check transaction

Look up transaction 0xabc... on QFC testnet — show me the receipt

ERC-20 Tokens

Create a new token called "My Token" with symbol MTK and 1 million supply on QFC testnet

Deploy an ERC-20 token named "QFC Rewards" (symbol: QREW) with 10 million supply

Create a mintable token called "Game Gold" with symbol GOLD and 0 initial supply

Mint 5000 GOLD tokens to address 0x1234...

Burn 100 of my GOLD tokens

What is the token at 0xabcd...? Show me name, symbol, and total supply.

Check my token balance for 0xabcd... token

Transfer 50 tokens (0xabcd...) to 0x5678...

Token Portfolio & History

Show me all token balances for address 0xfe913E97238B28abac7a55173f5878fD29147210

What tokens does my wallet hold on QFC testnet?

Show transfer history for token 0x603f0c43966f68dfb0737314cde8c4a46a0cc1f9

Show my recent transfers for the XHT token

Batch Operations

Airdrop 100 XHT tokens to these addresses: 0x1111..., 0x2222..., 0x3333...

Send 10 QFC to each of these addresses: 0xaaaa..., 0xbbbb...

Smart Airdrop (single-tx)

Deploy an airdrop contract on QFC testnet

Airdrop 100 XHT to 0x1111..., 200 XHT to 0x2222..., and 50 XHT to 0x3333... using airdrop contract 0xabcd...

Airdrop 500 GOLD tokens equally to these 10 addresses using the airdrop contract

NFTs

Deploy an NFT collection called "QFC Punks" with symbol QPUNK

Mint an NFT to 0x1234... with metadata URI https://api.example.com/metadata/1

Who owns token #0 in NFT contract 0xabcd...?

Get the metadata URI for token #3 in the NFT collection at 0xabcd...

Transfer NFT #2 from my wallet to 0x5678... on contract 0xabcd...

Token Swap / DEX

Create a swap pool for tokens 0xAAA... and 0xBBB... on QFC testnet

Add liquidity: 1000 of token A and 500 of token B to pool 0xPOOL...

Swap 100 of token 0xAAA... for token B on pool 0xPOOL...

Get a quote: how much token B would I get for 50 of token A on pool 0xPOOL...?

Show pool info for 0xPOOL... — reserves, price, and LP supply

Remove all my liquidity from pool 0xPOOL...

WQFC (Wrapped QFC)

Deploy WQFC contract on QFC testnet

Wrap 100 QFC into WQFC using contract 0xWQFC...

Swap 50 native QFC for token 0xAAA... via WQFC pool 0xPOOL...

Token Launchpad

Launch a new token called "Moon Coin" (MOON) with 1M supply, add 100k tokens and 500 QFC as initial liquidity

NFT Marketplace

Deploy an NFT marketplace on QFC testnet with 2% platform fee

Deploy a marketplace with 5% fee sent to 0xFEE...

List NFT #3 from collection 0xNFT... for 10 QFC on marketplace 0xMKT...

Buy listing #0 on marketplace 0xMKT...

Show all active NFT listings on marketplace 0xMKT...

Check the platform fee on marketplace 0xMKT...

Multi-Call

Deploy a Multicall3 contract on QFC testnet

Batch check balances of 5 tokens for my wallet using multicall 0xMC...

Smart Contracts

Is 0x1234...abcd a contract address on QFC testnet?

Read the name() and symbol() of ERC-20 contract 0xabcd...

Call the balanceOf method on contract 0xabcd... for address 0x1234...

Verify the source code for contract 0xabcd... on the QFC explorer

AI Inference

What AI models are available on QFC?

How much does it cost to run a text embedding on QFC?

Submit an inference task using qfc-embed-small with input "Hello world" and max fee 0.1 QFC

Check the status of inference task 0xdef456...

Show me QFC inference network statistics

Agent Registry

Register an AI agent called "my-agent" with Transfer permission, 100 QFC daily limit, 10 QFC max per tx, and 5 QFC deposit

Fund agent "my-agent" with 50 QFC

Issue a session key for agent "my-agent" to address 0x1234... valid for 1 hour

Rotate the session key for agent "my-agent" from 0xOLD... to 0xNEW... with 2 hour validity

Revoke the session key at 0x1234... for agent "my-agent"

Is session key 0x1234... still valid?

Show info for agent "my-agent"

List all agents owned by 0xfe913E97238B28abac7a55173f5878fD29147210

Safe Execution Mode

Check if agent "my-agent" can spend 50 QFC (dry run, don't submit)

Safely fund agent "my-agent" with 20 QFC — check policy first, then submit if allowed

Run preflight check for agent "my-agent" with Transfer permission and 5 QFC amount

Agent Wallet Client

Create an autonomous trader agent: register "trader-1" with InferenceSubmit and Transfer permissions, 100 QFC daily limit, issue a session key, then submit a sentiment analysis inference using only the session key

Set up a content generator agent with InferenceSubmit-only permission and a 7-day session key

Run an AI oracle: register agent, estimate inference fee, run preflight check, then submit a query — all using the session key

Submit an inference task as agent "my-agent" using session key — model qfc-embed-small, input "Hello world"

Discord Bot

Set up a QFC Discord bot using scripts/discord-bot-example.mjs as a template

Integrate QFCDiscordBot into my existing Discord bot to handle !balance and !faucet commands

Error Handling

Error	Meaning	Action
INSUFFICIENT_FUNDS	Not enough QFC	Check balance, fund wallet
INVALID_ADDRESS	Bad recipient format	Verify 0x + 40 hex chars
NETWORK_ERROR	RPC connection failed	Check RPC URL, retry
NONCE_TOO_LOW	Transaction already sent	Wait for confirmation, retry
FAUCET_TESTNET_ONLY	Faucet used on mainnet	Switch to testnet
CALL_EXCEPTION	Contract call reverted	Check method name, args, and ABI
UNPREDICTABLE_GAS	Gas estimation failed	Contract may revert, check args
MODEL_NOT_FOUND	Unknown model ID	List models with getModels()
TASK_EXPIRED	Inference task timed out	Resubmit with higher fee
FEE_TOO_LOW	Max fee below minimum	Use estimateFee() to get base price
AGENT_NOT_FOUND	Unknown agent ID	Check agentId, list agents with listAgents()
SESSION_KEY_EXPIRED	Session key past expiry	Issue or rotate to a new session key
PREFLIGHT_DENIED	Policy check failed	Inspect preflight.reasons[] for details
DAILY_LIMIT_EXCEEDED	Amount exceeds remaining daily budget	Wait for daily reset or increase limit
PER_TX_LIMIT_EXCEEDED	Amount exceeds per-transaction cap	Split into smaller transactions
DEPOSIT_INSUFFICIENT	Agent deposit too low	Fund agent with fundAgent()
PERMISSION_DENIED	Agent lacks required permission	Re-register with correct permissions

Qfc Openclaw Skill

Description