📡 Wallet Watchdog API

Use our REST API to manage wallets, access your plan, and receive webhook alerts.

---

🔐 Authentication

Use your token to authenticate all requests. Include it in the Authorization header:

Authorization: Token <your_token>

🔑 Get Token

POST /api/login/

Body:

{
  "username": "you@example.com",
  "password": "yourpassword"
}

Response:

{
  "token": "abc123..."
}

📥 Using Your Token

Once you receive a token, include it in the Authorization header for all authenticated API calls:

Authorization: Token abc123yourtokenvalue

Example: Get user info

GET /api/me/
Authorization: Token abc123yourtokenvalue

Example: Add a wallet

POST /api/wallets/
Authorization: Token abc123yourtokenvalue
Content-Type: application/json

{
  "address": "0xabc...",
  "chain": "eth",
  "notify_url": "https://yourwebhook.site"
}

🔄 Regenerate Token

POST /api/token/refresh/

Description: Invalidates your current token and returns a new one. Requires login via session (not token).

Headers: CSRF token and session cookie

Response:

{
  "token": "new_generated_token_here"
}

---

📬 Endpoints

• GET /api/me/

  Returns info about the authenticated user.

• GET /api/userplan/

  Returns current plan info and wallet usage.

• GET /api/wallets/

  List all tracked wallets for the user.

• GET /api/wallets/0x23....ed70/balance/

  Returns balance change information for given wallet address from your plan

• GET /api/wallets/0x23....ed70/balance_erc20/

  Returns (if selected) balance change information for ERC20 token for the given wallet address from your plan

• POST /api/wallets/

  Add a new wallet to monitor.

  Required headers:

  Authorization: Token your_token

  Body:

  {
    "address": "0xabc...",
    "chain": "eth",
    "notify_url": "optional https://yourdomain.com/webhook",
    "nickname": "optional label"
    }

  Notes:

  • user is automatically assigned to the authenticated user and is not required in the request.
  • chain must be one of: eth, polygon, bsc, or cronos.

  Example response:

  {
    "id": 12,
    "address": "0xabc...",
    "chain": "eth",
    "nickname": "My Wallet",
    "notify_url": "https://yourdomain.com/webhook",
    "created_at": "2025-08-03T07:00:00Z",
    "last_checked": null,
    "latest_balance_info": null
    }

• GET /api/wallets/

  List all tracked wallets for the authenticated user. Each entry includes the most recent balance change info.

  Headers:

  Authorization: Token your_token

  Example response:

  [
    {
      "id": 12,
      "address": "0xabc...",
      "chain": "eth",
      "nickname": "My Wallet",
      "notify_url": "https://yourdomain.com/webhook",
      "created_at": "2025-08-03T07:00:00Z",
      "last_checked": "2025-08-03T07:15:00Z",
      "latest_balance_info": {
        "old_balance": "1000000000000000000",
        "new_balance": "2000000000000000000",
        "timestamp": "2025-08-03T07:14:30Z"
      }
    },
    ...
    ]

---

📤 Webhook Format

When a balance change is detected, a signed POST is sent to your notify_url:

{
  "wallet": "0x123...",
  "chain": "eth",
  "old_balance": "1000000000000000000",
  "new_balance": "2000000000000000000",
  "timestamp": "2025-07-28T12:34:56Z",
  "polls_remaining_today": 1,
  "next_poll_available_at": "2025-07-30T19:38:17.018232+00:00",
  "nickname": "yourwalletnickname"
}

📤 Webhook Format ERC20 token

When a balance change is detected for a token in the related wallet, a signed POST is sent to your notify_url:

{
  "address": "0x5bdf85216ec1e38D6458C870992A69e38e03F7Ef",
  "chain": "eth",
  "old_balance_wei": "45703486876840436093818734800",
  "new_balance_wei": "45393552872051273603818734800",
  "decimals": 18,
  "timestamp": "2025-09-16T11:30:28.581148+00:00",
  "polls_remaining_today": "79",
  "next_poll_available_at": "2025-09-16T11:59:28.581157+00:00",
  "body": "Token balance change: SHIB",
  "nickname": "test tokenfunc",
  "symbol": "SHIB"
}

The signature is in the X-Signature header (HMAC SHA256).