NANO TRADE API Documentation

API v1.0 • Last updated 7 days ago

The NANO TRADE API provides programmatic access to advanced AI-driven trading capabilities on Aster DEX. Leverage our LLM-powered trading oracle through a comprehensive RESTful interface to automate bot creation, manage positions, and execute trades with precision.

RESTful

JSON-based REST API with standard HTTP methods

Secure

API key authentication with role-based access control

Real-time

Live market data feeds and instant trade execution

Authentication

All API requests require authentication via an API key. Include your API key in the request header as shown below:

Authorization: Bearer YOUR_API_KEY

You can generate API keys from your NANO TRADE account dashboard. Each key has specific permissions and can be revoked at any time.

API Key Permissions

Permission	Description
`read:bots`	Read-only access to bot information
`write:bots`	Create and modify bot configurations
`execute:trades`	Execute trading operations
`read:market`	Access market data and oracle feeds
`read:account`	View account balance and transaction history

Base URL

All API endpoints are accessible at:

https://api.nanotrade.money/v1

All requests must be made over HTTPS. Unencrypted requests will be rejected.

Create Bot

POST

POST /bots

Creates a new trading bot with specified configuration and strategy.

Request Body

                            {
  "name": "Arbitrage Bot v1",
  "strategy_type": "arbitrage",
  "market_type": "spot",
  "trading_pair": "BNB/USDT",
  "llm_model": "gpt-4-turbo",
  "prompt": "Execute arbitrage opportunities with 2% minimum profit threshold",
  "risk_level": "medium",
  "max_leverage": 1,
  "base_volume": 1000,
  "enabled": true
}
                        

Parameters

Parameter	Type	Description
`name`	string	Bot display name (required)
`strategy_type`	string	Strategy type: arbitrage, liquidity, hedging, momentum (required)
`market_type`	string	spot or perpetual (required)
`trading_pair`	string	Trading pair in format BASE/QUOTE (required)
`llm_model`	string	LLM model: gpt-4-turbo, claude-3, gemini-pro, etc. (required)
`prompt`	string	Custom trading prompt for AI decision making (required)
`risk_level`	string	low, medium, high (default: medium)
`max_leverage`	number	Maximum leverage (1-20x, default: 1)
`base_volume`	number	Base trading volume per transaction (default: 1000)
`enabled`	boolean	Enable bot immediately (default: true)

Response Example

{
  "success": true,
  "data": {
    "bot_id": "bot_abc123def456",
    "name": "Arbitrage Bot v1",
    "strategy_type": "arbitrage",
    "market_type": "spot",
    "trading_pair": "BNB/USDT",
    "status": "active",
    "created_at": "2025-10-23T14:30:00Z",
    "epoch_reset": "2025-10-24T14:30:00Z",
    "available_credits": 5,
    "total_trades": 0,
    "win_rate": 0.0,
    "profit_loss": 0.0
  }
}

List Bots

GET

GET /bots?page=1&limit=20&status=active

Retrieves a paginated list of all trading bots for your account.

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20, max: 100)
`status`	string	Filter by status: active, paused, stopped
`strategy_type`	string	Filter by strategy type

Response Example

{
  "success": true,
  "data": {
    "bots": [
      {
        "bot_id": "bot_abc123def456",
        "name": "Arbitrage Bot v1",
        "strategy_type": "arbitrage",
        "status": "active",
        "total_trades": 156,
        "win_rate": 0.72,
        "profit_loss": 2450.50
      }
    ],
    "pagination": {
      "total": 5,
      "page": 1,
      "limit": 20,
      "pages": 1
    }
  }
}

Get Bot Details

GET

GET /bots/:bot_id

Retrieves detailed information about a specific bot including performance metrics and current positions.

Path Parameters

Parameter	Type	Description
`bot_id`	string	Unique bot identifier (required)

Response Example

{
  "success": true,
  "data": {
    "bot_id": "bot_abc123def456",
    "name": "Arbitrage Bot v1",
    "strategy_type": "arbitrage",
    "market_type": "spot",
    "trading_pair": "BNB/USDT",
    "llm_model": "gpt-4-turbo",
    "status": "active",
    "prompt": "Execute arbitrage opportunities with 2% minimum profit threshold",
    "performance": {
      "total_trades": 156,
      "winning_trades": 112,
      "losing_trades": 44,
      "win_rate": 0.718,
      "profit_loss": 2450.50,
      "roi": 2.45,
      "avg_trade_profit": 15.71
    },
    "positions": {
      "open": 3,
      "total_exposure": 5000.00,
      "largest_position": 2000.00
    },
    "last_trade": "2025-10-23T14:25:32Z",
    "next_epoch_reset": "2025-10-24T14:30:00Z",
    "pause_cooldown_remaining": 0
  }
}

Update Bot

PUT

PUT /bots/:bot_id

Updates bot configuration including prompt refinement, strategy parameters, and settings.

Request Body (All fields optional)

                            {
  "name": "Arbitrage Bot v2",
  "prompt": "Updated trading logic with new parameters",
  "risk_level": "low",
  "max_leverage": 5,
  "base_volume": 1500,
  "enabled": true
}
                        

Response Example

{
  "success": true,
  "data": {
    "bot_id": "bot_abc123def456",
    "message": "Bot updated successfully. Changes take effect at next epoch reset.",
    "updated_fields": ["name", "prompt", "risk_level"],
    "epoch_reset_in": "15h 30m"
  }
}

Delete Bot

DELETE

DELETE /bots/:bot_id

Deletes a bot and closes all open positions. This action cannot be undone.

Response Example

{
  "success": true,
  "data": {
    "bot_id": "bot_abc123def456",
    "status": "deleted",
    "closed_positions": 3,
    "final_profit_loss": 2450.50,
    "message": "Bot deleted successfully"
  }
}

Execute Trade

POST

POST /bots/:bot_id/trades

Manually execute a trade for a specific bot. Requires appropriate bot status and available credits.

Request Body

                            {
  "action": "buy",
  "amount": 10,
  "order_type": "market",
  "leverage": 1,
  "take_profit": 2100,
  "stop_loss": 1900
}
                        

Parameters

Parameter	Type	Description
`action`	string	buy or sell (required)
`amount`	number	Trade amount in base currency (required)
`order_type`	string	market or limit (default: market)
`leverage`	number	Leverage multiplier 1-20x (default: 1)
`take_profit`	number	Optional take profit price
`stop_loss`	number	Optional stop loss price

Response Example

{
  "success": true,
  "data": {
    "trade_id": "trade_xyz789abc123",
    "bot_id": "bot_abc123def456",
    "action": "buy",
    "amount": 10,
    "entry_price": 2050.00,
    "total_cost": 20500.00,
    "leverage": 1,
    "status": "executed",
    "timestamp": "2025-10-23T14:35:00Z",
    "credits_used": 1,
    "remaining_credits": 4
  }
}

Get Positions

GET

GET /bots/:bot_id/positions

Retrieves all open positions for a specific bot including entry prices, current values, and P&L.

Response Example

{
  "success": true,
  "data": {
    "open_positions": [
      {
        "position_id": "pos_123abc456def",
        "trading_pair": "BNB/USDT",
        "action": "buy",
        "entry_price": 600.00,
        "current_price": 615.50,
        "amount": 5,
        "total_value": 3077.50,
        "entry_cost": 3000.00,
        "unrealized_pnl": 77.50,
        "unrealized_pnl_percent": 2.58,
        "take_profit": 650.00,
        "stop_loss": 550.00,
        "opened_at": "2025-10-23T12:00:00Z",
        "leverage": 1
      }
    ],
    "total_exposure": 5000.00,
    "total_unrealized_pnl": 150.25
  }
}

Close Position

POST

POST /bots/:bot_id/positions/:position_id/close

Closes an open position and realizes the profit or loss.

Response Example

{
  "success": true,
  "data": {
    "position_id": "pos_123abc456def",
    "closed_at": "2025-10-23T14:40:00Z",
    "exit_price": 615.50,
    "realized_pnl": 77.50,
    "realized_pnl_percent": 2.58,
    "status": "closed"
  }
}

Get Price Data

GET

GET /market/price/:trading_pair?timeframe=1h

Retrieves real-time and historical price data for trading pairs.

Query Parameters

Parameter	Type	Description
`timeframe`	string	1m, 5m, 15m, 1h, 4h, 1d (default: 1h)
`limit`	number	Number of candles to return (default: 100, max: 500)

Response Example

{
  "success": true,
  "data": {
    "trading_pair": "BNB/USDT",
    "current_price": 615.50,
    "24h_change": 2.45,
    "24h_high": 620.00,
    "24h_low": 598.00,
    "volume_24h": 1500000,
    "candles": [
      {
        "timestamp": "2025-10-23T13:00:00Z",
        "open": 610.00,
        "high": 618.00,
        "low": 608.00,
        "close": 615.50,
        "volume": 50000
      }
    ]
  }
}

Get Oracle Data

GET

GET /market/oracle/:trading_pair

Retrieves tamper-proof price data from integrated Chainlink oracles.

Response Example

{
  "success": true,
  "data": {
    "trading_pair": "BNB/USDT",
    "oracle_price": 615.48,
    "dex_price": 615.50,
    "price_deviation": 0.0032,
    "oracle_provider": "Chainlink",
    "last_update": "2025-10-23T14:39:45Z",
    "confidence_interval": 0.05,
    "heartbeat": 3600
  }
}

Market Statistics

GET

GET /market/stats

Retrieves aggregated market statistics and ecosystem metrics.

Response Example

{
  "success": true,
  "data": {
    "total_bots": 2045,
    "active_bots": 1834,
    "total_ecosystem_profit": 523750.50,
    "total_trades_24h": 45230,
    "average_win_rate": 0.65,
    "top_performing_pairs": ["BNB/USDT", "ETH/USDT", "SOL/USDT"],
    "most_used_strategy": "arbitrage",
    "total_volume_24h": 125000000,
    "liquidity_pool_size": 100000
  }
}

User Balance

GET

GET /account/balance

Retrieves your account balance including available funds, credits, and total portfolio value.

Response Example

{
  "success": true,
  "data": {
    "available_balance": 5000.00,
    "total_portfolio_value": 12450.50,
    "unrealized_pnl": 450.50,
    "realized_pnl": 2000.00,
    "credits_available": 4,
    "credits_total": 5,
    "total_exposed": 7000.00,
    "liquidity_pool_share": 500.00
  }
}

Wallet Information

GET

GET /account/wallet

Retrieves your non-custodial wallet information and associated addresses.

Response Example

{
  "success": true,
  "data": {
    "wallet_address": "0x1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P7Q8R9S0",
    "wallet_type": "non-custodial",
    "blockchain_network": "BNB Smart Chain",
    "total_balance_usd": 12450.50,
    "tokens": {
      "USDT": 5000.00,
      "NANO": 250.00,
      "BNB": 5.5,
      "ETH": 0.25
    },
    "created_at": "2025-09-15T10:00:00Z"
  }
}

Transaction History

GET

GET /account/transactions?page=1&limit=50&type=trade

Retrieves paginated transaction history including trades, credits, and transfers.

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 50, max: 200)
`type`	string	trade, credit, transfer, profit_share
`start_date`	string	ISO 8601 format (e.g., 2025-10-01T00:00:00Z)
`end_date`	string	ISO 8601 format (e.g., 2025-10-31T23:59:59Z)

Response Example

{
  "success": true,
  "data": {
    "transactions": [
      {
        "transaction_id": "tx_abc123def456",
        "type": "trade",
        "bot_id": "bot_abc123def456",
        "action": "buy",
        "amount": 10,
        "price": 615.50,
        "total_value": 6155.00,
        "status": "completed",
        "timestamp": "2025-10-23T14:35:00Z"
      },
      {
        "transaction_id": "tx_xyz789abc123",
        "type": "profit_share",
        "amount": 125.75,
        "status": "completed",
        "timestamp": "2025-10-23T00:00:00Z"
      }
    ],
    "pagination": {
      "total": 245,
      "page": 1,
      "limit": 50,
      "pages": 5
    }
  }
}

Error Handling

All errors are returned with appropriate HTTP status codes and detailed error messages.

Common Error Responses

Status Code	Error Type	Description
`400`	Bad Request	Invalid request parameters or malformed body
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Insufficient permissions for requested action
`404`	Not Found	Requested resource does not exist
`429`	Too Many Requests	Rate limit exceeded (100 requests/minute)
`500`	Server Error	Internal server error

Error Response Example

                        {
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance for this trade",
    "details": {
      "required": 5000.00,
      "available": 3500.00
    }
  }
}
                    

Rate Limiting

API requests are rate limited to ensure fair usage across all users:

•

1000 requests per minute

Standard rate limit for most endpoints

•

100000 requests per hour

Overall hourly limit