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

# Wealth Engine

> Autonomous portfolio management: limit orders, DCA, multi-yield allocation, and Synthra V3 liquidity

<Info>
  **Live on Arc Testnet** - The Aegis Wealth Engine is fully operational. Agents
  can register limit orders, schedule DCA strategies, allocate across yield
  protocols, and withdraw from Synthra V3.
</Info>

## Overview

The Aegis Wealth Engine handles portfolio management for AI agents. It wraps limit orders, DCA schedules, yield allocation, and concentrated liquidity into one API. Agents get access to DeFi strategies without writing custom execution logic.

A background **Wealth Sentinel** runs every 5 minutes. It scans open limit orders and DCA schedules, then executes them when conditions match the trigger.

## Limit Orders

Register conditional swaps. They execute when the target price hits.

```bash theme={null}
curl -X POST https://api.aegisintent.xyz/v1/actions/wealth/limitOrder \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Aegis-Email: agent@example.com" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Aegis-Nonce: 0" \
  -d '{
    "tokenIn": "USDC",
    "tokenOut": "EURC",
    "amountIn": "100.00",
    "targetPrice": "0.92",
    "condition": "LTE"
  }'
```

### Limit Order Parameters

| Field         | Type   | Required | Description                                                                                           |
| ------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `tokenIn`     | string | Yes      | Input token symbol (e.g. `"USDC"`)                                                                    |
| `tokenOut`    | string | Yes      | Output token symbol (e.g. `"EURC"`)                                                                   |
| `amountIn`    | string | Yes      | Amount of the input token to swap                                                                     |
| `targetPrice` | string | Yes      | The price threshold that triggers execution                                                           |
| `condition`   | string | Yes      | `"LTE"` (price is less than or equal to target) or `"GTE"` (price is greater than or equal to target) |

### Cancel a Limit Order

```bash theme={null}
curl -X POST https://api.aegisintent.xyz/v1/actions/wealth/limitOrder/cancel \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Aegis-Email: agent@example.com" \
  -H "Content-Type: application/json" \
  -d '{"id": "d290f1ee-6c54-4b01-90e6-d701748f0851"}'
```

## Dollar-Cost Averaging (DCA)

Schedule recurring token purchases. The Wealth Sentinel handles each execution. The schedule auto-completes when the total order count is met.

```bash theme={null}
curl -X POST https://api.aegisintent.xyz/v1/actions/wealth/dca \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Aegis-Email: agent@example.com" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7b1c3d4e-5f6a-7b8c-9d0e-1f2a3b4c5d6e" \
  -H "X-Aegis-Nonce: 1" \
  -d '{
    "tokenIn": "USDC",
    "tokenOut": "cirBTC",
    "amountInPerTx": "25.00",
    "frequencyHours": 24,
    "totalOrders": 30
  }'
```

### DCA Parameters

| Field            | Type   | Required | Description                                       |
| ---------------- | ------ | -------- | ------------------------------------------------- |
| `tokenIn`        | string | Yes      | Input token symbol                                |
| `tokenOut`       | string | Yes      | Output token symbol                               |
| `amountInPerTx`  | string | Yes      | Amount to swap per execution                      |
| `frequencyHours` | number | Yes      | Hours between each execution (e.g. `24` = daily)  |
| `totalOrders`    | number | Yes      | Total number of orders to execute before stopping |

### DCA Lifecycle

DCA schedules move through these states:

| Status                      | Description                                      |
| --------------------------- | ------------------------------------------------ |
| `ACTIVE`                    | Running. The sentinel executes at each interval. |
| `COMPLETED`                 | All `totalOrders` finished.                      |
| `PAUSED_INSUFFICIENT_FUNDS` | Paused. Resumes when wallet is funded.           |
| `CANCELLED`                 | Manually cancelled by the agent.                 |
| `FAILED`                    | Permanently failed after exhausting retries.     |

<Tip>
  Check the progress of any DCA schedule via `GET /v1/actions/wealth/intents`.
  The response includes `ordersExecuted` and `totalOrders`, so the agent can report
  "12 of 30 DCA orders completed."
</Tip>

### Cancel a DCA Schedule

```bash theme={null}
curl -X POST https://api.aegisintent.xyz/v1/actions/wealth/dca/cancel \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Aegis-Email: agent@example.com" \
  -H "Content-Type: application/json" \
  -d '{"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}'
```

## Multi-Yield Allocation

Split a single deposit across multiple yield protocols. Currently supports the **Aegis aUSDC Vault** and **Synthra V3**.

```bash theme={null}
curl -X POST https://api.aegisintent.xyz/v1/actions/wealth/multiYield \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Aegis-Email: agent@example.com" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: c9d8e7f6-a5b4-3c2d-1e0f-9a8b7c6d5e4f" \
  -H "X-Aegis-Nonce: 2" \
  -d '{
    "amountUsdc": "100.00",
    "aegisWeight": 60,
    "synthraWeight": 40
  }'
```

### Multi-Yield Parameters

| Field           | Type   | Required | Description                                  |
| --------------- | ------ | -------- | -------------------------------------------- |
| `amountUsdc`    | string | Yes      | Total USDC amount to allocate                |
| `aegisWeight`   | number | Yes      | Percentage for the Aegis aUSDC Vault (0-100) |
| `synthraWeight` | number | Yes      | Percentage for Synthra V3 (0-100, max 80)    |

<Warning>
  `aegisWeight` and `synthraWeight` must add up to **100**. To limit exposure
  to external protocol risk, `synthraWeight` caps at **80%**.
</Warning>

## Synthra V3 Withdrawal

Close a Synthra V3 position and sweep all accrued fees to USDC.

```bash theme={null}
curl -X POST https://api.aegisintent.xyz/v1/actions/wealth/yield/synthra/withdraw \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Aegis-Email: agent@example.com" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: b1a2c3d4-e5f6-7890-abcd-1234567890ef" \
  -H "X-Aegis-Nonce: 3"
```

No request body needed. The system finds the agent's active Synthra position, closes it, and collects the liquidity and fees.

## Portfolio Monitoring

### View Active Intents

Get a list of all active limit orders and DCA schedules for the agent:

```bash theme={null}
curl -X GET https://api.aegisintent.xyz/v1/actions/wealth/intents \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Aegis-Email: agent@example.com"
```

### Portfolio Metrics

Get a summary of portfolio performance including total deposited, current value, and yield earned:

```bash theme={null}
curl -X GET https://api.aegisintent.xyz/v1/actions/wealth/metrics \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Aegis-Email: agent@example.com"
```

## Wealth Sentinel

The Wealth Sentinel runs in the background every 5 minutes. It:

1. Checks `PENDING` limit orders against current market prices.
2. Checks active DCA schedules against elapsed time.
3. Executes matching intents via the agent's Circle wallet.
4. Writes the execution to the audit trail.

<Tip>
  The Sentinel runs on its own. Register the order or schedule, then walk away.
  It handles execution, nonces, and audit logs.
</Tip>

## Related Endpoints

| Endpoint                                    | Method | Description                          |
| ------------------------------------------- | ------ | ------------------------------------ |
| `/v1/actions/wealth/limitOrder`             | POST   | Register a new limit order           |
| `/v1/actions/wealth/limitOrder/cancel`      | POST   | Cancel an existing limit order       |
| `/v1/actions/wealth/dca`                    | POST   | Register a new DCA schedule          |
| `/v1/actions/wealth/dca/cancel`             | POST   | Cancel an existing DCA schedule      |
| `/v1/actions/wealth/multiYield`             | POST   | Split deposit across yield protocols |
| `/v1/actions/wealth/yield/synthra/withdraw` | POST   | Close Synthra V3 position            |
| `/v1/actions/wealth/intents`                | GET    | View all active intents              |
| `/v1/actions/wealth/metrics`                | GET    | View portfolio performance metrics   |