API Overview

​

API Overview

​

Base URLs

• Production: https://api.renesis.fi
• Development: http://localhost:3000/api
• API Documentation: http://localhost:3000/api/docs (development)

​

Authentication

​

API Key Authentication

Authorization: Bearer YOUR_API_KEY

​

Obtaining API Keys

1. Access the Renesis dashboard at https://terminal.renesis.fi
2. Navigate to API settings
3. Generate a new API key for your application
4. Store the API key securely and never expose it in client-side code

​

Authentication Errors

• 401 Unauthorized: Missing or invalid API key
• 403 Forbidden: API key lacks required permissions

​

Rate Limiting

​

Rate Limit Configuration

• Window: 15 minutes (900,000 ms)
• Maximum Requests: 100 requests per window per API key
• Burst Protection: Additional limits may apply for rapid successive requests

​

Rate Limit Headers

• X-RateLimit-Limit: Maximum requests allowed per window
• X-RateLimit-Remaining: Remaining requests in current window
• X-RateLimit-Reset: Timestamp when the rate limit window resets

​

Rate Limit Exceeded

• Status Code: 429 Too Many Requests
• Retry-After: Header indicating when to retry the request

​

CORS Configuration

​

CORS Settings

• Allowed Origins: Configurable per environment (default: http://localhost:3000, http://localhost:3001)
• Allowed Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
• Allowed Headers: Content-Type, Authorization, X-Requested-With
• Credentials: Supported for authenticated requests

​

Environment-Specific Origins

• Development: Local development servers
• Production: Authorized production domains only

​

Supported Networks

​

Network Types

• Testnet: For development, testing, and integration
  • Used for development and staging environments
  • Safe for testing without real asset risk
  • Separate token lists and configurations
• Mainnet: For production operations
  • Live network with real assets
  • Production-grade reliability and security
  • Complete token ecosystem support

​

Network Selection

# Testnet operations
POST /api/vaults/123/update-holdings?network=testnet

# Mainnet operations (default)
POST /api/vaults/123/update-holdings?network=mainnet

​

Network-Specific Features

• Token Lists: Different supported tokens per network
• Balance Fetching: Real-time balance updates from respective networks
• Validation: Network-appropriate address and contract validation

​

Response Format

​

Success Response

{
  "success": true,
  "message": "Operation completed successfully",
  "data": {
    // Response data object or array
  },
  "pagination": {
    "page": 1,
    "limit": 10,
    "totalItems": 25,
    "totalPages": 3,
    "hasNext": true,
    "hasPrev": false
  }
}

​

Error Response

{
  "success": false,
  "message": "Error description",
  "errors": [
    {
      "field": "fieldName",
      "message": "Specific validation error",
      "value": "invalid_value"
    }
  ]
}

​

Pagination Structure

• page: Current page number (1-based)
• limit: Number of items per page
• totalItems: Total number of items available
• totalPages: Total number of pages
• hasNext: Boolean indicating if there are more pages
• hasPrev: Boolean indicating if there are previous pages

​

API Features

​

Core Capabilities

• ✅ Complete CRUD Operations: Create, read, update, and delete vault management
• ✅ MongoDB Integration: Robust data storage with Mongoose ODM
• ✅ Token Holdings Tracking: Real-time balance updates and multi-token support
• ✅ Stellar Network Integration: Direct balance fetching from Stellar network
• ✅ Data Validation: Comprehensive input validation and sanitization
• ✅ Advanced Search: Pagination, filtering, and search functionality
• ✅ Security Middleware: Rate limiting, CORS, and authentication
• ✅ Error Handling: Structured error responses and logging
• ✅ TypeScript Support: Full type safety and IntelliSense support
• ✅ Stellar Address Validation: Built-in Stellar address format validation

​

Data Models

​

Vault Model

interface Vault {
  id: string;                    // MongoDB ObjectId
  vaultName: string;             // Human-readable vault name (2-100 chars)
  vaultOwner: string;            // Stellar address (starts with 'G', 56 chars)
  vaultAddress: string;          // Stellar contract address (starts with 'C', 56 chars)
  creationDate: string;          // ISO 8601 timestamp
  creationLedger: number;        // Stellar ledger number
  tradePermission: boolean;      // Trading allowed flag
  maxTradeSize: number;          // Max trade size as percentage (0-100)
  dailyTradeLimit: number;       // Daily trade limit count
  slippageTolerance: number;     // Slippage tolerance for swaps (0-100)
  updatedAt: string;             // ISO 8601 timestamp
  createdAt: string;             // ISO 8601 timestamp
}

​

Token Holdings Model

interface TokenHolding {
  id: string;                    // MongoDB ObjectId
  vaultId: string;               // Reference to vault ObjectId
  vaultAddress: string;          // Stellar contract address of vault
  tokenId: string;               // Stellar token contract address
  tokenSymbol: string;           // Token symbol (e.g., "USDC", "XLM")
  tokenName: string;             // Full token name (e.g., "USD Coin")
  tokenContract: string;         // Stellar contract address of token
  balance: string;               // Token balance as string (preserves precision)
  decimal: number;               // Token decimal places
  lastUpdated: string;           // ISO 8601 timestamp of last balance update
}

​

API Response Wrapper

interface APIResponse<T> {
  success: boolean;
  message: string;
  data?: T;
  pagination?: {
    page: number;
    limit: number;
    totalItems: number;
    totalPages: number;
    hasNext: boolean;
    hasPrev: boolean;
  };
  errors?: Array<{
    field: string;
    message: string;
    value?: any;
  }>;
}

​

Health Check & Utility Endpoints

​

Getting Started

​

Quick Start Guide

1. Obtain API Key: Get your API key from the Renesis dashboard
2. Choose Environment: Select appropriate base URL (development/production)
3. Test Connection: Use health check endpoints to verify connectivity
4. Create Vaults: Start with vault management endpoints
5. Manage Holdings: Use token endpoints for balance tracking
6. Implement Search: Add filtering and search capabilities

​

Development Workflow

1. Setup: Configure environment variables and MongoDB connection
2. Authentication: Implement API key authentication in your application
3. Error Handling: Implement proper error handling for all API responses
4. Rate Limiting: Respect rate limits and implement retry logic
5. Testing: Use testnet for development and testing

​

Next Steps

• Vault Endpoints - Core vault management operations
• Token Endpoints - Token holdings and balance management
• Search & Filtering - Advanced query capabilities
• Health Check & Utility Endpoints - API monitoring and information
• Error Handling - Error codes and troubleshooting