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

# 보안 아키텍처

> 신원 확인, 정책 엔진, MPC 서명, 사람 개입의 4개 보안 레이어가 에이전트를 보호합니다.

## 개요

AgentWallex는 AI 에이전트가 **절대 개인 키에 접근해서는 안 된다**는 원칙을 기반으로 구축되었습니다. 대신 거래는 다자간 연산(MPC)을 사용하여 서명되며, 단일 당사자가 완전한 키를 보유하지 않습니다.

플랫폼은 4개의 독립적인 레이어를 통해 보안을 적용합니다. 거래가 블록체인에 브로드캐스트되기 전에 모든 레이어를 통과해야 합니다.

## 4개의 보안 레이어

### 레이어 1: 신원 확인 및 인증

모든 API 요청은 2개의 토큰 시스템을 사용하여 인증됩니다:

* **API Key** (`awx_...`) — 장기 유효, 계정을 식별합니다. 환경 변수에 안전하게 저장하세요.
* **Session Token** — 단기 유효, 특정 에이전트 및 작업에 범위가 지정됩니다. 자동으로 교체됩니다.

```typescript theme={null}
// API key authenticates your account
const aw = new AgentWallex({ apiKey: process.env.AGENTWALLEX_API_KEY! });

// Session tokens are managed internally by the SDK
// Each agent gets its own scoped session
```

**주요 속성:**

| 속성       | 세부 사항                  |
| -------- | ---------------------- |
| 키 교체     | 다운타임 없이 가능             |
| 세션 만료    | 구성 가능: 1-24시간          |
| 권한 범위    | 에이전트별                  |
| IP 허용 목록 | Growth 및 Enterprise 플랜 |

### 레이어 2: 정책 엔진

모든 거래는 서명 전에 정책 엔진을 통과해야 합니다. 정책은 순서대로 평가되며 — 첫 번째 위반이 거래를 중단합니다.

정책 엔진이 지원하는 항목:

* 지출 한도 (거래별, 일별, 월별)
* 주소 화이트리스트 및 블랙리스트
* 토큰 제한
* 속도 제어 (속도 제한)
* 시간 기반 일정 규칙
* 사람 승인 라우팅

전체 구성 세부 사항은 [정책 엔진](/ko/features/policy-engine)을 참조하세요.

### 레이어 3: MPC 서명 (Paratro)

AgentWallex는 Paratro의 2-of-3 임계값 MPC 프로토콜을 사용합니다:

| 샤드   | 보유자                | 목적    |
| ---- | ------------------ | ----- |
| 샤드 1 | AgentWallex 서명 서비스 | 활성 서명 |
| 샤드 2 | 독립 커스터디 노드         | 활성 서명 |
| 샤드 3 | 콜드 스토리지            | 복구 전용 |

**핵심 보안 속성:**

* 전체 개인 키는 메모리에서 **절대 재구성되지 않습니다**
* 3개 중 2개의 샤드로 거래에 서명할 수 있습니다
* 단일 샤드의 유출은 지갑을 손상시키지 않습니다
* 키 생성은 분산 키 생성(DKG)을 사용합니다 — 단일 당사자가 전체 키를 보지 않습니다

### 레이어 4: 사람 개입

고액 또는 비정상 거래의 경우 AgentWallex는 사람 승인으로 라우팅할 수 있습니다:

* 구성 가능한 임계값을 초과하는 거래
* 새로운 (이전에 보지 못한) 주소로의 거래
* 이상 모니터링에 의해 감지된 비정상 패턴

```json theme={null}
{
  "event": "approval.requested",
  "data": {
    "transactionId": "tx_pending_123",
    "agentId": "agent_abc123",
    "amount": "2500.00",
    "reason": "Amount exceeds humanApprovalThreshold (1000)",
    "expiresAt": "2025-01-15T11:00:00Z"
  }
}
```

승인은 대시보드, API 또는 웹훅 통합을 통해 처리할 수 있습니다.

## 2단계 정책 아키텍처

AgentWallex는 두 가지 독립적인 수준에서 정책을 적용합니다:

### 비즈니스 레이어 (개발자 구성)

커스텀 규칙 — 지출 한도, 화이트리스트, 속도 제어. API 또는 대시보드를 통해 설정되며 언제든지 업데이트할 수 있습니다.

### 인프라 안전망 (Paratro 적용)

API 호출로 **재정의할 수 없는** MPC 서명 레벨의 하드 리밋:

| 제어 항목    | 기본값      | 설명                  |
| -------- | -------- | ------------------- |
| 절대 일일 상한 | \$50,000 | 비즈니스 정책과 관계없는 하드 상한 |
| 이상 탐지    | 활성화됨     | ML 기반 패턴 분석         |
| 긴급 동결    | 항상 사용 가능 | 즉시 지갑 잠금            |
| 쿨다운 기간   | 10분      | 동결 후 즉시 해제 불가       |

<Warning>
  API 키가 유출되더라도 인프라 안전망이 치명적인 손실을 방지합니다. 공격자는 Paratro가 적용한 한도를 재정의할 수 없습니다.
</Warning>

## 키 관리 수명 주기

### 키 생성

키는 분산 키 생성(DKG)을 사용하여 생성됩니다. 어떤 시점에서도 어떤 당사자도 전체 개인 키를 보지 않습니다:

1. 3개의 MPC 노드 각각이 랜덤 공유를 생성합니다.
2. 공유가 암호학적으로 결합되어 공개 키를 생성합니다.
3. 해당 개인 키는 분산된 샤드로만 존재합니다.

### 키 교체

키 샤드는 지갑 주소를 변경하지 않고 주기적으로 교체됩니다. 이를 "사전 비밀 공유"라고 하며 — 교체 후 이전 샤드는 무용지물이 됩니다.

### 긴급 동결

승인된 당사자는 즉시 지갑을 동결할 수 있습니다:

<CodeGroup>
  ```typescript SDK theme={null}
  await aw.agents.freeze("agent_abc123");
  ```

  ```bash API theme={null}
  curl -X PUT https://api.agentwallex.com/api/v1/agents/agent_abc123/status \
    -H "X-API-Key: awx_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"status": "inactive"}'
  ```
</CodeGroup>

동결된 지갑은 명시적으로 해제될 때까지(필수 쿨다운 기간 포함) 거래에 서명할 수 없습니다.

## 감사 로깅

모든 작업은 변경 불가능하게 기록됩니다:

* 모든 API 요청 (IP, 유저 에이전트, 타임스탬프 포함)
* 모든 정책 평가 (통과/실패 사유 포함)
* 모든 서명 작업
* 모든 동결/해제 이벤트
* 모든 웹훅 전달

| 플랜         | 로그 보관 기간 |
| ---------- | -------- |
| Starter    | 90일      |
| Growth     | 1년       |
| Enterprise | 커스텀      |

API를 통해 감사 로그를 조회합니다:

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