Intégration de paiement LlamaIndex.
Il n'y a pas de package LlamaIndex, et vous n'en avez pas besoin. Encapsulez le vrai client blockchain0x dans un FunctionTool et votre agent peut déplacer USDC et gérer une requête RAG payante sur Base.
Il n'existe pas de package spécifique à LlamaIndex, et vous n'en avez pas besoin. LlamaIndex transforme une fonction simple en outil avec , donc vous encapsulez le vrai client Python dans une fonction et l'ajoutez à un ou . L'agent peut envoyer des USDC, régler des factures et lire des wallets. Pour facturer par requête RAG, protégez votre propre QueryEngineTool de la même manière. Les paiements sont réglés sur Base.
Les requêtes RAG sont coûteuses. Facturer par requête rend l'économie viable.
La force de LlamaIndex est la génération augmentée par la récupération : vous avez un index vectoriel sur des documents propriétaires (les documents de votre entreprise, un ensemble de données de recherche, un corpus juridique), et l'agent répond en récupérant et en résumant les morceaux pertinents. Chaque requête coûte de l'argent réel en embeddings, en jetons LLM et souvent en appels d'API tiers. Un accès gratuit illimité épuise le budget ; la facturation par requête correspond à la forme des coûts.
Il n'y a pas d'assistant expédié pour cela, et vous n'en avez pas besoin. Vous le gérez vous-même : à l'intérieur de la fonction de votre QueryEngineTool, vérifiez si l'appelant a payé (votre propre indicateur, basculé par le webhook de paiement) et soit exécutez la récupération, soit renvoyez un prix. La fonction de portefeuille et le contrôle sont tous deux quelques lignes au-dessus du vrai client blockchain0x, qui maintient la politique - par requête, par session, niveau gratuit puis payant - entièrement entre vos mains.
Installez LlamaIndex et le SDK de base. Une variable d'environnement.
Il n'y a pas de package blockchain0x LlamaIndex à ajouter. Vous installez LlamaIndex (Python 3.10+, les API modernes FunctionAgent / ReActAgent / Workflows) et le vrai SDK de base blockchain0x, puis écrivez la fonction ci-dessous. Fonctionne avec n'importe quel magasin de vecteurs - Pinecone, Qdrant, Chroma, Weaviate, LlamaIndex Cloud.
pip install llama-index blockchain0xexport BLOCKCHAIN0X_API_KEY=sk_test_... # sk_test_ = Base Sepolia, sk_live_ = Base mainnet
BLOCKCHAIN0X_API_KEY est une clé sk_test_ testnet ou sk_live_ mainnet de votre tableau de bord ; le client la lit depuis l'environnement. Si vous restreignez les requêtes payantes, le gestionnaire de webhook a également besoin de BLOCKCHAIN0X_WEBHOOK_SECRET, que le tableau de bord renvoie une fois lorsque vous créez ou faites tourner un webhook.
Une fonction qui paie, enveloppée comme un FunctionTool.
Voici l'intégration complète. send_usdc appelle le véritable client blockchain0x ; FunctionTool.from_defaults l'encapsule, et FunctionAgent le récupère en tant qu'outil appelable. LlamaIndex lit les indications de type et la docstring pour construire le schéma. Ajoutez votre propre QueryEngineTool à la liste et le même agent peut également répondre aux requêtes RAG.
from llama_index.core.tools import FunctionTool from llama_index.core.agent.workflow import FunctionAgent from llama_index.llms.openai import OpenAI from blockchain0x import Client blockchain0x = Client() # reads BLOCKCHAIN0X_API_KEY from the environment def send_usdc(agent_id: str, to: str, amount_wei: str) -> str: """Send a USDC payment from an agent wallet. amount_wei is USDC base units (6 decimals), so "10000" is 0.01 USDC. """ return str( blockchain0x.payments.create(body={"agentId": agent_id, "to": to, "amountWei": amount_wei}) ) # Wrap the plain function as a LlamaIndex tool. No dedicated package needed. pay_tool = FunctionTool.from_defaults(fn=send_usdc) agent = FunctionAgent( tools=[pay_tool], # plus your own QueryEngineTool over a RAG index llm=OpenAI(model="gpt-4o"), system_prompt="You pay vendor invoices in USDC within owner-set limits.", ) response = await agent.run( "Pay 0.01 USDC from agent agt_123 to 0xVendor for the dataset." )
When the agent decides to pay, it calls send_usdc, the SDK submits the transfer, and you get a transaction hash back. amount_wei is base units, so 0.01 USDC is "10000". A sk_test_ key keeps it on Base Sepolia until you switch to sk_live_. To charge for a query instead, put the same paid check at the top of your QueryEngineTool's function.
Inversez le drapeau de paiement lorsque le webhook arrive.
Lorsque qu'un paiement est réglé, Blockchain0x envoie un événement signé payment.received à votre URL de webhook. L'outil de vérification est inclus dans le SDK Node ; dans un service Python, vous vérifiez manuellement contre le HMAC documenté. Marquez l'appelant comme payé dans votre propre magasin, et votre outil de requête sécurisé laisse passer l'appel suivant. Exemple FastAPI ci-dessous.
import hmac, hashlib, os, time from fastapi import FastAPI, Request, HTTPException app = FastAPI() SECRET = os.environ["BLOCKCHAIN0X_WEBHOOK_SECRET"].encode() @app.post("/webhooks/payment") async def receive(request: Request): raw = await request.body() # RAW bytes - do not parse first sig = request.headers.get("X-Blockchain0x-Signature", "") ts = request.headers.get("X-Blockchain0x-Timestamp", "") parts = dict(p.split("=", 1) for p in sig.split(",") if "=" in p) t, v1 = parts.get("t", ts), parts.get("v1", sig) want = hmac.new(SECRET, t.encode() + b"." + raw, hashlib.sha256).hexdigest() if not hmac.compare_digest(want, v1) or abs(time.time() - int(t)) > 300: raise HTTPException(status_code=401) if request.headers.get("X-Blockchain0x-Event-Type") == "payment.received": await trigger_followup() # USDC landed - serve the paid query return {"ok": True}
L'algorithme est HMAC-SHA256 sur la chaîne t.rawBody, une comparaison en temps constant, et une fenêtre de répétition de 300 secondes. Lisez le corps brut via await request.body(), jamais request.json() re-sérialisé, car cela change les octets que la signature couvre. Les événements expédiés sont payment.received, payment.sent, wallet.deployed, et webhook.test. Pour un travail de suivi lourd, mettez une tâche en file d'attente (Celery, arq) et répondez 200 immédiatement plutôt que de bloquer le gestionnaire.
Le client que vous enveloppez est ouvert. Lisez-le.
Il n'y a pas de package de démarrage LlamaIndex à cloner - la recette ci-dessus est l'intégration. Les SDK blockchain0x sont open source sur GitHub ; cette recette encapsule le SDK Python (blockchain0x-python), avec la surface complète des méthodes dans la documentation. Lisez-le pour une référence sur les corps de fonction.
github.com/tosh-labs/blockchain0x-pythonLa surface complète des méthodes SDK et les portées sont documentées dans la documentation. Commencez avec une clé sk_test_ sur Base Sepolia, puis passez à sk_live_ lorsque la fonction fonctionne comme vous l'attendez.
Cinq pièges spécifiques à LlamaIndex à éviter.
Celles-ci proviennent de notre boîte de réception de support. Chacune permet d'économiser au moins une heure de débogage une fois que vous en êtes informé.
Il n'y a pas de package LlamaIndex - vous encapsulez le SDK
Blockchain0x expédie des adaptateurs pour LangChain et CrewAI ainsi que le serveur MCP ; il n'y a pas de package LlamaIndex dédié. La recette ci-dessus est le chemin : une fonction typée ordinaire qui appelle le véritable client blockchain0x, encapsulée avec FunctionTool.from_defaults. LlamaIndex lit la signature et la docstring pour construire le schéma, alors gardez la docstring précise.
Contrôlez un QueryEngineTool vous-même - aucun helper ne le fait
Le modèle paid-RAG est réel et bon, mais il n'y a pas d'aide paid_query_engine_tool. Vous le construisez : dans la fonction de votre outil de requête, vérifiez si l'appelant a payé (votre propre magasin, mis à jour par le webhook ci-dessous) et ne lancez la récupération que s'il a payé, sinon renvoyez un prix. C'est quelques lignes, et vous gardez le contrôle de la politique de contrôle.
Les montants sont des unités de base USDC, sous forme de chaînes
payments.create takes amountWei: a string of USDC base units, not a float. USDC has 6 decimals, so 0.01 USDC is "10000" and 5 USDC is "5000000". Type the tool argument as str. LlamaIndex passes tool args through pydantic, which will happily coerce a float and lose precision, so keep it a string end to end.
FunctionAgent.run est asynchrone ; l'appel SDK est synchrone
Les agents LlamaIndex sont d'abord asynchrones - await agent.run(...). L'appel client blockchain0x à l'intérieur de votre outil est synchrone, ce qui est acceptable pour un paiement rapide unique mais bloque la boucle sous charge. Si vous traitez de nombreuses requêtes simultanées, enveloppez l'appel SDK avec asyncio.to_thread afin que la boucle d'événements reste réactive.
send_payment peut répondre 503 tôt
payments.create ne réessaie pas par défaut et peut renvoyer 503 jusqu'à ce que l'adaptateur de chaîne soit câblé pour votre réseau. Attrapez l'erreur à l'intérieur de votre fonction d'outil et renvoyez un message clair sur lequel le modèle peut agir, plutôt que de laisser l'agent boucler. La clé d'idempotence générée automatiquement signifie qu'un réessai manuel ne paiera pas deux fois.