Integración de pagos de LlamaIndex.
No hay paquete LlamaIndex, y no necesitas uno. Envuelve el cliente real de blockchain0x en un FunctionTool y tu agente puede mover USDC y gestionar una consulta RAG pagada en Base.
No existe un paquete específico de LlamaIndex, y no lo necesitas. LlamaIndex convierte una función simple en una herramienta con , así que envuelves el cliente Python real de en una función y lo agregas a un o . El agente puede enviar USDC, liquidar facturas y leer wallets. Para cobrar por cada consulta RAG, protege tu propio QueryEngineTool de la misma forma. Los pagos se liquidan en Base.
Las consultas RAG son costosas. Cobrar por consulta hace que la economía funcione.
La fortaleza de LlamaIndex es la generación aumentada por recuperación: tienes un índice vectorial sobre documentos propietarios (los documentos de tu empresa, un conjunto de datos de investigación, un corpus legal), y el agente responde recuperando y resumiendo los fragmentos relevantes. Cada consulta cuesta dinero real en embeddings, tokens de LLM y a menudo llamadas a API de terceros. El acceso gratuito ilimitado quema presupuesto; la facturación por consulta se ajusta a la forma de costo.
No hay un helper enviado para esto, y no necesitas uno. Tú mismo lo controlas: dentro de la función de tu QueryEngineTool, verifica si el llamador ha pagado (tu propia bandera, cambiada por el webhook de pago) y ejecuta la recuperación o devuelve un precio. La función de la billetera y el control son solo unas pocas líneas sobre el verdadero cliente de blockchain0x, que mantiene la política - por consulta, por sesión, nivel gratuito y luego pagado - completamente en tus manos.
Instala LlamaIndex y el SDK principal. Una variable de entorno.
No hay paquete de blockchain0x LlamaIndex para agregar. Instalas LlamaIndex (Python 3.10+, las modernas APIs FunctionAgent / ReActAgent / Workflows) y el verdadero SDK principal de blockchain0x, luego escribes la función a continuación. Funciona junto a cualquier almacén de vectores - 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 es una clave sk_test_ testnet o sk_live_ mainnet de tu panel de control; el cliente la lee del entorno. Si limitas consultas pagadas, el manejador de webhook también necesita BLOCKCHAIN0X_WEBHOOK_SECRET, que el panel de control devuelve una vez cuando creas o rotas un webhook.
Una función que paga, envuelta como un FunctionTool.
A continuación se presenta toda la integración. send_usdc llama al cliente real de blockchain0x; FunctionTool.from_defaults lo envuelve, y FunctionAgent lo recoge como una herramienta callable. LlamaIndex lee las sugerencias de tipo y la docstring para construir el esquema. Agrega tu propio QueryEngineTool a la lista y el mismo agente también puede responder consultas 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.
Cambia la bandera de pagado cuando el webhook llega.
Cuando un pago se liquida, Blockchain0x envía un evento firmado payment.received a tu URL de webhook. El ayudante de verificación se envía en el SDK de Node; en un servicio de Python verificas manualmente contra el HMAC documentado. Marca al llamador como pagado en tu propia tienda, y tu herramienta de consulta restringida permite que la siguiente llamada pase. Ejemplo de FastAPI a continuación.
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}
El algoritmo es HMAC-SHA256 sobre la cadena t.rawBody, una comparación en tiempo constante y una ventana de repetición de 300 segundos. Lee el cuerpo sin procesar a través de await request.body(), nunca request.json() re-serializado, porque eso cambia los bytes que cubre la firma. Los eventos enviados son payment.received, payment.sent, wallet.deployed y webhook.test. Para trabajos de seguimiento pesados, encola un trabajo (Celery, arq) y responde 200 inmediatamente en lugar de bloquear el controlador.
El cliente que estás envolviendo es abierto. Léelo.
No hay un paquete de inicio de LlamaIndex para clonar - la receta anterior es la integración. Los SDK de blockchain0x son de código abierto en GitHub; esta receta envuelve el SDK de Python (blockchain0x-python), con la superficie completa de métodos en la documentación. Léelo como referencia para los cuerpos de las funciones.
github.com/tosh-labs/blockchain0x-pythonLa superficie completa de métodos del SDK y los alcances están documentados en la documentación. Comienza con una clave sk_test_ contra Base Sepolia, luego cambia a sk_live_ cuando la función haga lo que esperas.
Cinco trampas específicas de LlamaIndex a evitar.
Estos provienen de nuestra bandeja de entrada de soporte. Cada uno ahorra al menos una hora de depuración una vez que lo conoces.
No hay paquete LlamaIndex - envuelves el SDK
Blockchain0x envía adaptadores para LangChain y CrewAI además del servidor MCP; no hay un paquete dedicado de LlamaIndex. La receta anterior es el camino: una función tipada simple que llama al cliente real de blockchain0x, envuelta con FunctionTool.from_defaults. LlamaIndex lee la firma y la docstring para construir el esquema, así que mantenga la docstring precisa.
Controla un QueryEngineTool tú mismo - ningún ayudante lo hace
El patrón paid-RAG es real y bueno, pero no hay un ayudante paid_query_engine_tool. Tú lo construyes: en la función de tu herramienta de consulta, verifica si el llamador ha pagado (tu propia tienda, actualizada por el webhook a continuación) y solo ejecuta la recuperación si lo ha hecho, de lo contrario devuelve un precio. Son unas pocas líneas, y mantienes el control de la política de acceso.
Las cantidades son unidades base de USDC, como cadenas
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 es asíncrono; la llamada SDK es síncrona
Los agentes de LlamaIndex son primero asíncronos - await agent.run(...). La llamada del cliente blockchain0x dentro de tu herramienta es sincrónica, lo cual está bien para un solo pago rápido pero bloquea el bucle bajo carga. Si estás sirviendo muchas consultas concurrentes, envuelve la llamada del SDK con asyncio.to_thread para que el bucle de eventos se mantenga receptivo.
send_payment puede responder 503 temprano
payments.create no reintenta por defecto y puede devolver 503 hasta que el adaptador de cadena esté conectado a su red. Capture el error dentro de la función de su herramienta y devuelva un mensaje claro que el modelo pueda utilizar, en lugar de dejar que el agente se repita. La clave de idempotencia generada automáticamente significa que un reintento manual no pagará el doble.