live Turnstile demo page<\/a> runs the widget variant, so you can compare it against whatever you are actually hitting.<\/p>\nSetup<\/h2>\n
CapSkip runs on your own machine, so there is a local service to start before any of this works. Install the SDK from NuGet:<\/p>\n
# .NET Standard 2.0, so this works on .NET Framework 4.6.1+,\n# .NET Core 2.0+, and .NET 6 through 9.\ndotnet add package CapSkip<\/pre>\nThen point the client at the port shown in the CapSkip app:<\/p>\n
using CapSkip;\n\nvar solver = new CapSkipClient(\n apiKey: "capskip", \/\/ any string when key validation is off\n host: "127.0.0.1",\n port: 8080,\n recaptchaTimeout: 300); \/\/ seconds, also covers Turnstile and GeeTest<\/pre>\nWidget mode, the easy case<\/h2>\n
Two arguments and you are done:<\/p>\n
var result = await solver.TurnstileAsync(\n "0x4AAAAAAA...", \/\/ sitekey from the data-sitekey attribute\n "https:\/\/example.com\/login");\n\nConsole.WriteLine(result.Code); \/\/ cf-turnstile-response token<\/pre>\nDrop result.Code<\/code> into the cf-turnstile-response<\/code> field and submit the form. Nothing else to do.<\/p>\nChallenge pages need two more values<\/h2>\n
An interstitial challenge carries per-request state that the token is bound to. Two pieces of it have to travel with your solve request:<\/p>\n
\n- cData<\/strong>, passed as
data<\/code><\/li>\n- chlPageData<\/strong>, passed as
pagedata<\/code><\/li>\n<\/ul>\nBoth are embedded in the challenge page itself rather than in a form attribute, so you have to read the page before you can solve it. On a standard Cloudflare interstitial they are exposed on the page’s own challenge options object, alongside the sitekey.<\/p>\n
They are also single-use and tied to that specific page load. Fetch them, solve immediately, and do not cache them between attempts.<\/p>\n
using System.Collections.Generic;\nusing CapSkip;\n\nvar result = await solver.TurnstileAsync(\n sitekey,\n pageUrl,\n new Dictionary<string, object?>\n {\n ["data"] = cData, \/\/ the cData value from the page\n ["pagedata"] = chlPageData, \/\/ the chlPageData value\n ["action"] = "managed", \/\/ optional, when the page declares one\n });\n\nConsole.WriteLine(result.Code);\nConsole.WriteLine(result.UserAgent); \/\/ you are going to need this<\/pre>\nThe part everyone misses: the user agent<\/h2>\n
Turnstile binds the token to the browser fingerprint that produced it, and the user agent is part of that. CapSkip returns the one it used in result.UserAgent<\/code>. If you then submit the token from an HttpClient<\/code> sending its own default user agent, the values do not match and Cloudflare rejects a token that is otherwise completely valid.<\/p>\nUserAgent<\/code> is populated for Turnstile only. It is null for every other CAPTCHA type, which is why this trips people up when they reuse a working reCAPTCHA helper.<\/p>\nusing System.Net.Http;\nusing CapSkip;\n\nvar result = await solver.TurnstileAsync(sitekey, pageUrl, options);\n\nusing var http = new HttpClient();\n\n\/\/ Send back the exact user agent the solve was performed with.\nhttp.DefaultRequestHeaders.UserAgent.ParseAdd(result.UserAgent);\n\nvar form = new FormUrlEncodedContent(new[]\n{\n new KeyValuePair<string, string>("cf-turnstile-response", result.Code),\n});\n\nvar response = await http.PostAsync(pageUrl, form);<\/pre>\nIf your token is being rejected and you have ruled out an expired cData<\/code>, this is almost always the reason.<\/p>\nHandling failures properly<\/h2>\n
Every SDK exception derives from CapSkipError<\/code>, so you can catch that one type or handle each individually. There is one .NET-specific trap worth knowing about.<\/p>\nusing System;\nusing CapSkip;\n\ntry\n{\n var result = await solver.TurnstileAsync(sitekey, pageUrl, options);\n}\ncatch (CapSkip.ValidationException) { \/* bad parameters *\/ }\ncatch (NetworkException) { \/* CapSkip is not running *\/ }\ncatch (ApiException) { \/* API returned an error code *\/ }\ncatch (CapSkip.TimeoutException) { \/* exceeded recaptchaTimeout *\/ }\ncatch (CapSkipError) { \/* anything else from the SDK *\/ }<\/pre>\nTimeoutException<\/code> and ValidationException<\/code> exist in both System<\/code> and CapSkip<\/code>. With both namespaces imported, an unqualified catch (TimeoutException)<\/code> resolves to the System<\/code> one and silently never fires. Qualify them as above, or just catch CapSkipError<\/code> and inspect it.<\/p>\nSolving several at once<\/h2>\n
Every method returns a Task<\/code>, so ordinary .NET concurrency applies:<\/p>\nvar results = await Task.WhenAll(\n solver.TurnstileAsync(sitekeyA, "https:\/\/a.example.com"),\n solver.TurnstileAsync(sitekeyB, "https:\/\/b.example.com"));\n\nforeach (var r in results)\n{\n Console.WriteLine(r.Code);\n}<\/pre>\nThe SDK also exports AsyncCapSkip<\/code>, but in .NET it is only an alias of CapSkipClient<\/code>. It exists so code ported from the Python SDK keeps compiling. Switching to it gains you nothing, because .NET I\/O is already asynchronous.<\/p>\nRouting through a proxy<\/h2>\n
If the challenge is geo-sensitive, solve from the same network path you will submit from:<\/p>\n
var result = await solver.TurnstileAsync(sitekey, pageUrl,\n new Dictionary<string, object?>\n {\n ["data"] = cData,\n ["pagedata"] = chlPageData,\n ["proxy"] = new Proxy("HTTPS", "user:pass@1.2.3.4:3128"),\n });<\/pre>\nProxies are supported for Turnstile, reCAPTCHA and GeeTest. They are not supported for image CAPTCHAs, which are solved from the image bytes and never touch the target site.<\/p>\n