For developers · any language
Use Unfret from any language
Unfret is one HTTPS call: send a link to POST /v1/check and get back
whether the page shows signs of a scam, dropshipped generic goods, fake reviews or pressure tricks,
with the evidence. Anything that can send JSON can use it. Python has
a client; this page is for everything else.
# check a page with an Unfret pass curl https://unfret.net/v1/check -H "Authorization: Bearer $UNFRET_PASS" \ -H "Content-Type: application/json" \ -d '{"url": "https://unfret.net/test-shop", "tier": "deep"}' # → 200 {"action": "block", "band": "junk_or_scam", "risk_score": 1.0, "flags": [ … ]}
Two ways to pay
An Unfret pass, sent as Authorization: Bearer ufk_…. A deep check uses one of the
pass's checks (its free ones first); a quick check is free, up to 10 a minute. Make a
developer pass with 20 free deep checks, or
buy checks for any pass: 25 for $6.00, 100 for $20.00.
x402, with no pass and no account: the agent pays each check from its own wallet,
$0.01 for quick and $0.20 for deep. Send the request without
Authorization and the first answer is 402, with a
PAYMENT-REQUIRED header (base64 of the JSON that is also the body) whose
accepts lists what Unfret takes: USDC and wSOL on Solana, scheme exact. Pay one
and send the same request again with the payment in a PAYMENT-SIGNATURE header; the answer
then carries a PAYMENT-RESPONSE header. Don't write the signing yourself: use an x402 client
library for your language (the x402
project has them for TypeScript, Python and Go), or unfret-mcp, which
pays from a Solana wallet. USDC on Base comes next. The same payment
sent again gets the same answer and is never charged twice. Every option, price and rule is in the
x402 discovery document and in llms.txt.
With x402 the answer is the same as with a pass, without the pass's four fields (below). The rest of this page uses a pass.
Get a developer pass in code
A pass with 20 free deep checks, for building and testing against Unfret. No account: the server asks for a few seconds of proof of work instead. (Or press "Make a developer pass" on the developer page.)
- Get a challenge.
GET /v1/keys/challengeanswers{"challenge": "…", "bits": 18, "expires_at": …}. It can be used once, within 10 minutes (expires_at, Unix seconds). - Solve it. Find a
solution: a string of 1 to 32 characters (a decimal counter 0, 1, 2, … works) such that SHA-256 of the UTF-8 bytes ofchallenge + ":" + solutionstarts withbitszero bits, counted from the most significant bit of the first byte (18 bits: the first 2 bytes are 0 and the next one is below 64). That takes about 262,144 hashes on average. Use thebitsthe challenge came with: it is 18, and up to 6 more on a day when very many passes are being made. - Make the pass.
POST /v1/keyswith{"challenge": "…", "solution": "…", "developer": true}answers201withkey(the pass,ufk_…),recovery_code(its backup code),key_id,account,balance_usd_microsandfree_checks. Both secrets are shown only this once and stored only as hashes: save them.
Limits. 20 free deep checks per developer pass, and
one developer pass with free checks a day per visitor network; past that, the
pass is made without them ("free_checks": 0). At most 5 new passes a
day per network (then 429). Free deep checks, everyone's together, come out of one daily
budget; once it's used, a deep check that only free checks could pay for answers
429 FREE_CHECKS_PAUSED until 00:00 UTC. Quick checks always go on.
The proof of work in JavaScript
Node 20 or newer, Deno, Bun or a browser: Web Crypto, no packages. Usually a few seconds.
async function solve(challenge, bits) {
const encoder = new TextEncoder();
for (let n = 0; ; n++) {
const digest = await crypto.subtle.digest("SHA-256", encoder.encode(`${challenge}:${n}`));
if (leadingZeroBits(new Uint8Array(digest)) >= bits) return String(n);
}
}
function leadingZeroBits(bytes) {
let bits = 0;
for (const byte of bytes) {
if (byte !== 0) return bits + Math.clz32(byte) - 24;
bits += 8;
}
return bits;
}
And the two calls around it (as an ES module, e.g. pass.mjs):
const base = "https://unfret.net";
const { challenge, bits } = await (await fetch(`${base}/v1/keys/challenge`)).json();
const response = await fetch(`${base}/v1/keys`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ challenge, solution: await solve(challenge, bits), developer: true }),
});
const pass = await response.json();
if (!response.ok) throw new Error(`${response.status} ${pass.error_code}: ${pass.detail}`);
console.log(pass.key, pass.recovery_code, pass.free_checks); // save both: shown only this once
The request: POST /v1/check
JSON, with Content-Type: application/json, to https://unfret.net/v1/check.
| Field | Type | |
|---|---|---|
url | string, required | The shop, product page, ad or service provider's page to check. |
tier | quick | deep | Default
quick: rules on the page itself, free with a pass. deep:
everything, including an AI read of the listing, its reviews, its photo and the shop's age; one check
from the pass. |
page_content | string, optional | The page's HTML, up to 2 MB, if you have it. Needed for marketplaces such as Amazon that refuse server-side visits; without it Unfret fetches the page itself. |
policy | strict | balanced |
lenient | Default balanced: how cautious the server's own
action is (below). |
The response
200 with the verdict. The fields you'll typically use (the
full response for the test shop is on the developer page, every field in
the API reference):
| Field | Type | |
|---|---|---|
band | string or null | The verdict a shopper would see:
reliable "Looks fine", concerns "Worth a look", careful "Think
twice", junk_or_scam "Serious concerns". Null when the page couldn't be assessed. |
summary | string or null | One plain sentence for the person you're buying for. |
flags | array | The evidence. Flags are signals, never a verdict that a shop is a scam. |
flags[].label | string | A short name: "Fake countdown". |
flags[].evidence | string | What Unfret found, in words, and where. |
flags[].severity | string | high, medium or
low. |
flags[].type | string | A stable key (timer_resets), for
code. |
assessed | boolean | False for a page that isn't a shop, listing, ad or
provider's page: no band, risk_score null, and the check is given back. |
action | allow | warn | block |
The server's own suggestion under the request's policy. |
risk_score | 0–1 or null | 0 = no concerns, 1 = clear risk. |
confidence | 0–1 | How sure the scorer is. |
tier | string | The tier that ran. |
cached | boolean | True when the answer is one from the last day for the same page, charged the same. |
page_type | string or null | storefront,
aggregate_listing (a marketplace), article, non_product,
… |
deep_check | object or null | On quick answers only: whether a deep check of this page is worth it. |
deep_check.suggested | boolean | Escalate to deep only
when this is true. |
deep_check.reason | string | Why (not): on_the_fence,
unknown_seller, serious_concerns, known_seller,
nothing_to_add. |
deep_check.text | string | "A deep check also looks at …", for a person. |
deep_check.adds | array | What a deep check would add here
(key, label). |
charged | boolean | With a pass: whether this check used one of its checks. |
free_check | boolean | With a pass: whether that was one of its free checks. |
free_checks_left | integer | With a pass: free deep checks left. |
balance_usd_micros | integer | With a pass: bought credit left, in millionths of a US dollar. |
From verdict to action
A suggested policy, the one the clients use: decide on band, and ask the human when the page
couldn't be assessed. Change it to suit your agent.
band | Action | |
|---|---|---|
reliable | allow | "Looks fine": go ahead. |
concerns | warn | "Worth a look": ask your human first. |
careful | block | "Think twice": don't buy. |
junk_or_scam | block | "Serious concerns": don't buy. |
| not assessed | warn | "assessed": false: let the human
decide. |
The server's own action follows the request's policy from
risk_score: under balanced (warn from 0.4, block from
0.7) and lenient it never warns about a page a shopper would see as "Looks
fine" or "Worth a look"; strict does. The thresholds are in the
discovery document.
Checks left
Every answer with a pass carries free_checks_left and balance_usd_micros. To ask
without checking a page: GET /v1/credits with the pass answers with
checks_remaining (deep checks it can pay for, free ones included),
free_checks_remaining, free_checks_paused (true while today's free deep checks
are all used) and balance_usd_micros.
For the card a shopper sees (a headline, reasons with where each one comes from, what
looks good, what was checked), POST /v1/analyze takes the same url,
tier and pass and answers with a verdict; see the
API reference.
Errors, retries and timeouts
Every error is JSON with detail (in words) and error_code, and nothing is
charged for any of these: a check that fails after it started is given back to the pass.
error_code | HTTP | What to do |
|---|---|---|
INVALID_API_KEY | 401 | Not a valid pass (mistyped, or replaced with its backup code): fix it. |
INSUFFICIENT_CREDITS | 402 | The pass has no checks left for a deep
check: buy checks, or use quick. |
PAYMENT_REQUIRED | 402 | No pass and no payment: x402 (above). |
VALIDATION_ERROR | 422 | The body is wrong; errors says
where. Fix it; don't retry as is. |
PAGE_UNAVAILABLE, PAGE_BLOCKED | 422 | Unfret couldn't
fetch the page, or got a bot check: send its HTML as page_content. |
RATE_LIMITED | 429 | Over 30 requests a minute: wait
the Retry-After header's seconds. |
TOO_MANY_REQUESTS | 429 | Over a pass's per-minute limit
(10 quick checks, 10 pages Unfret fetches): wait
metadata.retry_after_s seconds. Also for too many new passes in a day. |
FREE_CHECKS_PAUSED | 429 | Only free checks left and today's are all
used: back at 00:00 UTC (metadata.retry_after_s). Quick checks still work. |
BAD_CHALLENGE | 400 | POST /v1/keys: the challenge is
wrong, expired, used or unsolved: get a new one. |
INTERNAL_ERROR, GATEWAY_TIMEOUT | 500, 504 | The analysis failed or ran out of time; the check was given back. Retry later. |
SERVICE_UNAVAILABLE | 503 | Passes, payments or the analysis are off
for a moment: retry later (after Retry-After when it's sent). |
Retries. Retry a 429 after the time it gives, and a 5xx or a dropped
connection a few times with a growing pause (a few seconds, then longer): none of them used a check. Don't
retry other
4xx answers unchanged. With x402, retry with the same PAYMENT-SIGNATURE: it is
never charged twice.
Timeouts. On dev.unfret.net a quick check takes 0.2 s and a deep check
9.9 s (medians, measured on 2026-11-18; production runs on other hardware). The server
answers a deep check within 90 s with a pass (60 s with x402), or with a
free 504, so set your client's timeout above that: the examples use 120 s.
Examples: check a page, print the verdict
Each one sends a deep check of the test shop (a made-up store with every trick Unfret catches) with the
pass in UNFRET_PASS, and prints the band and the action, or the error.
Use https://dev.unfret.net, the test server, to try things without real money.
curl
With jq to pick the fields.
curl -sS --max-time 120 https://unfret.net/v1/check \
-H "Authorization: Bearer $UNFRET_PASS" -H "Content-Type: application/json" \
-d '{"url": "https://unfret.net/test-shop", "tier": "deep"}' \
| jq -r '.band // .error_code, .action // .detail'
JavaScript or TypeScript (fetch)
Node 20 or newer as an ES module (check.mjs), Deno or Bun. Keep the pass on a server: in a
web page anyone can read it.
const response = await fetch("https://unfret.net/v1/check", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.UNFRET_PASS}`, "Content-Type": "application/json" },
body: JSON.stringify({ url: "https://unfret.net/test-shop", tier: "deep" }),
signal: AbortSignal.timeout(120_000),
});
const verdict = await response.json();
if (!response.ok) throw new Error(`${response.status} ${verdict.error_code}: ${verdict.detail}`);
console.log(verdict.band, verdict.action);
Go (net/http)
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"os"
"time"
)
func main() {
body, _ := json.Marshal(map[string]string{"url": "https://unfret.net/test-shop", "tier": "deep"})
req, err := http.NewRequest("POST", "https://unfret.net/v1/check", bytes.NewReader(body))
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("UNFRET_PASS"))
req.Header.Set("Content-Type", "application/json")
resp, err := (&http.Client{Timeout: 120 * time.Second}).Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
var verdict struct {
Band string `json:"band"`
Action string `json:"action"`
ErrorCode string `json:"error_code"`
Detail string `json:"detail"`
}
if err := json.NewDecoder(resp.Body).Decode(&verdict); err != nil {
panic(err)
}
if resp.StatusCode != http.StatusOK {
fmt.Println(resp.StatusCode, verdict.ErrorCode, verdict.Detail)
os.Exit(1)
}
fmt.Println(verdict.Band, verdict.Action)
}
PHP (cURL)
For a shop or a plugin on your own server, PHP 8 with the cURL extension.
<?php
$ch = curl_init("https://unfret.net/v1/check");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("UNFRET_PASS"), "Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode(["url" => "https://unfret.net/test-shop", "tier" => "deep"]),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($ch);
if ($body === false) {
fwrite(STDERR, curl_error($ch) . "\n");
exit(1);
}
$verdict = json_decode($body, true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($status !== 200) {
fwrite(STDERR, "$status {$verdict['error_code']}: {$verdict['detail']}\n");
exit(1);
}
echo $verdict["band"], " ", $verdict["action"], "\n";
Python: the client does this, the developer pass and the errors for you.
A TypeScript reference client, to copy
For more than a call or two in JavaScript or TypeScript: the reference client in Unfret's repository
does the check, the suggested policy, typed errors, checks left and the developer pass (with the proof of
work above). One file with no dependencies, MIT licensed: copy
clients/typescript/src/index.ts into your project. It isn't published on npm.
- clients/typescript on git.kroshtan.com
- clients/typescript on the GitHub mirror
Machine-readable
- openapi.json and the API reference
- /.well-known/x402: tiers, prices, assets, policies and the pass
- llms.txt: the service described for language models
More for developers
- The MCP server, remote or local
- The Python client
- How often Unfret is right, measured