Social Vault API

Endpoints for managing Social Vault security features.

Get Vault Configuration

Get the user’s Social Vault configuration.

curl -X GET "https://api.usmewe.com/v1/social-vault/config" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "data": {
    "isConfigured": true,
    "dailyLimit": "100.00",
    "timelockDuration": 86400,
    "requiredSignatures": 2,
    "guardianCount": 3,
    "isLocked": false,
    "hasDuressPin": true
  }
}

Initialize a new Social Vault.

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"
  }'

{
  "success": true,
  "data": {
    "vaultAddress": "0x...",
    "dailyLimit": "100.00",
    "timelockDuration": 86400,
    "requiredSignatures": 2,
    "txHash": "0x...",
    "createdAt": "2024-01-15T12:00:00Z"
  }
}

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 USDC into Social Vault.

curl -X POST "https://api.usmewe.com/v1/social-vault/deposit" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500
  }'

{
  "success": true,
  "data": {
    "amount": "500.00",
    "newBalance": "1500.00",
    "txHash": "0x..."
  }
}

Instant Withdrawal

Withdraw within daily limit (no timelock).

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..."
  }'

{
  "success": true,
  "data": {
    "amount": "50.00",
    "recipient": "0x...",
    "remainingDailyLimit": "50.00",
    "newBalance": "1450.00",
    "txHash": "0x..."
  }
}

Request Large Withdrawal

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

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..."
  }'

{
  "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"
  }
}

List Pending Withdrawals

Get all pending withdrawal requests.

curl -X GET "https://api.usmewe.com/v1/social-vault/withdrawals/pending" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "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"]
    }
  ]
}

Approve Withdrawal (Guardian)

As a guardian, approve a pending withdrawal.

curl -X POST "https://api.usmewe.com/v1/social-vault/withdrawals/{withdrawalId}/approve" \
  -H "Authorization: Bearer GUARDIAN_TOKEN"

{
  "success": true,
  "data": {
    "withdrawalId": "wd_abc123",
    "approvalsReceived": 2,
    "approvalsRequired": 2,
    "status": "approved",
    "canExecuteAt": "2024-01-16T12:00:00Z"
  }
}

Execute Withdrawal

Execute an approved withdrawal after timelock.

curl -X POST "https://api.usmewe.com/v1/social-vault/withdrawals/{withdrawalId}/execute" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "data": {
    "withdrawalId": "wd_abc123",
    "amount": "500.00",
    "recipient": "0x...",
    "status": "executed",
    "txHash": "0x...",
    "newBalance": "1000.00"
  }
}

Cancel Withdrawal

Cancel a pending withdrawal request.

curl -X POST "https://api.usmewe.com/v1/social-vault/withdrawals/{withdrawalId}/cancel" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "data": {
    "withdrawalId": "wd_abc123",
    "status": "cancelled"
  }
}

Emergency Lock (Duress PIN)

Lock the vault using duress PIN.

curl -X POST "https://api.usmewe.com/v1/social-vault/lock" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "duressPin": "1234"
  }'

{
  "success": true,
  "data": {
    "status": "locked",
    "lockedAt": "2024-01-15T12:00:00Z",
    "guardiansNotified": true
  }
}

Emergency lock cancels all pending withdrawals and notifies guardians silently.

Manage Guardians

Add Guardian

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

Remove Guardian

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

List Guardians

curl -X GET "https://api.usmewe.com/v1/social-vault/guardians" \
  -H "Authorization: Bearer YOUR_TOKEN"

Webhook Events

// 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

​Social Vault API

​Get Vault Configuration

​Create Social Vault

​Configuration Parameters

​Deposit to Social Vault

​Instant Withdrawal

​Request Large Withdrawal

​List Pending Withdrawals

​Approve Withdrawal (Guardian)

​Execute Withdrawal

​Cancel Withdrawal

​Emergency Lock (Duress PIN)

​Manage Guardians

​Add Guardian

​Remove Guardian

​List Guardians

​Webhook Events

​Error Responses

Social Vault API

Get Vault Configuration

Create Social Vault

Configuration Parameters

Deposit to Social Vault

Instant Withdrawal

Request Large Withdrawal

List Pending Withdrawals

Approve Withdrawal (Guardian)

Execute Withdrawal

Cancel Withdrawal

Emergency Lock (Duress PIN)

Manage Guardians

Add Guardian

Remove Guardian

List Guardians

Webhook Events

Error Responses