# XCROP — Full Documentation

> Concatenated knowledge base for LLM ingestion. Index: https://xcrop.io/llms.txt · Site: https://xcrop.io

---

# XCROP — X Data Intelligence Platform

XCROP is an X (Twitter) Data Intelligence Platform providing real-time data access, KOL tracking, search, interaction verification, and write capabilities for developers, traders, and analysts.

## What We Do
- **Batch Operations** — Bulk lookup up to 100 users or tweets in a single request
- **KOL Intelligence** — Track any X user, monitor tweets, engagement metrics, follower growth
- **Search & Discovery** — Full-text search across tweets and users, real-time trending topics for 63 countries
- **User Analytics** — Deep profile analysis: followers, following, mentions, replies, media, relationships
- **Write API** — Post tweets, replies, quote-tweets, like, retweet, follow/unfollow programmatically
- **Interaction Check** — Verify retweets, replies, quotes, likes for airdrop/giveaway campaigns
- **Response Caching** — Built-in intelligent caching for faster responses and lower credit usage
- **Boost** — Social media growth services: buy views, likes, followers, comments across 8 platforms (Twitter, Instagram, TikTok, YouTube, Telegram, Discord, Spotify, Twitch) with dripfeed delivery and refill guarantees

## Key Stats
- 39 API endpoints (23 read + 6 interaction check + 10 write)
- Priority support (Pro+)
- Credit-based pricing — 30% cheaper than competitors
- Cursor-based pagination with configurable page sizes

## Platform
- RESTful API with JSON responses
- Bearer token authentication via API keys (format: `xc_live_...`)
- Cursor-based pagination on all list endpoints
- Rate limiting per plan tier (10-600 req/min)
- Response caching with X-Cache HIT/MISS headers
- Dashboard for API key management, usage tracking, billing, referrals, and webhook config
- Full documentation at /docs (27 sections), interactive endpoints at /endpoints

## Website Pages
- **Homepage** (/) — Landing page with hero, stats, features, code examples, live feed (real X data), pricing
- **Docs** (/docs) — Full API documentation with 27 sections, code examples, and 4 guides (Pagination, Credits & Billing, Rate Limits, Error Codes)
- **Endpoints** (/endpoints) — Interactive API endpoints to test all 39 endpoints live with your API key. Features include Batch Operations, Search, User Analytics, Write API, and Interaction Check
- **Blog** (/blog) — Product updates, tutorials, and crypto data insights
- **Dashboard** (/dashboard) — Manage API keys, view usage analytics, billing, referrals, webhooks, X account, and settings
- **Pricing** (/pricing) — Compare plans: Starter free, Basic $4.9/mo, Pro $9.9/mo, Pay as You Go from $2.9
- **Sign in** — Passwordless popup: email one-time code (OTP), Google, or GitHub. There is no password and no separate signup form — signing in with a new email creates the account automatically. The old /auth/login and /auth/signup URLs just redirect to this popup.
- **Status** (/status) — Real-time system status, uptime monitoring, incident history
- **Changelog** (/changelog) — Release notes, new features, improvements, bug fixes
- **FAQ** (/faq) — Frequently asked questions about pricing, rate limits, credits, auth
- **Contact & Community** (/contact) — Contact form for support tickets, sales, partnerships; Community section with GitHub, X (Twitter) links, newsletter signup (/community redirects here)
- **SDKs** (/sdk) — Official JavaScript, Python, Go SDKs with installation guides and code examples
- **API Versioning** (/docs?s=versioning) — API versioning policy, v1→v2 migration, deprecation policy (now a Docs section; /versioning redirects there)

## Features
- **Dark mode** — Dark theme only, optimized for developers
- **API key permissions** — Restrict keys to read-only, write-only, or all access
- **Webhook alerts** — Get notified when credits reach 80%/95%, rate limits hit, or error spikes
- **Newsletter** — Subscribe for weekly developer digest at /contact

## SDKs & Libraries
All 3 official SDKs cover 39 endpoints, with auto-retry (429 + 5xx, exponential backoff), auto-pagination, and MIT license.
- **JavaScript/TypeScript** — `npm install github:xcrop-io/xcrop-js` — `import { XCrop } from '@xcrop/sdk'` — GitHub: github.com/xcrop-io/xcrop-js
- **Python** — `pip install git+https://github.com/xcrop-io/xcrop-python.git` — `from xcrop import XCropClient` (sync) / `from xcrop import AsyncXCropClient` (async) — GitHub: github.com/xcrop-io/xcrop-python
- **Go** — `go get github.com/xcrop-io/xcrop-go` — `xcrop.NewClient("key")` — GitHub: github.com/xcrop-io/xcrop-go. Go requires `context.Context` as first param in all methods
- **cURL** — Direct REST API access with Bearer token authentication
- GitHub Organization: github.com/xcrop-io
- Full SDK docs and examples at /sdk page

## Domain & Contact
- **Website**: xcrop.io
- **API Base URL**: https://xcrop.io/api/v2
- **Support Email**: support@xcrop.io
- **Admin Email**: admin@xcrop.io

---

# API Endpoints — 39 Total

Base URL: `https://xcrop.io/api/v2`

Note: "39" counts the billable data & write endpoints. The 3 account-management endpoints (connect / status / disconnect) are free helpers and are listed here but not part of the 39.

All endpoints require authentication via `Authorization: Bearer xc_live_your_key` header.

## User Endpoints (10)
- `GET /users/{username}` — User profile (18 credits/result, cached 5min)
- `GET /users/{username}/tweets` — User tweets (15 credits/result). Params: count (default 20), sort (latest/popular/engagement, invalid→400), cursor
- `GET /users/{username}/mentions` — Mentions (15 credits/result). Params: count (default 20), sort (latest/popular/engagement, invalid→400), cursor
- `GET /users/{username}/followers` — Followers list (1 credit/result). Params: count (default 20), sort (default/followers/name, invalid→400), cursor
- `GET /users/{username}/followers-ids` — Bulk follower IDs, up to 5,000 per call, no profile metadata (1 credit/result). Params: count (default 5000, max 5000), cursor. For large-scale follower-ID collection (much faster/cheaper than the followers endpoint)
- `GET /users/{username}/following` — Following list (1 credit/result). Params: count (default 20), sort (default/followers/name, invalid→400), cursor
- `GET /users/{username}/replies` — Replies (15 credits/result). Params: count (default 20), sort (latest/popular/engagement, invalid→400), cursor. Note: returns both tweets and replies (like Twitter "Tweets & replies" tab)
- `GET /users/{username}/media` — Media tweets (15 credits/result). Params: count (default 20), sort (latest/popular/engagement, invalid→400), cursor
- `GET /users/{username}/verified-followers` — Blue verified followers (1 credit/result). Params: count (default 20), sort (default/followers/name, invalid→400), cursor
- `POST /users/batch` — Batch lookup up to 100 users (18 credits/result)

## Tweet Endpoints (4)
- `GET /tweets/{tweetId}` — Single tweet (15 credits, cached 2min)
- `GET /tweets/{tweetId}/conversation` — Thread/conversation (15 credits/result)
- `GET /tweets/{tweetId}/quotes` — Quote tweets (15 credits/result)
- `POST /tweets/batch` — Batch lookup up to 100 tweets (15 credits/result)

## Search (2)
- `POST /search` — Search tweets (15 credits/result). Body: `{ "query": "...", "count": 20 }`. Optional filters: `lang` (e.g. "en"), `min_likes`, `min_retweets`, `exclude_replies` (bool), `exclude_retweets` (bool), `since`/`until` (YYYY-MM-DD), `sort` (latest/popular/engagement). `popular` uses Twitter Top search for best results. Invalid sort values return 400. Accepts both `count` and `limit`. Max query length 200 chars
- `POST /search/users` — Search users (18 credits/result). Body: `{ "query": "...", "count": 20 }`. Optional: `sort` (default/followers/name, invalid→400), `cursor` for pagination. Accepts both `count` and `limit`. Max query length 200 chars. Note: `listed` field not available in search results (only in direct user lookup)

## Lists (3)
- `GET /lists/{listId}/tweets` — List tweets (15 credits/result)
- `GET /lists/{listId}/members` — List members (1 credit/result)
- `GET /lists/{listId}/subscribers` — List subscribers (1 credit/result)

## Communities (3) — Under Development
All community endpoints are currently under development. Twitter has restricted access to Communities data through their internal API. These endpoints return 503 with a development notice and will be published as soon as they are ready.
- `GET /communities/{communityId}` — Community details (planned)
- `GET /communities/{communityId}/tweets` — Community tweets (planned)
- `GET /communities/{communityId}/members` — Community members (planned)

## Analytics & Monitoring (1)
- `GET /trending?country=US` — Real-time trending topics by country, 50 per call, 63 countries (100 credits flat, cached 1min)

## User Relationship (1)
- `GET /users/check-follow?source=X&target=Y` — Check follow relationship (50 credits/interaction, cached 5min)

## Write API (13)
Note: All endpoints — including Write API and Interaction Check — are available on EVERY plan, including the free Starter tier, so you can test everything before subscribing. Plans differ only by monthly credits, per-minute rate limit, and credit price (never by which endpoints you can call or how much data an endpoint returns).
Write actions require a connected X account (see Dashboard → X Account) and a residential proxy — a technical requirement, not a plan restriction.
- `POST /account/connect` — Connect X account via credentials or cookies (free)
- `GET /account/status` — Check connection status (free)
- `DELETE /account/disconnect` — Disconnect X account (free)
- `POST /tweets/create` — Post a tweet (100 credits flat)
- `POST /tweets/reply` — Reply to a tweet (100 credits flat)
- `POST /tweets/quote` — Quote-tweet (100 credits flat)
- `DELETE /tweets/{tweetId}` — Delete a tweet (100 credits flat)
- `POST /tweets/{tweetId}/like` — Like a tweet (100 credits flat)
- `DELETE /tweets/{tweetId}/like` — Unlike a tweet (100 credits flat)
- `POST /tweets/{tweetId}/retweet` — Retweet (100 credits flat)
- `DELETE /tweets/{tweetId}/retweet` — Unretweet (100 credits flat)
- `POST /users/{username}/follow` — Follow a user (100 credits flat)
- `DELETE /users/{username}/follow` — Unfollow a user (100 credits flat)

## Interaction Check (5)
Check if a specific user has interacted with a tweet. No connected X account needed — uses pool accounts.
All endpoints require `?username=X` query parameter.
- `GET /tweets/{tweetId}/check-retweet?username=X` — Check if user retweeted (scans user tweets tab, up to 100, 50 credits)
- `GET /tweets/{tweetId}/check-reply?username=X&min_tags=N` — Check if user replied (scans user replies tab, up to 100, 50 credits). Optional `min_tags` (0-20): verify reply tags N friends (excludes tweet author from count)
- `GET /tweets/{tweetId}/check-quote?username=X&min_tags=N` — Check if user quoted (scans user tweets tab, up to 100, 50 credits). Optional `min_tags` (0-20): verify quote tags N friends
- `GET /users/{username}/check-qualified-account?min_followers=N&min_age_days=N` — Eligibility: account has ≥ N followers AND ≥ N days old (from createdAt). Returns `{qualified, followers, accountAgeDays}`. For giveaway/airdrop gating (reads public profile, no connected account) (50 credits)
- `GET /users/{username}/check-qualified-name?contains=X&position=anywhere|left|right` — Eligibility: display name contains text (case-insensitive; left=starts-with, right=ends-with). Returns `{qualified, name}`. For giveaway gating (50 credits)

Response format: `{ data: { retweeted/replied/quoted: boolean, tweetId, username, checkedAt }, meta: { latency_ms } }`
- check-retweet returns `scanned` (number of timeline items checked)
- check-reply returns `replyTweet: { id, text, createdAt }` if found. With `min_tags>0`: adds `tags_required`, `tags_found`, `tags_met`
- check-quote returns `quoteTweet: { id, text, createdAt }` if found. With `min_tags>0`: adds `tags_required`, `tags_found`, `tags_met`
- Use case: giveaway/airdrop/campaign verification

## Response Caching
Some endpoints return cached responses for better performance:
- User profiles: 5 min cache
- Individual tweets: 2 min cache
- Community info: 5 min cache
- Trending topics: 1 min cache
- Relationship checks: 5 min cache
- Response includes `X-Cache: HIT` or `X-Cache: MISS` header

## Common Parameters
- `count` — Number of results per page (up to 1,000 per request on every plan — paginate with the cursor for more). The `followers-ids` bulk endpoint allows up to 5,000 on every plan.
- `cursor` — Pagination cursor for next page (from `meta.next_cursor` in previous response)
- `sort` — Sort order for results:
  - Tweet endpoints (tweets, mentions, replies, media, conversation, quotes, list tweets, community tweets): `latest` (default), `popular`, `engagement`
  - User endpoints (followers, following, verified-followers, list members/subscribers, community members): `default`, `followers`, `name`

## Response Format
- All responses: `{ "data": <array|object>, "meta": { ... } }`
- Tweet object (sanitized): `{ id, text, created_at, author: { id, username, name }, metrics: { likes, retweets, replies, views, bookmarks }, is_reply, is_quote, is_retweet }`
- User object (sanitized): `{ id, username, name, description, followers, following, tweets_count, listed, verified, profile_image, created_at }`
- `created_at` uses Twitter raw format: `"Mon Mar 02 16:01:37 +0000 2026"` (NOT ISO 8601)
- Meta typically includes: `total`, `has_next_page`, `next_cursor`, `latency_ms`

## Pagination
- All list endpoints support cursor-based pagination
- Response includes `meta.next_cursor` field — pass it as `cursor` in next request
- When `meta.next_cursor` is null, no more pages available
- Access cursor: `response.meta.next_cursor` (NOT `response.next_cursor`)
- See /docs → Pagination guide for code examples in JS, Python, and Go

---

# Authentication

## Account Creation & Sign-In (Passwordless)
- **Email one-time code (OTP)** — Enter your email in the sign-in popup, receive a 6-digit code (15 min expiry), and you're in. If no account exists yet, it's created automatically — there is NO separate signup form and NO password.
- **Google** — One-click sign in with Google
- **GitHub** — One-click sign in with GitHub
- There are no passwords anywhere on XCROP (passwordless by design, like claude.ai). The old /auth/login, /auth/signup, /auth/forgot-password and /auth/reset-password pages just redirect to the sign-in popup.

## Two-Factor Authentication (2FA)
- Optional TOTP-based 2FA via authenticator app (Google Authenticator, Authy, etc.)
- Enable in Dashboard → Settings → Security
- When enabled, sign-in asks for the TOTP code after the email code/OAuth step
- Rate limited: max 5 verification attempts per 15 minutes

## API Keys
- Generated in Dashboard → API Keys tab
- Format: `xc_live_` prefix + random string (e.g. `xc_live_abc123def456...`)
- Use as Bearer token: `Authorization: Bearer xc_live_your_api_key`
- Or use X-API-Key header: `X-API-Key: xc_live_your_api_key`
- Multiple keys supported per account; each key can be scoped (read / write / all)
- Keys can be revoked/regenerated anytime
- Each key tracks its own usage stats and last-used timestamp

## Authentication for API Calls
```
Authorization: Bearer xc_live_your_api_key_here
```
Or:
```
X-API-Key: xc_live_your_api_key_here
```

**All API endpoints require authentication.** Requests without a valid API key return 401 Unauthorized.

**Using SDKs:** The official SDKs (JS, Python, Go) handle authentication automatically — just pass your API key when creating the client:
- JS: `new XCrop('xc_live_...')`
- Python: `XCropClient('xc_live_...')` or `AsyncXCropClient('xc_live_...')`
- Go: `xcrop.NewClient("xc_live_...")`

## Session Auth (Endpoints)
- The API Endpoints at /endpoints uses your browser session automatically — no API key needed for testing
- Session-based auth works for same-origin calls only
- The Endpoints page has a built-in sign-in popup (email code / Google / GitHub) — no need to leave the page

## Security Features
- Passwordless sign-in — no passwords stored or transmitted, so nothing to leak or reset
- Email one-time codes expire after 15 minutes and are rate limited
- Optional TOTP 2FA for accounts that want an extra factor
- Cloudflare Turnstile CAPTCHA protects the sign-in flow
- Disposable/temporary email addresses blocked at sign-in
- API keys stored as SHA-256 hashes (original key shown only once at creation)

---

# Write API — Post, Reply, Quote, Delete, Like, Retweet, Follow

The Write API lets you perform actions on X/Twitter through your connected account.

## Setup — Connect Your X Account

**A residential proxy is required.** All write operations are routed through your proxy to protect your account from detection. You must provide a working proxy URL when connecting.

### Method 1: Credentials (recommended)
1. Go to Dashboard → X Account tab, or use the API
2. `POST /api/v2/account/connect` with `{ "email": "...", "password": "...", "proxy": "http://user:pass@host:port" }`
3. Optional: provide `totp_secret` for seamless auto-login when session expires
4. Credentials encrypted with AES-256-GCM and stored securely
5. Sessions auto-refresh when they expire (re-login using stored credentials)

### Method 2: Cookies
1. `POST /api/v2/account/connect` with `{ "auth_token": "...", "ct0": "...", "proxy": "http://user:pass@host:port" }`
2. Extract `auth_token` and `ct0` from your browser's Twitter cookies
3. No auto-refresh — when cookies expire, you must provide new ones
4. Useful if you don't want to store email/password

### Proxy Requirements
- **Required**: A proxy URL must be provided when connecting — requests without a proxy are rejected
- **Format**: `http://user:pass@host:port` or `socks5://user:pass@host:port`
- **Recommended**: Residential proxies for best reliability and lowest detection risk
- **Validation**: Proxy is checked for liveness before the connection is accepted
- **Usage**: All write operations (create, reply, quote, delete, like, retweet, follow, etc.) are automatically routed through your proxy
- **Stored securely**: Proxy URL is encrypted with AES-256-GCM alongside your credentials

Rate limit: max 5 connect attempts per hour.

## Endpoints

### Create a Tweet
`POST /api/v2/tweets/create`
```json
{ "text": "Hello from XCROP API!" }
```
- Max 280 characters for regular tweets
- Over 280 characters automatically uses Twitter's Note Tweet feature (up to 25,000 chars for premium accounts)
- Cost: 100 credits flat

### Reply to a Tweet
`POST /api/v2/tweets/reply`
```json
{ "text": "Great thread!", "tweet_id": "1234567890" }
```
- Cost: 100 credits flat

### Quote-Tweet
`POST /api/v2/tweets/quote`
```json
{ "text": "Interesting take", "quoted_tweet_id": "1234567890" }
```
- Cost: 100 credits flat

### Delete a Tweet
`DELETE /api/v2/tweets/{tweetId}`
- Can only delete your own tweets
- Cost: 100 credits flat

### Like a Tweet
`POST /api/v2/tweets/{tweetId}/like`
- Cost: 100 credits flat

### Unlike a Tweet
`DELETE /api/v2/tweets/{tweetId}/like`
- Cost: 100 credits flat

### Retweet
`POST /api/v2/tweets/{tweetId}/retweet`
- Cost: 100 credits flat

### Unretweet
`DELETE /api/v2/tweets/{tweetId}/retweet`
- Cost: 100 credits flat

### Follow a User
`POST /api/v2/users/{username}/follow`
- Username is resolved to user ID automatically
- Cost: 100 credits flat

### Unfollow a User
`DELETE /api/v2/users/{username}/follow`
- Cost: 100 credits flat

### Check Follow Relationship
`GET /api/v2/users/check-follow?source=elonmusk&target=VitalikButerin`
- Returns whether source follows target and target follows source
- Read-only — does not require a connected X account or proxy
- Cost: 50 credits (interaction rate)

### Check Retweet / Reply / Quote (read-side — verify engagement)
IMPORTANT: These DEDICATED endpoints DO exist. They are READ endpoints (no connected X account needed), separate from the write actions above — use them to verify whether a user already retweeted/replied/quoted a tweet (e.g. "did user X retweet tweet Y?"), typically for airdrop/giveaway verification:
- `GET /api/v2/tweets/{tweetId}/check-retweet?username=X` — did user X retweet this tweet?
- `GET /api/v2/tweets/{tweetId}/check-reply?username=X&min_tags=N` — did user X reply? (optional `min_tags` verifies the reply tags N friends)
- `GET /api/v2/tweets/{tweetId}/check-quote?username=X&min_tags=N` — did user X quote this tweet?
- Cost: 50 credits each (interaction rate). Available on every plan, including the free Starter tier.
- Disambiguation: the WRITE `retweet` action POSTS a retweet from your connected account; the READ `check-retweet` endpoint VERIFIES whether someone already retweeted. Both exist — never say check-retweet is unavailable.

## Account Management
- `POST /api/v2/account/connect` — Connect account with proxy (free)
- `GET /api/v2/account/status` — Check connection status + proxy configured (free)
- `DELETE /api/v2/account/disconnect` — Disconnect and remove all stored credentials + proxy (free)

## Common Issues
- **"A proxy is required"**: You must provide a residential proxy URL in the `proxy` field when connecting
- **"Proxy is not reachable"**: Check that your proxy is online, credentials correct, and supports HTTPS traffic
- **"Invalid proxy URL format"**: Use format `http://user:pass@host:port` or `socks5://user:pass@host:port`
- **"X account not connected"**: Go to Dashboard → X Account tab and connect your account first
- **"Session expired"**: The system auto-refreshes sessions for credential-based accounts. Cookie-based accounts need new cookies manually.
- **Tweet failed**: Check that your account is not restricted/suspended on Twitter
- **2FA issues**: Make sure you provided the correct TOTP secret (the base32 string from your authenticator setup), not a one-time 6-digit code
- **Rate limited by Twitter**: The Write API may hit Twitter's own rate limits. Wait a few minutes and retry.

---

# Pricing — Credit-Based System

All API calls consume credits. XCROP is 30% cheaper than competitors (e.g., twitterapi.io).

## Plans

| Plan | Price | Credits/month | Rate Limit | Credit Price |
|------|-------|---------------|------------|--------------|
| Starter | Free | 5,000 | 10 req/min | — (free) |
| Basic | $4.90/mo | 700,000 | 30 req/min | $0.007 / 1K |
| Pro | $9.90/mo | 2,000,000 | 60 req/min | $0.005 / 1K |
| Pay as You Go | From $2.9 | Buy packs | 30 req/min | From $0.005 / 1K |

Note: every plan can call all endpoints and gets the same per-request result limit (up to 1,000; paginate with the cursor for more) — plans differ ONLY by the three columns above.

## Credit Costs Per Result

- **Tweet data**: 15 credits/result (search, timeline, conversation, quotes)
- **Profile data**: 18 credits/result (user profile, batch users)
- **Follower/following**: 1 credit/result (followers, following, verified-followers)
- **Interaction check**: 50 credits flat (check-retweet, check-reply, check-quote, relationship)
- **Write operations**: 100 credits flat (tweet, reply, quote, delete, like, retweet, follow)
- **Analytics/monitoring**: 100 credits flat (trending topics by country)
- **Minimum**: 10 credits per API call (even if 0 results)

## Credit Calculation
Credits = max(10, resultCount × creditRate)
Example: Fetching 50 followers = 50 × 10 = 500 credits

## Response Headers
Every API response includes usage headers:
- `X-RateLimit-Remaining` — Rate limit requests remaining (per-minute)
- `X-Response-Time` — Request latency
- `X-MaxResults-Allowed` — Max results per request (1,000 for all plans; list endpoints)
- `X-Cache` — Cache status (user profile endpoint only)

## Top-Up Credit Packs
Available to all plans (including Starter via referral rewards). Credits never expire.
- Top-up credits are used only after monthly plan credits are exhausted
- Pay-as-you-go users use credit packs directly
- Referral reward credits (1K signup + 40K purchase) are added as top-up credits
- Available packs: 400K ($2.9), 1M ($6.5), 2M ($12), 5M ($27.5), 10M ($50), 50M ($225)
- Purchase at /checkout?plan=payg or from the Dashboard billing section
- When both plan credits and top-up credits are exhausted, API returns 429 with upgrade/topup suggestions

## Boost Credits
- Boost (social media growth) services use your **top-up credits** (not monthly plan credits)
- 1,000 credits = $1.00 USD for Boost services
- Buy credit packs at /checkout?plan=payg to fund Boost orders
- Boost pricing varies per service — see the Boost page for per-service rates
- Credits used for Boost are the same credits used for API calls (shared balance)

## Upgrade
- Go to /pricing or /checkout to upgrade your plan
- Payment via Stripe (card) or cryptocurrency (USDT BEP-20, USDC BEP-20, SOL, POL).
- Credits reset monthly on billing date
- Unused plan credits do not roll over (top-up credits do)

## Plan Features
IMPORTANT: EVERY plan (including free Starter) can call ALL endpoints — read, Write API, and Interaction Check. Plans are NOT differentiated by which endpoints you can access; they differ only by monthly credits, per-minute rate limit, and credit price. This lets anyone fully test the product on the free tier before subscribing.
- **Starter (Free)**: 5,000 credits/month, ALL endpoints (read + Write API + Interaction Check), community support
- **Basic ($4.9/mo)**: 700K credits/month, ALL endpoints, $0.007/1K credits (30% cheaper than twitterapi.io)
- **Pro ($9.9/mo)**: 2M credits/month, ALL endpoints, 60 req/min, $0.005/1K credits (50% cheaper), priority support
- **Pay as You Go**: Buy credit packs on demand (from $2.9 for 400K credits), credits never expire, Write API, priority support. Packs: 400K/$2.9, 1M/$6.5, 2M/$12, 5M/$27.5, 10M/$50, 50M/$225 (down to $0.0045/1K = over 50% cheaper than twitterapi.io). Credits never expire

---

# Payment Methods

## Credit Card (Stripe)
- Visa, Mastercard, and other major cards supported via Stripe
- Instant plan activation upon successful payment
- Recurring monthly billing with auto-renewal
- Manage subscription via Stripe customer portal (Dashboard → Billing)

## Cryptocurrency — Supported Chains

### USDT BEP-20 (BNB Smart Chain) — Recommended
- Lowest fees (< $0.01)
- Fastest confirmation (~15s)
- Most popular option
- Chain color: `#f0b90b` (Binance yellow)

### USDC BEP-20 (BNB Smart Chain)
- Same network as USDT BEP-20
- Low fees (< $0.01)
- Shares same wallet address as USDT BEP-20
- Chain color: `#2775ca` (USDC blue)

### SOL (Solana)
- Ultra-low fees (< $0.001)
- Fast confirmation (~5s)
- 2% tolerance for price fluctuation
- Chain color: `#9945ff` (Solana purple)
- RPC: Helius (mainnet.helius-rpc.com) — reliable, high rate limit
- **Important**: All SOL operations use `tweetnacl` + raw JSON-RPC (not @solana/web3.js) — lightweight, no server blocking
- Forwarding: raw transaction built manually + ed25519 signing via tweetnacl

### POL (Polygon)
- Low fees (< $0.01)
- Fast confirmation (~5s)
- 2% tolerance for price fluctuation
- Chain color: `#8247e5` (Polygon purple)

**Note:** Only USDT BEP-20, USDC BEP-20, SOL, and POL are currently offered. Bitcoin (BTC) and ETH mainnet are not supported.

## Crypto Payment Architecture

### HD Wallet System
- **Mnemonic**: stored securely on the server (never exposed to clients)
- **Gas funder** (index 0): dedicated wallet that funds BNB gas for child wallets when forwarding tokens
- Each payment gets a **unique derived child wallet** from master HD mnemonic (BIP-44)
- No amount/timing conflicts — wallet starts at 0 balance, any deposit = payment received
- EVM chains (BSC, Polygon): `m/44'/60'/0'/0/{index}` via ethers.js
- SOL: `sha256(mnemonic:sol:{index})` → ed25519 keypair

### Verification Flow
1. **Balance check first** — single fast RPC call, short-circuits if no deposit
2. **TX hash lookup** — get signatures/logs for explorer link
3. **Amount tolerance** — USDT/USDC 0.5%, SOL/POL 2%
4. **Race condition prevention** — `verifyLock` ref on client, atomic `updateMany` on server
5. **Double-credit prevention** — `existing.status !== 'confirmed'` check before user plan update

### Chain-Specific Verification
- **BEP-20 (USDT/USDC)**: `eth_call` + `balanceOf` selector → `eth_getLogs` for txHash → BscScan API fallback
- **SOL**: `getBalance` → `getSignaturesForAddress` → `getTransaction` (all via Helius JSON-RPC, raw fetch)
- **POL**: `eth_getBalance` → scan recent blocks for txHash → Polygonscan API fallback

### Fund Forwarding (child → main wallet)
- **EVM chains** (USDT/USDC/POL): Forward immediately in request handler (fast, lightweight ethers.js)
  - BEP-20 tokens: 2-step (fund BNB gas from main → transfer token) + sweep leftover BNB
  - POL: native transfer with gas estimation, fallback RPC
- **SOL**: Immediate via tweetnacl + raw RPC (no heavy SDK, no WebSocket)
- Cron route: `GET /api/cron/crypto-verify` handles both verification polling and forwarding

### Network Fee Handling
- Small forwarding fee added to payment amount (skip if < $0.20)
- USDT/USDC BEP-20: ~$0.05, POL: ~$0.01, SOL: ~$0.01

## Crypto Payment Flow
1. Select plan at /pricing → Choose "Pay with Crypto"
2. Select your preferred chain (USDT BEP-20 recommended)
3. Unique child wallet address generated (valid for 30 minutes)
4. Send exact amount shown (includes network forwarding fee if applicable)
5. Auto-poll every 10s (for confirming/partial status) checks blockchain balance
6. Manual "I've sent the payment" button triggers instant verification (with lock to prevent double-call)
7. Plan activates immediately upon confirmation — credits reset to 0 for the new plan
8. Redirecting screen shown briefly (spinner + "Payment confirmed — redirecting...")
9. Success page: calls `updateSession()` then redirects via `window.location.href` (full reload for JWT refresh)
10. Receipt email + Telegram alert sent (fire-and-forget)
11. Funds forwarded from child → main wallet (EVM: immediate, SOL: cron)

## Tolerance
- **USDT/USDC**: 0.5% tolerance (covers minor rounding)
- **SOL/POL**: 2% tolerance (covers gas/network fee variance)

## Common Payment Issues

### Payment Not Detected
- Wait for blockchain confirmations: 1-3 min for USDT/USDC/POL, ~5s for SOL
- Click "Verify Payment" button to manually trigger verification
- Make sure you sent to the correct wallet address and correct chain
- Max 20 manual verify attempts per payment

### Underpaid (Partial Payment)
- Status changes to `partial` — user can send the remaining amount
- Partial payments don't expire (timer extends automatically)
- Balance is re-checked on each verify — cumulative deposits count

### Expired
- The 30-minute payment window passed
- Create a new payment — a fresh wallet address will be generated
- Previous wallet address is no longer monitored

### Dashboard Not Showing Updated Plan
- NextAuth JWT session is cached — requires full page reload to refresh
- Success page uses `window.location.href` (not `router.push`) to force reload
- `updateSession()` triggers JWT callback which fetches fresh plan from DB

### Which Chain Is Best?
USDT BEP-20 is recommended — lowest fees and fastest confirmation.

### Plan Upgrade & Credits
- When upgrading (e.g. Basic → Pro), credits reset to 0 for the new plan cycle
- The new plan's full credit allowance starts immediately
- Billing period: from payment confirmation to exactly 1 month later (shown in dashboard)
- Top-up credits carry over across plan changes (they never expire)

### Invoice History (Dashboard → Billing)
- All payments (crypto and card) shown in a single table
- Crypto payments include TX ID with link to blockchain explorer (BscScan, Solscan, PolygonScan)
- Invoice number format: `CRYPTO-XXXXXXXX` for crypto, Stripe invoice number for card
- Shows payment method badge (USDT BEP-20, USDC BEP-20, SOL, POL, Card)

### Refunds
- Refunds available within 7 days of purchase for unused credits
- Contact support@xcrop.io for refund requests
- Crypto payments are non-refundable after plan activation (due to blockchain finality)

---

# Code Examples — Quick Start

## JavaScript / Node.js

```javascript
const API_KEY = 'xc_live_your_api_key';
const BASE = 'https://xcrop.io/api/v2';

// Get user profile
const res = await fetch(BASE + '/users/elonmusk', {
  headers: { 'Authorization': 'Bearer ' + API_KEY }
});
const data = await res.json();
console.log(data);

// Search tweets
const search = await fetch(BASE + '/search', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ query: '$BTC', count: 20 })
});
const results = await search.json();

// Create a tweet (requires connected X account)
const tweet = await fetch(BASE + '/tweets/create', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ text: 'Hello from XCROP!' })
});
```

## Python

```python
import requests

API_KEY = 'xc_live_your_api_key'
BASE = 'https://xcrop.io/api/v2'
headers = {'Authorization': f'Bearer {API_KEY}'}

# Get user profile
r = requests.get(f'{BASE}/users/elonmusk', headers=headers)
print(r.json())

# Search tweets
r = requests.post(f'{BASE}/search',
    headers={**headers, 'Content-Type': 'application/json'},
    json={'query': '$BTC', 'count': 20})
print(r.json())

# Batch user lookup
r = requests.post(f'{BASE}/users/batch',
    headers={**headers, 'Content-Type': 'application/json'},
    json={'usernames': ['elonmusk', 'VitalikButerin', 'caborneaux']})
print(r.json())

# Like a tweet
r = requests.post(f'{BASE}/tweets/1234567890/like', headers=headers)
print(r.json())
```

## cURL

```bash
# Get user profile
curl -H "Authorization: Bearer xc_live_your_api_key" \
  https://xcrop.io/api/v2/users/elonmusk

# Search tweets
curl -X POST \
  -H "Authorization: Bearer xc_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "$ETH", "count": 10}' \
  https://xcrop.io/api/v2/search

# Get tweet by ID
curl -H "Authorization: Bearer xc_live_your_api_key" \
  https://xcrop.io/api/v2/tweets/1234567890

# Follow a user
curl -X POST \
  -H "Authorization: Bearer xc_live_your_api_key" \
  https://xcrop.io/api/v2/users/elonmusk/follow


# Check if user retweeted a tweet
curl -H "Authorization: Bearer xc_live_your_api_key" \
  "https://xcrop.io/api/v2/tweets/1893045621038174208/check-retweet?username=elonmusk"

# Check if user replied (with min 2 friend tags)
curl -H "Authorization: Bearer xc_live_your_api_key" \
  "https://xcrop.io/api/v2/tweets/1893045621038174208/check-reply?username=elonmusk&min_tags=2"

# Check if user quoted
curl -H "Authorization: Bearer xc_live_your_api_key" \
  "https://xcrop.io/api/v2/tweets/1893045621038174208/check-quote?username=elonmusk"
```

## Go

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

var (
	apiKey = os.Getenv("XCROP_API_KEY")
	base   = "https://xcrop.io/api/v2"
)

func xcropGet(path string) (map[string]interface{}, error) {
	req, _ := http.NewRequest("GET", base+path, nil)
	req.Header.Set("Authorization", "Bearer "+apiKey)
	resp, err := http.DefaultClient.Do(req)
	if err != nil { return nil, err }
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	var result map[string]interface{}
	json.Unmarshal(body, &result)
	return result, nil
}

func xcropPost(path string, data interface{}) (map[string]interface{}, error) {
	b, _ := json.Marshal(data)
	req, _ := http.NewRequest("POST", base+path, bytes.NewReader(b))
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil { return nil, err }
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	var result map[string]interface{}
	json.Unmarshal(body, &result)
	return result, nil
}

// Get user profile
result, _ := xcropGet("/users/elonmusk")
user := result["data"].(map[string]interface{})
fmt.Printf("%s — %.0f followers\n", user["name"], user["followers"])

// Search tweets
result, _ = xcropPost("/search", map[string]interface{}{
	"query": "#bitcoin", "count": 20, "sort": "latest",
})
tweets := result["data"].([]interface{})
for _, t := range tweets {
	tweet := t.(map[string]interface{})
	author := tweet["author"].(map[string]interface{})
	fmt.Printf("@%s: %s\n", author["username"], tweet["text"])
}
```

## Pagination with Cursor

All list endpoints support cursor-based pagination via `count` and `cursor` parameters.
Up to 1,000 per request on every plan — paginate with the cursor for more.

```javascript
let cursor = null;
const allResults = [];

do {
  const url = new URL(BASE + '/users/elonmusk/followers');
  url.searchParams.set('count', '100');
  if (cursor) url.searchParams.set('cursor', cursor);

  const res = await fetch(url, { headers: { 'Authorization': 'Bearer ' + API_KEY } });
  const data = await res.json();

  allResults.push(...data.data);
  cursor = data.meta.next_cursor;
} while (cursor);
```

```python
# Python pagination
cursor = None
results = []

while True:
    params = {"count": 100}
    if cursor:
        params["cursor"] = cursor

    r = requests.get(f"{BASE}/users/elonmusk/followers",
                     headers=headers, params=params)
    data = r.json()
    results.extend(data["data"])
    cursor = data.get("meta", {}).get("next_cursor")
    if not cursor:
        break
```

## Error Handling

```javascript
const res = await fetch(BASE + '/users/elonmusk', {
  headers: { 'Authorization': 'Bearer ' + API_KEY }
});

if (!res.ok) {
  if (res.status === 429) {
    console.log('Rate limited. Wait 60s before retrying.');
  } else {
    const err = await res.json();
    console.error(`Error ${res.status}: ${err.error}`);
  }
} else {
  const data = await res.json();
  console.log(`Rate limit remaining: ${res.headers.get('X-RateLimit-Remaining')}`);
  console.log(`Response time: ${res.headers.get('X-Response-Time')}`);
}
```

## Official SDKs — Quick Start

All SDKs handle auth, retries (429/5xx), and pagination automatically.

### JavaScript/TypeScript SDK

```bash
npm install github:xcrop-io/xcrop-js
```

```javascript
import { XCrop } from '@xcrop/sdk'

const client = new XCrop('xc_live_your_api_key')

// Get user profile
const user = await client.users.get('elonmusk')
console.log(user.data.followers)

// Search tweets
const results = await client.search({ query: '$BTC', count: 20 })

// Auto-pagination
const followers = await client.users.followers('elonmusk', { count: 100 })

// Auto-paginate through all followers
for await (const user of client.paginate.userFollowers('elonmusk')) {
  console.log(user.username)
}
```

### Python SDK

```bash
pip install git+https://github.com/xcrop-io/xcrop-python.git
```

```python
# Sync client
from xcrop import XCropClient

client = XCropClient('xc_live_your_api_key')
user = client.users.get('elonmusk')
print(user.data.followers)

results = client.search(query='$BTC', count=20)

# Async client
from xcrop import AsyncXCropClient
import asyncio

async def main():
    client = AsyncXCropClient('xc_live_your_api_key')
    user = await client.users.get('elonmusk')
    print(user.data.followers)

asyncio.run(main())
```

### Go SDK

```bash
go get github.com/xcrop-io/xcrop-go
```

```go
package main

import (
    "context"
    "fmt"
    "github.com/xcrop-io/xcrop-go"
)

func main() {
    client := xcrop.NewClient("xc_live_your_api_key")
    ctx := context.Background()

    // Get user profile
    user, _ := client.Users.Get(ctx, "elonmusk")
    fmt.Printf("%s — %d followers\n", user.Data.Name, user.Data.Followers)

    // Search tweets (Go requires context.Context as first param)
    results, _ := client.Search(ctx, &xcrop.SearchParams{
        Query: "$BTC",
        Count: 20,
    })
}
```

---

# Developer Setup & Integration Guide

## Quick Start Checklist
1. Click "Sign in" / "Get API Key" to open the passwordless login popup (email one-time code, Google, or GitHub — no password, no separate signup page). The /endpoints page has the same built-in popup.
2. Go to Dashboard -> API Keys -> Create new key
3. Copy key (shown once only!) — format: `xc_live_abc123...`
4. Use header: `Authorization: Bearer xc_live_your_key`
5. Base URL: `https://xcrop.io/api/v2`

## Python Setup

### Install requests
```
pip install requests
```
If permission error:
```
pip install --user requests
```
Or with virtual environment (recommended):
```
python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows
pip install requests
```

### SSL Certificate Errors
```
requests.exceptions.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED]
```
Fixes:
- Update certifi: `pip install --upgrade certifi`
- macOS: Run `Install Certificates.command` from Python folder in Applications
- Corporate proxy: Set `REQUESTS_CA_BUNDLE` env var to your CA cert path
- Last resort (NOT for production): `requests.get(url, verify=False)`

### Proxy / Corporate Firewall
If behind a proxy:
```python
proxies = {"https": "http://proxy.company.com:8080"}
r = requests.get(url, headers=headers, proxies=proxies)
```

### ModuleNotFoundError: No module named 'requests'
- Make sure you installed in the right Python: `python3 -m pip install requests`
- Check virtual env is activated
- VS Code: select correct Python interpreter (Ctrl+Shift+P -> Python: Select Interpreter)

## JavaScript / Node.js Setup

### Node.js fetch (v18+)
Node 18+ has built-in `fetch` — no extra packages needed:
```javascript
const res = await fetch('https://xcrop.io/api/v2/users/elonmusk', {
  headers: { 'Authorization': 'Bearer ' + API_KEY }
});
```

### Older Node.js (< 18)
Install node-fetch:
```
npm install node-fetch
```
```javascript
const fetch = require('node-fetch');
// or ES module: import fetch from 'node-fetch';
```

### axios (alternative)
```
npm install axios
```
```javascript
const axios = require('axios');
const { data } = await axios.get('https://xcrop.io/api/v2/users/elonmusk', {
  headers: { 'Authorization': 'Bearer xc_live_your_key' }
});
```

### CORS Errors (Browser)
XCROP API is backend-only — do NOT call from browser JavaScript directly.
```
Access-Control-Allow-Origin error
```
Fix: Call XCROP API from your backend server, then serve data to your frontend.
```
Browser -> Your Server -> XCROP API (correct)
Browser -> XCROP API (will fail with CORS)
```

### ECONNREFUSED / ETIMEDOUT
- Check internet connection
- Behind VPN? Try disconnecting
- DNS issue: try `curl https://xcrop.io/api/v2/health` to verify

## Go Setup

```go
package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://xcrop.io/api/v2/users/elonmusk", nil)
    req.Header.Set("Authorization", "Bearer xc_live_your_key")
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}
```

## cURL Setup

### Basic request
```bash
curl -H "Authorization: Bearer xc_live_your_key" https://xcrop.io/api/v2/users/elonmusk
```

### Common cURL mistakes
- Missing quotes around header: use `"Authorization: Bearer ..."` not `Authorization: Bearer ...`
- Windows CMD: use double quotes `"`, not single quotes `'`
- PowerShell: use backtick for line continuation, not `\`

## Environment Variables (Best Practice)

Never hardcode API keys in source code!

### .env file
```
XCROP_API_KEY=xc_live_your_key_here
```

### Python (python-dotenv)
```
pip install python-dotenv
```
```python
from dotenv import load_dotenv
import os
load_dotenv()
API_KEY = os.getenv('XCROP_API_KEY')
```

### Node.js (dotenv)
```
npm install dotenv
```
```javascript
require('dotenv').config();
const API_KEY = process.env.XCROP_API_KEY;
```

### Add .env to .gitignore!
```
# .gitignore
.env
```

## Common Mistakes

### Wrong auth header format
- Wrong: `Authorization: xc_live_abc123` (missing "Bearer")
- Wrong: `Authorization: Bearer "xc_live_abc123"` (extra quotes)
- Correct: `Authorization: Bearer xc_live_abc123`

### Using GET instead of POST
- Search endpoints require POST with JSON body
- `POST /search` with `{"query": "..."}` — NOT `GET /search?query=...`

### Missing Content-Type for POST
When sending JSON body, always include:
```
Content-Type: application/json
```

### JSON body as string (Python)
- Wrong: `requests.post(url, data='{"query": "BTC"}')` — sends as form data
- Correct: `requests.post(url, json={"query": "BTC"})` — auto-sets Content-Type

### Response parsing
- Always check `res.ok` / `res.status_code` before parsing JSON
- Rate limit info in headers: `X-RateLimit-Remaining`, `X-Response-Time`, `X-Cache`

---

# XCROP Boost — Social Media Growth Services

XCROP Boost is a social media growth service built into the XCROP platform. It lets you buy views, likes, followers, comments, and more across 8 major platforms — all paid with XCROP credits.

## Supported Platforms

| Platform | Available Services |
|----------|-------------------|
| Twitter / X | Views, Likes, Followers, Retweets, Custom Comments |
| Instagram | Post Likes, Followers, Reel Views, Custom Comments |
| TikTok | Video Views, Likes, Followers, Shares |
| YouTube | Video Views, Likes, Subscribers |
| Telegram | Group Members, Post Views, Reactions |
| Discord | Server Members |
| Spotify | Track Plays, Followers |
| Twitch | Followers, Video Views |

## Credit System

Boost uses the same XCROP credit system:
- **1,000 credits = $1.00 USD**
- Credits are deducted from your top-up (extra) credits balance
- Buy credit packs at /checkout?plan=payg (400K/$2.9, 1M/$6.5, 2M/$12, 5M/$27.5, 10M/$50, 50M/$225)
- Credits never expire

## Pricing Overview (per 1,000 units)

### Twitter / X
| Service | Rate (per 1K) | Min | Max | Refill | Dripfeed |
|---------|--------------|-----|-----|--------|----------|
| Tweet Views | $0.008 (8 credits) | 100 | 10M | No | Yes |
| Tweet Likes | $4.00 (4,000 credits) | 10 | 10K | 30-day | Yes |
| Followers | $1.25 (1,250 credits) | 10 | 1M | 30-day | Yes |
| Retweets | $0.85 (850 credits) | 10 | 1M | 30-day | Yes |
| Custom Comments | $42.00 (42,000 credits) | 50 | 35M | 30-day | No |

### Instagram
| Service | Rate (per 1K) | Min | Max | Refill | Dripfeed |
|---------|--------------|-----|-----|--------|----------|
| Post Likes | $0.23 (230 credits) | 10 | 500K | No | Yes |
| Followers | $1.00 (1,000 credits) | 10 | 1M | 30-day | Yes |
| Reel Views | $0.011 (11 credits) | 100 | 100M | No | Yes |
| Custom Comments | $1.45 (1,450 credits) | 10 | 500K | No | No |

### TikTok
| Service | Rate (per 1K) | Min | Max | Refill | Dripfeed |
|---------|--------------|-----|-----|--------|----------|
| Video Views | $0.009 (9 credits) | 100 | 10M | No | No |
| Likes | $0.035 (35 credits) | 10 | 5M | 30-day | Yes |
| Followers | $1.20 (1,200 credits) | 10 | 100M | 30-day | Yes |
| Shares | $0.055 (55 credits) | 10 | 10M | No | No |

### YouTube
| Service | Rate (per 1K) | Min | Max | Refill | Dripfeed |
|---------|--------------|-----|-----|--------|----------|
| Video Views | $0.90 (900 credits) | 100 | 1M | 365-day | Yes |
| Likes | $0.50 (500 credits) | 10 | 10K | 30-day | Yes |
| Subscribers | $17.00 (17,000 credits) | 10 | 100K | 30-day | Yes |

### Telegram
| Service | Rate (per 1K) | Min | Max | Refill | Dripfeed |
|---------|--------------|-----|-----|--------|----------|
| Group Members | $0.53 (530 credits) | 10 | 40K | 30-day | Yes |
| Post Views | $0.0025 (2.5 credits) | 10 | 500K | No | Yes |
| Reactions | $0.05 (50 credits) | 10 | 4M | No | Yes |

### Discord
| Service | Rate (per 1K) | Min | Max | Refill | Dripfeed |
|---------|--------------|-----|-----|--------|----------|
| Server Members | $9.50 (9,500 credits) | 50 | 20K | No | No |

### Spotify
| Service | Rate (per 1K) | Min | Max | Refill | Dripfeed |
|---------|--------------|-----|-----|--------|----------|
| Track Plays | $0.22 (220 credits) | 500 | 20M | 365-day | Yes |
| Followers | $0.36 (360 credits) | 100 | 100M | 30-day | Yes |

### Twitch
| Service | Rate (per 1K) | Min | Max | Refill | Dripfeed |
|---------|--------------|-----|-----|--------|----------|
| Followers | $0.27 (270 credits) | 50 | 10K | 30-day | Yes |
| Video Views | $0.28 (280 credits) | 20 | 10K | No | Yes |

## How to Place an Order

1. Go to **Boost** page (or /boost)
2. Select a **platform** (Twitter, Instagram, TikTok, etc.)
3. Choose a **service** (views, likes, followers, etc.)
4. Enter the **link** to the post, profile, or channel you want to boost
5. Set the **quantity** (within the min/max range for that service)
6. Optionally choose a **dripfeed speed** to spread delivery over time
7. For comment services, enter your **custom comment text** (one comment per line)
8. Review the **total cost** in credits and click **Place Order**
9. Credits are deducted immediately and delivery begins

## Dripfeed Delivery

Dripfeed spreads your order over time for natural-looking growth instead of delivering everything at once.

**Available speeds:**
| Speed | Duration |
|-------|----------|
| Instant | All at once (default) |
| 1 hour | Spread over 1 hour |
| 3 hours | Spread over 3 hours |
| 6 hours | Spread over 6 hours |
| 12 hours | Spread over 12 hours |
| 24 hours | Spread over 24 hours |
| 3 days | Spread over 3 days |
| 7 days | Spread over 7 days |

- Not all services support dripfeed — check the "Dripfeed" column in pricing tables
- The system splits your order into multiple batches delivered at intervals
- You can track batch progress in the order details

## Refill Guarantee

Many services include a **refill guarantee** — if the count drops after delivery, we automatically top it up at no extra cost.

- **30-day refill**: Most follower, like, and retweet services
- **365-day refill**: YouTube views and Spotify plays
- Services marked "No refill" do not offer this guarantee
- To request a refill: go to your order in the Dashboard and click **Request Refill**, or use the API
- Refill is available for orders with status "completed" or "partial"
- Only one refill request can be pending at a time per order

## Order Statuses

| Status | Meaning |
|--------|---------|
| `pending` | Order received, waiting to start |
| `processing` | Order sent to provider, delivery starting |
| `in_progress` | Delivery is actively happening |
| `completed` | Full quantity delivered |
| `partial` | Only part of the order was delivered (remainder may be refunded) |
| `cancelled` | Order was cancelled and credits refunded |
| `refunded` | Credits returned to your account |

## Cancellation & Refunds

- You can cancel orders that are still in **pending** or **processing** status
- Go to your order in the Dashboard and click **Cancel**, or use the API
- Credits are refunded immediately to your top-up balance
- Orders that are already **in_progress**, **completed**, or **partial** cannot be cancelled
- For partial orders, contact support for a partial refund

## Boost API (for Developers)

All Boost endpoints require API key authentication (`Authorization: Bearer xc_live_...`).

### List Services
```
GET /api/v2/boost/services
```
Returns all available services, platforms, dripfeed presets, and pricing. No authentication required.

### Place Order
```
POST /api/v2/boost/order
Body: { "service_id": "tw-views-1", "link": "https://x.com/...", "quantity": 1000, "dripfeed": "instant" }
```
- `service_id` — from the services list (e.g. `tw-views-1`, `ig-followers-1`)
- `link` — URL of the post/profile/channel to boost
- `quantity` — number of views/likes/followers to deliver
- `dripfeed` — optional: `"instant"`, `"3h"`, `"6h"`, `"12h"`, `"24h"`, `"3d"`, `"7d"`
- `comments` — required for comment services: array of comment strings

### Check Order Status
```
GET /api/v2/boost/status?order_id=xxx
```
Returns order details, status, delivery progress, and dripfeed batch info.

### List Recent Orders
```
GET /api/v2/boost/status?limit=50
```
Returns your recent boost orders (max 100).

### Cancel Order
```
POST /api/v2/boost/cancel
Body: { "order_id": "xxx" }
```
Cancels a pending/processing order and refunds credits.

### Request Refill
```
POST /api/v2/boost/refill
Body: { "order_id": "xxx" }
```
Requests a refill for a completed/partial order (service must support refill).

## Common Issues & Troubleshooting

### "Insufficient credits"
- You need enough top-up credits to cover the order. Credits cost = (rate per 1K) x (quantity / 1000) x 1000 credits
- Buy credit packs at /checkout?plan=payg

### Order stuck on "processing"
- Most orders start within 0-3 hours. Check the delivery time for your specific service
- Use the status endpoint or Dashboard to check for updates
- If stuck for more than 24 hours, contact support

### Views/followers dropped after delivery
- Some drop is normal (shown in the "Drop Rate" column for each service)
- If the service has refill guarantee, request a refill from your order page
- Refills are free and covered by the original order

### "Cannot cancel order"
- Only orders in "pending" or "processing" status can be cancelled
- Once delivery starts (in_progress), cancellation is not possible

### Content must be public
- The post, profile, or channel you are boosting must be publicly accessible
- Private/protected accounts will cause delivery to fail
- Do not change your username or make content private while an order is active

### Comment service requires comments array
- For custom comment services, you must provide the comment text
- Send `comments: ["comment 1", "comment 2", ...]` in the order body
- The quantity equals the number of comments provided

## Safety & Quality

- All services use high-quality delivery methods designed to look natural
- Dripfeed delivery is recommended for followers and subscribers to mimic organic growth
- Most services are marked "high quality" with real-looking accounts
- We monitor drop rates and adjust providers to maintain quality
- Your account information is never shared with third parties

---

# Dashboard Features

The XCROP Dashboard at /dashboard lets you manage your account, monitor usage, and configure settings.

## Sections (tabs)
- **Usage** (default tab) — Detailed usage analytics: performance stats, billing period progress, daily credit chart (30 days), endpoint breakdown, activity log, export options (CSV/JSON) for any period up to 90 days
- **API Keys** — Create, view, revoke API keys (each key can be scoped read / write / all, prefix `xc_live_`, tracks individual usage & last-used time). Also holds the Quick Start code snippets and Webhooks configuration
- **Billing** — Current plan with badges (ACTIVE, price, extra credits), end date inline with features, invoice history with TX ID links, upgrade/top-up buttons
- **Referrals** — Create, manage, and track referral codes and rewards
- **Settings** — Profile (name, company, timezone), notifications, X Account connect/disconnect (for Write API), Security (TOTP 2FA only — passwordless site), and Danger zone (delete account)

Note: Boost (social growth) is a separate top-level route (/boost), not a dashboard tab, and is currently hidden until launch. Support ticket management is an admin-only tab. Regular users reach the Dashboard only via the gradient button in the sidebar.

## Credits System
- **Monthly credits**: Plan-based, reset every billing cycle (Starter 5K, Basic 700K, Pro 2M)
- **Extra credits** (top-up + referral): Stored separately in DB, never expire, never reset
- When monthly credits run out, extra credits are used automatically (all plans including Starter)
- Dashboard shows monthly and extra credits separately (not combined)
- Sidebar: "X / 700K credits" + "+ 41K extra credits" below progress bar

## Credit Usage Alert
- A banner appears at the top of the Usage tab when you've used >80% of your monthly credits (amber warning) or >95% (red critical)
- Alert is based on monthly credits only (not including extra credits)
- Includes a quick link to upgrade your plan
- Dismissible, but reappears on page reload

## Rate Limit Monitor
- Real-time card showing current requests per minute vs your plan limit
- Color-coded: green (<50%), amber (50-80%), red (>80%)
- Plan limits: Starter 10/min, Basic 30/min, Pro 60/min, PayG 30/min

## Recent Activity & Error Filter
- Shows your latest API calls with method, endpoint, status code, latency, and credits used
- Toggle between "All" and "Errors" tabs to filter only failed requests (status >= 400)
- Error rows highlighted with red tint for quick identification

## Endpoint Breakdown
- Visual breakdown of your API usage by endpoint
- Shows call count, percentage, and color-coded progress bars for top 8 endpoints

## Quick Start Code Examples
- Ready-to-use code snippets in Python, cURL, and JavaScript
- Automatically uses your actual API key in the examples
- Syntax-highlighted code editor with copy button
- If no API key exists, shows a prompt to create one first

## Export Usage Data
- Export your usage data as CSV or JSON from the Usage section
- Configurable period (up to 90 days)
- Includes daily usage breakdown and per-endpoint statistics
- CSV format: date, calls, credits + endpoint, calls, credits, avg_latency_ms

## Webhook Configuration (API Keys tab)
- Configure a webhook URL to receive automated notifications
- Available triggers:
  - Credits usage >80% — early warning before running out
  - Credits usage >95% — critical alert
  - Rate limit hit — when exceeding your plan's per-minute limit
  - Error spike detected — unusual increase in error rates (10+ errors in 5 min)
- Test webhook button to verify your endpoint works
- Webhook sends POST requests with JSON payload
- Includes HMAC-SHA256 signature in `X-Webhook-Signature` header for verification
- Cooldown: credits alerts every 30-60min, rate limit every 5min, error spike every 10min

## Referral Program
- **Dashboard → Referrals tab**: Create, manage, and track referral codes
- Max 5 referral codes per user, each with 15% discount and up to 50 uses
- **For referred users**: 15% off first plan purchase only (Stripe or Crypto). After purchase, discount is consumed and won't apply again
- **For referrers**: 1,000 credits when someone signs up with your code + 40,000 bonus credits when they purchase a plan
- Track total referrals, credits earned, and active discount from the Referrals tab
- Active Discount shows strikethrough (~~15%~~) after the discount has been used
- Click the uses count (e.g. "1/50") to see the list of referred users
- Can also apply referral code during signup or redeem from dashboard
- Code format: `XCROP-XXXXXXXX` (auto-generated)
- Delete codes requires confirmation popup; one referral code per user (can't redeem multiple)

## Support
- Regular users get help via the Contact page (/contact) support form or the live chat widget (bottom-right on every page)
- The contact form creates a support ticket, emails a confirmation with the ticket ID, and notifies the team
- The Dashboard "Support" tab is admin-only — an inbox for staff to reply to chat-escalated tickets, not a user-facing ticket form

---

# Troubleshooting — Common Issues & Solutions

## HTTP Error Codes

### 401 Unauthorized
- Response: `{ "error": "Authentication required. Please provide an API key or log in.", "code": "AUTH_REQUIRED" }`
- Missing or invalid API key
- Fix: Check your `Authorization: Bearer xc_live_your_key` header
- Make sure the key is active (not revoked) in Dashboard → API Keys

### 403 Forbidden
- Access denied — typically means no X account connected (for write endpoints)
- Fix: Connect your X account via `POST /api/v2/account/connect`

### 404 Not Found
- User/tweet/list/community does not exist
- Check for typos in username or ID
- Twitter accounts can be suspended or deleted

### 410 Gone
- Endpoint permanently removed by Twitter
- No fix — this is a Twitter-side change

### 413 Request Too Large
- Request body exceeds size limit
- Fix: Reduce payload size (e.g., fewer images or smaller data)

### 429 Too Many Requests
- Rate limit exceeded for your plan tier
- Rate limits: Starter 10/min, Basic 30/min, Pro 60/min, PayG 30/min
- OR monthly credit allowance exhausted
- Fix: Wait for the rate limit window to reset (1 minute), upgrade plan, or wait for monthly credit reset

### 500 Internal Server Error
- Temporary server issue
- Retry after a few seconds with exponential backoff
- If persistent, contact support

### 503 Service Unavailable
- Twitter API temporarily down or rate limited on our end
- Usually resolves within minutes

## Common Issues

### "Credits exhausted"
- Monthly credit allowance used up AND no top-up credits remaining
- Starter gets 5,000 credits/month, Basic 700K, Pro 2M, PayG buy packs
- Top-up credits (from referral rewards or credit packs) are used automatically after monthly credits run out
- Fix: Upgrade plan at /pricing, buy top-up credits at /checkout?plan=payg, or wait for monthly reset

### "No results returned"
- Account may be private or suspended
- Search query may be too specific — try broader terms

### "Endpoint returns 410 Gone"
- Twitter removed certain endpoints — this is a Twitter-side change, not an XCROP issue

### Write API: "A proxy is required"
- You must provide a residential proxy URL when connecting your X account
- Format: `http://user:pass@host:port` or `socks5://user:pass@host:port`
- Residential proxies are strongly recommended to avoid detection

### Write API: "Proxy is not reachable"
- Check that your proxy is online and credentials are correct
- Make sure the proxy supports HTTPS traffic
- Try a different proxy or contact your proxy provider

### Write API: "X account not connected"
- You need to connect your X account first
- Go to Dashboard → X Account tab → Connect
- Or use API: `POST /api/v2/account/connect` (proxy required)

### Write API: "Session expired"
- For credential-based accounts: system auto-refreshes sessions automatically
- For cookie-based accounts: you need to provide new cookies manually (disconnect → reconnect)
- If persistent, disconnect and reconnect your X account

### Batch endpoint limits
- Maximum 100 items per batch request (users or tweets)
- Use multiple requests for larger batches

### Pagination not working
- Use `cursor` parameter (not `page` or `offset`) — XCROP uses cursor-based pagination
- Pass the `next_cursor` value from previous response as `cursor` in next request
- When `next_cursor` is null, you've reached the end
- Use `count` parameter to control results per page (default 20, up to 1,000 per request on every plan — paginate for more)

### "400 Bad Request"
- Missing required parameters or invalid JSON body
- Check the docs at /docs for required fields for each endpoint

### "409 Conflict"
- Usually means a duplicate pending operation (e.g., duplicate crypto payment, X account already connected)
- Check for existing pending resources before creating new ones
- For crypto: you already have a pending payment — complete or cancel it first

### Crypto: Plan not showing after payment
- Dashboard may show old plan due to session cache
- Fix: Hard refresh the page (Ctrl+Shift+R) to reload the session
- The plan is already active in the database — just needs a session refresh

### Crypto: Payment status stuck on "confirming"
- Blockchain confirmation can take 15s (BSC) to a few minutes
- Click "Verify Payment" to manually trigger check
- For SOL: verification uses Helius RPC — fast and reliable
- If stuck for more than 5 minutes, the cron job will also pick it up automatically

### "502 Bad Gateway"
- Twitter's upstream API is temporarily down
- Retry after 30 seconds — usually resolves quickly

### Cached responses
- Some endpoints return cached data (indicated by `X-Cache: HIT` header)
- User profiles cached for 5 min, tweets for 2 min, trending topics for 1 min
- If you need fresh data, wait for cache expiry

## Retry Strategy
- For 429 and 5xx errors: use exponential backoff (wait 1s, 2s, 4s, 8s, etc.)
- Check `X-RateLimit-Remaining` header to monitor usage
- Maximum 3-5 retries before giving up
- Do NOT retry 400, 401, 403, 404 errors — fix your request instead
- **Official SDKs** (JS, Python, Go) handle retries automatically with exponential backoff — no manual retry logic needed

### Response is HTML instead of JSON
- You're hitting the wrong URL (e.g., website URL instead of API URL)
- Correct base URL: `https://xcrop.io/api/v2` (not `https://xcrop.io/api` or `https://xcrop.io`)
- Make sure path includes `/api/v2/`

### "Unexpected token < in JSON" (JavaScript)
- Server returned HTML (likely an error page) instead of JSON
- Check the URL is correct and includes `/api/v2/`
- Check `res.ok` before calling `res.json()`

### Empty response / data array is empty
- For user tweets: User may have no public tweets
- For followers/following: User may have hidden their connections
- For likes: User has "hidden likes" enabled on Twitter (expected, not a bug)
- For search: Try broader query terms, remove special characters
- Check `next_cursor` — you might be past the last page

### API works in Endpoints but not in my code
- Endpoints uses session auth (cookie-based) — your code needs API key
- Make sure you're using the correct API key from Dashboard -> API Keys
- Check that key is not revoked
- Try the exact same request with cURL to isolate the issue

### Rate limit hit but I'm not making many requests
- Rate limits are per-minute windows: Starter 10/min, Pro 60/min
- Check `X-RateLimit-Remaining` header in responses
- If using pagination loops, add a small delay between requests
- Consider upgrading plan for higher limits

### Credits running out fast
- Credits are per-result, not per-request. A request returning 100 results costs 100x the per-result rate
- Use smaller `count` if you don't need all results
- Check Dashboard -> Usage to see which endpoints use the most credits
- User profiles (18 credits) cost more than tweets (15 credits); followers are cheapest (1 credit)
- Write operations cost 100 credits flat each

### Timeout errors
- Large requests (high count, batch with many IDs) take longer
- Set timeout to at least 30 seconds
- For Python: `requests.get(url, headers=h, timeout=30)`
- For Node.js: use AbortController with timeout
- If persistent, the endpoint may be temporarily slow — retry after a few seconds

## Need More Help?
- Check the docs at /docs for detailed API reference with guides
- Use the Endpoints at /endpoints to test endpoints interactively
- Create a support ticket from Dashboard → Support
- Chat with us via the live chat widget (bottom-right corner)