Documentation

Magicgate separates bot traffic from real users by evaluating every visitor against a configurable set of filters. The platform returns a verdict -- either 'white' (bot/crawler/unwanted) or 'offer' (real user) -- in under 10 milliseconds.

There are two integration modes. API Mode lets you send visitor attributes via a REST endpoint and receive a JSON verdict that your application acts on. Direct Mode handles everything automatically: point your domain at Magicgate and visitors are filtered and redirected without any code changes on your side.

This quick start focuses on API Mode because it gives you the most control and the fastest feedback loop during development. Once you are comfortable, you can switch to Direct Mode for production deployments where zero-code integration is preferred.

Magicgate evaluates every incoming visitor against a multi-layered detection pipeline. Each filter runs independently and contributes to the final verdict. The entire evaluation completes in under 10 milliseconds, ensuring zero perceptible latency for real users.

The detection pipeline is divided into several categories: network-level checks (IP reputation, GeoIP, VPN/proxy/Tor detection, datacenter identification), browser-level checks (user-agent analysis, JavaScript fingerprinting, header consistency), behavioral checks (click patterns, session velocity, referrer validation), and list-based checks (blocklists, allowlists, ISP filtering).

Each filter can be individually enabled or disabled per flow. This granular control lets you fine-tune detection for different traffic sources. For example, a campaign targeting US mobile users might enable GeoIP (US only), VPN/proxy detection, and mobile device verification, while disabling ISP filtering.

GeoIP filtering uses locally-hosted MaxMind databases updated weekly for zero-latency lookups. You can target or exclude traffic by country, region, or city. The database covers IPv4 and IPv6 addresses with 99.8% country-level accuracy.

VPN, proxy, and Tor detection combines multiple commercial and open-source databases. Magicgate maintains a continuously updated list of known VPN exit nodes, public and private proxy servers, Tor exit relays, and residential proxy networks. Detection covers both IPv4 and IPv6 ranges.

Datacenter detection identifies traffic originating from cloud providers (AWS, GCP, Azure, DigitalOcean, OVH, Hetzner, and 200+ others). This is particularly effective at catching automated scripts and headless browsers running on virtual machines.

User-agent analysis parses the visitor's user-agent string against a database of known crawlers, bots, and automated tools. It also detects inconsistencies -- for example, a user-agent claiming to be Chrome on Windows but sending Linux-specific headers.

The blocklist filter lets you maintain custom lists of IP addresses, IP ranges (CIDR notation), and user-agent patterns that should always be classified as bots. Conversely, the allowlist filter lets you whitelist trusted IPs (such as your own testing infrastructure) that should always pass through.

Referer validation checks the HTTP Referer header against expected patterns. You can require traffic to come from specific domains (e.g., Google, Facebook) or block traffic with empty, missing, or suspicious referers.

At its core, Magicgate is a traffic router. Every visitor is evaluated against your configured filters and assigned a verdict: 'offer' (legitimate user) or 'white' (bot, crawler, or unwanted traffic). The verdict determines where the visitor is redirected.

The Offer Page is your actual landing page, offer page, or conversion funnel -- the page you want real human visitors to see. The White Page is a decoy or benign page shown to bots, crawlers, and ad network reviewers. Common white pages include simple blog posts, news articles, or generic informational content.

This separation is essential for campaign protection. Ad network compliance reviewers, click fraud bots, and competitors see the white page, while genuine users from your target audience reach the offer page. The routing happens transparently and at wire speed.

In Direct Mode, routing is fully automatic. You point your domain's DNS to Magicgate, and the platform handles the entire request lifecycle: receive the visitor, evaluate filters, and issue an HTTP redirect (302 by default) to the appropriate destination. The visitor never sees an intermediate page.

In API Mode, your application calls the /api/v1/check endpoint with visitor attributes and receives a JSON response containing the verdict and recommended redirect URL. Your application then handles the redirect itself. This gives you full control over the user experience -- you can add custom logic, logging, or A/B testing before redirecting.

Magicgate supports three display modes for routing visitors. 'Redirect' (default) issues an HTTP redirect to the destination URL. 'Proxy' serves the destination page content at the original URL without changing the browser address bar. 'Iframe' loads the destination page inside an iframe on the original URL. The display mode is configurable per flow.

Verdicts are processed synchronously and cached briefly to handle rapid successive requests from the same visitor (e.g., page resources loading after the initial redirect). The cache TTL is configurable per flow, with a default of 30 seconds.

Magicgate offers two distinct integration modes, each designed for different use cases and technical requirements. Choosing the right mode affects your deployment complexity, control over the user experience, and operational overhead.

API Mode is a programmatic integration. Your application sends a POST request to the /api/v1/check endpoint with visitor attributes (IP address, user-agent, referrer, etc.) and receives a JSON response containing the verdict. Your code then handles the routing -- redirecting bots to the white page and allowing real users through. This mode requires you to write integration code but gives you complete control over the request flow.

Direct Mode is a DNS-level integration. You configure your domain's DNS records (CNAME to proxy.magicgate.io, or ALIAS/ANAME for root domains) to point to Magicgate. When a visitor arrives, Magicgate transparently intercepts the request, evaluates the visitor, and issues an HTTP redirect to either the offer page or white page. No code changes are needed on your application -- the entire filtering and routing layer sits in front of your origin server.

API Mode advantages: Full control over routing logic. You can add custom processing between receiving the verdict and redirecting the user -- logging, A/B test assignment, cookie setting, analytics events, or conditional logic based on the verdict metadata. API Mode works with any backend stack and does not require DNS changes. It is also ideal for single-page applications (SPAs) where client-side JavaScript makes the check call.

API Mode disadvantages: Requires code changes in your application. You need to handle the API call, error cases (timeouts, rate limits), and redirect logic. The API call adds a network round-trip to your page load time (typically 10-50ms depending on geographic proximity to Magicgate's edge).

Direct Mode advantages: Zero code changes. Point your DNS and configure your flow -- visitors are filtered and redirected automatically. Direct Mode is faster for the end user because there is no extra API round-trip; the filtering happens at the edge as part of the DNS resolution and initial HTTP request. It also handles all edge cases (timeouts, retries) transparently.

Direct Mode disadvantages: Less control over the routing process. You cannot inject custom logic between the verdict and the redirect. DNS changes propagate slowly (minutes to hours) which makes testing and rollback slower. Direct Mode requires that your white page and offer page are accessible via public URLs.

A hybrid approach is also possible. Use Direct Mode for your main landing pages (where zero-code integration is a priority) and API Mode for specific endpoints that need custom verdict handling (e.g., form submissions, API endpoints, or checkout flows).

Every Magicgate account has access to a shared domain (go.magicgate.io) for immediate use. Starter plans and above can add custom domains for branded URLs and improved trust signals with ad networks.

Custom domains let you use your own URL (e.g., track.yourbrand.com) instead of the shared domain. This is important for ad compliance -- many ad networks are more lenient with traffic coming from branded domains rather than shared tracking domains.

Magicgate supports both subdomains (track.yourbrand.com) and root domains (yourbrand.com). Subdomains are recommended because they do not interfere with your main website's DNS configuration and are easier to manage.

Domain verification uses CNAME records pointing to proxy.magicgate.io. When you add a domain, you configure a CNAME record from your domain to proxy.magicgate.io. For root domains that do not support CNAME records, use an ALIAS or ANAME record pointing to proxy.magicgate.io instead. Magicgate verifies ownership by checking that the DNS record resolves correctly to the proxy endpoint.

SSL certificates are provisioned automatically via Let's Encrypt after DNS propagation completes. Magicgate handles certificate issuance, renewal, and installation. Your custom domain will serve traffic over HTTPS with a valid certificate within minutes of DNS configuration.

For Cloudflare users, ensure that the proxy (orange cloud) is disabled for the CNAME record pointing to Magicgate. Cloudflare's proxy intercepts traffic before it reaches Magicgate, which can interfere with visitor evaluation. Set the record to 'DNS only' (grey cloud) mode.

You can also purchase domains directly through Magicgate's marketplace. These domains are pre-configured and ready to use immediately -- no DNS setup or verification required. The marketplace offers a selection of clean domains suitable for traffic campaigns.

Webhooks let you receive real-time HTTP POST notifications when important events occur in your Magicgate account -- such as flow changes, domain verification, or payment updates.

Magicgate supports webhook events across multiple categories: flow events (flow.created, flow.updated, flow.deleted), domain events (domain.added, domain.verified, domain.deleted, domain.registration_failed), white page events (white_page.ready, white_page.failed, white_page.deleted), blacklist events (blacklist.created, blacklist.updated, blacklist.deleted), API key events (apikey.created, apikey.deleted, apikey.activated, apikey.deactivated), wallet events (wallet.credited, wallet.debited), subscription events (subscription.changed, subscription.canceled, subscription.plan_changed, and more), billing events (payment.completed, payment.failed), and support events (ticket.created, ticket.replied, ticket.resolved, ticket.closed).

Each webhook delivery includes three security headers: X-Webhook-Signature (HMAC-SHA256 hex digest), X-Webhook-Timestamp (Unix timestamp), and X-Webhook-ID (endpoint identifier). The signature covers the timestamp and body together -- computed as HMAC-SHA256(secret, timestamp + '.' + body) -- which prevents both tampering and replay attacks. You should verify the signature and reject requests with timestamps older than 5 minutes. The signing secret is generated when you create the webhook endpoint and is displayed once -- store it securely.

Magicgate retries failed webhook deliveries. If your endpoint returns a non-2xx status code or does not respond within 10 seconds, the delivery is retried. After all retries are exhausted, the event is marked as failed and the endpoint's failure count is incremented.

Webhook payloads are JSON-encoded with the structure: { id, event, timestamp, data }. The 'event' field contains the event type string (e.g., 'domain.verified'), 'id' is a unique delivery ID for idempotency, 'timestamp' is an ISO 8601 datetime, and 'data' contains event-specific details.

You can configure multiple webhook endpoints per account, each subscribed to different event types. This lets you route domain events to your deployment pipeline and billing events to your accounting system, for example.

Magicgate uses a wallet-based billing model. You add funds to your wallet via crypto deposits, and your subscription auto-renews from the wallet balance at each billing cycle. This eliminates the need for recurring card charges and provides full control over your spending.

Three payment providers are supported: CCPayment, NowPayments, and TransVoucher. Each provider supports Bitcoin, Ethereum, USDT, USDC, and 50+ additional cryptocurrencies. When you initiate a deposit, a payment address and amount are generated. Once the blockchain confirms the transaction, your wallet balance updates automatically.

Plans determine your feature limits: checks per month, number of flows, rules per flow, API access, custom domains, and more. You can view available plans without authentication. Upgrading or downgrading takes effect immediately -- unused balance from the current period is prorated and credited back to your wallet.

Subscriptions can be monthly or yearly. Yearly subscriptions offer a discount. You can cancel at any time -- the subscription remains active until the end of the current billing period. Resuming a canceled subscription restores it without creating a new one.

The wallet tracks all transactions: deposits, subscription charges, refunds, and proration credits. Each transaction includes a reference type and ID linking it to the originating event (deposit, subscription renewal, plan change, etc.).

The Magicgate dashboard is your central control panel for managing traffic flows, monitoring analytics, and configuring account settings. After logging in, you land on the Overview page which shows a summary of your account's key metrics.

The Overview page displays total checks processed, verdict distribution (offer vs white), active flows, and recent activity. A time-series chart shows traffic volume over the last 24 hours, 7 days, or 30 days. This gives you an immediate sense of your traffic health and filtering effectiveness.

The Flows section is where you create and manage traffic flows. Each flow represents a distinct filtering configuration -- a set of filters, an offer page URL, a white page URL, and integration settings (API Mode or Direct Mode). You can have multiple flows for different campaigns, landing pages, or traffic sources.

Within each flow's detail view, you can see per-flow analytics: total checks, verdict breakdown, filter hit rates, geographic distribution, and top referrers. This granular data helps you optimize filter settings for each specific campaign.

The Analytics section provides a comprehensive view across all flows. Charts include verdict trends over time, filter effectiveness (which filters trigger most often), geographic heatmaps showing traffic origin, device and browser breakdowns, and hourly traffic patterns. All charts support date range filtering and flow-specific filtering.

The Domains section lists all configured domains (shared and custom). For each domain, you can see its status (active, pending verification, DNS error), SSL certificate status, and associated flows. Domain health checks run automatically and alert you if DNS or SSL issues are detected.

The Settings section contains account-wide configuration. API Keys: generate and manage API keys with optional expiration dates. Webhooks: configure webhook endpoints and view delivery logs. Providers: add and manage payment and DNS providers. Billing: view wallet balance, top-up history, and subscription status. Team: invite team members with role-based access (user, admin).

The dashboard supports both light and dark themes, with the theme toggle in the top-right corner. All pages are responsive and work on mobile devices, though the desktop experience provides the most comprehensive data views.