endpoints_usage.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Guide of HOW TO use the Overkill API\n",
    "\n",
    "This is a guide to help you use the Overkill API. The API is a RESTful API that allows you to interact with the Overkill platform. The API is designed to be simple and easy to use. This guide will walk you through the process of using the API to interact with the Overkill platform, using Python."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## GETTING STARTED\n",
    "\n",
    "To get started, you will need to create an account on the Overkill platform. You can do this by visiting the Overkill website and signing up for an account. Once you have created an account, you will need to generate an API key. You can do this by visiting the API section of the Overkill website and generating an API key.\n",
    "\n",
    "This account can also be registered using the API, but for this guide, we will assume that you have already created an account and generated an API key.\n",
    "\n",
    "### Pre-requisites\n",
    "\n",
    "- Python 3.11 or higher\n",
    "- Installed packages from the `requirements.txt` file\n",
    "\n",
    "```bash\n",
    "pip install -r requirements.txt\n",
    "```\n",
    "\n",
    "## AUTHENTICATION\n",
    "\n",
    "To authenticate with the Overkill API, you will need to include your API keys in the headers of your requests. You can do this by including an `x-api-key` and `x-api-secret` header with the values. Code below uses environment variables to store the API keys.\n",
    "\n",
    "Fill below code with your API keys and run it to check if the authentication is working."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "\n",
    "os.environ['X_API_KEY'] = 'YOUR_API_KEY'\n",
    "os.environ['X_API_SECRET'] = 'YOUR_API_SECRET'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "# prepare the headers for the requests\n",
    "\n",
    "import requests\n",
    "import os\n",
    "from pprint import pprint\n",
    "\n",
    "url = 'https://api.princeofcrypto.com/v1/{}'\n",
    "\n",
    "X_API_KEY = os.getenv('X_API_KEY')\n",
    "X_API_SECRET = os.getenv('X_API_SECRET')\n",
    "\n",
    "\n",
    "headers = {\n",
    "    'x-api-key': X_API_KEY,\n",
    "    'x-api-secret': X_API_SECRET,\n",
    "    'Content-Type': 'application/json'\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will use following input data, for the endpoints, if needed:\n",
    "\n",
    "```python\n",
    "paramaters = {\n",
    "    'param1': 'value1',\n",
    "    'param2': 'value2'\n",
    "}\n",
    "\n",
    "post_data = {\n",
    "    'key1': 'value1',\n",
    "    'key2': 'value2'\n",
    "}\n",
    "```\n",
    "\n",
    "and prepare full url with the endpoint type:\n",
    "\n",
    "```python\n",
    "url_get = url.format('coin/data')\n",
    "url_post = url.format('coin/data')\n",
    "\n",
    "response_get_endpoint = requests.get(url_get, headers=headers, params=paramaters)\n",
    "response_post_endpoint = requests.post(url_post, headers=headers, json=post_data)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example of using the Overkill API\n",
    "\n",
    "Here is an example of how you can use the Overkill API to get the data of a coin:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "# OVERKILL DATA\n",
    "\n",
    "from typing import Optional\n",
    "\n",
    "\n",
    "def get_overkill_active_coins():\n",
    "    url_get = url.format('coin/list')\n",
    "    response = requests.get(url_get, headers=headers)\n",
    "    response.raise_for_status()\n",
    "    return response.json()\n",
    "\n",
    "def get_overkill_coin_metadata(samples:int = 1):\n",
    "    url_get = url.format(f'coin/metadata/daily?samples={samples}')\n",
    "    response = requests.get(url_get, headers=headers)\n",
    "    response.raise_for_status()\n",
    "    return response.json()\n",
    "\n",
    "def get_overkill_coin_data(coin_id: int, samples:int = 365):\n",
    "    url_get = url.format(f'coin/data/daily?coin_id={coin_id}&samples={samples}')\n",
    "    response = requests.get(url_get, headers=headers)\n",
    "    response.raise_for_status()\n",
    "    return response.json()\n",
    "\n",
    "def get_telegram_filters():\n",
    "    url_get = url.format('telegram/filters')\n",
    "    response = requests.get(url_get, headers=headers)\n",
    "    response.raise_for_status()\n",
    "    telegram_filters = response.json().get('result')\n",
    "    telegram_filters = [{k: v for k, v in obj.items() if k != '_id'} for obj in telegram_filters]\n",
    "\n",
    "    url_get = url.format('telegram/expressions')\n",
    "    response = requests.get(url_get, headers=headers)\n",
    "    response.raise_for_status()   \n",
    "    expressions = response.json().get('result')\n",
    "\n",
    "    for telegram_filter in telegram_filters:\n",
    "        for key,val in expressions.items():\n",
    "            if val == telegram_filter.get('expression'):\n",
    "                telegram_filter['expression'] = key\n",
    "                break\n",
    "    return telegram_filters\n",
    "\n",
    "def get_current_watchlist():\n",
    "    url_get = url.format('coin/watch')\n",
    "    response = requests.get(url_get, headers=headers)\n",
    "    response.raise_for_status()\n",
    "    return response.json()     \n",
    "\n",
    "def get_signals(latest: int = 10, signal_type: str = \"telegram-signal\", username: Optional[str] = None):\n",
    "    url_get = url.format('user/signal')\n",
    "    params = {\n",
    "        \"latest\": latest,\n",
    "        \"signal_type\": signal_type,\n",
    "        \"username\": username\n",
    "    }\n",
    "    response = requests.get(url_get, headers=headers, params=params)\n",
    "    response.raise_for_status()\n",
    "    return response.json()\n",
    "\n",
    "# COINGECKO DATA\n",
    "\n",
    "def get_coingecko_coin_list():\n",
    "    url_get = url.format('coin/coingecko/list')\n",
    "    response = requests.get(url_get, headers=headers)\n",
    "    response.raise_for_status()\n",
    "    return response.json()\n",
    "\n",
    "\n",
    "def get_coingecko_price_data(coin_id: int, samples:int = 365):\n",
    "    url_get = url.format(f'coin/coingecko/data?coin_id={coin_id}&samples={samples}')\n",
    "    response = requests.get(url_get, headers=headers)\n",
    "    response.raise_for_status()\n",
    "    return response.json()\n",
    "\n",
    "def get_gecko_terminal_data(pool_address: str, network: str = \"solana\", timeframe: str = \"minute\"):\n",
    "    # endpoint also accepts there params: from_timestamp: datetime, to_timestamp: datetime\n",
    "    url_get = url.format('coin/gecko-terminal/data')\n",
    "    params = {\n",
    "        \"pool_address\": pool_address,\n",
    "        \"network\": network,\n",
    "        \"timeframe\": timeframe\n",
    "    }\n",
    "    response = requests.get(url_get, headers=headers, params=params)\n",
    "    response.raise_for_status()\n",
    "    return response.json()\n",
    "\n",
    "# YAHOO DATA\n",
    "\n",
    "def get_yahoo_coin_list():\n",
    "    url_get = url.format('coin/yahoo/list')\n",
    "    response = requests.get(url_get, headers=headers)\n",
    "    response.raise_for_status()\n",
    "    return response.json()    "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[{'expression': 'GreaterThanOrEqual',\n",
      "  'filter_name': 'token_market_cap',\n",
      "  'value': 4500},\n",
      " {'expression': 'LessThan',\n",
      "  'filter_name': 'token_market_cap',\n",
      "  'value': 2000000},\n",
      " {'expression': 'GreaterThanOrEqual',\n",
      "  'filter_name': 'token_liquidity',\n",
      "  'value': 1500},\n",
      " {'expression': 'Equal', 'filter_name': 'token_burned', 'value': True},\n",
      " {'expression': 'GreaterThanOrEqual',\n",
      "  'filter_name': 'token_burned_percent',\n",
      "  'value': 50}]\n"
     ]
    }
   ],
   "source": [
    "# get current telegram filters (only the ones that are to filter chat messages)\n",
    "\n",
    "pprint(get_telegram_filters())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'jsonrpc': '2.0',\n",
      " 'result': [{'created_at': '2024-07-25T19:49:56.209000',\n",
      "             'token_address': '8v1A5rrn2D3P3MckoyDkUwzXgBGGLYMDQEhW4cA8VuAr',\n",
      "             'token_burned': True,\n",
      "             'token_burned_percent': 100.0,\n",
      "             'token_decimals': 0,\n",
      "             'token_liquidity': 4880.0,\n",
      "             'token_liquidity_supply': 100000000.0,\n",
      "             'token_market_cap': 4880.0,\n",
      "             'token_name': 'wicked',\n",
      "             'token_network': 'solana',\n",
      "             'token_platform': 'Raydium',\n",
      "             'token_platform_address': '6wYfeT6iTFyozw4eVDxn8nQAiTChFLzkHbCu1nf8Ajg4',\n",
      "             'token_platform_price': 0.0,\n",
      "             'token_renounced': True,\n",
      "             'token_supply': 100000000,\n",
      "             'token_ticker': 'wicked'},\n",
      "            {'created_at': '2024-07-26T23:23:11.124000',\n",
      "             'token_address': 'FsAgEef2o8ErFyoqbQgKhLwrrjxTxbtjp6qVY71MoY2b',\n",
      "             'token_burned': True,\n",
      "             'token_burned_percent': 100.0,\n",
      "             'token_decimals': 0,\n",
      "             'token_liquidity': 12640.0,\n",
      "             'token_liquidity_supply': 1000000000.0,\n",
      "             'token_market_cap': 12640.0,\n",
      "             'token_name': 'T Pose',\n",
      "             'token_network': 'solana',\n",
      "             'token_platform': 'Raydium',\n",
      "             'token_platform_address': '6Bx9fdU5Kfx11ZLcVKykABXGTMEob3NkKaiho2gxsw7j',\n",
      "             'token_platform_price': 0.0,\n",
      "             'token_renounced': True,\n",
      "             'token_supply': 1000000000,\n",
      "             'token_ticker': 'T'}]}\n"
     ]
    }
   ],
   "source": [
    "# get current watchlist\n",
    "\n",
    "pprint(get_current_watchlist())\n",
    "\n",
    "# if result = [] -> no coins are on the watchlist right now"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "All the endpoints are available here: https://api.princeofcrypto.com/redoc"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Examples\n",
    "\n",
    "Below you can find usage examples, of the functions defined above."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get current active coins\n",
    "\n",
    "active_coins = get_overkill_active_coins()\n",
    "pprint(active_coins[0])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 57,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'adj_close': '28091.568359',\n",
      " 'close': '28091.568359',\n",
      " 'date': '2023-05-01T00:00:00',\n",
      " 'high': '29329.935547',\n",
      " 'low': '27680.792969',\n",
      " 'open': '29227.103516',\n",
      " 'volume': '18655599976'}\n"
     ]
    }
   ],
   "source": [
    "# get coin daily data\n",
    "\n",
    "import json\n",
    "\n",
    "coin_list_json = json.loads(active_coins[0]['body'])\n",
    "coin_id_example = coin_list_json['result'][0]['coin_id']\n",
    "\n",
    "coin_tohlcv = get_overkill_coin_data(coin_id_example).get('result') # time, open, high, low, close, volume\n",
    "pprint(coin_tohlcv[0]) # first sample = 365 days ago"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'adj_close': '63217.136719',\n",
      " 'close': '63217.136719',\n",
      " 'date': '2024-04-29T00:00:00',\n",
      " 'high': '63217.136719',\n",
      " 'low': '63103.300781',\n",
      " 'open': '63103.300781',\n",
      " 'volume': '17391955968'}\n"
     ]
    }
   ],
   "source": [
    "pprint(coin_tohlcv[-1])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# coin metadata\n",
    "\n",
    "pprint(get_overkill_coin_metadata().get('result'))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 61,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'_id': '01coin', 'name': '01coin', 'platforms': {}, 'symbol': 'zoc'}\n"
     ]
    }
   ],
   "source": [
    "# coingecko coin list\n",
    "\n",
    "pprint(get_coingecko_coin_list().get('result')[0])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 63,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'_id': 'ADF',\n",
      " 'name': 'Art de Finance USD',\n",
      " 'time_updated': '2024-04-21T17:15:40.182000'}\n"
     ]
    }
   ],
   "source": [
    "# yahoo coin list\n",
    "\n",
    "pprint(get_yahoo_coin_list().get('result')[0])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# coingecko data\n",
    "\n",
    "pprint(get_coingecko_price_data(coin_id_example))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Example signal:\n",
    "\n",
    "```json\n",
    "{\n",
    "  \"token_market_cap\": 141010,\n",
    "  \"token_liquidity\": 11900,\n",
    "  \"token_liquidity_supply\": 0,\n",
    "  \"token_renounced\": true,\n",
    "  \"token_burned\": true,\n",
    "  \"token_burned_percent\": 100,\n",
    "  \"token_network\": \"solana\",\n",
    "  \"token_name\": \"McDolendz\",\n",
    "  \"token_ticker\": \"MCDZ\",\n",
    "  \"token_address\": \"EKZYsyQrvwdzPoPYcEULZ4Zx65PdaH3bCMiWpsjSrQiW\",\n",
    "  \"token_supply\": 0,\n",
    "  \"token_platform\": \"Raydium\",\n",
    "  \"token_platform_address\": \"AaUaWBgSDn3ZupZDTLRU8GAyT5yrdfR1prGHdgv1axSp\",\n",
    "  \"token_platform_price\": 0,\n",
    "  \"token_decimals\": 0,\n",
    "  \"created_at\": {\n",
    "    \"$date\": \"2024-04-27T21:40:02.656Z\"\n",
    "  }\n",
    "}\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# coingecko terminal price data (coins from the 'watch list' are saved in here - to calculate PROFIT/LOSS of the signals)\n",
    "\n",
    "pprint(get_gecko_terminal_data(\"AaUaWBgSDn3ZupZDTLRU8GAyT5yrdfR1prGHdgv1axSp\").get('result'))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "url_get = url.format('coin/data/daily?coin_id=1')\n",
    "response = requests.get(url_get, headers=headers)\n",
    "response.raise_for_status()\n",
    "response.json()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Send your signals\n",
    "\n",
    "You can also send YOUR signals - will be saved & accessible LIVE to all websocket clients.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Define required logic\n",
    "\n",
    "from pydantic import BaseModel, Field\n",
    "from typing import Optional, Union\n",
    "\n",
    "class SignalMessage(BaseModel):\n",
    "    message: Union[dict, str] = Field(..., description=\"Message\")\n",
    "    target_user_id: Optional[str] = Field(None, description=\"Target user id\")\n",
    "\n",
    "# SEND YOUR SIGNAL\n",
    "def post_your_signal(signal: SignalMessage):\n",
    "    url_get = url.format('user/signal')\n",
    "    response = requests.post(url_get, headers=headers, json={**signal.model_dump()})\n",
    "    response.raise_for_status()\n",
    "    return response.json()   "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'jsonrpc': '2.0', 'result': 'ok'}\n",
      "{'jsonrpc': '2.0', 'result': 'ok'}\n"
     ]
    }
   ],
   "source": [
    "my_signal = SignalMessage(\n",
    "    message = {\n",
    "        \"token_market_cap\": 141010,\n",
    "        \"token_address\": \"0xexample\",\n",
    "        \"some_field\": \"BUY NOW!\"\n",
    "    }\n",
    ")\n",
    "\n",
    "my_message_signal = SignalMessage(\n",
    "    message= \"My public signal: BUY THIS NOW - TICHI GEM!\",\n",
    ")\n",
    "\n",
    "res1 = post_your_signal(my_signal)\n",
    "res2 = post_your_signal(my_message_signal)\n",
    "\n",
    "pprint(res1)\n",
    "pprint(res2)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'jsonrpc': '2.0', 'result': 'ok'}\n"
     ]
    }
   ],
   "source": [
    "my_message_signal = SignalMessage(\n",
    "    message= \"LOW CAP Watch list has been cleared automatically!\",\n",
    ")\n",
    "\n",
    "pprint(post_your_signal(my_message_signal))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "On server we got (and saved to 'signals' collection):\n",
    "\n",
    "```json\n",
    "[{\n",
    "  \"_id\": {\n",
    "    \"$oid\": \"662faf525d5257d23a41da87\"\n",
    "  },\n",
    "  \"username\": \"AlphaDragon\",\n",
    "  \"timestamp\": \"2024-04-29 14:31:46\",\n",
    "  \"message\": {\n",
    "    \"token_market_cap\": 141010,\n",
    "    \"token_address\": \"0xexample\",\n",
    "    \"some_field\": \"BUY NOW!\"\n",
    "  }\n",
    "  },\n",
    "  {\n",
    "  \"_id\": {\n",
    "    \"$oid\": \"662faf535d5257d23a41da88\"\n",
    "  },\n",
    "  \"username\": \"AlphaDragon\",\n",
    "  \"timestamp\": \"2024-04-29 14:31:47\",\n",
    "  \"message\": \"My public signal: BUY THIS NOW - TICHI GEM!\"\n",
    "  }\n",
    "]\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get signals\n",
    "telegram_signal = get_signals()\n",
    "\n",
    "pprint(telegram_signal)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'jsonrpc': '2.0',\n",
      " 'result': [{'message': 'My public signal: BUY THIS NOW - TICHI GEM!',\n",
      "             'signal_type': 'user-signal',\n",
      "             'timestamp': '2024-04-29 14:31:47',\n",
      "             'username': 'AlphaDragon'},\n",
      "            {'message': {'some_field': 'BUY NOW!',\n",
      "                         'token_address': 'example',\n",
      "                         'token_market_cap': 141010},\n",
      "             'signal_type': 'user-signal',\n",
      "             'timestamp': '2024-04-29 14:31:46',\n",
      "             'username': 'ErectorSpammer5000'}]}\n"
     ]
    }
   ],
   "source": [
    "# get user signals\n",
    "user_signals = get_signals(signal_type=\"user-signal\")\n",
    "\n",
    "pprint(user_signals)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'jsonrpc': '2.0',\n",
      " 'result': [{'message': 'My public signal: BUY THIS NOW - TICHI GEM!',\n",
      "             'signal_type': 'user-signal',\n",
      "             'timestamp': '2024-04-29 14:31:47',\n",
      "             'username': 'AlphaDragon'}]}\n"
     ]
    }
   ],
   "source": [
    "# get specific user signals\n",
    "user_signals = get_signals(signal_type=\"user-signal\", username=\"AlphaDragon\")\n",
    "\n",
    "pprint(user_signals)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Final words\n",
    "\n",
    "This is a simple guide to help you get started with the Overkill API. The API is designed to be simple and easy to use, and this guide should help you get started with using the API to interact with the Overkill platform. \n",
    "\n",
    "You can copy functions from these examples to your Python scripts and use them to interact with the Overkill API."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".venv",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}