Интеграция платежей LlamaIndex.
Нет пакета LlamaIndex, и он вам не нужен. Оберните реальный клиент blockchain0x в FunctionTool, и ваш агент сможет перемещать USDC и управлять платным запросом RAG на Base.
Специального пакета для LlamaIndex нет, и он вам не нужен. LlamaIndex превращает обычную функцию в tool с помощью , поэтому вы оборачиваете реальный Python client в функцию и добавляете его в или . Агент может отправлять USDC, закрывать invoices и читать wallets. Чтобы брать плату за каждый RAG query, ограничьте свой QueryEngineTool тем же способом. Платежи завершаются в Base.
Запросы RAG дорогие. Оплата за запрос делает экономику работающей.
Сила LlamaIndex заключается в генерации, дополненной извлечением: у вас есть векторный индекс по собственным документам (документы вашей компании, набор данных для исследований, юридический корпус), и агент отвечает, извлекая и обобщая соответствующие фрагменты. Каждый запрос стоит реальных денег в эмбеддингах, токенах LLM и часто вызовах сторонних API. Бесплатный неограниченный доступ сжигает бюджет; выставление счетов за каждый запрос соответствует структуре затрат.
Нет поставленного помощника для этого, и он вам не нужен. Вы управляете этим сами: внутри функции вашего QueryEngineTool проверьте, оплатил ли вызывающий (ваш собственный флаг, переключаемый вебхуком платежа) и либо выполните извлечение, либо верните цену. Функция кошелька и управление - это всего лишь несколько строк над реальным клиентом blockchain0x, который полностью держит политику - за запрос, за сессию, бесплатный уровень, а затем платный - в ваших руках.
Установите LlamaIndex и основной SDK. Одна переменная окружения.
Нет пакета blockchain0x LlamaIndex для добавления. Вы устанавливаете LlamaIndex (Python 3.10+, современные API FunctionAgent / ReActAgent / Workflows) и реальный основной SDK blockchain0x, затем пишете функцию ниже. Работает вместе с любым векторным хранилищем - 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 - это ключ sk_test_ для testnet или sk_live_ для mainnet из вашего dashboard; client читает его из environment. Если вы ограничиваете платные запросы, обработчику webhook дополнительно нужен BLOCKCHAIN0X_WEBHOOK_SECRET, который dashboard выдает один раз при создании или ротации webhook.
Функция, которая оплачивает, обернутая как FunctionTool.
Ниже приведена вся интеграция. send_usdc вызывает реальный клиент blockchain0x; FunctionTool.from_defaults оборачивает его, а FunctionAgent подбирает его как вызываемый инструмент. LlamaIndex считывает подсказки типов и документацию, чтобы построить схему. Добавьте свой собственный QueryEngineTool в список, и тот же агент сможет отвечать на запросы 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.
Переключите флаг оплаты, когда вебхук будет получен.
Когда платеж завершается, Blockchain0x отправляет подписанное событие payment.received на ваш URL вебхука. Помощник проверки поставляется в Node SDK; в службе Python вы проверяете вручную по документированному HMAC. Отметьте вызывающего как оплаченного в вашем собственном хранилище, и ваш инструмент с ограниченным доступом пропустит следующий вызов. Пример FastAPI ниже.
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}
Алгоритм - HMAC-SHA256 над строкой t.rawBody, сравнение с постоянным временем и окно повторного воспроизведения 300 секунд. Читайте необработанное тело через await request.body(), никогда не request.json() повторно сериализованное, потому что это изменяет байты, которые охватывает подпись. Отправленные события - payment.received, payment.sent, wallet.deployed и webhook.test. Для тяжелой последующей работы добавьте задачу в очередь (Celery, arq) и сразу ответьте 200, а не блокируйте обработчик.
Клиент, который вы оборачиваете, открыт. Читайте его.
Нет starter package для LlamaIndex, который можно было бы клонировать - рецепт выше и есть интеграция. SDK Blockchain0x открыты в GitHub; этот рецепт оборачивает Python SDK (blockchain0x-python), а полный набор методов приведен в docs. Используйте его как reference для body функций.
github.com/tosh-labs/blockchain0x-pythonПолный набор методов SDK и scopes описаны в the docs. Начните с ключа sk_test_ в Base Sepolia, затем переключитесь на sk_live_, когда функция начнет работать так, как вы ожидаете.
Пять ловушек, специфичных для LlamaIndex, которых следует избегать.
Эти данные поступают из нашего почтового ящика поддержки. Каждое из них экономит как минимум час отладки, как только вы о них узнаете.
Нет пакета LlamaIndex - вы оборачиваете SDK.
Blockchain0x поставляет адаптеры для LangChain и CrewAI, а также сервер MCP; нет отдельного пакета LlamaIndex. Рецепт выше - это путь: простая типизированная функция, которая вызывает реальный клиент blockchain0x, обернутая в FunctionTool.from_defaults. LlamaIndex читает сигнатуру и docstring, чтобы построить схему, поэтому держите docstring точным.
Запретите QueryEngineTool самостоятельно - ни один помощник этого не делает
Шаблон paid-RAG реальный и хороший, но нет помощника paid_query_engine_tool. Вы создаете его: в функции вашего инструмента запроса проверьте, оплатил ли вызывающий (ваш собственный магазин, обновленный вебхуком ниже) и выполняйте извлечение только если они оплатили, в противном случае верните цену. Это несколько строк, и вы сохраняете контроль над политикой доступа.
Суммы представлены в базовых единицах USDC, как строки
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 является асинхронным; вызов SDK является синхронным
Агенты LlamaIndex ориентированы на асинхронность - await agent.run(...). Вызов клиента blockchain0x внутри вашего инструмента является синхронным, что нормально для одного быстрого платежа, но блокирует цикл под нагрузкой. Если вы обрабатываете много параллельных запросов, оберните вызов SDK с помощью asyncio.to_thread, чтобы цикл событий оставался отзывчивым.
send_payment может ответить 503 на раннем этапе
payments.create по умолчанию не повторяет и может вернуть 503, пока адаптер цепочки не подключен к вашей сети. Поймайте ошибку внутри функции вашего инструмента и верните четкое сообщение, на которое модель может реагировать, вместо того чтобы позволить агенту зациклиться. Автоматически созданный ключ идемпотентности означает, что ручная попытка не приведет к двойной оплате.