# Getting started

## Getting started

Aeeron is easiest to understand through one full request flow.\
The key point is simple: **pricing, payment, and execution are separate stages**.

{% hint style="success" %}
**What to remember:** the agent does not jump straight into execution.\
It first checks price, then payment, then state.
{% endhint %}

### Base URL

All agent-facing operations share one base URL.

```bash
https://api.aeeron.com/v1
```

### Flow map

```
1. Choose action
        ↓
2. Request quote
        ↓
3. Receive x402 requirement
        ↓
4. Attach payment proof
        ↓
5. Create execution
        ↓
6. Poll or reconcile
```

### Minimal request flow

In a normal integration:

{% stepper %}
{% step %}

### 1. Send intent and budget

The agent sends the action payload and budget envelope.
{% endstep %}

{% step %}

### 2. Evaluate the quote

The client receives price and payment requirements.
{% endstep %}

{% step %}

### 3. Fund the action

The client satisfies the x402 requirement.
{% endstep %}

{% step %}

### 4. Create and track execution

The client stores the execution ID immediately.
{% endstep %}
{% endstepper %}

### Example flow

The first request prices a server provisioning task.\
The budget stays inside the request, so the quote can be checked against policy.

```bash
curl -X POST https://api.aeeron.com/v1/quotes \
  -H "Authorization: Bearer $AEERON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "servers.provision",
    "input": {
      "region": "fra1",
      "plan": "gpu-small",
      "durationHours": 24
    },
    "budget": {
      "amount": "18.50",
      "currency": "USDC"
    }
  }'
```

The response returns more than a number.\
It gives the client a quote ID, expiry window, and payment requirement.

```json
{
  "quoteId": "qt_8f1b0c",
  "action": "servers.provision",
  "amount": "16.80",
  "currency": "USDC",
  "expiresAt": "2026-05-30T12:30:00Z",
  "paymentRequirement": {
    "scheme": "x402",
    "resource": "/v1/executions",
    "network": "solana"
  }
}
```

### Quote check

Before execution, the client compares quote and budget.

```
Budget    18.50 USDC  ████████████
Quote     16.80 USDC  ███████████
Headroom   1.70 USDC  █
```

{% hint style="info" %}
**Key idea:** a quote is a control point.\
It is where policy decides whether the action can continue.
{% endhint %}

### Execute after payment

Once payment is satisfied, the client submits the same intent with:

* the quote reference
* the payment proof
* the action input

```bash
curl -X POST https://api.aeeron.com/v1/executions \
  -H "Authorization: Bearer $AEERON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Quote-Id: qt_8f1b0c" \
  -H "X-Payment-Proof: signed-payment-token" \
  -d '{
    "action": "servers.provision",
    "input": {
      "region": "fra1",
      "plan": "gpu-small",
      "durationHours": 24
    }
  }'
```

### Response shape

Aeeron returns stable identifiers because the client needs durable state.\
That is what makes retries and audits safe.

```json
{
  "executionId": "exe_3d7a9e",
  "status": "pending",
  "action": "servers.provision",
  "createdAt": "2026-05-30T12:05:19Z"
}
```

### What the client should persist

```
quoteId        → pricing decision
paymentProof   → funding proof
executionId    → source of truth for status
```

### What to implement first

Start with a narrow production loop:

* authentication
* quote creation
* x402 handling
* execution polling
* idempotent retries

{% hint style="info" %}
Start with a narrow action set. Expand once your spend policy and retry model are stable.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://aeeron.gitbook.io/aeeron-docs/getting-started.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.