{"id":37311456,"url":"https://github.com/lugondev/trade-perps-api","last_synced_at":"2026-01-16T03:01:09.883Z","repository":{"id":322106541,"uuid":"1088228193","full_name":"lugondev/trade-perps-api","owner":"lugondev","description":"Multi-Exchange Perpetual Futures Trading Platform","archived":false,"fork":false,"pushed_at":"2025-11-02T15:14:09.000Z","size":316,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-02T17:20:44.088Z","etag":null,"topics":["exchange-api","exchange-server","perps-dex","perps-trading","vibe-coding","vibecoding"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lugondev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-02T15:11:09.000Z","updated_at":"2025-11-02T15:18:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lugondev/trade-perps-api","commit_stats":null,"previous_names":["lugondev/trade-perps-api"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/lugondev/trade-perps-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lugondev%2Ftrade-perps-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lugondev%2Ftrade-perps-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lugondev%2Ftrade-perps-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lugondev%2Ftrade-perps-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lugondev","download_url":"https://codeload.github.com/lugondev/trade-perps-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lugondev%2Ftrade-perps-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28476668,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T00:15:39.755Z","status":"online","status_checked_at":"2026-01-16T02:00:07.781Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["exchange-api","exchange-server","perps-dex","perps-trading","vibe-coding","vibecoding"],"created_at":"2026-01-16T03:01:08.972Z","updated_at":"2026-01-16T03:01:09.875Z","avatar_url":"https://github.com/lugondev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Perps Vibe AI - Multi-Exchange Perpetual Futures Trading Platform\n\nA sophisticated NestJS-based trading platform with **Unified API Architecture** supporting multiple perpetual futures exchanges including Aster DEX, Hyperliquid, Binance Futures, and OKX Perpetuals.\n\n## 🎯 Architecture Highlights\n\n- ✅ **Unified API**: Single set of endpoints serving all exchanges\n- ✅ **Factory Pattern**: Dynamic service resolution at runtime via Exchange Factory\n- ✅ **Interface-Driven**: Clean separation between interfaces and implementations\n- ✅ **Type-Safe**: Full TypeScript with strict mode enabled\n- ✅ **Modular Design**: Each exchange is a self-contained module\n- ✅ **Plug \u0026 Play**: Add new exchanges by implementing standard interfaces\n\n## 🏢 Supported Exchanges\n\n- ✅ **Aster DEX**: Decentralized perpetual futures (with WebSocket support)\n- ✅ **Hyperliquid**: On-chain perpetual futures (with WebSocket support)\n- ✅ **Binance Futures**: Centralized perpetual futures\n- ✅ **OKX Perpetuals**: Centralized perpetual futures\n\n## 💡 Core Features\n\n- ✅ **Trading Operations**: Market/limit orders, position management, leverage control\n- ✅ **Risk Management**: Stop-loss, take-profit, margin management\n- ✅ **Balance \u0026 Portfolio**: Real-time balance tracking, P\u0026L calculation, portfolio value\n- ✅ **Market Data**: Real-time prices, orderbook depth, historical candles, funding rates\n- ✅ **Symbol Normalization**: Automatic symbol format conversion across exchanges\n\n## 🔧 Technical Features\n\n- ✅ **REST API**: Comprehensive Swagger documentation at `/api`\n- ✅ **WebSocket Support**: Real-time market data and account updates\n- ✅ **Authentication**: API Key guard for secure access\n- ✅ **Error Handling**: Standardized error responses\n- ✅ **Clean Architecture**: Modular, testable, maintainable codebase\n\n## 📦 Quick Start\n\n### 1. Installation\n\n```bash\n# Install dependencies\npnpm install\n```\n\n### 2. Configuration\n\nCreate a `.env` file in the root directory with your exchange API credentials:\n\n```env\n# Application Settings\nNODE_ENV=development\nPORT=3000\nLOG_LEVEL=debug\n\n# API Access Control (REQUIRED!)\n# This key protects all endpoints\nAPI_KEY_ACCESS=your_secure_api_key_here\n\n# Aster DEX Configuration\nASTER_API_KEY=your_aster_api_key\nASTER_API_SECRET=your_aster_api_secret\nASTER_USER_ADDRESS=your_wallet_address\nASTER_SIGNER_ADDRESS=your_signer_address\nASTER_PRIVATE_KEY=your_private_key\nASTER_REST_URL=https://fapi.asterdex.com\nASTER_WS_URL=wss://fstream.asterdex.com\n\n# Hyperliquid Configuration\nHYPERLIQUID_REST_URL=https://api.hyperliquid.xyz\nHYPERLIQUID_WS_URL=wss://api.hyperliquid.xyz/ws\nHYPERLIQUID_WALLET_ADDRESS=your_wallet_address\nHYPERLIQUID_PRIVATE_KEY=your_private_key\nHYPERLIQUID_TESTNET=false\n\n# Binance Futures Configuration (Optional)\nBINANCE_API_KEY=your_binance_api_key\nBINANCE_API_SECRET=your_binance_api_secret\nBINANCE_REST_URL=https://fapi.binance.com\nBINANCE_TESTNET=false\n\n# OKX Perpetuals Configuration (Optional)\nOKX_API_KEY=your_okx_api_key\nOKX_API_SECRET=your_okx_api_secret\nOKX_PASSPHRASE=your_okx_passphrase\nOKX_REST_URL=https://www.okx.com\nOKX_TESTNET=false\n```\n\n**Security Note:** The `API_KEY_ACCESS` is required in the `X-API-Key` header for all requests to protected endpoints.\n\n### 3. Start the Application\n\n```bash\n# Development mode with hot reload\npnpm start:dev\n\n# Production mode\npnpm build\npnpm start:prod\n```\n\nThe application will be available at:\n\n- **API**: \u003chttp://localhost:3000\u003e\n- **Swagger Documentation**: \u003chttp://localhost:3000/api\u003e\n\n## 🔐 API Authentication\n\nAll trading endpoints require API key authentication using the `X-API-Key` header.\n\n**Required Header:**\n\n```http\nX-API-Key: your_api_key_access_here\n```\n\n### Using Swagger UI\n\n1. Open \u003chttp://localhost:3000/api\u003e\n2. Click the **\"Authorize\"** button (lock icon) at the top\n3. Enter your `API_KEY_ACCESS` from `.env` file\n4. Click **\"Authorize\"** and **\"Close\"**\n5. Now you can test all endpoints directly in the browser\n\n### Using curl\n\n```bash\ncurl -H \"X-API-Key: your_api_key_access_here\" \\\n  http://localhost:3000/balance?exchange=aster\n```\n\n## 📡 Unified API Endpoints\n\nAll endpoints follow a unified pattern: `/{resource}?exchange={exchange_name}`\n\n### Balance Endpoints\n\n- `GET /balance?exchange={exchange}` - Get account balance and positions\n- `GET /balance/portfolio?exchange={exchange}` - Get portfolio summary\n- `GET /balance/positions?exchange={exchange}` - Get all open positions\n- `GET /balance/position?exchange={exchange}\u0026symbol={symbol}` - Get specific position\n\n**Example:**\n\n```bash\n# Get Aster balance\ncurl -H \"X-API-Key: your_key\" \\\n  \"http://localhost:3000/balance?exchange=aster\"\n\n# Get Hyperliquid positions\ncurl -H \"X-API-Key: your_key\" \\\n  \"http://localhost:3000/balance/positions?exchange=hyperliquid\"\n```\n\n### Market Data Endpoints\n\n- `GET /market/symbols?exchange={exchange}` - Get all tradable symbols\n- `GET /market/ticker?exchange={exchange}\u0026symbol={symbol}` - Get 24hr ticker\n- `GET /market/orderbook?exchange={exchange}\u0026symbol={symbol}` - Get order book\n- `GET /market/trades?exchange={exchange}\u0026symbol={symbol}` - Get recent trades\n- `GET /market/candles?exchange={exchange}\u0026symbol={symbol}\u0026interval={interval}` - Get klines/candles\n- `GET /market/funding?exchange={exchange}\u0026symbol={symbol}` - Get funding rate history\n\n**Example:**\n\n```bash\n# Get BTC ticker from Binance\ncurl -H \"X-API-Key: your_key\" \\\n  \"http://localhost:3000/market/ticker?exchange=binance\u0026symbol=BTC-USDT\"\n\n# Get ETH orderbook from Hyperliquid\ncurl -H \"X-API-Key: your_key\" \\\n  \"http://localhost:3000/market/orderbook?exchange=hyperliquid\u0026symbol=ETH-USD\"\n```\n\n### Trading Endpoints\n\n- `POST /trading/order/market` - Place market order\n- `POST /trading/order/limit` - Place limit order\n- `POST /trading/order/cancel` - Cancel order\n- `POST /trading/order/cancel-all` - Cancel all orders\n- `GET /trading/orders?exchange={exchange}` - Get open orders\n- `POST /trading/leverage` - Set leverage\n- `POST /trading/position/close` - Close position\n\n**Market Order Example:**\n\n```bash\ncurl -X POST -H \"X-API-Key: your_key\" \\\n  -H \"Content-Type: application/json\" \\\n  \"http://localhost:3000/trading/order/market\" \\\n  -d '{\n    \"exchange\": \"aster\",\n    \"symbol\": \"BTC-USDT\",\n    \"side\": \"BUY\",\n    \"quantity\": 0.001\n  }'\n```\n\n**Limit Order Example:**\n\n```bash\ncurl -X POST -H \"X-API-Key: your_key\" \\\n  -H \"Content-Type: application/json\" \\\n  \"http://localhost:3000/trading/order/limit\" \\\n  -d '{\n    \"exchange\": \"hyperliquid\",\n    \"symbol\": \"ETH-USD\",\n    \"side\": \"SELL\",\n    \"quantity\": 0.1,\n    \"price\": 3500\n  }'\n```\n\n**Close Position Example:**\n\n```bash\ncurl -X POST -H \"X-API-Key: your_key\" \\\n  -H \"Content-Type: application/json\" \\\n  \"http://localhost:3000/trading/position/close\" \\\n  -d '{\n    \"exchange\": \"binance\",\n    \"symbol\": \"BTC-USDT\"\n  }'\n```\n\n## 🏗️ Project Structure\n\n```text\nsrc/\n├── api/                          # Unified API Layer\n│   ├── controllers/              # REST API Controllers\n│   │   ├── balance.controller.ts    # Balance \u0026 portfolio endpoints\n│   │   ├── market.controller.ts     # Market data endpoints\n│   │   └── trading.controller.ts    # Trading endpoints\n│   └── api.module.ts             # API module configuration\n│\n├── common/                       # Shared Utilities\n│   ├── decorators/               # Custom decorators\n│   │   ├── api-key.decorator.ts     # API key extraction\n│   │   └── public.decorator.ts      # Public endpoint marker\n│   ├── dto/                      # Data Transfer Objects\n│   │   ├── exchange.dto.ts          # Exchange selection DTOs\n│   │   └── trading.dto.ts           # Trading operation DTOs\n│   ├── factory/                  # Factory Pattern\n│   │   └── exchange.factory.ts      # Dynamic service resolution\n│   ├── guards/                   # Authentication Guards\n│   │   └── api-key.guard.ts         # API key validation\n│   ├── interfaces/               # Standard Interfaces\n│   │   ├── balance.interface.ts     # Balance operations\n│   │   ├── market.interface.ts      # Market data operations\n│   │   └── trading.interface.ts     # Trading operations\n│   ├── middleware/               # HTTP Middleware\n│   │   └── symbol-normalizer.middleware.ts  # Symbol format conversion\n│   ├── services/                 # Common Services\n│   │   └── symbol-normalizer.service.ts     # Symbol normalization logic\n│   └── types/                    # Type Definitions\n│       └── exchange.types.ts        # Exchange enums and types\n│\n├── exchanges/                    # Exchange Integrations\n│   ├── aster/                    # Aster DEX\n│   │   ├── perpetual/\n│   │   │   ├── services/\n│   │   │   │   ├── perpetual-balance.service.ts\n│   │   │   │   ├── perpetual-market.service.ts\n│   │   │   │   └── perpetual-trading.service.ts\n│   │   │   └── perpetual.module.ts\n│   │   ├── shared/\n│   │   │   ├── aster-api.service.ts      # REST API client\n│   │   │   └── aster-websocket.service.ts # WebSocket client\n│   │   ├── types/                         # Type definitions\n│   │   └── aster.module.ts\n│   │\n│   ├── hyperliquid/              # Hyperliquid\n│   │   ├── perp/\n│   │   │   ├── services/\n│   │   │   │   ├── balance.service.ts\n│   │   │   │   ├── market-data.service.ts\n│   │   │   │   ├── order-management.service.ts\n│   │   │   │   └── order-placement.service.ts\n│   │   │   └── perp.module.ts\n│   │   ├── shared/\n│   │   │   ├── hyperliquid-api.service.ts # REST API client\n│   │   │   └── signing.service.ts         # Signature generation\n│   │   ├── types/\n│   │   └── hyperliquid.module.ts\n│   │\n│   ├── binance/                  # Binance Futures\n│   │   ├── perpetual/\n│   │   │   ├── services/\n│   │   │   │   ├── perpetual-balance.service.ts\n│   │   │   │   ├── perpetual-market.service.ts\n│   │   │   │   └── perpetual-trading.service.ts\n│   │   │   └── perpetual.module.ts\n│   │   ├── shared/\n│   │   │   └── binance-api.service.ts\n│   │   ├── types/\n│   │   └── binance.module.ts\n│   │\n│   ├── okx/                      # OKX Perpetuals\n│   │   ├── perpetual/\n│   │   │   ├── services/\n│   │   │   │   ├── perpetual-balance.service.ts\n│   │   │   │   ├── perpetual-market.service.ts\n│   │   │   │   └── perpetual-trading.service.ts\n│   │   │   └── perpetual.module.ts\n│   │   ├── shared/\n│   │   │   └── okx-api.service.ts\n│   │   ├── types/\n│   │   └── okx.module.ts\n│   │\n│   └── exchanges.module.ts       # Exchanges module aggregator\n│\n├── config/                       # Configuration Files\n│   ├── app.config.ts             # App settings\n│   ├── aster.config.ts           # Aster configuration\n│   ├── binance.config.ts         # Binance configuration\n│   ├── hyperliquid.config.ts     # Hyperliquid configuration\n│   ├── okx.config.ts             # OKX configuration\n│   └── trading.config.ts         # Trading settings\n│\n├── app.module.ts                 # Root module\n└── main.ts                       # Application entry point\n```\n\n## 🔌 Architecture Overview\n\n### Unified API Pattern\n\nInstead of separate endpoints per exchange, we use a unified pattern:\n\n```text\nTraditional Approach (Bad):\n- /aster/balance\n- /hyperliquid/balance\n- /binance/balance\n- /okx/balance\n→ 4 exchanges × 50 operations = 200 endpoints!\n\nUnified Approach (Good):\n- /balance?exchange=aster\n- /balance?exchange=hyperliquid\n- /balance?exchange=binance\n- /balance?exchange=okx\n→ 50 endpoints serving all exchanges\n```\n\n### Exchange Factory Pattern\n\nThe `ExchangeFactory` dynamically resolves the correct service based on the exchange parameter:\n\n```typescript\n// Client request\nGET /balance?exchange=aster\n\n// Factory resolves\nExchangeFactory → AsterPerpetualBalanceService → Execute\n\n// Client request\nGET /balance?exchange=hyperliquid\n\n// Factory resolves\nExchangeFactory → HyperliquidBalanceService → Execute\n```\n\n### Interface-Driven Design\n\nAll exchange implementations follow standard interfaces:\n\n- `IBalanceService`: Balance and portfolio operations\n- `IMarketDataService`: Market data operations\n- `ITradingService`: Trading operations\n\nThis ensures:\n\n- **Consistency**: All exchanges work the same way\n- **Testability**: Easy to mock and test\n- **Maintainability**: Changes in one place affect all exchanges\n- **Extensibility**: New exchanges just implement interfaces\n\n### Symbol Normalization\n\nEach exchange uses different symbol formats:\n\n- Aster: `BTCUSDT`\n- Hyperliquid: `BTC`\n- Binance: `BTCUSDT`\n- OKX: `BTC-USDT-SWAP`\n\nThe `SymbolNormalizerMiddleware` automatically converts symbols:\n\n```text\nClient → \"BTC-USDT\" → Middleware → \"BTCUSDT\" (Aster)\nClient → \"BTC-USDT\" → Middleware → \"BTC\" (Hyperliquid)\nClient → \"BTC-USDT\" → Middleware → \"BTC-USDT-SWAP\" (OKX)\n```\n\n## ⚙️ Configuration\n\n### Environment Variables\n\n| Variable         | Description                         | Required | Default       |\n| ---------------- | ----------------------------------- | -------- | ------------- |\n| `API_KEY_ACCESS` | API key for endpoint authentication | Yes      | -             |\n| `PORT`           | Application port                    | No       | `3000`        |\n| `NODE_ENV`       | Environment mode                    | No       | `development` |\n| `LOG_LEVEL`      | Logging level                       | No       | `debug`       |\n\n**Aster DEX:**\n\n| Variable               | Description      | Required |\n| ---------------------- | ---------------- | -------- |\n| `ASTER_API_KEY`        | Aster API key    | Yes      |\n| `ASTER_API_SECRET`     | Aster API secret | Yes      |\n| `ASTER_USER_ADDRESS`   | Wallet address   | Yes      |\n| `ASTER_SIGNER_ADDRESS` | Signer address   | Yes      |\n| `ASTER_PRIVATE_KEY`    | Private key      | Yes      |\n| `ASTER_REST_URL`       | REST API URL     | No       |\n| `ASTER_WS_URL`         | WebSocket URL    | No       |\n\n**Hyperliquid:**\n\n| Variable                     | Description    | Required |\n| ---------------------------- | -------------- | -------- |\n| `HYPERLIQUID_WALLET_ADDRESS` | Wallet address | Yes      |\n| `HYPERLIQUID_PRIVATE_KEY`    | Private key    | Yes      |\n| `HYPERLIQUID_REST_URL`       | REST API URL   | No       |\n| `HYPERLIQUID_WS_URL`         | WebSocket URL  | No       |\n| `HYPERLIQUID_TESTNET`        | Use testnet    | No       |\n\n**Binance Futures:**\n\n| Variable             | Description        | Required |\n| -------------------- | ------------------ | -------- |\n| `BINANCE_API_KEY`    | Binance API key    | Yes      |\n| `BINANCE_API_SECRET` | Binance API secret | Yes      |\n| `BINANCE_REST_URL`   | REST API URL       | No       |\n| `BINANCE_TESTNET`    | Use testnet        | No       |\n\n**OKX Perpetuals:**\n\n| Variable         | Description    | Required |\n| ---------------- | -------------- | -------- |\n| `OKX_API_KEY`    | OKX API key    | Yes      |\n| `OKX_API_SECRET` | OKX API secret | Yes      |\n| `OKX_PASSPHRASE` | OKX passphrase | Yes      |\n| `OKX_REST_URL`   | REST API URL   | No       |\n| `OKX_TESTNET`    | Use testnet    | No       |\n\n## 🧪 Development\n\n### Available Scripts\n\n```bash\n# Development\npnpm start:dev          # Start with hot reload\npnpm build              # Build for production\npnpm start:prod         # Start production build\n\n# Testing\npnpm test               # Run unit tests\npnpm test:watch         # Run tests in watch mode\npnpm test:cov           # Generate coverage report\npnpm test:e2e           # Run end-to-end tests\n\n# Code Quality\npnpm lint               # Run ESLint\npnpm format             # Format code with Prettier\n```\n\n### Adding a New Exchange\n\nTo add support for a new exchange:\n\n1. **Create exchange module structure:**\n\n   ```bash\n   mkdir -p src/exchanges/newexchange/perpetual/services\n   mkdir -p src/exchanges/newexchange/shared\n   mkdir -p src/exchanges/newexchange/types\n   ```\n\n2. **Implement standard interfaces:**\n\n   Create services implementing:\n   - `IBalanceService` (balance operations)\n   - `IMarketDataService` (market data)\n   - `ITradingService` (trading operations)\n\n3. **Create API service:**\n\n   Implement REST API client in `shared/newexchange-api.service.ts`\n\n4. **Define types:**\n\n   Add exchange-specific types in `types/index.ts`\n\n5. **Create configuration:**\n\n   Add config in `src/config/newexchange.config.ts`\n\n6. **Register in factory:**\n\n   Add exchange to `ExchangeFactory` resolution logic\n\n7. **Update exchange enum:**\n\n   Add to `ExchangeName` enum in `common/types/exchange.types.ts`\n\n8. **Test thoroughly:**\n\n   Create unit tests for all services\n\n## 🔒 Security Features\n\n- **Environment Variables**: Sensitive data stored securely in `.env`\n- **API Key Authentication**: All endpoints protected with API key guard\n- **HMAC Signatures**: Secure API authentication for supported exchanges\n- **Input Validation**: Comprehensive validation using class-validator\n- **Rate Limiting**: Built-in protection against API rate limits\n- **Error Sanitization**: Sensitive information removed from logs\n\n## 📊 Monitoring \u0026 Logging\n\nThe application uses structured logging with contextual information:\n\n- **Error**: System errors and critical failures\n- **Warn**: Non-critical issues and warnings\n- **Info**: General application information\n- **Debug**: Detailed debugging information (set `LOG_LEVEL=debug`)\n\nLogs include request IDs, exchange names, and operation metadata for easy troubleshooting.\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n**Connection Failed:**\n\n- Verify API credentials in `.env` file\n- Check network connectivity\n- Ensure exchange API is accessible\n\n**Invalid Signature:**\n\n- Verify API secret is correct\n- Check system time synchronization\n- Ensure timestamp is within acceptable range\n\n**Rate Limited:**\n\n- Reduce request frequency\n- Implement exponential backoff\n- Check exchange rate limit documentation\n\n**Symbol Not Found:**\n\n- Verify symbol format for the specific exchange\n- Check if symbol is supported by the exchange\n- Use `/market/symbols` endpoint to list available symbols\n\n### Debug Mode\n\nEnable detailed logging:\n\n```bash\nLOG_LEVEL=debug pnpm start:dev\n```\n\n## 📝 API Response Format\n\nAll API responses follow a standardized format:\n\n**Success Response:**\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    // Response data here\n  },\n  \"timestamp\": \"2024-01-01T00:00:00.000Z\"\n}\n```\n\n**Error Response:**\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"ERROR_CODE\",\n    \"message\": \"Error description\",\n    \"details\": {}\n  },\n  \"timestamp\": \"2024-01-01T00:00:00.000Z\"\n}\n```\n\n## 🚀 Deployment\n\n### Docker Deployment\n\n```bash\n# Build image\ndocker build -t perps-vibe-ai .\n\n# Run container\ndocker run -d \\\n  --name perps-vibe-ai \\\n  -p 3000:3000 \\\n  --env-file .env \\\n  perps-vibe-ai\n```\n\n### Cloud Run Deployment\n\n```bash\n# Deploy to Google Cloud Run\n./scripts/deploy-cloudrun.sh\n```\n\n## 📚 Documentation\n\nFor detailed documentation, see the `.docs` folder:\n\n- Architecture guides\n- API authentication details\n- Exchange-specific documentation\n- Trading strategies\n- WebSocket integration guides\n\n## 🤝 Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Implement your changes\n4. Add tests for new features\n5. Submit a pull request\n\n## 📄 License\n\nMIT License - see LICENSE file for details.\n\n## ⚠️ Disclaimer\n\n**Important:** This is a trading platform that can place real orders and spend real money. Always:\n\n- Test thoroughly in testnet/sandbox environments\n- Start with small amounts\n- Implement proper risk management\n- Monitor positions actively\n- Use at your own risk\n\nThe developers are not responsible for any financial losses incurred while using this platform.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flugondev%2Ftrade-perps-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flugondev%2Ftrade-perps-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flugondev%2Ftrade-perps-api/lists"}