Les agents IA qui cherchent sur le web ont besoin d'un mode de paiement qui fonctionne par programmation. Les stablecoins USDC permettent des micropaiements par requête, sans cartes de crédit ni engagements mensuels. Ce tutoriel construit une enveloppe de paiement autour des appels API de recherche qui suit les dépenses en USDC, fixe des budgets par agent et enregistre chaque transaction. La recherche elle-même utilise Scavio à 0,005 $/requête, et la couche USDC ajoute un suivi transparent des coûts.
Prérequis
- Python 3.9+ installé
- bibliothèque requests installée
- Une clé API Scavio depuis scavio.dev
- Compréhension de base des portefeuilles de stablecoins
Parcours
Étape 1: Construire le tracker de budget USDC
Créez un système de budget qui suit les dépenses des agents en USDC. Chaque agent reçoit une allocation budgétaire et ne peut pas la dépasser.
Python
from dataclasses import dataclass, field
from datetime import datetime
from typing import List, Dict
@dataclass
class Transaction:
agent_id: str
amount_usdc: float
service: str
query: str
timestamp: str = field(default_factory=lambda: datetime.now().isoformat())
class USDCBudget:
def __init__(self):
self.balances: Dict[str, float] = {}
self.transactions: List[Transaction] = []
def fund_agent(self, agent_id: str, amount_usdc: float):
self.balances[agent_id] = self.balances.get(agent_id, 0) + amount_usdc
print(f'Agent {agent_id}: funded ${amount_usdc} USDC (balance: ${self.balances[agent_id]})')
def can_spend(self, agent_id: str, amount: float) -> bool:
return self.balances.get(agent_id, 0) >= amount
def spend(self, agent_id: str, amount: float, service: str, query: str) -> bool:
if not self.can_spend(agent_id, amount):
return False
self.balances[agent_id] -= amount
self.transactions.append(Transaction(agent_id, amount, service, query))
return True
def summary(self, agent_id: str) -> dict:
agent_txns = [t for t in self.transactions if t.agent_id == agent_id]
total_spent = sum(t.amount_usdc for t in agent_txns)
return {'balance': self.balances.get(agent_id, 0),
'total_spent': total_spent, 'transactions': len(agent_txns)}
budget = USDCBudget()
budget.fund_agent('research-agent', 1.00) # $1 USDC budget
budget.fund_agent('lead-gen-agent', 5.00) # $5 USDC budget
print(f'Research agent: ${budget.balances["research-agent"]} USDC')
print(f'Lead gen agent: ${budget.balances["lead-gen-agent"]} USDC')Étape 2: Envelopper les appels de recherche avec des dépenses USDC
Créez une fonction de recherche qui vérifie le budget USDC de l'agent avant d'effectuer des appels API et enregistre chaque transaction.
Python
import requests, os
SCAVIO_KEY = os.environ['SCAVIO_API_KEY']
SEARCH_COST_USDC = 0.005 # $0.005 per query
def budgeted_search(agent_id: str, query: str, budget: USDCBudget) -> dict:
if not budget.can_spend(agent_id, SEARCH_COST_USDC):
remaining = budget.balances.get(agent_id, 0)
return {'error': f'Insufficient USDC balance: ${remaining:.3f} < ${SEARCH_COST_USDC}',
'results': []}
resp = requests.post('https://api.scavio.dev/api/v1/search',
headers={'x-api-key': SCAVIO_KEY, 'Content-Type': 'application/json'},
json={'query': query, 'country_code': 'us', 'num_results': 10})
results = resp.json().get('organic_results', [])
budget.spend(agent_id, SEARCH_COST_USDC, 'scavio_search', query)
return {
'results': [{'title': r['title'], 'link': r['link']}
for r in results],
'cost_usdc': SEARCH_COST_USDC,
'remaining_usdc': budget.balances[agent_id]
}
# Agent makes searches against its budget
result = budgeted_search('research-agent', 'best python frameworks 2026', budget)
print(f'Results: {len(result["results"])}')
print(f'Cost: ${result.get("cost_usdc", 0)} USDC')
print(f'Remaining: ${result.get("remaining_usdc", 0):.3f} USDC')Étape 3: Ajouter des rapports de dépenses et des alertes
Générez des rapports de dépenses par agent et configurez des alertes lorsque les budgets sont faibles.
Python
def spending_report(budget: USDCBudget):
print('Agent Spending Report')
print('=' * 50)
for agent_id, balance in budget.balances.items():
summary = budget.summary(agent_id)
print(f'\nAgent: {agent_id}')
print(f' Balance: ${balance:.3f} USDC')
print(f' Spent: ${summary["total_spent"]:.3f} USDC')
print(f' Transactions: {summary["transactions"]}')
# Alert if low balance
if balance < 0.10:
print(f' WARNING: Low balance! Fund this agent to continue.')
# Queries remaining estimate
queries_left = int(balance / SEARCH_COST_USDC)
print(f' Queries remaining: ~{queries_left}')
# Simulate some agent activity
for i in range(5):
budgeted_search('research-agent', f'query {i}', budget)
spending_report(budget)Exemple Python
Python
import requests, os
SCAVIO_KEY = os.environ['SCAVIO_API_KEY']
balances = {'agent-1': 1.0}
txns = []
def search(agent_id, query, cost=0.005):
if balances.get(agent_id, 0) < cost:
return {'error': 'Insufficient USDC'}
resp = requests.post('https://api.scavio.dev/api/v1/search',
headers={'x-api-key': SCAVIO_KEY, 'Content-Type': 'application/json'},
json={'query': query, 'country_code': 'us', 'num_results': 10})
balances[agent_id] -= cost
txns.append({'agent': agent_id, 'cost': cost, 'query': query})
results = resp.json().get('organic_results', [])
print(f'${cost} USDC | Balance: ${balances[agent_id]:.3f} | Results: {len(results)}')
return results
search('agent-1', 'best CRM tools 2026')
print(f'Total spent: ${sum(t["cost"] for t in txns):.3f} USDC')Exemple JavaScript
JavaScript
const SCAVIO_KEY = process.env.SCAVIO_API_KEY;
const balances = { 'agent-1': 1.0 };
async function search(agentId, query, cost = 0.005) {
if ((balances[agentId] || 0) < cost) return { error: 'Insufficient USDC' };
const resp = await fetch('https://api.scavio.dev/api/v1/search', {
method: 'POST',
headers: { 'x-api-key': SCAVIO_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({ query, country_code: 'us', num_results: 10 })
});
balances[agentId] -= cost;
const results = (await resp.json()).organic_results || [];
console.log(`$${cost} USDC | Balance: $${balances[agentId].toFixed(3)} | Results: ${results.length}`);
return results;
}
search('agent-1', 'best CRM tools 2026');Sortie attendue
JSON
Agent research-agent: funded $1.00 USDC (balance: $1.0)
Agent lead-gen-agent: funded $5.00 USDC (balance: $5.0)
Results: 10
Cost: $0.005 USDC
Remaining: $0.995 USDC
Agent Spending Report
==================================================
Agent: research-agent
Balance: $0.970 USDC
Spent: $0.030 USDC
Transactions: 6
Queries remaining: ~194