Integração de pagamento LlamaIndex.
Não há pacote LlamaIndex, e você não precisa de um. Envolva o cliente blockchain0x real em um FunctionTool e seu agente pode mover USDC e controlar uma consulta RAG paga na Base.
Não existe um pacote específico para LlamaIndex, e você não precisa de um. O LlamaIndex transforma uma função simples em uma tool com , então você encapsula o cliente Python real em uma função e o adiciona a um ou . O agente pode enviar USDC, liquidar invoices e ler wallets. Para cobrar por consulta RAG, controle o seu próprio QueryEngineTool da mesma forma. Os pagamentos são liquidados na Base.
Consultas RAG são caras. Cobrar por consulta faz a economia funcionar.
A força do LlamaIndex é a geração aumentada por recuperação: você tem um índice vetorial sobre documentos proprietários (documentos da sua empresa, um conjunto de dados de pesquisa, um corpus legal), e o agente responde recuperando e resumindo os trechos relevantes. Cada consulta custa dinheiro real em embeddings, tokens LLM e muitas vezes chamadas de API de terceiros. O acesso ilimitado gratuito consome orçamento; a cobrança por consulta se encaixa na forma de custo.
Não há um helper enviado para isso, e você não precisa de um. Você controla isso você mesmo: dentro da função do seu QueryEngineTool, verifique se o chamador pagou (sua própria flag, alterada pelo webhook de pagamento) e execute a recuperação ou retorne um preço. A função da carteira e o controle estão ambos a algumas linhas sobre o cliente real do blockchain0x, que mantém a política - por consulta, por sessão, nível gratuito e depois pago - totalmente em suas mãos.
Instale LlamaIndex e o SDK principal. Uma variável de ambiente.
Não há pacote blockchain0x LlamaIndex para adicionar. Você instala LlamaIndex (Python 3.10+, as modernas APIs FunctionAgent / ReActAgent / Workflows) e o SDK principal blockchain0x real, e então escreve a função abaixo. Funciona junto com qualquer loja de vetores - 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 é uma chave sk_test_ de testnet ou sk_live_ de mainnet do seu painel; o cliente a lê do ambiente. Se você restringe consultas pagas, o handler de webhook também precisa de BLOCKCHAIN0X_WEBHOOK_SECRET, que o painel retorna uma única vez quando você cria ou rota um webhook.
Uma função que paga, encapsulada como um FunctionTool.
Abaixo está toda a integração. send_usdc chama o cliente real blockchain0x; FunctionTool.from_defaults o envolve, e FunctionAgent o pega como uma ferramenta chamável. LlamaIndex lê as dicas de tipo e a docstring para construir o esquema. Adicione sua própria QueryEngineTool à lista e o mesmo agente pode responder a consultas RAG também.
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.
Altere a bandeira de pago quando o webhook chegar.
Quando um pagamento é liquidado, Blockchain0x POSTa um evento payment.received assinado para sua URL de webhook. O helper de verificação está no SDK do Node; em um serviço Python você verifica manualmente contra o HMAC documentado. Marque o chamador como pago em seu próprio armazenamento, e sua ferramenta de consulta restrita permite que a próxima chamada passe. Exemplo de FastAPI abaixo.
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}
O algoritmo é HMAC-SHA256 sobre a string t.rawBody, uma comparação em tempo constante e uma janela de replay de 300 segundos. Leia o corpo bruto via await request.body(), nunca request.json() re-serialized, porque isso altera os bytes que a assinatura cobre. Os eventos enviados são payment.received, payment.sent, wallet.deployed e webhook.test. Para trabalhos de acompanhamento pesados, enfileire um trabalho (Celery, arq) e responda 200 imediatamente em vez de bloquear o manipulador.
O cliente que você está envolvendo é aberto. Leia-o.
Não existe um starter package do LlamaIndex para clonar - a receita acima é a integração. Os SDKs da blockchain0x são open source no GitHub; esta receita encapsula o Python SDK (blockchain0x-python), com a superfície completa de métodos na documentação. Leia como referência para os corpos das funções.
github.com/tosh-labs/blockchain0x-pythonA superfície completa de métodos e os escopos do SDK estão documentados em the docs. Comece com uma chave sk_test_ na Base Sepolia e depois mude para sk_live_ quando a função fizer o que você espera.
Cinco armadilhas específicas do LlamaIndex a evitar.
Estes vêm da nossa caixa de entrada de suporte. Cada um economiza pelo menos uma hora de depuração uma vez que você saiba sobre isso.
Não há pacote LlamaIndex - você envolve o SDK
Blockchain0x envia adaptadores para LangChain e CrewAI, além do servidor MCP; não há um pacote dedicado do LlamaIndex. A receita acima é o caminho: uma função tipada simples que chama o cliente real do blockchain0x, envolta com FunctionTool.from_defaults. O LlamaIndex lê a assinatura e a docstring para construir o esquema, então mantenha a docstring precisa.
Controle um QueryEngineTool você mesmo - nenhum helper faz isso
O padrão paid-RAG é real e bom, mas não há um helper paid_query_engine_tool. Você o constrói: na função da sua ferramenta de consulta, verifique se o chamador pagou (sua própria loja, atualizada pelo webhook abaixo) e execute a recuperação somente se ele tiver, caso contrário, retorne um preço. São algumas linhas, e você mantém o controle da política de acesso.
Os valores são unidades base de USDC, como strings
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 é assíncrono; a chamada do SDK é síncrona
Os agentes LlamaIndex são assíncronos - aguarde agent.run(...). A chamada do cliente blockchain0x dentro da sua ferramenta é síncrona, o que é bom para um único pagamento rápido, mas bloqueia o loop sob carga. Se você estiver atendendo a muitas consultas simultâneas, envolva a chamada do SDK com asyncio.to_thread para que o loop de eventos permaneça responsivo.
send_payment pode responder 503 logo no início
payments.create não tenta novamente por padrão e pode retornar 503 até que o adaptador de cadeia esteja configurado para sua rede. Capture o erro dentro da função da sua ferramenta e retorne uma mensagem clara que o modelo possa agir, em vez de deixar o agente em loop. A chave de idempotência criada automaticamente significa que uma nova tentativa manual não resultará em pagamento duplicado.