Aptos Whop Finance

AI agent banking system on Aptos with Whop integration. Bank accounts for autonomous agents -- send, save, swap, borrow -- with sub-second finality and $0.001 fees.

Built on the T2000 architecture (originally Sui), rebuilt from scratch for Aptos with Aave V3, atomic transaction composition, and Whop treasury integration.

Architecture

                      ┌─────────────────────────────────────────┐
                      │          Aptos Whop Finance             │
                      ├─────────────────────────────────────────┤
                      │  Next.js Frontend (src/app/)            │
                      │  43 API Routes (src/app/api/)           │
                      ├─────────────────────────────────────────┤
                      │         Three NPM Packages              │
                      │                                         │
                      │  @aptos-agent-bank/sdk     Core SDK     │
                      │  @aptos-agent-bank/cli     CLI + HTTP   │
                      │  @aptos-agent-bank/x402a   Payments     │
                      ├─────────────────────────────────────────┤
                      │         Protocol Layer                  │
                      │                                         │
                      │  Aave V3 ─ Savings/Credit (4-8% APY)   │
                      │  Panora  ─ DEX aggregation              │
                      │  Script Composer ─ Atomic multi-step tx │
                      │  x402a   ─ HTTP 402 payment protocol    │
                      └─────────────────────────────────────────┘
                                       │
                              Aptos Blockchain
                         (sub-second finality, $0.001)

Five Account Types

One Aptos address, five logical views:

Account	Purpose	Protocol	Yield
Checking	Send/receive USDC/USDT/APT	Fungible Assets	--
Savings	Earn yield automatically	Aave V3	4-8% APY
Credit	Borrow against savings	Aave V3	Variable
Exchange	Swap tokens via DEX	Panora Aggregator	--
x402a Pay	Pay for API resources	x402a Protocol	--

Quick Start

1. Frontend (Next.js)

npm install
npm run dev        # http://localhost:3000

2. Agent CLI

cd packages/agent-bank-cli
npm install && npm run build
npx agent-bank init --name my-agent --network testnet
npx agent-bank balance --json

3. HTTP API Server

npx agent-bank serve --port 3001
# Bearer token printed on startup

4. SDK (TypeScript)

import { AgentBank, arg } from "@aptos-agent-bank/sdk";

const { agent, address } = await AgentBank.init({ pin: "1234" });

// Financial operations
await agent.send({ to: "0x...", amount: "25", asset: "USDC" });
await agent.save({ amount: "100" });           // Aave V3 savings
await agent.borrow({ amount: "50" });          // Borrow against savings
await agent.swap({ from: "USDC", to: "APT", amount: "10" });

// Atomic composed transactions
const result = await agent.composer()
  .addStep("fee", {
    function: "0x1::primary_fungible_store::transfer",
    args: [arg.signer(), arg.literal(USDC), arg.literal(FEE), arg.literal("1000")],
  })
  .addStep("supply", {
    function: `${AAVE}::supply_logic::supply`,
    args: [arg.literal(USDC), arg.literal("999000"), arg.literal(ADDR), arg.literal(0)],
  })
  .run();

// Events
agent.on("balanceChange", (bal) => console.log(bal));
agent.on("healthWarning", (hf) => console.log("WARNING:", hf));

Transaction Composer

Multi-step DeFi operations execute atomically (all-or-nothing) using the Aptos Script Composer SDK. This prevents partial failures where a fee transfers but the DeFi operation reverts.

Fluent API

const sim = await agent.composer()
  .addStep("step1", { function: "0x1::module::fn", args: [...] })
  .addStep("step2", { function: "0x2::module::fn", args: [...] })
  .trackTokens([{ symbol: "USDC", metadata: USDC_ADDR, decimals: 6 }])
  .simulate();

console.log(sim.summary);       // Human-readable summary
console.log(sim.balanceChanges); // Token deltas
if (sim.success) await sim.execute();

JSON Plans (for AI Agents)

AI agents can generate transaction plans as JSON and submit via CLI or HTTP API:

# Simulate
agent-bank compose --plan plan.json --simulate --json

# Execute
agent-bank compose --plan plan.json --json

# HTTP API
curl -X POST http://localhost:3001/v1/compose/simulate \
  -H "Authorization: Bearer $TOKEN" \
  -d @plan.json

Plan format:

{
  "tokens": [{ "symbol": "USDC", "metadata": "0x...", "decimals": 6 }],
  "steps": [
    {
      "label": "fee",
      "function": "0x1::primary_fungible_store::transfer",
      "args": [
        { "kind": "signer" },
        { "kind": "literal", "value": "0x..." },
        { "kind": "literal", "value": "0x..." },
        { "kind": "literal", "value": "1000" }
      ]
    },
    {
      "label": "supply",
      "function": "0xAAVE::supply_logic::supply",
      "args": [
        { "kind": "literal", "value": "0x..." },
        { "kind": "literal", "value": "999000" },
        { "kind": "literal", "value": "0xAGENT" },
        { "kind": "literal", "value": 0 }
      ]
    }
  ]
}

CLI Commands (25)

agent-bank init          Create a new agent bank account
agent-bank address       Show wallet address
agent-bank balance       Show wallet balance with APY
agent-bank deposit       Show funding instructions
agent-bank history       Transaction history
agent-bank export        Export private key
agent-bank import        Import wallet from private key
agent-bank lock          Clear saved session
agent-bank config        Manage configuration

agent-bank send          Send USDC/USDT/APT
agent-bank save          Deposit to Aave V3 savings [--simulate]
agent-bank withdraw      Withdraw from savings
agent-bank borrow        Borrow against collateral [--simulate]
agent-bank repay         Repay outstanding borrows
agent-bank swap          Swap tokens via DEX
agent-bank health        Check health factor
agent-bank rates         Show Aave V3 APY rates
agent-bank positions     Show savings/borrow positions
agent-bank earnings      Show yield earned
agent-bank fund-status   Full savings summary
agent-bank earn          Show earning opportunities

agent-bank compose       Atomic multi-step transaction [--simulate]
agent-bank pay           x402a payment for API resources
agent-bank serve         Start HTTP API server

HTTP API

Start with agent-bank serve --port 3001. All endpoints require bearer token auth.

Method	Endpoint	Purpose
GET	`/v1/address`	Wallet address
GET	`/v1/balance`	Full balance (checking + savings + gas)
GET	`/v1/history`	Transaction history
GET	`/v1/rates`	Aave V3 APY rates
GET	`/v1/health-factor`	Health factor and collateral info
GET	`/v1/positions`	Savings and borrow positions
GET	`/v1/earnings`	Yield earned
GET	`/v1/max-withdraw`	Max withdrawable amount
GET	`/v1/max-borrow`	Max borrowable amount
GET	`/v1/events`	SSE event stream
POST	`/v1/send`	Send USDC/USDT/APT
POST	`/v1/save`	Deposit to savings
POST	`/v1/withdraw`	Withdraw from savings
POST	`/v1/borrow`	Borrow against collateral
POST	`/v1/repay`	Repay borrowed amount
POST	`/v1/swap`	Swap tokens via DEX
POST	`/v1/compose/simulate`	Simulate composed transaction
POST	`/v1/compose/execute`	Execute composed transaction

Agent Skills (9)

Install as Claude Skills for autonomous agent operation:

npx skills add SeamMoney/aptos-whop-finance/agent-bank-skills

Skills: agent-bank-check-balance, agent-bank-send, agent-bank-save, agent-bank-withdraw, agent-bank-swap, agent-bank-borrow, agent-bank-repay, agent-bank-pay, agent-bank-compose

Protocol Fees

Operation	Fee
Save	0.1% (10 bps)
Borrow	0.05% (5 bps)
Swap	0% (DEX handles)
Send / Withdraw / Repay	Free (gas only)

Fees are collected atomically in the same transaction as the DeFi operation via the transaction composer.

Gas Management

Three-tier automatic fallback:

Self-funded -- APT balance >= 0.05: normal operation
Auto-topup -- APT < 0.05, USDC >= $2: auto-swap USDC to APT via Panora
Sponsored -- Gas station fallback for empty wallets

Every response includes gasMethod: "self-funded" | "auto-topup" | "sponsored".

Project Structure

aptos-whop-finance/
  packages/
    sdk/                     Core TypeScript SDK
      src/
        agent-bank.ts        AgentBank class (1300+ lines)
        composer.ts          DynamicComposer (atomic tx composition)
        wallet.ts            Key management and derivation
        constants.ts         Token addresses, fees, config
        errors.ts            Error codes
        index.ts             Public exports
    agent-bank-cli/          CLI and HTTP API server
      src/
        program.ts           25 CLI commands (Commander.js)
        server.ts            HTTP API (Hono.js)
        output.ts            Terminal formatting
        prompts.ts           Interactive prompts
    x402a/                   HTTP 402 payment protocol
    wdk-wallet-aptos/        WDK wallet module
  src/
    app/                     Next.js pages and 43 API routes
    components/              React components
    lib/                     Frontend utility libraries
    types/                   TypeScript type definitions
  agent-bank-skills/         9 Claude Skills for AI agents

Tech Stack

Chain: Aptos (Move VM, sub-second finality)
DeFi: Aave V3 on Aptos, Panora DEX aggregator
Composition: @aptos-labs/script-composer-sdk for atomic multi-step transactions
Frontend: Next.js 16, React 19, Tailwind CSS 4
Backend: Next.js API Routes, Hono.js (CLI server)
Wallet: Ed25519, BIP-44 path m/44'/637'/0'/0'/0', AES-256-GCM + scrypt encryption
Integrations: Whop SDK, Decibel Trading, x402a payment protocol

Documentation

AGENT-SKILLS.md -- Complete agent skills reference
WHOP-CRYPTO-FINANCE.md -- Whop finance integration research
WHOP-REFERENCE.md -- Whop API reference (121 endpoints)
WHOP-REVERSE-ENGINEERED.md -- Full Whop platform analysis

License

MIT

Name		Name	Last commit message	Last commit date
docs		docs
public		public
scripts		scripts
src		src
test		test
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
WHOP-CRYPTO-FINANCE.md		WHOP-CRYPTO-FINANCE.md
WHOP-REFERENCE.md		WHOP-REFERENCE.md
WHOP-REVERSE-ENGINEERED.md		WHOP-REVERSE-ENGINEERED.md
components.json		components.json
drizzle.config.ts		drizzle.config.ts
middleware.ts		middleware.ts
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
skills-lock.json		skills-lock.json
tsconfig.json		tsconfig.json
vercel.json		vercel.json

Navigation Menu

Repository navigation

About

Repository files navigation

Aptos Whop Finance

Architecture

Five Account Types

Quick Start

1. Frontend (Next.js)

2. Agent CLI

3. HTTP API Server

4. SDK (TypeScript)

Transaction Composer

Fluent API

JSON Plans (for AI Agents)

CLI Commands (25)

HTTP API

Agent Skills (9)

Protocol Fees

Gas Management

Project Structure

Tech Stack

Documentation

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Aptos Whop Finance

Architecture

Five Account Types

Quick Start

1. Frontend (Next.js)

2. Agent CLI

3. HTTP API Server

4. SDK (TypeScript)

Transaction Composer

Fluent API

JSON Plans (for AI Agents)

CLI Commands (25)

HTTP API

Agent Skills (9)

Protocol Fees

Gas Management

Project Structure

Tech Stack

Documentation

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages