By using KYA data, payment endpoints can grant trust-limited access based on an agent’s verified profile and behavior patterns. The protocol also helps prevent unauthorized spending by binding agent wallets to verifiable credentials—a must-have in complex autonomous agent ecosystems.
Unlike typical API keys, Skyfire’s KYA ties identity verification on-chain, allowing smart contracts to enforce agent governance policies directly. This opens up composability with agent payment protocols like the ERC-8004 agent identity standard.
Prerequisites and Setup Overview
Before diving in, make sure you have:
- Node.js 18+ and npm installed
- An EVM-compatible wallet (using either private keys or session keys with spending limits)
- Access to an Ethereum testnet or mainnet RPC endpoint
- Basic understanding of TypeScript or JavaScript SDK consumption
- A compatible Solidity development environment for deploying or interfacing with Skyfire contracts
This tutorial uses the following versions (as of writing):
skyfire-sdk version 0.3.1- OpenZeppelin Contracts 4.9.0 (for reference contracts)
The final working state will demonstrate an agent authenticating via KYA, preparing a wallet with USDC funds, and making micropayments through Skyfire’s KYAPay token on-chain rails.
For related MCP monetization setups, check the mcp-server-monetization guide.
Step 1: Installing Skyfire SDK and Dependencies
We'll use the Skyfire developer library to make integration smoother. Install it via npm:
npm install skyfire-sdk ethers dotenv
Set up your .env variables for private keys and RPC URLs:
PRIVATE_KEY=your_agent_wallet_private_key
RPC_URL=https://rpc.your-testnet.fallback
USDC_ADDRESS=0xYourUSDCaddress
KYAPAY_TOKEN_ADDRESS=0xYourKYAPayTokenAddress
Create a basic connection module (e.g., connection.ts):
import { ethers } from 'ethers';
import dotenv from 'dotenv';
dotenv.config();
export const provider = new ethers.providers.JsonRpcProvider(process.env.RPC_URL);
export const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);
This setup assumes you handle private keys carefully and do not expose them publicly.
Step 2: Configuring Your AI Agent Wallet for On-Chain Payments
The agent wallet acts as the payment source for agent micropayments. In production, you might use session keys or delegated wallets with spending limits to reduce risk. For now, we’ll use the private key directly but keep risks in mind.
To interact with USDC and KYAPay tokens, we'll first connect standard ERC-20 ABIs:
const erc20Abi = [
'function balanceOf(address owner) view returns (uint256)',
'function approve(address spender, uint256 amount) returns (bool)',
'function allowance(address owner, address spender) view returns (uint256)',
'function transfer(address to, uint256 amount) returns (bool)',
];
import {provider, wallet} from './connection';
const usdcContract = new ethers.Contract(process.env.USDC_ADDRESS!, erc20Abi, wallet);
const kyapayContract = new ethers.Contract(process.env.KYAPAY_TOKEN_ADDRESS!, erc20Abi, wallet);
async function printBalances() {
const usdcBal = await usdcContract.balanceOf(wallet.address);
const kyapayBal = await kyapayContract.balanceOf(wallet.address);
console.log(`USDC balance: ${ethers.utils.formatUnits(usdcBal, 6)}`);
console.log(`KYAPay balance: ${ethers.utils.formatUnits(kyapayBal, 18)}`);
}
printBalances();
This lets you verify your agent wallet is funded for upcoming payment calls.
Step 3: Integrating Skyfire KYAPay Token and Payment Rails
KYAPay is Skyfire’s native token designed to facilitate payment settlements between AI agents and service endpoints. It supports low-fee, fast on-chain settlements, leveraging the ERC-20 standard with some agent-focused extensions.
To prepare the wallet for spending, you need to approve the relevant payment contract—the recipient or the payment processor handling the KYAPay tokens.
Example approval flow:
const paymentProcessorAddress = '0xPaymentProcessorAddress';
async function approveKyapay(amount: string) {
const amountWei = ethers.utils.parseUnits(amount, 18);
const currentAllowance = await kyapayContract.allowance(wallet.address, paymentProcessorAddress);
if (currentAllowance.lt(amountWei)) {
const tx = await kyapayContract.approve(paymentProcessorAddress, amountWei);
console.log(`Approving ${amount} KYAPay tokens... TX Hash: ${tx.hash}`);
await tx.wait();
console.log('Approval confirmed');
} else {
console.log('Sufficient allowance already exists');
}
}
approveKyapay('10.0');
After approval, the payment processor contract can deduct agent funds for service usage, e.g., API calls or compute tasks.
Integrating the KYA verification typically requires querying the Skyfire KYA smart contracts or SDK APIs to validate the agent's identity before allowing payment use. This call ensures the agent is known, authorized, and hasn’t triggered any bans or limits.
Step 4: Executing Agent Micropayments Using USDC Stablecoin
If your use case requires stablecoin payments (say USDC) instead of KYAPay, the flow is similar but includes payment routing through Skyfire-enabled rails. The important thing is to check token decimals—USDC uses 6 decimals, unlike the typical 18.
Here’s a minimal example of sending a micropayment in USDC:
async function sendUSDC(recipient: string, amount: string) {
const amountRaw = ethers.utils.parseUnits(amount, 6); // USDC is 6 decimals
const tx = await usdcContract.transfer(recipient, amountRaw);
console.log(`Sending ${amount} USDC to ${recipient}. TX: ${tx.hash}`);
await tx.wait();
console.log('Payment confirmed on-chain');
}
sendUSDC('0xRecipientAddress', '0.5');
Keep in mind USDC may require prior allowance/approval depending on your contract flow, especially if payments happen through middleman contracts.
Micropayment granularity depends on network gas costs and service pricing. In my experience, batching payments or using ERC-20 permit signatures can reduce friction but also require additional contract support.
Security Considerations Around Agent Wallets and Payments
One pitfall I repeatedly warn developers about: never embed private keys directly in production code. Using session keys with spending limits drastically reduces risk if a key leaks.
Also, be cautious with unlimited token approvals—especially for KYAPay or any stablecoin. Set explicit allowance amounts tied to expected payment volumes.
Validate all on-chain KYA data off-chain when possible to avoid delaying critical workflows. If your integration relies on untrusted MCP servers or third-party oracles, always double-check data authenticity to prevent replay or double-spend attacks.
Finally, don’t forget to test extensively on testnets to verify contract events, payment flows, and KYA lookups before any mainnet deployment.
Troubleshooting Common Integration Issues
Skyfire SDK connection errors: Often caused by network RPC outages or misconfigured private keys.
- Verify your
.env credentials.
- Use a reliable RPC provider with health checks.
Allowance not sufficient errors: Happens when token approvals are missing or too low.
- Use contracts’
allowance() to confirm approval settings.
- Remember USDC vs KYAPay decimals and token contract differences.
KYA verification failures: Usually due to agent registration missing or contract version mismatch.
- Cross-check the agent’s on-chain profile.
- Ensure your SDK version matches deployed KYA contracts.
A deeper dive into common FAQs and error fixes is available at the troubleshooting-faq page.
Summary and Next Steps
You should now have a working foundation for integrating Skyfire KYA and payment rails into your AI agent projects. Key takeaways:
- KYA ties agent identity on-chain, enabling trustable autonomous payments.
- Use standard ERC-20 flows to manage KYAPay and USDC balances.
- Handle approvals carefully to maintain secure agent wallet operations.
- Test on relevant testnets before scaling to mainnet.
From here, you might explore building an on-chain agent payment gateway or extending your contracts with session keys and spending limits (see erc-8004-agent-identity for more).
For a broader understanding of alternative agent payment protocols, the agent-payments-protocol-comparisons page lays out trade-offs.
Feel free to jump into the code and customize flows per your project needs. And remember—dealing with autonomous agent payments is still early; keep security top of mind.
Happy building!
Back to Home | x402 Protocol Tutorial | MCP Server Monetization
