/hypersolutions-claude-code

name: hypersolutions
description: >-
  Integrate and debug the Hyper Solutions API for bypassing anti-bot systems —
  Akamai Bot Manager, Incapsula/Imperva, DataDome, and Kasada.
  Use when working with the hyper-sdk (Go), hyper-sdk-py (Python), or hyper-sdk-js
  (JavaScript/TypeScript) SDKs, or calling the *.hypersolutions.co API directly;
  when generating sensor data, _abck / reese84 / ___utmvc / datadome cookies,
  Kasada x-kpsdk-* tokens, sec-cpt (428) or SBSD (429) payloads, Akamai-BM-Telemetry
  headers, DataDome
  interstitial/slider/tags, or Vercel BotID x-is-human headers; and when
  debugging blocks, challenges, 403/428/429 responses, TLS fingerprinting, or
  header-order problems in request-based scraping. Triggers on: Hyper Solutions,
  hypersolutions, hyper-sdk, Akamai sensor, _abck, sec-cpt, sbsd, Incapsula,
  reese84, utmvc, DataDome, Kasada, kpsdk, Akamai-BM-Telemetry, client hints,
  Accept-CH, anti-bot bypass,
  powhttp, HAR analysis, captured-request debugging, header order.

Hyper Solutions API Integration

What this service does (mental model)

Hyper Solutions is a **payload-generation API**. It does **not** make requests to the target site for you. It takes inputs you collect from the protected site (script contents, cookies, UUIDs, IP, User-Agent) and returns the **sensor data / cookie / token** a real browser would produce. **Your code** is responsible for all the actual HTTP traffic to the target — with a browser-grade TLS client and correct header order.

┌────────────┐   1. GET page / script      ┌──────────────┐
│ Your code  │ ──────────────────────────► │ Target site  │
│ (TLS       │ ◄────────────────────────── │ (Akamai/DD/…)│
│  client)   │   2. HTML, cookies, script   └──────────────┘
│            │
│            │   3. inputs (script, cookies, ip, ua)   ┌────────────────────┐
│            │ ──────────────────────────────────────► │ *.hypersolutions.co │
│            │ ◄────────────────────────────────────── │ (this API)          │
│            │   4. generated payload / token           └────────────────────┘
│            │
│            │   5. POST payload back to target ─────►  Target site → valid cookie
└────────────┘

If a request is failing, the cause is almost always in **step 1/5 (your TLS client, header order, cookies, or IP)**, not in the generated payload. See `references/debugging.md` first.

Non-negotiable requirements

These apply to **every** product. Standard HTTP libraries (`requests`, `axios`, `net/http`, `fetch`) will be blocked — they have non-browser TLS fingerprints.

1. **Browser-grade TLS client** with a Chrome fingerprint (e.g. `tls-client`, `azuretls-client`, `rnet`/`wreq`, `tlsclientwrapper`). Recommended profile: the **latest Chrome profile your client offers**, with **HTTP/3 disabled** (most proxies don't support it yet) and **random TLS extension order enabled**. 2. **Exact browser header order**, including HTTP/2 pseudo-header order. This is a top fingerprinting signal and DevTools does **not** show the real order. 3. **Session consistency**: the same User-Agent, TLS fingerprint, IP, and header order for the entire flow. A proper cookie jar. Consistent client-hint headers. 4. **Sticky/session proxies, never rotating** — the IP you send to the API must match the IP the target site sees. Pass your outbound IP as the `ip` input (get it from `GET https://ip.hypersolutions.co/ip`). 5. **Match Chrome versions across the board**: UA version, `sec-ch-ua`, and `sec-ch-ua-platform` must agree. Mismatched versions flag automation.

Full detail: `references/tls-and-headers.md`.

Authentication

Every API request needs the `x-api-key` header (get a key at https://hypersolutions.co/keys). Optionally add JWT signing (`x-signature`) for client-side use, or organization headers (`x-app-key` + `x-app-signature`). The SDKs handle all of this for you. Full detail + code: `references/authentication.md`.

Install & construct a session

| Language | Package | Construct | |---|---|---| | Go | `github.com/Hyper-Solutions/hyper-sdk-go/v4` (v4.0.0+) | `hyper.NewSession("api-key")` | | Python | `hyper-sdk` (PyPI, 4.0.0+) | `Session("api-key")` / `SessionAsync("api-key")` | | JS/TS | `hyper-sdk-js` (npm, 5.0.0+) | `new Session("api-key")` |

These majors are the current SDKs: **every generate call returns a result object** (Go `*XResult`, Python dataclass, JS object) with `Payload`/`payload`, `Context`/`context` where the product chains, and the client hints (`ClientHints` / `client_hints` / `clientHints`), instead of positional values. Older majors (Go `/v3`, Python 3.x, JS 4.x) returned tuples; translate old snippets to the result objects. They also add the Akamai telemetry methods, SBSD `scriptUrl` and Kasada `strict`, and drop the SBSD `index`. `hyper-sdk-playwright` **1.0.0-beta.16** handles SBSD, the SBSD `scriptUrl` and the Akamai-BM-Telemetry header automatically.

// Go
session := hyper.NewSession("your-api-key").
    WithJwtKey("your-jwt-key").      // optional
    WithClient(customHTTPClient)     // optional

# Python (sync) — also SessionAsync with the same signature, methods are awaitable
from hyper_sdk import Session, SensorInput
session = Session("your-api-key", jwt_key=None, app_key=None, app_secret=None)

// JS/TS
import { Session } from 'hyper-sdk-js';
const session = new Session("your-api-key", jwtKey?, appKey?, appSecret?, options?);

• **Go**: product methods are on the `Session` (e.g. `session.GenerateSensorData(ctx, input)`), take a `context.Context` first, and a pointer to an input struct.
• **Python**: product methods are on the session (e.g. `session.generate_sensor_data(input)`); input classes use keyword args.
• **JS/TS**: product operations are **free functions** taking the session as the first arg (e.g. `generateSensorData(session, input)`); input classes use **positional** constructor args (arg order sometimes differs from field ord