Tweet Alerts REST API: track Twitter/X accounts

The REST API exposes 15 endpoints for managing your Xanguard account programmatically. All endpoints live under a single base URL and return consistent JSON responses.

Base URL

https://api.xanguard.tech/v1

Authentication

All API requests require a Bearer token in the Authorization header. Consumer API keys start with xg_ and are created at xanguard.tech/api-keys (Telegram login); creating a new key revokes the old one. API access requires a paid Tweet Alerts plan — Free-tier keys get 403. New API users are pointed to @B2B_Xanguard_bot: a B2B dt_ key also works on every endpoint on this page and on /v1/ws, and with a dt_ key /v1/accounts manages your B2B handle list.

Authorization Header

Authorization: Bearer xg_your_api_key_here

Response Envelope

Every response from a valid endpoint is wrapped in a standard envelope. On success, the ok field is true and the payload is in data. On error, ok is false and the error message is in error.

JSON — Success response

{
  "ok": true,
  "data": { ... }
}

JSON — Error response

{
  "ok": false,
  "error": "Invalid or expired API key",
  "code": "unauthorized"
}

Rate Limiting

Requests are rate-limited per account (all your keys share the limit) in 1-second windows; the limit scales with your plan. Exceeding it returns 429 with code: "rate_limited" and retry_after: 1 in the body — back off and retry. Error codes on this API are status-derived: unauthorized (401, any key problem), forbidden (403: no paid plan, account or webhook limit reached), bad_request, not_found, rate_limited, server_error. Requests the server can't parse (bad JSON, wrong types, body over 64 KB) get a plain-text 400 / 413 / 415 / 422; unknown paths get an empty 404.

Accounts

Manage your tracked Twitter accounts. Add, remove, configure keywords, and mute/unmute handles.

Method	Path	Description
GET	`/v1/accounts`	List all tracked accounts
POST	`/v1/accounts`	Add accounts (max 25 per request)
GET	`/v1/accounts/{handle}`	Get account detail + profile data
DELETE	`/v1/accounts/{handle}`	Remove an account
PUT	`/v1/accounts/{handle}/keywords`	Set keyword filters (max 20)
DELETE	`/v1/accounts/{handle}/keywords`	Clear all keywords
PUT	`/v1/accounts/{handle}/mute`	Mute or unmute an account
PATCH	`/v1/accounts/{handle}/filters`	Per-account reply/repost/quote filters (`exclude_replies`, `exclude_reposts`, `exclude_quotes`)

GET /v1/accounts

Returns all Twitter accounts you are currently monitoring, along with their keyword filters and mute status. added_at is epoch milliseconds.

Response

JSON

{
  "ok": true,
  "data": {
    "accounts": [
      {
        "handle": "elonmusk",
        "keywords": [],
        "muted": false,
        "is_active": true,
        "exclude_replies": false,
        "exclude_reposts": false,
        "exclude_quotes": false,
        "added_at": 1782248682700,
        "profile": null
      }
    ],
    "count": 1,
    "limit": 10
  }
}

POST /v1/accounts

Add one or more Twitter handles to your monitoring list. Maximum 25 handles per request. Handles are case-insensitive and the @ prefix is optional. Returns 201. Handles that don't exist or are suspended, and any beyond your remaining slots, are skipped silently and appear in neither list; a full plan returns 403.

Request Body

JSON

{
  "handles": ["elonmusk", "VitalikButerin"]
}

Response

JSON

{
  "ok": true,
  "data": {
    "added": ["elonmusk"],
    "already_exists": ["vitalikbuterin"],
    "total": 5,
    "limit": 10
  }
}

GET /v1/accounts/{handle}

Get detailed information about a single tracked account, including profile data (display name, follower count, verification status, and profile picture).

Response

JSON

{
  "ok": true,
  "data": {
    "handle": "elonmusk",
    "keywords": ["bitcoin", "doge"],
    "muted": false,
    "is_active": true,
    "exclude_replies": false,
    "exclude_reposts": false,
    "exclude_quotes": false,
    "added_at": 1782248682700,
    "profile": {
      "display_name": "Elon Musk",
      "followers": 180000000,
      "is_verified": true,
      "profile_pic": "https://pbs.twimg.com/..."
    }
  }
}

DELETE /v1/accounts/{handle}

Remove a Twitter handle from your monitoring list. Keyword filters are kept and come back if you re-add the handle; clear them first with DELETE /v1/accounts/{handle}/keywords. With Profile Watch sync on, the handle is removed there too.

Response

JSON

{
  "ok": true,
  "data": {
    "removed": true,
    "handle": "elonmusk"
  }
}

PUT /v1/accounts/{handle}/keywords

Set keyword filters for a specific account. Only tweets containing at least one of the specified keywords will trigger a Telegram alert. Maximum 20 keywords, 50 characters each. This replaces any existing keywords.

Request Body

JSON

{
  "keywords": ["bitcoin", "solana", "launch"]
}

Response

JSON

{
  "ok": true,
  "data": {
    "handle": "elonmusk",
    "keywords": ["bitcoin", "solana", "launch"]
  }
}

DELETE /v1/accounts/{handle}/keywords

Clear all keyword filters for a specific account. After clearing, all tweets from this account will trigger alerts (subject to global settings).

Response

JSON

{
  "ok": true,
  "data": {
    "handle": "elonmusk",
    "keywords": []
  }
}

PUT /v1/accounts/{handle}/mute

Mute or unmute a tracked account. Muted accounts remain in your list but send no Telegram alerts.

Request Body

JSON

{
  "muted": true
}

Response

JSON

{
  "ok": true,
  "data": {
    "handle": "elonmusk",
    "muted": true
  }
}

PATCH /v1/accounts/{handle}/filters

Set per-account reply/repost/quote filters for Telegram alerts. Accepts exclude_replies, exclude_reposts and exclude_quotes (booleans); the response echoes the request and omitted fields come back as null (= unchanged). An empty body or an untracked handle returns 404.

Request Body

JSON

{
  "exclude_replies": true
}

Response

JSON

{
  "ok": true,
  "data": {
    "handle": "elonmusk",
    "exclude_replies": true,
    "exclude_reposts": null,
    "exclude_quotes": null
  }
}

Settings

Manage your global notification preferences. These settings (and per-account keywords, filters and mute) apply to Telegram alerts; the WebSocket and webhooks ignore them (webhooks use their own filter_handles / filter_keywords).

Method	Path	Description
GET	`/v1/settings`	Get current notification preferences
PATCH	`/v1/settings`	Update preferences (partial update)

Settings Fields

All fields are booleans. The PATCH endpoint accepts partial updates — only include the fields you want to change.

exclude_replies false Skip tweets that are replies to other users.

contracts_only false Only deliver tweets that contain a detected contract address (Solana or ETH).

notifications_paused false Pause Telegram alerts.

exclude_reposts false Skip repost/retweet tweets.

exclude_quotes false Skip quote tweets.

auto_topics true Automatically create a forum topic in your Telegram group for each tracked handle.

contract_topic false Route tweets containing contract addresses to a dedicated "Contracts" forum topic.

GET /v1/settings

Returns your current notification preferences.

Response

JSON

{
  "ok": true,
  "data": {
    "exclude_replies": false,
    "contracts_only": false,
    "notifications_paused": false,
    "exclude_reposts": false,
    "exclude_quotes": false,
    "auto_topics": true,
    "contract_topic": false
  }
}

PATCH /v1/settings

Update one or more notification settings. Only include the fields you want to change. Omitted fields remain unchanged.

Request Body

JSON

{
  "exclude_replies": true,
  "contracts_only": true
}

Response

Returns the full settings object after the update.

JSON

{
  "ok": true,
  "data": {
    "exclude_replies": true,
    "contracts_only": true,
    "notifications_paused": false,
    "exclude_reposts": false,
    "exclude_quotes": false,
    "auto_topics": true,
    "contract_topic": false
  }
}

Subscription

View your current subscription tier and browse available plans.

Method	Path	Description
GET	`/v1/subscription`	Current tier, limits, and expiry
GET	`/v1/plans`	List all available plans

GET /v1/subscription

Returns your current subscription tier, account limit, and expiration date.

Response

JSON

{
  "ok": true,
  "data": {
    "tier": "starter",
    "account_limit": 10,
    "expires_at": "2026-10-06T03:12:45.523620+00:00"
  }
}

GET /v1/plans

Returns the public subscription plans with their prices, account limits, and webhook limits. Note: the list currently includes the plans of every Xanguard product (no product field), not only Tweet Alerts.

Response

JSON

{
  "ok": true,
  "data": {
    "plans": [
      {
        "name": "starter",
        "display_name": "Starter",
        "price_usd": 19.0,
        "account_limit": 10,
        "max_webhooks": 1,
        "duration_hours": 720
      }
    ]
  }
}

The Free plan is not included in this list.