Financial Intelligence Layer for Onchain AI Agents
The official TypeScript HTTP client for the AUREON API. Financial Compass, capital health, and verified restore plans: one typed integration surface.
Contract Address (CA): 0xd293291060334d42e5dbea6fb854c231af527777
pnpm add @buildaureon/sdk- What is AUREON?
- Requirements & Installation
- Architecture & System Flow
- Quickstart
- Detailed Authentication Guide
- API Surface Reference & Code Walkthroughs
- Client Configuration & Transport Engine
- Error Model and Code Handling
- CLI Command-Line Guide
- Design Principles & Settlement Honesty
- Documentation Registry Map
AUREON is a policy and execution layer for capital on Robinhood Chain. Traditional web3 interactions are transactional: an operator submits a single swap or deposit instruction, and once settled, the system forgets the broader goal.
AUREON introduces Financial Compass Objectives (FCOs) as execution primitives. Instead of sending raw transactions, developers register continuous financial rules (e.g., "maintain a stable coin buffer at 25% of total portfolio value"). The AUREON system:
- Monitors capital holdings across active addresses and smart vault contracts.
- Computes live portfolio value using public market data.
- Detects allocation breaches against registered objective bands.
- Produces recovery instructions (e.g., wrap/unwrap transactions or keeper-driven vault swaps).
- Maintains a cryptographic, append-only timeline of compliance audits.
flowchart TD
subgraph Public [Public Node / Operator App]
SDK["@buildaureon/sdk (TypeScript)"]
Signer[Wallet Signer / Viem]
end
subgraph Cloud [Hosted Ingress]
API[AUREON API Gateway]
Watchdog[Health Watchdog Engine]
DB[(SQLite Ledger)]
end
subgraph EVM [Robinhood Chain L2]
Vault[AUREON Smart Vault]
Keeper[Keeper Rebalance Adapter]
end
SDK -->|"HTTPS request with Key + JWT"| API
API --> Watchdog
API --> DB
Watchdog -->|"Identify violation"| Keeper
Signer -->|"1. Request Calldata Steps"| API
API --x|"2. Returns steps (no keys held)"| Signer
Signer -->|"3. Signs & broadcasts transactions"| EVM
- Node.js version 20 or higher (ESM environment).
- Viem (version 2.x) if signing and broadcasting transaction steps is required.
Add the package to your project using a package manager:
# Using pnpm
pnpm add @buildaureon/sdk
# Using npm
npm install @buildaureon/sdk
# Using yarn
yarn add @buildaureon/sdkTo protect user funds, AUREON uses a decoupled trust boundary. The hosted API handles monitoring, calculations, public oracle pricing, and rebalance coordination, while private keys remain with the client.
| Layer | Responsibility |
|---|---|
| SDK | Request transport, EIP-712 hashing utilities, parameter validation, retry backing, and vault deposit/withdrawal calldata construction. |
| AUREON API | Ledger syncing, objective validation logic, public price marks tracking, execution timeline compilation, and stage rebalance management. |
| Host Application | Private key storage, MetaMask/signer integrations, and transaction signing & broadcasting. |
Authentication requires a challenge-response signature verification to link a wallet address with a temporary JWT session.
sequenceDiagram
autonumber
participant App as Client Operator
participant SDK as SDK Client
participant API as AUREON API Gateway
App->>SDK: aureon.getAuthNonce(address)
SDK->>API: GET /auth/nonce?address=0x...
API-->>SDK: { message, nonce, expiresAt }
SDK-->>App: { message, nonce }
Note over App: Operator signs message<br/>using private key
App->>SDK: aureon.verifyWallet({ address, message, signature })
SDK->>API: POST /auth/verify { address, message, signature }
API->>API: Verify EIP-191 Signature
API-->>SDK: { token, expiresAt, sessionId }
SDK-->>App: Return JWT Token
When portfolio weights drift, the system triggers a rebalance using the execution flow:
sequenceDiagram
autonumber
participant Client as Client Application
participant API as AUREON API Gateway
participant DB as SQLite DB
participant Engine as Health Engine
participant Keeper as Keeper Service
Client->>API: aureon.refreshWatchdog()
API->>DB: Pull current price marks & positions
API->>Engine: Recompute objective deviations
alt Drift Exceeds Tolerance Limit
Engine->>DB: Write health state: "violation"
Engine->>DB: Write event: "violation_detected"
Engine->>Keeper: Request restoration plan
Keeper-->>API: Return plan (e.g. vault_swap)
else Within Bands
Engine->>DB: Write health state: "healthy"
end
API-->>Client: Returns watchdog status and breach reports
Initialize the SDK, retrieve a signing nonce, verify the signature, and sync wallet positions:
import { createAureonClient, createSessionTokenProvider } from "@buildaureon/sdk";
import { privateKeyToAccount } from "viem/accounts";
import { createWalletClient, http } from "viem";
async function run() {
// 1. Setup session token container
const session = createSessionTokenProvider(null);
// 2. Initialize the client
const aureon = createAureonClient({
baseUrl: "https://api.aureonlabs.network",
apiKey: process.env.AUREON_API_KEY!,
getAccessToken: session.getAccessToken,
});
// 3. Perform a handshake to authenticate
const account = privateKeyToAccount("0x..."); // Operator private key
const { message } = await aureon.getAuthNonce(account.address);
const walletClient = createWalletClient({ account, transport: http() });
const signature = await walletClient.signMessage({ message, account });
const login = await aureon.verifyWallet({
address: account.address,
message,
signature,
});
// 4. Save credentials
session.setToken(login.token);
// 5. Query portfolio status
const synced = await aureon.syncPortfolio();
console.log("Portfolio Value USD:", synced.portfolio.totalNotionalUsd);
}API keys regulate product access at the gateway level. They must be sent with all client requests via the X-Aureon-Api-Key header. Generate new API keys inside the operator utility developer console.
Bearer sessions scope data operations to a specific wallet. The SDK client obtains a nonce, signs it using an EVM signer, and posts the signature back to /auth/verify to receive a JWT session token.
The createSessionTokenProvider manager handles token resolution and injection. It can be passed directly as a resolver function:
import { createSessionTokenProvider } from "@buildaureon/sdk";
const session = createSessionTokenProvider(process.env.AUREON_TOKEN ?? null);
// Clear tokens on logout
await aureon.logout();
session.clear();const ping = await aureon.ping();
console.log(`Connected. Backend version: ${ping.version}`);The Capital Book defines the assets tracked by AUREON. Sync positions from the chain or modify them directly:
// Sync active balances from Robinhood Chain L2 and smart vaults
const syncResult = await aureon.syncPortfolio();
console.log("Current stable coin weight:", syncResult.portfolio.stableWeight);
// Manually define positions (useful for simulation environments)
const updatedBook = await aureon.setPortfolio([
{ symbol: "WETH", quantity: 2.5, category: "gas" },
{ symbol: "USDG", quantity: 2500, category: "stable" }
]);
// Clear all active ledger tracking rows
await aureon.clearPortfolio();Objectives dictate the target weights and tolerance buffers. All SDK objectives are initialized with automatic rebalancing:
// Create a stable coin allocation objective
const stableObj = await aureon.createObjective({
name: "Stable Core Reserve",
kind: "stable_allocation",
targetWeight: 0.30, // Keep 30% of portfolio value in stables
tolerance: 0.03, // Rebalance if drift exceeds +/- 3%
priority: "high"
});
// Create a stock token tracking objective
const stockObj = await aureon.createObjective({
name: "Tesla Sleeve Allocation",
kind: "balanced_portfolio",
targetSymbol: "TSLA",
targetWeight: 0.20,
tolerance: 0.05
});
// List objectives registered to the authenticated wallet
const objectives = await aureon.listObjectives();// Get active health states for all objectives
const healthRecords = await aureon.getHealth();
for (const health of healthRecords) {
console.log(`Objective ${health.objectiveId}: State: ${health.state}`);
}
// Fetch timeline events (logs objective updates, breaches, and rebalances)
const timeline = await aureon.getTimeline();
timeline.forEach(event => console.log(`[${event.type}]: ${event.message}`));
// Fetch general dashboard overview metrics
const overview = await aureon.getOverview();
console.log("Global health score:", overview.globalHealthScore);Vault interactions construct raw transactions (calldatas) locally. The host application signs and broadcasts these to execute actions:
import { Hex } from "viem";
// 1. Prepare vault deposit parameters
const depositData = await aureon.prepareVaultDeposit({
symbol: "ETH",
amount: "0.5",
});
// 2. Iterate and sign calldata steps
for (const step of depositData.steps) {
const hash = await walletClient.sendTransaction({
account,
to: step.to as `0x${string}`,
data: step.data as Hex,
value: BigInt(step.value),
});
await publicClient.waitForTransactionReceipt({ hash });
}If a deviation triggers a breach, fetch the restore instructions:
// 1. Fetch recovery plan details
const plan = await aureon.getRestorePlan(objective.id);
console.log(`Plan requires action: ${plan.kind} for ${plan.amountHuman} tokens.`);
// 2. Perform restoration
if (plan.kind === "vault_swap") {
// Vault swaps are handled directly on the backend
const receipt = await aureon.restoreObjective(objective.id);
console.log("Rebalance transaction hash:", receipt.transactionHash);
console.log("Settlement environment:", receipt.settlement); // "vault" or "staged"
} else {
// ETH wraps or WETH unwraps are executed client-side
console.warn("Execute wrap_eth or unwrap_weth using your wallet provider.");
}Trigger price changes to test rebalancing routines:
// Trigger a mock 15% drop in NVDA's price mark
const shockResult = await aureon.applyMarketEvent({
symbol: "NVDA",
priceChangeRatio: -0.15,
autoRestore: true, // Trigger staged/vault restorations automatically if a breach occurs
});Generate, toggle, and revoke keys:
// Generate a new key (Store the returned plain-text 'secret' immediately)
const newKey = await aureon.createApiKey("Secondary Bot Ingress");
console.log(`Plaintext secret: ${newKey.secret}`);
// List active keys
const keys = await aureon.listApiKeys();
// Toggle active/inactive state
await aureon.toggleApiKey(newKey.id);
// Revoke a key
await aureon.revokeApiKey(newKey.id);Pass these parameters inside the AureonClientOptions constructor payload:
| Parameter | Type | Default | Description |
|---|---|---|---|
baseUrl |
string |
"https://api.aureonlabs.network" |
Target API ingress endpoint |
apiKey |
string |
undefined |
Key sent with X-Aureon-Api-Key headers |
authToken |
string |
undefined |
Static JWT bearer token |
getAccessToken |
() => string | null |
undefined |
Dynamic getter function resolving bearer tokens |
timeoutMs |
number |
30000 |
Abort threshold per network call |
maxRetries |
number |
0 |
Re-attempt counts for transport failures |
retryDelayMs |
number |
250 |
Wait delay between retry loops |
headers |
Record<string, string> |
{} |
Key-value headers appended to requests |
fetch |
typeof fetch |
globalThis.fetch |
Custom fetch wrapper engine overrides |
When maxRetries is greater than 0, the client retries failed requests if it encounters a transient error (such as a timeout or a 503 HTTP status code). Retries use a fixed delay (retryDelayMs).
| Code | HTTP Status | Description |
|---|---|---|
UNAUTHORIZED |
401 | Missing or invalid API key or Bearer token |
VALIDATION_ERROR |
400 | Payload fails validation (e.g. name length or targetWeight bounds) |
NOT_FOUND |
404 | Target object (objective, key, etc.) does not exist |
CONFLICT |
409 | Request conflicts with current database state |
RATE_LIMITED |
429 | Request count exceeds API limits |
SERVER_ERROR |
500 / 503 | Server-side execution failure |
TIMEOUT |
N/A | Call exceeded client-configured timeoutMs |
NETWORK_ERROR |
N/A | Endpoint unreachable or client is offline |
AUREON methods throw custom error instances. Wrap calls in a try/catch block and use isAureonError to handle them:
import { isAureonError } from "@buildaureon/sdk";
try {
const objective = await aureon.getObjective("missing_id");
} catch (error) {
if (isAureonError(error)) {
switch (error.code) {
case "NOT_FOUND":
console.error("The specified objective does not exist.");
break;
case "UNAUTHORIZED":
console.error("Check your API key and wallet session configuration.");
break;
default:
console.error(`Aureon error: ${error.message}`);
}
} else {
console.error("Generic execution failure:", error);
}
}The SDK package includes a developer CLI utility. Provide configuration values using environment variables:
export AUREON_API_KEY=your_key
export AUREON_TOKEN=your_bearer_token
# Verify connection
pnpm --filter @buildaureon/sdk cli ping
# Fetch current account metadata
pnpm --filter @buildaureon/sdk cli me
# Synchronize current on-chain balances
pnpm --filter @buildaureon/sdk cli sync
# Print Capital Book portfolio weights
pnpm --filter @buildaureon/sdk cli portfolio
# List all registered objectives
pnpm --filter @buildaureon/sdk cli objectives- Non-Custodial Design: Private keys never leave the client application. The AUREON API gateway only receives signature verification requests and constructs unsigned transaction payloads.
- Settlement Transparency: Execution receipts include a
settlementattribute ("staged"or"vault")."vault"indicates the transaction settled on-chain on Robinhood Chain L2."staged"indicates a local ledger update only. Staged transactions must be labeled transparently in user interfaces.
- Seeded Ledger Capital: Position data comes from synchronized block queries or explicit operator inputs. The SDK does not fabricate capital balances.
For more detail, refer to the documents inside the sdk/docs/ directory:
| Document | Focus |
|---|---|
| docs/architecture.md | Client vs API boundary lines and system maps |
| docs/auth.md | Wallet handshake, signature verifications, and JWT lifecycles |
| docs/client-api.md | Detailed parameter index for all client methods |
| docs/data-contracts.md | Type index matching hosted JSON endpoints |
| docs/error-model.md | Complete error code listing and code mappings |
| docs/integration-guide.md | End-to-end integration walkthroughs |
| docs/security.md | API key and token security guidelines |
| docs/transport.md | Transport configurations, retry loops, and error-handling |
- Official Website: aureonlabs.network
- Operator Utility Platform: app.aureonlabs.network
- Twitter / X: @buildaureon
- GitHub Repository: github.com/buildaureon