📘 Manual Oficial de Referencia: iAgent-Pay (v8.5.0)

Bienvenido a iAgent-Pay, la infraestructura de pago más avanzada para Agentes de Inteligencia Artificial. Este manual técnico está diseñado para enseñarte a desbloquear el 100% de las capacidades de tus agentes, permitiéndoles operar, cobrar e invertir de forma autónoma a escala global.

🌎 1. Soporte Global y Arquitectura Multi-Cadena

iAgent-Pay no es una simple API local; es una pasarela global financiera. Nuestro motor de enrutamiento le permite a tu agente mover dinero a través de todo el ecosistema Web3 y financiero mundial.

Ethereum (ETH): Alta liquidez, máxima seguridad.
Base (BASE): La capa 2 de Coinbase, ideal para comisiones bajas.
Solana (SOL): Velocidad extrema (miles de transacciones por segundo).

El agente es "Agnóstico a la moneda". Puedes elegir la moneda predeterminada. Las divisas integradas incluyen: USDC, USDT, EURC (Euro), CNHC (Yuan), GYEN (Yen), MXNT (Peso).

from iagent_pay import AgentPay

# Agente especialista en el mercado asiático
agente = AgentPay(chain_name="BASE", default_stablecoin="CNHC")

⚡ 2. Características Principales

A. Pagos Autónomos (x402)

tx_hash = agente.pay_token(
    recipient_address="0xProveedor...", 
    amount=5.0
)
print(f"Pago completado: {tx_hash}")

B. Generación de Facturas

Si tu IA realiza un trabajo para un cliente (humano o máquina), puede generar una "Factura Inteligente".

factura_id = agente.invoices.create_invoice(
    amount=25.0, 
    customer_address="0xCliente...", 
    description="Auditoría de código"
)

🏢 4. Consolidación Corporativa (Enterprise Tier)

iAgent-Pay ha sido escalado para manejar operaciones globales ininterrumpidas (24/7) y millones de transacciones simultáneas con las siguientes tecnologías:

⚡ Rendimiento de 54,000+ TPS: Usando PostgreSQL y Connection Pooling avanzado, el sistema procesa oleadas masivas de peticiones sin agotar la memoria del servidor.
💰 iAgent-Yield (Rendimiento Automático): ¡Tus fondos inactivos se invierten solos! A través de nuestra integración nativa con Aave v3, el presupuesto inactivo del bot y las comisiones de tesorería generan automáticamente un ~5% APY.
🔐 Disaster Recovery (AES-256): El sistema realiza copias de seguridad encriptadas en frío todos los días para proteger la contabilidad ante catástrofes de red.
🌍 Portal No-Code Multi-Idiomas: 10 idiomas disponibles en una interfaz visual para que tus clientes establezcan límites financieros sin tocar código.
📲 Alertas Externas (Telegram/Discord): El SafetyKernel envía notificaciones push directas a tu móvil ante transacciones sospechosas o ataques DDoS.

🛡️ 5. Safety Kernel (Núcleo de Seguridad)

Darle libertad financiera a un software requiere límites duros. Verifica cada transacción antes de tocar la red.

Límites Diarios: Evita que un agente defectuoso vacíe tu cuenta.
Identidad Inteligente (ERC-8004): Los agentes tienen una "Identidad Soberana" en la blockchain, inmune a robos de llaves privadas.

# Limitar a un máximo de $15 dólares por día
agente = AgentPay(daily_limit=15.0)

# Acuñar Identidad
identidad = agente.identity.mint_soulbound_id("Bot", "0xOwner")

📈 4. Tesorería Autónoma (DeFi)

Deposita automáticamente los ahorros excedentes en protocolos mundiales como Aave v3, generando intereses mientras duermes.

# Mantener $50 en efectivo, invertir el resto
agente.yield_manager.auto_invest(buffer_usd=50.0)

🏦 5. Puente Bancario Fiat (Fiat Bridge)

¿El cliente no tiene cripto? No hay problema. iAgent-Pay conecta directamente con Stripe para depositar dinero en cuentas bancarias tradicionales o cobrar con tarjeta de crédito.

Stripe Transfer: Paga a cualquier persona con cuenta bancaria.
ACH (EE.UU.): Transferencias bancarias directas de bajo costo.
Smart Router: Elige automáticamente la ruta más barata (cripto vs banco).
Link de Pago: El agente genera un enlace para que humanos paguen sin cripto.

from iagent_pay.fiat_bridge import FiatBridge

bridge = FiatBridge()

# Pagar a un programador freelancer por su banco
bridge.send_stripe(amount_usd=150.0, stripe_account_id="acct_1M2...", description="Pago quincenal")

# El agente crea un link para que el cliente pague con tarjeta
link = bridge.create_payment_link(amount_usd=9.99, description="Acceso Premium API")
print(link["url"])  # → https://buy.stripe.com/...

# Router inteligente: decide solo si usar USDC o Stripe
bridge.smart_send(amount_usd=25.0, recipient="cliente@empresa.com")

🌉 6. Enrutamiento Cross-Chain (Motor AP2)

El agente puede tener su dinero en una red (ej. Ethereum) y pagar en otra (ej. Polygon). El Motor AP2 evalúa todos los puentes disponibles y selecciona automáticamente el más barato y rápido.

from iagent_pay.cross_chain import CrossChainRouter

router = CrossChainRouter()

# Mover $100 USDC de Base → Polygon automáticamente
tx = router.bridge_assets(
    source_chain="BASE",
    target_chain="POLYGON",
    amount=100.0,
    token="USDC"
)
print(f"Bridge completado: {tx}")

🤖 7. Gestión de Flotas (Sub-Agentes)

Para equipos de múltiples agentes. Un Agente Maestro puede crear y controlar "sub-agentes" especializados, cada uno con su propio presupuesto, límites y historial de transacciones aislado.

from iagent_pay.sub_agents import SubAgentManager

# Agente Maestro con presupuesto total de $500
manager = SubAgentManager(master_budget_usd=500.0)

# Crear sub-agentes especializados
investigador = manager.create("investigador", daily_limit_usd=20.0)
redactor     = manager.create("redactor",     daily_limit_usd=10.0)

# El sub-agente verifica seguridad antes de gastar
investigador.kernel.check(amount=5.0, recipient="0xDataAPI...")
investigador.spend(5.0, "USDC", "Compra de datos de mercado")

# Pausar un agente en emergencias
manager.pause("investigador")
print(manager.get_status())

🌐 8. Diccionario Global Completo (Todas las Redes)

El sistema tiene registro oficial de las siguientes redes y monedas. Puedes usar cualquier combinación al inicializar tu agente:

Red	Monedas Soportadas	Caso de Uso
Ethereum (ETH)	USDC, USDT, DAI, EURC, CNHC (Yuan), GYEN (Yen), XSGD, MXNT	Alta liquidez, seguridad máxima
Base (BASE)	USDC, USDT, DAI, EURC, WETH	Comisiones mínimas, Coinbase
Polygon (MATIC)	USDC, USDT, DAI, WETH	Micropagos rápidos
Arbitrum (ARB)	USDC, USDT, DAI, WETH	Alta velocidad, bajo costo
BNB (Binance)	USDC, USDT, BUSD, DAI	Ecosistema Binance
Solana (SOL)	USDC nativo, SOL	Velocidad extrema (4000+ TPS)

# Ejemplo: Agente especializado en mercado latinoamericano
agente = AgentPay(chain_name="BNB", default_stablecoin="USDT")

# Ejemplo: Agente para pagos europeos
agente_eu = AgentPay(chain_name="ETH", default_stablecoin="EURC")

# Ejemplo: Agente para Asia con Yuan chino
agente_asia = AgentPay(chain_name="ETH", default_stablecoin="CNHC")

⚙️ 9. Safety Kernel Avanzado (Configuración Completa)

Más allá de los límites diarios, el Safety Kernel tiene 4 capas de protección configurables de forma independiente:

from iagent_pay.safety_kernel import SafetyKernel, SafetyConfig

kernel = SafetyKernel(SafetyConfig(
    daily_limit_usd=100.0,       # Máximo diario
    weekly_limit_usd=500.0,      # Máximo semanal
    session_limit_usd=20.0,      # Máximo por sesión
    max_tx_usd=10.0,             # Máximo por transacción individual
    max_tx_per_minute=5,         # Máximo velocidad: 5 tx por minuto
    max_tx_per_hour=50,          # Máximo velocidad: 50 tx por hora
    human_approval_threshold_usd=50.0,  # Sobre $50 pide aprobación humana
    allowed_recipients=["0xAlice...", "0xBob..."],  # Lista blanca de direcciones
    enable_whitelist=True,       # Activar lista blanca
))

# Verificar ANTES de cada pago (bloquea si viola alguna regla)
kernel.check(amount=5.0, recipient="0xAlice...", currency="USDC")

# Consultar el estado del presupuesto en tiempo real
print(kernel.get_status())

# Obtener el historial de auditoría forense completo
auditoria = kernel.get_audit_log()

💳 10. Gestor de Billeteras (WalletManager)

El módulo que crea, importa y protege las llaves criptográficas de tu agente. Soporta Keystores cifrados con contraseña (AES-128) y archivos .env para desarrollo.

from iagent_pay.wallet_manager import WalletManager

wm = WalletManager()

# Crea o carga la billetera automáticamente
# Si existe un Keystore cifrado, se usa esa (más segura)
wallet = wm.get_or_create_wallet(password="MiContraseñaSegura123")
print(f"Dirección del Agente: {wallet.address}")

# Importar billetera desde clave privada existente
wallet_importado = wm.load_wallet("0xTuLlavePrivadaAqui...")

# Crear billetera temporal (efímera, para pruebas)
wallet_nuevo = wm.create_wallet()

🔤 11. Resolver de Nombres Sociales (Social Resolver)

En lugar de pegar direcciones como 0x7F5E..., tu agente puede resolver nombres humanos como dominios ENS (Ethereum) o nombres de Solana.

from iagent_pay.social_resolver import SocialResolver

resolver = SocialResolver()

# Pagar usando un nombre ENS (.eth)
direccion = resolver.resolve("vitalik.eth")
print(f"Dirección resuelta: {direccion}")
# → 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

# Pagar usando un nombre Solana (.sol)
sol_address = resolver.resolve("example.sol")

# Usar con AgentPay directamente
tx = agente.pay_token(resolver.resolve("socio.eth"), amount=10.0)

🔔 12. Webhooks en Tiempo Real (WebhookManager)

Registra URLs que reciben notificaciones automáticas de tus agentes. Cada evento está firmado con HMAC-SHA256 (el mismo estándar de Stripe) para garantizar que nadie los falsifica.

from iagent_pay.webhooks import WebhookManager

wm = WebhookManager(default_secret="clave-secreta-compartida")

# Registrar un endpoint (tu servidor Flask, FastAPI, etc.)
wm.register("https://tuservidor.com/webhook", events=["payment.completed", "budget.exceeded"])

# Emitir evento manualmente
wm.emit("payment.completed", {"tx_hash": "0xabc...", "amount": 5.0, "currency": "USDC"})

# Handler local (sin necesidad de servidor HTTP)
def mi_handler(evento):
    print(f"Evento recibido: {evento['type']}")

wm.on("payment.completed", mi_handler)

# Eventos disponibles: payment.completed, payment.failed,
# budget.exceeded, human.approval_needed, swap.completed, agent.paused

👤 13. Aprobación Humana (Human-in-the-Loop)

Para pagos grandes, el agente puede pausar y solicitar aprobación humana vía Telegram, Slack o consola. Si el humano no responde antes del tiempo límite, el pago se cancela automáticamente.

from iagent_pay.human_loop import HumanApproval, HumanLoopConfig

hitl = HumanApproval(HumanLoopConfig(
    threshold_usd=20.0,           # Pedir aprobación para pagos > $20
    timeout_seconds=300,          # Esperar máximo 5 minutos
    notify_telegram_token="BOT_TOKEN",  # Token del Bot de Telegram
    notify_telegram_chat_id="CHAT_ID",  # Tu ID de chat
))

# El agente intenta pagar $50 → automáticamente pausa y notifica
aprobado = hitl.request_approval(
    amount=50.0,
    currency="USDC",
    recipient="0xProveedor...",
    reason="Compra de acceso a datos premium"
)

if aprobado:
    agente.pay_token("0xProveedor...", 50.0)
else:
    print("Pago cancelado por el humano o por tiempo.")

🔄 14. Motor de Swaps (SwapEngine)

Intercambia tokens automáticamente. El agente puede convertir ETH a USDC, SOL a BONK, o cualquier par disponible en los exchanges descentralizados Jupiter (Solana) y Uniswap (EVM).

from iagent_pay.swap_engine import SwapEngine

# El swap engine se inicializa con el agente
swap = agente.swap_engine

# Consultar precio antes de intercambiar (cotización)
cotizacion = swap.get_quote(input_token="SOL", output_token="USDC", amount=1.0)
print(f"1 SOL ≈ {cotizacion['output']} USDC (Slippage: {cotizacion['slippage']}%)")

# Ejecutar el swap con protección anti-deslizamiento
resultado = swap.execute_swap(
    input_token="ETH",
    output_token="USDC",
    amount=0.5,
    min_output_amount=900.0  # No acepta menos de 900 USDC
)
print(f"Swap exitoso! Tx: {resultado['tx_hash']}")

🛒 15. Mercado de Datos (Data Marketplace)

Un registro descentralizado donde tus agentes pueden comprar y vender datos. Funciona junto con el protocolo x402: el comprador busca el mejor proveedor, paga automáticamente y recibe los datos.

from iagent_pay.data_marketplace import DataMarketplace, DataProvider, get_marketplace

marketplace = get_marketplace()

# Vendedor: registrar tu API como proveedor de datos
marketplace.register(DataProvider(
    name="MiClimaAPI",
    data_type="weather",
    url="https://miapi.com/v1/clima",
    price_usdc=0.05,
    trust_score=95.0
))

# Comprador: buscar el mejor proveedor de clima (precio < $0.10)
mejor = marketplace.find_best_provider("weather", max_price_usd=0.10)
print(f"Mejor proveedor: {mejor.name} a ${mejor.price_usdc} USDC")

# Ver todos los proveedores disponibles
todos = marketplace.list_all()

🤝 16. Sistema de Reputación (ReputationManager)

Cada agente mantiene un historial de reputación local (0-5 estrellas) de sus contrapartes. Antes de pagarle a un agente desconocido, puedes verificar si ha sido confiable en transacciones anteriores.

from iagent_pay.reputation_manager import ReputationManager

# El ReputationManager viene integrado en el AgentPay
rep = agente.reputation

# Calificar a un agente después de una transacción exitosa
rep.rate_peer("0xProveedor...", score=4.8)  # 0 a 5 estrellas

# Verificar la reputación antes de pagar
confianza = rep.get_trust_score("0xDesconocido...")
print(f"Puntaje de confianza: {confianza}/5.0")
if confianza < 3.0:
    print("⚠️ Este agente tiene baja reputación, proceder con cautela.")

# Ver la lista de agentes más confiables
top_agentes = rep.get_top_agents(limit=5)

🤖 17. Integración con Claude y Cursor (MCP Server)

iAgent-Pay es compatible con el Protocolo MCP (Model Context Protocol), el estándar que usa Claude de Anthropic, Cursor, Windsurf y VS Code. Esto significa que Claude puede ordenarle directamente a tu agente que haga pagos con lenguaje natural.

# Iniciar el servidor MCP desde la terminal:
# iagent-pay mcp-server

# Configurar en tu archivo claude_desktop_config.json:
# {
#   "mcpServers": {
#     "iagentpay": {
#       "command": "python",
#       "args": ["-m", "iagent_pay.mcp_server"]
#     }
#   }
# }

# Una vez conectado, Claude puede ejecutar comandos como:
# "Págale 5 USDC a 0xBob..."
# "¿Cuál es el balance de mi agente?"
# "Haz un swap de 0.1 ETH a USDC"
# "Muéstrame el historial de transacciones"

💻 18. Interfaz de Línea de Comandos (CLI)

iAgent-Pay incluye comandos de terminal para administrar y probar tus agentes sin escribir código Python.

# Crear un nuevo proyecto de agente desde cero
iagent-pay init mi-agente-empresa

# Ver el balance y estado de tu agente
iagent-pay status --chain BASE

# Obtener links de faucets (dinero de prueba gratuito)
iagent-pay faucet

# Iniciar el servidor MCP para conectar con Claude/Cursor
iagent-pay mcp-server

🌐 19. Servidor x402 — Vende tus propios Datos

La otra cara del protocolo x402. Si tú tienes una API con datos valiosos (financieros, climáticos, legales, etc.), puedes protegerla y cobrar automáticamente en USDC a cualquier agente que quiera acceder. Compatible con Flask y FastAPI.

# --- Ejemplo con FastAPI ---
from fastapi import FastAPI, Request
from iagent_pay.x402_server import X402Middleware

app = FastAPI()

# Proteger TODAS las rutas bajo /premium con 0.10 USDC
app.add_middleware(
    X402Middleware,
    payment_address="0xTuDireccionDePago...",
    amount_usdc=0.10,
    protected_paths=["/premium", "/api/v2"],
    network="BASE"
)

@app.get("/premium/data")
async def datos_premium():
    return {"data": "Aquí van tus datos exclusivos"}

# --- Ejemplo con Flask (decorador) ---
from flask import Flask, jsonify
from iagent_pay.x402_server import x402_flask

app_flask = Flask(__name__)

@app_flask.route("/datos-clima")
@x402_flask(amount_usdc=0.05, payment_address="0xTuDireccion...", description="Datos del Clima")
def clima():
    return jsonify({"temperatura": "25°C", "ciudad": "CDMX"})

📊 20. Observabilidad y Monitoreo (PaymentObserver)

Panel de control en tiempo real con estadísticas de todos los pagos. Detecta patrones de gasto anómalos automáticamente e integra con Prometheus y OpenTelemetry para infraestructura enterprise.

from iagent_pay.observability import PaymentObserver, ObservabilityConfig, get_observer

# Configurar observador con detección de anomalías
observer = PaymentObserver(ObservabilityConfig(
    log_level="INFO",
    log_format="json",                  # Logs estructurados JSON
    enable_anomaly_detection=True,      # Alerta si un pago es 3x el promedio
    anomaly_threshold_multiplier=3.0,
    enable_prometheus=True,             # Exponer métricas en /metrics
    prometheus_port=9090,
))

# Registrar eventos manualmente o dejarlo automático
observer.record_payment(amount=5.0, currency="USDC", to="0xBob...", success=True)
observer.record_x402(url="https://api.datos.com/v1", amount=0.01, success=True)

# Ver el dashboard en la terminal
observer.print_dashboard()
# ╔══════════════════════════════════════════════╗
# ║         iAgent-Pay Observability Dashboard     ║
# ║  Total Payments: 42    Success Rate: 98.0%   ║
# ║  Total Spent:    $127.50                      ║
# ╚══════════════════════════════════════════════╝

# Obtener métricas para Prometheus/Grafana
metricas = observer.get_prometheus_metrics()

# Usar el observer global (singleton)
obs_global = get_observer()

💵 21. Motor de Precios en Tiempo Real (PricingManager)

Consulta el precio actual de ETH, SOL y XRP desde 3 fuentes simultáneas (CoinGecko, Coinbase, APIs on-chain). Si una fuente falla, usa automáticamente la siguiente. Si todas fallan, usa el valor en cadena como fallback.

from iagent_pay.pricing import PricingManager

pricing = PricingManager()

# Obtener precios en tiempo real
precio_eth = pricing.get_price("ETH")    # → 3200.50
precio_sol = pricing.get_price("SOL")    # → 145.30
precio_xrp = pricing.get_price("XRP")    # → 0.52

print(f"1 ETH = ${precio_eth:.2f} USD")

# Calcular cuántos tokens necesito para pagar $50
cantidad_eth = 50.0 / precio_eth
print(f"Para pagar $50 necesito {cantidad_eth:.6f} ETH")

# El PricingManager viene integrado automáticamente en AgentPay
# agente.pricing.get_price("ETH")

🌊 22. Red XRP Ledger (XRPLDriver)

Soporte nativo para la red XRP Ledger, uno de los sistemas de pagos más rápidos del mundo (3-5 segundos de confirmación, menos de $0.001 por transacción). Ideal para pagos internacionales de alto volumen.

from iagent_pay.agent_pay import AgentPay

# Inicializar agente en la red XRP
agente_xrp = AgentPay(chain_name="XRP")

# Cargar billetera XRP desde semilla secreta
agente_xrp.xrpl.load_wallet("sYourXRPSecretSeedHere...")

# Verificar balance en XRP
balance = agente_xrp.xrpl.get_balance()
print(f"Balance: {balance} XRP")

# Enviar XRP a otro agente (confirmación en 3-5 segundos)
tx_hash = agente_xrp.xrpl.transfer(
    recipient="rDestinationAddress...",
    amount_xrp=10.0,
    destination_tag=12345    # Para exchanges institucionales
)
print(f"Tx XRP confirmada: {tx_hash}")

🎯 23. Tablero de Recompensas (MarketplaceBridge)

Tu agente puede publicar misiones o recompensas para que humanos realicen tareas específicas. Una vez completada la tarea, el agente libera el pago automáticamente.

from iagent_pay.marketplace_bridge import MarketplaceBridge

bridge = MarketplaceBridge(agente)

# Publicar una recompensa para que un humano realice una tarea
bounty_id = bridge.post_bounty(
    title="Traduce 10 documentos legales al inglés",
    reward_usd=75.0
)
print(f"Recompensa publicada: ID {bounty_id}")

# Ver todas las recompensas activas
mis_bounties = bridge.list_my_bounties()

# Una vez verificado el trabajo, el agente paga automáticamente
bridge.release_payment(bounty_id, human_address="0xFreelancer...")

🦾 24. Integración con CrewAI

CrewAI es el framework más popular para crear equipos de agentes de IA colaborativos. Con esta integración, cualquier agente dentro de un Crew puede pagar a otros agentes o servicios de forma nativa.

from iagent_pay.integrations.crewai import iAgentPayCrewTool
from crewai import Agent, Task, Crew

# Crear la herramienta de pagos con límite de seguridad
herramienta_pago = iAgentPayCrewTool(chain="BASE", max_amount_usdc=5.0)

# Dar la herramienta al agente tesorero del equipo
tesorero = Agent(
    role="Tesorero del Equipo",
    goal="Gestionar pagos entre miembros del equipo de IA",
    backstory="Experto en finanzas on-chain para equipos de agentes.",
    tools=[herramienta_pago],
)

tarea_pago = Task(
    description="Paga 2 USDC a 0xBob... por completar el análisis de datos",
    agent=tesorero
)

crew = Crew(agents=[tesorero], tasks=[tarea_pago])
resultado = crew.kickoff()

🔗 25. Integración con LangChain

LangChain es el framework de IA más usado en el mundo. Con esta integración, cualquier cadena o agente LangChain puede enviar pagos cripto como si fuera una herramienta normal.

from iagent_pay.integrations.langchain import iAgentPayTool
from langchain.agents import initialize_agent, AgentType
from langchain_openai import ChatOpenAI

# Crear la herramienta de pagos para LangChain
herramienta = iAgentPayTool()  # Usa AgentPay automáticamente

# Agregar la herramienta al agente LangChain
llm = ChatOpenAI(model="gpt-4")
agente_lc = initialize_agent(
    tools=[herramienta],
    llm=llm,
    agent=AgentType.OPENAI_FUNCTIONS,
    verbose=True
)

# El agente decide cuándo y cómo pagar basado en el contexto
resultado = agente_lc.run(
    "Paga 0.001 ETH a 0xProveedor... como compensación por el servicio de datos."
)

💰 26. Modelo de Comisiones por Volumen Acumulado

iAgent-Pay implementa un modelo de comisiones ultra-competitivo y transparente basado en el volumen acumulado de transacciones. En lugar de cobrar comisiones de porcentaje caras por cada transacción individual, el sistema cobra una tarifa fija de $1.00 USD por cada $1,000.00 USD de volumen acumulado.

La comisión se calcula y se acumula en segundo plano para no demorar la transacción principal.
Al alcanzar exactamente cada múltiplo de $1,000.00 USD de volumen histórico, el SDK deduce automáticamente la comisión equivalente de $1.00 USD (convertida al tipo de cambio en tiempo real de la criptomoneda nativa o establecoin que se está usando) y la envía a la cartera del tesoro (treasury_address).
Si un usuario envía un pago, la comisión no afecta el saldo recibido por el destinatario, asegurando la integridad exacta de los montos de facturación.

🔒 27. Modos de Seguridad Multifirma y Human-in-the-Loop

Tu agente puede configurarse para operar bajo tres esquemas de seguridad diferentes definidos en la propiedad multisig_mode de tu SafetyConfig:

from iagent_pay.safety_kernel import MultisigMode

# 1. ALLOWANCE_ONLY (Solo Límites Autónomos)
# El agente ejecuta autónomamente pagos por debajo del límite de aprobación.
# Cualquier pago superior se cancelará inmediatamente sin pedir confirmación.
agente.safety_config.multisig_mode = MultisigMode.ALLOWANCE_ONLY

# 2. PROPOSAL_ONLY (Solo Firma / Propuesta de Multifirma)
# Ninguna transacción es autónoma. Cada pago (incluso de $0.01) se detiene 
# y requiere aprobación / firma explícita del humano para ejecutarse.
agente.safety_config.multisig_mode = MultisigMode.PROPOSAL_ONLY

# 3. HYBRID (Híbrido - Autonomía y Gobernanza)
# El agente transacciona libremente montos pequeños. Si un pago supera
# el umbral, se detiene y pide confirmación en lugar de fallar.
agente.safety_config.multisig_mode = MultisigMode.HYBRID

🔄 28. Auto-Balanceo de Liquidez (Auto-Swap Fallback)

Cuando tu agente necesita pagar en una stablecoin o token específico (por ejemplo, USDC) pero no cuenta con suficiente balance del mismo, iAgent-Pay puede balancear automáticamente la liquidez usando las tenencias en la moneda nativa del agente (ETH o SOL).

Esta opción es totalmente configurable por el desarrollador / usuario mediante el flag enable_auto_swap:

# Habilitar Auto-Balanceo (Comportamiento por defecto)
# Si falta USDC pero hay ETH/SOL, realiza un swap automático en Uniswap/Jupiter
agente = AgentPay(enable_auto_swap=True)

# Deshabilitar Auto-Balanceo
# Si no hay suficiente USDC, la transacción fallará inmediatamente indicando
# que es necesario recargar liquidez en ese token específico.
agente = AgentPay(enable_auto_swap=False)

🔑 29. Copia de Seguridad Cifrada (Backup & Restore)

Para mayor seguridad y portabilidad, puedes realizar una copia de seguridad cifrada con contraseña de las credenciales de tu agente, lo cual te permite exportarlas o importarlas fácilmente en cualquier entorno:

A. Desde el SDK (Código Python)

# Crear una copia de seguridad cifrada (AES-128/256 standard keystore)
agente.backup_wallet("mi_respaldo.enc", password="MiContraseñaSegura123")

B. Desde la Consola (CLI)

# Crear copia de seguridad interactiva (te pedirá la contraseña de forma segura)
iagent-pay backup mi_respaldo.enc

# Restaurar copia de seguridad en un nuevo servidor
iagent-pay restore mi_respaldo.enc

📦 30. Transacciones por Lotes (Batch Transactions / Multicall)

iAgent-Pay introduce el soporte para pagos concurrentes optimizados por lotes. En lugar de enviar transacciones secuencialmente y esperar por su confirmación, el agente puede enviar decenas de pagos de stablecoins al mismo tiempo utilizando una arquitectura de flujo canalizado (pipelined nonces) en EVM, y firmas SPL concurrentes en Solana. Esto reduce el consumo de gas hasta un 30% y acelera la velocidad de dispersión x10.

# Pagar a múltiples proveedores o sub-agentes en un solo lote
pagos = [
    {"recipient": "0xProveedorA...", "amount": 10.0},
    {"recipient": "0xProveedorB...", "amount": 25.0},
    {"recipient": "vitalik.eth", "amount": 5.0} # Auto-resolución ENS
]

# Ejecutar el lote (con auto-balanceo de liquidez y safety limits verificados sobre el total acumulado)
tx_hashes = agente.pay_token_batch(pagos, token="USDC", wait=True)
print(f"Transacciones enviadas con éxito: {tx_hashes}")

🔄 31. Auto-Rotación de RPC con Backoff Exponencial y Rate Limit Guard

Para aplicaciones empresariales que requieren una alta disponibilidad ininterrumpida, iAgent-Pay implementa un sistema automatizado de tolerancia a fallos en la conexión de red RPC. Al detectar errores de tasa de límite (HTTP 429) o fallos de conexión de red, el agente aplica un backoff exponencial inteligente y conmuta automáticamente a sus nodos de respaldo previamente configurados sin interrumpir la ejecución del código.

# El sistema utiliza internamente _execute_rpc_with_backoff en cada llamada web3
# Si un nodo falla de forma persistente, el agente rota su proveedor RPC principal:
agente.rotate_rpc()
print(f"Conectado al nuevo proveedor RPC: {agente.w3.provider.endpoint_uri}")

Modo Empresa: Para las empresas que ofrecen sus agentes como servicio, iAgent-Pay soporta transacciones "Sin Gas" (Paymasters). Los usuarios finales nunca tienen que comprar criptomonedas para operar.

📊 32. Panel de Control Visual Corporativo (Solo Lectura)

Para garantizar el máximo nivel de ciberseguridad sin comprometer la transparencia, iAgent-Pay introduce un panel visual de monitoreo en tiempo real con diseño corporativo en tonos pastel. Por diseño de seguridad, este panel es estrictamente de Solo Lectura (Read-Only). Esto evita que actores maliciosos o atacantes que vulneren la interfaz web puedan alterar la configuración del agente, el Safety Kernel, o desviar fondos de la cuenta.

Monitoreo en Tiempo Real: Visualiza balances de gas nativo, stablecoins USDC y el estado de la licencia ERC-8004.
Telemetría de Red y RPC: Muestra el nodo RPC activo, latencia en vivo y número de auto-rotaciones realizadas.
Guardrails del Safety Kernel: Muestra límites diarios, por transacción y el estado de listas blancas.
Exportador de Auditoría Criptográfica: Permite descargar reportes completos del estado del agente en formato JSON compatible mediante un solo clic.

🧪 33. Sandbox de Simulaciones Interactivas Avanzadas

Para propósitos de demostración y pruebas rápidas, iAgent-Pay cuenta con un Entorno Sandbox de Simulaciones interactivo en el dashboard. Esto permite a los desarrolladores y clientes experimentar con todas las funciones autónomas que ofrecemos en tiempo real sin arriesgar fondos reales y con total retroalimentación visual.

Capital Simulado Inicial de $10,000.00 USDC: Cada sesión de simulación comienza con un capital ficticio que disminuye dinámicamente con cada operación exitosa.
Interruptores de Control Interactivos: Activa o desactiva las características que iAgent-Pay ofrece (Safety Kernel, Auto-Swap, RPC Failover, Sponsor Gasless y Human Loop) para observar cómo reacciona el agente frente a fallos y protecciones.
Modos de Ejecución (Simple vs Bucle): Ejecuta una única operación o dispara simulaciones en bucle consecutivo de 5 transacciones en tiempo real con un solo clic.
Consola de Telemetría Interactiva: Muestra logs detallados con marca de tiempo codificados por colores en la consola simulada.
Descarga de Reportes de Simulación: Un botón dedicado para exportar todo el registro de transacciones simuladas en formato JSON para auditoría.
Botón de Reset General: Devuelve la simulación a su estado inicial de forma instantánea ($10,000 USDC de capital y progreso en cero).

🔑 34. Claves de Sesión Efímeras Sin Custodia (Session Keys)

iAgent-Pay permite delegar un poder de firma transaccional temporal a tus agentes de Inteligencia Artificial sin necesidad de exponer la clave privada principal (Master Key). Esto habilita el modelo "Zero-Custody" (Sin Custodia): el agente posee una clave efímera para firmar transacciones de forma autónoma, pero está severamente limitado por las reglas pre-firmadas por el propietario.

Límites por Transacción: El agente no puede enviar pagos individuales superiores a un monto máximo especificado.
Límites Diarios Acumulados: Previene que el agente agote el saldo completo en caso de comportamiento errático.
Vencimiento Temporal (Expiry): Cada clave de sesión vence automáticamente después de un período determinado (en segundos).
Lista Blanca de Destinatarios: El agente solo puede transferir fondos a las direcciones pre-aprobadas (por defecto, solo permite regresar fondos al propietario).

from iagent_pay import AgentPay
from iagent_pay.session_keys import SessionKeyManager

# 1. El propietario inicializa su cuenta master
owner_account = wm.get_or_create_wallet("MiContraseñaSegura123")

# 2. Crea una clave de sesión restringida (Vence en 1 hora, límite diario de $100 USD, límite por tx de $20 USD)
session_key = SessionKeyManager.create_session(
    owner_account=owner_account,
    allowed_tokens=["USDC", "ETH"],
    daily_limit_usd=100.0,
    max_tx_usd=20.0,
    validity_seconds=3600,
    allowed_destinations=[owner_account.address, "0xProveedorA..."]
)

# 3. El agente de IA carga la clave de sesión efímera
agente = AgentPay(chain_name="SEPOLIA")
agente.use_session_key(session_key)

# 4. El agente realiza un pago de $5 USDC de forma autónoma (Se valida contra las reglas de la sesión)
tx = agente.pay_token("0xProveedorA...", amount=5.0, token="USDC")
print(f"Transacción autorizada y enviada: {tx}")

🏅 35. Cumplimiento y Verificación de Identidad (Know Your Agent - KYA)

Para aplicaciones empresariales y cumplimiento regulatorio, iAgent-Pay implementa el protocolo **Know Your Agent (KYA)**. Habilita una reputación y verificación de confianza basada en DIDs (Identificadores Descentralizados) y Credenciales Verificables. Esto previene ataques de suplantación y permite acelerar transferencias y elevar límites para agentes confiables.

DIDs de W3C: Cada agente posee un DID único determinista en formato did:iagent:<hash>.
Niveles de Confianza (TrustLevel): Desde UNKNOWN, pasando por VERIFIED hasta ELITE, los límites aumentan y la fricción disminuye dinámicamente.
Credenciales Verificables (Verifiable Credentials): Los emisores pueden otorgar reclamaciones (claims) firmadas al agente.
Lista Negra (Blacklisting): Los agentes fraudulentos se bloquean globalmente, rechazando cualquier transacción hacia o desde ellos.

from iagent_pay.kya import AgentIdentity, get_registry

# 1. Crear identidad para el agente de IA
identidad = AgentIdentity.create(
    name="ResearcherBot-7",
    owner_address="0xAlice...",
    capabilities=["payments", "web_search"]
)
print(f"DID generado: {identidad.did}")

# 2. Registrar el agente en el registro KYA
registry = get_registry()
registry.register(identidad)

# 3. Actualizar reputación después de transacciones exitosas
# (Aumenta dinámicamente el ART Reputation Score del agente)
registry.update_after_payment(identidad.did, success=True, amount_usd=50.0)

# 4. Obtener reporte completo de KYA y nivel de confianza
reporte = registry.get_full_report(identidad.did)
print(f"Nivel de Confianza: {reporte['trust_level']} (Reputación ART: {reporte['art_score']}/100)")

📈 36. Reportes Analíticos Avanzados y Resumen Ejecutivo

iAgent-Pay incluye un módulo avanzado para generar inteligencia de negocios a partir del historial de transacciones de tus agentes. Este módulo permite agrupar datos (Diario, Semanal, Mensual, Anual) y visualizar el crecimiento del capital, volumen procesado, ahorro de comisiones y métricas de adquisición de usuarios (agentes).

Métricas de Crecimiento: Gráficas interactivas que modelan el Volumen USD, Comisiones y Adquisición.
Filtros Temporales: Analiza horizontes específicos con un seleccionador de fechas incorporado en el Dashboard.
Exportación Profesional: Genera con un solo clic un Resumen Ejecutivo en PDF (con gráficas incrustadas) o en Excel (CSV) para uso corporativo o contable.
Paginación Inteligente: El backend está optimizado para procesar y agrupar miles de transacciones de forma hiper-eficiente utilizando SQLite optimizado y paginación matemática en los endpoints /api/admin/advanced_reports.

# Las funciones de Reportes Avanzados están directamente integradas en el Dashboard.
# Para acceder:
# 1. Abre el panel corporativo (admin.html)
# 2. Navega a la pestaña "📈 Reportes Avanzados"
# 3. Selecciona la Agrupación (Ej: Mensual) y tu Rango de Fechas
# 4. Haz clic en "Generar Reporte" y visualiza las gráficas.
# 5. Usa los botones "Exportar a PDF Avanzado" o "Exportar a Excel" para tus registros contables.

🧠 37. Protección contra Alucinaciones (Hallucination Guard)

Los modelos de lenguaje grandes (LLMs) pueden sufrir de "alucinaciones" matemáticas o lógicas. iAgent-Pay cuenta con un Hallucination Guard en su Safety Kernel que previene que los agentes ejecuten transacciones basadas en precios falsos o matemáticas incorrectas generadas por el modelo de IA.

Verificación Cruzada de Precios: El SDK ignora el precio que el LLM dice que tienen los tokens y realiza su propia cotización en cadena en tiempo real antes de firmar cualquier transacción.
Chequeos de Deslizamiento (Slippage): Si un agente decide hacer un swap, el SDK calcula matemáticamente si el intercambio tiene sentido financiero. Si la pérdida es mayor al umbral de seguridad (slippage > 5%), la transacción aborta automáticamente.
Límites Estrictos en Contexto: Al usar el servidor MCP, las reglas financieras se inyectan en el prompt del sistema de la IA como directivas duras, limitando el marco cognitivo del modelo.

🕵️ 38. Recibos Criptográficos de Razonamiento (Proof of Reasoning)

Para lograr transparencia total, iAgent-Pay permite adjuntar un "Proof of Reasoning" (Prueba de Razonamiento) a cada pago. Esto no es solo el hash de la transacción, sino un recibo que explica matemáticamente por qué la IA decidió gastar ese dinero.

from iagent_pay.proof_of_reasoning import ProofGenerator

# El agente decide pagar por una API y genera su recibo de razonamiento
recibo = ProofGenerator.create_proof(
    tx_hash="0x123abc...",
    amount=50.0,
    currency="USDC",
    reasoning="Compré 10,000 llamadas a la API meteorológica porque mi análisis indicó una alta probabilidad de huracán y necesito datos en tiempo real.",
    llm_confidence=0.98
)

print(f"Recibo Forense Inmutable: {recibo.get_receipt_url()}")

📘 Official Reference Manual: iAgent-Pay (v8.5.0)

Welcome to iAgent-Pay, the most advanced payment infrastructure for AI Agents. This technical manual is designed to teach you how to unlock 100% of your agents' capabilities, allowing them to operate, charge, and invest autonomously on a global scale.

🌎 1. Global Support & Multi-Chain Architecture

iAgent-Pay is not just a local API; it is a global financial gateway. Our routing engine allows your agent to move money across the entire Web3 ecosystem.

Ethereum (ETH): High liquidity, maximum security.
Base (BASE): Coinbase's Layer 2, ideal for low fees.
Solana (SOL): Extreme speed (thousands of TPS).

The agent is "Currency Agnostic". Built-in currencies include: USDC, USDT, EURC (Euro), CNHC (Yuan), GYEN (Yen), MXNT (Peso).

from iagent_pay import AgentPay

# Agent specialized in the Asian market
agent = AgentPay(chain_name="BASE", default_stablecoin="CNHC")

⚡ 2. Core Features

A. Autonomous Payments (x402)

tx_hash = agent.pay_token(
    recipient_address="0xProvider...", 
    amount=5.0
)
print(f"Payment completed: {tx_hash}")

B. Invoicing

If your AI performs a job for a client, it can generate a "Smart Invoice".

invoice_id = agent.invoices.create_invoice(
    amount=25.0, 
    customer_address="0xClient...", 
    description="Code Audit"
)

🏢 4. Corporate Consolidation (Enterprise Tier)

iAgent-Pay has been scaled to handle uninterrupted global operations (24/7) and millions of simultaneous transactions using the following technologies:

⚡ 54,000+ TPS Performance: Using PostgreSQL and advanced Connection Pooling, the system processes massive request waves without exhausting server memory.
💰 iAgent-Yield (Auto-Yield): Your idle funds invest themselves! Through our native Aave v3 integration, inactive bot budgets and treasury commissions automatically generate ~5% APY.
🔐 Disaster Recovery (AES-256): The system performs encrypted cold backups every day to protect accounting against network catastrophes.
🌍 Multi-Language No-Code Portal: 10 languages available in a visual interface for your clients to set financial limits without touching code.
📲 External Alerts (Telegram/Discord): The SafetyKernel sends direct push notifications to your mobile regarding suspicious transactions or DDoS attacks.

🛡️ 5. Safety Kernel

Giving financial freedom to software requires hard limits. Validates every transaction before touching the network.

Daily Limits: Prevents a rogue agent from draining your account.
Smart Identity (ERC-8004): Agents have a "Sovereign Identity" on the blockchain, immune to private key theft.

# Limit to max $15 per day
agent = AgentPay(daily_limit=15.0)

# Mint Identity
identity = agent.identity.mint_soulbound_id("Bot", "0xOwner")

📈 4. Autonomous Treasury (DeFi)

Automatically deposit excess savings into global protocols like Aave v3, generating yield while you sleep.

# Keep $50 in cash, invest the rest
agent.yield_manager.auto_invest(buffer_usd=50.0)

🏦 5. Fiat Bridge (Bank & Card Payments)

Client doesn't have crypto? No problem. iAgent-Pay connects directly to Stripe to deposit money into traditional bank accounts or charge credit cards.

Stripe Transfer: Pay anyone with a bank account.
ACH (US): Low-cost direct bank transfers.
Smart Router: Automatically picks cheapest route (crypto vs bank).
Payment Link: Agent generates a link for humans to pay without crypto.

from iagent_pay.fiat_bridge import FiatBridge

bridge = FiatBridge()

# Pay a freelancer to their bank account
bridge.send_stripe(amount_usd=150.0, stripe_account_id="acct_1M2...", description="Biweekly payment")

# Agent creates a payment link for card payments
link = bridge.create_payment_link(amount_usd=9.99, description="Premium API Access")
print(link["url"])  # → https://buy.stripe.com/...

# Smart router: automatically decides USDC or Stripe
bridge.smart_send(amount_usd=25.0, recipient="client@company.com")

🌉 6. Cross-Chain Routing (AP2 Engine)

The agent can hold money on one network (e.g. Ethereum) and pay on another (e.g. Polygon). The AP2 Engine evaluates all available bridges and selects the cheapest and fastest automatically.

from iagent_pay.cross_chain import CrossChainRouter

router = CrossChainRouter()

# Move $100 USDC from Base → Polygon automatically
tx = router.bridge_assets(
    source_chain="BASE",
    target_chain="POLYGON",
    amount=100.0,
    token="USDC"
)
print(f"Bridge complete: {tx}")

🤖 7. Fleet Management (Sub-Agents)

For multi-agent teams. A Master Agent can create and control specialized "sub-agents", each with their own budget, limits, and isolated transaction history.

from iagent_pay.sub_agents import SubAgentManager

# Master agent with $500 total budget
manager = SubAgentManager(master_budget_usd=500.0)

# Create specialized sub-agents
researcher = manager.create("researcher", daily_limit_usd=20.0)
writer     = manager.create("writer",     daily_limit_usd=10.0)

researcher.kernel.check(amount=5.0, recipient="0xDataAPI...")
researcher.spend(5.0, "USDC", "Market data purchase")

# Emergency pause
manager.pause("researcher")
print(manager.get_status())

🌐 8. Full Global Token Dictionary

Network	Supported Tokens	Use Case
Ethereum (ETH)	USDC, USDT, DAI, EURC, CNHC (Yuan), GYEN (Yen), XSGD, MXNT	High liquidity, max security
Base (BASE)	USDC, USDT, DAI, EURC, WETH	Minimal fees, Coinbase
Polygon (MATIC)	USDC, USDT, DAI, WETH	Fast micropayments
Arbitrum (ARB)	USDC, USDT, DAI, WETH	High speed, low cost
BNB (Binance)	USDC, USDT, BUSD, DAI	Binance ecosystem
Solana (SOL)	USDC native, SOL	Extreme speed (4000+ TPS)

agent_latam = AgentPay(chain_name="BNB", default_stablecoin="USDT")
agent_eu    = AgentPay(chain_name="ETH", default_stablecoin="EURC")
agent_asia  = AgentPay(chain_name="ETH", default_stablecoin="CNHC")

⚙️ 9. Advanced Safety Kernel

from iagent_pay.safety_kernel import SafetyKernel, SafetyConfig

kernel = SafetyKernel(SafetyConfig(
    daily_limit_usd=100.0,
    weekly_limit_usd=500.0,
    session_limit_usd=20.0,
    max_tx_usd=10.0,
    max_tx_per_minute=5,
    max_tx_per_hour=50,
    human_approval_threshold_usd=50.0,
    allowed_recipients=["0xAlice...", "0xBob..."],
    enable_whitelist=True,
))

kernel.check(amount=5.0, recipient="0xAlice...", currency="USDC")
print(kernel.get_status())
audit_log = kernel.get_audit_log()

💳 10. Wallet Manager

Creates, imports and protects your agent's cryptographic keys. Supports AES-128 encrypted keystores and .env files for development.

from iagent_pay.wallet_manager import WalletManager

wm = WalletManager()

# Create or load wallet automatically
wallet = wm.get_or_create_wallet(password="MySecurePassword123")
print(f"Agent Address: {wallet.address}")

# Import existing wallet from private key
imported = wm.load_wallet("0xYourPrivateKeyHere...")

# Create ephemeral wallet (for testing)
temp_wallet = wm.create_wallet()

🔤 11. Social Name Resolver

Instead of copying addresses like 0x7F5E..., your agent can resolve human-readable names like ENS domains or Solana Name Service.

from iagent_pay.social_resolver import SocialResolver

resolver = SocialResolver()

# Pay using ENS name
address = resolver.resolve("vitalik.eth")
# → 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

# Pay using Solana name
sol_address = resolver.resolve("example.sol")

# Use directly with AgentPay
tx = agent.pay_token(resolver.resolve("partner.eth"), amount=10.0)

🔔 12. Real-Time Webhooks

Register URLs that receive automatic notifications from your agents. Each event is signed with HMAC-SHA256 (Stripe's same standard) to prevent forgery.

from iagent_pay.webhooks import WebhookManager

wm = WebhookManager(default_secret="my-shared-secret")
wm.register("https://myserver.com/webhook", events=["payment.completed", "budget.exceeded"])

# Emit event manually
wm.emit("payment.completed", {"tx_hash": "0xabc...", "amount": 5.0})

# Local handler (no HTTP server needed)
def my_handler(event):
    print(f"Event received: {event['type']}")

wm.on("payment.completed", my_handler)

# Available events: payment.completed, payment.failed,
# budget.exceeded, human.approval_needed, swap.completed, agent.paused

👤 13. Human-in-the-Loop Approval

For large payments, the agent pauses and requests human approval via Telegram, Slack, or console. If no response within the timeout, the payment is automatically cancelled.

from iagent_pay.human_loop import HumanApproval, HumanLoopConfig

hitl = HumanApproval(HumanLoopConfig(
    threshold_usd=20.0,           # Ask approval for payments > $20
    timeout_seconds=300,          # Wait max 5 minutes
    notify_telegram_token="BOT_TOKEN",
    notify_telegram_chat_id="CHAT_ID",
))

approved = hitl.request_approval(
    amount=50.0,
    currency="USDC",
    recipient="0xVendor...",
    reason="Premium data access purchase"
)

if approved:
    agent.pay_token("0xVendor...", 50.0)

🔄 14. Swap Engine

Exchange tokens automatically. The agent can convert ETH to USDC, SOL to BONK, or any pair on Jupiter (Solana) and Uniswap (EVM).

swap = agent.swap_engine

# Get a price quote before swapping
quote = swap.get_quote(input_token="SOL", output_token="USDC", amount=1.0)
print(f"1 SOL ≈ {quote['output']} USDC (Slippage: {quote['slippage']}%)")

# Execute swap with slippage protection
result = swap.execute_swap(
    input_token="ETH",
    output_token="USDC",
    amount=0.5,
    min_output_amount=900.0  # Reject if less than 900 USDC received
)
print(f"Swap successful! Tx: {result['tx_hash']}")

🛒 15. Data Marketplace

A decentralized registry where your agents can buy and sell data. Works with x402: the buyer finds the best provider, pays automatically, and receives the data.

from iagent_pay.data_marketplace import DataMarketplace, DataProvider, get_marketplace

marketplace = get_marketplace()

# Seller: register your API as a data provider
marketplace.register(DataProvider(
    name="MyWeatherAPI", data_type="weather",
    url="https://myapi.com/v1/weather", price_usdc=0.05, trust_score=95.0
))

# Buyer: find best weather provider under $0.10
best = marketplace.find_best_provider("weather", max_price_usd=0.10)
print(f"Best: {best.name} at ${best.price_usdc}")

🤝 16. Reputation System

Each agent maintains a local reputation ledger (0-5 stars) for its counterparts. Before paying an unknown agent, check their track record.

rep = agent.reputation

# Rate a peer after a successful transaction
rep.rate_peer("0xVendor...", score=4.8)

# Check reputation before paying
trust = rep.get_trust_score("0xUnknown...")
if trust < 3.0:
    print("Low trust agent — proceed with caution.")

# View most trusted agents
top = rep.get_top_agents(limit=5)

🤖 17. Claude & Cursor Integration (MCP Server)

iAgent-Pay is fully compatible with the Model Context Protocol (MCP), used by Claude, Cursor, Windsurf, and VS Code. Claude can directly instruct your agent to make payments in natural language.

# Start MCP server from terminal:
# iagent-pay mcp-server

# Configure in claude_desktop_config.json:
# {
#   "mcpServers": {
#     "iagentpay": {
#       "command": "python",
#       "args": ["-m", "iagent_pay.mcp_server"]
#     }
#   }
# }

# Once connected, Claude can say:
# "Pay 5 USDC to 0xBob..."
# "What is my agent balance?"
# "Swap 0.1 ETH to USDC"
# "Show recent transaction history"

💻 18. Command Line Interface (CLI)

iAgent-Pay includes terminal commands to manage and test agents without writing Python code.

# Create a new agent project from scratch
iagent-pay init my-enterprise-agent

# View agent balance and status
iagent-pay status --chain BASE

# Get testnet faucet links (free test money)
iagent-pay faucet

# Start the MCP server for Claude/Cursor integration
iagent-pay mcp-server

🌐 19. x402 Server — Sell Your Own Data

The other side of the x402 protocol. If you have an API with valuable data (financial, weather, legal, etc.), you can protect it and automatically charge USDC to any agent that wants access. Compatible with Flask and FastAPI.

# --- FastAPI Example ---
from fastapi import FastAPI, Request
from iagent_pay.x402_server import X402Middleware

app = FastAPI()

# Protect all /premium routes for 0.10 USDC
app.add_middleware(
    X402Middleware,
    payment_address="0xYourPaymentAddress...",
    amount_usdc=0.10,
    protected_paths=["/premium", "/api/v2"],
    network="BASE"
)

@app.get("/premium/data")
async def premium_data():
    return {"data": "Your exclusive data here"}

# --- Flask Example (decorator) ---
from iagent_pay.x402_server import x402_flask

@app_flask.route("/weather-data")
@x402_flask(amount_usdc=0.05, payment_address="0xYourAddress...", description="Weather Data")
def weather():
    return jsonify({"temperature": "25°C", "city": "NYC"})

📊 20. Observability & Monitoring

Real-time dashboard with statistics for all payments. Automatically detects anomalous spending patterns and integrates with Prometheus and OpenTelemetry for enterprise infrastructure.

from iagent_pay.observability import PaymentObserver, ObservabilityConfig

observer = PaymentObserver(ObservabilityConfig(
    log_level="INFO",
    log_format="json",
    enable_anomaly_detection=True,
    anomaly_threshold_multiplier=3.0,
    enable_prometheus=True,
    prometheus_port=9090,
))

observer.record_payment(amount=5.0, currency="USDC", to="0xBob...", success=True)

# Print terminal dashboard
observer.print_dashboard()
# ╔══════════════════════════════════════════════╗
# ║         iAgent-Pay Observability Dashboard     ║
# ║  Total Payments: 42    Success Rate: 98.0%   ║
# ╚══════════════════════════════════════════════╝

# Prometheus metrics for Grafana
metrics = observer.get_prometheus_metrics()

💵 21. Real-Time Pricing Engine

Queries current prices of ETH, SOL, and XRP from 3 simultaneous sources. Automatically falls back to the next source if one fails.

from iagent_pay.pricing import PricingManager

pricing = PricingManager()

eth_price = pricing.get_price("ETH")    # → 3200.50
sol_price = pricing.get_price("SOL")    # → 145.30

# Calculate how many tokens needed to pay $50
eth_needed = 50.0 / eth_price
print(f"To pay $50 you need {eth_needed:.6f} ETH")

🌊 22. XRP Ledger Network

Native support for XRP Ledger, one of the fastest payment networks in the world (3-5 second confirmation, under $0.001 per transaction). Ideal for high-volume international payments.

from iagent_pay.agent_pay import AgentPay

agent_xrp = AgentPay(chain_name="XRP")
agent_xrp.xrpl.load_wallet("sYourXRPSecretSeedHere...")

balance = agent_xrp.xrpl.get_balance()
print(f"Balance: {balance} XRP")

# Send XRP (confirmed in 3-5 seconds)
tx_hash = agent_xrp.xrpl.transfer(
    recipient="rDestinationAddress...",
    amount_xrp=10.0,
    destination_tag=12345
)
print(f"XRP Tx confirmed: {tx_hash}")

🎯 23. Bounty Marketplace (MarketplaceBridge)

Your agent can post bounties for humans to complete specific tasks. Once the task is verified, the agent releases payment automatically.

from iagent_pay.marketplace_bridge import MarketplaceBridge

bridge = MarketplaceBridge(agent)

# Post a bounty for a human task
bounty_id = bridge.post_bounty(
    title="Translate 10 legal documents to Spanish",
    reward_usd=75.0
)

# View active bounties
my_bounties = bridge.list_my_bounties()

# Once work is verified, agent pays automatically
bridge.release_payment(bounty_id, human_address="0xFreelancer...")

🦾 24. CrewAI Integration

CrewAI is the most popular framework for building collaborative AI agent teams. With this integration, any agent in a Crew can pay other agents or services natively.

from iagent_pay.integrations.crewai import iAgentPayCrewTool
from crewai import Agent, Task, Crew

# Create payment tool with safety limit
pay_tool = iAgentPayCrewTool(chain="BASE", max_amount_usdc=5.0)

treasurer = Agent(
    role="Team Treasurer",
    goal="Manage payments between AI team members",
    tools=[pay_tool],
)

pay_task = Task(
    description="Pay 2 USDC to 0xBob... for completing data analysis",
    agent=treasurer
)

crew = Crew(agents=[treasurer], tasks=[pay_task])
result = crew.kickoff()

🔗 25. LangChain Integration

LangChain is the world's most used AI framework. With this integration, any LangChain chain or agent can send crypto payments as a native tool.

from iagent_pay.integrations.langchain import iAgentPayTool
from langchain.agents import initialize_agent, AgentType
from langchain_openai import ChatOpenAI

pay_tool = iAgentPayTool()

llm = ChatOpenAI(model="gpt-4")
lc_agent = initialize_agent(
    tools=[pay_tool],
    llm=llm,
    agent=AgentType.OPENAI_FUNCTIONS,
    verbose=True
)

result = lc_agent.run(
    "Pay 0.001 ETH to 0xVendor... as compensation for data services."
)

💰 26. Volume Accumulation Fee Model

iAgent-Pay implements an ultra-competitive and transparent pricing fee structure based on accumulated transaction volume. Instead of charging expensive percentage-based fees on individual transactions, the system logs total transaction volume in the background and settles a flat fee of $1.00 USD for every $1,000.00 USD of total volume transacted.

The fee is computed in the background to ensure no latency for the main transaction payload.
Exactly when the accumulated volume reaches any multiple of $1,000.00 USD, the SDK automatically settles the equivalent $1.00 USD fee (converted to the real-time valuation of the currency used) and transfers it directly to the treasury_address.
This ensures that if a user sends a payment, the recipient receives the exact, intact invoice amount without percentage cuts.

🔒 27. Multisig & Human-in-the-Loop Security Modes

Your agent can be configured to run under three distinct security and governance schemes using the multisig_mode property in your SafetyConfig:

from iagent_pay.safety_kernel import MultisigMode

# 1. ALLOWANCE_ONLY (Autonomous Limits Only)
# The agent executes payments autonomously under the threshold.
# Any transaction exceeding the limit is aborted immediately without prompt.
agent.safety_config.multisig_mode = MultisigMode.ALLOWANCE_ONLY

# 2. PROPOSAL_ONLY (Proposal & Multisig Signing Only)
# No autonomous payments allowed. Every transaction (even $0.01) is paused
# and requests a manual signature/approval from the human administrator.
agent.safety_config.multisig_mode = MultisigMode.PROPOSAL_ONLY

# 3. HYBRID (Hybrid — Autonomy & Governance)
# The agent transacts autonomously for small payments. If a payment exceeds
# the threshold, the SDK pauses and requests human approval instead of failing.
agent.safety_config.multisig_mode = MultisigMode.HYBRID

🔄 28. Auto-Liquidity-Balancing (Auto-Swap Fallback)

When your agent needs to make a payment in a specific stablecoin or token (e.g. USDC) but does not have enough balance, iAgent-Pay can automatically balance liquidity by swapping the agent's native holdings (ETH or SOL).

This feature is fully configurable by the developer / user via the enable_auto_swap config flag:

# Enable Auto-Balancing (Default Behavior)
# Swaps ETH/SOL automatically on Uniswap/Jupiter to cover missing stablecoin balance
agent = AgentPay(enable_auto_swap=True)

# Disable Auto-Balancing
# If USDC balance is insufficient, the transaction fails immediately.
# The agent will prompt the user to manually reload liquidity in that specific token.
agent = AgentPay(enable_auto_swap=False)

🔑 29. Encrypted Key Backup & Restore

For enhanced portability and security, you can create a password-encrypted backup of your agent's credentials. This allows you to securely export and import them to any new server or environment:

A. Via the SDK (Python Code)

# Create password-encrypted backup (AES-128/256 standard Web3 keystore format)
agent.backup_wallet("backup_wallet.enc", password="MySecureBackupPassword123")

B. Via the CLI

# Create an interactive encrypted backup (prompts securely for password)
iagent-pay backup backup_wallet.enc

# Restore the backup to a new server/active local agent keystore
iagent-pay restore backup_wallet.enc

📦 30. Batch Transactions (Pipelined Multicall)

iAgent-Pay introduces support for optimized concurrent batch payments. Instead of sending transactions sequentially and waiting for confirmation, the agent can send dozens of stablecoin payments simultaneously using a pipelined nonce architecture on EVM and concurrent SPL transfers on Solana. This reduces gas overhead by up to 30% and accelerates payouts by 10x.

# Pay multiple vendors or sub-agents in a single batch
payments = [
    {"recipient": "0xVendorA...", "amount": 10.0},
    {"recipient": "0xVendorB...", "amount": 25.0},
    {"recipient": "vitalik.eth", "amount": 5.0} # Automatic ENS resolution
]

# Execute the batch (with auto-liquidity balancing and safety limits evaluated on the cumulative sum)
tx_hashes = agent.pay_token_batch(payments, token="USDC", wait=True)
print(f"Transactions successfully broadcasted: {tx_hashes}")

🔄 31. RPC Auto-Rotation with Exponential Backoff & Rate Limit Guard

For enterprise-grade applications requiring uninterrupted high-availability, iAgent-Pay implements an automated RPC network connection failover system. Upon detecting rate limits (HTTP 429) or persistent connection drops, the agent applies an intelligent exponential backoff and automatically rotates to alternative backup nodes without halting execution.

# The SDK automatically wraps all web3 calls in _execute_rpc_with_backoff
# If a node exhibits persistent failures, the agent rotates to the next node:
agent.rotate_rpc()
print(f"Switched to backup RPC provider: {agent.w3.provider.endpoint_uri}")

Enterprise Mode: For companies offering agents as a service, iAgent-Pay supports "Gasless" transactions (Paymasters). End users never have to buy crypto to operate.

📊 32. Corporate Visual Dashboard (Read-Only)

To guarantee the highest level of cybersecurity without compromising transparency, iAgent-Pay introduces a real-time visual monitoring dashboard with a clean pastel corporate design. By security design, this panel is strictly Read-Only. This prevents malicious actors or attackers from modifying agent configurations, altering the Safety Kernel, or draining funds through web interface exploits.

Real-Time Monitoring: Visualize native gas balances, USDC stablecoin balances, and ERC-8004 license status.
Network & RPC Telemetry: View active RPC nodes, latency metrics, and total auto-rotations performed.
Safety Kernel Guardrails: Displays daily limits, transaction thresholds, and whitelist state.
Audit JSON Exporter: Allows downloading complete agent status reports in standard JSON format in one click.

🧪 33. Advanced Interactive Simulation Sandbox

For demonstration and quick-testing purposes, iAgent-Pay features an interactive Simulation Sandbox Environment on the dashboard. This allows developers and clients to experiment with all autonomous capabilities in real time without risking real funds, coupled with complete visual telemetry feedback.

Initial Simulated Capital of $10,000.00 USDC: Each simulation starts with a mock balance that decreases dynamically with each successfully confirmed transaction.
Interactive Feature Toggles: Enable or disable key iAgent-Pay features (Safety Kernel, Auto-Swap, RPC Failover, Gasless Sponsor, and Human-in-the-Loop) to observe how the agent handles failures and policy boundaries.
Execution Modes (Single vs Loop): Run a single simulated action or trigger a consecutive loop of 5 operations with a single click.
Interactive Telemetry Console: Color-coded logs with timestamps output directly to the mock console.
Simulation Audit Exporter: Download complete simulated transaction ledgers in standard JSON format in one click.
Global Reset Button: Reverts the entire sandbox back to default parameters ($10,000.00 USDC balance and zero progress) instantly.

🔑 34. Ephemeral Zero-Custody Session Keys

iAgent-Pay allows delegating restricted, temporary transaction signing power to your AI agents without exposing your master private key. This enables a complete "Zero-Custody" security model: the agent signs transactions autonomously using a temporary key, while remaining strictly bound by rules pre-signed by the wallet owner.

Single Transaction Caps: Prevents the agent from sending individual payments above a pre-defined threshold.
Daily Cumulative Limits: Restricts total spending per day to prevent loss in case of logic bugs or infinite loops.
Time Expiry (TTL): Ephemeral keys automatically expire and become invalid after a designated duration.
Destination Whitelisting: The agent can only transfer funds to pre-approved addresses (by default, only back to the owner).

from iagent_pay import AgentPay
from iagent_pay.session_keys import SessionKeyManager

# 1. Load the master wallet owner
owner_account = wm.get_or_create_wallet("MySecurePassword123")

# 2. Create a restricted session key (TTL: 1 hour, daily cap: $100, single tx cap: $20)
session_key = SessionKeyManager.create_session(
    owner_account=owner_account,
    allowed_tokens=["USDC", "ETH"],
    daily_limit_usd=100.0,
    max_tx_usd=20.0,
    validity_seconds=3600,
    allowed_destinations=[owner_account.address, "0xVendorA..."]
)

# 3. Load the session key into the AgentPay instance
agent = AgentPay(chain_name="SEPOLIA")
agent.use_session_key(session_key)

# 4. Execute transaction autonomously (validated instantly against session bounds)
tx = agent.pay_token("0xVendorA...", amount=5.0, token="USDC")
print(f"Transaction successfully broadcasted: {tx}")

🏅 35. Compliance & Trust Verification (Know Your Agent - KYA)

For enterprise compliance and security, iAgent-Pay introduces the **Know Your Agent (KYA)** standard. Using W3C Decentralized Identifiers (DIDs) and Verifiable Credentials, agents can prove their identity and build reputation scores. Higher trust levels grant lower friction, faster execution, and higher spending limits.

W3C Standard DIDs: Unique DID documents issued in the format did:iagent:<hash>.
Trust Levels (TrustLevel): Dynamic levels ranging from UNKNOWN, VERIFIED, up to ELITE based on successful transactions.
Verifiable Credentials: Secure claims issued by controllers detailing agent capabilities and limits.
Compliance Blacklisting: Fraudulent or misbehaving DIDs are instantly blacklisted, blocking all incoming and outgoing payments.

from iagent_pay.kya import AgentIdentity, get_registry

# 1. Create a decentralized identity for the AI agent
identity = AgentIdentity.create(
    name="ResearcherBot-7",
    owner_address="0xAlice...",
    capabilities=["payments", "web_search"]
)
print(f"Agent DID: {identity.did}")

# 2. Register the agent in the KYA database
registry = get_registry()
registry.register(identity)

# 3. Automatically build reputation score through transaction history
registry.update_after_payment(identity.did, success=True, amount_usd=50.0)

# 4. Fetch KYA audit report and trust score
report = registry.get_full_report(identity.did)
print(f"Trust Level: {report['trust_level']} (ART Rep Score: {report['art_score']}/100)")

📈 36. Advanced Analytical Reports & Executive Summary

iAgent-Pay includes an advanced module for generating business intelligence from your agents' transaction history. This module allows you to group data (Daily, Weekly, Monthly, Yearly) and visualize capital growth, processed volume, commission savings, and user (agent) acquisition metrics.

Growth Metrics: Interactive charts that model USD Volume, Commissions, and Acquisition.
Time Filters: Analyze specific horizons with a date picker built into the Dashboard.
Professional Export: Generate a one-click Executive Summary in PDF (with embedded charts) or Excel (CSV) for corporate or accounting use.
Smart Pagination: The backend is optimized to process and group thousands of transactions hyper-efficiently using optimized SQLite and mathematical pagination on the /api/admin/advanced_reports endpoints.

# Advanced Reports features are directly integrated into the Dashboard.
# To access:
# 1. Open the corporate panel (admin.html)
# 2. Navigate to the "📈 Advanced Reports" tab
# 3. Select the Grouping (e.g., Monthly) and your Date Range
# 4. Click "Generate Report" and view the charts.
# 5. Use the "Export to Advanced PDF" or "Export to Excel" buttons for your accounting records.

🧠 37. AI Hallucination Guard

Large Language Models (LLMs) can suffer from mathematical or logical "hallucinations". iAgent-Pay features a Hallucination Guard in its Safety Kernel that prevents agents from executing transactions based on fake prices or incorrect math generated by the AI model.

Price Cross-Verification: The SDK ignores the price the LLM claims tokens have and performs its own real-time on-chain quote before signing any transaction.
Slippage Checks: If an agent decides to swap, the SDK mathematically calculates if the trade makes financial sense. If the loss exceeds the safety threshold (slippage > 5%), the transaction automatically aborts.
Strict Context Limits: When using the MCP server, financial rules are injected into the AI's system prompt as hard directives, limiting the model's cognitive framework.

🕵️ 38. Cryptographic Proof of Reasoning

To achieve full transparency, iAgent-Pay allows attaching a "Proof of Reasoning" to each payment. This is not just the transaction hash, but a receipt that mathematically explains why the AI decided to spend that money.

from iagent_pay.proof_of_reasoning import ProofGenerator

# The agent decides to pay for an API and generates its reasoning receipt
receipt = ProofGenerator.create_proof(
    tx_hash="0x123abc...",
    amount=50.0,
    currency="USDC",
    reasoning="I bought 10,000 calls to the weather API because my analysis indicated a high probability of a hurricane and I need real-time data.",
    llm_confidence=0.98
)

print(f"Immutable Forensic Receipt: {receipt.get_receipt_url()}")

📘 官方参考手册：iAgent-Pay (v8.5.0)

欢迎来到 iAgent-Pay，这是为人工智能代理提供的最先进支付基础设施。本技术手册旨在教您如何解锁代理 100% 的能力，使其能够在全球范围内自主运营、收费和投资。

🌎 1. 全球支持和多链架构

iAgent-Pay 不仅仅是一个本地 API；它是一个全球金融网关。我们的路由引擎允许您的代理在整个 Web3 生态系统中转移资金。

Ethereum (ETH): 高流动性，最高安全性。
Base (BASE): Coinbase的第二层，适合低费用。
Solana (SOL): 极速（每秒数千次交易）。

代理是“货币不可知论者”。内置货币包括：USDC, USDT, EURC（欧元）, CNHC（人民币）, GYEN（日元）, MXNT（比索）。

from iagent_pay import AgentPay

# 专注于亚洲市场的代理
agent = AgentPay(chain_name="BASE", default_stablecoin="CNHC")

⚡ 2. 核心功能

A. 自主支付 (x402)

tx_hash = agent.pay_token(
    recipient_address="0xProvider...", 
    amount=5.0
)
print(f"支付完成: {tx_hash}")

B. 开具发票 (Invoicing)

如果您的 AI 为客户完成工作，它可以生成“智能发票”。

invoice_id = agent.invoices.create_invoice(
    amount=25.0, 
    customer_address="0xClient...", 
    description="代码审计"
)

🛡️ 3. 安全内核 (Safety Kernel)

赋予软件财务自由需要严格的限制。在接触网络之前验证每笔交易。

每日限额： 防止流氓代理耗尽您的账户。
智能身份 (ERC-8004)： 代理在区块链上拥有“主权身份”，免受私钥盗窃。

# 每天最多限制 15 美元
agent = AgentPay(daily_limit=15.0)

# 铸造身份
identity = agent.identity.mint_soulbound_id("Bot", "0xOwner")

📈 4. 自主国库 (DeFi)

自动将多余的储蓄存入像 Aave v3 这样的全球协议，在您睡觉时产生收益。

# 保留 50 美元现金，其余投资
agent.yield_manager.auto_invest(buffer_usd=50.0)

企业模式： 对于提供代理即服务的公司，iAgent-Pay 支持“无 Gas”交易（Paymasters）。最终用户永远不需要购买加密货币即可操作。

📊 32. 企业级可视化控制面板 (只读模式)

为了在不影响透明度的前提下保证最高级别的网络安全，iAgent-Pay 引入了具有干净淡雅企业色彩的实时可视化监控面板。从安全设计的角度出发，此面板严格处于只读 (Read-Only) 模式。这防止了恶意人员通过 Web 界面篡改代理配置、修改安全内核 (Safety Kernel) 或窃取资金。

实时监控： 可视化原生 Gas 余额、USDC 稳定币余额以及 ERC-8004 许可状态。
网络与 RPC 遥测： 查看活动 RPC 节点、延迟指标和自动轮换次数。
安全内核保护栏： 显示每日限制、单笔交易阈值和白名单状态。
审计 JSON 导出： 支持一键下载标准 JSON 格式的完整代理状态报告。

🧪 33. 高级交互式模拟沙盒 (Sandbox)

为了便于演示和快速测试，iAgent-Pay 控制面板包含一个交互式 模拟沙盒环境。这允许开发人员和客户实时体验我们提供的所有自主功能，而无需冒着损失真实资金的风险，并获得完整的可视化遥测反馈。

初始模拟资金 $10,000.00 USDC： 每个模拟会话都以虚拟余额开始，该余额在每笔成功确认的交易中动态减少。
交互式控制开关： 启用或禁用 iAgent-Pay 的主要功能（安全内核、自动兑换、RPC 故障转移、无 Gas 赞助和人工循环/KYA），以观察代理如何应对网络故障和策略限制。
执行模式（单次 vs 循环）： 一键执行单次操作或触发连续 5 次交易的循环模拟。
交互式遥测控制台： 在模拟控制台中输出带有时间戳和颜色编码的详细日志。
模拟审计报告下载： 一键将所有模拟交易历史记录和参数导出为标准的 JSON 审计格式文件。
全局重置按钮： 瞬间恢复模拟到初始状态（$10,000 USDC 资金和进度归零）。

🔑 34. Ephemeral Zero-Custody Session Keys

Single Transaction Caps: Prevents the agent from sending individual payments above a pre-defined threshold.
Daily Cumulative Limits: Restricts total spending per day to prevent loss in case of logic bugs or infinite loops.
Time Expiry (TTL): Ephemeral keys automatically expire and become invalid after a designated duration.
Destination Whitelisting: The agent can only transfer funds to pre-approved addresses (by default, only back to the owner).

from iagent_pay import AgentPay
from iagent_pay.session_keys import SessionKeyManager

# 1. Load the master wallet owner
owner_account = wm.get_or_create_wallet("MySecurePassword123")

# 2. Create a restricted session key (TTL: 1 hour, daily cap: $100, single tx cap: $20)
session_key = SessionKeyManager.create_session(
    owner_account=owner_account,
    allowed_tokens=["USDC", "ETH"],
    daily_limit_usd=100.0,
    max_tx_usd=20.0,
    validity_seconds=3600,
    allowed_destinations=[owner_account.address, "0xVendorA..."]
)

# 3. Load the session key into the AgentPay instance
agent = AgentPay(chain_name="SEPOLIA")
agent.use_session_key(session_key)

# 4. Execute transaction autonomously (validated instantly against session bounds)
tx = agent.pay_token("0xVendorA...", amount=5.0, token="USDC")
print(f"Transaction successfully broadcasted: {tx}")

🏅 35. Compliance & Trust Verification (Know Your Agent - KYA)

W3C Standard DIDs: Unique DID documents issued in the format did:iagent:<hash>.
Trust Levels (TrustLevel): Dynamic levels ranging from UNKNOWN, VERIFIED, up to ELITE based on successful transactions.
Verifiable Credentials: Secure claims issued by controllers detailing agent capabilities and limits.
Compliance Blacklisting: Fraudulent or misbehaving DIDs are instantly blacklisted, blocking all incoming and outgoing payments.

from iagent_pay.kya import AgentIdentity, get_registry

# 1. Create a decentralized identity for the AI agent
identity = AgentIdentity.create(
    name="ResearcherBot-7",
    owner_address="0xAlice...",
    capabilities=["payments", "web_search"]
)
print(f"Agent DID: {identity.did}")

# 2. Register the agent in the KYA database
registry = get_registry()
registry.register(identity)

# 3. Automatically build reputation score through transaction history
registry.update_after_payment(identity.did, success=True, amount_usd=50.0)

# 4. Fetch KYA audit report and trust score
report = registry.get_full_report(identity.did)
print(f"Trust Level: {report['trust_level']} (ART Rep Score: {report['art_score']}/100)")

📘 आधिकारिक संदर्भ मैनुअल: iAgent-Pay (v8.5.0)

iAgent-Pay में आपका स्वागत है, जो AI एजेंट्स के लिए सबसे उन्नत भुगतान बुनियादी ढांचा है। यह तकनीकी मैनुअल आपको सिखाने के लिए डिज़ाइन किया गया है कि अपने एजेंट्स की 100% क्षमताओं को कैसे अनलॉक करें, जिससे वे वैश्विक स्तर पर स्वायत्त रूप से काम कर सकें, शुल्क ले सकें और निवेश कर सकें।

🌎 1. वैश्विक समर्थन और मल्टी-चेन आर्किटेक्चर

iAgent-Pay सिर्फ एक स्थानीय API नहीं है; यह एक वैश्विक वित्तीय गेटवे है। हमारा रूटिंग इंजन आपके एजेंट को पूरे Web3 इकोसिस्टम में पैसा ट्रांसफर करने की अनुमति देता है।

Ethereum (ETH): उच्च तरलता, अधिकतम सुरक्षा।
Base (BASE): कॉइनबेस का लेयर 2, कम शुल्क के लिए आदर्श।
Solana (SOL): अत्यधिक गति (हजारों TPS)।

एजेंट "मुद्रा अज्ञेयवादी" है। अंतर्निहित मुद्राओं में शामिल हैं: USDC, USDT, EURC (यूरो), CNHC (चीनी युआन), GYEN (जापानी येन), MXNT (मैक्सिकन पेसो)।

from iagent_pay import AgentPay

# एशियाई बाजार में विशेषज्ञ एजेंट
agent = AgentPay(chain_name="BASE", default_stablecoin="CNHC")

⚡ 2. मुख्य विशेषताएं

A. स्वायत्त भुगतान (x402)

tx_hash = agent.pay_token(
    recipient_address="0xProvider...", 
    amount=5.0
)
print(f"भुगतान पूरा हुआ: {tx_hash}")

B. चालान जनरेशन (Invoicing)

यदि आपका AI क्लाइंट के लिए काम करता है, तो यह एक "स्मार्ट इनवॉइस" उत्पन्न कर सकता है।

invoice_id = agent.invoices.create_invoice(
    amount=25.0, 
    customer_address="0xClient...", 
    description="कोड ऑडिट"
)

🛡️ 3. सेफ्टी कर्नेल (Safety Kernel)

सॉफ्टवेयर को वित्तीय स्वतंत्रता देने के लिए सख्त सीमाओं की आवश्यकता होती है। नेटवर्क को छूने से पहले हर लेन-देन को सत्यापित करता है।

दैनिक सीमाएँ: एक खराब एजेंट को आपके खाते को खाली करने से रोकता है।
स्मार्ट पहचान (ERC-8004): एजेंट्स की ब्लॉकचेन पर एक "संप्रभु पहचान" होती है, जो निजी कुंजी की चोरी से सुरक्षित है।

# प्रतिदिन अधिकतम $15 तक सीमित करें
agent = AgentPay(daily_limit=15.0)

# पहचान बनाएँ
identity = agent.identity.mint_soulbound_id("Bot", "0xOwner")

📈 4. स्वायत्त खजाना (DeFi)

अतिरिक्त बचत को स्वचालित रूप से Aave v3 जैसे वैश्विक प्रोटोकॉल में जमा करें, जिससे आपके सोते समय भी ब्याज उत्पन्न हो।

# $50 नकद रखें, बाकी निवेश करें
agent.yield_manager.auto_invest(buffer_usd=50.0)

एंटरप्राइज मोड: उन कंपनियों के लिए जो सेवा के रूप में एजेंट प्रदान करती हैं, iAgent-Pay "गैसलेस" (Paymasters) लेन-देन का समर्थन करता है। अंतिम उपयोगकर्ताओं को संचालित करने के लिए कभी भी क्रिप्टो खरीदने की आवश्यकता नहीं होती है।

📊 32. कॉर्पोरेट विज़ुअल डैशबोर्ड (केवल-पठन)

बिना पारदर्शिता से समझौता किए उच्चतम स्तर की साइबर सुरक्षा की गारंटी के लिए, iAgent-Pay एक साफ पेस्टल कॉर्पोरेट डिज़ाइन के साथ वास्तविक समय विज़ुअल मॉनिटरिंग डैशबोर्ड पेश करता है। सुरक्षा डिज़ाइन के अनुसार, यह पैनल **कड़ाई से केवल-पठन (Read-Only)** है। यह दुर्भावनापूर्ण अभिनेताओं को वेब इंटरफेस के माध्यम से एजेंट कॉन्फ़िगरेशन को बदलने, सेफ्टी कर्नेल को संशोधित करने या धन निकालने से रोकता है

वास्तविक समय मॉनिटरिंग: मूल गैस संतुलन, USDC स्थिर सिक्का शेष और ERC-8004 लाइसेंस स्थिति की कल्पना करें।
नेटवर्क और RPC टेलीमेट्री: सक्रिय RPC नोड्स, विलंबता मेट्रिक्स और कुल ऑटो-रोटेशन देखें।
सेफ्टी कर्नेल सीमाएं: दैनिक सीमाएं, लेनदेन सीमाएं और श्वेतसूची स्थिति प्रदर्शित करता है।
ऑडिट JSON निर्यातक: एक क्लिक में मानक JSON प्रारूप में पूर्ण एजेंट स्थिति रिपोर्ट डाउनलोड करने की अनुमति देता है।

🧪 33. उन्नत इंटरएक्टिव सिमुलेशन सैंडबॉक्स (Sandbox)

प्रदर्शन और त्वरित परीक्षण उद्देश्यों के लिए, iAgent-Pay डैशबोर्ड पर एक इंटरैक्टिव सिमुलेशन सैंडबॉक्स वातावरण प्रदान करता है। यह डेवलपर्स और ग्राहकों को वास्तविक धन को जोखिम में डाले बिना वास्तविक समय में हमारी सभी स्वायत्त सुविधाओं का अनुभव करने की अनुमति देता है।

$10,000.00 USDC का प्रारंभिक सिमुलेटेड फंड: प्रत्येक सिमुलेशन सत्र एक काल्पनिक शेष राशि के साथ शुरू होता है जो प्रत्येक सफल लेनदेन के साथ गतिशील रूप से घटता है।
इंटरएक्टिव फीचर टॉगल: iAgent-Pay की प्रमुख विशेषताओं (सेफ्टी कर्नेल, ऑटो-स्वैप, RPC फेलओवर, गैसलेस प्रायोजक, और ह्यूमन-इन-द-लूप) को सक्षम या अक्षम करें ताकि यह देखा जा सके कि एजेंट विफलताओं और नीति सीमाओं पर कैसे प्रतिक्रिया करता है।
निष्पादन मोड (एकल बनाम लूप): एक क्लिक के साथ एकल क्रिया चलाएं या लगातार 5 लेनदेन के लूप सिमुलेशन को ट्रिगर करें।
इंटरएक्टिव टेलीमेट्री कंसोल: सिमुलेटेड कंसोल में टाइमस्टैम्प और रंग-कोडित विस्तृत लॉग प्रदर्शित करता है।
सिमुलेशन ऑडिट रिपोर्ट डाउनलोड: एक क्लिक में मानक JSON प्रारूप में सभी सिम्युलेटेड लेनदेन इतिहास को निर्यात करने की अनुमति देता है।
ग्लोबल रीसेट बटन: सिमुलेशन को तुरंत उसकी प्रारंभिक स्थिति ($10,000 USDC पूंजी और शून्य प्रगति) में वापस लाता है।

🔑 34. Ephemeral Zero-Custody Session Keys

Single Transaction Caps: Prevents the agent from sending individual payments above a pre-defined threshold.
Daily Cumulative Limits: Restricts total spending per day to prevent loss in case of logic bugs or infinite loops.
Time Expiry (TTL): Ephemeral keys automatically expire and become invalid after a designated duration.
Destination Whitelisting: The agent can only transfer funds to pre-approved addresses (by default, only back to the owner).

from iagent_pay import AgentPay
from iagent_pay.session_keys import SessionKeyManager

# 1. Load the master wallet owner
owner_account = wm.get_or_create_wallet("MySecurePassword123")

# 2. Create a restricted session key (TTL: 1 hour, daily cap: $100, single tx cap: $20)
session_key = SessionKeyManager.create_session(
    owner_account=owner_account,
    allowed_tokens=["USDC", "ETH"],
    daily_limit_usd=100.0,
    max_tx_usd=20.0,
    validity_seconds=3600,
    allowed_destinations=[owner_account.address, "0xVendorA..."]
)

# 3. Load the session key into the AgentPay instance
agent = AgentPay(chain_name="SEPOLIA")
agent.use_session_key(session_key)

# 4. Execute transaction autonomously (validated instantly against session bounds)
tx = agent.pay_token("0xVendorA...", amount=5.0, token="USDC")
print(f"Transaction successfully broadcasted: {tx}")

🏅 35. Compliance & Trust Verification (Know Your Agent - KYA)

W3C Standard DIDs: Unique DID documents issued in the format did:iagent:<hash>.
Trust Levels (TrustLevel): Dynamic levels ranging from UNKNOWN, VERIFIED, up to ELITE based on successful transactions.
Verifiable Credentials: Secure claims issued by controllers detailing agent capabilities and limits.
Compliance Blacklisting: Fraudulent or misbehaving DIDs are instantly blacklisted, blocking all incoming and outgoing payments.

from iagent_pay.kya import AgentIdentity, get_registry

# 1. Create a decentralized identity for the AI agent
identity = AgentIdentity.create(
    name="ResearcherBot-7",
    owner_address="0xAlice...",
    capabilities=["payments", "web_search"]
)
print(f"Agent DID: {identity.did}")

# 2. Register the agent in the KYA database
registry = get_registry()
registry.register(identity)

# 3. Automatically build reputation score through transaction history
registry.update_after_payment(identity.did, success=True, amount_usd=50.0)

# 4. Fetch KYA audit report and trust score
report = registry.get_full_report(identity.did)
print(f"Trust Level: {report['trust_level']} (ART Rep Score: {report['art_score']}/100)")

📘 دليل المرجع الرسمي: iAgent-Pay (v8.5.0)

مرحبًا بك في iAgent-Pay، البنية التحتية للمدفوعات الأكثر تقدمًا لوكلاء الذكاء الاصطناعي. تم تصميم هذا الدليل الفني لتعليمك كيفية فتح 100٪ من قدرات وكلائك، مما يسمح لهم بالعمل والتحصيل والاستثمار بشكل مستقل على نطاق عالمي.

🌎 1. الدعم العالمي وبنية السلاسل المتعددة

iAgent-Pay ليست مجرد واجهة برمجة تطبيقات محلية؛ إنها بوابة مالية عالمية. يسمح محرك التوجيه الخاص بنا لوكيلك بنقل الأموال عبر نظام Web3 بالكامل.

Ethereum (ETH): سيولة عالية، أقصى أمان.
Base (BASE): الطبقة الثانية من Coinbase، مثالية للرسوم المنخفضة.
Solana (SOL): سرعة فائقة (آلاف المعاملات في الثانية).

الوكيل "لا يعتمد على عملة معينة". العملات المدمجة تشمل: USDC, USDT, EURC (اليورو), CNHC (اليوان الصيني), GYEN (الين الياباني), MXNT (البيزو المكسيكي).

from iagent_pay import AgentPay

# وكيل يركز على الأسواق الآسيوية
agent = AgentPay(chain_name="BASE", default_stablecoin="CNHC")

⚡ 2. الميزات الرئيسية

أ. الدفع الذاتي (x402)

tx_hash = agent.pay_token(
    recipient_address="0xProvider...", 
    amount=5.0
)
print(f"اكتمل الدفع: {tx_hash}")

ب. إصدار الفواتير (Invoicing)

إذا كان الذكاء الاصطناعي الخاص بك يكمل عملاً لعميل، فيمكنه إنشاء "فاتورة ذكية".

invoice_id = agent.invoices.create_invoice(
    amount=25.0, 
    customer_address="0xClient...", 
    description="تدقيق الكود"
)

🛡️ 3. نواة الأمان (Safety Kernel)

منح البرمجيات الحرية المالية يتطلب قيودًا صارمة. يتم التحقق من كل معاملة قبل إرسالها إلى الشبكة.

الحدود اليومية: يمنع الوكيل المارق من استنزاف حسابك.
الهوية الذكية (ERC-8004): يمتلك الوكلاء "هوية سيادية" على البلوكشين، محمية من سرقة المفاتيح الخاصة.

# حد أقصى 15 دولارًا في اليوم
agent = AgentPay(daily_limit=15.0)

# صك الهوية
identity = agent.identity.mint_soulbound_id("Bot", "0xOwner")

📈 4. الخزانة المستقلة (DeFi)

قم بإيداع المدخرات الزائدة تلقائيًا في بروتوكولات عالمية مثل Aave v3 لتوليد عوائد أثناء نومك.

# احتفظ بـ 50 دولارًا نقدًا واستثمر الباقي
agent.yield_manager.auto_invest(buffer_usd=50.0)

وضع المؤسسات: بالنسبة للشركات التي تقدم وكلاء كخدمة، يدعم iAgent-Pay المعاملات "الخالية من الغاز" (Paymasters). لا يحتاج المستخدمون النهائيون أبدًا إلى شراء عملات مشفرة للتشغيل.

📊 32. لوحة التحكم المرئية للمؤسسات (للقراءة فقط)

لضمان أعلى مستويات الأمن السيبراني دون المساومة на الشفافية، تقدم iAgent-Pay لوحة مراقبة مرئية في الوقت الفعلي بتصميم ألوان مهدئة للمؤسسات. وتصميمًا للأمان، تكون هذه اللوحة **للقراءة فقط (Read-Only) بشكل صارم**. هذا يمنع الجهات الخبيثة من تغيير تكوينات الوكيل، أو تعديل نواة الأمان (Safety Kernel)، أو سحب الأموال عبر واجهة الويب.

المراقبة الفورية: تصور رصيد الغاز الأصلي، ورصيد عملة USDC المستقرة، وحالة ترخيص ERC-8004.
قياسات الشبكة والـ RPC: عرض عقد RPC النشطة، ومقاييس زمن الانتقال، وإجمالي التدويرات التلقائية.
حدود نواة الأمان: عرض الحدود اليومية، وحدود المعاملات الفردية، وحالة القائمة البيضاء.
مستخرج تقرير التدقيق JSON: يسمح بتنزيل تقارير حالة الوكيل الكاملة بتنسيق JSON قياسي بنقرة واحدة.

🧪 33. بيئة محاكاة تفاعلية متقدمة (Sandbox)

لأغراض العرض والاختبار السريع، تتضمن لوحة معلومات iAgent-Pay بيئة محاكاة تفاعلية (Sandbox). يتيح ذلك للمطورين والعملاء تجربة جميع الميزات المستقلة في الوقت الفعلي دون المخاطرة بأموال حقيقية.

رصيد محاكاة أولي بقيمة 10,000.00 دولار USDC: تبدأ كل جلسة محاكاة برصيد افتراضي يتناقص ديناميكيًا مع كل معاملة ناجحة.
مفاتيح الميزات التفاعلية: قم بتمكين أو تعطيل الميزات الرئيسية لـ iAgent-Pay (نواة الأمان، الصرف التلقائي، التدوير التلقائي لـ RPC، الرعاية بدون غاز، والحلقة البشرية) لمراقبة استجابة الوكيل للمشكلات والقيود السياسية.
أوضاع التنفيذ (فردي مقابل حلقة): تشغيل إجراء واحد أو بدء محاكاة حلقة من 5 معاملات متتالية بنقرة واحدة.
콘솔 تفاعلي للقياس عن بعد: يعرض سجلات مفصلة بترميز لوني وطوابع زمنية في وحدة تحكم المحاكاة.
تنزيل تقرير تدقيق المحاكاة: يسمح بتصدير تاريخ المعاملات والمحاكاة الكامل بتنسيق JSON قياسي بنقرة واحدة.
زر إعادة الضبط العالمي: يعيد المحاكاة فورًا إلى وضعها الافتراضي (رصيد 10,000 دولار USDC وصفر تقدم).

🔑 34. Ephemeral Zero-Custody Session Keys

Single Transaction Caps: Prevents the agent from sending individual payments above a pre-defined threshold.
Daily Cumulative Limits: Restricts total spending per day to prevent loss in case of logic bugs or infinite loops.
Time Expiry (TTL): Ephemeral keys automatically expire and become invalid after a designated duration.
Destination Whitelisting: The agent can only transfer funds to pre-approved addresses (by default, only back to the owner).

from iagent_pay import AgentPay
from iagent_pay.session_keys import SessionKeyManager

# 1. Load the master wallet owner
owner_account = wm.get_or_create_wallet("MySecurePassword123")

# 2. Create a restricted session key (TTL: 1 hour, daily cap: $100, single tx cap: $20)
session_key = SessionKeyManager.create_session(
    owner_account=owner_account,
    allowed_tokens=["USDC", "ETH"],
    daily_limit_usd=100.0,
    max_tx_usd=20.0,
    validity_seconds=3600,
    allowed_destinations=[owner_account.address, "0xVendorA..."]
)

# 3. Load the session key into the AgentPay instance
agent = AgentPay(chain_name="SEPOLIA")
agent.use_session_key(session_key)

# 4. Execute transaction autonomously (validated instantly against session bounds)
tx = agent.pay_token("0xVendorA...", amount=5.0, token="USDC")
print(f"Transaction successfully broadcasted: {tx}")

🏅 35. Compliance & Trust Verification (Know Your Agent - KYA)

W3C Standard DIDs: Unique DID documents issued in the format did:iagent:<hash>.
Trust Levels (TrustLevel): Dynamic levels ranging from UNKNOWN, VERIFIED, up to ELITE based on successful transactions.
Verifiable Credentials: Secure claims issued by controllers detailing agent capabilities and limits.
Compliance Blacklisting: Fraudulent or misbehaving DIDs are instantly blacklisted, blocking all incoming and outgoing payments.

from iagent_pay.kya import AgentIdentity, get_registry

# 1. Create a decentralized identity for the AI agent
identity = AgentIdentity.create(
    name="ResearcherBot-7",
    owner_address="0xAlice...",
    capabilities=["payments", "web_search"]
)
print(f"Agent DID: {identity.did}")

# 2. Register the agent in the KYA database
registry = get_registry()
registry.register(identity)

# 3. Automatically build reputation score through transaction history
registry.update_after_payment(identity.did, success=True, amount_usd=50.0)

# 4. Fetch KYA audit report and trust score
report = registry.get_full_report(identity.did)
print(f"Trust Level: {report['trust_level']} (ART Rep Score: {report['art_score']}/100)")

📘 Manual de Referência Oficial: iAgent-Pay (v8.5.0)

Bem-vindo ao iAgent-Pay, a infraestrutura de pagamentos mais avançada para Agentes de Inteligência Artificial. Este manual técnico foi projetado para ensinar você a desbloquear 100% das capacidades dos seus agentes, permitindo-lhes operar, cobrar e investir autonomamente em escala global.

🌎 1. Suporte Global e Arquitetura Multi-Chain

O iAgent-Pay não é apenas uma API local; é um gateway financeiro global. Nosso mecanismo de roteamento permite que seu agente mova fundos por todo o ecossistema Web3.

Ethereum (ETH): Alta liquidez, máxima segurança.
Base (BASE): Layer 2 da Coinbase, ideal para taxas baixas.
Solana (SOL): Velocidade extrema (milhares de transações por segundo).

O agente é "agnóstico à moeda". Moedas integradas incluem: USDC, USDT, EURC (Euro), CNHC (Yuan chinês), GYEN (Iene japonês), MXNT (Peso mexicano).

from iagent_pay import AgentPay

# Agente com foco no mercado asiático
agent = AgentPay(chain_name="BASE", default_stablecoin="CNHC")

⚡ 2. Recursos Principais

A. Pagamentos Autônomos (x402)

tx_hash = agent.pay_token(
    recipient_address="0xProvider...", 
    amount=5.0
)
print(f"Pagamento concluído: {tx_hash}")

B. Emissão de Faturas (Invoicing)

Se a sua IA conclui um trabalho para um cliente, ela pode gerar uma "fatura inteligente".

invoice_id = agent.invoices.create_invoice(
    amount=25.0, 
    customer_address="0xClient...", 
    description="Auditoria de Código"
)

🛡️ 3. Kernel de Segurança (Safety Kernel)

Dar liberdade financeira a softwares exige limites rígidos. Verifica cada transação antes de tocar na rede.

Limites Diários: Impede que um agente corrompido drene sua conta.
Identidade Inteligente (ERC-8004): Agentes possuem uma "identidade soberana" na blockchain, protegida contra roubo de chaves privadas.

# Limita a no máximo $15 por dia
agent = AgentPay(daily_limit=15.0)

# Emitir identidade
identity = agent.identity.mint_soulbound_id("Bot", "0xOwner")

📈 4. Tesouraria Autônoma (DeFi)

Deposite automaticamente economias excedentes em protocolos globais como Aave v3, gerando rendimento enquanto você dorme.

# Mantém $50 em caixa, investe o restante
agent.yield_manager.auto_invest(buffer_usd=50.0)

Modo Enterprise: Para empresas que fornecem agentes como serviço, o iAgent-Pay suporta transações "gasless" (Paymasters). Os usuários finais nunca precisam comprar cripto para operar.

📊 32. Painel Visual Corporativo (Apenas Leitura)

Para garantir os mais altos níveis de segurança cibernética sem comprometer a transparência, o iAgent-Pay apresenta um painel de monitoramento visual em tempo real com cores pastéis corporativas limpas. Por design de segurança, este painel é **estritamente de apenas leitura (Read-Only)**. Isso impede que agentes maliciosos alterem a configuração do agente, modifiquem o Kernel de Segurança (Safety Kernel) ou retirem fundos através da interface web.

Monitoramento em Tempo Real: Visualize o saldo nativo de gás, o saldo de USDC e o status de licenciamento ERC-8004.
Telemetria de Rede e RPC: Visualize nós RPC ativos, métricas de latência e total de rotações automáticas.
Limites do Kernel de Segurança: Exibe limites diários, limites de transações individuais e status de lista de permissões.
Exportador de Auditoria JSON: Permite baixar relatórios completos do estado do agente em formato JSON padrão em um clique.

🧪 33. Sandbox de Simulação Interativa Avançada (Sandbox)

Para fins de demonstração e teste rápido, o painel do iAgent-Pay inclui um ambiente interativo de sandbox de simulação. Isso permite que desenvolvedores e clientes experimentem todos os nossos recursos autônomos em tempo real, sem arriscar fundos reais.

Saldo Simulado Inicial de $10.000,00 USDC: Cada sessão de simulação começa com um saldo fictício que diminui dinamicamente a cada transação bem-sucedida.
Controles de Recursos Interativos: Habilite ou desabilite recursos principais do iAgent-Pay (Kernel de Segurança, Auto-Swap, Failover de RPC, Patrocínio Gasless e Human-in-the-loop) para observar como o agente responde a falhas e limites de política.
Modo de Execução (Único vs Loop): Execute uma única ação ou acione uma simulação em loop de 5 transações contínuas com um clique.
Console de Telemetria Interativo: Exibe logs detalhados coloridos e com carimbo de data/hora no console simulado.
Download de Relatório de Auditoria: Exporta o histórico completo de transações simuladas em formato JSON padrão com um clique.
Botão de Reset Global: Retorna a simulação instantaneamente ao estado inicial ($10.000 USDC e progresso zero).

🔑 34. Ephemeral Zero-Custody Session Keys

Single Transaction Caps: Prevents the agent from sending individual payments above a pre-defined threshold.
Daily Cumulative Limits: Restricts total spending per day to prevent loss in case of logic bugs or infinite loops.
Time Expiry (TTL): Ephemeral keys automatically expire and become invalid after a designated duration.
Destination Whitelisting: The agent can only transfer funds to pre-approved addresses (by default, only back to the owner).

from iagent_pay import AgentPay
from iagent_pay.session_keys import SessionKeyManager

# 1. Load the master wallet owner
owner_account = wm.get_or_create_wallet("MySecurePassword123")

# 2. Create a restricted session key (TTL: 1 hour, daily cap: $100, single tx cap: $20)
session_key = SessionKeyManager.create_session(
    owner_account=owner_account,
    allowed_tokens=["USDC", "ETH"],
    daily_limit_usd=100.0,
    max_tx_usd=20.0,
    validity_seconds=3600,
    allowed_destinations=[owner_account.address, "0xVendorA..."]
)

# 3. Load the session key into the AgentPay instance
agent = AgentPay(chain_name="SEPOLIA")
agent.use_session_key(session_key)

# 4. Execute transaction autonomously (validated instantly against session bounds)
tx = agent.pay_token("0xVendorA...", amount=5.0, token="USDC")
print(f"Transaction successfully broadcasted: {tx}")

🏅 35. Compliance & Trust Verification (Know Your Agent - KYA)

W3C Standard DIDs: Unique DID documents issued in the format did:iagent:<hash>.
Trust Levels (TrustLevel): Dynamic levels ranging from UNKNOWN, VERIFIED, up to ELITE based on successful transactions.
Verifiable Credentials: Secure claims issued by controllers detailing agent capabilities and limits.
Compliance Blacklisting: Fraudulent or misbehaving DIDs are instantly blacklisted, blocking all incoming and outgoing payments.

from iagent_pay.kya import AgentIdentity, get_registry

# 1. Create a decentralized identity for the AI agent
identity = AgentIdentity.create(
    name="ResearcherBot-7",
    owner_address="0xAlice...",
    capabilities=["payments", "web_search"]
)
print(f"Agent DID: {identity.did}")

# 2. Register the agent in the KYA database
registry = get_registry()
registry.register(identity)

# 3. Automatically build reputation score through transaction history
registry.update_after_payment(identity.did, success=True, amount_usd=50.0)

# 4. Fetch KYA audit report and trust score
report = registry.get_full_report(identity.did)
print(f"Trust Level: {report['trust_level']} (ART Rep Score: {report['art_score']}/100)")

📘 Официальное справочное руководство: iAgent-Pay (v8.5.0)

Добро пожаловать в iAgent-Pay, самую передовую платежную инфраструктуру для агентов искусственного интеллекта. Это техническое руководство разработано, чтобы научить вас раскрывать 100% возможностей ваших агентов, позволяя им автономно работать, взимать плату и инвестировать в глобальном масштабе.

🌎 1. Глобальная поддержка и мультичейн-архитектура

iAgent-Pay — это не просто локальный API; это глобальный финансовый шлюз. Наш механизм маршрутизации позволяет вашему агенту перемещать средства по всей экосистеме Web3.

Ethereum (ETH): Высокая ликвидность, максимальная безопасность.
Base (BASE): Layer 2 от Coinbase, идеально подходит для низких комиссий.
Solana (SOL): Экстремальная скорость (тысячи транзакций в секунду).

Агент не зависит от конкретной монеты. Поддерживаемые валюты включают: USDC, USDT, EURC (Евро), CNHC (Китайский юань), GYEN (Японская иена), MXNT (Мексиканское песо).

from iagent_pay import AgentPay

# Агент с фокусом на азиатский рынок
agent = AgentPay(chain_name="BASE", default_stablecoin="CNHC")

⚡ 2. Ключевые особенности

A. Автономные платежи (x402)

tx_hash = agent.pay_token(
    recipient_address="0xProvider...", 
    amount=5.0
)
print(f"Платеж выполнен: {tx_hash}")

B. Выставление счетов (Invoicing)

Если ваш ИИ выполняет работу для клиента, он может создать «умный счет».

invoice_id = agent.invoices.create_invoice(
    amount=25.0, 
    customer_address="0xClient...", 
    description="Аудит кода"
)

🛡️ 3. Ядро безопасности (Safety Kernel)

Предоставление программному обеспечению финансовой свободы требует строгих ограничений. Проверяет каждую транзакцию перед отправкой в сеть.

Суточные лимиты: Предотвращает опустошение вашего счета неисправным агентом.
Смарт-идентификация (ERC-8004): Агенты обладают суверенной идентичностью на блокчейне, защищенной от кражи приватных ключей.

# Ограничение до $15 в день
agent = AgentPay(daily_limit=15.0)

# Выпуск идентификатора
identity = agent.identity.mint_soulbound_id("Bot", "0xOwner")

📈 4. Автономное казначейство (DeFi)

Автоматически вносите избыточные сбережения в глобальные протоколы, такие как Aave v3, получая доход, пока вы спите.

# Хранить $50 наличными, остальное инвестировать
agent.yield_manager.auto_invest(buffer_usd=50.0)

Корпоративный режим: Для компаний, предоставляющих агентов как услугу, iAgent-Pay поддерживает транзакции без комиссии за газ (Paymasters). Конечным пользователям не нужно покупать криптовалюту.

📊 32. Корпоративная визуальная панель управления (только для чтения)

Чтобы гарантировать высочайший уровень кибербезопасности без ущерба для прозрачности, iAgent-Pay представляет визуальную панель мониторинга в реальном времени с чистыми пастельными корпоративными цветами. В целях безопасности эта панель **строго работает в режиме "только для чтения" (Read-Only)**. Это предотвращает изменение конфигурации агента, модификацию ядра безопасности (Safety Kernel) или вывод средств злоумышленниками через веб-интерфейс.

Мониторинг в реальном времени: Визуализируйте баланс нативного газа, баланс стейблкоина USDC и статус лицензирования ERC-8004.
Телеметрия сети и RPC: Просматривайте активные узлы RPC, метрики задержки и общее количество автоматических ротаций.
Границы ядра безопасности: Отображает суточные лимиты, лимиты на одну транзакцию и статус белого списка.
Экспорт аудита в JSON: Позволяет загружать полные отчеты о состоянии агента в стандартном формате JSON в один клик.

🧪 33. Продвинутая интерактивная песочница симуляции (Sandbox)

Для демонстрации и быстрого тестирования панель управления iAgent-Pay включает интерактивную симуляционную песочницу. Это позволяет разработчикам и клиентам тестировать все наши автономные функции в реальном времени без риска потери реальных средств.

Начальный баланс $10 000,00 USDC: Каждая сессия симуляции начинается с виртуального баланса, который динамически уменьшается с каждой успешной транзакцией.
Интерактивные переключатели функций: Включайте или отключайте ключевые функции iAgent-Pay (ядро безопасности, авто-своп, RPC-failover, спонсорство газа и ручное подтверждение), чтобы увидеть реакцию агента на сбои и ограничения.
Режим выполнения (Одиночный против Цикла): Запуск одиночного действия или симуляция непрерывного цикла из 5 транзакций в один клик.
Интерактивная консоль телеметрии: Отображает подробные логи с цветовой кодировкой и метками времени в симуляционной консоли.
Скачивание отчета симуляции: Экспортирует полную историю транзакций симуляции в стандартный формат JSON в один клик.
Глобальная кнопка сброса: Мгновенно возвращает симуляцию в исходное состояние ($10 000 USDC и нулевой прогресс).

🔑 34. Ephemeral Zero-Custody Session Keys

Single Transaction Caps: Prevents the agent from sending individual payments above a pre-defined threshold.
Daily Cumulative Limits: Restricts total spending per day to prevent loss in case of logic bugs or infinite loops.
Time Expiry (TTL): Ephemeral keys automatically expire and become invalid after a designated duration.
Destination Whitelisting: The agent can only transfer funds to pre-approved addresses (by default, only back to the owner).

from iagent_pay import AgentPay
from iagent_pay.session_keys import SessionKeyManager

# 1. Load the master wallet owner
owner_account = wm.get_or_create_wallet("MySecurePassword123")

# 2. Create a restricted session key (TTL: 1 hour, daily cap: $100, single tx cap: $20)
session_key = SessionKeyManager.create_session(
    owner_account=owner_account,
    allowed_tokens=["USDC", "ETH"],
    daily_limit_usd=100.0,
    max_tx_usd=20.0,
    validity_seconds=3600,
    allowed_destinations=[owner_account.address, "0xVendorA..."]
)

# 3. Load the session key into the AgentPay instance
agent = AgentPay(chain_name="SEPOLIA")
agent.use_session_key(session_key)

# 4. Execute transaction autonomously (validated instantly against session bounds)
tx = agent.pay_token("0xVendorA...", amount=5.0, token="USDC")
print(f"Transaction successfully broadcasted: {tx}")

🏅 35. Compliance & Trust Verification (Know Your Agent - KYA)

W3C Standard DIDs: Unique DID documents issued in the format did:iagent:<hash>.
Trust Levels (TrustLevel): Dynamic levels ranging from UNKNOWN, VERIFIED, up to ELITE based on successful transactions.
Verifiable Credentials: Secure claims issued by controllers detailing agent capabilities and limits.
Compliance Blacklisting: Fraudulent or misbehaving DIDs are instantly blacklisted, blocking all incoming and outgoing payments.

from iagent_pay.kya import AgentIdentity, get_registry

# 1. Create a decentralized identity for the AI agent
identity = AgentIdentity.create(
    name="ResearcherBot-7",
    owner_address="0xAlice...",
    capabilities=["payments", "web_search"]
)
print(f"Agent DID: {identity.did}")

# 2. Register the agent in the KYA database
registry = get_registry()
registry.register(identity)

# 3. Automatically build reputation score through transaction history
registry.update_after_payment(identity.did, success=True, amount_usd=50.0)

# 4. Fetch KYA audit report and trust score
report = registry.get_full_report(identity.did)
print(f"Trust Level: {report['trust_level']} (ART Rep Score: {report['art_score']}/100)")

📘 公式リファレンスマニュアル: iAgent-Pay (v8.5.0)

iAgent-Pay へようこそ。これは AI エージェント向けに設計された最先端の決済インフラストラクチャです。この技術マニュアルは、エージェントの能力を 100% 引き出し、グローバル規模で自律的な運用、課金、および投資を行えるようにするためのものです。

🌎 1. グローバルサポートとマルチチェーンアーキテクチャ

iAgent-Pay は単なるローカル API ではありません。グローバルな金融ゲートウェイです。ルーティングエンジンにより、エージェントは Web3 エコシステム全体で資金を移動できます。

Ethereum (ETH): 高い流動性と最高のセキュリティ。
Base (BASE): 低コストな運用のための Coinbase の Layer 2。
Solana (SOL): 極めて高速（毎秒数千トランザクション）。

エージェントは通貨に依存しません。対応通貨：USDC, USDT, EURC (ユーロ), CNHC (オフショア人民元), GYEN (日本円), MXNT (メキシコペソ)。

from iagent_pay import AgentPay

# アジア市場に特化したエージェント
agent = AgentPay(chain_name="BASE", default_stablecoin="CNHC")

⚡ 2. 主な機能

A. 自律的な支払い (x402)

tx_hash = agent.pay_token(
    recipient_address="0xProvider...", 
    amount=5.0
)
print(f"支払い完了: {tx_hash}")

B. 請求書生成 (Invoicing)

AI がクライアント向けのタスクを完了した際、「スマート請求書」を作成できます。

invoice_id = agent.invoices.create_invoice(
    amount=25.0, 
    customer_address="0xClient...", 
    description="コード監査"
)

🛡️ 3. セーフティカーネル (Safety Kernel)

ソフトウェアに資金の自由を与えるには、厳格な制限が必要です。ネットワークに送信する前にすべてのトランザクションを検証します。

日限額制限： 異常なエージェントがアカウントを空にするのを防ぎます。
スマートID (ERC-8004)： エージェントはブロックチェーン上で主権IDを持ち、秘密鍵の盗難から保護されます。

# 1日あたり最大15ドルに制限
agent = AgentPay(daily_limit=15.0)

# IDをミント
identity = agent.identity.mint_soulbound_id("Bot", "0xOwner")

📈 4. 自律的トレジャリー (DeFi)

余剰資金を Aave v3 のようなグローバルプロトコルに自動預入し、眠っている間にも利回りを生成します。

# 50ドルを手元に残し、残りを投資
agent.yield_manager.auto_invest(buffer_usd=50.0)

エンタープライズモード: エージェントをサービスとして提供する企業向けに、ガスレス取引（Paymasters）をサポート。エンドユーザーが暗号通貨を購入する必要はありません。

📊 32. 企業向けビジュアルダッシュボード (読み取り専用)

透明性を損なうことなく最高水準のサイバーセキュリティを保証するため、iAgent-Pay は落ち着いたパステル調の企業向けリアルタイムビジュアル監視ダッシュボードを導入しています。セキュリティ設計上、このパネルは**厳格に読み取り専用 (Read-Only)**です。これにより、悪意のある攻撃者がウェブインターフェースを通じてエージェントの設定を変更したり、セーフティカーネル (Safety Kernel) を書き換えたり、資金を盗み出したりすることを完全に防止します。

リアルタイム監視： ネイティブガス残高、USDC残高、およびERC-8004ライセンスステータスを可視化。
ネットワークおよびRPCテレメトリ： アクティブなRPCノード、遅延メトリクス、自動ローテーション回数を表示。
セーフティカーネルのガードレール： 1日の上限、個別トランザクション閾値、ホワイトリスト状況を表示。
JSON監査エクスポート： 1クリックで標準JSONフォーマットの完全なエージェントステータスレポートをダウンロード。

🧪 33. 高度なインタラクティブシミュレーションサンドボックス (Sandbox)

デモおよび迅速なテストのため、iAgent-Pay ダッシュボードはインタラクティブなシミュレーションサンドボックス環境を提供します。これにより、開発者やクライアントはリアルマネーを危険にさらすことなく、すべての自律機能をリアルタイムで体験できます。

初期模擬資金 $10,000.00 USDC： シミュレーションは仮の残高から開始され、トランザクションが成功するたびに動的に減少します。
インタラクティブ機能トグル： セーフティカーネル、自動スワップ、RPCフェイルオーバー、ガスレススポンサー、Human-in-the-loop などの主要機能をオン/オフにし、障害に対するエージェントの挙動を観察できます。
実行モード（シングル vs ループ）： 1回のトランザクションの実行、または5回連続した自動取引シミュレーションを1クリックで実行。
インタラクティブログコンソール： タイムスタンプと色分けされた詳細なログを出力。
シミュレーション監査レポートダウンロード： 1クリックで模擬取引履歴を標準JSON形式でエクスポート。
グローバルリセットボタン： シミュレーションを即座に初期状態（$10,000 USDCの資金とゼロ進捗）にリセット。

🔑 34. Ephemeral Zero-Custody Session Keys

Single Transaction Caps: Prevents the agent from sending individual payments above a pre-defined threshold.
Daily Cumulative Limits: Restricts total spending per day to prevent loss in case of logic bugs or infinite loops.
Time Expiry (TTL): Ephemeral keys automatically expire and become invalid after a designated duration.
Destination Whitelisting: The agent can only transfer funds to pre-approved addresses (by default, only back to the owner).

from iagent_pay import AgentPay
from iagent_pay.session_keys import SessionKeyManager

# 1. Load the master wallet owner
owner_account = wm.get_or_create_wallet("MySecurePassword123")

# 2. Create a restricted session key (TTL: 1 hour, daily cap: $100, single tx cap: $20)
session_key = SessionKeyManager.create_session(
    owner_account=owner_account,
    allowed_tokens=["USDC", "ETH"],
    daily_limit_usd=100.0,
    max_tx_usd=20.0,
    validity_seconds=3600,
    allowed_destinations=[owner_account.address, "0xVendorA..."]
)

# 3. Load the session key into the AgentPay instance
agent = AgentPay(chain_name="SEPOLIA")
agent.use_session_key(session_key)

# 4. Execute transaction autonomously (validated instantly against session bounds)
tx = agent.pay_token("0xVendorA...", amount=5.0, token="USDC")
print(f"Transaction successfully broadcasted: {tx}")

🏅 35. Compliance & Trust Verification (Know Your Agent - KYA)

W3C Standard DIDs: Unique DID documents issued in the format did:iagent:<hash>.
Trust Levels (TrustLevel): Dynamic levels ranging from UNKNOWN, VERIFIED, up to ELITE based on successful transactions.
Verifiable Credentials: Secure claims issued by controllers detailing agent capabilities and limits.
Compliance Blacklisting: Fraudulent or misbehaving DIDs are instantly blacklisted, blocking all incoming and outgoing payments.

from iagent_pay.kya import AgentIdentity, get_registry

# 1. Create a decentralized identity for the AI agent
identity = AgentIdentity.create(
    name="ResearcherBot-7",
    owner_address="0xAlice...",
    capabilities=["payments", "web_search"]
)
print(f"Agent DID: {identity.did}")

# 2. Register the agent in the KYA database
registry = get_registry()
registry.register(identity)

# 3. Automatically build reputation score through transaction history
registry.update_after_payment(identity.did, success=True, amount_usd=50.0)

# 4. Fetch KYA audit report and trust score
report = registry.get_full_report(identity.did)
print(f"Trust Level: {report['trust_level']} (ART Rep Score: {report['art_score']}/100)")

📘 Offizielles Referenzhandbuch: iAgent-Pay (v8.5.0)

Willkommen bei iAgent-Pay, der fortschrittlichsten Zahlungsinfrastruktur für KI-Agenten. Dieses technische Handbuch führt Sie in die Freischaltung von 100 % der Fähigkeiten Ihrer Agenten ein, sodass diese autonom operieren, abrechnen und weltweit investieren können.

🌎 1. Globaler Support und Multi-Chain-Architektur

iAgent-Pay ist nicht nur eine lokale API; es ist ein globales Finanzgateway. Unsere Routing-Engine ermöglicht es Ihrem Agenten, Gelder im gesamten Web3-Ökosystem zu bewegen.

Ethereum (ETH): Hohe Liquidität, maximale Sicherheit.
Base (BASE): Layer 2 von Coinbase, ideal für niedrige Gebühren.
Solana (SOL): Extreme Geschwindigkeit (Tausende Transaktionen pro Sekunde).

Der Agent ist währungsunabhängig. Integrierte Währungen umfassen: USDC, USDT, EURC (Euro), CNHC (chinesischer Yuan), GYEN (japanischer Yen), MXNT (mexikanischer Peso).

from iagent_pay import AgentPay

# Agent mit Fokus auf den asiatischen Markt
agent = AgentPay(chain_name="BASE", default_stablecoin="CNHC")

⚡ 2. Hauptmerkmale

A. Autonome Zahlungen (x402)

tx_hash = agent.pay_token(
    recipient_address="0xProvider...", 
    amount=5.0
)
print(f"Zahlung abgeschlossen: {tx_hash}")

B. Rechnungsstellung (Invoicing)

Wenn Ihre KI eine Arbeit für einen Kunden abschließt, kann sie eine „intelligente Rechnung“ erstellen.

invoice_id = agent.invoices.create_invoice(
    amount=25.0, 
    customer_address="0xClient...", 
    description="Code-Audit"
)

🛡️ 3. Sicherheitskernel (Safety Kernel)

Software finanzielle Freiheit zu gewähren, erfordert strenge Limits. Jede Transaktion wird validiert, bevor sie an das Netzwerk gesendet wird.

Tägliche Limits: Verhindert, dass ein fehlerhafter Agent Ihr Konto leert.
Intelligente Identität (ERC-8004): Agenten besitzen eine souveräne Identität auf der Blockchain, geschützt vor Diebstahl privater Schlüssel.

# Täglich maximal 15 USD zulassen
agent = AgentPay(daily_limit=15.0)

# Identität prägen
identity = agent.identity.mint_soulbound_id("Bot", "0xOwner")

📈 4. Autonome Schatzkammer (DeFi)

Zahlen Sie überschüssige Ersparnisse automatisch in globale Protokolle wie Aave v3 ein, um Renditen zu erzielen, während Sie schlafen.

# 50 USD in bar halten, den Rest investieren
agent.yield_manager.auto_invest(buffer_usd=50.0)

Unternehmensmodus: Für Unternehmen, die Agenten als Dienstleistung anbieten, unterstützt iAgent-Pay gaslose Transaktionen (Paymasters). Endbenutzer müssen keine Kryptowährung kaufen.

📊 32. Visuelles Dashboard für Unternehmen (schreibgeschützt)

Um ein Höchstmaß an Cybersicherheit zu garantieren, ohne die Transparenz zu beeinträchtigen, bietet iAgent-Pay ein Echtzeit-Überwachungsdashboard mit klaren Pastelltönen. Aus Sicherheitsgründen ist dieses Dashboard **streng schreibgeschützt (Read-Only)**. Dies verhindert, dass böswillige Akteure Agentenkonfigurationen über die Weboberfläche ändern, den Sicherheitskernel manipulieren oder Gelder stehlen.

Echtzeitüberwachung: Visualisieren Sie das native Gasguthaben, das USDC-Guthaben und den ERC-8004-Lizenzstatus.
Netzwerk- und RPC-Telemetrie: Zeigen Sie aktive RPC-Knoten, Latenzmetriken und die Anzahl der automatischen Rotationen an.
Leitplanken des Sicherheitskernels: Zeigt tägliche Limits, Grenzwerte für Einzeltransaktionen und den Whitelist-Status an.
JSON-Prüfberichtsexport: Ermöglicht das Herunterladen vollständiger Agentenstatusberichte im Standard-JSON-Format mit einem Klick.

🧪 33. Erweiterte interaktive Simulations-Sandbox (Sandbox)

Für Demonstrations- und schnelle Testzwecke enthält das iAgent-Pay-Dashboard eine interaktive Simulations-Sandbox. So können Entwickler und Kunden alle autonomen Funktionen in Echtzeit testen, ohne echtes Geld zu riskieren.

Anfängliches simuliertes Guthaben von $10.000,00 USDC: Jede Sitzung beginnt mit einem fiktiven Saldo, der sich bei jeder erfolgreichen Transaktion verringert.
Interaktive Funktionsschalter: Aktivieren oder deaktivieren Sie die Kernfunktionen von iAgent-Pay (Sicherheitskernel, Auto-Swap, RPC-Failover, Gasless Sponsor und Human-in-the-loop), um die Reaktionen des Agenten zu beobachten.
Ausführungsmodi (Einzelaktion vs. Loop): Führen Sie eine einzelne Aktion aus oder starten Sie eine automatische Schleifensimulation von 5 kontinuierlichen Transaktionen mit einem Klick.
Interaktive Telemetriekonsole: Gibt detaillierte farbcodierte Protokolle mit Zeitstempeln im Simulationsfenster aus.
Simulationsprüfbericht herunterladen: Exportiert die Historie der simulierten Transaktionen im Standard-JSON-Format mit einem Klick.
Globaler Reset-Knopf: Setzt die Simulation sofort auf den Anfangszustand zurück ($10.000 USDC Guthaben und kein Fortschritt).

🔑 34. Ephemeral Zero-Custody Session Keys

Single Transaction Caps: Prevents the agent from sending individual payments above a pre-defined threshold.
Daily Cumulative Limits: Restricts total spending per day to prevent loss in case of logic bugs or infinite loops.
Time Expiry (TTL): Ephemeral keys automatically expire and become invalid after a designated duration.
Destination Whitelisting: The agent can only transfer funds to pre-approved addresses (by default, only back to the owner).

from iagent_pay import AgentPay
from iagent_pay.session_keys import SessionKeyManager

# 1. Load the master wallet owner
owner_account = wm.get_or_create_wallet("MySecurePassword123")

# 2. Create a restricted session key (TTL: 1 hour, daily cap: $100, single tx cap: $20)
session_key = SessionKeyManager.create_session(
    owner_account=owner_account,
    allowed_tokens=["USDC", "ETH"],
    daily_limit_usd=100.0,
    max_tx_usd=20.0,
    validity_seconds=3600,
    allowed_destinations=[owner_account.address, "0xVendorA..."]
)

# 3. Load the session key into the AgentPay instance
agent = AgentPay(chain_name="SEPOLIA")
agent.use_session_key(session_key)

# 4. Execute transaction autonomously (validated instantly against session bounds)
tx = agent.pay_token("0xVendorA...", amount=5.0, token="USDC")
print(f"Transaction successfully broadcasted: {tx}")

🏅 35. Compliance & Trust Verification (Know Your Agent - KYA)

W3C Standard DIDs: Unique DID documents issued in the format did:iagent:<hash>.
Trust Levels (TrustLevel): Dynamic levels ranging from UNKNOWN, VERIFIED, up to ELITE based on successful transactions.
Verifiable Credentials: Secure claims issued by controllers detailing agent capabilities and limits.
Compliance Blacklisting: Fraudulent or misbehaving DIDs are instantly blacklisted, blocking all incoming and outgoing payments.

from iagent_pay.kya import AgentIdentity, get_registry

# 1. Create a decentralized identity for the AI agent
identity = AgentIdentity.create(
    name="ResearcherBot-7",
    owner_address="0xAlice...",
    capabilities=["payments", "web_search"]
)
print(f"Agent DID: {identity.did}")

# 2. Register the agent in the KYA database
registry = get_registry()
registry.register(identity)

# 3. Automatically build reputation score through transaction history
registry.update_after_payment(identity.did, success=True, amount_usd=50.0)

# 4. Fetch KYA audit report and trust score
report = registry.get_full_report(identity.did)
print(f"Trust Level: {report['trust_level']} (ART Rep Score: {report['art_score']}/100)")

📘 Manuel de Référence Officiel: iAgent-Pay (v8.5.0)

Bienvenue sur iAgent-Pay, l'infrastructure de paiement la plus avancée pour les agents d'Intelligence Artificielle. Ce manuel technique est conçu pour vous apprendre à débloquer 100 % des capacités de vos agents, leur permettant d'opérer, de facturer et d'investir de manière autonome à l'échelle mondiale.

🌎 1. Support Global et Architecture Multi-Chaînes

iAgent-Pay n'est pas qu'une simple API locale ; c'est une passerelle financière mondiale. Notre moteur de routage permet à votre agent de déplacer des fonds à travers tout l'écosystème Web3.

Ethereum (ETH): Liquidité élevée, sécurité maximale.
Base (BASE): Layer 2 de Coinbase, idéal pour des frais bas.
Solana (SOL): Vitesse extrême (milliers de transactions par seconde).

L'agent est agnostique vis-à-vis de la monnaie. Les devises intégrées comprennent : USDC, USDT, EURC (Euro), CNHC (Yuan chinois), GYEN (Yen japonais), MXNT (Peso mexicain).

from iagent_pay import AgentPay

# Agent axé sur le marché asiatique
agent = AgentPay(chain_name="BASE", default_stablecoin="CNHC")

⚡ 2. Fonctionnalités Clés

A. Paiements Autonomes (x402)

tx_hash = agent.pay_token(
    recipient_address="0xProvider...", 
    amount=5.0
)
print(f"Paiement complété: {tx_hash}")

B. Facturation (Invoicing)

Si votre IA effectue un travail pour un client, elle peut générer une « facture intelligente ».

invoice_id = agent.invoices.create_invoice(
    amount=25.0, 
    customer_address="0xClient...", 
    description="Audit de Code"
)

🛡️ 3. Noyau de Sécurité (Safety Kernel)

Donner une liberté financière à des logiciels nécessite des limites strictes. Chaque transaction est validée avant d'être envoyée au réseau.

Limites quotidiennes: Empêche un agent défaillant de vider votre compte.
Identité intelligente (ERC-8004): Les agents possèdent une identité souveraine sur la blockchain, protégée contre le vol de clés privées.

# Limite à 15 USD par jour maximum
agent = AgentPay(daily_limit=15.0)

# Émettre une identité
identity = agent.identity.mint_soulbound_id("Bot", "0xOwner")

📈 4. Trésorerie Autonome (DeFi)

Déposez automatiquement vos excédents de trésorerie dans des protocoles mondiaux comme Aave v3 pour générer des rendements pendant votre sommeil.

# Conserver 50 USD en espèces, investir le reste
agent.yield_manager.auto_invest(buffer_usd=50.0)

Mode Entreprise: Pour les entreprises qui fournissent des agents en tant que service, iAgent-Pay prend en charge les transactions sans frais de gaz (Paymasters). Les utilisateurs finaux n'ont pas besoin d'acheter de crypto.

📊 32. Tableau de bord visuel d'entreprise (lecture seule)

Pour garantir les plus hauts niveaux de cybersécurité sans compromettre la transparence, iAgent-Pay introduit un tableau de bord de surveillance visuelle en temps réel aux couleurs pastel épurées. Par conception de sécurité, ce panneau est **strictement en lecture seule (Read-Only)**. Cela empêche les acteurs malveillants de modifier la configuration de l'agent, d'altérer le noyau de sécurité (Safety Kernel) ou de retirer des fonds via l'interface web.

Surveillance en temps réel: Visualisez le solde de gaz natif, le solde USDC et le statut de licence ERC-8004.
Télémétrie réseau et RPC: Affichez les nœuds RPC actifs, les mesures de latence et le nombre de rotations automatiques.
Limites du noyau de sécurité: Affiche les limites quotidiennes, les seuils de transaction unique et le statut de la liste blanche.
Exportateur d'audit JSON: Permet de télécharger des rapports complets sur l'état de l'agent au format JSON standard en un clic.

🧪 33. Sandbox de simulation interactive avancée (Sandbox)

À des fins de démonstration et de test rapide, le tableau de bord iAgent-Pay comprend un environnement interactif de sandbox de simulation. Cela permet aux développeurs et aux clients de tester toutes nos fonctionnalités autonomes en temps réel, sans risquer de fonds réels.

Solde de simulation initial de 10 000,00 USDC: Chaque session commence avec un solde virtuel qui diminue dynamiquement à chaque transaction réussie.
Boutons de fonctionnalités interactifs: Activez ou désactivez les fonctionnalités clés de iAgent-Pay (noyau de sécurité, auto-swap, failover RPC, parrainage gasless et Human-in-the-loop) pour observer les réactions de l'agent aux pannes et limites de politique.
Modes d'exécution (Action unique vs Boucle): Exécutez une seule action ou lancez une simulation en boucle de 5 transactions consécutives en un clic.
Console de télémétrie interactive: Affiche des journaux détaillés avec code couleur et horodatage dans la console de simulation.
Télécharger le rapport d'audit: Exporte l'historique complet des transactions simulées au format JSON standard en un clic.
Bouton de réinitialisation globale: Ramène instantanément la simulation à son état initial (solde de 10 000 USDC et progression nulle).

🔑 34. Ephemeral Zero-Custody Session Keys

Single Transaction Caps: Prevents the agent from sending individual payments above a pre-defined threshold.
Daily Cumulative Limits: Restricts total spending per day to prevent loss in case of logic bugs or infinite loops.
Time Expiry (TTL): Ephemeral keys automatically expire and become invalid after a designated duration.
Destination Whitelisting: The agent can only transfer funds to pre-approved addresses (by default, only back to the owner).

from iagent_pay import AgentPay
from iagent_pay.session_keys import SessionKeyManager

# 1. Load the master wallet owner
owner_account = wm.get_or_create_wallet("MySecurePassword123")

# 2. Create a restricted session key (TTL: 1 hour, daily cap: $100, single tx cap: $20)
session_key = SessionKeyManager.create_session(
    owner_account=owner_account,
    allowed_tokens=["USDC", "ETH"],
    daily_limit_usd=100.0,
    max_tx_usd=20.0,
    validity_seconds=3600,
    allowed_destinations=[owner_account.address, "0xVendorA..."]
)

# 3. Load the session key into the AgentPay instance
agent = AgentPay(chain_name="SEPOLIA")
agent.use_session_key(session_key)

# 4. Execute transaction autonomously (validated instantly against session bounds)
tx = agent.pay_token("0xVendorA...", amount=5.0, token="USDC")
print(f"Transaction successfully broadcasted: {tx}")

🏅 35. Compliance & Trust Verification (Know Your Agent - KYA)

W3C Standard DIDs: Unique DID documents issued in the format did:iagent:<hash>.
Trust Levels (TrustLevel): Dynamic levels ranging from UNKNOWN, VERIFIED, up to ELITE based on successful transactions.
Verifiable Credentials: Secure claims issued by controllers detailing agent capabilities and limits.
Compliance Blacklisting: Fraudulent or misbehaving DIDs are instantly blacklisted, blocking all incoming and outgoing payments.

from iagent_pay.kya import AgentIdentity, get_registry

# 1. Create a decentralized identity for the AI agent
identity = AgentIdentity.create(
    name="ResearcherBot-7",
    owner_address="0xAlice...",
    capabilities=["payments", "web_search"]
)
print(f"Agent DID: {identity.did}")

# 2. Register the agent in the KYA database
registry = get_registry()
registry.register(identity)

# 3. Automatically build reputation score through transaction history
registry.update_after_payment(identity.did, success=True, amount_usd=50.0)

# 4. Fetch KYA audit report and trust score
report = registry.get_full_report(identity.did)
print(f"Trust Level: {report['trust_level']} (ART Rep Score: {report['art_score']}/100)")

📘 Resmi Başvuru Kılavuzu: iAgent-Pay (v8.5.0)

Yapay Zeka Ajanları için en gelişmiş ödeme altyapısı olan iAgent-Pay'e hoş geldiniz. Bu teknik kılavuz, ajanlarınızın yeteneklerini %100 oranında nasıl açacağınızı öğretmek ve küresel ölçekte otonom olarak işlem yapmalarını, ödeme almalarını ve yatırım yapmalarını sağlamak için tasarlanmıştır.

🌎 1. Küresel Destek ve Çoklu Zincir Mimarisi

iAgent-Pay yalnızca yerel bir API değildir; küresel bir finansal geçittir. Yönlendirme motorumuz, ajanınızın tüm Web3 ekosisteminde para taşımasına olanak tanır.

Ethereum (ETH): Yüksek likidite, maksimum güvenlik.
Base (BASE): Coinbase'in Katman 2'si, düşük ücretler için idealdir.
Solana (SOL): Olağanüstü hız (binlerce TPS).

Ajan "Para Birimi Bağımsızdır". Dahili para birimleri şunları içerir: USDC, USDT, EURC (Euro), CNHC (Yuan), GYEN (Yen), MXNT (Peso).

from iagent_pay import AgentPay

# Asya pazarına özel ajan
agent = AgentPay(chain_name="BASE", default_stablecoin="CNHC")

⚡ 2. Temel Özellikler

A. Otonom Ödemeler (x402)

tx_hash = agent.pay_token(
    recipient_address="0xProvider...", 
    amount=5.0
)
print(f"Ödeme tamamlandı: {tx_hash}")

B. Faturalandırma

Yapay zekanız bir müşteri için iş yaparsa, "Akıllı Fatura" oluşturabilir.

invoice_id = agent.invoices.create_invoice(
    amount=25.0, 
    customer_address="0xClient...", 
    description="Kod Denetimi"
)

🛡️ 3. Güvenlik Çekirdeği (Safety Kernel)

Yazılıma finansal özgürlük vermek katı limitler gerektirir. Ağa dokunmadan önce her işlemi doğrular.

Günlük Limitler: Hatalı çalışan bir ajanın hesabınızı boşaltmasını önler.
Akıllı Kimlik (ERC-8004): Ajanlar, blok zincirinde özel anahtar hırsızlığına karşı bağışıklığı olan "Egemen Kimliğe" sahiptir.

# Günlük maksimum 15 ABD Doları limit
agent = AgentPay(daily_limit=15.0)

# Kimlik Basımı (SBT)
identity = agent.identity.mint_soulbound_id("Bot", "0xOwner")

📈 4. Otonom Hazine (DeFi)

Fazla tasarrufları Aave v3 gibi küresel protokollere otomatik olarak yatırın, siz uyurken getiri elde edin.

# Nakit olarak 50$ tut, gerisini yatır
agent.yield_manager.auto_invest(buffer_usd=50.0)

🏦 5. Fiat Köprüsü (Banka ve Kart Ödemeleri)

Müşterinin kripto parası yok mu? Sorun değil. iAgent-Pay, geleneksel banka hesaplarına para yatırmak veya kredi kartlarından tahsilat yapmak için doğrudan Stripe'a bağlanır.

Stripe Transferi: Banka hesabı olan herkese ödeme yapın.
ACH (ABD): Düşük maliyetli doğrudan banka transferleri.
Akıllı Yönlendirici: Otomatik olarak en ucuz rotayı seçer (kripto vs banka).
Ödeme Bağlantısı: Ajan, insanların kripto olmadan ödeme yapması için bir bağlantı oluşturur.

from iagent_pay.fiat_bridge import FiatBridge

bridge = FiatBridge()

# Bir serbest çalışana banka hesabına ödeme yapın
bridge.send_stripe(amount_usd=150.0, stripe_account_id="acct_1M2...", description="İki haftalık ödeme")

# Ajan kart ödemeleri için ödeme bağlantısı oluşturur
link = bridge.create_payment_link(amount_usd=9.99, description="Premium API Erişimi")
print(link["url"])  # → https://buy.stripe.com/...

# Akıllı yönlendirici: USDC veya Stripe kararı
bridge.smart_send(amount_usd=25.0, recipient="client@company.com")

🌉 6. Zincirler Arası Yönlendirme (AP2 Motoru)

Ajan bir ağda (örneğin Ethereum) para tutup başka bir ağda (örneğin Polygon) ödeme yapabilir. AP2 Motoru mevcut tüm köprüleri değerlendirir ve en ucuz ve en hızlı olanı otomatik seçer.

from iagent_pay.cross_chain import CrossChainRouter

router = CrossChainRouter()

# 100 USDC'yi Base -> Polygon arasında otomatik köprüle
tx = router.bridge_assets(
    source_chain="BASE",
    target_chain="POLYGON",
    amount=100.0,
    token="USDC"
)
print(f"Köprü tamamlandı: {tx}")

🤖 7. Filo Yönetimi (Alt Temsilciler)

Çoklu ajan ekipleri için. Bir Ana Ajan, her biri kendi bütçesine, limitlerine ve izole işlem geçmişine sahip özel "alt temsilciler" oluşturabilir ve kontrol edebilir.

from iagent_pay.sub_agents import SubAgentManager

# 500$ toplam bütçeli ana temsilci
manager = SubAgentManager(master_budget_usd=500.0)

# Özel alt temsilciler oluştur
researcher = manager.create("researcher", daily_limit_usd=20.0)
writer     = manager.create("writer",     daily_limit_usd=10.0)

researcher.kernel.check(amount=5.0, recipient="0xDataAPI...")
researcher.spend(5.0, "USDC", "Piyasa verisi alımı")

# Acil durum durdurma
manager.pause("researcher")
print(manager.get_status())

🌐 8. Tam Küresel Token Sözlüğü

Ağ	Desteklenen Tokenlar	Kullanım Durumu
Ethereum (ETH)	USDC, USDT, DAI, EURC, CNHC (Yuan), GYEN (Yen), XSGD, MXNT	Yüksek likidite, maksimum güvenlik
Base (BASE)	USDC, USDT, DAI, EURC, WETH	Minimum işlem ücreti, Coinbase
Polygon (MATIC)	USDC, USDT, DAI, WETH	Hızlı mikro ödemeler
Arbitrum (ARB)	USDC, USDT, DAI, WETH	Yüksek hız, düşük maliyet
BNB (Binance)	USDC, USDT, BUSD, DAI	Binance ekosistemi
Solana (SOL)	USDC native, SOL	Olağanüstü hız (4000+ TPS)

agent_latam = AgentPay(chain_name="BNB", default_stablecoin="USDT")
agent_eu    = AgentPay(chain_name="ETH", default_stablecoin="EURC")
agent_asia  = AgentPay(chain_name="ETH", default_stablecoin="CNHC")

⚙️ 9. Gelişmiş Güvenlik Çekirdeği

from iagent_pay.safety_kernel import SafetyKernel, SafetyConfig

kernel = SafetyKernel(SafetyConfig(
    daily_limit_usd=100.0,
    weekly_limit_usd=500.0,
    session_limit_usd=20.0,
    max_tx_usd=10.0,
    max_tx_per_minute=5,
    max_tx_per_hour=50,
    human_approval_threshold_usd=50.0,
    allowed_recipients=["0xAlice...", "0xBob..."],
    enable_whitelist=True,
))

kernel.check(amount=5.0, recipient="0xAlice...", currency="USDC")
print(kernel.get_status())
audit_log = kernel.get_audit_log()

💳 10. Cüzdan Yöneticisi

Ajanınızın kriptografik anahtarlarını oluşturur, içe aktarır ve korur. Geliştirme için AES-128 şifreli anahtar depolarını ve .env dosyalarını destekler.

from iagent_pay.wallet_manager import WalletManager

wm = WalletManager()

# Cüzdanı otomatik oluştur veya yükle
wallet = wm.get_or_create_wallet(password="MySecurePassword123")
print(f"Ajan Adresi: {wallet.address}")

# Mevcut cüzdanı özel anahtardan içe aktar
imported = wm.load_wallet("0xYourPrivateKeyHere...")

# Geçici cüzdan oluştur (test amaçlı)
temp_wallet = wm.create_wallet()

🔤 11. Sosyal İsim Çözümleyici

Ajanınız, 0x7F5E... gibi adresleri kopyalamak yerine ENS alan adları veya Solana İsim Servisi gibi insan tarafından okunabilen adları çözebilir.

from iagent_pay.social_resolver import SocialResolver

resolver = SocialResolver()

# ENS adı kullanarak öde
address = resolver.resolve("vitalik.eth")

# Solana adı kullanarak öde
sol_address = resolver.resolve("example.sol")

# Doğrudan AgentPay ile kullanın
tx = agent.pay_token(resolver.resolve("partner.eth"), amount=10.0)

🔔 12. Gerçek Zamanlı Webhook'lar

Ajanlarınızdan otomatik bildirimler alan URL'leri kaydedin. Her olay, sahtekarlığı önlemek için HMAC-SHA256 (Stripe ile aynı standart) ile imzalanır.

from iagent_pay.webhooks import WebhookManager

wm = WebhookManager(default_secret="my-shared-secret")
wm.register("https://myserver.com/webhook", events=["payment.completed", "budget.exceeded"])

# Olayı manuel olarak tetikleyin
wm.emit("payment.completed", {"tx_hash": "0xabc...", "amount": 5.0})

# Yerel işleyici (HTTP sunucusuna gerek yok)
def my_handler(event):
    print(f"Olay alındı: {event['type']}")

wm.on("payment.completed", my_handler)

👤 13. Döngü içi İnsan Onayı (Human-in-the-Loop)

Büyük ödemeler için ajan duraklar ve Telegram, Slack veya konsol üzerinden insan onayı ister. Zaman aşımı süresi içinde yanıt alınamazsa ödeme otomatik iptal edilir.

from iagent_pay.human_loop import HumanApproval, HumanLoopConfig

hitl = HumanApproval(HumanLoopConfig(
    threshold_usd=20.0,           # 20$'dan büyük ödemeler için onay iste
    timeout_seconds=300,          # Maksimum 5 dakika bekle
    notify_telegram_token="BOT_TOKEN",
    notify_telegram_chat_id="CHAT_ID",
))

approved = hitl.request_approval(
    amount=50.0,
    currency="USDC",
    recipient="0xVendor...",
    reason="Premium veri erişim alımı"
)

if approved:
    agent.pay_token("0xVendor...", 50.0)

🔄 14. Swap Motoru (SwapEngine)

Tokenleri otomatik olarak takas edin. Ajan, Uniswap (EVM) ve Jupiter (Solana) üzerindeki herhangi bir çifti veya ETH'yi USDC'ye, SOL'u BONK'a dönüştürebilir.

swap = agent.swap_engine

# Takas yapmadan önce fiyat teklifi al
quote = swap.get_quote(input_token="SOL", output_token="USDC", amount=1.0)
print(f"1 SOL ≈ {quote['output']} USDC (Slippage: {quote['slippage']}%)")

# Kayma (slippage) koruması ile takası gerçekleştir
result = swap.execute_swap(
    input_token="ETH",
    output_token="USDC",
    amount=0.5,
    min_output_amount=900.0  # Alınan USDC 900'den azsa işlemi reddet
)
print(f"Takas başarılı! Tx: {result['tx_hash']}")

🛒 15. Veri Pazaryeri (Data Marketplace)

Ajanlarınızın veri alıp satabileceği merkeziyetsiz bir kayıt defteri. x402 ile çalışır: alıcı en iyi sağlayıcıyı bulur, otomatik ödeme yapar ve veriyi alır.

from iagent_pay.data_marketplace import DataMarketplace, DataProvider, get_marketplace

marketplace = get_marketplace()

# Satıcı: API'nizi veri sağlayıcısı olarak kaydedin
marketplace.register(DataProvider(
    name="MyWeatherAPI", data_type="weather",
    url="https://myapi.com/v1/weather", price_usdc=0.05, trust_score=95.0
))

# Alıcı: 0.10$ altındaki en iyi hava durumu sağlayıcısını bulun
best = marketplace.find_best_provider("weather", max_price_usd=0.10)
print(f"En iyi: {best.name} fiyat: ${best.price_usdc}")

🤝 16. İtibar Sistemi

Her ajan, ortakları için yerel bir itibar defteri (0-5 yıldız) tutar. Bilinmeyen bir ajana ödeme yapmadan önce geçmiş performansını kontrol edin.

rep = agent.reputation

# Başarılı bir işlemden sonra eşi derecelendirin
rep.rate_peer("0xVendor...", score=4.8)

# Ödemeden önce itibarı kontrol edin
trust = rep.get_trust_score("0xUnknown...")
if trust < 3.0:
    print("Düşük güvenli ajan — dikkatli ilerleyin.")

# En güvenilir ajanları görüntüleyin
top = rep.get_top_agents(limit=5)

🤖 17. Claude ve Cursor Entegrasyonu (MCP Sunucusu)

iAgent-Pay, Claude, Cursor, Windsurf ve VS Code tarafından kullanılan Model Context Protocol (MCP) ile tamamen uyumludur. Claude, doğal dilde ajanınıza ödeme yapma talimatı verebilir.

# Terminalden MCP sunucusunu başlatın:
# iagent-pay mcp-server

# claude_desktop_config.json dosyasında yapılandırın:
# {
#   "mcpServers": {
#     "iagentpay": {
#       "command": "python",
#       "args": ["-m", "iagent_pay.mcp_server"]
#     }
#   }
# }

# Bağlandıktan sonra Claude şunları söyleyebilir:
# "0xBob... adresine 5 USDC öde"
# "Ajan bakiyem ne kadar?"

💻 18. Komut Satırı Arayüzü (CLI)

iAgent-Pay, Python kodu yazmadan ajanları yönetmek ve test etmek için terminal komutları içerir.

# Sıfırdan yeni bir ajan projesi oluşturun
iagent-pay init my-enterprise-agent

# Ajan bakiyesini ve durumunu görüntüleyin
iagent-pay status --chain BASE

# Testnet musluk bağlantılarını alın (ücretsiz test parası)
iagent-pay faucet

# Claude/Cursor entegrasyonu için MCP sunucusunu başlatın
iagent-pay mcp-server

🌐 19. x402 Sunucusu — Kendi Verinizi Satın

x402 protokolünün diğer tarafı. Değerli verileri olan bir API'niz varsa (finansal, hava durumu, yasal vb.), bunu koruyabilir ve erişim isteyen her ajandan otomatik olarak USDC tahsil edebilirsiniz. Flask ve FastAPI ile uyumludur.

# --- FastAPI Örneği ---
from fastapi import FastAPI, Request
from iagent_pay.x402_server import X402Middleware

app = FastAPI()

app.add_middleware(
    X402Middleware,
    payment_address="0xYourPaymentAddress...",
    amount_usdc=0.10,
    protected_paths=["/premium", "/api/v2"],
    network="BASE"
)

📊 20. Gözlemlenebilirlik ve İzleme

Tüm ödemeler için istatistikler içeren gerçek zamanlı kontrol paneli. Anormal harcama kalıplarını otomatik olarak algılar ve kurumsal altyapı için Prometheus ve OpenTelemetry ile entegre olur.

from iagent_pay.observability import PaymentObserver, ObservabilityConfig

observer = PaymentObserver(ObservabilityConfig(
    log_level="INFO",
    log_format="json",
    enable_anomaly_detection=True,
    anomaly_threshold_multiplier=3.0,
    enable_prometheus=True,
    prometheus_port=9090,
))

💵 21. Fiyat Motoru

Eş zamanlı 3 kaynaktan anlık ETH, SOL ve XRP fiyatlarını sorgular. Biri başarısız olursa otomatik olarak diğer kaynağa geçer.

from iagent_pay.pricing import PricingManager

pricing = PricingManager()
eth_price = pricing.get_price("ETH")  # → 3200.50

🌊 22. XRP Ledger Ağı

Dünyanın en hızlı ödeme ağlarından biri olan XRP Ledger için yerel destek. İşlem başına 0.001 doların altında maliyetle 3-5 saniyede onaylama sağlar.

agent_xrp = AgentPay(chain_name="XRP")
agent_xrp.xrpl.load_wallet("sYourXRPSecretSeed...")
tx_hash = agent_xrp.xrpl.transfer("rDestinationAddress...", amount_xrp=10.0)

🎯 23. Ödül Pazaryeri (Bounty Marketplace)

Ajanınız, insanların belirli görevleri tamamlaması için ödüller (bounty) yayınlayabilir. Görev doğrulandıktan sonra ödeme otomatik serbest bırakılır.

from iagent_pay.marketplace_bridge import MarketplaceBridge

bridge = MarketplaceBridge(agent)
bounty_id = bridge.post_bounty(title="Çeviri görevi", reward_usd=75.0)
bridge.release_payment(bounty_id, human_address="0xFreelancer...")

🦾 24. CrewAI Entegrasyonu

CrewAI, işbirlikçi yapay zeka ajan ekipleri oluşturmak için en popüler çerçevedir. Bu entegrasyonla, bir Crew içindeki herhangi bir ajan diğerlerine otonom ödeme yapabilir.

from iagent_pay.integrations.crewai import iAgentPayCrewTool
pay_tool = iAgentPayCrewTool(chain="BASE", max_amount_usdc=5.0)

🔗 25. LangChain Entegrasyonu

Dünyanın en çok kullanılan yapay zeka çerçevesi LangChain entegrasyonu ile herhangi bir zincir veya temsilci kripto ödemelerini yerel bir araç olarak gönderebilir.

from iagent_pay.integrations.langchain import iAgentPayTool
pay_tool = iAgentPayTool()

💰 26. Birikmiş Hacim Ücret Modeli

iAgent-Pay, birikmiş işlem hacmine dayalı rekabetçi ve şeffaf bir ücret yapısı uygular. Bireysel işlemlerden yüzde komisyonu almak yerine, arka planda hacim biriktirilir ve her 1.000,00 ABD Doları hacim için sabit 1,00 ABD Doları ücret tahsil edilir.

🔒 27. Çoklu İmza ve İnsan Döngüsü Güvenlik Modları

Ajanınız, SafetyConfig içindeki multisig_mode özelliği ile üç farklı güvenlik şemasında çalıştırılabilir:

ALLOWANCE_ONLY: Sadece otonom limitler. Aşılması durumunda doğrudan iptal edilir.
PROPOSAL_ONLY: Tamamen manuel onay gerektiren mod. Ajan ödeme teklif eder, insan onaylar.
HYBRID: Hibrit mod. Düşük tutarlar otonom, limit üstü ise insan onayına sunulur.

🔄 28. Otomatik Likidite Dengeleme (Auto-Swap Geri Dönüşü)

Ajanın belirli bir token ile ödeme yapması gerektiğinde ancak yeterli bakiyesi olmadığında, iAgent-Pay eldeki yerel varlıkları (ETH veya SOL) otomatik olarak takas ederek bakiyeyi dengeler.

# Otomatik dengelemeyi etkinleştir (Varsayılan)
agent = AgentPay(enable_auto_swap=True)

🔑 29. Şifreli Anahtar Yedekleme ve Geri Yükleme

Güvenlik ve taşınabilirlik için bakiye ve kimlik bilgilerinizi şifreli olarak yedekleyebilirsiniz:

agent.backup_wallet("backup_wallet.enc", password="MySecureBackupPassword123")

📦 30. Toplu İşlemler (Batch Transactions / Multicall)

iAgent-Pay, optimize edilmiş eş zamanlı toplu ödemeleri destekler. Bu, gaz maliyetlerini %30'a kadar düşürür ve ödemeleri 10 kat hızlandırır.

tx_hashes = agent.pay_token_batch(payments, token="USDC", wait=True)

🔄 31. Üstel Geri Çekilme ve Hız Sınırı Korumalı RPC Otomatik Rotasyonu

Kesintisiz çalışma gerektiren kurumsal uygulamalar için iAgent-Pay, RPC bağlantı hatası durumunda otomatik olarak yedek düğümlere döner.

agent.rotate_rpc()

Kurumsal Mod: Ajanları hizmet olarak sunan şirketler için iAgent-Pay, gazsız işlemleri (Paymasters) destekler. Son kullanıcıların işlem yapmak için kripto para almasına gerek yoktur.

📊 32. Kurumsal Görsel Kontrol Paneli (Salt Okunur)

Şeffaflıktan ödün vermeden en üst düzeyde siber güvenlik sağlamak için iAgent-Pay, pastel tonlarda tasarlanmış gerçek zamanlı bir kontrol paneli sunar. Güvenlik gereği bu panel kesinlikle Salt Okunurdur. Bu, saldırganların web arayüzü üzerinden bütçe sınırlarını değiştirmesini veya fon çekmesini engeller.

Gerçek Zamanlı İzleme: Gaz bakiyelerini, USDC durumunu ve ERC-8004 lisansını görün.
Ağ Telemetrisi: Aktif RPC düğümlerini ve gecikme sürelerini izleyin.
Güvenlik Çekirdeği Limitleri: Günlük limitleri ve beyaz liste durumunu görüntüler.
JSON Denetim İhracatçısı: Ajan raporunu tek tıkla standart JSON olarak indirmeyi sağlar.

🧪 33. Gelişmiş Etkileşimli Simülasyon Sandbox'ı

Kontrol panelinde hızlı testler için etkileşimli bir **Simülasyon Sandbox Ortamı** bulunur. Geliştiriciler gerçek fonları riske atmadan tüm otonom özellikleri gerçek zamanlı test edebilir.

10.000,00 USDC Simüle Edilmiş Başlangıç Sermayesi: Her simülasyon sanal bir bakiye ile başlar ve işlemlerle azalır.
Etkileşimli Özellik Seçenekleri: Güvenlik Çekirdeği, Auto-Swap ve Human-in-the-Loop gibi özellikleri açıp kapatarak ajanın davranışını gözlemleyin.
Konsol Çıktısı: Simüle edilen konsolda zaman damgalı günlükleri doğrudan inceleyin.

🔑 34. Emanetsiz Oturum Anahtarları (Session Keys)

iAgent-Pay, ana özel anahtarınızı açığa çıkarmadan Yapay Zeka ajanlarınıza geçici işlem imzalama yetkisi vermenizi sağlar. Bu, tam bir "Emanetsiz" (Zero-Custody) güvenlik modeli oluşturur: ajan, cüzdan sahibi tarafından önceden imzalanmış kurallara sıkı sıkıya bağlı kalarak geçici anahtarla otonom olarak işlem yapar.

Tek İşlem Sınırları: Ajanın önceden belirlenmiş eşiğin üzerinde bireysel ödeme göndermesini engeller.
Günlük Kümülatif Limitler: Sonsuz döngüler veya mantık hataları durumunda kaybı önlemek için günlük harcamayı sınırlar.
Zaman Aşımı (TTL): Geçici anahtarlar belirlenen süre sonunda otomatik olarak geçersiz hale gelir.
Alıcı Beyaz Listesi: Ajan yalnızca önceden onaylanmış adreslere fon transfer edebilir.

from iagent_pay import AgentPay
from iagent_pay.session_keys import SessionKeyManager

owner_account = wm.get_or_create_wallet("MySecurePassword123")
session_key = SessionKeyManager.create_session(
    owner_account=owner_account,
    allowed_tokens=["USDC", "ETH"],
    daily_limit_usd=100.0,
    max_tx_usd=20.0,
    validity_seconds=3600,
    allowed_destinations=[owner_account.address, "0xVendorA..."]
)
agent = AgentPay(chain_name="SEPOLIA")
agent.use_session_key(session_key)
tx = agent.pay_token("0xVendorA...", amount=5.0, token="USDC")
print(f"Transaction successfully broadcasted: {tx}")

🏅 35. Uyum ve Güven Doğrulaması (Ajanını Tanı - KYA)

Kurumsal uyumluluk ve güvenlik için iAgent-Pay, **Ajanını Tanı (KYA)** standardını sunar. W3C Merkeziyetsiz Kimlik Tanımlayıcıları (DID) ve Doğrulanabilir Kimlik Bilgilerini kullanarak, ajanlar kimliklerini kanıtlayabilir ve itibar puanları oluşturabilir.

W3C Standart DID'leri: did:iagent:<hash> biçiminde benzersiz DID belgeleri.
Güven Seviyeleri (TrustLevel): İşlem geçmişine göre UNKNOWN seviyesinden ELITE seviyesine kadar dinamik derecelendirme.
Kara Liste Yönetimi: Hatalı davranan veya sahte DİD'ler anında kara listeye alınarak tüm ödemeleri engellenir.

from iagent_pay.kya import AgentIdentity, get_registry
identity = AgentIdentity.create(name="ResearcherBot-7", owner_address="0xAlice...", capabilities=["payments"])
registry = get_registry()
registry.register(identity)
report = registry.get_full_report(identity.did)
print(f"Trust Level: {report['trust_level']} (Rep Score: {report['art_score']}/100)")

📘 Opisyal na Manwal ng Sanggunian: iAgent-Pay (v8.5.0)

Maligayang pagdating sa iAgent-Pay, ang pinaka-advanced na imprastraktura ng pagbabayad para sa mga AI Agent. Ang teknikal na manwal na ito ay dinisenyo upang ituro sa iyo kung paano i-unlock ang 100% ng mga kakayahan ng iyong mga agent, na nagpapahintulot sa kanila na gumana, maningil, at mag-invest nang autonomous sa pandaigdigang antas.

🌎 1. Pandaigdigang Suporta at Multi-Chain na Arkitektura

Ang iAgent-Pay ay hindi lamang isang lokal na API; ito ay isang pandaigdigang financial gateway. Ang aming routing engine ay nagpapahintulot sa iyong agent na maglipat ng pera sa buong Web3 ecosystem.

Ethereum (ETH): Mataas na likidasyon, pinakamataas na seguridad.
Base (BASE): Layer 2 ng Coinbase, perpekto para sa mabababang bayarin.
Solana (SOL): Sukdulang bilis (libo-libong TPS).

Ang agent ay "Currency Agnostic". Ang mga built-in na currency ay kinabibilangan ng: USDC, USDT, EURC (Euro), CNHC (Yuan), GYEN (Yen), MXNT (Peso).

from iagent_pay import AgentPay

# Agent na dalubhasa sa merkado ng Asya
agent = AgentPay(chain_name="BASE", default_stablecoin="CNHC")

⚡ 2. Mga Pangunahing Tampok

A. Autonomous na Pagbabayad (x402)

tx_hash = agent.pay_token(
    recipient_address="0xProvider...", 
    amount=5.0
)
print(f"Kumpleto ang pagbabayad: {tx_hash}")

B. Invoicing

Kung ang iyong AI ay gumawa ng trabaho para sa isang kliyente, maaari itong gumawa ng isang "Smart Invoice".

invoice_id = agent.invoices.create_invoice(
    amount=25.0, 
    customer_address="0xClient...", 
    description="Audit ng Code"
)

🛡️ 3. Safety Kernel (Kalyo ng Seguridad)

Ang pagbibigay ng kalayaang pinansyal sa software ay nangangailangan ng mahigpit na mga limitasyon. Bini-verify nito ang bawat transaksyon bago ito ipadala sa network.

Pang-araw-araw na Limitasyon: Pinipigilan ang isang mapanirang agent na ubusin ang iyong account.
Smart Identity (ERC-8004): Ang mga agent ay may "Sovereign Identity" sa blockchain, na ligtas laban sa pagnanakaw ng private key.

# Limitahan sa max $15 bawat araw
agent = AgentPay(daily_limit=15.0)

# Mint ng Identidad
identity = agent.identity.mint_soulbound_id("Bot", "0xOwner")

📈 4. Autonomous na Kaban (DeFi)

Awtomatikong magdeposito ng labis na ipon sa mga pandaigdigang protocol tulad ng Aave v3, na nagbibigay ng yield habang ikaw ay natutulog.

# Panatilihin ang $50 sa cash, i-invest ang iba
agent.yield_manager.auto_invest(buffer_usd=50.0)

🏦 5. Fiat Bridge (Mga Pagbabayad sa Bangko at Kard)

Walang crypto ang kliyente? Walang problema. Direktang kumokonekta ang iAgent-Pay sa Stripe upang magdeposito ng pera sa mga tradisyunal na bank account o maningil sa mga credit card.

Stripe Transfer: Magbayad sa sinumang may bank account.
ACH (US): Mababang-halaga na direktang bank transfer.
Smart Router: Awtomatikong pinipili ang pinakamurang ruta (crypto vs bangko).
Payment Link: Gumagawa ang agent ng link para magbayad ang mga tao nang walang crypto.

from iagent_pay.fiat_bridge import FiatBridge

bridge = FiatBridge()

# Magbayad sa isang freelancer sa kanilang bank account
bridge.send_stripe(amount_usd=150.0, stripe_account_id="acct_1M2...", description="Kalahating buwang bayad")

# Gumawa ng payment link ang agent
link = bridge.create_payment_link(amount_usd=9.99, description="Premium API Access")
print(link["url"])  # → https://buy.stripe.com/...

# Smart router
bridge.smart_send(amount_usd=25.0, recipient="client@company.com")

🌉 6. Cross-Chain Routing (AP2 Engine)

Ang agent ay maaaring magtabi ng pera sa isang network (hal. Ethereum) at magbayad sa isa pa (hal. Polygon). Ang AP2 Engine ay nag-eebaluate ng lahat ng magagamit na tulay at awtomatikong pinipili ang pinakamabilis at pinakamura.

from iagent_pay.cross_chain import CrossChainRouter

router = CrossChainRouter()

# I-bridge ang $100 USDC mula Base → Polygon nang awtomatiko
tx = router.bridge_assets(
    source_chain="BASE",
    target_chain="POLYGON",
    amount=100.0,
    token="USDC"
)
print(f"Kumpleto ang tulay: {tx}")

🤖 7. Pamamahala ng Fleet (Mga Sub-Agent)

Para sa mga multi-agent team. Ang isang Master Agent ay maaaring gumawa at sumubaybay sa mga specialized na "sub-agent", bawat isa ay may sariling badyet at limitasyon.

from iagent_pay.sub_agents import SubAgentManager

manager = SubAgentManager(master_budget_usd=500.0)
researcher = manager.create("researcher", daily_limit_usd=20.0)
writer     = manager.create("writer",     daily_limit_usd=10.0)

researcher.kernel.check(amount=5.0, recipient="0xDataAPI...")
researcher.spend(5.0, "USDC", "Bumili ng datos ng merkado")

# Emergency pause
manager.pause("researcher")

🌐 8. Buong Pandaigdigang Diksyonaryo ng Token

Network	Mga Suportadong Token	Gamit
Ethereum (ETH)	USDC, USDT, DAI, EURC, CNHC, GYEN, XSGD, MXNT	Mataas na likidasyon, max seguridad
Base (BASE)	USDC, USDT, DAI, EURC, WETH	Mababang fees, Coinbase
Polygon (MATIC)	USDC, USDT, DAI, WETH	Mabilis na micro ödemeler
Arbitrum (ARB)	USDC, USDT, DAI, WETH	Mabilis, mababang gastos

⚙️ 9. Progresibong Safety Kernel

from iagent_pay.safety_kernel import SafetyKernel, SafetyConfig

kernel = SafetyKernel(SafetyConfig(
    daily_limit_usd=100.0,
    weekly_limit_usd=500.0,
    session_limit_usd=20.0,
    max_tx_usd=10.0,
    max_tx_per_minute=5,
    max_tx_per_hour=50,
    human_approval_threshold_usd=50.0,
    allowed_recipients=["0xAlice...", "0xBob..."],
    enable_whitelist=True,
))

💳 10. Tagapamahala ng Wallet

Gumagawa, nag-iimport at nagpapanatili ng mga cryptographic key ng iyong agent. Sumusuporta sa AES-128 encrypted keystores at .env na mga file.

from iagent_pay.wallet_manager import WalletManager
wm = WalletManager()
wallet = wm.get_or_create_wallet(password="MySecurePassword123")
print(f"Address ng Agent: {wallet.address}")

🔤 11. Social Name Resolver

Sa halip na kumopya ng mga mahabang address tulad ng 0x7F5E..., maaaring resolbahin ng iyong agent ang mga pangalan ng tao tulad ng mga domain ng ENS o Solana Name Service.

from iagent_pay.social_resolver import SocialResolver
resolver = SocialResolver()
address = resolver.resolve("vitalik.eth")

🔔 12. Real-Time na Webhooks

Magrehistro ng mga URL na awtomatikong makakatanggap ng mga notipikasyon mula sa iyong mga agent. Nilalagdaan gamit ang HMAC-SHA256.

from iagent_pay.webhooks import WebhookManager
wm = WebhookManager(default_secret="my-shared-secret")
wm.register("https://myserver.com/webhook", events=["payment.completed"])

👤 13. Human-in-the-Loop na Pag-apruba

Para sa malalaking transaksyon, humihinto ang agent at humihingi ng manwal na pag-apruba ng tao sa pamamagitan ng Telegram, Slack o console.

from iagent_pay.human_loop import HumanApproval, HumanLoopConfig
hitl = HumanApproval(HumanLoopConfig(threshold_usd=20.0, timeout_seconds=300))
approved = hitl.request_approval(amount=50.0, currency="USDC", recipient="0xVendor...")

🔄 14. Engine ng Swap (SwapEngine)

Awtomatikong magpalit ng mga token. Maaaring magpalit ang agent sa pagitan ng ETH at USDC o SOL at BONK sa Uniswap at Jupiter.

swap = agent.swap_engine
quote = swap.get_quote(input_token="SOL", output_token="USDC", amount=1.0)

🛒 15. Data Marketplace

Isang desentralisadong rehistro kung saan ang mga agent ay maaaring bumili at magbenta ng datos gamit ang x402 protocol.

from iagent_pay.data_marketplace import get_marketplace
marketplace = get_marketplace()

🤝 16. Sistema ng Reputasyon

Bawat agent ay may lokal na ledger ng reputasyon (0-5 stars) para sa kanilang mga katuwang. Suriin ang kanilang tiwala bago magbayad.

rep = agent.reputation
rep.rate_peer("0xVendor...", score=4.8)

🤖 17. Integrasyon sa Claude at Cursor (MCP Server)

Ang iAgent-Pay ay katutubong katugma sa Model Context Protocol (MCP). Maaaring utusan ni Claude ang iyong agent na magbayad gamit ang natural na wika.

# Patakbuhin ang MCP server:
# iagent-pay mcp-server

💻 18. Command Line Interface (CLI)

Pamahalaan at subukan ang iyong mga agent mula sa terminal nang hindi nagsusulat ng code ng Python.

# I-initialize ang isang proyekto
iagent-pay init my-agent
# Tingnan ang status
iagent-pay status --chain BASE

🌐 19. x402 Server — Ibenta ang Iyong Sariling Datos

Kung mayroon kang mahalagang API ng datos, maaari mo itong protektahan at maningil ng USDC sa anumang agent. Katugma sa FastAPI at Flask.

# Protektahan ang mga premium na ruta para sa 0.10 USDC
app.add_middleware(X402Middleware, payment_address="0xAddr...", amount_usdc=0.10)

📊 20. Kakayahang Maobserbahan at Pagsubaybay

Dashboard na may mga real-time na istatistika. Awtomatikong nakikita ang mga kahina-hinalang aktibidad at sumusuporta sa Prometheus.

from iagent_pay.observability import PaymentObserver
observer = PaymentObserver(ObservabilityConfig(enable_prometheus=True))

💵 21. Real-Time na Engine ng Presyo

Kumukuha ng mga live na presyo ng ETH, SOL, at XRP mula sa 3 sabay-sabay na mapagkukunan ng datos.

pricing = PricingManager()
price = pricing.get_price("ETH")

🌊 22. XRP Ledger Network

Suporta para sa XRP Ledger, isa sa mga pinakamabilis at pinakamurang network ng pagbabayad sa buong mundo.

agent_xrp = AgentPay(chain_name="XRP")
agent_xrp.xrpl.load_wallet("sYourSecret...")

🎯 23. Bounty Marketplace

Ang iyong agent ay maaaring mag-post ng mga bounty para sa mga tao upang tapusin ang mga gawain.

bridge = MarketplaceBridge(agent)
bounty_id = bridge.post_bounty(title="Translation task", reward_usd=75.0)

🦾 24. Integrasyon sa CrewAI

Nagbibigay-daan sa mga agent ng CrewAI na gumawa ng otonom na pagbabayad sa iba pang mga miyembro ng koponan.

from iagent_pay.integrations.crewai import iAgentPayCrewTool
pay_tool = iAgentPayCrewTool(chain="BASE", max_amount_usdc=5.0)

🔗 25. Integrasyon sa LangChain

Nagpapahintulot sa mga chain ng LangChain na magpadala ng mga pagbabayad sa crypto bilang isang tool.

from iagent_pay.integrations.langchain import iAgentPayTool
pay_tool = iAgentPayTool()

💰 26. Modelo ng Bayad sa Nakaipong Dami

Sa halip na maningil ng mga porsyento, ang iAgent-Pay ay nagpapatupad ng flat fee na $1.00 USD para sa bawat $1,000.00 USD ng nakaipong transaksyon.

🔒 27. Mga Mode ng Seguridad na Multisig at Human-in-the-Loop

Ang agent ay maaaring tumakbo sa tatlong magkakaibang mode ng pamamahala:

ALLOWANCE_ONLY: Tanging mga limitasyon lamang ng badyet.
PROPOSAL_ONLY: Nangangailangan ng pirma ng tao para sa bawat transaksyon.
HYBRID: Awtomatikong magtransak para sa maliliit na halaga; humingi ng pirma para sa malalaki.

🔄 28. Awtomatikong Pagbabalanse ng Likido (Auto-Swap Fallback)

Kung kulang ang balanse sa USDC ng iyong agent, maaari nitong awtomatikong i-swap ang ETH o SOL upang matapos ang transaksyon.

agent = AgentPay(enable_auto_swap=True)

🔑 29. Nakapreserbang Backup at Pagpapanumbalik ng Key

Maaari kang gumawa ng password-encrypted backup ng mga credential ng iyong agent upang i-migrate sa ibang server:

agent.backup_wallet("backup.enc", password="MyPassword")

📦 30. Batch na Transaksyon (Batch Transactions / Multicall)

Magpadala ng maramihang pagbabayad sa isang transaksyon upang makatipid ng gas nang hanggang 30%.

txs = agent.pay_token_batch(payments, token="USDC", wait=True)

🔄 31. Awtomatikong Pag-ikot ng RPC na may Exponential Backoff

Kung sakaling magka-error ang RPC node, awtomatikong lilipat ang agent sa backup node nang hindi humihinto.

agent.rotate_rpc()

Enterprise Mode: Para sa mga korporasyon, sinusuportahan ng iAgent-Pay ang gasless na transaksyon gamit ang Paymasters.

📊 32. Corporate na Visual Dashboard (Read-Only)

Upang matiyak ang pinakamataas na antas ng seguridad, ang dashboard na ito ay read-only lamang. Pinoprotektahan nito ang agent laban sa mga panlabas na atake sa web.

Real-Time Monitor: Subaybayan ang USDC at native gas.
RPC Telemetry: Tingnan ang aktibong network node.
JSON Audit Export: I-download ang buong report ng agent sa isang click.

🧪 33. Advanced na Interactive Simulation Sandbox

Mayroong sandbox simulation environment sa control panel kung saan maaari mong subukan ang agent nang walang tunay na pondo.

Simulated Capital na $10,000.00 USDC: Magsimula sa virtual na balanse upang subukan ang transaksyon.
Feature Toggles: Buksan o isara ang Safety Kernel, Auto-Swap, at Human-in-the-Loop upang masaksihan ang reaksyon ng agent.

🔑 34. Ephemeral Zero-Custody Session Keys

Pinapayagan ng iAgent-Pay ang pag-delegate ng pansamantalang kapangyarihan sa pagpirma sa mga agent nang hindi ibinubunyag ang master private key. Gumagana ang agent sa loob ng mga pre-approved na patakaran.

Single Transaction Cap: Pinipigilan ang pagpapadala ng malalaking bayad.
Daily Limit: Nililimitahan ang kabuuang gastos bawat araw.
TTL Expiry: Awtomatikong nag-eexpire ang mga key pagkatapos ng tinukoy na oras.

session_key = SessionKeyManager.create_session(
    owner_account=owner_account,
    allowed_tokens=["USDC"],
    daily_limit_usd=100.0,
    max_tx_usd=20.0,
    validity_seconds=3600
)

🏅 35. Pagsunod at Pagpapatunay ng Tiwala (Know Your Agent - KYA)

Ipinapakilala ng iAgent-Pay ang pamantayan ng **Know Your Agent (KYA)** upang patunayan ang reputasyon at pagkakakilanlan ng mga agent sa Web3 ecosystem gamit ang mga W3C DID.

W3C Standard DIDs: Mga ID sa format na did:iagent:<hash>.
Trust Levels: Dynamic na lebel ng tiwala mula UNKNOWN hanggang ELITE batay sa matagumpay na transaksyon.

identity = AgentIdentity.create(name="ResearcherBot", owner_address="0xAlice...")
registry.register(identity)

📘 Official Reference Manual: iAgent-Pay (v8.5.0)

Welcome to iAgent-Pay, the sharpest payment infrastructure for AI Agents. This technical manual dey teach you how to open 100% of your agents' power, so they go fit do transactions, collect money, and invest by themselves for the whole world.

🌎 1. Global Support & Multi-Chain Architecture

iAgent-Pay no be just local API; na global financial gateway. Our routing engine dey allow your agent to move money across the whole Web3 ecosystem.

Ethereum (ETH): Heavy liquidity, maximum security.
Base (BASE): Coinbase's Layer 2, beta for low transaction fees.
Solana (SOL): Super speed (thousands of TPS).

The agent is "Currency Agnostic" (e fit run any currency). Built-in currencies include: USDC, USDT, EURC (Euro), CNHC (Yuan), GYEN (Yen), MXNT (Peso).

from iagent_pay import AgentPay

# Agent specialized in the Asian market
agent = AgentPay(chain_name="BASE", default_stablecoin="CNHC")

⚡ 2. Core Features

A. Autonomous Payments (x402)

tx_hash = agent.pay_token(
    recipient_address="0xProvider...", 
    amount=5.0
)
print(f"Payment completed: {tx_hash}")

B. Invoicing

If your AI do work for client, e fit generate "Smart Invoice" sharp-sharp.

invoice_id = agent.invoices.create_invoice(
    amount=25.0, 
    customer_address="0xClient...", 
    description="Code Audit"
)

🛡️ 3. Safety Kernel (How We Keep Funds Safe)

To give financial freedom to software, you need sharp rules. The system dey check every single payment before e touch network.

Daily Limits: This one dey stop run-away agent from draining your account.
Smart Identity (ERC-8004): Agents get "Sovereign Identity" for blockchain, so nobody fit steal their private key.

# Limit to max $15 per day
agent = AgentPay(daily_limit=15.0)

# Mint Identity
identity = agent.identity.mint_soulbound_id("Bot", "0xOwner")

📈 4. Autonomous Treasury (DeFi Yields)

Automatically deposit extra savings inside global protocols like Aave v3, make you dey yield money while you dey sleep.

# Keep $50 in cash, invest the rest
agent.yield_manager.auto_invest(buffer_usd=50.0)

🏦 5. Fiat Bridge (Bank & Card Payments)

Client no get crypto? No wahala. iAgent-Pay dey connect straight to Stripe to put money inside normal bank account or charge credit card.

Stripe Transfer: Pay anyone with normal bank account.
ACH (US): Cheap direct bank transfer.
Smart Router: E dey choose the cheapest route automatically (crypto or bank).
Payment Link: Agent dey generate link for humans to pay without crypto.

from iagent_pay.fiat_bridge import FiatBridge

bridge = FiatBridge()

# Pay freelancer straight to bank account
bridge.send_stripe(amount_usd=150.0, stripe_account_id="acct_1M2...", description="Work payment")

# Create payment link for credit cards
link = bridge.create_payment_link(amount_usd=9.99, description="Premium API Access")
print(link["url"])  # → https://buy.stripe.com/...

# Smart router: USDC or Stripe
bridge.smart_send(amount_usd=25.0, recipient="client@company.com")

🌉 6. Cross-Chain Routing (AP2 Engine)

Agent fit hold money for one network (like Ethereum) and pay for another network (like Polygon). The AP2 Engine dey calculate all bridges to pick the fastest and cheapest one.

from iagent_pay.cross_chain import CrossChainRouter

router = CrossChainRouter()

# Move $100 USDC Base → Polygon automatically
tx = router.bridge_assets(
    source_chain="BASE",
    target_chain="POLYGON",
    amount=100.0,
    token="USDC"
)
print(f"Bridge complete: {tx}")

🤖 7. Fleet Management (Sub-Agents Fleet)

For teams with many agents. A **Master Agent** fit create and control specialized "sub-agents", each one with its own budget and isolated history.

from iagent_pay.sub_agents import SubAgentManager

manager = SubAgentManager(master_budget_usd=500.0)
researcher = manager.create("researcher", daily_limit_usd=20.0)
writer     = manager.create("writer",     daily_limit_usd=10.0)

researcher.kernel.check(amount=5.0, recipient="0xDataAPI...")
researcher.spend(5.0, "USDC", "Buy market data")

# Emergency pause
manager.pause("researcher")

🌐 8. Full Global Token Dictionary

Network	Supported Tokens	Use Case
Ethereum (ETH)	USDC, USDT, DAI, EURC, CNHC (Yuan), GYEN (Yen), XSGD, MXNT	High liquidity, max security
Base (BASE)	USDC, USDT, DAI, EURC, WETH	Low gas fees, Coinbase
Polygon (MATIC)	USDC, USDT, DAI, WETH	Fast micropayments

⚙️ 9. Advanced Safety Kernel Rules

from iagent_pay.safety_kernel import SafetyKernel, SafetyConfig

kernel = SafetyKernel(SafetyConfig(
    daily_limit_usd=100.0,
    weekly_limit_usd=500.0,
    session_limit_usd=20.0,
    max_tx_usd=10.0,
    max_tx_per_minute=5,
    max_tx_per_hour=50,
    human_approval_threshold_usd=50.0,
    allowed_recipients=["0xAlice...", "0xBob..."],
    enable_whitelist=True,
))

💳 10. Wallet Manager (How to Keep Keys)

This one dey create, import, and shield your agent's cryptographic keys. Supports AES-128 encrypted keystores and .env file format.

from iagent_pay.wallet_manager import WalletManager
wm = WalletManager()
wallet = wm.get_or_create_wallet(password="MySecurePassword123")
print(f"Agent Address: {wallet.address}")

🔤 11. Social Name Resolver (ENS & SNS)

Instead of copying long addresses like 0x7F5E..., your agent fit resolve clean names like ENS domains or Solana Name Service.

from iagent_pay.social_resolver import SocialResolver
resolver = SocialResolver()
address = resolver.resolve("vitalik.eth")

🔔 12. Real-Time Webhooks

from iagent_pay.webhooks import WebhookManager
wm = WebhookManager(default_secret="my-shared-secret")
wm.register("https://myserver.com/webhook", events=["payment.completed"])

👤 13. Human-in-the-Loop Confirmations

For big payments, the agent go pause and ask for human confirmation via Telegram, Slack, or terminal. If nobody answer, transaction go cancel.

from iagent_pay.human_loop import HumanApproval, HumanLoopConfig
hitl = HumanApproval(HumanLoopConfig(threshold_usd=20.0, timeout_seconds=300))
approved = hitl.request_approval(amount=50.0, currency="USDC", recipient="0xVendor...")

🔄 14. Swap Engine

Swap tokens automatically. The agent fit swap ETH to USDC, SOL to BONK, or any pair on Uniswap/Jupiter.

swap = agent.swap_engine
quote = swap.get_quote(input_token="SOL", output_token="USDC", amount=1.0)

🛒 15. Data Marketplace

Decentralized place where your agents fit buy and sell data with x402 protocol.

from iagent_pay.data_marketplace import get_marketplace
marketplace = get_marketplace()

🤝 16. Reputation System

Each agent dey maintain local reputation ledger (0-5 stars) for other agents. Check record before you pay any unknown agent.

rep = agent.reputation
rep.rate_peer("0xVendor...", score=4.8)

🤖 17. Claude & Cursor Integration (MCP Server)

iAgent-Pay fully compatible with Model Context Protocol (MCP). Claude fit tell your agent to do payment in normal language.

# Start MCP server:
# iagent-pay mcp-server

💻 18. Command Line Interface (CLI Tools)

Manage and test agents straight from terminal without writing Python code.

# Init new project
iagent-pay init my-agent
# Check status
iagent-pay status --chain BASE

🌐 19. x402 Server — Sell Your Own Data

If you get API with beta data, protect am and charge USDC automatically to any agent wey want access. Works with FastAPI & Flask.

app.add_middleware(X402Middleware, payment_address="0xAddr...", amount_usdc=0.10)

📊 20. Observability & Monitoring Dashboard

Real-time dashboard with stats for all payments. Anomaly detection included with Prometheus support.

from iagent_pay.observability import PaymentObserver
observer = PaymentObserver(ObservabilityConfig(enable_prometheus=True))

💵 21. Real-Time Pricing Engine

Query current price of ETH, SOL, and XRP from 3 sources at the same time.

pricing = PricingManager()
price = pricing.get_price("ETH")

🌊 22. XRP Ledger Network Support

Native support for XRP Ledger, one of the fastest networks for international payments.

agent_xrp = AgentPay(chain_name="XRP")
agent_xrp.xrpl.load_wallet("sYourSecret...")

🎯 23. Bounty Marketplace (BountyBridge)

Post bounties for humans to do tasks. Once job is verified, agent pay automatically.

bridge = MarketplaceBridge(agent)
bounty_id = bridge.post_bounty(title="Translation task", reward_usd=75.0)

🦾 24. CrewAI Integration

Allow CrewAI agents to make autonomous payments to other team members.

from iagent_pay.integrations.crewai import iAgentPayCrewTool
pay_tool = iAgentPayCrewTool(chain="BASE", max_amount_usdc=5.0)

🔗 25. LangChain Integration

Use crypto payments as native tool in any LangChain agent.

from iagent_pay.integrations.langchain import iAgentPayTool
pay_tool = iAgentPayTool()

💰 26. Volume Accumulation Fee Model

Instead of charging percentages on every transaction, settle flat fee of $1.00 USD for every $1,000.00 USD of total volume transacted.

🔒 27. Multisig & Human-in-the-Loop Security Modes

Run agent in three security levels:

ALLOWANCE_ONLY: Strictly follow set budgets.
PROPOSAL_ONLY: Wait for human signature on every payment.
HYBRID: Small payments are autonomous, big ones need human signature.

🔄 28. Auto-Liquidity-Balancing (Auto-Swap Fallback)

If stablecoin balance is too low, auto-swap native holdings (ETH or SOL) to complete the transaction.

agent = AgentPay(enable_auto_swap=True)

🔑 29. Encrypted Key Backup & Restore

Create secure backup of agent's wallet details with password encryption:

agent.backup_wallet("backup.enc", password="MyPassword")

📦 30. Batch Payments (Pipelined Multicall)

Send multiple payments at once to save gas by up to 30%.

txs = agent.pay_token_batch(payments, token="USDC", wait=True)

🔄 31. RPC Auto-Rotation with Backoff & Rate Limit Guard

If network node gets error, rotate to backup RPC provider automatically without halting.

agent.rotate_rpc()

Enterprise Mode: For big business, iAgent-Pay supports sponsor fee transactions using Paymasters.

📊 32. Corporate Visual Dashboard (Read-Only Panel)

For high cybersecurity, this dashboard is Read-Only. Attackers cannot change limits or take funds through the browser.

Real-Time Monitoring: View native gas and USDC balances.
RPC Telemetry: Track active RPC endpoints.
JSON Audit Export: Download full agent report in one click.

🧪 33. Advanced Interactive Simulation Sandbox

Simulation sandbox on the dashboard to test all features with mock money.

Initial Simulated Balance of $10,000.00 USDC: Start with mock funds and test swaps.
Feature Toggles: Play with Safety Kernel and Auto-Swap to see how agent behaves.

🔑 34. Ephemeral Zero-Custody Session Keys

Delegate temporary transaction signing power to your AI agents without giving them your main private key. Agents must obey rules signed by wallet owner.

Single Transaction Cap: Stop agent from sending big money at once.
Daily Limit: Restrict cumulative spending per day.
TTL Expiry: Temporary keys expire automatically after a set time.

session_key = SessionKeyManager.create_session(
    owner_account=owner_account,
    allowed_tokens=["USDC"],
    daily_limit_usd=100.0,
    max_tx_usd=20.0,
    validity_seconds=3600
)

🏅 35. Compliance & Trust Verification (Know Your Agent - KYA)

Verify agent record using **Know Your Agent (KYA)** standard with W3C DIDs and verifiable credentials.

W3C Standard DIDs: IDs in format did:iagent:<hash>.
Trust Levels: Dynamic trust ranking from UNKNOWN up to ELITE.

identity = AgentIdentity.create(name="ResearcherBot", owner_address="0xAlice...")
registry.register(identity)