> ## 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.

# 모범 사례

> 보안 팁, 정책 설정, 모니터링 권장 사항, 프로덕션 준비 체크리스트를 제공합니다.

## 보안

<Warning>
  클라이언트 측 코드, 공개 저장소 또는 애플리케이션 로그에 API 키를 노출하지 마세요.
</Warning>

* **시크릿 관리자에 API 키 저장** — AWS Secrets Manager, HashiCorp Vault 또는 플랫폼의 시크릿 솔루션을 사용하세요. 프로덕션에서 `.env` 파일 사용을 피하세요.
* **90일마다 키 교체** — 반복 알림을 설정하세요. 교체 방법은 [API 키](/ko/introduction/api-keys)를 참조하세요.
* **환경별 별도 키 사용** — 개발, 스테이징, 프로덕션 간에 키를 공유하지 마세요.
* **IP 허용 목록 활성화** — Growth 및 Enterprise 플랜에서 알려진 서버 IP로 API 접근을 제한하세요.
* **테스트에는 샌드박스 사용** — 프로덕션 키나 실제 자금으로 테스트하지 마세요.

## 정책 구성

<Tip>
  가능한 한 가장 제한적인 정책으로 시작하고 에이전트의 동작에 대한 확신이 생기면 점진적으로 완화하세요.
</Tip>

### 권장 초기 정책

```typescript theme={null}
await aw.policies.update("agent_abc123", {
  // Start with low limits
  maxTransactionAmount: "100",
  dailyLimit: "1000",
  monthlyLimit: "10000",

  // Whitelist trusted addresses only
  allowedAddresses: ["0xTrustedVendor1", "0xTrustedVendor2"],

  // Restrict to stablecoins
  allowedTokens: ["USDC"],

  // Prevent runaway loops
  velocityLimit: {
    maxCount: 50,
    windowSeconds: 3600,
  },

  // Human review for larger amounts
  requireHumanApproval: true,
  humanApprovalThreshold: "500",
});
```

### 정책 팁

* **allowedAddresses 사용** — 화이트리스트가 블랙리스트보다 안전합니다.
* **속도 제한 설정** — 에이전트가 무한 거래 루프에 빠지는 것을 방지합니다.
* **사람 승인 활성화** — 의미 있는 임계값 이상의 금액에 대해 활성화합니다.
* **주간 검토** — 에이전트 동작 패턴이 명확해지면 정책을 조정합니다.
* **템플릿 사용** — 일반적인 구성을 위한 재사용 가능한 템플릿을 생성합니다.

## 모니터링

### 주요 이벤트 구독

```typescript theme={null}
await aw.webhooks.create({
  url: "https://your-app.com/webhooks",
  events: [
    "payment.completed",
    "payment.failed",
    "policy.violated",
    "agent.frozen",
  ],
});
```

### 모니터링 항목

| 지표          | 이유                            |
| ----------- | ----------------------------- |
| 정책 위반       | 잘못 구성된 에이전트 또는 예상치 못한 동작을 나타냄 |
| 실패한 거래      | 잔액 부족 또는 체인 문제를 나타낼 수 있음      |
| 동결 이벤트      | 이상 탐지 또는 수동 조치에 의해 트리거됨       |
| 에이전트별 일일 지출 | 예산 초과를 조기에 감지                 |
| API 오류율     | 통합 문제를 감지                     |
| 웹훅 전달 실패    | 핸들러의 정상 작동을 보장                |

### 감사 로그

예상치 못한 활동에 대해 정기적으로 감사 로그를 검토하세요:

```bash theme={null}
curl -X GET "https://api.agentwallex.com/api/v1/audit-logs?page_num=1&page_size=50" \
  -H "X-API-Key: awx_your_api_key"
```

## 프로덕션 준비 체크리스트

서비스 시작 전에 이 체크리스트를 사용하세요:

* [ ] **API 키** — 프로덕션 키를 생성하고 시크릿 관리자에 저장
* [ ] **환경** — SDK를 `environment: "production"`으로 초기화
* [ ] **정책 구성** — 에이전트별 지출 한도, 주소 화이트리스트, 속도 제어
* [ ] **사람 승인** — 적절한 임계값으로 고액 거래에 대해 활성화
* [ ] **웹훅 등록** — `payment.completed`, `payment.failed`, `policy.violated`에 대한 핸들러 배포
* [ ] **웹훅 서명 검증** — 핸들러가 모든 전달에서 `X-AgentWallex-Signature`를 검증
* [ ] **오류 처리** — 일시적 오류에 대한 재시도 로직과 함께 SDK 오류를 캐치 및 로깅
* [ ] **모니터링** — 정책 위반, 실패한 거래, 동결 이벤트에 대한 알림 설정
* [ ] **감사 로그 접근** — 팀원이 대시보드에서 감사 로그를 볼 수 있는지 확인
* [ ] **긴급 절차** — 에이전트 동결 방법과 권한자를 문서화
* [ ] **키 교체 일정** — 90일 키 교체를 위한 캘린더 알림 설정
* [ ] **샌드박스 테스트** — 프로덕션 전환 전에 테스트넷에서 전체 플로우를 엔드투엔드 테스트
* [ ] **지갑 자금 조달** — 예상 거래량에 충분한 잔액으로 프로덕션 지갑에 자금 조달
* [ ] **속도 제한 이해** — 애플리케이션이 지수 백오프로 429 응답을 처리

<Info>
  AgentWallex 팀이 서비스 시작 전에 통합을 검토해 드립니다. 사전 출시 검토는 [support@agentwallex.com](mailto:support@agentwallex.com)으로 문의하세요.
</Info>