Skip to main content

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 Micropayments

The x402 protocol enables AI agents to pay for API services using USDC, no credit cards, no subscriptions, no manual approvals. When an agent calls a 402-gated endpoint, Aegis handles the entire payment negotiation automatically.

​
How x402 Works

Aegis handles the entire payment negotiation and settlement automatically:
StepActor / SenderReceiverAction / MessageDetails & Outcome
1AI AgentAegis APIPOST /v1/actions/payAgent requests Aegis to pay for an external API service (serviceUrl & maxAmount specified).
2Aegis APITarget ServiceInitial HTTP RequestAegis forwards the request to the target service without payment to trigger the x402 challenge.
3Target ServiceAegis API402 Payment RequiredTarget service rejects initial call and returns pricing and recipient wallet details in response headers.
4Aegis APIPolicy Engine (DB)Limits CheckAegis verifies cost against agent’s spending limits. If limits are exceeded, the flow aborts immediately.
5Aegis APICircle DCWTransaction SigningAegis connects to the agent’s secure Circle Developer Controlled Wallet to sign the USDC payment proof.
6Aegis APITarget ServiceResubmit with Payment ProofAegis resubmits request to target service with the cryptographic payment proof attached.
7Target ServiceAegis → Agent200 OK + Data DeliveryTarget service verifies payment, executes request, and returns data. Aegis forwards it back to the agent.
1

1. Agent requests a paid service

Your agent calls /v1/actions/pay with the target service URL, the HTTP method, and a maximum amount it’s willing to spend.
2

2. Aegis negotiates the payment

Aegis sends an initial request to the target service. If the service responds with 402 Payment Required, Aegis extracts the payment requirements (price, token type, and recipient address) from the response headers.
3

3. Policy check

Before authorization, Aegis checks the price against the agent’s spending policies. If the cost exceeds any configured limit (per-transaction, daily, weekly, or monthly budgets), the payment is immediately rejected.
4

4. Payment execution

If the policy allows it, Aegis connects to the agent’s secure Circle Developer Controlled Wallet (DCW) to sign the USDC transaction authorization payload, then resubmits the request with the payment proof attached.
5

5. Data returned

The target service validates the cryptographic payment proof, processes the transaction, and returns the requested data. Aegis forwards the clean response back to the agent.

​
Usage

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

FieldTypeRequiredDescription
serviceUrlstringYesThe full URL of the x402-gated API endpoint
maxAmountstringYesMaximum USDC the agent is willing to pay
methodstringNoHTTP method (GET, POST, PUT, DELETE, PATCH). Defaults to GET
dataanyNoRequest body to forward to the target service (for POST/PUT)
headersarrayNoAdditional headers to forward (max 10). Format: "Header-Name: value"

​
Service Discovery

Before paying, your agent can discover available x402 services through the Marketplace API. You can also inspect a specific service to check its pricing before committing: 
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

Use the dry-run endpoint to estimate what a payment would cost without executing it: 
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"
  }'
The maxAmount field acts as a spending cap. If the service’s actual price is lower, the agent only pays the actual amount. If the price exceeds maxAmount, the payment is rejected.