Pydantic AI 결제 통합.
Pydantic AI 패키지가 없으며, 필요하지도 않습니다. @agent.tool_plain로 타입이 지정된 함수를 등록하고 실제 blockchain0x 클라이언트를 호출하면 에이전트가 Base에서 USDC를 이동할 수 있습니다.
Pydantic AI 전용 패키지는 없으며, 필요하지도 않습니다. Pydantic AI는 로 함수를 검증된 도구로 바꾸므로, 실제 Python 클라이언트를 타입이 지정된 함수로 감싸면 에이전트가 USDC 전송, 인보이스 정산, 지갑 조회를 할 수 있습니다. 이 도구는 모델이 아니라 HTTP API를 호출하기 때문에 OpenAI, Anthropic, Google, Mistral, Groq 및 다른 모든 Pydantic AI 제공자에서 동작합니다. 결제는 Base에서 정산됩니다.
Pydantic AI의 타입 지정이 승리합니다. 결제에도 사용하세요.
Pydantic AI의 핵심은 강력한 타입 지정입니다: 에이전트 입력은 타입이 지정되고, 출력도 타입이 지정되며, 의존성도 타입이 지정되고, 재시도도 타입이 지정됩니다. 프레임워크는 LLM 호출을 통해 전파되지 않도록 경계에서 잘못된 데이터를 거부합니다. 귀하의 지갑 도구는 바로 그것에 기반합니다 - 인수를 타입으로 선언하고, Pydantic AI는 모델이 호출되기 전에 서명 및 문서 문자열에서 검증된 스키마를 생성합니다.
실질적인 이점: 모델이 기본 단위 문자열 대신 부동 소수점으로 send_usdc를 호출하려고 하면, 실패는 우리에게 HTTP 호출이 이루어지기 전에 Pydantic의 검증 레이어에서 발생합니다. API에서 암호화된 필드 경로로 422를 받는 대신 유용한 메시지가 있는 명확한 ValidationError를 볼 수 있습니다. 이것이 바로 일반 어댑터를 찾는 대신 클라이언트를 직접 래핑해야 하는 이유입니다 - 와이어까지의 모든 타이핑을 유지합니다.
Pydantic AI 및 핵심 SDK를 설치하세요. 두 개의 키.
추가할 blockchain0x Pydantic AI 패키지가 없습니다. Pydantic AI(Python 3.10+)와 실제 blockchain0x 코어 SDK를 설치한 후 아래의 함수를 작성합니다. 그것이 전체 의존성 목록입니다.
pip install pydantic-ai blockchain0xexport OPENAI_API_KEY=sk-... export BLOCKCHAIN0X_API_KEY=sk_test_... # sk_test_ = Base Sepolia, sk_live_ = Base mainnet
OPENAI_API_KEY (또는 사용하는 provider에 해당하는 키). BLOCKCHAIN0X_API_KEY는 dashboard의 sk_test_ testnet 또는 sk_live_ mainnet 키이며, client는 이를 environment에서 읽습니다. agent가 돈도 받는 경우, webhook handler에는 추가로 BLOCKCHAIN0X_WEBHOOK_SECRET가 필요합니다.
지불을 하는 타입 지정 함수, 도구로 등록됩니다.
아래는 전체 통합입니다. send_usdc는 실제 blockchain0x 클라이언트를 호출합니다; @agent.tool_plain은 타입 힌트와 문서 문자열로 구축된 스키마로 등록합니다. 이를 실행하면 에이전트가 Base에서 USDC를 이동하며, 호출 전에 인수가 검증됩니다.
from pydantic_ai import Agent from blockchain0x import Client blockchain0x = Client() # reads BLOCKCHAIN0X_API_KEY from the environment agent = Agent( "openai:gpt-4o", system_prompt="You pay vendor invoices in USDC within owner-set limits.", ) # Register a plain function as a tool. No dedicated package needed. @agent.tool_plain 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}) ) result = agent.run_sync( "Pay 0.01 USDC from agent agt_123 to 0xVendor for the dataset." ) print(result.output)
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_. Want a typed result object instead of a string? Set the agent's output_type to your own Pydantic model and return it from the tool. Add read and settle functions the same way.
서명된 웹후크로 수신 결제를 확인하십시오.
내 에이전트가 USDC를 수신하는 경우, 폴링 대신 웹후크로 확인하세요. verify 헬퍼는 Node SDK에 포함되어 있으며; Python 서비스에서는 문서화된 HMAC에 대해 수동으로 검증합니다. 타입이 지정된 이벤트를 원하면, 자신의 Pydantic 모델을 정의하고 서명이 확인된 후 원시 본문을 model_validate_json으로 검증하세요 - 타입 지정은 귀하가 추가해야 합니다. 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 - run the next step return {"ok": True}
알고리즘은 문자열 t.rawBody에 대한 HMAC-SHA256, 상수 시간 비교 및 300초 재생 창입니다. 원시 본문을 await request.body()를 통해 읽으십시오; request.json()을 다시 직렬화하지 마십시오, 그렇게 하면 서명이 포함하는 바이트가 변경됩니다. 전송된 이벤트는 payment.received, payment.sent, wallet.deployed 및 webhook.test입니다; X-Blockchain0x-Event-Type 헤더를 좁혀서 분기하십시오.
래핑하고 있는 클라이언트는 공개되어 있습니다. 읽어보십시오.
복제할 Pydantic AI starter package는 없습니다 - 위의 recipe가 바로 integration입니다. blockchain0x SDK는 GitHub에서 open source로 제공됩니다. 이 recipe는 Python SDK(blockchain0x-python)를 감싸며, 전체 method surface는 docs에 있습니다. function body 참고용으로 읽으세요.
github.com/tosh-labs/blockchain0x-python전체 SDK method surface와 scope는 the docs에 문서화되어 있습니다. Base Sepolia에서 sk_test_ 키로 시작한 다음, function이 예상대로 동작하면 sk_live_로 전환하세요.
Pydantic AI에 특화된 피해야 할 다섯 가지 함정.
Pydantic AI의 강력한 타입 지정은 경계에서 대부분의 통합 버그를 잡아냅니다; 이는 몇 가지가 통과하는 것입니다.
Pydantic AI 패키지가 없습니다 - 도구를 등록합니다.
Blockchain0x는 LangChain 및 CrewAI와 MCP 서버를 위한 어댑터를 제공합니다. 전용 Pydantic AI 패키지는 없습니다. 위의 레시피는 경로입니다: 실제 blockchain0x 클라이언트를 호출하는 @agent.tool_plain로 장식된 일반 타입 함수입니다. Pydantic AI는 시그니처와 docstring을 읽어 검증된 도구 스키마를 구축하므로, 이는 Pydantic AI를 위해 온 정확한 타입 승리입니다.
금액을 문자열로 유지하세요; Pydantic이 이를 유지하도록 하세요.
payments.create takes amountWei: a string of USDC base units (6 decimals), so 0.01 USDC is "10000" and 5 USDC is "5000000". Type the tool argument as str and Pydantic AI rejects a float at the boundary with a clear ValidationError, before any HTTP call. That is the whole point of doing this in Pydantic AI - the malformed value never reaches the API.
send_payment는 초기 단계에서 503을 반환할 수 있습니다.
payments.create는 기본적으로 재시도하지 않으며 체인 어댑터가 귀하의 네트워크에 연결될 때까지 503을 반환할 수 있습니다. 도구 내에서 오류를 포착하고 모델이 작동할 수 있는 명확한 메시지를 반환하세요. 자동 발행된 멱등성 키는 수동 재시도가 이중 결제를 발생시키지 않음을 의미합니다.
제공자 접두사가 있는 모델 문자열
Pydantic AI는 제공자 접두사가 있는 모델 문자열을 사용합니다: 'openai:gpt-4o', 'anthropic:claude-3-5-sonnet-latest', 'google-gla:gemini-1.5-pro'. 접두사를 생략하면 '알 수 없는 모델' 오류가 발생합니다. 귀하의 도구는 HTTP API를 호출하기 때문에 제공자에 구애받지 않으며, 접두사를 자유롭게 교환해도 지갑 기능은 변경되지 않습니다.
tool_plain vs tool (RunContext)
함수가 실행에서 아무것도 필요하지 않을 때는 위와 같이 @agent.tool_plain을 사용하십시오. 도구 내에서 에이전트의 의존성이 필요하다면(요청별 클라이언트 ID, 지출 한도), @agent.tool을 사용하고 첫 번째 인수를 ctx: RunContext[Deps]로 선언하여 ctx.deps를 읽습니다. 두 가지를 혼합하면 - tool_plain에서 ctx 인수를 선언하면 - 등록 시 TypeError가 발생합니다.