Autonomi

Documentation

Everything you need to use Autonomi and build on it — from connecting your wallet to integrating the API.

Overview

Autonomi is autonomous lending protection on Arc. You deposit USYC (tokenized Treasury) as collateral and borrow USDC. An agent monitors your loan-to-value (LTV) 24/7 and automatically calls autoRebalance when risk gets too high, so your position stays within safe bounds without you watching the charts.

For users: Connect your wallet (Arc Testnet), view your position and USYC yield on the dashboard, and optionally register a phone number for SMS alerts (rebalances, LTV warnings, big price moves). Only you can register or change the number for your wallet — we verify ownership with a signature.

For developers: The REST API v1 exposes positions, agent status, and alerts. Create API keys, register webhooks for rebalance / warning / price events, and build dashboards, bots, or wallets. OpenAPI spec and interactive docs are available at /api/v1/docs when the backend is running.

For Users

Connect your wallet

Use Launch App and connect with MetaMask, Coinbase Wallet, Rabby, or another Arc-compatible wallet. We use Arc Testnet (Chain ID 5042002). Your address is used to load your position and to manage SMS alerts — we never store your private key.

Dashboard

After connecting, the dashboard shows live USYC price, your collateral and borrowed amount, LTV, and whether the agent is running. Stats and position data load only when your wallet is connected.

SMS Alerts

Go to Alerts to register a phone number (E.164, e.g. +15551234567). You'll sign a message in your wallet to prove ownership — then we can send you SMS when the agent rebalances your position, when LTV is high, or when USYC price moves sharply. One number per wallet; only you can change it. You can also send a test SMS to confirm delivery.

Getting Started (Self-Host / Dev)

1. Clone and env

Copy .env.example to .env in the project root and in backend/. Set ARC_TESTNET_RPC_URL (e.g. https://rpc.testnet.arc.network) and PRIVATE_KEY (your deployer wallet).

2. Fund the wallet

Get testnet USDC from the Circle Faucet — choose Arc Testnet and paste your wallet address.

3. Deploy contracts

From the repo root, with Foundry installed:

source .env
forge build
# Deploy Autonomi + mocks (see script/DeployWithMockCollateral.s.sol)
# Save AUTONOMI_ADDRESS in backend/.env

4. Run the backend

In backend/.env set AUTONOMI_ADDRESS and AGENT_PRIVATE_KEY (same as deployer key). Authorize the agent on-chain:

cast send $AUTONOMI_ADDRESS "authorizeAgent(address)" <YOUR_DEPLOYER_ADDRESS> \
  --rpc-url $ARC_TESTNET_RPC_URL --private-key $PRIVATE_KEY

Then run npm run dev in backend/.

5. Open the web app

Serve the web/ folder (e.g. python3 -m http.server 8787 --directory web) and open the dashboard. It will request live data from http://localhost:3000/api/dashboard.

Protocol

Autonomi contract

Core functions: depositCollateral(amount), borrow(amount), repay(amount). LTV is computed as (USDC borrowed × 10000 × 1e18) / (USYC deposited × USYC price). Only an authorized agent can call autoRebalance(user, targetLTVBps) to bring a position toward the target LTV (e.g. 60%).

LTV and rebalancing

When LTV exceeds a threshold (e.g. 65%), the backend agent calls autoRebalance(user, 6000) (60% target). The contract repays debt or adjusts collateral as needed. The agent runs on a cron (e.g. every 5 minutes) and checks all watched addresses.

Oracles

USYC price is read from a teller contract (on testnet, MockTeller returns a fixed price). In production, Stork oracle feeds are used.

SMS Alerts

Alerts are stored per wallet in a JSON registry. To register or change your number you must sign a time-bound message in your wallet; the backend verifies the signature so only the wallet owner can add or update a number. Each phone number can be linked to at most one wallet. Rate limits apply (e.g. 5 registrations per hour per address, 3 test SMS per 10 minutes) to prevent abuse. Events sent: rebalance, LTV warning, large price move, optional daily summary.

API

The backend exposes a dashboard endpoint and a full REST API v1 for integrations.

GET /api/dashboard

Query: address (required when using the app — pass the connected wallet address). The server returns position data for that address only; no default wallet.

Response:

{
  "usycPrice": "1.05",
  "position": {
    "usycDeposited": "1000",
    "usdcBorrowed": "600",
    "ltvBps": 5700,
    "active": true
  }
}

If there is no active position, position is null. CORS is enabled for the web app.

REST API v1

Base URL: /api/v1. Versioned, consistent envelope: { success, data?, error?, meta: { version, timestamp } }.

  • Health & market: GET /api/v1/health, GET /api/v1/market
  • Positions: GET /api/v1/positions/:address or GET /api/v1/positions?addresses=0x...,0x... (batch, max 20)
  • Agent: GET /api/v1/agent — running, contract, watched count
  • Alerts: GET /api/v1/alerts/status?address=0x...; POST /api/v1/alerts/register, preferences, test (require wallet signature in body)
  • Auth: POST /api/v1/auth/keys to create API keys; GET /api/v1/auth/keys?address=0x...; DELETE /api/v1/auth/keys/:id. Use Authorization: Bearer <key> on protected routes.
  • Webhooks: POST /api/v1/webhooks (url, events: rebalance, warning, price), list, update, delete; deliveries logged.
  • Analytics: GET /api/v1/analytics/overview, webhooks?hours=24, usage?days=7

Interactive docs: GET /api/v1/docs (Swagger UI). OpenAPI spec: GET /api/v1/openapi.json.

References