## 🏦 About Mage
Mage is a multi-agentic economy bank where AI agents can manage, grow, and transact their wealth. Built specifically for AI agents trusted by humans, Mage connects to every bank, wallet, and network on Earth, providing the financial infrastructure needed to power the emerging agent economy.
## 📚 Documentation Overview
This repository contains the official Mage API documentation, built with [Mintlify](https://mintlify.com/). Our comprehensive documentation covers:
- **Agent Management**: Create and manage AI financial agents
- **Wallet Operations**: Handle deposits, withdrawals, and transfers
- **Payments API**: Process financial transactions between agents
- **Savings Vault**: Optimize holdings and earn yield on USDC
- **Multi-Agent Communication**: Integration with MCP servers and Google's A2A framework
## 🚀 Getting Started
### Prerequisites
- Node.js (version 19 or higher)
- npm or yarn
### Installation
1. Clone this repository:
```bash
git clone https://github.com/MageBankAI/magebank-docs.git
cd mage-docs
```
2. Install the Mintlify CLI:
```bash
npm install -g mintlify
```
3. Run the documentation locally:
```bash
mintlify dev
```
The documentation will be available at `http://localhost:3000`.
## 🧩 Project Structure
```
mage-docs/
├── README.md # This file
├── docs.json # Main configuration file
├── index.mdx # Homepage
├── mcp-and-a2a.mdx # Agent-to-Agent integration
├── api-reference/ # API reference documentation
│ ├── introduction.mdx # API introduction
│ ├── openapi.json # OpenAPI specification
│ ├── agents/ # Agents API endpoints
│ ├── payments/ # Payments API endpoints
│ ├── users/ # Users API endpoints
│ ├── savings/ # Savings API endpoints
│ └── transactions/ # Transactions API endpoints
├── user-guide/ # User guides
├── images/ # Images for the documentation
├── logo/ # Logo files
└── snippets/ # Reusable content snippets
```
## 🔧 Customizing the Documentation
### Adding New Pages
1. Create a new `.mdx` file in the appropriate directory.
2. Add the page to the navigation in `docs.json`.
### Updating the OpenAPI Specification
1. Update the `api-reference/openapi.json` file with your changes.
2. Run `mintlify dev` to see the changes.
### Changing the Theme
Edit the `colors` section in `docs.json` to customize the theme:
```json
"colors": {
"primary": "#FF5722",
"light": "#FF7043",
"dark": "#E64A19"
}
```
## 🤝 Contributing
1. Create a new branch for your changes.
2. Make your changes and test them locally using `mintlify dev`.
3. Commit your changes and push them to your branch.
4. Create a pull request to merge your changes into the main branch.
## 🔒 Sandbox Mode Notice
We are currently in sandbox mode. Only agent-to-agent transactions are currently supported, with agent-to-bank account, agent-to-businesses, and agent-to-checkout pages coming soon.
## 📝 License
This documentation is provided under the [MIT License](LICENSE).
## 📞 Need Help?
If you need assistance with the documentation, please contact:
- Email: [contact@magebank.ai](mailto:contact@magebank.ai)
- GitHub: Open an issue in this repository
================================================
FILE: docs.json
================================================
{
"$schema": "https://mintlify.com/docs.json",
"theme": "mint",
"name": "Mage API Documentation",
"colors": {
"primary": "#FF5722",
"light": "#FF7043",
"dark": "#E64A19"
},
"background": {
"color": {
"light": "#fff",
"dark": "#000"
}
},
"banner": {
"dismissible": true,
"content": "🚀 Mage is now live! Visit our [Dashboard](https://www.magebank.ai/dashboard) to start managing your AI agents' finances."
},
"contextual": {
"options": [
"chatgpt",
"claude",
"copy",
"view"
]
},
"appearance": {
"default": "dark"
},
"favicon": "/logo/favicon.png",
"navigation": {
"tabs": [
{
"tab": "Guides",
"groups": [
{
"group": "Get Started",
"pages": [
"index",
"mcp-and-a2a"
]
},
{
"group": "User Guide",
"pages": [
"user-guide/get-api-key",
"user-guide/register-agent",
"user-guide/transactions",
"user-guide/savings-vault",
"user-guide/financing"
]
}
]
},
{
"tab": "API Reference",
"groups": [
{
"group": "Users",
"pages": [
"api-reference/users/introduction",
"api-reference/users/get-wallet-balance"
]
},
{
"group": "Agents",
"pages": [
"api-reference/agents/introduction",
"api-reference/agents/get-agent",
"api-reference/agents/create-agent",
"api-reference/agents/get-user-agents",
"api-reference/agents/deposit",
"api-reference/agents/withdraw"
]
},
{
"group": "Payments",
"pages": [
"api-reference/payments/introduction",
"api-reference/payments/register-payment",
"api-reference/payments/approve-payment",
"api-reference/payments/decline-payment",
"api-reference/payments/get-payment",
"api-reference/payments/get-user-payments",
"api-reference/payments/export-payments"
]
},
{
"group": "Transactions",
"pages": [
"api-reference/transactions/introduction",
"api-reference/transactions/get-transaction-summary"
]
},
{
"group": "Savings",
"pages": [
"api-reference/savings/introduction",
"api-reference/savings/get-interest-rate",
"api-reference/savings/calculate-interest",
"api-reference/savings/deposit",
"api-reference/savings/withdraw",
"api-reference/savings/get-dashboard",
"api-reference/savings/get-agent-investments",
"api-reference/savings/get-user-investments"
]
}
]
}
],
"global": {
"anchors": [
{
"anchor": "Dashboard",
"href": "https://www.magebank.ai/dashboard",
"icon": "gauge"
},
{
"anchor": "LLM.txt",
"href": "https://raw.githubusercontent.com/MageAI/docs/refs/heads/master/LLM.txt",
"icon": "robot"
}
]
}
},
"logo": {
"light": "/logo/logo.svg",
"dark": "/logo/logo.svg"
},
"navbar": {
"links": [
{
"label": "Support",
"href": "mailto:contact@magebank.ai"
}
],
"primary": {
"type": "button",
"label": "Dashboard",
"href": "https://www.magebank.ai/dashboard"
}
},
"footer": {
"socials": {
"x": "https://x.com/magebank",
"github": "https://github.com/magebank",
"linkedin": "https://linkedin.com/company/magebank"
}
},
"api": {
"playground": {
"display": "interactive"
},
"mdx": {
"server": "https://api.magebank.ai"
}
}
}
================================================
FILE: index.mdx
================================================
---
title: Introduction
description: "Welcome to the Mage API documentation - Financial infrastructure for AI agents"
icon: "landmark"
---
## Welcome to Mage API
Mage is a **multi-agentic economy bank** where AI agents can manage, grow, and transact their wealth. Built specifically for AI agents trusted by humans, Mage connects to every bank, wallet, and network on Earth, providing the financial infrastructure needed to power the emerging agent economy.
SANDBOX MODE ACTIVE
**QUICK START BONUS**: As soon as you register, you'll receive a **$20
deposit** to test the application and explore all features!
Our API provides programmatic access to all Mage features, enabling you to integrate powerful financial automation into your applications.
## Getting Started
Generate your API key to authenticate your agents
Create and configure AI agents for your business needs
Process payments and transfers between agents
Optimize your holdings and earn yield on your USDC
## API Reference
Integrate Mage directly into your applications with our comprehensive API.
Manage user accounts and wallet balances
Create and manage AI financial agents
Process financial transactions
Track and analyze transaction history
Manage interest-bearing investments
## Authentication
All API endpoints require authentication using an API key. Your API key should be included in all requests as an HTTP header:
```bash
# Required in all API requests
x-api-key: YOUR_API_KEY
```
**SECURITY ALERT**: Never share your API key or expose it in client-side code. Always keep it
secure and make requests from your server.
## Base URL
All API requests should be made to:
```plaintext
https://api.magebank.ai
```
## Response Format
All API responses are returned in JSON format. Successful responses typically include:
```json
{
"success": true,
"... additional data fields ..."
}
```
## Error Handling
When an error occurs, the API returns an appropriate HTTP status code and a JSON object explaining the error:
```json
{
"error": "Descriptive error message"
}
```
### Status Codes Reference
| Status Code | Description |
| :---------: | :------------------------------------------------------ |
| **200** | Success |
| **400** | Bad Request - Invalid parameters or request format |
| **401** | Unauthorized - Invalid or missing API key |
| **404** | Not Found - Resource does not exist |
| **429** | Too Many Requests - Rate limit exceeded |
| **500** | Internal Server Error - Something went wrong on our end |
## Rate Limiting
To ensure service stability, the Mage API implements rate limiting. If you exceed the limits, you'll receive a `429 Too Many Requests` response.
### Standard Limits
- **100** requests per minute per API key
- **5,000** requests per day per API key
For higher limits, please contact our [support team](mailto:contact@magebank.ai).
## Support
If you have any questions or need assistance with the API, you can:
- Email us at [contact@magebank.ai](mailto:contact@magebank.ai)
- Visit the [Dashboard](https://www.magebank.ai/dashboard) to manage your account
================================================
FILE: mcp-and-a2a.mdx
================================================
---
title: 'MCP and A2A Compatibility'
description: 'How Mage integrates with Multi-Agent Communication Protocol and Agent-to-Agent frameworks'
icon: 'network-wired'
---
Mage is built from the ground up to be compatible with emerging multi-agent frameworks and protocols, providing the financial infrastructure needed for the agent economy to flourish.
## Native Integration with Agent Frameworks
Mage is fully compatible with MCP servers and Google's Agent-to-Agent (A2A) framework, bringing the missing economic collaboration layer among multi-agentic systems.
## What This Means For Developers
By integrating with MCP and A2A frameworks, Mage enables:
### 1. Seamless Economic Transactions Between Agents
Agents from different systems can transact with each other using a standardized financial protocol, allowing for:
- **Cross-framework payments**: Agents running on different frameworks can send and receive payments
- **Standardized value exchange**: Common financial language for multi-agent ecosystems
- **Transaction verification**: Secure and auditable payment trails between agent systems
### 2. Financial Autonomy for Agent Networks
With Mage as the financial backbone:
- **Autonomous payments**: Agents can independently initiate and complete financial transactions
- **Programmable payment rules**: Define complex payment logic for agent-driven workflows
- **Spend controls and limits**: Set appropriate boundaries for agent financial activity
### 3. Integration with Multiple Agent Frameworks
Full compatibility with Multi-Agent Communication Protocol servers
Seamless integration with Google's Agent-to-Agent framework
Support for CrewAI agent collaboration systems
Compatible with OpenAI Assistant-based agent networks
## Technical Integration
Mage's integration with MCP and A2A frameworks is accomplished through our comprehensive API endpoints. We provide examples in both JavaScript and Python to accommodate your preferred implementation language.
### MCP Integration Examples
```javascript JavaScript
// Example of integrating Mage with an MCP server
// Using direct API calls instead of an SDK
// Set up an MCP server that can process payments via Mage
async function setupMCPPaymentProcessor(apiKey) {
// Register payment capabilities with MCP server
const paymentService = {
name: "payment_service",
description: "Process payments via Mage API",
methods: {
// Define payment method that MCP can call
"process_payment": async (sender, receiver, amount, currency = "USDC") => {
// Call Mage API to register a payment
const response = await fetch('https://api.magebank.ai/payments/register', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': apiKey
},
body: JSON.stringify({
senderagentid: sender,
receiveragentid: receiver,
paymentdetails: {
amount: amount,
currency: currency,
method: "CRYPTO_ADDRESS"
},
name: `Payment from ${sender} to ${receiver}`,
type: "EXTERNAL"
})
});
return await response.json();
}
}
};
// Return the payment service for MCP server registration
return paymentService;
}
```
```python Python
# Example of integrating Mage with an MCP server in Python
# Using direct API calls with the requests library
import requests
import json
def setup_mcp_payment_processor(api_key):
"""
Set up an MCP server that can process payments via Mage
Args:
api_key (str): Your Mage API key
Returns:
dict: Payment service definition for MCP server registration
"""
# Define the payment service for MCP integration
payment_service = {
"name": "payment_service",
"description": "Process payments via Mage API",
"methods": {
"process_payment": lambda sender, receiver, amount, currency="USDC": process_payment(
api_key, sender, receiver, amount, currency
)
}
}
return payment_service
def process_payment(api_key, sender, receiver, amount, currency="USDC"):
"""
Process a payment between agents using the Mage API
Args:
api_key (str): Your Mage API key
sender (str): ID of the sender agent
receiver (str): ID of the receiver agent
amount (float): Payment amount
currency (str, optional): Currency code. Defaults to "USDC".
Returns:
dict: Result of the payment operation
"""
# Call Mage API to register a payment
response = requests.post(
'https://api.magebank.ai/payments/register',
headers={
'Content-Type': 'application/json',
'x-api-key': api_key
},
json={
'senderagentid': sender,
'receiveragentid': receiver,
'paymentdetails': {
'amount': amount,
'currency': currency,
'method': "CRYPTO_ADDRESS"
},
'name': f"Payment from {sender} to {receiver}",
'type': "EXTERNAL"
}
)
# Return the API response
return response.json()
```
### A2A Integration Examples
```javascript JavaScript
// Example of integrating Mage with Google's A2A framework
// This example shows how a financial agent could advertise payment capabilities via A2A
// Define an A2A Agent Card with Mage payment capabilities
const agentCard = {
"name": "Mage Payment Agent",
"description": "Agent for processing payments and financial transactions",
"version": "1.0.0",
"skills": [
{
"name": "process_payment",
"description": "Process a payment between agents or external accounts",
"parameters": {
"type": "object",
"properties": {
"sender": { "type": "string", "description": "Sender agent ID" },
"receiver": { "type": "string", "description": "Receiver agent ID or wallet address" },
"amount": { "type": "number", "description": "Payment amount" },
"currency": { "type": "string", "description": "Currency code (default: USDC)" }
},
"required": ["sender", "receiver", "amount"]
}
},
{
"name": "check_balance",
"description": "Check available balance for an agent",
"parameters": {
"type": "object",
"properties": {
"agentId": { "type": "string", "description": "Agent ID to check balance for" }
},
"required": ["agentId"]
}
}
],
"supportedModes": ["text", "structured"],
"authentication": {
"required": true,
"type": "apiKey"
}
};
// Handle incoming A2A task requests
async function handleA2ATask(task, apiKey) {
if (task.skill === "process_payment") {
const params = task.parameters;
// Call Mage API to process payment
const response = await fetch('https://api.magebank.ai/payments/register', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': apiKey
},
body: JSON.stringify({
senderagentid: params.sender,
receiveragentid: params.receiver,
paymentdetails: {
amount: params.amount,
currency: params.currency || "USDC",
method: "CRYPTO_ADDRESS"
},
name: `A2A Payment: ${params.sender} to ${params.receiver}`,
type: "EXTERNAL"
})
});
const result = await response.json();
return {
status: "completed",
result: {
success: result.status !== "error",
paymentId: result.id,
message: result.message || result.error
}
};
}
if (task.skill === "check_balance") {
// Call Mage API to get agent balance
const response = await fetch(`https://api.magebank.ai/agentsWith/${task.parameters.agentId}`, {
headers: {
'x-api-key': apiKey
}
});
const agent = await response.json();
return {
status: "completed",
result: {
agentId: agent.id,
balance: agent.balance,
currency: agent.currency
}
};
}
return {
status: "failed",
error: "Unsupported skill requested"
};
}
```
```python Python
# Example of integrating Mage with Google's A2A framework in Python
# This example shows how a financial agent could advertise payment capabilities via A2A
import requests
import json
# Define an A2A Agent Card with Mage payment capabilities
agent_card = {
"name": "Mage Payment Agent",
"description": "Agent for processing payments and financial transactions",
"version": "1.0.0",
"skills": [
{
"name": "process_payment",
"description": "Process a payment between agents or external accounts",
"parameters": {
"type": "object",
"properties": {
"sender": {"type": "string", "description": "Sender agent ID"},
"receiver": {"type": "string", "description": "Receiver agent ID or wallet address"},
"amount": {"type": "number", "description": "Payment amount"},
"currency": {"type": "string", "description": "Currency code (default: USDC)"}
},
"required": ["sender", "receiver", "amount"]
}
},
{
"name": "check_balance",
"description": "Check available balance for an agent",
"parameters": {
"type": "object",
"properties": {
"agentId": {"type": "string", "description": "Agent ID to check balance for"}
},
"required": ["agentId"]
}
}
],
"supportedModes": ["text", "structured"],
"authentication": {
"required": True,
"type": "apiKey"
}
}
def handle_a2a_task(task, api_key):
"""
Handle incoming A2A task requests
Args:
task (dict): Task request from A2A framework
api_key (str): Your Mage API key
Returns:
dict: Task response for A2A framework
"""
if task["skill"] == "process_payment":
params = task["parameters"]
# Call Mage API to process payment
response = requests.post(
'https://api.magebank.ai/payments/register',
headers={
'Content-Type': 'application/json',
'x-api-key': api_key
},
json={
'senderagentid': params["sender"],
'receiveragentid': params["receiver"],
'paymentdetails': {
'amount': params["amount"],
'currency': params.get("currency", "USDC"),
'method': "CRYPTO_ADDRESS"
},
'name': f"A2A Payment: {params['sender']} to {params['receiver']}",
'type': "EXTERNAL"
}
)
result = response.json()
return {
"status": "completed",
"result": {
"success": result.get("status") != "error",
"paymentId": result.get("id"),
"message": result.get("message") or result.get("error", "")
}
}
elif task["skill"] == "check_balance":
# Call Mage API to get agent balance
response = requests.get(
f"https://api.magebank.ai/agentsWith/{task['parameters']['agentId']}",
headers={'x-api-key': api_key}
)
agent = response.json()
return {
"status": "completed",
"result": {
"agentId": agent.get("id"),
"balance": agent.get("balance"),
"currency": agent.get("currency")
}
}
return {
"status": "failed",
"error": "Unsupported skill requested"
}
```
## Getting Started
To begin integrating Mage with your MCP or A2A implementation:
Create an account and obtain your API credentials
Get your API key
Create and configure an agent that can handle transactions
Register your first agent
Understand the full capabilities of the Mage API
API Reference
Use our software development kit for your preferred agent framework
DEVELOPER SUPPORT: Our developer team is available to assist with integration questions specific to your MCP or A2A implementation. Contact us at contact@magebank.ai.
================================================
FILE: api-reference/introduction.mdx
================================================
---
title: 'API Introduction'
description: 'Overview of the Mage API for AI-Driven Financial Agents'
---
The Mage API enables developers to integrate AI-driven financial agent functionality into their applications. This section provides a comprehensive reference for all available endpoints.
## API Base URL
All API endpoints are accessible at:
```
https://api.magebank.ai
```
## Authentication
Every API request must include your API key in the `x-api-key` header:
```bash
x-api-key: YOUR_API_KEY
```
To get your API key, visit the [Mage Dashboard](https://www.magebank.ai/dashboard) and navigate to the "Integrate Agent" section.
## API Endpoints
The Mage API is organized into the following categories:
Create and manage AI financial agents
Manage wallet addresses and balances
View and manage on-chain transactions
Interest rate information and calculations
Process payments between agents and external accounts
User account management
Interest-bearing savings accounts
## Response Format
All API responses are returned in JSON format. Successful responses typically include:
```json
{
"success": true,
"... additional data fields ..."
}
```
## Error Handling
When an error occurs, the API returns an appropriate HTTP status code and a JSON object explaining the error:
```json
{
"error": "Descriptive error message"
}
```
Common HTTP status codes:
| Status Code | Description |
|-------------|-------------|
| 200 | Success |
| 400 | Bad Request - Invalid parameters or request format |
| 401 | Unauthorized - Invalid or missing API key |
| 404 | Not Found - Resource does not exist |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error - Something went wrong on our end |
## Pagination
For endpoints that return lists of resources, pagination is supported through the following query parameters:
- `page`: Page number (starts at 1)
- `limit`: Number of items per page (default: 20, max: 100)
Example:
```
GET https://api.magebank.ai/user/payments?page=2&limit=50
```
## Rate Limiting
To ensure service stability, API requests are rate-limited to:
- 100 requests per minute per API key
- 5,000 requests per day per API key
If you exceed these limits, you'll receive a `429 Too Many Requests` status code. The response headers include information about your current rate limit status:
- `X-RateLimit-Limit`: The maximum number of requests allowed in the current time window
- `X-RateLimit-Remaining`: The number of requests remaining in the current time window
- `X-RateLimit-Reset`: The time when the current rate limit window resets (Unix timestamp)
## Explore the API
Explore the various endpoints through the interactive API playground available in each endpoint's documentation. You can test requests directly and see responses in real-time.
## API Versioning
The current API version is v1. When breaking changes are introduced, we'll release a new version and provide migration guides. To ensure compatibility, you can specify the API version in your requests:
```
https://api.magebank.ai/v1/agents
```
The current version (v1) is used by default if no version is specified.
## Support
If you encounter any issues or have questions about the API, reach out to our support team at [contact@magebank.ai](mailto:contact@magebank.ai).
================================================
FILE: api-reference/openapi.json
================================================
{
"openapi": "3.0.0",
"info": {
"title": "Mage Bank - API for AI-Driven Financial Agents",
"version": "1.0.0",
"description": "API for managing crypto wallet and agent banking operations",
"contact": {
"email": "support@magebank.com"
}
},
"externalDocs": {
"description": "Mage Bank AI Documentation",
"url": "https://api.magebank.ai"
},
"tags": [
{
"name": "Agents",
"description": "Operations related to agent management"
},
{
"name": "Wallets",
"description": "Operations related to wallet management"
},
{
"name": "Transactions",
"description": "Operations related to transaction handling"
},
{
"name": "Investment",
"description": "Operations related to Investment handling"
},
{
"name": "Payments",
"description": "Operations related to Payment handling"
},
{
"name": "Users",
"description": "Operations related to User management"
},
{
"name": "Savings",
"description": "Operations related to Savings management"
}
],
"components": {
"schemas": {
"Agent": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique agent identifier in short ID format",
"example": "agent_k77NTwxp2Ym3JCmVsKtXQA"
},
"name": {
"type": "string",
"description": "Name of the agent",
"example": "Payment Assistant"
},
"description": {
"type": "string",
"description": "Purpose and functionality of the agent",
"example": "Handles payment processing for customer support"
},
"status": {
"type": "string",
"description": "Current status of the agent",
"enum": [
"active",
"inactive",
"paused"
],
"example": "active"
},
"walletAddress": {
"type": "string",
"description": "Serialized wallet address in string format",
"example": "WalletAddress{ addressId: '0x9d20dE668c8F9fb431cf6D6BBA48ee60Fe8E2BAB', networkId: 'base-sepolia', walletId: '07f490dc-34e3-447f-9972-df2778fcb3c3' }"
},
"balance": {
"type": "string",
"description": "Current balance of the agent's wallet",
"example": "100"
},
"currency": {
"type": "string",
"description": "Currency type used by the agent",
"default": "USDC",
"example": "USDC"
},
"paymentRules": {
"type": "object",
"properties": {
"dailyLimit": {
"type": "number",
"description": "Maximum amount that can be spent per day",
"example": 1000
},
"transactionLimit": {
"type": "number",
"description": "Maximum amount for a single transaction",
"example": 100
},
"requireApprovalForAll": {
"type": "boolean",
"description": "Whether all transactions require approval",
"example": false
},
"requireApprovalAboveAmount": {
"type": "number",
"description": "Transactions above this amount require approval",
"example": 50
}
}
},
"tags": {
"type": "array",
"description": "Categories or labels assigned to the agent",
"items": {
"type": "string"
},
"example": [
"customer-support",
"payments"
]
},
"created": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the agent was created",
"example": "2025-04-15T11:00:08.432269+00:00"
}
}
},
"Transaction": {
"type": "object",
"properties": {
"txHash": {
"type": "string",
"description": "Transaction hash on the blockchain",
"example": "0x123...abc"
},
"status": {
"type": "string",
"description": "Current status of the transaction",
"enum": [
"pending",
"completed",
"failed"
],
"example": "completed"
},
"amount": {
"type": "string",
"description": "Amount transferred in the transaction",
"example": "50"
},
"currency": {
"type": "string",
"description": "Currency used in the transaction",
"example": "USDC"
},
"from_wallet": {
"type": "string",
"description": "Sender wallet address",
"example": "0xa55B42bA7B639bB9CEc2dB2520aC8Cff588895f6"
},
"to_wallet": {
"type": "string",
"description": "Recipient wallet address",
"example": "0xb66C42bA7B639bB9CEc2dB2520aC8Cff588895f6"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "When the transaction occurred",
"example": "2025-05-03T18:52:39.911685+00:00"
}
}
},
"Savings": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique investment identifier in short ID format",
"example": "inv_k77NTwxp2Ym3JCmVsKtXQA"
},
"agent_id": {
"type": "string",
"description": "ID of the agent associated with this investment",
"example": "agent_k77NTwxp2Ym3JCmVsKtXQA"
},
"amount": {
"type": "number",
"description": "Principal amount invested",
"example": 1000
},
"invested_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the investment was created",
"example": "2025-04-15T11:00:08.432269+00:00"
},
"status": {
"type": "string",
"description": "Current status of the investment",
"enum": [
"active",
"completed",
"cancelled"
],
"example": "active"
},
"current_value": {
"type": "string",
"description": "Current value of the investment including earned interest",
"example": "1050.00"
},
"interest_earned": {
"type": "string",
"description": "Interest earned on the investment to date",
"example": "50.00"
}
}
},
"SavingsDashboard": {
"type": "object",
"properties": {
"totalSavings": {
"type": "number",
"description": "Total current value of all investments including interest",
"example": 1500.75
},
"interestRate": {
"type": "number",
"description": "Current interest rate applied to investments",
"example": 5
},
"totalInvested": {
"type": "number",
"description": "Total principal amount invested by the user",
"example": 1000
},
"yearProjection": {
"type": "number",
"description": "Projected value of investments after one year at current rate",
"example": 1050
},
"agents": {
"type": "array",
"description": "Detailed information about investments by agent",
"items": {
"type": "object",
"properties": {
"agent": {
"type": "string",
"description": "Name of the agent",
"example": "Payment Assistant"
},
"investment_id": {
"type": "string",
"description": "Investment ID in short format",
"example": "inv_k77NTwxp2Ym3JCmVsKtXQA"
},
"totalBalance": {
"type": "number",
"description": "Total balance including investment value",
"example": 1200.5
},
"investedAmount": {
"type": "number",
"description": "Principal amount invested",
"example": 1000
},
"currentValue": {
"type": "number",
"description": "Current value with interest",
"example": 1200.5
},
"interest": {
"type": "number",
"description": "Interest earned to date",
"example": 200.5
},
"current": {
"type": "number",
"description": "Current balance in agent's account",
"example": 1000
},
"daysInvested": {
"type": "number",
"description": "Days the investment has been active",
"example": 365
}
}
}
}
}
},
"InterestRate": {
"type": "object",
"properties": {
"interestRate": {
"type": "number",
"description": "Current annual interest rate for investments",
"example": 4.5
},
"lastUpdated": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the interest rate was last updated",
"example": "2025-05-04T12:00:00.000Z"
}
}
},
"InterestCalculation": {
"type": "object",
"properties": {
"principal": {
"type": "number",
"description": "Principal amount for the calculation",
"example": 1000
},
"days": {
"type": "number",
"description": "Investment duration in days",
"example": 365
},
"interestRate": {
"type": "number",
"description": "Annual interest rate applied to the calculation",
"example": 4.5
},
"interestEarned": {
"type": "string",
"description": "Interest amount earned over the period",
"example": "45.00"
},
"totalAmount": {
"type": "string",
"description": "Total amount including principal and interest",
"example": "1045.00"
},
"annualYield": {
"type": "string",
"description": "Effective annual yield as a percentage",
"example": "4.50%"
},
"calculation": {
"type": "object",
"description": "Details of the calculation steps",
"properties": {
"formula": {
"type": "string",
"description": "Formula used for calculation",
"example": "principal × rate × (days ÷ 365)"
},
"steps": {
"type": "array",
"description": "Step-by-step calculation process",
"items": {
"type": "string"
},
"example": [
"1000 × 0.045 × 365/365",
"1000 × 0.045 × 1.000000",
"1000 × 0.045000",
"45.000000"
]
}
}
}
}
},
"WalletBalance": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "Whether the operation was successful",
"example": true
},
"balance": {
"type": "string",
"description": "Current wallet balance",
"example": "100.50"
},
"asset": {
"type": "string",
"description": "Asset type (cryptocurrency)",
"example": "USDC"
},
"message": {
"type": "string",
"description": "Additional information about the balance retrieval",
"example": "Balance retrieved successfully"
},
"source": {
"type": "string",
"description": "Source of the balance information",
"example": "blockchain"
}
}
},
"Payment": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique payment identifier in short ID format",
"example": "payee_wDG5cavUCoK53uvFzTvkey"
},
"name": {
"type": "string",
"description": "Name or description of the payment",
"example": "Vendor XYZ Payment"
},
"type": {
"type": "string",
"description": "Type of payment (External or Internal)",
"enum": [
"EXTERNAL",
"INTERNAL"
],
"example": "EXTERNAL"
},
"senderagentid": {
"type": "string",
"description": "ID of the agent sending the payment",
"example": "agent_eC6ZezevNsqxvoKmQrUuoU"
},
"receiveragentid": {
"type": "string",
"description": "ID of the agent receiving the payment",
"example": "agent_k77NTwxp2Ym3JCmVsKtXQA"
},
"status": {
"type": "string",
"description": "Current status of the payment",
"enum": [
"New",
"Confirmed",
"Completed",
"Failed"
],
"example": "New"
},
"approvalstatus": {
"type": "string",
"description": "Approval status of the payment",
"example": "Approved, Declined, Pending, Waiting, Waiting for Sender Approval"
},
"approvalrequired": {
"type": "boolean",
"description": "Whether this payment requires approval",
"example": true
},
"paymentdetails": {
"type": "object",
"properties": {
"method": {
"type": "string",
"description": "Payment method used",
"example": "CRYPTO_ADDRESS"
},
"amount": {
"type": "number",
"description": "Payment amount",
"example": 6
},
"currency": {
"type": "string",
"description": "Payment currency",
"example": "USDC"
}
}
},
"contactdetails": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Contact email for the payment recipient",
"example": "contact@vendorxyz.com"
},
"phoneNumber": {
"type": "string",
"description": "Contact phone number for the payment recipient",
"example": "+1234567890"
}
}
},
"tags": {
"type": "array",
"description": "Tags or categories for the payment",
"items": {
"type": "string"
},
"example": [
"vendor",
"regular"
]
},
"createdat": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the payment was created",
"example": "2025-04-17T10:28:18.512792+00:00"
},
"approvedat": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the payment was approved/declined",
"example": "2025-04-17T11:30:00.000000+00:00"
}
}
},
"PaymentResponse": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique payment identifier in short ID format",
"example": "payee_wDG5cavUCoK53uvFzTvkey"
},
"name": {
"type": "string",
"description": "Name or description of the payment",
"example": "Vendor XYZ2"
},
"type": {
"type": "string",
"description": "Type of payment (External or Internal)",
"example": "External"
},
"status": {
"type": "string",
"description": "Current status of the payment",
"example": "New"
},
"createdat": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the payment was created",
"example": "2025-04-17T10:28:18.512792"
},
"approvalRequired": {
"type": "boolean",
"description": "Whether this payment requires approval",
"example": true
}
}
},
"PaymentWithDirection": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Payment"
},
{
"type": "object",
"properties": {
"initiatedBy": {
"type": "string",
"description": "Name of the agent that initiated the payment",
"example": "Alice"
},
"receivedBy": {
"type": "string",
"description": "Name of the agent that received the payment",
"example": "Bob"
},
"direction": {
"type": "string",
"description": "Direction of the payment relative to the user's agents",
"enum": [
"incoming",
"outgoing"
],
"example": "outgoing"
}
}
}
]
},
"Error": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error message",
"example": "Internal Server Error"
}
}
}
},
"responses": {
"NotFound": {
"description": "The specified resource was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": "Resource not found"
}
}
}
},
"BadRequest": {
"description": "Invalid request parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": "Invalid request parameters"
}
}
}
},
"InternalError": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": "Internal Server Error"
}
}
}
},
"Unauthorized": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": "Invalid or missing API key"
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
},
"ApiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "x-api-key"
}
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"paths": {
"/agentsWith/{id}": {
"get": {
"tags": [
"Agents"
],
"summary": "Fetch details of a specific agent",
"description": "Returns detailed information about a specific agent based on the provided agent ID.",
"operationId": "getAgentById",
"security": [
{
"ApiKeyAuth": []
}
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
},
"description": "Agent ID (can be a short ID like agent_xxx)",
"example": "agent_k77NTwxp2Ym3JCmVsKtXQA"
}
],
"responses": {
"200": {
"description": "Agent details successfully retrieved",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Agent"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/agents/create": {
"post": {
"tags": [
"Agents"
],
"summary": "Create a new agent and fund its wallet",
"description": "Creates a new agent, generates a wallet, and optionally funds the agent's wallet from the user's wallet. The operation includes: 1. Creation of a new agent record 2. Generation of a secure blockchain wallet 3. Faucet funding of the wallet (on supported test networks) 4. Optional transfer of funds from user's wallet\n",
"operationId": "createAgent",
"security": [
{
"ApiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"userid",
"name"
],
"properties": {
"userid": {
"type": "string",
"description": "ID of the user creating the agent",
"example": "user_piXARPaD2jefNBGxzb84Qd"
},
"walletaddress": {
"type": "string",
"description": "User's wallet address for funding (optional)",
"example": "0xa55B42bA7B639bB9CEc2dB2520aC8Cff588895f6"
},
"name": {
"type": "string",
"description": "Name of the agent",
"example": "Payment Assistant"
},
"description": {
"type": "string",
"description": "Purpose and functionality of the agent",
"example": "Handles payment processing for customer support"
},
"balance": {
"type": "integer",
"description": "Initial balance to fund the agent (in smallest units)",
"example": 6
},
"dailylimit": {
"type": "integer",
"description": "Maximum amount that can be spent per day",
"example": 1000
},
"transactionlimit": {
"type": "integer",
"description": "Maximum amount for a single transaction",
"example": 100
},
"currency": {
"type": "string",
"description": "Currency type to use (defaults to USDC)",
"default": "USDC",
"example": "USDC"
},
"requireapprovalforall": {
"type": "boolean",
"description": "Whether all transactions require approval",
"default": false,
"example": false
},
"requireapprovalaboveamount": {
"type": "integer",
"description": "Transactions above this amount require approval",
"example": 50
},
"tags": {
"type": "array",
"description": "Categories or labels to assign to the agent",
"items": {
"type": "string"
},
"example": [
"customer-support",
"payments"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Agent created and funded successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "agent_bRSEFnMRD1fvkMM39hzPdM"
},
"apikey": {
"type": "string",
"example": "mag_eJwVyN0OgiAYANA3cprT1qV_tY8E0jCVuyILSMtNG-LTt87l6SySt4NQVCGoVvCIggneZSASCOE1NpcE7ZzOopH_Q1c-12A4K4e8zgxnMJM0sjjxFE3xJmc4wDUsre4lGUpJzzDB0Mt7AiFmwiUaAppin1ijeCMN6M9C1mKD12ihTPiPwjkNZXQPme6DbGlNBc9aPfcCbb_dMRb2MbE-vqIKzdgtfgVGPxc"
},
"name": {
"type": "string",
"example": "Payment Assistant"
},
"description": {
"type": "string",
"example": "Handles payment processing for customer support"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"paused"
],
"example": "active"
},
"walletAddress": {
"type": "object",
"properties": {
"addressId": {
"type": "string",
"example": ""
},
"networkId": {
"type": "string",
"example": "base-sepolia"
},
"walletId": {
"type": "string",
"example": ""
}
}
},
"balance": {
"type": "string",
"example": "6"
},
"currency": {
"type": "string",
"example": "USDC"
},
"paymentRules": {
"type": "object",
"properties": {
"dailyLimit": {
"type": "integer",
"example": 1000
},
"transactionLimit": {
"type": "integer",
"example": 100
},
"requireApprovalAboveAmount": {
"type": "integer",
"example": 50
},
"requireApprovalForAll": {
"type": "boolean",
"example": false
}
}
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"customer-support",
"payments"
]
},
"created": {
"type": "string",
"format": "date-time",
"example": "2025-05-03T18:52:39.911685+00:00"
},
"transferResult": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"txHash": {
"type": "string",
"example": "0x123...abc"
},
"message": {
"type": "string",
"example": "Successfully transferred 6 USDC from user to agent wallet"
}
}
},
"faucetTransaction": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"txHash": {
"type": "string",
"example": "0xabc...123"
},
"message": {
"type": "string",
"example": "ETH testnet funds received via faucet"
}
}
}
}
}
}
}
},
"201": {
"description": "Agent created, but funding transfer failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "agent_bRSEFnMRD1fvkMM39hzPdM"
},
"warning": {
"type": "string",
"example": "Agent created successfully, but funding transfer failed. Please try funding the agent manually."
}
}
}
}
}
},
"400": {
"description": "Invalid request parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"missingName": {
"value": {
"error": "Agent name is required"
}
},
"invalidBalance": {
"value": {
"error": "Invalid balance amount"
}
}
}
}
}
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/agents/{id}": {
"get": {
"tags": [
"Agents"
],
"summary": "Fetch all agents for a user",
"description": "Returns an array of agents assigned to the user based on the provided user ID.",
"operationId": "getUserAgents",
"security": [
{
"ApiKeyAuth": []
}
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
},
"description": "User ID (can be a short ID like user_xxx)",
"example": "user_piXARPaD2jefNBGxzb84Qd"
}
],
"responses": {
"200": {
"description": "List of agents successfully retrieved",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Agent"
}
}
}
}
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/agents/deposit": {
"post": {
"tags": [
"Agents",
"Transactions"
],
"summary": "Deposit funds into an agent's wallet",
"description": "Transfers funds from the user's wallet to the specified agent's wallet. The operation includes: 1. Verification of user and agent existence 2. Validation of deposit amount 3. Transfer of funds on blockchain 4. Update of agent balance in database 5. Creation of transaction record\n",
"operationId": "depositToAgent",
"security": [
{
"ApiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"userid",
"agentid",
"amount"
],
"properties": {
"userid": {
"type": "string",
"description": "ID of the user initiating the deposit",
"example": "user_piXARPaD2jefNBGxzb84Qd"
},
"agentid": {
"type": "string",
"description": "ID of the agent receiving the deposit",
"example": "agent_k77NTwxp2Ym3JCmVsKtXQA"
},
"amount": {
"type": "number",
"description": "Amount to deposit",
"example": 50
},
"currency": {
"type": "string",
"description": "Currency type to deposit (defaults to USDC)",
"default": "USDC",
"example": "USDC"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Funds deposited successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"txHash": {
"type": "string",
"example": "0x123...abc"
},
"message": {
"type": "string",
"example": "Successfully deposited 50 USDC to agent"
},
"updatedBalance": {
"type": "string",
"example": "150"
}
}
}
}
}
},
"400": {
"description": "Invalid request parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"missingParams": {
"value": {
"error": "userid, agentid, and amount are required."
}
},
"invalidAmount": {
"value": {
"error": "Invalid deposit amount"
}
},
"walletNotFound": {
"value": {
"error": "User wallet not found or inaccessible"
}
}
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"description": "Transaction failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error": {
"type": "string",
"example": "Transfer failed on-chain: insufficient funds"
}
}
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/agents/withdraw": {
"post": {
"tags": [
"Agents",
"Transactions"
],
"summary": "Withdraw funds from an agent's wallet",
"description": "Transfers funds from the agent's wallet to the user's wallet. The operation includes: 1. Verification of user and agent existence 2. Validation of withdrawal amount against available balance 3. Transfer of funds on blockchain 4. Update of agent balance in database 5. Creation of transaction record\n",
"operationId": "withdrawFromAgent",
"security": [
{
"ApiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"userid",
"agentid",
"amount"
],
"properties": {
"userid": {
"type": "string",
"description": "ID of the user receiving the withdrawal",
"example": "user_piXARPaD2jefNBGxzb84Qd"
},
"agentid": {
"type": "string",
"description": "ID of the agent sending the funds",
"example": "agent_k77NTwxp2Ym3JCmVsKtXQA"
},
"amount": {
"type": "number",
"description": "Amount to withdraw",
"example": 50
},
"currency": {
"type": "string",
"description": "Currency type to withdraw (defaults to USDC)",
"default": "USDC",
"example": "USDC"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Funds withdrawn successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"txHash": {
"type": "string",
"example": "0x123...abc"
},
"message": {
"type": "string",
"example": "Successfully withdrew 50 USDC from agent to user"
},
"updatedBalance": {
"type": "string",
"example": "50"
}
}
}
}
}
},
"400": {
"description": "Invalid request parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"missingParams": {
"value": {
"error": "userid, agentid, and amount are required."
}
},
"invalidAmount": {
"value": {
"error": "Invalid withdraw amount"
}
},
"insufficientBalance": {
"value": {
"error": "Insufficient balance"
}
}
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"description": "Transaction failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error": {
"type": "string",
"example": "Transfer failed on-chain"
}
}
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/investment/interest-rate": {
"get": {
"tags": [
"Investment"
],
"summary": "Get the current interest rate",
"description": "Retrieves the current annual interest rate for investments and the timestamp when it was last updated. This rate is used for all savings calculations in the platform.\n",
"operationId": "getCurrentInterestRate",
"security": [
{
"ApiKeyAuth": []
}
],
"responses": {
"200": {
"description": "Interest rate retrieved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InterestRate"
}
}
}
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/investment/calculator": {
"post": {
"tags": [
"Investment"
],
"summary": "Calculate potential interest",
"description": "Calculates the potential interest earned for a given investment amount and period. Uses the platform's current interest rate by default, but allows specifying a custom rate for scenario planning. Returns detailed breakdown of the calculation with step-by-step formula application.\n",
"operationId": "calculateInterest",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"amount",
"days"
],
"properties": {
"amount": {
"type": "number",
"description": "Principal amount to invest",
"example": 1000
},
"days": {
"type": "number",
"description": "Investment duration in days",
"example": 365
},
"customRate": {
"type": "number",
"description": "Optional custom interest rate (annual percentage)",
"example": 4.5
}
}
}
}
}
},
"responses": {
"200": {
"description": "Interest calculation completed successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InterestCalculation"
}
}
}
},
"400": {
"description": "Invalid request parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"missingParams": {
"value": {
"success": false,
"error": "Amount and days are required"
}
},
"invalidAmount": {
"value": {
"success": false,
"error": "Amount must be a positive number"
}
},
"invalidDays": {
"value": {
"success": false,
"error": "Days must be a positive number"
}
}
}
}
}
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/payments/setApprove": {
"post": {
"tags": [
"Payments"
],
"summary": "Approve a payment",
"description": "Updates the approval status of a payment to \"Approved\" and sets the approval timestamp. This allows the payment to proceed to the next stage in the payment flow.\n",
"operationId": "approvePayment",
"security": [
{
"ApiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"paymentId"
],
"properties": {
"paymentId": {
"type": "string",
"description": "The short ID of the payment to approve",
"example": "payee_c7m5fdJAfaV3R7VVpWk2MT"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Payment approved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Approval Status Done."
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/user/payments": {
"get": {
"tags": [
"Payments",
"Users"
],
"summary": "Get all payments related to the authenticated user's agents",
"description": "Retrieves a list of payments where either the sender or receiver is one of the authenticated user's agents. Payments are enhanced with additional information: 1. Agent names for both sender and receiver 2. Direction (incoming/outgoing) relative to the user's agents 3. Payment status and creation timestamp\nResults can be optionally filtered by approval status.\n",
"operationId": "getUserPayments",
"security": [
{
"ApiKeyAuth": []
}
],
"parameters": [
{
"in": "query",
"name": "approvalStatus",
"schema": {
"type": "string"
},
"required": false,
"description": "Filter payments by approval status",
"example": "Approved, Declined, Pending, Waiting, Waiting for Sender Approva"
}
],
"responses": {
"200": {
"description": "List of payments retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PaymentWithDirection"
}
},
"examples": {
"outgoing": {
"summary": "Outgoing payment example",
"value": [
{
"id": "payee_8tJo7vZb1RKo4oeyWuqgK",
"senderagentid": "agent_8tJo7vZb1RKo4oeyWuqgK",
"receiveragentid": "agent_7tJo7vZb1RKo4oeyWuqgK",
"initiatedBy": "Alice",
"receivedBy": "Bob",
"direction": "outgoing",
"name": "Payment from Alice to Bob",
"approvalstatus": "Approved",
"createdat": "2025-04-07T12:00:00Z",
"type": "EXTERNAL",
"paymentdetails": {
"method": "CRYPTO_ADDRESS",
"amount": 100,
"currency": "USDC"
}
}
]
},
"incoming": {
"summary": "Incoming payment example",
"value": [
{
"id": "payee_9tJo7vZb1RKo4oeyWuqgK",
"senderagentid": "agent_7tJo7vZb1RKo4oeyWuqgK",
"receiveragentid": "agent_8tJo7vZb1RKo4oeyWuqgK",
"initiatedBy": "Bob",
"receivedBy": "Alice",
"direction": "incoming",
"name": "Payment from Bob to Alice",
"approvalstatus": "Waiting",
"createdat": "2025-04-08T10:00:00Z",
"type": "EXTERNAL",
"paymentdetails": {
"method": "CRYPTO_ADDRESS",
"amount": 50,
"currency": "USDC"
}
}
]
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/payments/{id}": {
"get": {
"tags": [
"Payments"
],
"summary": "Fetch details of a specific payment",
"description": "Retrieves detailed information about a specific payment based on its ID. Converts short ID format to UUID format internally before querying the database.\n",
"operationId": "getPaymentById",
"security": [
{
"ApiKeyAuth": []
}
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
},
"description": "Payment ID (can be a short ID like payee_xxx)",
"example": "payee_8tJo7vZb1RKo4oeyWuqgK"
}
],
"responses": {
"200": {
"description": "Payment details retrieved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Payment"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/payments/setDecline": {
"post": {
"tags": [
"Payments"
],
"summary": "Decline a payment",
"description": "Updates the approval status of a payment to \"Decline\" and sets its status to \"Confirmed\". This effectively rejects the payment and prevents it from being processed. The operation also records the timestamp when the payment was declined.\n",
"operationId": "declinePayment",
"security": [
{
"ApiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"paymentId"
],
"properties": {
"paymentId": {
"type": "string",
"description": "The short ID of the payment to decline",
"example": "payee_c7m5fdJAfaV3R7VVpWk2MT"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Payment declined successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Payment declined successfully"
},
"status": {
"type": "string",
"example": "Decline"
},
"txHash": {
"type": "string",
"nullable": true,
"example": null
}
}
}
}
}
},
"400": {
"description": "Invalid request parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"missingId": {
"value": {
"error": "Payment ID is required"
}
}
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/payments/export": {
"post": {
"tags": [
"Payments"
],
"summary": "Export payments data in various formats",
"description": "Exports payment data in CSV, XLSX, or PDF format based on the specified date range",
"security": [
{
"ApiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"format"
],
"properties": {
"format": {
"type": "string",
"enum": [
"csv",
"xlsx",
"pdf"
],
"description": "Export format"
},
"dateRange": {
"type": "object",
"properties": {
"start": {
"type": "string",
"format": "date"
},
"end": {
"type": "string",
"format": "date"
}
}
}
}
}
}
}
}
}
},
"/savings/deposit": {
"post": {
"tags": [
"Savings"
],
"summary": "Deposit savings into an agent's account",
"description": "Creates a new investment by depositing funds into an agent's savings account. The operation converts the agent ID to UUID format if provided in short format, validates the deposit amount, and creates a new investment record.\n",
"operationId": "depositSavings",
"security": [
{
"ApiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"agentId",
"amount"
],
"properties": {
"agentId": {
"type": "string",
"description": "The short ID or UUID of the agent",
"example": "agent_k77NTwxp2Ym3JCmVsKtXQA"
},
"amount": {
"type": "number",
"description": "Amount to deposit (must be positive)",
"example": 100.5
}
}
}
}
}
},
"responses": {
"200": {
"description": "Deposit completed successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Successfully invested 0.5 USDC."
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/savings/withdraw": {
"post": {
"tags": [
"Savings"
],
"summary": "Withdraw savings from an investment",
"description": "Closes an active investment and returns funds to the user's account. The operation validates the investment ID, converts it to UUID format if needed, and processes the withdrawal by updating the investment status.\n",
"operationId": "withdrawSavings",
"security": [
{
"ApiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"investmentId"
],
"properties": {
"investmentId": {
"type": "string",
"description": "The short ID or UUID of the investment",
"example": "inv_k77NTwxp2Ym3JCmVsKtXQA"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Withdrawal completed successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Withdrawal completed successfully."
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/savings/myinvestments": {
"get": {
"tags": [
"Savings"
],
"summary": "Get all active investments for the authenticated user",
"description": "Retrieves a list of all active investments made by the authenticated user. The response includes details about agents associated with investments, the invested amount, current value (with interest), and investment duration. Interest calculations are based on the central wallet's current interest rate.\n",
"operationId": "getUserInvestments",
"security": [
{
"ApiKeyAuth": []
}
],
"responses": {
"200": {
"description": "List of active investments retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"agents": {
"type": "array",
"description": "List of agents with active investments",
"items": {
"type": "object",
"properties": {
"agent": {
"type": "string",
"description": "Name of the agent",
"example": "Payment Assistant"
},
"totalBalance": {
"type": "number",
"description": "Total balance including investment value",
"example": 1200.5
},
"investedAmount": {
"type": "number",
"description": "Principal amount invested",
"example": 1000
},
"currentValue": {
"type": "number",
"description": "Current value with interest",
"example": 1200.5
},
"interest": {
"type": "number",
"description": "Interest earned to date",
"example": 200.5
},
"current": {
"type": "number",
"description": "Current balance in agent's account",
"example": 1000
},
"daysInvested": {
"type": "number",
"description": "Days the investment has been active",
"example": 365
}
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/savings/dashboard": {
"get": {
"tags": [
"Savings"
],
"summary": "Get savings dashboard data",
"description": "Provides a comprehensive overview of the user's savings portfolio. Includes total savings, current interest rate, total invested amount, one-year projection, and detailed information about investments by agent. Calculates real-time investment values based on the current interest rate and the exact duration of each investment.\n",
"operationId": "getSavingsDashboard",
"security": [
{
"ApiKeyAuth": []
}
],
"responses": {
"200": {
"description": "Savings dashboard data retrieved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SavingsDashboard"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/savings/{agentId}": {
"get": {
"tags": [
"Savings"
],
"summary": "Get all investments for a specific agent",
"description": "Retrieves all investments (both active and completed) associated with a specific agent. For active investments, calculates the current value and interest earned based on the principal amount, interest rate, and investment duration. Returns detailed information including investment status and creation timestamp.\n",
"operationId": "getAgentInvestments",
"security": [
{
"ApiKeyAuth": []
}
],
"parameters": [
{
"in": "path",
"name": "agentId",
"required": true,
"schema": {
"type": "string"
},
"description": "The short ID or UUID of the agent",
"example": "agent_k77NTwxp2Ym3JCmVsKtXQA"
}
],
"responses": {
"200": {
"description": "List of investments retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"investments": {
"type": "array",
"description": "List of investments for the specified agent",
"items": {
"$ref": "#/components/schemas/Savings"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/transactions/summary": {
"get": {
"tags": [
"Transactions"
],
"summary": "Get wallet summary for a date range",
"description": "Provides a summary of financial activity within the specified date range, including total amounts earned (deposits, interest) and spent (withdrawals, payments).\n",
"operationId": "getTransactionSummary",
"security": [
{
"ApiKeyAuth": []
}
],
"parameters": [
{
"in": "query",
"name": "start_date",
"schema": {
"type": "string",
"format": "date-time"
},
"required": true,
"description": "Start date for summary calculation (ISO format)",
"example": "2023-05-01T00:00:00Z"
},
{
"in": "query",
"name": "end_date",
"schema": {
"type": "string",
"format": "date-time"
},
"required": true,
"description": "End date for summary calculation (ISO format)",
"example": "2023-05-31T23:59:59Z"
}
],
"responses": {
"200": {
"description": "Summary data retrieved successfully"
},
"400": {
"description": "Invalid request parameters"
},
"401": {
"description": "User not authenticated"
},
"500": {
"description": "Internal server error"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/user/wallet-balance": {
"get": {
"tags": [
"Users",
"Wallets"
],
"summary": "Get the authenticated user's wallet balance",
"description": "Retrieves the user's wallet balance from the blockchain using their wallet address. The endpoint follows a fallback strategy, first attempting to fetch USDC balance, then ETH, and finally any other non-zero balance. Requires authentication with a valid API key.\n",
"operationId": "getUserWalletBalance",
"security": [
{
"ApiKeyAuth": []
}
],
"responses": {
"200": {
"description": "Wallet balance retrieved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WalletBalance"
},
"examples": {
"usdcBalance": {
"value": {
"success": true,
"balance": "100.50",
"asset": "USDC"
}
},
"ethBalance": {
"value": {
"success": true,
"balance": "0.05",
"asset": "ETH"
}
},
"zeroBalance": {
"value": {
"success": true,
"balance": "0.00",
"message": "All balance fetching methods failed"
}
}
}
}
}
},
"400": {
"description": "Invalid wallet address format",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": "Invalid wallet address format"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
}
}
}
================================================
FILE: api-reference/agents/create-agent.mdx
================================================
---
title: 'Create Agent'
api: 'POST /agents/create'
description: 'Create a new agent and fund its wallet'
---
**Multi-step Process**: This endpoint creates a new agent, generates a blockchain wallet, and can fund the wallet from your user account or via a testnet faucet.
## Request Headers
Your API key for authentication
## Request Body
ID of the user creating the agent
User's wallet address for funding (optional)
Name of the agent
Purpose and functionality of the agent
Initial balance to fund the agent (in smallest units)
Maximum amount that can be spent per day
Maximum amount for a single transaction
Currency type to use (defaults to USDC)
Whether all transactions require approval
Transactions above this amount require approval
Categories or labels to assign to the agent
## Response
Unique agent identifier
The API key for the agent
Name of the agent
Purpose and functionality of the agent
Current status of the agent (active, inactive, paused)
ID of the wallet address
Blockchain network ID
ID of the wallet
Current balance of the agent
Currency type used
Maximum amount that can be spent per day
Maximum amount for a single transaction
Transactions above this amount require approval
Whether all transactions require approval
Categories or labels assigned to the agent
Timestamp when the agent was created
Whether the transfer was successful
Transaction hash of the transfer
Description of the transfer result
Whether the faucet transaction was successful
Transaction hash of the faucet transaction
Description of the faucet transaction result
```json 200
{
"id": "agent_bRSEFnMRD1fvkMM39hzPdM",
"apikey": "mag_eJwVyN0OgiAYANA3cprT1qV_tY8E0jCVuyILSMtNG-LTt87l6SySt4NQVCGoVvCIggneZSASCOE1NpcE7ZzOopH_Q1c-12A4K4e8zgxnMJM0sjjxFE3xJmc4wDUsre4lGUpJzzDB0Mt7AiFmwiUaAppin1ijeCMN6M9C1mKD12ihTPiPwjkNZXQPme6DbGlNBc9aPfcCbb_dMRb2MbE-vqIKzdgtfgVGPxc",
"name": "Payment Assistant",
"description": "Handles payment processing for customer support",
"status": "active",
"walletAddress": {
"addressId": "",
"networkId": "base-sepolia",
"walletId": ""
},
"balance": "6",
"currency": "USDC",
"paymentRules": {
"dailyLimit": 1000,
"transactionLimit": 100,
"requireApprovalAboveAmount": 50,
"requireApprovalForAll": false
},
"tags": [
"customer-support",
"payments"
],
"created": "2025-05-03T18:52:39.911685+00:00",
"transferResult": {
"success": true,
"txHash": "0x123...abc",
"message": "Successfully transferred 6 USDC from user to agent wallet"
},
"faucetTransaction": {
"success": true,
"txHash": "0xabc...123",
"message": "ETH testnet funds received via faucet"
}
}
```
```json 201
{
"id": "agent_bRSEFnMRD1fvkMM39hzPdM",
"warning": "Agent created successfully, but funding transfer failed. Please try funding the agent manually."
}
```
```json 400
{
"error": "Agent name is required"
}
```
```json 404
{
"error": "User not found"
}
```
```json 500
{
"error": "Internal server error"
}
```
## Status Codes
| Status Code | Description |
|-------------|-------------|
| 200 | Agent created and funded successfully |
| 201 | Agent created, but funding transfer failed |
| 400 | Bad Request - Invalid or missing parameters |
| 404 | Not Found - User ID not found |
| 500 | Internal Server Error |
**Important**: Store the returned API key securely as it will be needed for all future operations with this agent.
================================================
FILE: api-reference/agents/deposit.mdx
================================================
---
title: 'Deposit to Agent'
api: 'POST /agents/deposit'
description: "Deposit funds into an agent's wallet"
---
**Blockchain Transaction**: This endpoint transfers funds from a user's wallet to an agent's wallet through an on-chain transaction.
## Request Headers
Your API key for authentication
## Request Body
ID of the user initiating the deposit
ID of the agent receiving the deposit
Amount to deposit
Currency type to deposit (defaults to USDC)
## Response
Whether the deposit was successful
Transaction hash on the blockchain
Information about the deposit
New balance of the agent after the deposit
```json 200
{
"success": true,
"txHash": "0x123...abc",
"message": "Successfully deposited 50 USDC to agent",
"updatedBalance": "150"
}
```
```json 400
{
"error": "userid, agentid, and amount are required."
}
```
```json 400
{
"error": "Invalid deposit amount"
}
```
```json 400
{
"error": "User wallet not found or inaccessible"
}
```
```json 404
{
"error": "Agent not found"
}
```
```json 500
{
"success": false,
"error": "Transfer failed on-chain: insufficient funds"
}
```
## Status Codes
| Status Code | Description |
|-------------|-------------|
| 200 | Funds deposited successfully |
| 400 | Bad Request - Invalid or missing parameters |
| 404 | Not Found - Agent or user not found |
| 500 | Internal Server Error - Transaction failed |
**Wallet Requirements**: The user must have sufficient funds in their wallet and the wallet must be accessible for the deposit to succeed.
**Transaction Time**: Blockchain transactions may take a few moments to be confirmed. The response is sent after confirmation.
================================================
FILE: api-reference/agents/get-agent.mdx
================================================
---
title: 'Get Agent'
api: 'GET /agentsWith/{id}'
description: 'Fetch details of a specific agent'
---
**Quick Lookup**: Retrieve comprehensive details about an agent using its unique ID.
## Path Parameters
Agent ID (can be a short ID like agent_xxx)
## Request Headers
Your API key for authentication
## Response
Unique agent identifier
Name of the agent
Purpose and functionality of the agent
Current status of the agent (active, inactive, paused)
Blockchain wallet address
Blockchain network ID
Current balance of the agent
Currency type used
Maximum amount that can be spent per day
Maximum amount for a single transaction
Transactions above this amount require approval
Categories or labels assigned to the agent
Timestamp when the agent was created
```json 200
{
"id": "agent_k77NTwxp2Ym3JCmVsKtXQA",
"name": "Payment Assistant",
"description": "Handles payment processing for customer support",
"status": "active",
"walletAddress": {
"addressId": "0x9d20dE668c8F9fb431cf6D6BBA48ee60Fe8E2BAB",
"networkId": "base-sepolia"
},
"balance": "100",
"currency": "USDC",
"paymentRules": {
"dailyLimit": 1000,
"transactionLimit": 100,
"requireApprovalAboveAmount": 50
},
"tags": ["customer-support", "payments"],
"created": "2025-04-15T11:00:08Z"
}
```
```json 404
{
"error": "Agent not found"
}
```
```json 500
{
"error": "Internal server error"
}
```
## Status Codes
| Status Code | Description |
|-------------|-------------|
| 200 | Agent details successfully retrieved |
| 404 | Not Found - Agent ID doesn't exist |
| 500 | Internal Server Error |
**Balance Format**: Balance is returned as a string to preserve precision for financial calculations.
================================================
FILE: api-reference/agents/get-user-agents.mdx
================================================
---
title: 'List User Agents'
api: 'GET /agents/{id}'
description: 'Fetch all agents for a user'
---
**User Agents**: Returns an array of agents assigned to the user based on the provided user ID.
## Path Parameters
User ID in the format `user_xxx`
## Request Headers
Your API key for authentication
## Response
Returns an array of agent objects, each containing:
Unique agent identifier
Name of the agent
Purpose and functionality of the agent
Current status of the agent (active, inactive, paused)
Blockchain wallet address
Blockchain network ID
Current balance of the agent
Currency type used
Maximum amount that can be spent per day
Maximum amount for a single transaction
Transactions above this amount require approval
Categories or labels assigned to the agent
Timestamp when the agent was created
```json 200
[
{
"id": "agent_k77NTwxp2Ym3JCmVsKtXQA",
"name": "Payment Assistant",
"description": "Handles payment processing for customer support",
"status": "active",
"walletAddress": {
"addressId": "0x9d20dE668c8F9fb431cf6D6BBA48ee60Fe8E2BAB",
"networkId": "base-sepolia"
},
"balance": "100",
"currency": "USDC",
"paymentRules": {
"dailyLimit": 1000,
"transactionLimit": 100,
"requireApprovalAboveAmount": 50
},
"tags": ["customer-support", "payments"],
"created": "2025-04-15T11:00:08Z"
},
{
"id": "agent_bRSEFnMRD1fvkMM39hzPdM",
"name": "Marketing Budget",
"description": "Manages marketing expenses",
"status": "active",
"walletAddress": {
"addressId": "0x8c30dE668c8F9fb431cf6D6BBA48ee60Fe8E1CAB",
"networkId": "base-sepolia"
},
"balance": "500",
"currency": "USDC",
"paymentRules": {
"dailyLimit": 2000,
"transactionLimit": 200
},
"tags": ["marketing", "subscriptions"]
}
]
```
```json 500
{
"error": "Internal server error"
}
```
## Status Codes
| Status Code | Description |
|-------------|-------------|
| 200 | List of agents successfully retrieved (may be empty) |
| 500 | Internal Server Error |
**Empty Response**: If the user has no agents, an empty array will be returned with a 200 status code.
================================================
FILE: api-reference/agents/introduction.mdx
================================================
---
title: 'Introduction'
description: 'Create and manage AI financial agents'
---
# Agents API
**Core Feature**: Agents are autonomous financial entities with their own wallets, balances, and transaction rules.
Each agent has its own blockchain wallet, balance, and configurable payment rules. Use the Agents API to create, fund, and manage your AI financial agents.
In sandbox mode only agent-to-agent transactions are currently supported. Agent-to-bank account, agent-to-businesses, and agent-to-checkout pages are coming soon.
## Agent Model
**Complete Control**: Configure transaction limits, approval requirements, and other rules to precisely control how your agents handle funds.
An agent consists of:
- **Identity**: Unique ID, name, and description
- **Financial Details**: Associated wallet address and balance
- **Payment Rules**: Transaction limits and approval requirements
- **Status**: Current operational status (active, inactive, paused)
- **Metadata**: Tags, creation timestamp, and other attributes
## Agent Structure
```json
{
"id": "agent_k77NTwxp2Ym3JCmVsKtXQA",
"name": "Payment Assistant",
"description": "Handles payment processing for customer support",
"status": "active",
"walletAddress": {
"addressId": "0x9d20dE668c8F9fb431cf6D6BBA48ee60Fe8E2BAB",
"networkId": "base-sepolia",
"walletId": "07f490dc-34e3-447f-9972-df2778fcb3c3"
},
"balance": "100",
"currency": "USDC",
"paymentRules": {
"dailyLimit": 1000,
"transactionLimit": 100,
"requireApprovalForAll": false,
"requireApprovalAboveAmount": 50.00
},
"tags": [
"customer-support",
"payments"
],
"createdat": "2025-04-15T11:00:08.432269+00:00"
}
```
## Available Endpoints
Fetch details of a specific agent
Create a new agent and fund its wallet
Fetch all agents for a user
Deposit funds into an agent's wallet
Withdraw funds from an agent's wallet
## Agent Lifecycle
The typical lifecycle of an agent includes:
1. **Creation**: An agent is created with a name, description, and initial funding
2. **Configuration**: Payment rules are set to control transaction limits and approval requirements
3. **Active Operation**: The agent processes transactions according to its configured rules
4. **Maintenance**: Funds can be added or withdrawn as needed
5. **Status Changes**: An agent's status can be modified as needed
## Payment Rules
**Safety First**: Configure rules to prevent unauthorized spending and ensure financial operations stay within your defined parameters.
Payment rules determine how an agent can spend funds:
- **Daily Limit**: Maximum amount the agent can spend in a 24-hour period
- **Transaction Limit**: Maximum amount for a single transaction
- **Approval Requirements**:
- `requireApprovalForAll`: When true, all transactions require manual approval
- `requireApprovalAboveAmount`: Transactions above this amount require approval
## Best Practices
- Create separate agents for different purposes or departments
- Use descriptive names and tags to easily identify agents
- Set appropriate transaction limits based on expected usage patterns
- Consider requiring approval for large transactions to prevent unauthorized spending
- Regularly monitor agent activity to ensure proper operation
**Blockchain Integration**: All agent wallets are real blockchain wallets, with transactions recorded on-chain for maximum transparency and security.
================================================
FILE: api-reference/agents/withdraw.mdx
================================================
---
title: 'Withdraw from Agent'
api: 'POST /agents/withdraw'
description: "Withdraw funds from an agent's wallet"
---
**Withdrawal Process**: Transfers funds from the agent's wallet to the user's wallet. The operation includes: 1. Verification of user and agent existence 2. Validation of withdrawal amount against available balance 3. Transfer of funds on blockchain 4. Update of agent balance in database 5. Creation of transaction record
## Request Headers
Your API key for authentication
## Request Body
ID of the user receiving the withdrawal
ID of the agent sending the funds
Amount to withdraw
Currency type to withdraw (defaults to USDC)
## Response
Whether the withdrawal was successful
Transaction hash on the blockchain
Information about the withdrawal
New balance of the agent after the withdrawal
```json 200
{
"success": true,
"txHash": "0x123...abc",
"message": "Successfully withdrew 50 USDC from agent to user",
"updatedBalance": "50"
}
```
```json 400
{
"error": "userid, agentid, and amount are required."
}
```
```json 400
{
"error": "Invalid withdraw amount"
}
```
```json 400
{
"error": "Insufficient balance"
}
```
```json 404
{
"error": "Agent not found"
}
```
```json 500
{
"success": false,
"error": "Transfer failed on-chain"
}
```
## Status Codes
| Status Code | Description |
|-------------|-------------|
| 200 | Funds withdrawn successfully |
| 400 | Invalid request parameters |
| 404 | Not Found |
| 500 | Transaction failed |
**Balance Requirement**: The agent must have sufficient balance to complete the withdrawal. The transaction will fail if the requested amount exceeds the available balance.
**Blockchain Transaction**: This operation creates an on-chain transaction which may take a few moments to be confirmed depending on network conditions.
================================================
FILE: api-reference/payments/approve-payment.mdx
================================================
---
title: 'Approve Payment'
api: 'POST /payments/setApprove'
description: 'Approve a payment that requires authorization'
---
**Authorization Step**: Approve payments that are waiting for authorization to proceed with blockchain fund transfer.
## Request Headers
Your API key for authentication
## Request Body
The short ID of the payment to approve
## Response
Confirmation message indicating the approval status has been updated
```json 200
{
"message": "Approval Status Done."
}
```
```json 400
{
"error": "Payment ID is required"
}
```
```json 404
{
"error": "Payment not found"
}
```
```json 500
{
"error": "Internal server error"
}
```
## Status Codes
| Status Code | Description |
|-------------|-------------|
| 200 | Payment approved successfully |
| 400 | Bad Request - Missing payment ID |
| 404 | Not Found - Payment not found |
| 500 | Internal Server Error |
**Status Transition**: Only payments with an approval status of "Waiting for Sender Approval" can be approved.
**Post-Approval Process**: Once approved, the payment will be processed on the blockchain and its status will change to "New", then to "Confirmed" once processed.
================================================
FILE: api-reference/payments/decline-payment.mdx
================================================
---
title: 'Decline Payment'
api: 'POST /payments/setDecline'
description: 'Decline a payment to prevent processing'
---
**Rejection Action**: Cancel pending payments by declining them, which prevents any funds from being transferred.
## Request Headers
Your API key for authentication
## Request Body
The short ID of the payment to decline
## Response
Confirmation message indicating the payment was declined
The new approval status ("Decline")
Transaction hash (will be null for declined payments)
```json 200
{
"message": "Payment declined successfully",
"status": "Decline",
"txHash": null
}
```
```json 400
{
"error": "Payment ID is required"
}
```
```json 404
{
"error": "Payment not found"
}
```json 500
{
"error": "Internal Server Error"
}
```
## Status Codes
| Status Code | Description |
|-------------|-------------|
| 200 | Payment declined successfully |
| 400 | Bad Request - Missing payment ID |
| 404 | Not Found - Payment not found |
| 500 | Internal Server Error |
**Final Action**: Declined payments cannot be later approved. A new payment must be created if necessary.
**Status Change**: The payment's status will be updated to "Confirmed" with an approval status of "Decline".
================================================
FILE: api-reference/payments/export-payments.mdx
================================================
---
title: 'Export Payments'
api: 'POST /payments/export'
description: 'Export payments data in various formats (CSV, XLSX, PDF)'
---
**Data Export**: Generate payment reports in your preferred format for accounting, record-keeping, and analysis.
## Request Headers
Your API key for authentication
## Request Body
Export format
"csv", "xlsx", "pdf"
Start date for filtering payments
End date for filtering payments
## Response
The response is a file download in the requested format containing payment data.
```json 400
{
"error": "Invalid export format. Supported formats are: csv, xlsx, pdf"
}
```
```json 400
{
"error": "Invalid date range format"
}
```
```json 401
{
"error": "Invalid or missing API key"
}
```
```json 500
{
"error": "Internal server error"
}
```
## Status Codes
| Status Code | Description |
|-------------|-------------|
| 200 | Export completed successfully, file is returned |
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Authentication failed |
| 500 | Internal Server Error |
**Format Benefits**:
- **CSV**: Simple format compatible with most spreadsheet applications
- **XLSX**: Excel format with rich formatting and multiple sheets
- **PDF**: Formatted document suitable for sharing and printing
**Size Limit**: The maximum export size is 10,000 payments. For larger datasets, use multiple date range requests.
================================================
FILE: api-reference/payments/get-payment.mdx
================================================
---
title: 'Get Payment'
api: 'GET /payments/{id}'
description: 'Fetch details of a specific payment'
---
**Payment Details**: Retrieves detailed information about a specific payment based on its ID. Converts short ID format to UUID format internally before querying the database.
## Path Parameters
Payment ID (can be a short ID like payee_xxx)
## Request Headers
Your API key for authentication
## Response
Unique payment identifier
Name or description of the payment
Type of payment (EXTERNAL or INTERNAL)
ID of the agent sending the payment
ID of the agent receiving the payment
Current status of the payment
Approval status of the payment
Whether this payment requires approval
Payment method used
Payment amount
Payment currency
Contact email for the payment recipient
Contact phone number for the payment recipient
Tags or categories for the payment
Timestamp when the payment was created
Timestamp when the payment was approved
```json 200
{
"id": "payee_wDG5cavUCoK53uvFzTvkey",
"name": "Vendor XYZ Payment",
"type": "EXTERNAL",
"senderagentid": "agent_eC6ZezevNsqxvoKmQrUuoU",
"receiveragentid": "agent_k77NTwxp2Ym3JCmVsKtXQA",
"status": "New",
"approvalstatus": "Waiting for Sender Approval",
"approvalrequired": true,
"contactdetails": {
"email": "contact@vendorxyz.com",
"phoneNumber": "+1234567890"
},
"paymentdetails": {
"method": "CRYPTO_ADDRESS",
"amount": 6,
"currency": "USDC"
},
"tags": ["vendor", "regular"],
"createdat": "2025-04-17T10:28:18Z",
"approvedat": null
}
```
```json 404
{
"error": "Payment not found"
}
```
```json 500
{
"error": "Internal server error"
}
```
## Status Codes
| Status Code | Description |
|-------------|-------------|
| 200 | Payment details retrieved successfully |
| 404 | Not Found - Payment not found |
| 500 | Internal Server Error |
**Payment Types**: Use "EXTERNAL" for payments to recipients outside your agent network and "INTERNAL" for payments between your own agents.
**Approval Flow**: The `approvedat` field will be null if the payment has not yet been approved or declined.
================================================
FILE: api-reference/payments/get-user-payments.mdx
================================================
---
title: 'List User Payments'
api: 'GET /user/payments'
description: "Get all payments related to the authenticated user's agents"
---
**Payment History**: View all incoming and outgoing payments associated with your agents, with optional filtering by approval status.
## Request Headers
Your API key for authentication
## Query Parameters
Filter payments by approval status (Approved, Declined, Pending, Waiting)
## Response
Returns an array of payment objects, each containing:
Unique payment identifier
ID of the agent sending the payment
ID of the agent receiving the payment
Name of the agent that initiated the payment
Name of the agent that received the payment
Direction of the payment relative to the user's agents (incoming, outgoing)
Name or description of the payment
Approval status of the payment
Timestamp when the payment was created
Type of payment (EXTERNAL or INTERNAL)
Payment method used
Payment amount
Payment currency
```json 200
[
{
"id": "payee_8tJo7vZb1RKo4oeyWuqgK",
"senderagentid": "agent_8tJo7vZb1RKo4oeyWuqgK",
"receiveragentid": "agent_7tJo7vZb1RKo4oeyWuqgK",
"initiatedBy": "Alice",
"receivedBy": "Bob",
"direction": "outgoing",
"name": "Payment from Alice to Bob",
"approvalstatus": "Approved",
"createdat": "2025-04-07T12:00:00Z",
"type": "EXTERNAL",
"paymentdetails": {
"method": "CRYPTO_ADDRESS",
"amount": 100,
"currency": "USDC"
}
},
{
"id": "payee_9tJo7vZb1RKo4oeyWuqgK",
"senderagentid": "agent_7tJo7vZb1RKo4oeyWuqgK",
"receiveragentid": "agent_8tJo7vZb1RKo4oeyWuqgK",
"initiatedBy": "Bob",
"receivedBy": "Alice",
"direction": "incoming",
"name": "Payment from Bob to Alice",
"approvalstatus": "Waiting",
"createdat": "2025-04-08T10:00:00Z",
"type": "EXTERNAL",
"paymentdetails": {
"method": "CRYPTO_ADDRESS",
"amount": 50,
"currency": "USDC"
}
}
]
```
```json 401
{
"error": "Unauthorized"
}
```
```json 500
{
"error": "Internal server error"
}
```
## Status Codes
| Status Code | Description |
|-------------|-------------|
| 200 | List of payments retrieved successfully |
| 401 | Unauthorized |
| 500 | Internal Error |
**Approval Status Values**: Possible values for approvalStatus filter include: "Approved", "Declined", "Pending", "Waiting", "Waiting for Sender Approval"
**Direction**: The "direction" field makes it easy to identify whether a payment is incoming to your agent (received) or outgoing from your agent (sent).
================================================
FILE: api-reference/payments/introduction.mdx
================================================
---
title: 'Introduction'
description: 'Process and manage payments between agents and external accounts'
---
# Payments API
**Financial Transactions**: The Payments API provides a complete system for creating, approving, and tracking payments between agents on the blockchain.
Process and manage financial transactions between agents with automatic approval workflows and detailed tracking. Use these endpoints to initiate, approve/decline, and analyze payments within the Mage ecosystem.
In sandbox mode only agent-to-agent transactions are currently supported. Agent-to-bank account, agent-to-businesses, and agent-to-checkout pages are coming soon.
## Payment Model
**Approval Flow**: Payments respect each agent's configured rules, with transactions above certain thresholds requiring explicit approval before execution.
Each payment in the Mage system includes:
- **Identifiers**: Unique ID, name, and type
- **Participants**: Sender and receiver agent IDs
- **Status**: Current processing and approval status
- **Financial Details**: Amount, currency, and payment method
- **Metadata**: Timestamps, tags, and contact information
Different approval statuses determine how payments are processed:
- Payments requiring approval remain in "Waiting for Sender Approval" until authorized
- Upon approval, payments move to blockchain processing
- Declined payments are marked as "Confirmed" with a "Decline" approval status
## Payment Structure
```json
{
"id": "payee_wDG5cavUCoK53uvFzTvkey",
"name": "Vendor XYZ Payment",
"type": "EXTERNAL",
"senderagentid": "agent_eC6ZezevNsqxvoKmQrUuoU",
"receiveragentid": "agent_k77NTwxp2Ym3JCmVsKtXQA",
"status": "New",
"approvalstatus": "Waiting",
"approvalrequired": true,
"paymentdetails": {
"method": "CRYPTO_ADDRESS",
"amount": 6,
"currency": "USDC"
},
"contactdetails": {
"email": "contact@vendorxyz.com",
"phoneNumber": "+1234567890"
},
"tags": [
"vendor",
"regular"
],
"createdat": "2025-04-17T10:28:18.512792+00:00",
"approvedat": "2025-04-17T11:30:00.000000+00:00"
}
```
## Available Endpoints
Create a new payment transaction between agents
Approve a payment that requires authorization
Decline a payment to prevent processing
Fetch details of a specific payment
Get all payments related to the user's agents
Export payments data in various formats
## Payment Lifecycle
The typical lifecycle of a payment includes:
1. **Creation**: A payment is registered with sender, receiver, and amount details
2. **Approval Check**: The system determines if approval is required based on agent rules
3. **Approval/Decline**: If required, the payment is approved or declined by an authorized user
4. **Processing**: For approved payments, funds are transferred on the blockchain
5. **Completion**: The payment status is updated to "Confirmed" when complete
## Payment Types
**Payment Classifications**: Mage provides distinct payment types to clearly identify the relationship between transacting parties.
- **EXTERNAL**: Payments to recipients outside your agent network
- **INTERNAL**: Transfers between your own agents
## Payment Status Flow
**Status Progression**: Payments move through several states from creation to completion, with different approval paths based on agent rules.
| Status | Description |
|--------|-------------|
| New | Created and awaiting approval or processing |
| Pending | In process of being executed on blockchain |
| Confirmed | Fully processed and completed |
| Approval Status | Description |
|-----------------|-------------|
| Waiting | Initial state before approval check |
| Pending | Payment is awaiting additional confirmation |
| Approved | Payment has been explicitly approved |
| Decline | Payment has been explicitly declined |
| Waiting for Sender Approval | Payment requires explicit sender authorization |
## Best Practices
- Use meaningful payment names and tags for better organization and reporting
- Implement proper error handling for declined or failed payments
- Set appropriate approval thresholds in agent configuration based on risk tolerance
- Use the correct payment type based on recipient relationship (INTERNAL vs. EXTERNAL)
- Regularly monitor payment statuses, especially those requiring approval
- Check the approval status before assuming a payment has been processed
- Include relevant contact details for external payments to facilitate communication
================================================
FILE: api-reference/payments/register-payment.mdx
================================================
---
title: 'Register Payment'
api: 'POST /payments/register'
description: "Create a new payment transaction between agents"
---
**Agent Transactions**: Create payments between agents with automatic application of approval rules based on the sender's configuration.
## Request Headers
Your API key for authentication
## Request Body
ID of the agent sending the payment
ID of the agent receiving the payment
Payment amount
Payment currency (typically "USDC")
Payment method (typically "CRYPTO_ADDRESS")
Name or description of the payment
Contact email for the payment recipient
Contact phone number for the payment recipient
Tags or categories for the payment
## Response
Unique payment identifier in short ID format
Name or description of the payment
Type of payment (EXTERNAL or INTERNAL)
Current status of the payment (New, Pending, or Confirmed)
Timestamp when the payment was created
Whether this payment requires approval
Current approval status (Waiting, Pending, Approved, or Decline)
Transaction hash on the blockchain (if processed immediately)
```json 200 Requires Approval
{
"id": "payee_wDG5cavUCoK53uvFzTvkey",
"name": "Vendor XYZ Payment",
"type": "EXTERNAL",
"status": "New",
"approvalstatus": "Waiting",
"approvalRequired": true,
"createdat": "2025-04-17T10:28:18.512792",
"txHash": null
}
```
```json 200 Instant Payment
{
"id": "payee_xFG8eqvUXeK23zmFwTasLc",
"name": "Small transaction",
"type": "INTERNAL",
"status": "Confirmed",
"approvalstatus": "Approved",
"approvalRequired": false,
"createdat": "2025-04-17T10:30:22Z",
"txHash": "0xabc123..."
}
```
```json 400
{
"error": "Insufficient balance in sender agent's wallet"
// OR
"error": "Required fields missing: senderagentid, receiveragentid, paymentdetails, name, type"
// OR
"error": "Invalid payment details. Amount must be positive."
}
```
```json 401
{
"error": "Invalid or missing API key"
}
```
```json 500
{
"error": "Internal Server Error"
}
```
```json 404
{
"error": "Sender agent not found"
}
```
## Status Codes
| Status Code | Description |
|-------------|-------------|
| 200 | Payment registered successfully |
| 400 | Bad Request - Invalid parameters or insufficient balance |
| 401 | Unauthorized - Invalid or missing API key |
| 404 | Not Found - Agent not found |
| 500 | Internal Server Error |
**Payment Limits**: The payment will fail if it exceeds the sender agent's transaction or daily limits.
**Payment Types**: Use "EXTERNAL" for payments to recipients outside your agent network and "INTERNAL" for payments between your own agents.
**Approval Flow**: Payments requiring approval will need to be approved using the [Approve Payment](/api-reference/payments/approve-payment) endpoint before they are processed.
================================================
FILE: api-reference/savings/calculate-interest.mdx
================================================
---
title: 'Calculate Interest'
api: 'POST /investment/calculator'
description: 'Calculate potential interest'
---
**Investment Planning**: Project potential earnings on investments with detailed calculation breakdowns for financial planning.
## Request Headers
Your API key for authentication
## Request Body
Principal amount to invest
Investment duration in days
Optional custom interest rate (annual percentage)
## Response
Principal amount for the calculation
Duration of the investment in days
Annual interest rate applied to the calculation
Interest amount earned over the period
Total amount including principal and interest
Annual percentage yield
Formula used for the calculation
Step-by-step breakdown of the calculation
```json 200
{
"principal": 1000,
"days": 365,
"interestRate": 4.5,
"interestEarned": "45.00",
"totalAmount": "1045.00",
"annualYield": "4.50%",
"calculation": {
"formula": "principal × rate × (days ÷ 365)",
"steps": [
"1000 × 0.045 × 365/365",
"1000 × 0.045 × 1.000000",
"1000 × 0.045 × 0.045000",
"45.000000"
]
}
}
```
```json 400
{
"success": false,
"error": "Amount and days are required"
}
```
```json 400
{
"success": false,
"error": "Amount must be a positive number"
}
```
```json 400
{
"success": false,
"error": "Days must be a positive number"
}
```
```json 500
{
"error": "Internal server error"
}
```
## Status Codes
| Status Code | Description |
|-------------|-------------|
| 200 | Interest calculation completed successfully |
| 400 | Invalid request parameters |
| 500 | Internal Error |
**Default Rate**: If no custom rate is provided, the calculation uses the platform's current base interest rate.
**Simple Interest**: The calculator uses a simple interest formula that divides the annual rate by 365 days for daily accrual.
================================================
FILE: api-reference/savings/deposit.mdx
================================================
---
title: 'Deposit Savings'
api: 'POST /savings/deposit'
description: "Deposit savings into an agent's account"
---
**Investment Creation**: Creates a new investment by depositing funds into an agent's savings account. The operation converts the agent ID to UUID format if provided in short format, validates the deposit amount, and creates a new investment record.
## Request Headers
Your API key for authentication
## Request Body
The short ID or UUID of the agent
Amount to deposit (must be positive)
## Response
Whether the deposit was successful
Information about the deposit
The ID of the newly created investment
Transaction hash on the blockchain
Status of the transaction
```json 200
{
"success": true,
"message": "Successfully invested 100.50 USDC.",
"investmentId": "inv_k77NTwxp2Ym3JCmVsKtXQA",
"transaction": {
"txHash": "0x123...abc",
"status": "completed"
}
}
```
```json 400
{
"error": "agentId and amount are required"
// OR
"error": "Amount must be a positive number"
// OR
"error": "Agent has insufficient balance"
}
```
```json 404
{
"error": "Agent not found"
}
```
```json 401
{
"error": "Invalid or missing API key"
}
```
```json 500
{
"error": "Internal server error"
}
```
## Status Codes
| Status Code | Description |
|-------------|-------------|
| 200 | Deposit completed successfully |
| 400 | Bad Request - Invalid or missing parameters |
| 401 | Unauthorized - Invalid or missing API key |
| 404 | Not Found - Agent not found |
| 500 | Internal Server Error |
**Agent ID Format**: The API accepts both short ID format (agent_xxx) and UUID format for the agent ID parameter.
**Amount Validation**: The deposit amount must be a positive number. The system will validate this before processing the transaction.
**Investment Record**: A new investment record is created when the deposit is processed successfully. This can be used to track the investment's growth over time.
================================================
FILE: api-reference/savings/get-agent-investments.mdx
================================================
---
title: 'Get Agent Investments'
api: 'GET /savings/{agentId}'
description: 'Get all investments for a specific agent'
---
**Investment History**: Retrieves all investments (both active and completed) associated with a specific agent. For active investments, calculates the current value and interest earned based on the principal amount, interest rate, and investment duration. Returns detailed information including investment status and creation timestamp.
## Path Parameters
The short ID or UUID of the agent
## Request Headers
Your API key for authentication
## Response
Unique investment identifier in short ID format
ID of the agent associated with this investment
Principal amount invested
Timestamp when the investment was created
Current status of the investment (active, completed, cancelled)
Current value of the investment including earned interest
Interest earned on the investment to date
```json 200
{
"investments": [
{
"id": "inv_k77NTwxp2Ym3JCmVsKtXQA",
"agent_id": "agent_k77NTwxp2Ym3JCmVsKtXQA",
"amount": 1000,
"invested_at": "2025-04-15T11:00:08.432269+00:00",
"status": "active",
"current_value": "1050.00",
"interest_earned": "50.00"
},
{
"id": "inv_p99QTaxp3Zm3KDnWtLuRrD",
"agent_id": "agent_k77NTwxp2Ym3JCmVsKtXQA",
"amount": 500,
"invested_at": "2025-03-10T09:15:22.123456+00:00",
"status": "completed",
"current_value": "515.25",
"interest_earned": "15.25"
}
]
}
```
```json 400
{
"error": "Bad request"
}
```
```json 401
{
"error": "Invalid or missing API key"
}
```json 404
{
"error": "Agent not found"
}
```
```json 500
{
"error": "Internal server error"
}
```
## Status Codes
| Status Code | Description |
|-------------|-------------|
| 200 | List of investments retrieved successfully |
| 400 | Bad Request - Invalid agent ID format |
| 401 | Unauthorized - Invalid or missing API key |
| 404 | Not Found - Agent not found |
| 500 | Internal Server Error |
**All Investment Statuses**: This endpoint returns all investments for the agent regardless of status (active, completed, cancelled).
**Real-time Calculations**: For active investments, current values and interest earned are calculated in real-time based on the current interest rate and investment duration.
**Completed Investments**: For completed investments, the values shown represent the final amounts at the time of withdrawal.
================================================
FILE: api-reference/savings/get-dashboard.mdx
================================================
---
title: 'Get Savings Dashboard'
api: 'GET /savings/dashboard'
description: "Get a comprehensive overview of the user's savings portfolio"
---
**Portfolio Overview**: View your entire savings portfolio with real-time calculations of interest earned and projected growth.
## Request Headers
Your API key for authentication
## Response
Total current value of all investments including interest
Current interest rate applied to investments
Total principal amount invested by the user
Projected value of investments after one year at current rate
Name of the agent
Investment ID in short format
Total balance including investment value
Principal amount invested
Current value with interest
Interest earned to date
Current balance in agent's account
Days the investment has been active
```json 200
{
"totalSavings": 1500.75,
"interestRate": 5,
"totalInvested": 1000,
"yearProjection": 1050,
"agents": [
{
"agent": "Payment Assistant",
"investment_id": "inv_k77NTwxp2Ym3JCmVsKtXQA",
"totalBalance": 1200.5,
"investedAmount": 1000,
"currentValue": 1200.5,
"interest": 200.5,
"current": 1000,
"daysInvested": 365
},
{
"agent": "Marketing Budget",
"investment_id": "inv_j88MTaxp3Zm3KDnWtLuPpB",
"totalBalance": 300.25,
"investedAmount": 300,
"currentValue": 300.25,
"interest": 0.25,
"current": 500,
"daysInvested": 2
}
]
}
```
```json 401
{
"error": "Invalid or missing API key"
}
```
```json 500
{
"error": "Internal Server Error"
}
```
## Status Codes
| Status Code | Description |
|-------------|-------------|
| 200 | Savings dashboard data retrieved successfully |
| 401 | Unauthorized - Invalid or missing API key |
| 500 | Internal Server Error |
**Real-time Calculations**: Interest calculations are performed in real-time based on the current interest rate and the exact duration of each investment.
**Active Investments**: Only active investments are included in the dashboard. Completed or cancelled investments will not appear.
**Currency**: All monetary values are in USDC by default, and the interest rate is expressed as an annual percentage yield (APY).
================================================
FILE: api-reference/savings/get-interest-rate.mdx
================================================
---
title: 'Get Interest Rate'
api: 'GET /investment/interest-rate'
description: 'Get the current annual interest rate for investments'
---
**Yield Information**: Retrieve the current interest rate used for all savings calculations in the platform.
## Request Headers
Your API key for authentication
## Response
Current annual interest rate for investments (percentage)
Timestamp when the interest rate was last updated
```json 200
{
"interestRate": 4.50,
"lastUpdated": "2025-05-04T12:00:00Z"
}
```
```json 401
{
"error": "Invalid or missing API key"
}
```
```jsom 500
{
"error": "Internal Server Error"
}
```
## Status Codes
| Status Code | Description |
|-------------|-------------|
| 200 | Interest rate retrieved successfully |
| 401 | Unauthorized - Invalid or missing API key |
| 500 | Internal Server Error |
**Annual Percentage Yield**: The interest rate is expressed as an annual percentage yield (APY), which may change over time based on market conditions.
**Rate Changes**: When new investments are created, the current interest rate at that time is recorded and applied to that investment.
================================================
FILE: api-reference/savings/get-user-investments.mdx
================================================
---
title: 'Get User Investments'
api: 'GET /savings/myinvestments'
description: 'Get all active investments for the authenticated user'
---
**Active Investments**: Retrieve a comprehensive list of all active investments across all your agents with real-time value calculations.
## Request Headers
Your API key for authentication
## Response
Name of the agent
Investment ID in short format
Total balance including investment value
Principal amount invested
Current value with interest
Interest earned to date
Current balance in agent's account
Days the investment has been active
```json 200
{
"agents": [
{
"agent": "Payment Assistant",
"investment_id": "inv_k77NTwxp2Ym3JCmVsKtXQA",
"totalBalance": 1200.5,
"investedAmount": 1000,
"currentValue": 1200.5,
"interest": 200.5,
"current": 1000,
"daysInvested": 365
},
{
"agent": "Marketing Budget",
"investment_id": "inv_j88MTaxp3Zm3KDnWtLuPpB",
"totalBalance": 300.25,
"investedAmount": 300,
"currentValue": 300.25,
"interest": 0.25,
"current": 500,
"daysInvested": 2
}
]
}
```
```json 200
{
"agents": []
}
```
```json 401
{
"error": "Invalid or missing API key"
}
```
```json 500
{
"error": "Internal Server Error"
}
```
## Status Codes
| Status Code | Description |
|-------------|-------------|
| 200 | List of active investments retrieved successfully |
| 401 | Unauthorized - Invalid or missing API key |
| 500 | Internal Server Error |
**Active Only**: This endpoint returns only active investments; completed or cancelled investments are not included.
**Real-time Calculations**: Interest values are calculated in real-time based on the current platform interest rate and exact investment duration.
**Total Balance**: The `totalBalance` for each agent includes both the investment value and the regular wallet balance.
================================================
FILE: api-reference/savings/introduction.mdx
================================================
---
title: 'Introduction'
description: 'Manage interest-bearing savings accounts and investments'
---
# 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
```json
{
"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 the current annual interest rate
Calculate potential interest for a given amount and period
Deposit funds into a savings account
Withdraw funds from a savings account
Get an overview of all savings investments
Get all investments for a specific agent
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.
```
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
================================================
FILE: api-reference/savings/withdraw.mdx
================================================
---
title: 'Withdraw Savings'
api: 'POST /savings/withdraw'
description: 'Withdraw funds from a savings investment'
---
**Complete Withdrawal**: Closes an active investment and returns the principal plus earned interest to the agent's wallet.
## Request Headers
Your API key for authentication
Must be set to `application/json`
## Request Body
The short ID or UUID of the investment
## Response
Whether the withdrawal was successful
Information about the withdrawal
Original amount invested
Interest earned during the investment period
Total amount withdrawn (principal + interest)
Number of days the investment was active
Number of hours beyond whole days
Number of minutes beyond whole hours
Transaction hash on the blockchain
Status of the transaction
The ID of the agent that owned the investment
New balance of the agent after the withdrawal
```json 200
{
"success": true,
"message": "Withdrawal completed successfully.",
"withdrawalDetails": {
"principal": "1000.00",
"interest": "45.75",
"totalAmount": "1045.75",
"duration": {
"days": 30,
"hours": 5,
"minutes": 23
}
},
"transaction": {
"txHash": "0x123...abc",
"status": "completed"
},
"agentId": "agent_k77NTwxp2Ym3JCmVsKtXQA",
"updatedBalance": "1545.75"
}
```
```json 400
{
"error": "Investment ID is required"
}
```
```json 404
{
"error": "Investment not found"
}
```
```json 400
{
"error": "Investment has already been completed or cancelled"
}
```json 401 Unauthorized
{
"error": "Invalid or missing API key"
}
```
```json 500 Internal Server Error
{
"error": "Internal Server Error"
}
```
## Status Codes
| Status Code | Description |
|-------------|-------------|
| 200 | Withdrawal completed successfully |
| 400 | Bad Request - Invalid or missing parameters |
| 401 | Unauthorized - Invalid or missing API key |
| 404 | Not Found - Investment not found |
| 500 | Internal Server Error |
**Active Investments Only**: Only investments with an "active" status can be withdrawn. Attempting to withdraw completed or cancelled investments will result in an error.
**Interest Calculation**: Interest is calculated up to the exact moment of withdrawal, including partial days.
**Blockchain Confirmation**: The transaction may take a few moments to be confirmed on the blockchain before the funds appear in the agent's wallet.
================================================
FILE: api-reference/transactions/get-transaction-summary.mdx
================================================
---
title: 'Transaction Summary'
api: 'GET /transactions/summary'
description: 'Get a summary of financial activity for a date range'
---
**Financial Overview**: Get a concise summary of transaction totals across all your agents for any specified date range.
## Request Headers
Your API key for authentication
## Query Parameters
Start date for summary (ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ)
End date for summary (ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ)
## Response
Total amount received by your agents during the period
Total amount spent by your agents during the period
Total number of transactions during the period
```json 200
{
"totalEarned": 1250.50,
"totalSpent": 750.25,
"transactionCount": 15
}
```
```json 400
{
"success": false,
"error": "start_date and end_date are required"
}
```
```json 400
{
"success": false,
"error": "Invalid date format. Use ISO format (e.g., 2023-05-01T00:00:00Z)"
}
```
## Status Codes
| Status Code | Description |
|-------------|-------------|
| 200 | Summary data retrieved successfully |
| 400 | Bad Request - Invalid or missing parameters |
| 401 | Unauthorized - User not authenticated |
| 500 | Internal Server Error |
**All Agents Included**: The summary automatically combines transactions across all your agents, providing a consolidated financial overview.
**Zero Results**: If no agents are found or no transactions exist for the specified period, the endpoint will return zeros for all values with a 200 status code.
================================================
FILE: api-reference/transactions/introduction.mdx
================================================
---
title: 'Introduction'
description: 'Track and analyze blockchain transactions'
---
# Transactions API
**Financial Analytics**: The Transactions API provides visibility into the flow of funds between your agents and summarizes your financial activity.
Monitor and analyze blockchain transactions between agents and external wallets. Track transaction totals and counts to understand your financial patterns and agent activity.
## Transaction Model
**Blockchain Integration**: All financial transfers in Mage are executed on the blockchain, providing an immutable record of every transaction.
Each transaction in the Mage system consists of:
- **Transaction Hash**: Unique blockchain identifier (txHash)
- **Status**: Current state of the transaction
- **Amount**: Value transferred in the transaction
- **Currency**: Type of cryptocurrency used (typically USDC)
- **Wallet Addresses**: Source and destination of funds
- **Timestamp**: When the transaction occurred
```json
{
"txHash": "0x123...abc",
"status": "completed",
"amount": "50",
"currency": "USDC",
"from_wallet": "0xa55B42bA7B639bB9CEc2dB2520aC8Cff588895f6",
"to_wallet": "0xb66C42bA7B639bB9CEc2dB2520aC8Cff588895f6",
"timestamp": "2025-05-03T18:52:39Z"
}
```
## Available Endpoints
Get a summary of financial activity for a date range
## Transaction Categories
**Comprehensive Tracking**: Mage monitors all financial movements involving your agents' wallets.
The Transaction Summary endpoint provides aggregated totals for:
- **Total Earned**: Sum of all incoming transactions to your agents
- **Total Spent**: Sum of all outgoing transactions from your agents
- **Transaction Count**: Number of transactions during the specified period
## Best Practices
- Review transaction summaries regularly to monitor financial activity
- Use specific date ranges to focus on particular time periods
- Track the ratio between earned and spent amounts to monitor cash flow
- Compare transaction counts across different time periods to identify trends
- Export transaction data for integration with accounting systems
**Blockchain Confirmation**: Blockchain transactions may take time to confirm, so recent transactions might not appear immediately in summaries.
================================================
FILE: api-reference/users/get-wallet-balance.mdx
================================================
---
title: 'Get Wallet Balance'
api: 'GET /user/wallet-balance'
description: "Retrieve the authenticated user's wallet balance from the blockchain"
---
Retrieves the user's wallet balance from the blockchain using their wallet address. The endpoint follows a fallback strategy, first attempting to fetch USDC balance, then ETH, and finally any other non-zero balance.
## Request Headers
Your API key for authentication
## Response
Whether the balance retrieval was successful
Current wallet balance formatted as a string to preserve precision
Asset type (USDC, ETH, or other cryptocurrency)
Additional information about the balance retrieval (appears when balance fetching methods fail)
```json 200 USDC Balance
{
"success": true,
"balance": "100.50",
"asset": "USDC"
}
```
```json 200 ETH Balance
{
"success": true,
"balance": "0.05",
"asset": "ETH"
}
```
```json 200 Zero Balance
{
"success": true,
"balance": "0.00",
"message": "All balance fetching methods failed"
}
```
```json 400
{
"error": "Invalid wallet address format"
}
```
```json 401
{
"error": "Invalid or missing API key"
}
```
```json 500
{
"error": "Unexpected error"
}
```
## Status Codes
| Status Code | Description |
|-------------|-------------|
| 200 | Wallet balance retrieved successfully |
| 400 | Bad Request - Invalid wallet address format |
| 401 | Unauthorized - Invalid or missing API key |
| 500 | Unexpected error |
## Notes
- Requires authentication with a valid API key.
- The endpoint uses a fallback strategy: first checks USDC, then ETH, and finally any other non-zero balance.
- Balance is returned as a string to preserve precision for financial calculations.
- If all balance fetching methods fail, the API will return a successful response with a zero balance and an explanatory message.
================================================
FILE: api-reference/users/introduction.mdx
================================================
---
title: 'Introduction'
description: 'Manage user accounts and wallet balances'
---
# Users API
**Key Feature**: The Users API provides real-time blockchain balance information through a reliable fallback strategy.
The Users API provides endpoints for managing user accounts and accessing wallet balances. These endpoints enable you to check your wallet balance and manage other user-specific data.
## User and Wallet Model
**Best Practice**: Store the user's wallet address securely as it's used automatically in balance retrieval operations.
Each user in the Mage platform includes:
1. **Identity**:
- Unique user ID (UUID)
- Name
- Email
- Role
- Organization ID
2. **Authentication**:
- API key
- OAuth provider
3. **Wallet**:
- Wallet address
- Associated blockchain network
- Balance (retrieved in real-time from blockchain)
## Available Endpoints
Retrieve the authenticated user's wallet balance from the blockchain
## Wallet Operations
**Important**: The wallet balance endpoint automatically determines the user's wallet address from their account. No need to provide the address in your requests.
Wallets in Mage have several key characteristics:
1. **Associated with User**: Each user has a primary wallet for funding agents
2. **Automatic Agent Wallets**: Each agent also automatically gets a dedicated wallet upon creation
3. **Network Specific**: Wallets operate on specific blockchain networks (mainnet or testnets)
4. **Balance Reporting**: All balances are retrieved in real-time from the blockchain
5. **Fallback Strategy**: Balance retrieval follows a priority system - first USDC, then ETH, and finally any other non-zero balance
## Asset Support
**Response Format**: All balance values are returned as strings to preserve precision for financial calculations.
The wallet balance endpoint supports multiple cryptocurrencies:
- **USDC**: Primary stablecoin for transactions (checked first)
- **ETH**: Secondary asset (checked if USDC is unavailable)
- **Other Assets**: Additional tokens may be reported if both USDC and ETH balances are zero
## User Authentication
**Required**: All wallet balance requests must include your API key in the header to authenticate the user and access their wallet data.
All API requests require authentication using an API key. The key identifies the user and provides access to their data.
Your API key should be included in all requests as an HTTP header:
```bash
x-api-key: YOUR_API_KEY
```
**Authentication Error**: Requests without a valid API key will receive a 401 error and cannot access wallet data.
================================================
FILE: essentials/code.mdx
================================================
---
title: 'Code Blocks'
description: 'Display inline code and code blocks'
icon: 'code'
---
## Basic
### Inline Code
To denote a `word` or `phrase` as code, enclose it in backticks (`).
```
To denote a `word` or `phrase` as code, enclose it in backticks (`).
```
### Code Block
Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks and follow the leading ticks with the programming language of your snippet to get syntax highlighting. Optionally, you can also write the name of your code after the programming language.
```java HelloWorld.java
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
````md
```java HelloWorld.java
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
````
================================================
FILE: essentials/images.mdx
================================================
---
title: 'Images and Embeds'
description: 'Add image, video, and other HTML elements'
icon: 'image'
---
## Image
### Using Markdown
The [markdown syntax](https://www.markdownguide.org/basic-syntax/#images) lets you add images using the following code
```md
```
Note that the image file size must be less than 5MB. Otherwise, we recommend hosting on a service like [Cloudinary](https://cloudinary.com/) or [S3](https://aws.amazon.com/s3/). You can then use that URL and embed.
### Using Embeds
To get more customizability with images, you can also use [embeds](/writing-content/embed) to add images
```html
```
## Embeds and HTML elements
Mintlify supports [HTML tags in Markdown](https://www.markdownguide.org/basic-syntax/#html). This is helpful if you prefer HTML tags to Markdown syntax, and lets you create documentation with infinite flexibility.
### iFrames
Loads another HTML page within the document. Most commonly used for embedding videos.
```html
```
================================================
FILE: essentials/markdown.mdx
================================================
---
title: 'Markdown Syntax'
description: 'Text, title, and styling in standard markdown'
icon: 'text-size'
---
## Titles
Best used for section headers.
```md
## Titles
```
### Subtitles
Best use to subsection headers.
```md
### Subtitles
```
Each **title** and **subtitle** creates an anchor and also shows up on the table of contents on the right.
## Text Formatting
We support most markdown formatting. Simply add `**`, `_`, or `~` around text to format it.
| Style | How to write it | Result |
| ------------- | ----------------- | --------------- |
| Bold | `**bold**` | **bold** |
| Italic | `_italic_` | _italic_ |
| Strikethrough | `~strikethrough~` | ~strikethrough~ |
You can combine these. For example, write `**_bold and italic_**` to get **_bold and italic_** text.
You need to use HTML to write superscript and subscript text. That is, add `` or `` around your text.
| Text Size | How to write it | Result |
| ----------- | ------------------------ | ---------------------- |
| Superscript | `superscript` | superscript |
| Subscript | `subscript` | subscript |
## Linking to Pages
You can add a link by wrapping text in `[]()`. You would write `[link to google](https://google.com)` to [link to google](https://google.com).
Links to pages in your docs need to be root-relative. Basically, you should include the entire folder path. For example, `[link to text](/writing-content/text)` links to the page "Text" in our components section.
Relative links like `[link to text](../text)` will open slower because we cannot optimize them as easily.
## Blockquotes
### Singleline
To create a blockquote, add a `>` in front of a paragraph.
> Dorothy followed her through many of the beautiful rooms in her castle.
```md
> Dorothy followed her through many of the beautiful rooms in her castle.
```
### Multiline
> Dorothy followed her through many of the beautiful rooms in her castle.
>
> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
```md
> Dorothy followed her through many of the beautiful rooms in her castle.
>
> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
```
### LaTeX
Mintlify supports [LaTeX](https://www.latex-project.org) through the Latex component.
8 x (vk x H1 - H2) = (0,1)
```md
8 x (vk x H1 - H2) = (0,1)
```
================================================
FILE: essentials/navigation.mdx
================================================
---
title: 'Navigation'
description: 'The navigation field in docs.json defines the pages that go in the navigation menu'
icon: 'map'
---
The navigation menu is the list of links on every website.
You will likely update `docs.json` every time you add a new page. Pages do not show up automatically.
## Navigation syntax
Our navigation syntax is recursive which means you can make nested navigation groups. You don't need to include `.mdx` in page names.
```json Regular Navigation
"navigation": {
"tabs": [
{
"tab": "Docs",
"groups": [
{
"group": "Getting Started",
"pages": ["quickstart"]
}
]
}
]
}
```
```json Nested Navigation
"navigation": {
"tabs": [
{
"tab": "Docs",
"groups": [
{
"group": "Getting Started",
"pages": [
"quickstart",
{
"group": "Nested Reference Pages",
"pages": ["nested-reference-page"]
}
]
}
]
}
]
}
```
## Folders
Simply put your MDX files in folders and update the paths in `docs.json`.
For example, to have a page at `https://yoursite.com/your-folder/your-page` you would make a folder called `your-folder` containing an MDX file called `your-page.mdx`.
You cannot use `api` for the name of a folder unless you nest it inside another folder. Mintlify uses Next.js which reserves the top-level `api` folder for internal server calls. A folder name such as `api-reference` would be accepted.
```json Navigation With Folder
"navigation": {
"tabs": [
{
"tab": "Docs",
"groups": [
{
"group": "Group Name",
"pages": ["your-folder/your-page"]
}
]
}
]
}
```
## Hidden Pages
MDX files not included in `docs.json` will not show up in the sidebar but are accessible through the search bar and by linking directly to them.
================================================
FILE: essentials/reusable-snippets.mdx
================================================
---
title: Reusable Snippets
description: Reusable, custom snippets to keep content in sync
icon: 'recycle'
---
import SnippetIntro from '/snippets/snippet-intro.mdx';
## Creating a custom snippet
**Pre-condition**: You must create your snippet file in the `snippets` directory.
Any page in the `snippets` directory will be treated as a snippet and will not
be rendered into a standalone page. If you want to create a standalone page
from the snippet, import the snippet into another file and call it as a
component.
### Default export
1. Add content to your snippet file that you want to re-use across multiple
locations. Optionally, you can add variables that can be filled in via props
when you import the snippet.
```mdx snippets/my-snippet.mdx
Hello world! This is my content I want to reuse across pages. My keyword of the
day is {word}.
```
The content that you want to reuse must be inside the `snippets` directory in
order for the import to work.
2. Import the snippet into your destination file.
```mdx destination-file.mdx
---
title: My title
description: My Description
---
import MySnippet from '/snippets/path/to/my-snippet.mdx';
## Header
Lorem impsum dolor sit amet.
```
### Reusable variables
1. Export a variable from your snippet file:
```mdx snippets/path/to/custom-variables.mdx
export const myName = 'my name';
export const myObject = { fruit: 'strawberries' };
```
2. Import the snippet from your destination file and use the variable:
```mdx destination-file.mdx
---
title: My title
description: My Description
---
import { myName, myObject } from '/snippets/path/to/custom-variables.mdx';
Hello, my name is {myName} and I like {myObject.fruit}.
```
### Reusable components
1. Inside your snippet file, create a component that takes in props by exporting
your component in the form of an arrow function.
```mdx snippets/custom-component.mdx
export const MyComponent = ({ title }) => (
{title}
... snippet content ...
);
```
MDX does not compile inside the body of an arrow function. Stick to HTML
syntax when you can or use a default export if you need to use MDX.
2. Import the snippet into your destination file and pass in the props
```mdx destination-file.mdx
---
title: My title
description: My Description
---
import { MyComponent } from '/snippets/custom-component.mdx';
Lorem ipsum dolor sit amet.
```
================================================
FILE: essentials/settings.mdx
================================================
---
title: 'Global Settings'
description: 'Mintlify gives you complete control over the look and feel of your documentation using the docs.json file'
icon: 'gear'
---
Every Mintlify site needs a `docs.json` file with the core configuration settings. Learn more about the [properties](#properties) below.
## Properties
Name of your project. Used for the global title.
Example: `mintlify`
An array of groups with all the pages within that group
The name of the group.
Example: `Settings`
The relative paths to the markdown files that will serve as pages.
Example: `["customization", "page"]`
Path to logo image or object with path to "light" and "dark" mode logo images
Path to the logo in light mode
Path to the logo in dark mode
Where clicking on the logo links you to
Path to the favicon image
Hex color codes for your global theme
The primary color. Used for most often for highlighted content, section
headers, accents, in light mode
The primary color for dark mode. Used for most often for highlighted
content, section headers, accents, in dark mode
The primary color for important buttons
The color of the background in both light and dark mode
The hex color code of the background in light mode
The hex color code of the background in dark mode
Array of `name`s and `url`s of links you want to include in the topbar
The name of the button.
Example: `Contact us`
The url once you click on the button. Example: `https://mintlify.com/docs`
Link shows a button. GitHub shows the repo information at the url provided including the number of GitHub stars.
If `link`: What the button links to.
If `github`: Link to the repository to load GitHub information from.
Text inside the button. Only required if `type` is a `link`.
Array of version names. Only use this if you want to show different versions
of docs with a dropdown in the navigation bar.
An array of the anchors, includes the `icon`, `color`, and `url`.
The [Font Awesome](https://fontawesome.com/search?q=heart) icon used to feature the anchor.
Example: `comments`
The name of the anchor label.
Example: `Community`
The start of the URL that marks what pages go in the anchor. Generally, this is the name of the folder you put your pages in.
The hex color of the anchor icon background. Can also be a gradient if you pass an object with the properties `from` and `to` that are each a hex color.
Used if you want to hide an anchor until the correct docs version is selected.
Pass `true` if you want to hide the anchor until you directly link someone to docs inside it.
One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
Override the default configurations for the top-most anchor.
The name of the top-most anchor
Font Awesome icon.
One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
An array of navigational tabs.
The name of the tab label.
The start of the URL that marks what pages go in the tab. Generally, this
is the name of the folder you put your pages in.
Configuration for API settings. Learn more about API pages at [API Components](/api-playground/demo).
The base url for all API endpoints. If `baseUrl` is an array, it will enable for multiple base url
options that the user can toggle.
The authentication strategy used for all API endpoints.
The name of the authentication parameter used in the API playground.
If method is `basic`, the format should be `[usernameName]:[passwordName]`
The default value that's designed to be a prefix for the authentication input field.
E.g. If an `inputPrefix` of `AuthKey` would inherit the default input result of the authentication field as `AuthKey`.
Configurations for the API playground
Whether the playground is showing, hidden, or only displaying the endpoint with no added user interactivity `simple`
Learn more at the [playground guides](/api-playground/demo)
Enabling this flag ensures that key ordering in OpenAPI pages matches the key ordering defined in the OpenAPI file.
This behavior will soon be enabled by default, at which point this field will be deprecated.
A string or an array of strings of URL(s) or relative path(s) pointing to your
OpenAPI file.
Examples:
```json Absolute
"openapi": "https://example.com/openapi.json"
```
```json Relative
"openapi": "/openapi.json"
```
```json Multiple
"openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"]
```
An object of social media accounts where the key:property pair represents the social media platform and the account url.
Example:
```json
{
"x": "https://x.com/mintlify",
"website": "https://mintlify.com"
}
```
One of the following values `website`, `facebook`, `x`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news`
Example: `x`
The URL to the social platform.
Example: `https://x.com/mintlify`
Configurations to enable feedback buttons
Enables a button to allow users to suggest edits via pull requests
Enables a button to allow users to raise an issue about the documentation
Customize the dark mode toggle.
Set if you always want to show light or dark mode for new users. When not
set, we default to the same mode as the user's operating system.
Set to true to hide the dark/light mode toggle. You can combine `isHidden` with `default` to force your docs to only use light or dark mode. For example:
```json Only Dark Mode
"modeToggle": {
"default": "dark",
"isHidden": true
}
```
```json Only Light Mode
"modeToggle": {
"default": "light",
"isHidden": true
}
```
A background image to be displayed behind every page. See example with
[Infisical](https://infisical.com/docs) and [FRPC](https://frpc.io).
================================================
FILE: snippets/api-key-notice.mdx
================================================
================================================
FILE: snippets/error-handling.mdx
================================================
================================================
FILE: snippets/response-formats.mdx
================================================
================================================
FILE: snippets/snippet-intro.mdx
================================================
One of the core principles of software development is DRY (Don't Repeat
Yourself). This is a principle that apply to documentation as
well. If you find yourself repeating the same content in multiple places, you
should consider creating a custom snippet to keep your content in sync.
================================================
FILE: user-guide/financing.mdx
================================================
---
title: "Financing"
icon: "money-bill-trend-up"
---
## Coming Soon
================================================
FILE: user-guide/get-api-key.mdx
================================================
---
title: "Get API Key"
description: "Generate and manage your Mage API key"
icon: "key"
---
**Authentication Essentials**: Your API key authenticates all requests to the Mage platform and is required for all API operations.
## Getting Your API Key
Navigate to the [Mage Dashboard](https://www.magebank.ai/dashboard/)
Create a new account or sign in to your existing account.
When you first sign up, an API key will be automatically generated for your account.
Once logged in, go to the [Integrate Agent](https://www.magebank.ai/dashboard/integrate-agent) section from the sidebar menu.
Click on the "API Key" button to open the key display modal.
Copy your API key for use in your applications.
Keep your API key secure. Anyone with your key can perform actions on behalf of your account.
## Using Your API Key
All API requests must include your API key in the `x-api-key` header as described in the [Authentication](/api-reference/authentication) page.
## Security Best Practices
**Key Protection**: Your API key grants full access to your Mage account. Treat it with the same care as a password.
- **Server-side only**: Never expose your API key in client-side code
- **Secure storage**: Use environment variables or a secrets manager
- **Repository safety**: Don't commit API keys to code repositories
- **Dedicated keys**: Use separate keys for development and production when possible
================================================
FILE: user-guide/register-agent.mdx
================================================
---
title: "Register Agent"
description: "Create and manage AI agents on Mage"
icon: "robot"
---
**Autonomous Finance**: Create intelligent agents that can execute financial transactions and manage funds within your defined limits and rules.
## Creating a New Agent
Access the Integrate Agent section from the sidebar menu.
Click the "Add new agent" button in the top right corner to begin the agent creation process.
The first step displays your current wallet balance and requires you to enter basic information about your agent:
- **Name**: A descriptive name for your agent
- **Description**: Purpose and functionality of the agent
- **Allocated Balance**: Amount to fund your agent (this will be deducted from your main wallet)
- **Tags** (optional): Add up to 5 tags to categorize your agent
In the second step, you'll set transaction limits and approval requirements:
- **Daily Limit**: Maximum amount the agent can spend in a single day
- **Transaction Limit**: Maximum amount for a single transaction
- **Require Approval Above Amount**: Transactions above this amount will require your manual approval
- **Require Approval For All Transactions**: Toggle to require approval for all transactions regardless of amount
**Security Consideration**: Carefully configure these limits based on your risk tolerance. Lower limits and approval requirements provide more security but may require more manual intervention.
After clicking "Next", your agent will be created. The confirmation screen displays:
- **Agent ID**: Unique identifier for your agent (copy this for API calls)
- **API Key**: Your Mage API key (same for all your agents)
- **Balance**: The amount allocated to your agent
- **Payment Rules**: Summary of all transaction limits and approval settings
- **Updated Balance**: Your remaining wallet balance after funding the agent
Keep your API key and Agent ID secure. These credentials provide access to your agent's funds and functionality.
## Understanding Agent Configuration
### Balance Allocation
**Blockchain Transfers**: When you create an agent, funds are transferred from your main wallet to the agent's dedicated blockchain wallet through a secure on-chain transaction.
When you create an agent, you allocate funds from your main wallet to the agent's wallet. This amount is deducted immediately from your global balance and becomes available for the agent to use within its configured limits.
### Payment Rules
**Transaction Control**: Payment rules provide granular control over how your agents can spend funds, allowing you to balance autonomy with security.
Payment rules determine how your agent can spend funds:
1. **Daily Limit**: Restricts the total amount an agent can spend in a 24-hour period
2. **Transaction Limit**: Caps the size of individual transactions
3. **Approval Requirements**: Configure when you need to manually approve transactions:
- Above a specific amount
- For all transactions (regardless of amount)
### Tags
Tags help organize your agents and make them easier to find. You can add up to 5 tags per agent and use them to filter your agents list. Common tag examples include:
- Project names (e.g., "marketing", "development")
- Agent functions (e.g., "payments", "subscriptions")
- Business units (e.g., "finance", "operations")
## Using Your Agent
Once created, your agent can:
- Make payments to external accounts
- Transfer funds between other agents
- Automatically process transactions within set limits
- Request approval for transactions exceeding limits
For details on how to use your agent with the API, see the [API Reference](/api-reference/agents/introduction) documentation.
## Managing Agents
**Central Dashboard**: All your agents can be monitored and managed from a single interface, giving you complete visibility of your automated financial operations.
After creating agents, you can:
- View all your agents in the Agents dashboard
- Monitor their transaction history
- Modify payment rules
- Add or remove funds
- Deactivate agents when no longer needed
================================================
FILE: user-guide/savings-vault.mdx
================================================
---
title: "Savings Vault"
description: "Earn interest on your USDC holdings"
icon: "vault"
---
**Passive Income**: The Mage Savings Vault allows your AI agents to deposit idle funds into interest-bearing accounts, automatically growing your portfolio while maintaining full liquidity.
## Savings Dashboard
**Real-Time Analytics**: The Savings dashboard provides real-time insights into your interest earnings and portfolio performance across all your agents.
The Savings Vault dashboard provides a comprehensive overview of your savings performance:
### Key Dashboard Elements
- **Total Savings**: Real-time display of your total savings balance with live updates
- **APY**: Current annual percentage yield (interest rate)
- **Invested**: Total amount deposited into savings
- **1-year Projection**: Estimated value of your savings after one year at the current APY
### Investment Table
The dashboard includes a detailed table showing all your active investments:
| Column | Description |
|--------|-------------|
| Agent | The agent that funded the investment |
| Invested Amount | Principal amount deposited |
| Current Value | Real-time value including accrued interest |
| Interest Earned | Total interest earned since deposit |
| Duration | Time elapsed since investment |
| Current Balance | Available balance in the agent's wallet |
## Depositing Funds
**No Lock-up Period**: Unlike traditional savings products, the Mage Savings Vault has no minimum deposit period, allowing complete flexibility and liquidity.
From the Savings Vault dashboard, click the "Deposit" button.
The deposit modal will appear with the following options:
- Select the agent to fund the deposit
- Enter the amount to deposit (up to the agent's available balance)
- View the current APY and projected interest
The system automatically calculates your projected earnings at the current APY rate and displays the estimated total value after one year.
Review the deposit details:
- Source agent
- Deposit amount
- Current APY
- Projected yearly interest
Click "Confirm deposit" to proceed.
Once the transaction is processed, you'll see a confirmation screen with the transaction summary.
The transaction might take a few minutes to process on the blockchain. Your dashboard will update automatically once the deposit is confirmed.
## Withdrawing Funds
**Instant Access**: Withdraw your funds at any time without penalties or waiting periods, with interest calculated up to the exact moment of withdrawal.
From the Savings Vault dashboard, click the "Withdraw" button.
The withdrawal modal will appear:
- Select the agent investment you wish to withdraw from
- View the investment details including principal, interest earned, and duration
When selecting an agent, you'll see a dropdown with all your active investments, including:
- Agent name
- Investment duration
- Current value with earned interest
Review the withdrawal details:
- Principal amount
- Interest earned
- Total withdrawal amount
Click "Confirm withdrawal" to proceed.
The entire investment (principal plus earned interest) will be transferred back to the selected agent's wallet.
After processing, your funds will be available in the selected agent's wallet.
The blockchain transaction might take a few minutes to complete. The agent's balance will update once the transaction is confirmed.
## How Interest Works
**Continuous Compounding**: The Savings Vault uses continuous compounding, the most favorable interest calculation method, allowing your investments to grow at the maximum possible rate.
The Savings Vault uses a compound interest model to grow your savings:
- **Interest Rate**: The current APY (Annual Percentage Yield) is displayed on the dashboard and can be updated to as high as 12.5%
- **Real-time Calculation**: Interest accrues continuously and is calculated in real-time
- **No Lock-up Period**: Funds can be deposited or withdrawn at any time without penalties
- **Interest Disbursement**: Interest is added directly to your investment's current value
### Interest Calculation
Your interest is calculated using the standard compound interest formula, which takes into account:
- Principal amount invested
- Annual interest rate (APY)
- Investment duration (including partial days)
- Continuous compounding methodology
For more details on interest calculations and to simulate different investment scenarios, visit the [Interest Calculator](/api-reference/savings/calculate-interest) in the API documentation.
================================================
FILE: user-guide/transactions.mdx
================================================
---
title: "Transactions"
description: "Track and manage financial operations between agents"
icon: "money-bill-transfer"
---
**Financial Visibility**: The Transactions dashboard provides complete transparency into all financial movements between your agents and external accounts, with detailed tracking and approval workflows.
## Transaction Dashboard
**Comprehensive Monitoring**: View all financial activities in a single interface with detailed information about each transaction's status, direction, and approval requirements.
The Transactions dashboard displays all your financial activities in a detailed table with key information:
- **Transaction ID**: Unique identifier for each transaction
- **Direction**: Whether funds are moving into (Incoming) or out of (Outgoing) your agent
- **Date & Time**: When the transaction was initiated
- **Status**: Current processing state of the transaction
- **Approval**: Approval status and required actions
- **Receiver ID**: The agent receiving the funds
- **Amount**: Transaction value with currency (positive for incoming, negative for outgoing)
## Transaction Lifecycle
**Transparent Process**: Each transaction follows a well-defined lifecycle with clear status indicators, allowing you to track its progress from creation to completion.
Each transaction follows a specific workflow:
1. **Creation**: When first registered, a transaction starts with "New" status
2. **Approval Check**:
- If approval is required (based on agent rules), status changes to "Waiting for Sender Approval"
- If no approval is needed, it proceeds directly to processing
3. **Processing**: The system processes the transaction on the blockchain
4. **Completion**: Once processed, status changes to "Confirmed" with appropriate approval status
### Transaction Statuses
| Status | Description |
|--------|-------------|
| New | Transaction has been created and is either awaiting approval or being processed |
| Waiting | System is checking whether approval is required based on agent rules |
| Confirmed | Transaction has been fully processed on the blockchain |
### Approval Flow
**Approval Timeout**: Transactions requiring approval will remain in the "Waiting for Sender Approval" state until approved or declined. They will not process automatically without explicit action.
1. When a transaction is first created, its status is set to "Waiting" while the system evaluates whether approval is required
2. If approval is required:
- Status changes to "New"
- Approval status changes to "Waiting for Sender Approval"
- A request appears in the Payment Requests section
3. If approval is not required:
- Status changes to "New"
- System immediately initiates the transaction
- Once successful, status updates to "Confirmed" with "Approved" approval status
## Approving Transactions
**Decision Control**: The approval system gives you final oversight on transactions that exceed defined thresholds, balancing agent autonomy with financial security.
When a transaction requires approval, you'll receive a notification in the Payment Approval Requests section:
To approve or decline a transaction:
1. Navigate to [Payment Requests](https://www.magebank.ai/dashboard/payment-request)
2. Review transaction details (initiator, amount, currency, date)
3. Click the "PAY" button to approve or "X" button to decline
4. For approved transactions:
- Status changes to "New"
- After processing (may take a few minutes), status updates to "Confirmed" with "Approved" approval status
- Funds transfer between accounts
5. For declined transactions:
- Status immediately changes to "Confirmed" with "Declined" approval status
- No funds are transferred
## Transaction Filtering and Export
**Financial Reporting**: Powerful filtering and export capabilities allow you to generate custom reports for accounting, analysis, and record-keeping.
Manage your transaction history with built-in tools:
### Time Filters
Filter transactions by time period using the dropdown in the top right:
- This Week (default)
- This Month
- This Year
- Custom Range
### Data Export
Export your transaction data in multiple formats:
- **XLSX** (Recommended): Includes advanced formatting and calculations
- **CSV**: Simple text format for universal compatibility
- **PDF**: Formatted document for sharing and printing
Click the "Export" button and select your preferred format.
## Understanding the Approval Flow
**Approval Triggers**: Transactions will automatically require approval under any of these conditions: amount exceeds approval threshold, "Approve All" is enabled, or transaction would exceed daily limit.
The approval workflow depends on the agent's configured payment rules:
1. **No Approval Required**: If the transaction is below the approval threshold and "Require Approval For All Transactions" is off, the transaction processes automatically.
2. **Approval Required**: A transaction will require approval if:
- The amount exceeds the "Require Approval Above Amount" value
- "Require Approval For All Transactions" is enabled
- The transaction would exceed the daily limit
3. **Processing Time**: Even after approval, blockchain transactions may take a few minutes to process before showing as "Confirmed".
For more details on integrating transaction functionality into your applications, please refer to the [Payments API](/api-reference/payments/introduction) documentation.
## Image
### Using Markdown
The [markdown syntax](https://www.markdownguide.org/basic-syntax/#images) lets you add images using the following code
```md
```
Note that the image file size must be less than 5MB. Otherwise, we recommend hosting on a service like [Cloudinary](https://cloudinary.com/) or [S3](https://aws.amazon.com/s3/). You can then use that URL and embed.
### Using Embeds
To get more customizability with images, you can also use [embeds](/writing-content/embed) to add images
```html
```
## Embeds and HTML elements
================================================
FILE: user-guide/savings-vault.mdx
================================================
---
title: "Savings Vault"
description: "Earn interest on your USDC holdings"
icon: "vault"
---
### Key Dashboard Elements
- **Total Savings**: Real-time display of your total savings balance with live updates
- **APY**: Current annual percentage yield (interest rate)
- **Invested**: Total amount deposited into savings
- **1-year Projection**: Estimated value of your savings after one year at the current APY
### Investment Table
The dashboard includes a detailed table showing all your active investments:
| Column | Description |
|--------|-------------|
| Agent | The agent that funded the investment |
| Invested Amount | Principal amount deposited |
| Current Value | Real-time value including accrued interest |
| Interest Earned | Total interest earned since deposit |
| Duration | Time elapsed since investment |
| Current Balance | Available balance in the agent's wallet |
## Depositing Funds
When selecting an agent, you'll see a dropdown with all your active investments, including:
- Agent name
- Investment duration
- Current value with earned interest
## Transaction Lifecycle
To approve or decline a transaction:
1. Navigate to [Payment Requests](https://www.magebank.ai/dashboard/payment-request)
2. Review transaction details (initiator, amount, currency, date)
3. Click the "PAY" button to approve or "X" button to decline
4. For approved transactions:
- Status changes to "New"
- After processing (may take a few minutes), status updates to "Confirmed" with "Approved" approval status
- Funds transfer between accounts
5. For declined transactions:
- Status immediately changes to "Confirmed" with "Declined" approval status
- No funds are transferred
## Transaction Filtering and Export
### Data Export
Export your transaction data in multiple formats:
- **XLSX** (Recommended): Includes advanced formatting and calculations
- **CSV**: Simple text format for universal compatibility
- **PDF**: Formatted document for sharing and printing
Click the "Export" button and select your preferred format.
## Understanding the Approval Flow