## File: docs/getting-started/aster-api-wallet.md

# Aster DEX API Wallet Setup Guide

This guide explains how to create and configure an API Wallet for secure trading on Aster DEX.

## Why Use API Wallet?

- ✅ **Binance-compatible API**: Easy migration from Binance
- ✅ **Separate Trading Wallet**: Enhanced security
- ✅ **Revocable Access**: Can be disabled anytime
- ✅ **Lower Fees**: Competitive trading fees

## Prerequisites

- A Web3 wallet (MetaMask, WalletConnect, etc.)
- Funds on supported EVM chain (Ethereum, BSC, Polygon, etc.)

## Step 1: Register on Aster DEX

1. Visit [Aster DEX](https://www.asterdex.com/en/referral/fdfc0e) (use referral link for fee discount)
2. Connect your Web3 wallet
3. Complete any required verification

## Step 2: Create API Wallet

1. Go to [Aster API Wallet](https://www.asterdex.com/en/api-wallet)
2. Connect your main wallet
3. Click **Create API Wallet**
4. Approve the transaction in your wallet

## Step 3: Save API Wallet Credentials

After creation, save these **immediately**:

| Field | Description |
|-------|-------------|
| **User Address** | Your main wallet address |
| **Signer Address** | API wallet address |
| **Private Key** | API wallet private key |

⚠️ **Important**: The private key is only shown once! Save it securely.

## Step 4: Configure in NOFX

Add your API wallet through the NOFX web interface:

1. Open NOFX dashboard (http://localhost:3000)
2. Go to **Exchange Configuration**
3. Enable **Aster DEX**
4. Enter:
   - **User**: Your main wallet address (with `0x`)
   - **Signer**: API wallet address (with `0x`)
   - **Private Key**: API wallet private key (remove `0x` prefix)
5. Save configuration

## Configuration Example

```
User:        0xYOUR_MAIN_WALLET_ADDRESS
Signer:      0xYOUR_API_WALLET_SIGNER_ADDRESS
Private Key: your_api_wallet_private_key_without_0x
```

## Fund Your Account

1. Deposit supported assets to Aster DEX
2. Transfer to your trading account
3. API wallet will trade using these funds

## Managing Your API Wallet

### Revoke Access

1. Go to [Aster API Wallet](https://www.asterdex.com/en/api-wallet)
2. Find your API wallet
3. Click **Revoke** or **Delete**

### Create New API Wallet

You can create multiple API wallets:
- Delete old wallet first (recommended)
- Or create additional wallet for different purposes

## Security Best Practices

- Never share your API wallet private key
- Store credentials in a secure password manager
- Revoke access when not in use
- Use separate wallets for different applications
- Monitor API wallet activity regularly

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Authentication failed | Verify User, Signer, and Private Key are correct |
| Invalid signature | Ensure private key doesn't have `0x` prefix |
| Insufficient balance | Deposit funds to Aster DEX |
| API wallet not found | Create new API wallet at asterdex.com |

## Supported Chains

Aster DEX supports multiple EVM chains:
- Ethereum Mainnet
- BNB Smart Chain (BSC)
- Polygon
- And more...

Select your preferred chain when depositing funds.

---

## File: docs/getting-started/binance-api.md

# Binance API Setup Guide

This guide explains how to create and configure Binance API keys for use with NOFX.

## Create API Key

1. Log in to your [Binance account](https://www.binance.com)
2. Go to **Account** → **API Management**
3. Click **Create API**
4. Select **System Generated** API key type
5. Complete 2FA verification
6. Name your API key (e.g., "NOFX Trading")

## Configure API Permissions

Enable the following permissions:

- ✅ **Enable Reading** - Required
- ✅ **Enable Futures** - Required for trading
- ❌ **Enable Withdrawals** - Keep disabled for security

## IP Whitelist (Recommended)

For enhanced security:

1. Click **Edit restrictions**
2. Select **Restrict access to trusted IPs only**
3. Add your server's IP address
4. Save changes

## Save Your Keys

After creation, you'll see:
- **API Key**: `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
- **Secret Key**: `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`

⚠️ **Important**: Save the Secret Key immediately - it's only shown once!

## Configure in NOFX

Add your API credentials through the NOFX web interface:

1. Open NOFX dashboard (http://localhost:3000)
2. Go to **Exchange Configuration**
3. Enable **Binance**
4. Enter your API Key and Secret Key
5. Save configuration

## Troubleshooting

| Error | Solution |
|-------|----------|
| `Invalid API-key` | Check if API key is correct |
| `Signature verification failed` | Check if Secret key is correct |
| `IP not whitelisted` | Add your IP to whitelist or disable IP restriction |
| `Futures not enabled` | Enable Futures permission in API settings |

## Security Best Practices

- Never share your API keys
- Use IP whitelisting
- Don't enable withdrawal permissions
- Create separate API keys for different applications
- Regularly rotate your API keys

---

## File: docs/getting-started/bybit-api.md

# Bybit API Setup Guide

This guide explains how to create and configure Bybit API keys for use with NOFX.

## Create API Key

1. Log in to your [Bybit account](https://partner.bybit.com/b/83856)
2. Go to **Account & Security** → **API Management**
3. Click **Create New Key**
4. Select **System-generated API Keys**
5. Complete 2FA verification
6. Name your API key (e.g., "NOFX Trading")

## Configure API Permissions

Enable the following permissions:

- ✅ **Read-Write** - Required for trading
- ✅ **Contract** - Required for futures/perpetual trading
- ❌ **Withdrawals** - Keep disabled for security

## IP Whitelist (Recommended)

For enhanced security:

1. Click **Edit** on your API key
2. Add your server's IP address to the whitelist
3. Save changes

## Save Your Keys

After creation, you'll see:
- **API Key**: `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
- **API Secret**: `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`

⚠️ **Important**: Save the API Secret immediately - it's only shown once!

## Configure in NOFX

Add your API credentials through the NOFX web interface:

1. Open NOFX dashboard (http://localhost:3000)
2. Go to **Exchange Configuration**
3. Enable **Bybit**
4. Enter your API Key and API Secret
5. Save configuration

## Troubleshooting

| Error | Solution |
|-------|----------|
| `Invalid API key` | Check if API key is correct |
| `Signature error` | Check if API Secret is correct |
| `IP not allowed` | Add your IP to whitelist |
| `Permission denied` | Enable Contract trading permission |

## Security Best Practices

- Never share your API keys
- Use IP whitelisting
- Don't enable withdrawal permissions
- Create separate API keys for different applications
- Regularly rotate your API keys

---

## File: docs/getting-started/custom-api.en.md

# Custom AI API Usage Guide

## Features

NOFX now supports using any OpenAI-compatible API format, including:
- OpenAI official API (gpt-4o, gpt-4-turbo, etc.)
- OpenRouter (access to multiple models)
- Locally deployed models (Ollama, LM Studio, etc.)
- Other OpenAI-compatible API services

## Configuration Method

~~Add trader using custom API in `config.json` (deprecated):~~

*Note: Custom APIs and traders are now configured through the Web interface. config.json only retains basic settings.*

```json
{
  "traders": [
    {
      "id": "trader_custom",
      "name": "My Custom AI Trader",
      "ai_model": "custom",
      "exchange": "binance",

      "binance_api_key": "your_binance_api_key",
      "binance_secret_key": "your_binance_secret_key",

      "custom_api_url": "https://api.openai.com/v1",
      "custom_api_key": "sk-your-openai-api-key",
      "custom_model_name": "gpt-4o",

      "initial_balance": 1000,
      "scan_interval_minutes": 3
    }
  ]
}
```

## Configuration Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `ai_model` | string | ✅ | Set to `"custom"` to enable custom API |
| `custom_api_url` | string | ✅ | API Base URL (without `/chat/completions`). Special usage: If ending with `#`, use full URL (no auto path append) |
| `custom_api_key` | string | ✅ | API key |
| `custom_model_name` | string | ✅ | Model name (e.g. `gpt-4o`, `claude-3-5-sonnet`, etc.) |

## Usage Examples

### 1. OpenAI Official API

```json
{
  "ai_model": "custom",
  "custom_api_url": "https://api.openai.com/v1",
  "custom_api_key": "sk-proj-xxxxx",
  "custom_model_name": "gpt-4o"
}
```

### 2. OpenRouter

```json
{
  "ai_model": "custom",
  "custom_api_url": "https://openrouter.ai/api/v1",
  "custom_api_key": "sk-or-xxxxx",
  "custom_model_name": "anthropic/claude-3.5-sonnet"
}
```

### 3. Local Ollama

```json
{
  "ai_model": "custom",
  "custom_api_url": "http://localhost:11434/v1",
  "custom_api_key": "ollama",
  "custom_model_name": "llama3.1:70b"
}
```

### 4. Azure OpenAI

```json
{
  "ai_model": "custom",
  "custom_api_url": "https://your-resource.openai.azure.com/openai/deployments/your-deployment",
  "custom_api_key": "your-azure-api-key",
  "custom_model_name": "gpt-4"
}
```

### 5. Using Full Custom Path (append #)

For certain special API endpoints that already include the full path (including `/chat/completions` or other custom paths), you can append `#` at the end of the URL to force using the full URL:

```json
{
  "ai_model": "custom",
  "custom_api_url": "https://api.example.com/v2/ai/chat/completions#",
  "custom_api_key": "your-api-key",
  "custom_model_name": "custom-model"
}
```

**Note**: The `#` will be automatically removed, and the actual request will be sent to `https://api.example.com/v2/ai/chat/completions`

## Compatibility Requirements

Custom APIs must:
1. Support OpenAI Chat Completions format
2. Accept `POST` requests to `/chat/completions` endpoint (or append `#` at URL end for custom path)
3. Support `Authorization: Bearer {api_key}` authentication
4. Return standard OpenAI response format

## Important Notes

1. **URL Format**: `custom_api_url` should be the Base URL, system will auto-append `/chat/completions`
   - ✅ Correct: `https://api.openai.com/v1`
   - ❌ Wrong: `https://api.openai.com/v1/chat/completions`
   - 🔧 **Special usage**: If you need to use a full custom path (without auto-appending `/chat/completions`), append `#` at the URL end
     - Example: `https://api.example.com/custom/path/chat/completions#`
     - System will automatically remove `#` and use the full URL directly

2. **Model Name**: Ensure `custom_model_name` exactly matches the model name supported by your API provider

3. **API Key**: Some locally deployed models may not require a real API key, you can fill in any string

4. **Timeout Settings**: Default timeout is 120 seconds, may need adjustment if model response is slow

## Multi-AI Comparison Trading

You can configure multiple traders with different AIs for comparison:

```json
{
  "traders": [
    {
      "id": "deepseek_trader",
      "ai_model": "deepseek",
      "deepseek_key": "sk-xxxxx",
      ...
    },
    {
      "id": "gpt4_trader",
      "ai_model": "custom",
      "custom_api_url": "https://api.openai.com/v1",
      "custom_api_key": "sk-xxxxx",
      "custom_model_name": "gpt-4o",
      ...
    },
    {
      "id": "claude_trader",
      "ai_model": "custom",
      "custom_api_url": "https://openrouter.ai/api/v1",
      "custom_api_key": "sk-or-xxxxx",
      "custom_model_name": "anthropic/claude-3.5-sonnet",
      ...
    }
  ]
}
```

## Troubleshooting

### Issue: Configuration Validation Failed

**Error Message**: `使用自定义API时必须配置custom_api_url` (custom_api_url must be configured when using custom API)

**Solution**: After setting `ai_model: "custom"`, ensure you also configure:
- `custom_api_url`
- `custom_api_key`
- `custom_model_name`

### Issue: API Call Failed

**Possible Causes**:
1. URL format error
   - Normal usage: Should not include `/chat/completions` (system will auto-append)
   - Special usage: If full path is needed, remember to append `#` at URL end
2. Invalid API key
3. Incorrect model name
4. Network connection issues

**Debug Method**: Check error messages in logs, usually includes HTTP status code and error details

## Backward Compatibility

Existing `deepseek` and `qwen` configurations are unaffected and can continue to be used:

```json
{
  "ai_model": "deepseek",
  "deepseek_key": "sk-xxxxx"
}
```

Or

```json
{
  "ai_model": "qwen",
  "qwen_key": "sk-xxxxx"
}
```

---

## File: docs/getting-started/custom-api.md

# 自定义 AI API 使用指南

## 功能说明

现在 NOFX 支持使用任何 OpenAI 格式兼容的 API，包括：
- OpenAI 官方 API (gpt-4o, gpt-4-turbo 等)
- OpenRouter (可访问多种模型)
- 本地部署的模型 (Ollama, LM Studio 等)
- 其他兼容 OpenAI 格式的 API 服务

## 配置方式

在 `config.json` 中添加使用自定义 API 的 trader（~~已弃用~~）：

*注意：现在通过Web界面配置自定义API和交易员，config.json仅保留基础设置*

```json
{
  "traders": [
    {
      "id": "trader_custom",
      "name": "My Custom AI Trader",
      "ai_model": "custom",
      "exchange": "binance",

      "binance_api_key": "your_binance_api_key",
      "binance_secret_key": "your_binance_secret_key",

      "custom_api_url": "https://api.openai.com/v1",
      "custom_api_key": "sk-your-openai-api-key",
      "custom_model_name": "gpt-4o",

      "initial_balance": 1000,
      "scan_interval_minutes": 3
    }
  ]
}
```

## 配置字段说明

| 字段 | 类型 | 必需 | 说明 |
|-----|------|------|------|
| `ai_model` | string | ✅ | 设置为 `"custom"` 启用自定义 API |
| `custom_api_url` | string | ✅ | API 的 Base URL (不含 `/chat/completions`)。特殊用法：如果以 `#` 结尾，则使用完整 URL（不自动添加路径） |
| `custom_api_key` | string | ✅ | API 密钥 |
| `custom_model_name` | string | ✅ | 模型名称 (如 `gpt-4o`, `claude-3-5-sonnet` 等) |

## 使用示例

### 1. OpenAI 官方 API

```json
{
  "ai_model": "custom",
  "custom_api_url": "https://api.openai.com/v1",
  "custom_api_key": "sk-proj-xxxxx",
  "custom_model_name": "gpt-4o"
}
```

### 2. OpenRouter

```json
{
  "ai_model": "custom",
  "custom_api_url": "https://openrouter.ai/api/v1",
  "custom_api_key": "sk-or-xxxxx",
  "custom_model_name": "anthropic/claude-3.5-sonnet"
}
```

### 3. 本地 Ollama

```json
{
  "ai_model": "custom",
  "custom_api_url": "http://localhost:11434/v1",
  "custom_api_key": "ollama",
  "custom_model_name": "llama3.1:70b"
}
```

### 4. Azure OpenAI

```json
{
  "ai_model": "custom",
  "custom_api_url": "https://your-resource.openai.azure.com/openai/deployments/your-deployment",
  "custom_api_key": "your-azure-api-key",
  "custom_model_name": "gpt-4"
}
```

### 5. 使用完整自定义路径（末尾添加 #）

对于某些特殊的 API 端点，如果已经包含完整路径（包括 `/chat/completions` 或其他自定义路径），可以在 URL 末尾添加 `#` 来强制使用完整 URL：

```json
{
  "ai_model": "custom",
  "custom_api_url": "https://api.example.com/v2/ai/chat/completions#",
  "custom_api_key": "your-api-key",
  "custom_model_name": "custom-model"
}
```

**注意**：`#` 会被自动去除，实际请求会发送到 `https://api.example.com/v2/ai/chat/completions`

## 兼容性要求

自定义 API 必须：
1. 支持 OpenAI Chat Completions 格式
2. 接受 `POST` 请求到 `/chat/completions` 端点（或在 URL 末尾添加 `#` 以使用自定义路径）
3. 支持 `Authorization: Bearer {api_key}` 认证
4. 返回标准的 OpenAI 响应格式

## 注意事项

1. **URL 格式**：`custom_api_url` 应该是 Base URL，系统会自动添加 `/chat/completions`
   - ✅ 正确：`https://api.openai.com/v1`
   - ❌ 错误：`https://api.openai.com/v1/chat/completions`
   - 🔧 **特殊用法**：如果需要使用完整的自定义路径（不自动添加 `/chat/completions`），可以在 URL 末尾添加 `#`
     - 例如：`https://api.example.com/custom/path/chat/completions#`
     - 系统会自动去掉 `#` 并直接使用该完整 URL

2. **模型名称**：确保 `custom_model_name` 与 API 提供商支持的模型名称完全一致

3. **API 密钥**：某些本地部署的模型可能不需要真实的 API 密钥，可以填写任意字符串

4. **超时设置**：默认超时时间为 120 秒，如果模型响应较慢可能需要调整

## 多 AI 对比交易

你可以同时配置多个不同 AI 的 trader 进行对比：

```json
{
  "traders": [
    {
      "id": "deepseek_trader",
      "ai_model": "deepseek",
      "deepseek_key": "sk-xxxxx",
      ...
    },
    {
      "id": "gpt4_trader",
      "ai_model": "custom",
      "custom_api_url": "https://api.openai.com/v1",
      "custom_api_key": "sk-xxxxx",
      "custom_model_name": "gpt-4o",
      ...
    },
    {
      "id": "claude_trader",
      "ai_model": "custom",
      "custom_api_url": "https://openrouter.ai/api/v1",
      "custom_api_key": "sk-or-xxxxx",
      "custom_model_name": "anthropic/claude-3.5-sonnet",
      ...
    }
  ]
}
```

## 故障排除

### 问题：配置验证失败

**错误信息**：`使用自定义API时必须配置custom_api_url`

**解决方案**：确保设置了 `ai_model: "custom"` 后，同时配置了：
- `custom_api_url`
- `custom_api_key`
- `custom_model_name`

### 问题：API 调用失败

**可能原因**：
1. URL 格式错误
   - 普通用法：不应包含 `/chat/completions`（系统会自动添加）
   - 特殊用法：如果需要完整路径，记得在 URL 末尾添加 `#`
2. API 密钥无效
3. 模型名称错误
4. 网络连接问题

**调试方法**：查看日志中的错误信息，通常会包含 HTTP 状态码和错误详情

## 向后兼容性

现有的 `deepseek` 和 `qwen` 配置完全不受影响，可以继续使用：

```json
{
  "ai_model": "deepseek",
  "deepseek_key": "sk-xxxxx"
}
```

或

```json
{
  "ai_model": "qwen",
  "qwen_key": "sk-xxxxx"
}
```

---

## File: docs/getting-started/hyperliquid-agent-wallet.md

# Hyperliquid Agent Wallet Setup Guide

This guide explains how to create and configure an Agent Wallet for secure trading on Hyperliquid.

## Why Use Agent Wallet?

- ✅ **More Secure**: Never expose your main wallet private key
- ✅ **Limited Access**: Agent only has trading permissions
- ✅ **Revocable**: Can be disabled anytime from Hyperliquid interface
- ✅ **Separate Funds**: Keep main holdings safe

## Prerequisites

- A wallet with funds on Hyperliquid
- Access to [Hyperliquid](https://app.hyperliquid.xyz/join/AITRADING)

## Step 1: Connect Your Main Wallet

1. Visit [Hyperliquid](https://app.hyperliquid.xyz/join/AITRADING)
2. Click **Connect Wallet** (top right)
3. Choose MetaMask, WalletConnect, or other Web3 wallet
4. Approve the connection

## Step 2: Create Agent Wallet

1. Click on your wallet address (top right)
2. Go to **Settings** → **API & Agents**
3. Or visit directly: [https://app.hyperliquid.xyz/agents](https://app.hyperliquid.xyz/agents)
4. Click **Create Agent** or **Add Agent**
5. System generates a new agent wallet automatically

## Step 3: Save Agent Credentials

After creation, save these immediately:

- **Agent Wallet Address**: `0x...` (starts with 0x)
- **Agent Private Key**: Shown only once!

⚠️ **Important**: The private key is only displayed once. Save it securely!

## Step 4: Configure in NOFX

Add your agent wallet through the NOFX web interface:

1. Open NOFX dashboard (http://localhost:3000)
2. Go to **Exchange Configuration**
3. Enable **Hyperliquid**
4. Enter:
   - **Wallet Address**: Your main wallet address (with `0x`)
   - **Private Key**: Agent private key (remove `0x` prefix)
5. Save configuration

## Agent Wallet Details

| Field | Description | Example |
|-------|-------------|---------|
| Main Wallet | Your connected wallet (holds funds) | `0xABC123...` |
| Agent Wallet | Sub-wallet for trading | `0xDEF456...` |
| Private Key | Only needed for NOFX | `abc123...` (no 0x) |

## Managing Your Agent

### Revoke Agent Access

1. Go to [Hyperliquid Agents](https://app.hyperliquid.xyz/agents)
2. Find your agent in the list
3. Click **Revoke** or **Delete**

### Create Multiple Agents

You can create multiple agents for different purposes:
- One for NOFX
- One for other trading bots
- One for manual API access

## Security Best Practices

- Use agent wallet instead of main wallet private key
- Store agent private key securely
- Revoke unused agents
- Monitor agent activity regularly
- Keep main wallet funds separate from trading funds

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Agent not working | Check if agent is still active in Hyperliquid settings |
| Invalid signature | Ensure private key doesn't have `0x` prefix |
| Insufficient funds | Transfer funds to your Hyperliquid account |
| Connection error | Check network (mainnet vs testnet) setting |

---

## File: docs/getting-started/lighter-agent-wallet.md

# Lighter Agent Wallet Setup Guide

This guide explains how to create and configure an Agent Wallet for secure trading on Lighter.

## Why Use Agent Wallet?

- ✅ **More Secure**: Never expose your main wallet private key
- ✅ **Limited Access**: Agent only has trading permissions
- ✅ **Revocable**: Can be disabled anytime
- ✅ **Separate Funds**: Keep main holdings safe

## Prerequisites

- A Web3 wallet (MetaMask, WalletConnect, etc.)
- Access to [Lighter](https://lighter.xyz)

## Step 1: Connect Your Main Wallet

1. Visit [Lighter](https://lighter.xyz)
2. Click **Connect Wallet**
3. Choose MetaMask, WalletConnect, or other Web3 wallet
4. Approve the connection

## Step 2: Create Agent Wallet

1. Navigate to **Settings** or **API** section
2. Look for **Agent Wallet** or **Trading Wallet** option
3. Click **Create Agent** or **Generate New Wallet**
4. Approve the transaction if required

## Step 3: Save Agent Credentials

After creation, save these immediately:

| Field | Description |
|-------|-------------|
| **Main Wallet Address** | Your connected wallet address |
| **Agent Wallet Address** | Generated agent wallet address |
| **Agent Private Key** | Private key for the agent wallet |

⚠️ **Important**: The private key is only shown once! Save it securely.

## Step 4: Configure in NOFX

Add your agent wallet through the NOFX web interface:

1. Open NOFX dashboard (http://localhost:3000)
2. Go to **Exchange Configuration**
3. Enable **Lighter**
4. Enter:
   - **Wallet Address**: Your main wallet address (with `0x`)
   - **Private Key**: Agent private key (remove `0x` prefix)
5. Save configuration

## Managing Your Agent

### Revoke Agent Access

1. Go to Lighter Settings
2. Find your agent in the list
3. Click **Revoke** or **Delete**

### Fund Your Account

1. Deposit supported assets to Lighter
2. Agent wallet will trade using deposited funds

## Security Best Practices

- Use agent wallet instead of main wallet private key
- Store agent private key securely
- Revoke unused agents
- Monitor agent activity regularly
- Keep main wallet funds separate from trading funds

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Agent not working | Check if agent is still active |
| Invalid signature | Ensure private key doesn't have `0x` prefix |
| Insufficient funds | Deposit funds to your Lighter account |
| Connection error | Check network settings |

---

## File: docs/getting-started/okx-api.md

# OKX API Setup Guide

This guide explains how to create and configure OKX API keys for use with NOFX.

## Create API Key

1. Log in to your [OKX account](https://www.okx.com/join/1865360)
2. Go to **Account** → **API**
3. Click **Create API Key**
4. Select **Trade** as the purpose
5. Complete 2FA verification
6. Name your API key (e.g., "NOFX Trading")

## Configure API Permissions

Enable the following permissions:

- ✅ **Read** - Required
- ✅ **Trade** - Required for trading
- ❌ **Withdraw** - Keep disabled for security

## Passphrase

OKX requires a passphrase in addition to API Key and Secret:

1. Create a strong passphrase during API creation
2. Save it securely - you'll need it for configuration

## IP Whitelist (Recommended)

For enhanced security:

1. Click **Edit** on your API key
2. Enable **IP Whitelist**
3. Add your server's IP address
4. Save changes

## Save Your Keys

After creation, you'll have:
- **API Key**: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
- **Secret Key**: `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
- **Passphrase**: Your created passphrase

⚠️ **Important**: Save the Secret Key immediately - it's only shown once!

## Configure in NOFX

Add your API credentials through the NOFX web interface:

1. Open NOFX dashboard (http://localhost:3000)
2. Go to **Exchange Configuration**
3. Enable **OKX**
4. Enter:
   - **API Key**
   - **Secret Key**
   - **Passphrase**
5. Save configuration

## Troubleshooting

| Error | Solution |
|-------|----------|
| `Invalid API key` | Check if API key is correct |
| `Invalid signature` | Check if Secret key and Passphrase are correct |
| `IP not whitelisted` | Add your IP to whitelist or disable IP restriction |
| `Permission denied` | Enable Trade permission in API settings |

## Security Best Practices

- Never share your API keys or passphrase
- Use IP whitelisting
- Don't enable withdrawal permissions
- Create separate API keys for different applications
- Regularly rotate your API keys

---

## File: docs/getting-started/README.md

# 🚀 Getting Started with NOFX

**Language:** [English](README.md) | [中文](README.zh-CN.md)

This section contains all the documentation you need to get NOFX up and running.

## 📋 Deployment Options

Choose the method that best fits your needs:

### 🐳 Docker Deployment (Recommended)

**Best for:** Beginners, quick setup, production deployments

- **English:** [docker-deploy.en.md](docker-deploy.en.md)
- **中文:** [docker-deploy.zh-CN.md](docker-deploy.zh-CN.md)

**Pros:**
- ✅ One-command setup
- ✅ All dependencies included
- ✅ Easy to update and manage
- ✅ Isolated environment

**Quick Start:**
```bash
cp config.json.example config.json
./scripts/start.sh start --build
```

---


## 🤖 AI Configuration

### Custom AI Providers

- **English:** [custom-api.en.md](custom-api.en.md)
- **中文:** [custom-api.md](custom-api.md)

Use custom AI models or third-party OpenAI-compatible APIs:
- Custom DeepSeek endpoints
- Self-hosted models
- Other LLM providers

---

## 🔑 Prerequisites

Before starting, ensure you have:

### For Docker Method:
- ✅ Docker 20.10+
- ✅ Docker Compose V2

### For Manual Method:
- ✅ Go 1.21+
- ✅ Node.js 18+
- ✅ TA-Lib library

---

## 📚 Next Steps

After deployment:

1. **Configure AI Models** → Web interface at http://localhost:3000
2. **Set Up Exchange** → Add Binance/Hyperliquid credentials
3. **Create Traders** → Combine AI models with exchanges
4. **Start Trading** → Monitor performance in dashboard

### 🔐 Optional: Enable Admin Mode (Single-User)

For single-tenant/self-hosted usage, you can enable strict admin-only access:

1) In `config.json` set the 2 fields below:
```jsonc
{
	"admin_mode": true,
  ...
  "jwt_secret": "YOUR_JWT_SCR"
}
```
2) Set environment variables (Docker compose already wired):
- `NOFX_ADMIN_PASSWORD` — admin password (plaintext; hashed on startup)

3) Login at `/login` using the admin password. All non-essential endpoints are blocked to unauthenticated users while admin mode is enabled.

---

## ⚠️ Important Notes

**Before Trading:**
- ⚠️ Test on testnet first
- ⚠️ Start with small amounts
- ⚠️ Understand the risks
- ⚠️ Read [Security Policy](../../SECURITY.md)

**API Keys:**
- 🔑 Never commit API keys to git
- 🔑 Use environment variables
- 🔑 Restrict IP access
- 🔑 Enable 2FA on exchanges

---

## 🆘 Troubleshooting

**Common Issues:**

1. **Docker build fails** → Check Docker version, update to 20.10+
2. **TA-Lib not found** → `brew install ta-lib` (macOS) or `apt-get install libta-lib0-dev` (Ubuntu)
3. **Port 8080 in use** → Change `API_PORT` in .env file
4. **Frontend won't connect** → Check backend is running on port 8080

**Need more help?**
- 📖 [FAQ](../guides/faq.zh-CN.md)
- 💬 [Telegram Community](https://t.me/nofx_dev_community)
- 🐛 [GitHub Issues](https://github.com/NoFxAiOS/nofx/issues)

---

[← Back to Documentation Home](../README.md)

---

## File: docs/getting-started/README.zh-CN.md

# 🚀 NOFX 快速开始

本节包含让 NOFX 运行起来所需的所有文档。

## 📋 部署选项

选择最适合您的方式：

### 🐳 Docker 部署（推荐）

**适合：** 初学者、快速部署、生产环境

- **中文文档：** [docker-deploy.zh-CN.md](docker-deploy.zh-CN.md)
- **English:** [docker-deploy.en.md](docker-deploy.en.md)

**优势：**
- ✅ 一键启动
- ✅ 包含所有依赖
- ✅ 易于更新和管理
- ✅ 隔离环境

**快速开始：**
```bash
cp config.json.example config.json
./scripts/start.sh start --build
```

---


## 🤖 AI 配置

### 自定义 AI 提供商

- **中文文档：** [custom-api.md](custom-api.md)
- **English:** [custom-api.en.md](custom-api.en.md)

使用自定义 AI 模型或第三方 OpenAI 兼容 API：
- 自定义 DeepSeek 端点
- 本地部署的模型
- 其他 LLM 提供商

---

## 🔑 环境要求

开始之前，请确保已安装：

### Docker 方式：
- ✅ Docker 20.10+
- ✅ Docker Compose V2

### 手动部署方式：
- ✅ Go 1.21+
- ✅ Node.js 18+
- ✅ TA-Lib 库

---

## 📚 下一步

部署完成后：

1. **配置 AI 模型** → 访问 Web 界面 http://localhost:3000
2. **设置交易所** → 添加 Binance/Hyperliquid 凭证
3. **创建交易员** → 将 AI 模型与交易所结合
4. **开始交易** → 在仪表板中监控表现

---

## ⚠️ 重要提示

**交易前：**
- ⚠️ 先在测试网测试
- ⚠️ 从小金额开始
- ⚠️ 了解风险
- ⚠️ 阅读[安全策略](../../SECURITY.md)

**API 密钥：**
- 🔑 永远不要提交 API 密钥到 git
- 🔑 使用环境变量
- 🔑 限制 IP 访问
- 🔑 在交易所启用 2FA

---

## 🆘 故障排除

**常见问题：**

1. **Docker 构建失败** → 检查 Docker 版本，更新到 20.10+
2. **找不到 TA-Lib** → `brew install ta-lib` (macOS) 或 `apt-get install libta-lib0-dev` (Ubuntu)
3. **端口 8080 被占用** → 在 .env 文件中更改 `API_PORT`
4. **前端无法连接** → 检查后端是否在端口 8080 上运行

**需要更多帮助？**
- 📖 [常见问题](../guides/faq.zh-CN.md)
- 💬 [Telegram 社区](https://t.me/nofx_dev_community)
- 🐛 [GitHub Issues](https://github.com/NoFxAiOS/nofx/issues)

---

[← 返回文档首页](../README.md)

---

## File: docs/community/bounty-aster.md

# 🚀 [BOUNTY] Integrate Aster Exchange Support

## 💰 Bounty Reward
**To be discussed** - Open to proposals from contributors

## 📋 Overview
We're looking for contributors to add Aster exchange support to NOFX AI Trading System. Currently supports Binance Futures, seeking to expand to Aster perpetual contracts.

## 🎯 Task Requirements

### Core Features to Implement

#### 1. **Aster API Integration**
- [ ] Account management (balance, positions, margin)
- [ ] Market data fetching (K-lines, order book, trades)
- [ ] Order execution (market/limit orders)
- [ ] Position management (open, close, modify)
- [ ] Websocket real-time data stream (if available)

#### 2. **Adapter Layer**
- [ ] Create `trader/aster_perpetual.go` adapter
- [ ] Implement unified interface compatible with existing `BinanceFuturesClient`
- [ ] Handle Aster-specific features (if any)

#### 3. **Configuration Support**
```json
{
  "traders": [
    {
      "id": "aster_trader",
      "name": "Aster AI Trader",
      "exchange": "aster",  // NEW
      "aster_api_key": "xxx",
      "aster_secret_key": "xxx",
      "ai_model": "deepseek",
      "initial_balance": 1000.0
    }
  ]
}
```

#### 4. **Risk Control Adaptation**
- [ ] Adapt position limits for Aster specs
- [ ] Handle leverage rules (may differ from Binance)
- [ ] Implement liquidation price calculation
- [ ] Funding rate integration (if applicable)

#### 5. **Testing & Documentation**
- [ ] Unit tests for API wrapper
- [ ] Integration tests with testnet (if available)
- [ ] Update README with Aster setup guide
- [ ] Add Aster-specific troubleshooting docs

## 📚 Technical References

**Aster Resources:**
- Official Website: [Add Aster exchange URL]
- API Documentation: [Add Aster API docs URL]
- SDK/Libraries: [Add if available]

**NOFX Architecture:**
- See `trader/binance_futures.go` as reference implementation
- Main trading logic: `trader/auto_trader.go`
- Configuration: `config.json` structure

## 🔧 Implementation Guidelines

### File Structure
```
trader/
├── binance_futures.go     (existing reference)
├── aster_perpetual.go     (NEW - to implement)
└── exchange_interface.go  (NEW - unified interface)

config/
└── config.go              (UPDATE - add Aster config)
```

### Interface to Implement
```go
type ExchangeClient interface {
    // Account
    GetAccount() (*AccountInfo, error)
    GetPositions() ([]*Position, error)

    // Market Data
    GetKlines(symbol, interval string, limit int) ([]*Kline, error)
    GetTicker(symbol string) (*Ticker, error)

    // Trading
    CreateOrder(params *OrderParams) (*Order, error)
    ClosePosition(symbol, side string) error

    // Risk Management
    SetLeverage(symbol string, leverage int) error
    GetLiquidationPrice(position *Position) (float64, error)
}
```

## ✅ Acceptance Criteria

**Minimum Requirements:**
- [ ] Can connect to Aster testnet/mainnet
- [ ] Fetch real-time account balance and positions
- [ ] Execute market orders successfully
- [ ] Close positions correctly
- [ ] Calculate accurate P/L
- [ ] No breaking changes to existing Binance integration

**Bonus Points:**
- [ ] Websocket streaming for real-time data
- [ ] Support for limit orders and stop-loss/take-profit
- [ ] Multi-exchange competition mode (Binance vs Aster)
- [ ] Performance comparison dashboard

## 📝 How to Contribute

1. **Comment on this issue** to express interest
2. **Fork the repository** and create a feature branch
3. **Implement the integration** following guidelines above
4. **Test thoroughly** on testnet before mainnet
5. **Submit a Pull Request** with:
   - Code changes
   - Tests
   - Documentation updates
   - Demo video/screenshots

## 🤝 Support & Questions

- Ask questions in this issue's comments
- Join our Telegram: [NOFX Developer Community](https://t.me/nofx_dev_community)
- Reference existing code: `trader/binance_futures.go`

## ⚠️ Important Notes

- **Test on testnet first** - Do NOT test with real funds initially
- **Maintain backward compatibility** - Existing Binance users should not be affected
- **Code quality** - Follow existing code style and patterns
- **Security** - Handle API keys securely, no hardcoded credentials

## 🔍 Research Needed

**Before starting, please investigate:**
- [ ] Does Aster provide a public API? (REST/Websocket)
- [ ] Is there an official SDK or code examples?
- [ ] Does Aster support testnet for development?
- [ ] What are the API rate limits?
- [ ] What symbols/markets are available?
- [ ] Are there any unique features or limitations?

**Share your findings in the comments!**

---

**Ready to contribute?** Comment below or start working and submit a PR!

**Questions?** Feel free to ask in the comments or on Telegram.

---

## File: docs/community/bounty-guide.md

# 📝 如何在 GitHub 发布集成任务 (Bounty)

## 🎯 发布步骤

### 方法 1: 直接创建 GitHub Issue（推荐）

1. **访问项目 Issues 页面**
   ```
   https://github.com/NoFxAiOS/nofx/issues
   ```

2. **点击 "New Issue" 按钮**

3. **选择 "Feature Request" 模板**（如果可用）

4. **填写 Issue 内容**

#### Hyperliquid 集成 Issue：

```markdown
标题：[BOUNTY] Integrate Hyperliquid Exchange Support 🚀

内容：复制 INTEGRATION_BOUNTY_HYPERLIQUID.md 的全部内容
```

#### Aster 集成 Issue：

```markdown
标题：[BOUNTY] Integrate Aster Exchange Support 🚀

内容：复制 INTEGRATION_BOUNTY_ASTER.md 的全部内容
```

5. **添加标签 (Labels)**
   - `enhancement` - 新功能
   - `bounty` - 悬赏任务
   - `help wanted` - 寻求帮助
   - `good first issue` - 适合新手（如果适用）

6. **点击 "Submit new issue"**

---

### 方法 2: 使用 GitHub CLI（适合命令行用户）

```bash
# 安装 GitHub CLI (如果还没安装)
brew install gh  # macOS
# 或访问 https://cli.github.com/

# 登录
gh auth login

# 创建 Hyperliquid 集成 Issue
gh issue create \
  --title "[BOUNTY] Integrate Hyperliquid Exchange Support 🚀" \
  --body-file INTEGRATION_BOUNTY_HYPERLIQUID.md \
  --label "enhancement,bounty,help wanted"

# 创建 Aster 集成 Issue
gh issue create \
  --title "[BOUNTY] Integrate Aster Exchange Support 🚀" \
  --body-file INTEGRATION_BOUNTY_ASTER.md \
  --label "enhancement,bounty,help wanted"
```

---

## 💰 设置悬赏金额

### 选项 1: 直接在 GitHub Issue 说明
在 Issue 开头写明：
```markdown
## 💰 Bounty Reward
- **$500 USD** for complete Hyperliquid integration
- **Bonus $200** for websocket real-time data support
- **Bonus $100** for comprehensive tests and docs
```

### 选项 2: 使用悬赏平台

**Gitcoin Bounties**
- 网站：https://gitcoin.co/
- 支持加密货币支付
- 步骤：
  1. 创建 Gitcoin 账户
  2. 点击 "Post a Bounty"
  3. 链接到你的 GitHub Issue
  4. 设置奖金金额和条件

**Bountysource**
- 网站：https://www.bountysource.com/
- 支持法币和加密货币
- 步骤：
  1. 导入 GitHub Issue
  2. 设置悬赏金额
  3. 托管资金直到完成

**IssueHunt**
- 网站：https://issuehunt.io/
- 专注于开源项目
- 步骤：
  1. 连接 GitHub 仓库
  2. 为特定 Issue 设置悬赏
  3. 贡献者完成后自动支付

---

## 📢 推广你的 Bounty

### 1. 社交媒体宣传

**Twitter/X:**
```
🚀 $500 Bounty! 🚀

Looking for devs to integrate Hyperliquid exchange into NOFX AI Trading System

✅ Add perpetual contracts support
✅ Unified API interface
✅ Full testing & docs

Issue: [GitHub链接]
Details: [详情链接]

#Bounty #OpenSource #Crypto #Trading
```

**Telegram:**
- 在 NOFX 开发者社区发布：https://t.me/nofx_dev_community
- 在相关的开发者群组分享

### 2. 开发者社区

**Reddit:**
- r/CryptoCurrency
- r/algotrading
- r/opensource
- r/forhire

**Discord:**
- 相关的加密货币交易社区
- 开发者频道

### 3. 开发者平台

**Dev.to / Hashnode:**
写一篇博客：
- 介绍项目
- 说明集成需求
- 展示悬赏奖励
- 链接到 GitHub Issue

---

## 📋 Issue 管理最佳实践

### 1. 及时回复
- 在24小时内回复所有问题
- 提供清晰的技术指导
- 鼓励潜在贡献者

### 2. 更新进度
定期更新 Issue，说明：
- 当前进展
- 已有贡献者
- 剩余工作
- 截止日期（如果有）

### 3. 设置里程碑
```markdown
## 📅 Milestones

**Phase 1 (Week 1-2):** API Wrapper
- [ ] Basic API integration
- [ ] Account & position fetching

**Phase 2 (Week 3):** Trading Functions
- [ ] Order execution
- [ ] Position management

**Phase 3 (Week 4):** Testing & Docs
- [ ] Comprehensive tests
- [ ] Documentation updates
```

### 4. 评审 PR
当有人提交 Pull Request：
- 快速进行代码审查
- 提供建设性反馈
- 测试功能是否正常
- 合并后及时支付赏金

---

## ⚠️ 注意事项

### 法律 & 合规
- ✅ 明确说明这是开源贡献，不是雇佣关系
- ✅ 确保贡献者同意 AGPL-3.0 License
- ✅ 保留最终合并决定权

### 资金管理
- ✅ 使用托管服务（Gitcoin、Bountysource）
- ✅ 在 Issue 中明确支付条件
- ✅ 完成后及时支付

### 质量控制
- ✅ 要求代码审查
- ✅ 必须有测试覆盖
- ✅ 必须有文档更新
- ✅ 不破坏现有功能

---

## 📞 需要帮助？

- **GitHub Issues**: https://github.com/NoFxAiOS/nofx/issues
- **Telegram**: https://t.me/nofx_dev_community
- **Twitter/X**: [@Web3Tinkle](https://x.com/Web3Tinkle)

---

**祝你成功招募到优秀的开发者！** 🎉