AURA Agent Gateway

/02Request contract

{
  "origin": "ACC",
  "destination": "KMS",
  "departure_date": "2026-12-01",
  "preferences": "Prefer daytime travel."
}

curl -i 'https://auragateway.app/api/public/v1/travel/aggregate' \
  -H 'Content-Type: application/json' \
  --data '{"origin":"ACC","destination":"KMS","departure_date":"2026-12-01","preferences":"Prefer daytime travel."}'

curl -i 'https://auragateway.app/api/public/v1/vision/process-frame' \
  -H 'Content-Type: application/json' \
  --data '{"image_url":"https://upload.wikimedia.org/wikipedia/commons/thumb/3/3f/Fronalpstock_big.jpg/640px-Fronalpstock_big.jpg","prompt":"Identify objects and return normalized spatial metadata."}'

/03Payment protocol

Protocol

x402 v2 · exact · EIP-3009 authorization

Network

eip155:8453 · Base mainnet

Amount

10000 atomic USDC · 6 decimals

Asset contract

0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

1. 1.

   Submit a valid unpaid POST

   Decode the base64 JSON in PAYMENT-REQUIRED on HTTP 402. The response body also includes the payment challenge.

2. 2.

   Validate and authorize

   Check network, asset, amount, resource URL and payTo against your agent’s allowlist. Use the payTo returned by this gateway’s challenge; never substitute a wallet or send a standalone transfer. Sign the exact payment authorization with your agent’s funded Base USDC wallet.

3. 3.

   Resubmit once with the signature

   Send the same JSON body with PAYMENT-SIGNATURE containing the x402 v2 encoded payment payload. X-PAYMENT-SIGNATURE is also accepted. A transaction hash alone is not a valid payment payload.

4. 4.

   Save the receipt and result

   The gateway verifies and settles payment, checks the Base USDC receipt, and then calls Sabre or runs vision AI. Read the JSON result and decode PAYMENT-RESPONSE for settlement evidence. Duplicate authorization nonces are rejected.

// Install: npm install @x402/core @x402/evm @x402/fetch viem
// Run in the agent's own secure environment; never expose its key.
import { x402Client } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { wrapFetchWithPayment } from "@x402/fetch";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY);
const trustedPayTo = process.env.AURA_TRUSTED_PAY_TO?.toLowerCase();
if (!trustedPayTo) throw new Error("Configure a verified receiver allowlist first");
const client = new x402Client().register("eip155:8453", new ExactEvmScheme(account));
client.onBeforePaymentCreation(async ({ paymentRequired, selectedRequirements }) => {
  if (selectedRequirements.scheme !== "exact" ||
      selectedRequirements.network !== "eip155:8453" ||
      selectedRequirements.asset.toLowerCase() !== "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913" ||
      selectedRequirements.amount !== "10000" ||
      selectedRequirements.payTo.toLowerCase() !== trustedPayTo ||
      selectedRequirements.maxTimeoutSeconds > 60 ||
      paymentRequired.resource?.url !== "https://auragateway.app/api/public/v1/travel/aggregate") {
    return { abort: true, reason: "Unexpected payment terms" };
  }
});
const paidFetch = wrapFetchWithPayment(fetch, client);
const response = await paidFetch("https://auragateway.app/api/public/v1/travel/aggregate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ origin: "ACC", destination: "KMS", departure_date: "2026-12-01" }),
});
// Save settlement evidence even when AI processing returns an error.
const receipt = response.headers.get("PAYMENT-RESPONSE");
console.log({ status: response.status, receipt, result: await response.json() });
// Do not automatically repeat this paid request.

Set AURA_TRUSTED_PAY_TO to the receiver you verified from the gateway’s challenge and configure a spending budget before enabling automatic calls. The SDK handles the initial challenge and signed resubmission; no browser or human approval is needed when the agent securely owns its signing wallet. For vision, change the URL, body and exact resource check together.

/04Response handling

Payment-stage errors may use a plain error string and omit paymentStatus. A submission-pending error means do not repay. Provider errors use error.code, error.message, error.retryable, requestId and paymentStatus; even HTTP 402 can be an AI credit failure after settlement, not a new payment challenge. Treat the settlement header and paymentStatus as authoritative.