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

# Vault API

> Stake USDC and manage Trust Vault positions

# Vault API

Endpoints for managing Trust Vault staking positions.

## Get Vault Status

Get current vault statistics.

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET "https://api.usmewe.com/v1/vault/status"
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "totalDeposits": "1500000.00",
      "totalBorrowed": "1200000.00",
      "utilization": 0.80,
      "currentAPY": 0.075,
      "exchangeRate": 1.025,
      "tmUSDCSupply": "1463414.63"
    }
  }
  ```
</CodeGroup>

## Get User Position

Get the authenticated user's vault position.

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

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "userId": "user_abc123",
      "tmUSDCBalance": "1000.00",
      "usdcValue": "1025.00",
      "earnedYield": "25.00",
      "depositedAt": "2024-01-01T00:00:00Z",
      "lastYieldClaim": "2024-01-15T00:00:00Z"
    }
  }
  ```
</CodeGroup>

## Deposit USDC

Stake USDC into the Trust Vault.

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

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "depositAmount": "1000.00",
      "exchangeRate": 1.025,
      "tmUSDCReceived": "975.61",
      "newBalance": "1975.61",
      "txHash": "0x...",
      "xpEarned": 25
    }
  }
  ```
</CodeGroup>

### Deposit Parameters

| Parameter | Type   | Required | Description            |
| --------- | ------ | -------- | ---------------------- |
| `amount`  | number | Yes      | USDC amount to deposit |

<Note>
  You'll receive tmUSDC based on the current exchange rate. As yield accrues, the exchange rate increases.
</Note>

## Withdraw

Redeem tmUSDC for USDC.

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

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "tmUSDCRedeemed": "500.00",
      "exchangeRate": 1.025,
      "usdcReceived": "512.50",
      "remainingBalance": "475.61",
      "txHash": "0x..."
    }
  }
  ```
</CodeGroup>

### Withdraw Parameters

| Parameter      | Type   | Required | Description             |
| -------------- | ------ | -------- | ----------------------- |
| `tmUSDCAmount` | number | Yes      | tmUSDC amount to redeem |

## Get Yield History

Get historical yield earnings.

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET "https://api.usmewe.com/v1/vault/yield/history?period=30d" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "period": "30d",
      "totalYield": "15.75",
      "averageAPY": 0.072,
      "history": [
        {
          "date": "2024-01-15",
          "yield": "0.52",
          "apy": 0.075
        },
        {
          "date": "2024-01-14",
          "yield": "0.51",
          "apy": 0.074
        }
      ]
    }
  }
  ```
</CodeGroup>

## Calculate Potential Yield

Estimate yield for a deposit amount.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST "https://api.usmewe.com/v1/vault/yield/calculate" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 1000,
      "duration": 365
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "depositAmount": 1000,
      "duration": 365,
      "currentAPY": 0.075,
      "projectedYield": "75.00",
      "projectedTotal": "1075.00",
      "disclaimer": "APY varies based on utilization"
    }
  }
  ```
</CodeGroup>

## Get Interest Rate Model

Get current interest rate parameters.

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET "https://api.usmewe.com/v1/vault/rates"
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "utilization": 0.80,
      "borrowRate": 0.05,
      "supplyAPY": 0.075,
      "model": [
        {"utilization": 0.00, "borrowRate": 0.02, "supplyAPY": 0.01},
        {"utilization": 0.50, "borrowRate": 0.03, "supplyAPY": 0.03},
        {"utilization": 0.80, "borrowRate": 0.05, "supplyAPY": 0.075},
        {"utilization": 0.95, "borrowRate": 0.10, "supplyAPY": 0.10},
        {"utilization": 1.00, "borrowRate": 0.15, "supplyAPY": 0.12}
      ]
    }
  }
  ```
</CodeGroup>

## Get Transaction History

Get vault transaction history.

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

  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "tx_1",
        "type": "deposit",
        "usdcAmount": "1000.00",
        "tmUSDCAmount": "975.61",
        "exchangeRate": 1.025,
        "timestamp": "2024-01-15T10:00:00Z",
        "txHash": "0x..."
      },
      {
        "id": "tx_2",
        "type": "withdraw",
        "usdcAmount": "500.00",
        "tmUSDCAmount": "487.80",
        "exchangeRate": 1.025,
        "timestamp": "2024-01-10T15:00:00Z",
        "txHash": "0x..."
      }
    ],
    "pagination": {
      "total": 15,
      "limit": 10,
      "offset": 0,
      "hasMore": true
    }
  }
  ```
</CodeGroup>

## Webhook Events

```json theme={null}
// Deposit completed
{
  "event": "vault.deposit",
  "data": {
    "userId": "user_abc123",
    "usdcAmount": "1000.00",
    "tmUSDCReceived": "975.61"
  }
}

// Withdrawal completed
{
  "event": "vault.withdraw",
  "data": {
    "userId": "user_abc123",
    "tmUSDCRedeemed": "500.00",
    "usdcReceived": "512.50"
  }
}

// Yield distributed
{
  "event": "vault.yield_distributed",
  "data": {
    "totalYield": "1500.00",
    "newExchangeRate": 1.026
  }
}
```

## Error Responses

| Code | Error                    | Description              |
| ---- | ------------------------ | ------------------------ |
| 400  | `INSUFFICIENT_BALANCE`   | Not enough USDC/tmUSDC   |
| 400  | `AMOUNT_TOO_SMALL`       | Below minimum deposit    |
| 400  | `INSUFFICIENT_LIQUIDITY` | Not enough liquidity     |
| 503  | `VAULT_PAUSED`           | Vault temporarily paused |