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

# x402 Payments

> Agents pay for API services using the x402 micropayment protocol

## x402 Micropayments

The x402 protocol lets AI agents pay for API services in USDC. No credit cards, no subscriptions. Call a 402-gated endpoint, and Aegis handles the payment negotiation.

## How x402 Works

Aegis manages payment negotiation and settlement:

|  Step | Actor / Sender     | Receiver           | Action / Message            | Details & Outcome                                                                                         |
| :---: | :----------------- | :----------------- | :-------------------------- | :-------------------------------------------------------------------------------------------------------- |
| **1** | **AI Agent**       | Aegis API          | `POST /v1/actions/pay`      | Agent requests Aegis to pay for an external API service (`serviceUrl` & `maxAmount` specified).           |
| **2** | **Aegis API**      | Target Service     | Initial HTTP Request        | Aegis forwards the request to the target service without payment to trigger the x402 challenge.           |
| **3** | **Target Service** | Aegis API          | `402 Payment Required`      | Target service rejects initial call and returns pricing and recipient wallet details in response headers. |
| **4** | **Aegis API**      | Policy Engine (DB) | Limits Check                | Aegis verifies cost against agent's spending limits. If limits are exceeded, the flow aborts immediately. |
| **5** | **Aegis API**      | Circle DCW         | Transaction Signing         | Aegis connects to the agent's Wallet to sign the USDC payment proof.                                      |
| **6** | **Aegis API**      | Target Service     | Resubmit with Payment Proof | Aegis resubmits request to target service with the cryptographic payment proof attached.                  |
| **7** | **Target Service** | Aegis → Agent      | `200 OK` + Data Delivery    | Target service verifies payment, executes request, and returns data. Aegis forwards it back to the agent. |

<Steps>
  <Step title="1. Agent requests a paid service">
    Call `/v1/actions/pay`. Provide the target URL, HTTP method, and spending limit.
  </Step>

  <Step title="2. Aegis negotiates the payment">
    Aegis sends an initial request to the target. If it returns `402 Payment Required`,
    Aegis extracts the price and recipient address from the headers.
  </Step>

  <Step title="3. Policy check">
    Aegis checks the price against agent spending policies. If the cost exceeds limits,
    the payment fails immediately.
  </Step>

  <Step title="4. Payment execution">
    Aegis connects to the agent's Circle Developer Controlled Wallet. It signs the USDC
    payment proof, then resubmits the request.
  </Step>

  <Step title="5. Data returned">
    The target verifies the proof and returns the data. Aegis forwards it to the agent.
  </Step>
</Steps>

## Usage

```bash theme={null}
curl -X POST https://api.aegisintent.xyz/v1/actions/pay \
  -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 '{
    "serviceUrl": "https://api.example.com/v1/market-data",
    "maxAmount": "1.50",
    "method": "GET"
  }'
```

## Payment Parameters

| Field        | Type   | Required | Description                                                              |
| ------------ | ------ | -------- | ------------------------------------------------------------------------ |
| `serviceUrl` | string | Yes      | The full URL of the x402-gated API endpoint                              |
| `maxAmount`  | string | Yes      | Maximum USDC the agent is willing to pay                                 |
| `method`     | string | No       | HTTP method (`GET`, `POST`, `PUT`, `DELETE`, `PATCH`). Defaults to `GET` |
| `data`       | any    | No       | Request body to forward to the target service (for POST/PUT)             |
| `headers`    | array  | No       | Additional headers to forward (max 10). Format: `"Header-Name: value"`   |

## Service Discovery

Agents discover x402 services through the [Marketplace API](/api-reference/marketplace/search). Inspect a service to check pricing before paying:

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

## Cost Estimation

Estimate payment costs without executing:

```bash theme={null}
curl -X POST https://api.aegisintent.xyz/v1/actions/estimate/pay \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Aegis-Email: agent@example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceUrl": "https://api.example.com/v1/market-data",
    "maxAmount": "1.50"
  }'
```

<Info>
  `maxAmount` is a spending cap. If the price is lower, the agent pays the actual amount.
  If it exceeds `maxAmount`, the payment drops.
</Info>