# Authentication and x402 ## Authentication and x402 Aeeron separates caller identity from payment authorization. Authentication answers the question of who is allowed to use the API. x402 answers the separate question of whether a specific payable action has actually been funded. Keeping those concerns distinct is important because an authenticated client still should not be able to execute paid work unless it has satisfied the economic requirement for that exact operation. ### Required headers Every authenticated request should identify the caller and carry an idempotency key for any state-changing operation. That key becomes critical when the client has to retry under network failure, because the server can distinguish a safe replay from a new economic intent. ```http Authorization: Bearer Content-Type: application/json Idempotency-Key: ``` Execution requests that follow a successful quote also need to attach the quote reference and the payment proof. Those headers tie the provider action to a concrete pricing decision and a concrete payment event. ```http X-Quote-Id: X-Payment-Proof: ``` ### Typical x402 flow Aeeron can return a payment challenge as part of normal control flow, and the client should be built to expect that outcome rather than treat it as an exceptional failure. A payment-required response means the action is valid and understood, but the economic precondition has not yet been satisfied. That distinction makes agent behavior cleaner because the caller can branch into approval or payment logic without losing the original execution context. ```json { "error": { "code": "payment_required", "message": "Payment is required before this action can execute." }, "paymentRequirement": { "scheme": "x402", "network": "solana", "resource": "/v1/executions", "quoteId": "qt_8f1b0c", "amount": "16.80", "currency": "USDC", "expiresAt": "2026-05-30T12:30:00Z" } } ``` ### How agents should handle it When an x402 challenge arrives, the agent should read the quote and compare it against local policy before doing anything else. If the action is inside budget, the client can proceed with payment through the configured Solana flow and then replay the same operational request with proof attached. If it falls outside the allowed range, the correct response is escalation or rejection, not silent truncation of the request. ### Security guidance The safest production design is to constrain spending along several dimensions at once. Budget limits should be tied to action type, amount range, and time window, and the signing context should reflect those boundaries. A quote identifier, payment proof, and execution identifier should always be stored together because that triplet is the minimum record needed to explain what the agent paid for and why that payment unlocked a specific provider action. ### Wallet strategy Aeeron works best when the wallet model is constrained instead of universal. A small rolling hot wallet is useful for low-risk autonomous actions. A delegated signer works well when the spend boundaries are narrow and machine-enforceable. A higher-friction approval wallet makes sense for expensive or regulated actions. The correct choice depends less on the chain itself and more on the operational risk of the action being funded. ### Failure cases Payment failure and execution failure must be recorded as different states. A payment can fail before the provider is touched, while an execution can fail after the spend is already committed. That distinction is not bookkeeping trivia. It affects refund logic, retry behavior, provider escalation, and the way the client explains the outcome to users or supervising systems. --- # 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/authentication-and-x402.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.