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

# Social Vault API

> Manage Social Vault security features

# Social Vault API

Endpoints for managing Social Vault security features.

## Get Vault Configuration

Get the user's Social Vault configuration.

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET "https://api.usmewe.com/v1/social-vault/config" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "isConfigured": true,
      "dailyLimit": "100.00",
      "timelockDuration": 86400,
      "requiredSignatures": 2,
      "guardianCount": 3,
      "isLocked": false,
      "hasDuressPin": true
    }
  }
  ```
</CodeGroup>

## Create Social Vault

Initialize a new Social Vault.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST "https://api.usmewe.com/v1/social-vault" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "dailyLimit": 100,
      "timelockDuration": 86400,
      "requiredSignatures": 2,
      "duressPin": "1234"
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "vaultAddress": "0x...",
      "dailyLimit": "100.00",
      "timelockDuration": 86400,
      "requiredSignatures": 2,
      "txHash": "0x...",
      "createdAt": "2024-01-15T12:00:00Z"
    }
  }
  ```
</CodeGroup>

### Configuration Parameters

| Parameter            | Type   | Description                       |
| -------------------- | ------ | --------------------------------- |
| `dailyLimit`         | number | Max instant withdrawal (USDC)     |
| `timelockDuration`   | number | Timelock in seconds (3600-604800) |
| `requiredSignatures` | number | Required guardian approvals       |
| `duressPin`          | string | 4-6 digit emergency code          |

## Deposit to Social Vault

Deposit USDC into Social Vault.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST "https://api.usmewe.com/v1/social-vault/deposit" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 500
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "amount": "500.00",
      "newBalance": "1500.00",
      "txHash": "0x..."
    }
  }
  ```
</CodeGroup>

## Instant Withdrawal

Withdraw within daily limit (no timelock).

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST "https://api.usmewe.com/v1/social-vault/withdraw/instant" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 50,
      "recipient": "0x..."
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "amount": "50.00",
      "recipient": "0x...",
      "remainingDailyLimit": "50.00",
      "newBalance": "1450.00",
      "txHash": "0x..."
    }
  }
  ```
</CodeGroup>

## Request Large Withdrawal

Request withdrawal exceeding daily limit (requires timelock + approvals).

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST "https://api.usmewe.com/v1/social-vault/withdraw/request" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 500,
      "recipient": "0x..."
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "withdrawalId": "wd_abc123",
      "amount": "500.00",
      "recipient": "0x...",
      "status": "pending",
      "approvalsRequired": 2,
      "approvalsReceived": 0,
      "executeAfter": "2024-01-16T12:00:00Z",
      "expiresAt": "2024-01-22T12:00:00Z"
    }
  }
  ```
</CodeGroup>

## List Pending Withdrawals

Get all pending withdrawal requests.

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET "https://api.usmewe.com/v1/social-vault/withdrawals/pending" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "withdrawalId": "wd_abc123",
        "amount": "500.00",
        "recipient": "0x...",
        "status": "pending",
        "approvalsRequired": 2,
        "approvalsReceived": 1,
        "executeAfter": "2024-01-16T12:00:00Z",
        "approvers": ["guardian_1"]
      }
    ]
  }
  ```
</CodeGroup>

## Approve Withdrawal (Guardian)

As a guardian, approve a pending withdrawal.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST "https://api.usmewe.com/v1/social-vault/withdrawals/{withdrawalId}/approve" \
    -H "Authorization: Bearer GUARDIAN_TOKEN"
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "withdrawalId": "wd_abc123",
      "approvalsReceived": 2,
      "approvalsRequired": 2,
      "status": "approved",
      "canExecuteAt": "2024-01-16T12:00:00Z"
    }
  }
  ```
</CodeGroup>

## Execute Withdrawal

Execute an approved withdrawal after timelock.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST "https://api.usmewe.com/v1/social-vault/withdrawals/{withdrawalId}/execute" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "withdrawalId": "wd_abc123",
      "amount": "500.00",
      "recipient": "0x...",
      "status": "executed",
      "txHash": "0x...",
      "newBalance": "1000.00"
    }
  }
  ```
</CodeGroup>

## Cancel Withdrawal

Cancel a pending withdrawal request.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST "https://api.usmewe.com/v1/social-vault/withdrawals/{withdrawalId}/cancel" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "withdrawalId": "wd_abc123",
      "status": "cancelled"
    }
  }
  ```
</CodeGroup>

## Emergency Lock (Duress PIN)

Lock the vault using duress PIN.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST "https://api.usmewe.com/v1/social-vault/lock" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "duressPin": "1234"
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "status": "locked",
      "lockedAt": "2024-01-15T12:00:00Z",
      "guardiansNotified": true
    }
  }
  ```
</CodeGroup>

<Warning>
  Emergency lock cancels all pending withdrawals and notifies guardians silently.
</Warning>

## Manage Guardians

### Add Guardian

```bash theme={null}
curl -X POST "https://api.usmewe.com/v1/social-vault/guardians" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"walletAddress": "0x..."}'
```

### Remove Guardian

```bash theme={null}
curl -X DELETE "https://api.usmewe.com/v1/social-vault/guardians/{guardianId}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### List Guardians

```bash theme={null}
curl -X GET "https://api.usmewe.com/v1/social-vault/guardians" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Webhook Events

```json theme={null}
// Withdrawal requested
{
  "event": "social_vault.withdrawal_requested",
  "data": {
    "withdrawalId": "wd_abc123",
    "amount": "500.00",
    "requiredApprovals": 2
  }
}

// Withdrawal approved
{
  "event": "social_vault.withdrawal_approved",
  "data": {
    "withdrawalId": "wd_abc123",
    "approver": "guardian_1",
    "totalApprovals": 1
  }
}

// Vault locked
{
  "event": "social_vault.locked",
  "data": {
    "vaultOwner": "user_abc123",
    "lockedAt": "2024-01-15T12:00:00Z"
  }
}
```

## Error Responses

| Code | Error                  | Description                  |
| ---- | ---------------------- | ---------------------------- |
| 400  | `DAILY_LIMIT_EXCEEDED` | Amount exceeds daily limit   |
| 400  | `VAULT_LOCKED`         | Vault is locked              |
| 403  | `NOT_GUARDIAN`         | Not authorized as guardian   |
| 409  | `TIMELOCK_ACTIVE`      | Withdrawal still in timelock |