> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roolink.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Proof of work

> Protected API calls on Kasada sites carry a fresh x-kpsdk-cd on every request. Generate it from the session you already have.

Solving the challenge earns you cookies and a session token. For plain page loads that is enough. For the site's own API calls, the ones the page makes after it loads, Kasada usually asks for one more thing: a small proof of work, computed per request, sent as the `x-kpsdk-cd` header. The browser computes it in JavaScript; Roolink's `/cd` endpoint computes it for you.

## When you need it

Look at a protected API request in your powhttp recording. If it carries an `x-kpsdk-cd` header, every request you make to that endpoint needs one too. If the browser sends only cookies and `x-kpsdk-ct`, you do not need this page for that endpoint.

## What goes into it

| Input | Where it comes from | Rule |
| - | - | - |
| `st` | The `x-kpsdk-st` response header from `/tl`. | Stays the same for the whole session. Do not update it from later responses. |
| `ct` | The `x-kpsdk-ct` response header from `/tl`, and from any later response that carries one. | Always the newest. Kasada rotates it, and a proof of work built on an old `ct` is refused. |
| `domain` | The hostname the `ips.js` script was fetched from. | Exactly as it appears, for example `www.example.com`. |
| `fc` | The `x-kpsdk-fc` response header from `/mfc`, when the browser makes that request. | Send it when you have it. Leave it out otherwise and Roolink uses Kasada's defaults. |

## The optional /mfc request

Some sites make one extra request after `/tl`: a `GET` to `/mfc` in the same directory as `ips.js`, carrying `x-kpsdk-v` and `x-kpsdk-h`. Its response returns two headers you keep for the rest of the session: `x-kpsdk-fc`, the feature configuration for the proof of work, and `x-kpsdk-h`. Make this request only if it appears in your recording. Before the first `/mfc`, `x-kpsdk-h` is `01`.

## The flow, per protected request

**1. Generate the proof of work**

Call `/cd` with `st`, the current `ct`, `domain` and, if you have it, `fc`. Roolink returns a `payload` string. It is free of side effects and free of charge: it doesn't count against your plan, though your key still needs an active plan or balance. It takes up to ten seconds at high difficulty.

```python Python theme={null}
cd = requests.post(f"{ROOLINK}/cd",
    headers={"x-api-key": os.environ["ROOLINK_API_KEY"]},
    json={"st": st, "ct": ct, "domain": "www.example.com", "fc": fc},
).json()["payload"]
```

```go Go theme={null}
var cd struct{ Payload string `json:"payload"` }
json.Unmarshal(callRoolink("/cd", map[string]any{
    "st": st, "ct": ct, "domain": "www.example.com", "fc": fc,
}), &cd)
```

```typescript TypeScript theme={null}
const { payload: cd } = await roolinkPost("/cd", { st, ct, domain: "www.example.com", fc });
```

**2. Send the request with the Kasada headers**

Make the protected request through the same session with the browser's headers for that endpoint from your recording. Four of them are Kasada's: `x-kpsdk-v` (the SDK version from the `/fp` URL), `x-kpsdk-h`, `x-kpsdk-ct` (the current token) and `x-kpsdk-cd` (the value you just generated). Keep them in the position the browser had them.

**3. Read the response for a new ct**

If the response carries an `x-kpsdk-ct` header, replace your stored `ct` with it before the next request. `st` does not change.

**4. Repeat for every protected request**

One proof of work per request. Never reuse an `x-kpsdk-cd` value, even for an identical request a second later.

## When to start over

A `429` on a protected request means the session is no longer trusted: the cookies expired, the `ct` went stale, or the IP changed. Do not keep generating proofs of work against it. Go back to the [Quickstart](https://docs.roolink.io/kasada/quickstart.md) flow, solve the challenge again, and continue with the new `ct` and `st`.

## Request fields

| Field | Required | What it does |
| - | - | - |
| `st` | yes | The session's `x-kpsdk-st`, a millisecond timestamp. Must not be in the future. |
| `ct` | yes | The current `x-kpsdk-ct`. At least 16 bytes. |
| `domain` | yes | The hostname `ips.js` was served from. Roolink answers `422` for a domain it does not support. |
| `fc` | no | The `x-kpsdk-fc` value from `/mfc`, base64. Omit when the site does not use `/mfc`. |

## Troubleshooting

> [accordion] Roolink answers 422 with invalid\_request
>
> Read the `error` message. `st` in the future usually means a clock problem on your side; `ct` too short means you stored a truncated token; `fc` errors mean the value was altered in transit, so pass it through exactly as received.

> [accordion] Roolink answers 422 and the message says the domain is not supported
>
> Roolink solves the proof of work per site. Bring the hostname to [Discord](https://discord.gg/rooapi) and we will add it.

> [accordion] Roolink answers 504 pow\_timeout
>
> The puzzle ran past ten seconds. Retry once. If it repeats, the `fc` is not the one the site is serving now; refetch `/mfc`.

> [accordion] The protected request answers 429 straight away
>
> Check the four headers are present and in the browser's order, that `ct` is the newest you have seen, and that `st` is the original one from `/tl`. If all three hold, the session is stale: solve the challenge again.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.