> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentwallex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> agentwallex Python 패키지에 대한 전체 레퍼런스 — 비동기 우선 설계와 전체 API 커버리지를 제공합니다.

## 설치

```bash theme={null}
pip install agentwallex
```

**요구 사항:** Python 3.9+

## 클라이언트 초기화

```python theme={null}
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`        | 요청 타임아웃(초)                    |

<Note>
  Python SDK는 완전한 비동기 방식입니다. 모든 메서드는 코루틴을 반환하며 await해야 합니다.
</Note>

## 에이전트

### `aw.agents.create()`

MPC 보안 지갑을 갖춘 새 에이전트를 생성합니다.

```python theme={null}
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)`

```python theme={null}
agent = await aw.agents.get("agent_abc123")
```

### `aw.agents.list()`

```python theme={null}
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)`

```python theme={null}
# Freeze — immediate
await aw.agents.freeze("agent_abc123")

# Unfreeze — subject to 10-minute cool-down
await aw.agents.unfreeze("agent_abc123")
```

## 결제

### `aw.payments.send()`

직접 온체인 결제를 전송합니다.

```python theme={null}
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)`

```python theme={null}
tx = await aw.payments.get("tx_xyz789")
```

### `aw.payments.list()`

```python theme={null}
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()`

```python theme={null}
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()`

```python theme={null}
info = await aw.x402.check(url="https://paid-api.example.com/v1/data")
```

### `aw.x402.pay()`

```python theme={null}
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)`

```python theme={null}
await aw.x402.session_pay(
    session.id,
    target_url="https://paid-api.example.com/v1/data",
)
```

### `aw.x402.http_interceptor()`

x402 v2 챌린지를 자동으로 처리하는 인터셉터를 생성합니다:

```python theme={null}
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()`

```python theme={null}
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)`

```python theme={null}
policies = await aw.policies.get("agent_abc123")
```

### `aw.policies.apply_template()`

```python theme={null}
await aw.policies.apply_template("agent_abc123", "conservative")
```

## 웹훅

### `aw.webhooks.create()`

```python theme={null}
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",
)
```

## 오류 처리

```python theme={null}
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 지원 및 정적 분석을 위한 전체 타입 힌트를 포함합니다:

```python theme={null}
from agentwallex.types import (
    Agent,
    Payment,
    Transaction,
    Policy,
    X402Session,
    WebhookEvent,
)
```

## asyncio 사용법

SDK는 비동기 우선 설계입니다. 비동기 컨텍스트 내에서 사용하세요:

```python theme={null}
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())
```