# How Aeeron works ## How Aeeron works Aeeron exposes payment-aware API calls that wrap real provider operations behind an explicit payment boundary. The system is intentionally structured so an agent sees price before execution and receives a durable execution record after payment clears. That design keeps the economic step visible, which is the main requirement for safe autonomous action. Without that boundary, an agent can make tool calls, but it cannot reliably manage the parts of execution that involve spending money and waiting on external providers. ### Core model Aeeron sits between the agent and the downstream provider. The agent sends intent, parameters, and budget context. Aeeron turns that into a quote, enforces payment through x402, invokes the correct provider adapter once funding is present, and returns the resulting execution state to the caller. This separation is the main architectural advantage of the product. The agent stack remains focused on planning and policy, while Aeeron owns pricing, payment enforcement, provider invocation, and lifecycle tracking. ### System components At a system level there are four moving parts. The agent client forms the intent and decides whether an action should proceed. The Aeeron API exposes the action surface and keeps request semantics consistent. The x402 layer defines the payment challenge that must be satisfied before execution can begin. The provider adapter layer translates a generic Aeeron action into a provider-specific operation and normalizes the result back into a tracked execution object. ### Request envelope Most actions use the same request envelope because the client should not need a new runtime model for every provider integration. Action-specific fields stay inside `input`, while the outer shape remains stable enough for policy, budgeting, logging, and retries to work the same way across infrastructure, business services, and agent-to-agent purchases. ```json { "action": "servers.provision", "input": { "region": "fra1", "plan": "gpu-small", "durationHours": 24 }, "budget": { "amount": "18.50", "currency": "USDC" } } ``` ### Request lifecycle The lifecycle is easier to think about as a controlled state machine rather than as a single request. The agent first chooses an action. Aeeron then prices that action and declares the payment requirement. After payment proof is supplied, the provider-facing execution begins and produces a trackable record. That structure gives the client a clean place to apply approval rules, attach idempotency keys, and decide whether the action is still worth running if time or price conditions have changed. {% stepper %} {% step %} ### 1. The agent selects an action The agent chooses a payable operation. Examples include company formation, server payments, or buying another agent service. {% endstep %} {% step %} ### 2. Aeeron returns payment requirements The call is gated by x402. The agent gets a clear payment requirement before execution continues. {% endstep %} {% step %} ### 3. Payment is completed The payment is settled through the configured Solana-based flow. This creates a machine-readable checkpoint for the operation. {% endstep %} {% step %} ### 4. The action executes Once payment clears, Aeeron forwards the request to the target service. The result is returned to the agent as a single workflow. {% endstep %} {% endstepper %} ### Execution record The execution resource is the system of record for long-running work. It should be persisted as soon as it is created because the execution identifier becomes the anchor for every later operation: polling, webhook reconciliation, provider escalation, refund handling, and post-run audit. In practice, stable execution objects are what make paid automation workable in production rather than only in demos. ```json { "executionId": "exe_3d7a9e", "status": "processing", "action": "servers.provision", "quoteId": "qt_8f1b0c", "providerMeta": { "provider": "compute-fabric", "region": "fra1" } } ``` ### Why this model works well for agents Aeeron works well for agents because it turns paid services into primitives without pretending they are stateless tools. The agent can still reason in terms of actions, but the system preserves the distinction between asking for something, paying for it, and receiving the result later. That reduces the amount of custom billing and provider glue code each team has to build, and it makes third-party services easier to compose into larger multi-step workflows. ### What Aeeron abstracts away With Aeeron in place, the agent integration no longer has to manage per-service payment mechanics, ad hoc checkout flows, or a different retry model for every provider. Those details still exist, but they are pushed below a common API layer where they can be handled once instead of leaking into every agent workflow. ### Design strengths Aeeron is strongest when an agent needs to act, pay, and continue in one uninterrupted path. That is especially important in autonomous and semi-autonomous systems, where the real product challenge is not only choosing the correct next step but doing so with enough structure that budgets, approvals, retries, and audits remain manageable. ### Related pages For the payment boundary itself, read [Authentication and x402](/aeeron-docs/authentication-and-x402.md). For object lifecycle and retry semantics, continue with [API conventions](/aeeron-docs/api-conventions.md). For long-running work completion, see [Async jobs and webhooks](/aeeron-docs/async-jobs-and-webhooks.md). --- # 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/how-aeeron-works.md?ask= ``` 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.