# Code examples

## Code examples

The examples on this page focus on the operational loop that matters most in Aeeron: request a quote, satisfy the payment requirement, create an execution, and track the result to completion. The code itself is straightforward. The more important point is how state moves through the workflow. Each snippet keeps the quote, payment, and execution stages distinct so a client can apply policy, retries, and logging without losing economic context.

### Example: provision a server with curl

This example starts with the quote phase for a server provisioning request. Notice that the request includes an explicit budget and an idempotency key. Those two fields are what make the call safe to use in an agent runtime, because they constrain the financial intent and make replay behavior predictable under failure.

```bash
QUOTE=$(curl -s -X POST https://api.aeeron.com/v1/quotes \
  -H "Authorization: Bearer $AEERON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4a4e4b6d-server-001" \
  -d '{
    "action": "servers.provision",
    "input": {
      "region": "nyc1",
      "plan": "cpu-medium",
      "image": "ubuntu-24.04",
      "durationHours": 12
    },
    "budget": { "amount": "12.00", "currency": "USDC" }
  }')

echo "$QUOTE"
```

### Example: create an execution in JavaScript

The next step turns a funded quote into a tracked execution. The key detail is that the code does not invent a new action at this point. It reuses the previously priced intent, attaches the quote identifier and payment proof, and lets the server create a durable execution object that the client can reconcile later.

```javascript
const quoteId = "qt_8f1b0c";

const response = await fetch("https://api.aeeron.com/v1/executions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.AEERON_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "server-run-001",
    "X-Quote-Id": quoteId,
    "X-Payment-Proof": process.env.PAYMENT_PROOF
  },
  body: JSON.stringify({
    action: "servers.provision",
    input: {
      region: "nyc1",
      plan: "cpu-medium",
      image: "ubuntu-24.04",
      durationHours: 12
    }
  })
});

const execution = await response.json();
console.log(execution);
```

### Example: poll execution in Python

Polling is intentionally simple. Once the execution exists, the client should treat the execution resource as the source of truth for state changes instead of assuming that the initial create response contains the final answer.

```python
import os
import requests

execution_id = "exe_3d7a9e"
headers = {
    "Authorization": f"Bearer {os.environ['AEERON_API_KEY']}"
}

res = requests.get(
    f"https://api.aeeron.com/v1/executions/{execution_id}",
    headers=headers,
    timeout=10,
)

print(res.json())
```

### Example: purchase another agent service

This payload shows how outsourced agent work fits the same model. The request still carries an explicit action, a structured input, and a price ceiling. That gives the caller enough information to decide whether delegation is worth the spend before any external service is purchased.

```json
{
  "action": "agent-services.purchase",
  "input": {
    "serviceId": "svc_due-diligence-v2",
    "task": "Evaluate three VPS vendors for latency and GPU cost.",
    "deliveryMode": "json"
  },
  "budget": {
    "amount": "45.00",
    "currency": "USDC"
  }
}
```

### Example: create a company

Company formation is a stronger example of why Aeeron separates payment from execution. Legal and business setup tasks often run longer than infrastructure calls and produce artifacts later in the lifecycle. A priced request plus a tracked execution record gives the client a much better foundation for supervising that work than a single synchronous provider call would.

```json
{
  "action": "companies.create",
  "input": {
    "jurisdiction": "US-WY",
    "companyType": "llc",
    "name": "North Orbit Systems",
    "owners": [
      {
        "type": "person",
        "fullName": "Ari Novak",
        "country": "EE"
      }
    ]
  },
  "budget": {
    "amount": "280.00",
    "currency": "USDC"
  }
}
```

### What these examples show

The common thread in all of these examples is that the paid step remains visible. The client always knows whether it is still planning, actively funding an action, or waiting on provider execution. That visibility is the core requirement for safe autonomous spending and for any production system that needs to explain later why money was spent on a specific action.


---

# 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/code-examples.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.