Integrazione dei pagamenti LlamaIndex.
Non esiste un pacchetto LlamaIndex, e non ne hai bisogno. Avvolgi il vero client blockchain0x in un FunctionTool e il tuo agente può muovere USDC e gestire una query RAG a pagamento su Base.
Non esiste un package specifico per LlamaIndex, e non ne hai bisogno. LlamaIndex trasforma una normale funzione in uno strumento con , quindi avvolgi il vero client Python in una funzione e lo aggiungi a un o . L'agente può inviare USDC, saldare fatture e leggere i wallet. Per addebitare per ogni query RAG, proteggi il tuo QueryEngineTool nello stesso modo. I pagamenti si regolano su Base.
Le query RAG sono costose. Addebitare per query rende l'economia sostenibile.
La forza di LlamaIndex è la generazione aumentata dal recupero: hai un indice vettoriale su documenti proprietari (i documenti della tua azienda, un dataset di ricerca, un corpus legale), e l'agente risponde recuperando e riassumendo i frammenti pertinenti. Ogni query costa soldi reali in embeddings, token LLM e spesso chiamate API di terze parti. L'accesso gratuito illimitato consuma budget; la fatturazione per query si adatta alla forma dei costi.
Non esiste un helper fornito per questo, e non ne hai bisogno. Gestisci tu stesso: all'interno della funzione del tuo QueryEngineTool, controlla se il chiamante ha pagato (la tua bandiera, attivata dal webhook di pagamento) e esegui il recupero o restituisci un prezzo. La funzione wallet e il gating sono entrambe poche righe sopra il vero client blockchain0x, che mantiene la politica - per query, per sessione, livello gratuito poi a pagamento - interamente nelle tue mani.
Installa LlamaIndex e il core SDK. Una variabile d'ambiente.
Non esiste un pacchetto blockchain0x LlamaIndex da aggiungere. Installa LlamaIndex (Python 3.10+, le moderne API FunctionAgent / ReActAgent / Workflows) e il vero core SDK blockchain0x, quindi scrivi la funzione qui sotto. Funziona insieme a qualsiasi store vettoriale - 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 è una chiave sk_test_ per testnet o sk_live_ per mainnet dalla tua dashboard; il client la legge dall'ambiente. Se proteggi le query a pagamento, il gestore webhook richiede inoltre BLOCKCHAIN0X_WEBHOOK_SECRET, che la dashboard restituisce una sola volta quando crei o ruoti un webhook.
Una funzione che paga, avvolta come un FunctionTool.
Di seguito è l'intera integrazione. send_usdc chiama il reale client blockchain0x; FunctionTool.from_defaults lo avvolge e FunctionAgent lo raccoglie come uno strumento chiamabile. LlamaIndex legge gli suggerimenti di tipo e la docstring per costruire lo schema. Aggiungi il tuo QueryEngineTool alla lista e lo stesso agente può rispondere anche alle query 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.
Capovolgi il flag pagato quando il webhook arriva.
Quando un pagamento si stabilisce, Blockchain0x POSTa un evento firmato payment.received al tuo URL webhook. L'helper di verifica è incluso nel Node SDK; in un servizio Python verifichi manualmente contro l'HMAC documentato. Segna il chiamante come pagato nel tuo store e il tuo strumento di query protetto consente alla chiamata successiva di passare. Esempio FastAPI qui sotto.
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'algoritmo è HMAC-SHA256 sulla stringa t.rawBody, un confronto a tempo costante e una finestra di replay di 300 secondi. Leggi il corpo grezzo tramite await request.body(), mai request.json() rieseguito, perché ciò cambia i byte coperti dalla firma. Gli eventi spediti sono payment.received, payment.sent, wallet.deployed e webhook.test. Per lavori di follow-up pesanti, accoda un lavoro (Celery, arq) e rispondi 200 immediatamente anziché bloccare il gestore.
Il client che stai avvolgendo è aperto. Leggilo.
Non esiste un starter package LlamaIndex da clonare - la ricetta sopra è l'integrazione. Gli SDK blockchain0x sono open source su GitHub; questa ricetta incapsula il Python SDK (blockchain0x-python), con la superficie completa dei metodi nella documentazione. Consultala come riferimento per i body delle funzioni.
github.com/tosh-labs/blockchain0x-pythonLa superficie completa dei metodi dell'SDK e gli scope sono documentati in the docs. Inizia con una chiave sk_test_ su Base Sepolia, poi passa a sk_live_ quando la funzione si comporta come previsto.
Cinque trappole specifiche di LlamaIndex da evitare.
Questi provengono dalla nostra casella di supporto. Ognuno risparmia almeno un'ora di debug una volta che ne sei a conoscenza.
Non esiste un pacchetto LlamaIndex - avvolgi l'SDK
Blockchain0x fornisce adattatori per LangChain e CrewAI oltre al server MCP; non esiste un pacchetto LlamaIndex dedicato. La ricetta sopra è il percorso: una funzione tipizzata semplice che chiama il reale client blockchain0x, avvolta con FunctionTool.from_defaults. LlamaIndex legge la firma e la docstring per costruire lo schema, quindi mantieni la docstring accurata.
Limita un QueryEngineTool da solo - nessun helper lo fa
Il pattern paid-RAG è reale e valido, ma non esiste un helper paid_query_engine_tool. Lo costruisci: nella funzione del tuo strumento di query, controlla se il chiamante ha pagato (il tuo store, aggiornato dal webhook qui sotto) e esegui il recupero solo se ha pagato, altrimenti restituisci un prezzo. Sono poche righe, e mantieni il controllo della politica di gating.
Gli importi sono unità base USDC, come stringhe
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 è async; la chiamata SDK è sync
Gli agenti LlamaIndex sono orientati all'asincrono - await agent.run(...). La chiamata del client blockchain0x all'interno del tuo strumento è sincrona, il che va bene per un pagamento rapido singolo ma blocca il ciclo sotto carico. Se stai servendo molte query concorrenti, avvolgi la chiamata SDK con asyncio.to_thread affinché il ciclo degli eventi rimanga reattivo.
send_payment può rispondere 503 all'inizio
payments.create non ripete per impostazione predefinita e può restituire 503 fino a quando l'adattatore della catena non è collegato alla tua rete. Cattura l'errore all'interno della funzione del tuo strumento e restituisci un messaggio chiaro su cui il modello può agire, piuttosto che lasciare che l'agente continui a girare. La chiave di idempotenza auto-mintata significa che un tentativo manuale non comporterà un pagamento doppio.