To build a minimal API CAPTCHA solver, register one CapSkipClient as a singleton in ASP.NET Core. Expose a POST endpoint that takes a sitekey and a page URL. Wrap each call in a deadline and a SemaphoreSlim, and map the SDK’s four exceptions to HTTP status codes. Your scrapers, workers and scripts in any language then call one internal address. They never see CapSkip’s port or key. CapSkip runs on your own Windows machine, so the service has no per-solve bill either. This guide builds the service in about 120 lines and shows what each part does when CapSkip is slow, closed or silent.<\/p>\n
The numbers in this guide come from a mock CapSkip on the same PC. ASP.NET Core and the SDK are the real ones. The mock holds each solve for a set time, two seconds unless a test says otherwise, and real solve times will differ. Nothing here was run against a live CapSkip or a live site.<\/p>\n
If one C# app solves CAPTCHAs, call the SDK from that app. The C# CAPTCHA solver page<\/a> covers that. A service pays off when several callers share one CapSkip. Four jobs then belong in one place.<\/p>\n The web template is the empty ASP.NET Core project: one Program.cs, no controllers. Keep the project in its own folder. The package install writes to the project file only.<\/p>\n The CapSkip section holds the address, the solver’s API key, the number of CapSkip threads to match and the deadline in seconds. The Solver section holds the key your callers will send. Replace both placeholders before you run anything.<\/p>\n Any value can be overridden by an environment variable. A double underscore stands for the colon, so CapSkip__Port overrides CapSkip:Port. The section called Run the service away from CapSkip uses that to point the service at another machine without editing the file.<\/p>\n Replace everything in the template’s Program.cs with the blocks that follow, and add each new block below the one before. The project builds only after Step 10, because the records and helper functions come last.<\/p>\n The top of Program.cs binds the CapSkip section to a record and reads the service key. The key check uses IsNullOrWhiteSpace, not a null check with throw. On the mock, an empty string passed a null check and the service started, then accepted every request that sent an empty header.<\/p>\n This block also holds the one .NET-specific trap. System and CapSkip both define a class called TimeoutException. With implicit usings and using CapSkip, a bare TimeoutException does not compile. A switch arm on System.TimeoutException compiles but never matches the SDK’s exception. In the service, that sent an SDK timeout to the catch-all arm and returned 500 instead of 504. The last using line gives the SDK’s class its own name.<\/p>\n CapSkipClient is safe as a singleton. In the SDK source it keeps no per-call state, it copies the options dictionary on every call, and all instances share one static HttpClient. There is nothing to dispose and no need for IHttpClientFactory. The SDK uses one private static HttpClient and does not take yours. A long-lived connection would not notice a DNS change, so use an IP address for the CapSkip host.<\/p>\n The SemaphoreSlim is the gate. Give it one slot per CapSkip thread, which is the Max. Threads setting in CapSkip (it defaults to 10). AddProblemDetails together with UseStatusCodePages makes the 400, 404, 405 and 415 answers that ASP.NET Core writes itself come back in the same format as ours. Without UseStatusCodePages, those answers had no body.<\/p>\n An unprotected solve endpoint on a network address is a free solver for everyone who can reach the port. This middleware guards the \/solve path. FixedTimeEquals compares the bytes in the same time wherever they differ, and it returns false for a different length instead of throwing. A missing key, a wrong key and a too-long key all got 401 on the mock.<\/p>\n It returns 401, not 403, because there is one credential and it is missing or wrong. The middleware runs before model binding, so a request with no key and a broken JSON body gets 401, not 400.<\/p>\n The SDK has no ping call, so the health endpoint opens a TCP connection to CapSkip’s port and gives up after three seconds. With CapSkip closed it answered 503 after about two seconds, because Windows refuses a loopback connection that slowly. It tells a load balancer or a monitoring script that the service is up and CapSkip is not. It does not check that a solve works.<\/p>\n A record parameter does not make a missing field an error. System.Text.Json leaves the property null, so the handler checks the sitekey and the URL itself and answers with a validation problem.<\/p>\n The deadline is one linked CancellationTokenSource. It is cancelled when the caller hangs up (RequestAborted) or when the deadline passes (CancelAfter). Every later step takes its token, so there is only one clock to look at.<\/p>\n The wait for a slot uses the same token, plus its own limit of QueueSeconds (20 in the settings record). If every slot stays busy for that long, the caller gets 503 and can retry. Without a limit the request would sit in the queue until the deadline took it.<\/p>\n CapSkipError is the base class of the SDK’s four exceptions, and the catch names it together with the cancellation exception. RecaptchaAsync takes the token too. The SDK passes it to every poll request, so the deadline cancels the HTTP call in flight instead of waiting for it. The finally block releases the slot only when it was taken. Releasing a slot you never held would let one more solve through than CapSkip can run.<\/p>\n This is the part callers notice. The order of the switch cases matters, because the SDK reports a cancelled call in two different ways. A cancelled submit comes out as a NetworkException (“The operation was canceled”). A cancelled poll comes out as a TaskCanceledException. Mapping by exception type would tell a caller that CapSkip is down when really the deadline passed. So the two flags are checked first.<\/p>\n The SDK’s ApiException carries its text in the message and has no code property. The unsolvable case is matched on the word UNSOLVABLE in that message. The status codes below were each provoked against the mock.<\/p>\n\n
Step 1: create the project<\/h2>\n
# "web" is the empty ASP.NET Core template. This guide uses .NET SDK 10.\ndotnet new web -n CapSkipSolver -f net10.0\ncd CapSkipSolver\ndotnet add package CapSkip<\/pre>\n<\/div>\n
Step 2: put the settings in appsettings.json<\/h2>\n
{\n "CapSkip": {\n "Host": "127.0.0.1",\n "Port": 8080,\n "ApiKey": "YOUR_API_KEY",\n "MaxThreads": 10,\n "DeadlineSeconds": 120\n },\n "Solver": {\n "ApiKey": "YOUR_SERVICE_KEY"\n },\n "Logging": {\n "LogLevel": {\n "Default": "Information",\n "Microsoft.AspNetCore": "Warning"\n }\n },\n "AllowedHosts": "*"\n}<\/pre>\n<\/div>\nStep 3: read the settings and refuse to start without a key<\/h2>\n
\/\/ Program.cs\nusing System.Net.Sockets;\nusing System.Security.Cryptography;\nusing System.Text;\nusing CapSkip;\n\/\/ System and CapSkip both define TimeoutException, so give the SDK's\n\/\/ one its own name.\nusing SolverTimeout = CapSkip.TimeoutException;\n\nvar builder = WebApplication.CreateBuilder(args);\n\n\/\/ Reads the "CapSkip" section of appsettings.json. The environment\n\/\/ variable CapSkip__Port overrides CapSkip:Port (__ stands for a colon).\nvar cfg = builder.Configuration.GetSection("CapSkip").Get<CapSkipSettings>()\n ?? new CapSkipSettings();\nvar serviceKey = builder.Configuration["Solver:ApiKey"];\nif (string.IsNullOrWhiteSpace(serviceKey))\n throw new InvalidOperationException("Set Solver:ApiKey before starting.");<\/pre>\n<\/div>\nStep 4: register one client and one gate<\/h2>\n
builder.Services.AddSingleton(cfg);\n\/\/ One client for the whole process. It keeps no per-call state.\nbuilder.Services.AddSingleton(new CapSkipClient(\n cfg.ApiKey, cfg.Host, cfg.Port, recaptchaTimeout: cfg.SdkTimeoutSeconds));\n\/\/ One slot per CapSkip thread (Max. Threads in the CapSkip settings).\nbuilder.Services.AddSingleton(new SemaphoreSlim(cfg.MaxThreads));\n\/\/ With these two calls, 400, 404, 405 and 415 also come back as\n\/\/ ProblemDetails.\nbuilder.Services.AddProblemDetails();\n\nvar app = builder.Build();\napp.UseStatusCodePages();<\/pre>\n<\/div>\n
Step 5: check the service key<\/h2>\n
\/\/ Only callers that know the service key may use \/solve. FixedTimeEquals\n\/\/ takes the same time wherever the first wrong byte is.\nvar expected = Encoding.UTF8.GetBytes(serviceKey);\napp.Use(async (ctx, next) =>\n{\n var sent = Encoding.UTF8.GetBytes(ctx.Request.Headers["X-API-Key"].ToString());\n if (ctx.Request.Path.StartsWithSegments("\/solve")\n && !CryptographicOperations.FixedTimeEquals(sent, expected))\n {\n await Fail(401, "Missing or wrong X-API-Key").ExecuteAsync(ctx);\n return;\n }\n await next(ctx);\n});<\/pre>\n<\/div>\nStep 6: add a health check<\/h2>\n
\/\/ CapSkip has no ping call, so check that its port accepts a connection.\napp.MapGet("\/health", async (CapSkipSettings s, CancellationToken ct) =>\n{\n using var probe = CancellationTokenSource.CreateLinkedTokenSource(ct);\n probe.CancelAfter(TimeSpan.FromSeconds(3));\n try\n {\n using var tcp = new TcpClient();\n await tcp.ConnectAsync(s.Host, s.Port, probe.Token);\n return Results.Ok(new { status = "ok" });\n }\n catch (Exception ex) when (ex is SocketException or OperationCanceledException)\n {\n return Fail(503, "CapSkip is not reachable");\n }\n});<\/pre>\n<\/div>\nStep 7: validate the request and start the deadline<\/h2>\n
app.MapPost("\/solve", async (SolveRequest req, CapSkipClient solver,\n SemaphoreSlim gate, CapSkipSettings s, HttpContext http) =>\n{\n if (string.IsNullOrWhiteSpace(req.Sitekey)\n || !Uri.IsWellFormedUriString(req.Url, UriKind.Absolute))\n return Results.ValidationProblem(new Dictionary<string, string[]>\n {\n ["request"] = ["sitekey and an absolute url are required"]\n });\n\n \/\/ One token for the whole request. It is cancelled when the caller\n \/\/ hangs up (RequestAborted) or when the deadline passes.\n using var deadline = CancellationTokenSource.CreateLinkedTokenSource(\n http.RequestAborted);\n deadline.CancelAfter(TimeSpan.FromSeconds(s.DeadlineSeconds));<\/pre>\n<\/div>\nStep 8: wait for a slot, solve and release<\/h2>\n
var held = false;\n try\n {\n \/\/ Wait for a free slot, but not longer than QueueSeconds.\n if (!await gate.WaitAsync(TimeSpan.FromSeconds(s.QueueSeconds), deadline.Token))\n return Fail(503, "All solver slots are busy");\n held = true;\n var result = await solver.RecaptchaAsync(\n req.Sitekey, req.Url, req.Options(), deadline.Token);\n return Results.Ok(new SolveResponse(result.Code));\n }\n catch (Exception ex) when (ex is CapSkipError or OperationCanceledException)\n {\n return ToProblem(ex, http.RequestAborted.IsCancellationRequested,\n deadline.IsCancellationRequested);\n }\n finally\n {\n if (held) gate.Release();\n }\n});<\/pre>\n<\/div>\nStep 9: turn exceptions into status codes<\/h2>\n
app.Run();\n\nstatic IResult Fail(int status, string title, string? detail = null) =>\n Results.Problem(statusCode: status, title: title, detail: detail);\n\n\/\/ Check the two flags first: a cancelled submit surfaces as\n\/\/ NetworkException, a cancelled poll as TaskCanceledException.\nstatic IResult ToProblem(Exception ex, bool callerLeft, bool deadlinePassed) => ex switch\n{\n _ when callerLeft => Results.StatusCode(499),\n _ when deadlinePassed => Fail(504, "Solve deadline exceeded"),\n SolverTimeout => Fail(504, "CapSkip timed out"),\n ValidationException => Fail(400, "Bad solve parameters", ex.Message),\n ApiException when ex.Message.Contains("UNSOLVABLE") => Fail(422, "CAPTCHA could not be solved"),\n ApiException => Fail(502, "CapSkip refused the request"),\n NetworkException => Fail(503, "CapSkip is not reachable"),\n _ => Fail(500, "Unexpected error"),\n};<\/pre>\n<\/div>\n