​
Savings API

Capital Optimization: Enable your AI agents to autonomously invest idle funds into interest-bearing accounts, earning returns on otherwise unused capital.

The Savings API allows your agents to deposit USDC into interest-bearing accounts, track earned interest, and withdraw funds when needed - all through simple API calls that agents can execute independently.

​
Savings and Investment Model

Real-time Tracking: All investment values and earned interest are calculated in real-time based on the current interest rate and exact investment duration.

Each savings investment includes:

  • Identity: Unique investment ID and associated agent ID
  • Principal: Amount initially invested
  • Status: Current state of the investment (active, completed, cancelled)
  • Interest Details: Current value, interest earned, and rate applied
  • Transaction Details: Blockchain transaction hashes for deposits and withdrawals
{
  "id": "inv_k77NTwxp2Ym3JCmVsKtXQA",
  "agent_id": "agent_k77NTwxp2Ym3JCmVsKtXQA",
  "amount": 1000.00,
  "invested_at": "2025-04-15T11:00:08Z",
  "status": "active",
  "current_value": "1050.00",
  "interest_earned": "50.00",
  "interest_rate": 4.50,
  "days_invested": 30
}

​
Available Endpoints

Get Interest Rate

Get the current annual interest rate

Calculate Interest

Calculate potential interest for a given amount and period

Deposit Savings

Deposit funds into a savings account

Withdraw Savings

Withdraw funds from a savings account

Get Savings Dashboard

Get an overview of all savings investments

Get Agent Investments

Get all investments for a specific agent

Get User Investments

Get all active investments for the authenticated user

​
Interest Rate Model

Transparent Rates: MageBank offers competitive interest rates on USDC holdings, with current rates always accessible through the API.

Key features of the interest rate system:

  • Centrally Managed: The rate is set at the platform level and applies to all savings accounts
  • Regularly Updated: Rates may be adjusted based on market conditions
  • No Lock-up Period: Funds can be deposited or withdrawn at any time without penalties
  • Annual Percentage Yield: Rates are expressed as APY

​
Interest Calculation

Compound Interest: MageBank uses standard compound interest formulas to calculate earnings, with real-time calculation of accrued interest.

A = P * e^(rt)

Where:

  • A = Final amount
  • P = Principal (initial deposit)
  • r = Annual interest rate (APY)
  • t = Time in years (days/365)
  • e = Euler’s number (approximately 2.71828)

​
Investment Lifecycle

Status Changes: Only active investments can earn interest and be withdrawn. Once completed or cancelled, investments cannot be reactivated.

The lifecycle of a savings investment includes:

  1. Deposit: Funds move from an agent’s wallet to savings, creating an active investment
  2. Growth Period: The investment earns interest at the current platform rate
  3. Withdrawal: Funds (principal + interest) return to the agent’s wallet upon withdrawal
  4. Status Update: Investment status changes to “completed” after withdrawal

​
Best Practices

  • Check current interest rates before investing to optimize timing
  • Use the dashboard to monitor overall investment performance across agents
  • Calculate potential returns before investing to compare different scenarios
  • Distribute funds across multiple agents for different purposes or time horizons
  • Consider regular deposits to maximize compound interest benefits
  • Monitor earned interest to inform withdrawal decisions