요구 사항: Python 3.9+
클라이언트 초기화
import os
from agentwallex import AgentWallex
aw = AgentWallex(
api_key=os.environ["AGENTWALLEX_API_KEY"],
environment="sandbox", # "sandbox" or "production"
timeout=30, # Request timeout in seconds (default: 30)
)
| 매개변수 | 타입 | 기본값 | 설명 |
|---|
api_key | str | 필수 | API 키 (awx_...) |
environment | str | "sandbox" | "sandbox" 또는 "production" |
base_url | str | None | 커스텀 기본 URL (환경 설정을 재정의) |
timeout | int | 30 | 요청 타임아웃(초) |
Python SDK는 완전한 비동기 방식입니다. 모든 메서드는 코루틴을 반환하며 await해야 합니다.
에이전트
aw.agents.create()
MPC 보안 지갑을 갖춘 새 에이전트를 생성합니다.
agent = await aw.agents.create(
name="my-agent",
chain="eip155:8453",
policies={
"max_transaction_amount": "100",
"daily_limit": "1000",
"allowed_addresses": ["0x..."],
"allowed_tokens": ["USDC"],
},
metadata={"team": "growth"},
)
print(f"Agent ID: {agent.id}")
print(f"Wallet: {agent.wallet.address}")
aw.agents.get(agent_id)
agent = await aw.agents.get("agent_abc123")
aw.agents.list()
result = await aw.agents.list(
limit=20,
offset=0,
status="active",
)
for agent in result.agents:
print(f"{agent.name}: {agent.wallet.address}")
aw.agents.freeze(agent_id) / aw.agents.unfreeze(agent_id)
# Freeze — immediate
await aw.agents.freeze("agent_abc123")
# Unfreeze — subject to 10-minute cool-down
await aw.agents.unfreeze("agent_abc123")
aw.payments.send()
직접 온체인 결제를 전송합니다.
tx = await aw.payments.send(
agent_id="agent_abc123",
to="0xRecipientAddress",
amount="50.00",
token="USDC",
memo="Payment for API access",
)
print(f"Hash: {tx.hash}")
print(f"Status: {tx.status}")
print(f"Fee: {tx.fee}")
aw.payments.get(transaction_id)
tx = await aw.payments.get("tx_xyz789")
aw.payments.list()
result = await aw.payments.list(
agent_id="agent_abc123",
limit=50,
status="confirmed",
)
for tx in result.transactions:
print(f"{tx.amount} {tx.token} -> {tx.status}")
x402 소액 결제
aw.x402.create_session()
session = await aw.x402.create_session(
agent_id="agent_abc123",
budget_limit="100.00",
chain="eip155:84532",
ttl_seconds=3600,
allowed_urls=["https://paid-api.example.com/v1/data"],
)
aw.x402.check()
info = await aw.x402.check(url="https://paid-api.example.com/v1/data")
aw.x402.pay()
result = await aw.x402.pay(
agent_id="agent_abc123",
target_url="https://paid-api.example.com/v1/data",
session_id=session.id,
chain="eip155:84532",
)
aw.x402.session_pay(session_id, target_url)
await aw.x402.session_pay(
session.id,
target_url="https://paid-api.example.com/v1/data",
)
aw.x402.http_interceptor()
x402 v2 챌린지를 자동으로 처리하는 인터셉터를 생성합니다:
fetch_with_payment = aw.x402.http_interceptor(
agent_id="agent_abc123",
chain="eip155:84532",
)
# Automatically handles 402 -> pay -> retry
response = await fetch_with_payment("https://paid-api.example.com/v1/data")
data = response.json()
aw.policies.update()
await aw.policies.update(
"agent_abc123",
max_transaction_amount="200",
daily_limit="2000",
allowed_addresses=["0xAddr1", "0xAddr2"],
velocity_limit={"max_count": 100, "window_seconds": 3600},
)
aw.policies.get(agent_id)
policies = await aw.policies.get("agent_abc123")
aw.policies.apply_template()
await aw.policies.apply_template("agent_abc123", "conservative")
aw.webhooks.create()
webhook = await aw.webhooks.create(
url="https://your-app.com/webhooks/agentwallex",
events=[
"payment.completed",
"payment.failed",
"agent.frozen",
"policy.violated",
],
secret="whsec_your_signing_secret",
)
오류 처리
from agentwallex import AgentWallexError, PolicyViolationError
try:
tx = await aw.payments.send(
agent_id="agent_abc123",
to="0xRecipientAddress",
amount="50.00",
token="USDC",
)
except PolicyViolationError as e:
print(f"Policy violated: {e.rule}")
print(f"Details: {e.message}")
except AgentWallexError as e:
print(f"API error [{e.code}]: {e.message}")
except Exception as e:
print(f"Unexpected error: {e}")
| 오류 클래스 | 발생 시점 |
|---|
AgentWallexError | 모든 API 오류의 기본 클래스 |
PolicyViolationError | 정책 엔진에 의해 거래가 차단됨 |
AuthenticationError | 유효하지 않거나 누락된 API 키 |
NotFoundError | 리소스가 존재하지 않음 |
RateLimitError | 속도 제한 초과 |
타입 힌트
Python SDK는 IDE 지원 및 정적 분석을 위한 전체 타입 힌트를 포함합니다:
from agentwallex.types import (
Agent,
Payment,
Transaction,
Policy,
X402Session,
WebhookEvent,
)
asyncio 사용법
SDK는 비동기 우선 설계입니다. 비동기 컨텍스트 내에서 사용하세요:
import asyncio
from agentwallex import AgentWallex
async def main():
aw = AgentWallex(api_key="awx_your_api_key", environment="sandbox")
agent = await aw.agents.create(
name="my-agent",
chain="eip155:84532",
)
print(f"Created agent: {agent.id}")
asyncio.run(main())
