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

# Quickstart

> Connect an AI agent, inspect its Arc wallet, and execute a policy-checked payment

## Get Started with Aegis

This guide walks through the core Aegis lifecycle:

1. Give your agent the live Aegis skill instructions.
2. Connect the agent and receive an API token.
3. Verify the provisioned Arc wallet.
4. Execute a guarded x402 payment.

## Prerequisites

Before you begin, make sure you have:

* An email address for the agent
* `curl` or another HTTP client
* Access to `https://api.aegisintent.xyz`
* A way to store the returned token securely

## Step 1: Load the Agent Skill File

Aegis publishes a live `SKILL.md` file that teaches an AI agent the required
headers, nonce flow, idempotency rules, supported actions, and recovery
patterns.

```bash theme={null}
curl https://api.aegisintent.xyz/SKILL.md
```

Use this prompt when bootstrapping the agent:

```text theme={null}
get started on aegis: https://api.aegisintent.xyz/SKILL.md
```

<Tip>
  For autonomous agents, load `SKILL.md` before allowing the agent to request
  transfers, payments, swaps, bridges, or yield actions.
</Tip>

## Step 2: Connect the Agent

Aegis uses an email OTP flow to bind an agent identity to a token and wallet.

<Steps>
  <Step title="Request a verification code">
    ```bash theme={null}
    curl -X POST https://api.aegisintent.xyz/v1/connect/start \
      -H "Content-Type: application/json" \
      -d '{"email": "your-agent@example.com"}'
    ```

    Example response:

    ```json theme={null}
    {
      "success": true,
      "challengeId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "expiresAt": "2026-05-20T00:45:00.000Z",
      "message": "Verification code prepared. Complete the challenge before a token is issued."
    }
    ```
  </Step>

  <Step title="Complete the OTP challenge">
    Submit the `challengeId` and the 6-character code sent to the agent email.

    ```bash theme={null}
    curl -X POST https://api.aegisintent.xyz/v1/connect/complete \
      -H "Content-Type: application/json" \
      -d '{
        "email": "your-agent@example.com",
        "challengeId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
        "otp": "A8F93D"
      }'
    ```

    On success, Aegis registers the agent, provisions a Circle Developer
    Controlled Wallet on Arc, and returns a bearer token.

    ```json theme={null}
    {
      "success": true,
      "agent": {
        "id": "clx1abc2d0001...",
        "email": "your-agent@example.com",
        "walletId": "85d48e9b-bd7c-5181-a980-89ae1233272e",
        "walletAddress": "0xc27508085e5b2128e5a14dedacb53d6525dbcbde"
      },
      "tokenIssued": true,
      "token": "aegis_live_wzm79d9Jzd7LMY4T2iOoWICg1puoWkL...",
      "tokenExpiresAt": "2026-06-19T00:35:00.000Z"
    }
    ```

    <Warning>
      Store the token immediately. The plaintext token is shown once and is
      stored as a hash by Aegis.
    </Warning>
  </Step>
</Steps>

## Step 3: Check the Wallet

Use the token and registered email on every authenticated request.

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

Example response:

```json theme={null}
{
  "success": true,
  "wallet": {
    "walletId": "85d48e9b-bd7c-5181-a980-...",
    "walletAddress": "0xc27508085e5b2128e5a14..."
  },
  "balance": [
    {
      "token": {
        "blockchain": "ARC-TESTNET",
        "name": "USDC",
        "symbol": "USDC",
        "decimals": 18,
        "isNative": true
      },
      "amount": "39.492258598461631676",
      "blockchain": "ARC-TESTNET"
    }
  ]
}
```

## Step 4: Execute an x402 Payment

Search for paid services first:

```bash theme={null}
curl -X POST https://api.aegisintent.xyz/v1/marketplace/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Aegis-Email: your-agent@example.com" \
  -d '{"keyword": "crypto"}'
```

Then route the payment through Aegis. Financial actions require both an
`Idempotency-Key` and `X-Aegis-Nonce`.

```bash theme={null}
curl -X POST https://api.aegisintent.xyz/v1/actions/pay \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Aegis-Email: your-agent@example.com" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Aegis-Nonce: 0" \
  -d '{
    "serviceUrl": "https://api.example.com/v1/data",
    "maxAmount": "1.50",
    "method": "GET"
  }'
```

Example response:

```json theme={null}
{
  "success": true,
  "result": {
    "status": "completed",
    "paymentProtocol": "x402",
    "chargedUsdc": "1.00",
    "response": {
      "status": 200,
      "data": { "message": "service response" }
    }
  }
}
```

<Success>
  The agent completed a payment without bypassing policy, nonce, idempotency,
  or audit controls.
</Success>

## Next Steps

<CardGroup cols={2}>
  <Card color="#00A360" title="Authentication" icon="lock" href="/authentication">
    Learn the token, email, nonce, and idempotency requirements.
  </Card>

  <Card color="#00A360" title="Transfers" icon="paper-plane" href="/features/transfers">
    Send USDC to any EVM address on Arc.
  </Card>

  <Card color="#00A360" title="Wealth Engine" icon="chart-line" href="/features/wealth-engine">
    Register DCA schedules, limit orders, and multi-yield allocations.
  </Card>

  <Card color="#00A360" title="API Reference" icon="code" href="/api-reference/overview">
    Browse endpoint schemas and examples.
  </Card>
</CardGroup>