Skip to main content

​
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

​
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: Mage 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: Mage uses standard compound interest formulas to calculate earnings, with real-time calculation of accrued interest.
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