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.)

  1. Get a challenge. GET /v1/keys/challenge answers {"challenge": "…", "bits": 18, "expires_at": …}. It can be used once, within 10 minutes (expires_at, Unix seconds).
  2. 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 of challenge + ":" + solution starts with bits zero 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 the bits the challenge came with: it is 18, and up to 6 more on a day when very many passes are being made.
  3. Make the pass. POST /v1/keys with {"challenge": "…", "solution": "…", "developer": true} answers 201 with key (the pass, ufk_…), recovery_code (its backup code), key_id, account, balance_usd_micros and free_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.

FieldType
urlstring, requiredThe shop, product page, ad or service provider's page to check.
tierquick | deepDefault 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_contentstring, optionalThe 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.
policystrict | balanced | lenientDefault 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):

FieldType
bandstring or nullThe 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.
summarystring or nullOne plain sentence for the person you're buying for.
flagsarrayThe evidence. Flags are signals, never a verdict that a shop is a scam.
flags[].labelstringA short name: "Fake countdown".
flags[].evidencestringWhat Unfret found, in words, and where.
flags[].severitystringhigh, medium or low.
flags[].typestringA stable key (timer_resets), for code.
assessedbooleanFalse 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.
actionallow | warn | block The server's own suggestion under the request's policy.
risk_score0–1 or null0 = no concerns, 1 = clear risk.
confidence0–1How sure the scorer is.
tierstringThe tier that ran.
cachedbooleanTrue when the answer is one from the last day for the same page, charged the same.
page_typestring or nullstorefront, aggregate_listing (a marketplace), article, non_product, …
deep_checkobject or nullOn quick answers only: whether a deep check of this page is worth it.
deep_check.suggestedbooleanEscalate to deep only when this is true.
deep_check.reasonstringWhy (not): on_the_fence, unknown_seller, serious_concerns, known_seller, nothing_to_add.
deep_check.textstring"A deep check also looks at …", for a person.
deep_check.addsarrayWhat a deep check would add here (key, label).
chargedbooleanWith a pass: whether this check used one of its checks.
free_checkbooleanWith a pass: whether that was one of its free checks.
free_checks_leftintegerWith a pass: free deep checks left.
balance_usd_microsintegerWith 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.

bandAction
reliableallow"Looks fine": go ahead.
concernswarn"Worth a look": ask your human first.
carefulblock"Think twice": don't buy.
junk_or_scamblock"Serious concerns": don't buy.
not assessedwarn"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_codeHTTPWhat to do
INVALID_API_KEY401Not a valid pass (mistyped, or replaced with its backup code): fix it.
INSUFFICIENT_CREDITS402The pass has no checks left for a deep check: buy checks, or use quick.
PAYMENT_REQUIRED402No pass and no payment: x402 (above).
VALIDATION_ERROR422The body is wrong; errors says where. Fix it; don't retry as is.
PAGE_UNAVAILABLE, PAGE_BLOCKED422Unfret couldn't fetch the page, or got a bot check: send its HTML as page_content.
RATE_LIMITED429Over 30 requests a minute: wait the Retry-After header's seconds.
TOO_MANY_REQUESTS429Over 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_PAUSED429Only free checks left and today's are all used: back at 00:00 UTC (metadata.retry_after_s). Quick checks still work.
BAD_CHALLENGE400POST /v1/keys: the challenge is wrong, expired, used or unsolved: get a new one.
INTERNAL_ERROR, GATEWAY_TIMEOUT500, 504The analysis failed or ran out of time; the check was given back. Retry later.
SERVICE_UNAVAILABLE503Passes, 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.