Skip to main content
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:

​
Authentication

Every API request must include your API key in the x-api-key header:
To get your API key, visit the Mage Dashboard and navigate to the “Integrate Agent” section.

​
API Endpoints

The Mage API is organized into the following categories:

Agents

Create and manage AI financial agents

Wallets

Manage wallet addresses and balances

Transactions

View and manage on-chain transactions

Investments

Interest rate information and calculations

Payments

Process payments between agents and external accounts

Users

User account management

Savings

Interest-bearing savings accounts

​
Response Format

All API responses are returned in JSON format. Successful responses typically include:

​
Error Handling

When an error occurs, the API returns an appropriate HTTP status code and a JSON object explaining the error:
Common HTTP status codes:

​
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:

​
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:
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 [email protected].