# Developer Platform API

## Overview

The 0fees Trading API provides unified access to both Binance Smart Chain (BSC) and Solana trading services. This API enables developers to build trading applications with features like token buying/selling, wallet management, and meme token creation.

Base URL: `https://api.0fees.trade`

## Authentication & Subscription System

### Subscription Required

Most trading endpoints require an active subscription. The API uses a wallet-based authentication system.

### Headers

All protected endpoints require:

```
x-wallet-address: YOUR_WALLET_ADDRESS
Content-Type: application/json
```

### Subscription Plans

* Daily: 10 USDC (24 hours)
* Weekly: 40 USDC (7 days)
* Monthly: 100 USDC (30 days)

Payment Address: `0x17DE1b47328C8e951fb013eDAd21A41f0dF38CF7`

## Public Endpoints

### Health Check

```
GET /health
```

Response:

```json
{
  "success": true,
  "message": "Server is running healthy",
  "services": {
    "solana": "http://localhost:3008",
    "binance": "http://localhost:3007"
  },
  "subscription": {
    "enabled": true,
    "plans": [
      { "name": "Daily", "price": "10 USDC", "duration": "1 day" },
      { "name": "Weekly", "price": "40 USDC", "duration": "7 days" },
      { "name": "Monthly", "price": "100 USDC", "duration": "30 days" }
    ]
  }
}
```

## Subscription Management

### Get Subscription Plans

```
GET /subscription/plans
```

### Check Subscription Status

```
GET /subscription/status?walletAddress=YOUR_WALLET_ADDRESS
```

### Verify Payment

```
POST /subscription/verify-payment
Content-Type: application/json

{
  "transactionHash": "0x...",
  "walletAddress": "0x...",
  "plan": "daily|weekly|monthly"
}
```

## Binance Smart Chain (BSC) Trading

All BSC endpoints are prefixed with `/binance/`

### Buy Tokens

```
POST /binance/buy
x-wallet-address: YOUR_WALLET_ADDRESS
Content-Type: application/json

{
  "tokenAddress": "0x...",
  "gasPrice": "5",
  "slippage": 10,
  "wallets": [
    {
      "privateKey": "0x...",
      "bnbAmount": "0.1"
    }
  ],
  "sequential": false,
  "skipBalanceValidation": false
}
```

Response:

```json
{
  "success": true,
  "data": {
    "results": [
      {
        "wallet": "0x...",
        "success": true,
        "transactionHash": "0x...",
        "bnbAmount": "0.1",
        "tokenAmount": "1000.5",
        "gasUsed": "0.002"
      }
    ],
    "summary": {
      "totalWallets": 1,
      "successfulTrades": 1,
      "failedTrades": 0,
      "totalBnbSpent": "0.1",
      "totalTokensReceived": "1000.5"
    }
  }
}
```

### Sell Tokens

```
POST /binance/sell
x-wallet-address: YOUR_WALLET_ADDRESS
Content-Type: application/json

{
  "tokenAddress": "0x...",
  "gasPrice": "5",
  "slippage": 10,
  "wallets": [
    {
      "privateKey": "0x...",
      "sellPercentage": 100
    }
  ],
  "sequential": false,
  "skipBalanceValidation": false,
  "feeRate": 1,
  "feeRecipient": "0xF17Ac4aE0b212f0129988F15BaD4407437BFA091"
}
```

### Consolidate BNB

```
POST /binance/consolidate
x-wallet-address: YOUR_WALLET_ADDRESS
Content-Type: application/json

{
  "sourcePrivateKeys": ["0x...", "0x..."],
  "destinationAddress": "0x...",
  "gasPrice": "5",
  "reserveAmount": "0.01"
}
```

### Distribute BNB

```
POST /binance/distribute
x-wallet-address: YOUR_WALLET_ADDRESS
Content-Type: application/json

{
  "sourcePrivateKey": "0x...",
  "distributions": [
    {
      "address": "0x...",
      "amount": "0.1"
    }
  ],
  "gasPrice": "5"
}
```

### Create Meme Token

```
POST /binance/createMeme
x-wallet-address: YOUR_WALLET_ADDRESS
Content-Type: application/json

{
  "privateKey": "0x...",
  "name": "My Meme Token",
  "symbol": "MMT",
  "description": "A fun meme token",
  "imageFile": "base64_encoded_image_data",
  "website": "https://example.com",
  "twitter": "https://twitter.com/example",
  "telegram": "https://t.me/example",
  "preSale": false,
  "gasPrice": "5",
  "buyWallets": [
    {
      "privateKey": "0x...",
      "amount": "0.1",
      "slippage": 10
    }
  ]
}
```

## Solana Trading

All Solana endpoints are prefixed with `/solana/`

### Buy Tokens

```
POST /solana/buy
x-wallet-address: YOUR_WALLET_ADDRESS
Content-Type: application/json

{
  "tokenAddress": "TOKEN_MINT_ADDRESS",
  "jitoTip": "0.001",
  "slippage": 10,
  "wallets": [
    {
      "privateKey": "BASE58_PRIVATE_KEY",
      "solAmount": "0.1"
    }
  ],
  "sequential": false,
  "skipBalanceValidation": false
}
```

Response:

```json
{
  "success": true,
  "data": {
    "results": [
      {
        "wallet": "WALLET_ADDRESS",
        "success": true,
        "transactionHash": "SIGNATURE",
        "solAmount": "0.1",
        "tokenAmount": "1000.5",
        "jitoTip": "0.001"
      }
    ],
    "summary": {
      "totalWallets": 1,
      "successfulTrades": 1,
      "failedTrades": 0,
      "totalSolSpent": "0.1",
      "totalTokensReceived": "1000.5"
    }
  }
}
```

### Sell Tokens

```
POST /solana/sell
x-wallet-address: YOUR_WALLET_ADDRESS
Content-Type: application/json

{
  "tokenAddress": "TOKEN_MINT_ADDRESS",
  "jitoTip": "0.001",
  "slippage": 10,
  "wallets": [
    {
      "privateKey": "BASE58_PRIVATE_KEY",
      "sellPercentage": 100
    }
  ],
  "sequential": false,
  "skipBalanceValidation": false
}
```

### Consolidate SOL

```
POST /solana/consolidate
x-wallet-address: YOUR_WALLET_ADDRESS
Content-Type: application/json

{
  "sourcePrivateKeys": ["PRIVATE_KEY_1", "PRIVATE_KEY_2"],
  "destinationAddress": "DESTINATION_ADDRESS",
  "jitoTip": "0.001",
  "reserveAmount": "0.01"
}
```

### Distribute SOL

```
POST /solana/distribute
x-wallet-address: YOUR_WALLET_ADDRESS
Content-Type: application/json

{
  "sourcePrivateKey": "BASE58_PRIVATE_KEY",
  "distributions": [
    {
      "address": "RECIPIENT_ADDRESS",
      "amount": "0.1"
    }
  ],
  "jitoTip": "0.001"
}
```

## Rate Limiting

* Rate Limit: 200 requests per minute per IP
* Burst Limit: Configurable based on subscription tier

## Error Responses

### Authentication Errors

```json
{
  "success": false,
  "error": "Wallet address required",
  "code": "WALLET_ADDRESS_REQUIRED",
  "message": "Please provide your wallet address in the x-wallet-address header"
}
```

```json
{
  "success": false,
  "error": "Active subscription required",
  "code": "SUBSCRIPTION_REQUIRED",
  "message": "You need an active subscription to access this endpoint. Please purchase a subscription plan.",
  "subscriptionUrl": "/subscription/plans"
}
```

### Trading Errors

```json
{
  "success": false,
  "error": "Transaction failed",
  "message": "Insufficient balance or slippage too low"
}
```

### Rate Limit Errors

```json
{
  "success": false,
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again later."
}
```

## SDK Integration Examples

{% tabs %}
{% tab title="JavaScript / Node.js" %}
{% code title="example.js" %}

```javascript
const axios = require('axios');

const API_BASE = 'http://localhost:8989';
const WALLET_ADDRESS = 'YOUR_WALLET_ADDRESS';

// Create API client
const apiClient = axios.create({
  baseURL: API_BASE,
  headers: {
    'x-wallet-address': WALLET_ADDRESS,
    'Content-Type': 'application/json'
  }
});

// Buy tokens on BSC
async function buyTokenBSC(tokenAddress, bnbAmount, privateKey) {
  try {
    const response = await apiClient.post('/binance/buy', {
      tokenAddress,
      gasPrice: '5',
      slippage: 10,
      wallets: [{
        privateKey,
        bnbAmount
      }],
      sequential: false
    });
    
    return response.data;
  } catch (error) {
    console.error('Buy failed:', error.response?.data || error.message);
    throw error;
  }
}

// Buy tokens on Solana
async function buyTokenSolana(tokenAddress, solAmount, privateKey) {
  try {
    const response = await apiClient.post('/solana/buy', {
      tokenAddress,
      jitoTip: '0.001',
      slippage: 10,
      wallets: [{
        privateKey,
        solAmount
      }],
      sequential: false
    });
    
    return response.data;
  } catch (error) {
    console.error('Buy failed:', error.response?.data || error.message);
    throw error;
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code title="example.py" %}

```python
import requests

API_BASE = 'http://localhost:8989'
WALLET_ADDRESS = 'YOUR_WALLET_ADDRESS'

class TradingAPI:
    def __init__(self, wallet_address):
        self.base_url = API_BASE
        self.headers = {
            'x-wallet-address': wallet_address,
            'Content-Type': 'application/json'
        }
    
    def buy_token_bsc(self, token_address, bnb_amount, private_key):
        payload = {
            'tokenAddress': token_address,
            'gasPrice': '5',
            'slippage': 10,
            'wallets': [{
                'privateKey': private_key,
                'bnbAmount': bnb_amount
            }],
            'sequential': False
        }
        
        response = requests.post(
            f'{self.base_url}/binance/buy',
            json=payload,
            headers=self.headers
        )
        
        return response.json()
    
    def check_subscription_status(self):
        response = requests.get(
            f'{self.base_url}/subscription/status',
            params={'walletAddress': self.headers['x-wallet-address']}
        )
        return response.json()

# Usage
api = TradingAPI(WALLET_ADDRESS)
status = api.check_subscription_status()
print(f"Subscription status: {status}")
```

{% endcode %}
{% endtab %}
{% endtabs %}

## WebSocket Support (Future)

WebSocket endpoints for real-time updates will be available at:

* `ws://localhost:8989/ws/trades` - Real-time trade updates
* `ws://localhost:8989/ws/prices` - Real-time price feeds

## Support & Contact

For API support and questions:

* GitHub Issues: \[Repository Issues]
* Documentation Updates: Check this file for latest changes
* Rate Limit Increases: Contact support with your use case

## Changelog

### v1.0.0

* Initial API release
* BSC and Solana trading support
* Subscription system implementation
* Rate limiting and authentication

Last Updated: 2024