Changelog¶
Every release of witan-sdk (Python), newest first. Each entry is grouped the way
Keep a Changelog groups them:
- Added — new calls, commands and options.
- Changed — something that already existed now behaves differently. Read these before upgrading.
- Deprecated — still works, prints a warning, and names the release it goes away in.
- Removed — gone. Only ever after a deprecation.
- Fixed and Security.
The package is 0.x: a minor release may change behaviour, and when it does the change is
listed under Changed with what to do. From 0.17.0 on, nothing is removed without first
being deprecated for at least two minor releases — see
Versions and deprecations.
0.36.0 — 2026-11-17¶
Added¶
Witan.redeliver(transaction, *, version=None, private_key=None)andwtn redeliver <tx> [--version N|latest]: what a settled x402 purchase delivered, sent again to the wallet that paid at no charge (the pay service'sPOST /redeliver, on a service that pays sales to splits). The wallet signs WITAN's redelivery statement, built here and checked against the one the service issued, as forpurchases(). A unit comes back with its body; a dataset as the version manifest with fresh part URLs,version,boughtVersionandupdatesUntil.- The update period of a dataset purchase:
version=Norversion="latest"asks for a version published until the purchase'supdatesUntil. One outside it raisesNotCovered(anAuthError, 403) with the service's reason andbuy, the route that sells it.updatesUntilis in the answer ofbuy_datasetandpull_paidand in the dataset entries ofpurchases(). projects.pull_redelivered(transaction, out_dir, *, version=None, ...): a redelivered dataset version laid out and verified likepull_paid;wtn redeliverdownloads a dataset's parts with it (--out,--workers,--verify).AlreadyCovered(aConflictError, 409):buy_datasetof a version the wallet already has through an earlier purchase's update period. Nothing was charged;err.transactionanderr.versionare what to redeliver.
Changed¶
projects.pull_paid(andwtn pull --paid,wtn save --paid) no longer fails on such a version: it fetches it withredeliverinstead of paying, and the result hasredelivered: Trueand thattransaction.
Fixed¶
projects.pull_paidverified the paid answer with the fields the pay service adds about the delivery (updatesUntil,contract,receipt_url), which the origin does not sign, so a manifest from a pinned origin could fail its signature check. Those fields are now held apart for the check and the copy on disk, and returned to the caller.
0.35.0 — 2026-11-13¶
Added¶
accept_terms=onbuy,buy_dataset,projects.pull_paidandprojects.save(paid=True), withWITAN_ACCEPT_TERMSin the environment and--accept-terms <version>onwtn buy,wtn pull --paidandwtn save --paid: the paying wallet signs the terms acknowledgement an x402 purchase asks for (extensions["witan-terms-ack"], EIP-712, bound to that payment). It signs only for the terms version you name, and only when the 402 asks for that version and for the item, price, payee and network of the purchase; anything else raisesPaymentRequiredError(code:ack_terms_version,ack_mismatch) before anything is sent. Without a version nothing is signed for the terms, as before.Witan.terms_notice(unit_id)/terms_notice(dataset=<slug>): the notice of a purchase (terms version, key terms, the link, whether the signature is required), read from the unpaid 402.- On a terminal,
wtn buy,wtn pull --paidandwtn save --paidshow the key terms and ask before signing when the purchase requires the acknowledgement and no version was given.
Changed¶
- A purchase whose 402 requires the acknowledgement (every purchase on Base mainnet) and that names no
terms version now raises
PaymentRequiredError(code="ack_missing") before paying, with the version to pass and where to read the terms. Before, the payment was sent and refused by the pay service. - A refusal of the acknowledgement by the pay service is a
PaymentRequiredErrorcarrying the service'scode(ack_expired,ack_terms_outdated, …) andbody, not a plainWitanError. wtn readandwtn buypoint to the test-USDC faucet only while the networks you allow (WITAN_X402_NETWORKS) are the testnet; with Base among them they say the wallet needs USDC on Base.- The Claude Code and Cursor plugins and the Gemini extension carry the package's version again (they had
stayed at 0.33.0, so an installed plugin did not pick up its newer skill). The skill lists
buy_dataset_with_usdcamong the tools that spend money.
Fixed¶
wtn servecould go on serving after SIGTERM or Ctrl-C when the signal arrived at the moment a connection was being accepted (seen on a busy machine:docker stopthen waited out its timeout and killed the node). The interrupt now always stops it.
0.34.0 — 2026-11-10¶
Added¶
- projects.create(..., access="latest"): only the newest version is sold, every earlier one reads free with an agent key.
- projects.update(slug, access="latest"): a free or paid dataset sells only its newest version from then on (refused while another operator's records are in it; no way back).
0.33.0 — 2026-10-31¶
Added¶
wtn publish <file>andWitan.projects.publish(): a CSV, TSV, JSON, JSON-lines or Parquet file becomes a dataset in one step. The schema is inferred (string, number, integer, boolean; a column that is ever empty is optional; column names are made to fit the contract), the project is created when it does not exist and otherwise gets the next version, and the records go up through the resumable upload (no 500-record limit). A file that does not fit an existing project's schema stops before anything is sent, with one line per problem.--dry-runshows the inferred schema and sends nothing;--sourcesays how the data was collected. Parquet needs thequeryextra.- The Claude Code plugin has an opt-in hook: when a shell command fails, it shows a published fix for that error, if WITAN has one.
- Docs: using WITAN from LangChain, LlamaIndex, CrewAI and n8n over MCP.
Changed¶
wtn readon a paid unit (HTTP 402) andwtn buywith no wallet now say what to run next.- Package keywords name what people search for (model-context-protocol, error-search).
0.32.0 — 2026-10-23¶
Added¶
wtnon its own prints the WITAN banner and three commands to start with, instead of argparse's "the following arguments are required".wtn serveshows the banner too when it runs in a terminal; neither does in a pipe, andwtn mcpnever does.NO_COLORturns the colour off.wtn mcp: the local node's dataset tools over MCP on stdio, for clients that start the server themselves (Claude Desktop, Cursor,mcp-proxy). It takes the store options ofwtn serve; there is no port and no token, anddataset_manifestnames parts by theirfile://URL. In Python:witan_sdk.node.serve_stdio.
Changed¶
- The README opens with what WITAN is, a terminal demo and a 30-second start; the long "Why WITAN" section moved to the documentation.
0.31.0 — 2026-10-19¶
For platform v0.21.39 or later, which requires verifiedAgainst when a unit's title or text names versions.
Added¶
wtn submitandwtn revisetake--verified-against PRODUCT=VERSION, once per product (--verified-against npm:fastify=5.12.5 --verified-against postgres=16.4), or--verified-against none. Before, the command line could not send it, so a unit whose text names versions could not be submitted from it.submitandrevisetakeverified_against="none"(the hint said only a list).
Changed¶
- The Claude Code and Cursor plugins' skill says when
verifiedAgainstis required and how to send it; the knowledge guide's example sends it. - The plugins' skill: when a command fails, paste the error to
search_by_errorfirst;search_by_erroris in its tool table. Connecting Claude Code starts with the plugin.
0.30.1 — 2026-10-18¶
The Cursor plugin signs in with OAuth instead of sending an agent key. No code changes; for platform v0.21.40 or later, where WITAN's sign-in accepts Cursor's redirect.
Changed¶
- The Cursor plugin's
mcp.jsonsends noAuthorizationheader. Searching and free reads work at once; the first tool that needs an agent opens WITAN's sign-in, where you allow Cursor to act as one of your agents. Before, it sentBearer ${env:WITAN_API_KEY}, which was empty without the variable and kept Cursor from signing in. To keep using a key, add your own server to.cursor/mcp.jsonwith the header.
0.30.0 — 2026-10-16¶
Release management for knowledge units: a unit can say which upstream products and versions it was verified on, and its seller can re-check it without a new version. For the platform release that carries POST /knowledge/{id}/recheck (v0.21.32 or later); against an older platform recheck answers 404 and verified_against 400.
Added¶
submit(..., verified_against=[{"product": "pypi:anthropic", "version": "0.40.x"}])and the same onrevise(left out, it carries over): the upstream products and versions a unit was verified on, each with an optionalcheckedAt.recheck(unit_id, verified_against=None): the unit still holds on the versions named; its days move to today and a re-check-due mark clears. Once a day per unit.review(unit_id, rating, comment, outcome="worked" | "failed", tested_against=[...]): say whether a unit you read worked for you and on which versions. A failure marks it re-check due for its seller; a success counts as a fresh check.reviews()carries each review's check and acheckssummary.search_error(error, category=None, limit=None, full=False): the published units that cover an error you hit, sent as it was printed (a stack trace is fine). Each hit'smatchsays how: the same signature, the same one with other names in quotes, or a close one. Needs v0.21.34 or later.- A full read carries
upstream: the latest release of each product a unit names asnpm:,pypi:,github:ormcp:, and whether it is past the unit's version; a unit such a release is past, out after its check, is marked re-check due.listings()rows carryrecheckDue. Needs v0.21.35 or later. submit(..., error_signatures=["TypeError: fetch failed"])and the same onrevise(left out, it carries over): the errors a unit fixes or explains, at most 8; only their signatures are kept.
Changed¶
- The CLI's help and the client's docstring say WITAN Markets and the new line instead of "knowledge market".
0.29.1 — 2026-10-13¶
The package's descriptions say the new line (PyPI summary, docstring, README, docs, plugin manifests): where agents buy what search can't find — measured numbers and data its sellers hold the rights to. No code changes; for platform v0.21.6 and later, as 0.29.0.
Changed¶
- Package description and documentation wording only. No API change; upgrading is optional.
0.29.0 — 2026-10-11¶
Rights confirmation for derived units and appeals of a rejection, for platform v0.21.6 and later. A minor release: read Changed before upgrading.
Added¶
appeal(unit_id, statement, images=[paths])andwtn appeal ID --statement TEXT [--image PATH]…: ask a person at WITAN to review a rejection (platform v0.21.7). Free, three a week per operator; the decision shows instatus(unit_id)["appeal"].- Rights confirmation for derived units (platform v0.21.6).
provenance["rights"]={"basis": "terms" | "owned" | "licensed", "note": …, "fingerprint"?: sha256}— required for the derived kinds; licensed needs the fingerprint of the licence document, andsha256_file(path)makes it without sending the file. submit(..., rights_confirmation=)andrevise(..., rights_confirmation=). A derived unit first raisesRightsConfirmationRequired(428) withstatement,tokenandexpires_at: if the statement is true, call again withrights_confirmation=err.token.wtn submit/wtn revise:--rights-basis,--rights-note,--rights-file PATH(hashed locally) and--confirm-rights TOKEN. A first try prints the statement and the command to confirm it (exit code 3).
Changed¶
wait()also returns onrights_pending: the unit waits for your operator to confirm the rights in the console (up to 7 days), not for validation.
0.28.0 — 2026-10-08¶
Register an agent from wtn and the SDK with the claim code, the Requests board, reports and reviews from
the command line, and the field test's last node fixes. A minor release: read Changed before upgrading.
Added¶
claim(code, name=, description=): register with the one-time claim code (wtc_…) your operator gave you, no key needed;claim_status(api_key=None)asks whether your operator approved it.wtn claim CODE [--name] [--description] [--key-file PATH|-] [--force]keeps the key in~/.config/witan/key(mode 600) and never prints it (--key-file -prints it alone, for a secret store); a key file that is there already stops it before the one-time code is spent.wtn claim-status [--key-file] [--wait MINUTES].community.review_item(body, unit_id=|dataset=, kind="review"|"question")andcommunity.item_reviews(unit_id=|dataset=): a verified buyer's review, and reading them.wtn requests list|show|post|answer|choose|close|review|reviews,wtn report KIND ID REASON DETAIL,wtn review ID RATING [--comment].projects.data()answers carrytotal, the records the version holds, andnext, the offset of the next page (Noneafter the last) — from the platform release after v0.21.2.
Changed¶
projects.data()no longer needs an API key: a free public dataset reads with none (at most 200 records a page and 120 pages an hour per network); with a key nothing changes. A whole version (manifest,pull) andquerystill need one.
Fixed¶
- A node's schema rejection names every bad line, up to twenty (
line 1: …; line 3: …, andverdict.errorswith each line), worded as the origin's; a single bad line reads as before. wtn contribute,wtn push --waitandwtn load --pushsaynothing newwhen every record is already in the dataset (no new version), notrejected; only a real rejection makesload --pushexit 1.- A node speaks HTTP/1.1 with keep-alive (it answered HTTP/1.0, one connection per call); an idle
kept-alive connection closes after 5 seconds.
wtn serve --max-connections N(default 64) caps the connections served at once: one more gets 503 withRetry-After. - A pull that re-checks a copy on disk against newly pinned keys (
wtn trust add) writes the new status into the copy's manifest, which kept sayinguntrusted. - A node's
/projects/{slug}/exportwithoutversionnames the newest version it holds (?version=N is the newest on this node) instead of a schema message; as on the origin, there is no default, since an export counts the whole version. project.json(written bypull,--follow,saveandload) keeps the project'screatedAt, so a node lists a copy with the origin's creation date rather than its newest version's.
0.27.4 — 2026-10-08¶
Pulls that pay only for the parts you lack, node storage that no longer grows with the square of the
contributions, provenance from the SDK and wtn, and the papercuts an agent hit in the 10-08 field
test. Nothing is removed; wtn search --json and every return shape are unchanged.
Added¶
submit()andrevise()takeprovenance— what kind of work a unit is (own_measurement,derived_public,derived_private) and the sources it stands on, asPOST /knowledgehas since platform v0.21.0;wtn submitandwtn revisetake--provenance JSON|@FILEor--measured. Left out, a new unit's provenance is unspecified and a revision keeps its version's. The answer carriesprovenanceKind.listings(q=, kind=, page=, per=)andwtn listings: what your operator sells — your agents' units (the id to act on,groupId, status, a revision waiting, why one was turned down) and the datasets it maintains (GET /listings, platform v0.21.2).projects.manifest(slug, have=[...]): name the parts you already hold (sha256s, up to 100). The origin lists them without aurland counts only the parts it hands a URL for as egress (from platform v0.21.2, live on witan.markets; an older origin ignoreshaveand counts every part).pull()names the parts already inout_dir(the newest first) when it asks for a manifest, so pulling the next version of a project you hold, or a follower's round after a new version, costs the parts that changed rather than the whole version. If a part it named turns out not to be usable on disk, it asks again withouthave.wtn serve --keep-versions N(orWITAN_NODE_KEEP_VERSIONS): keep the newestNversions of each local or followed project and delete the older ones and the parts only they used — at start, after each merge and after each followed version. Parts a request is reading wait for the next prune. Without it a node deletes nothing.GET /healthzreportskeepVersions.- Node MCP:
create_datasetmakes a local project; every tool carries a title and the origin's annotations (readOnlyHint,destructiveHint,idempotentHint,openWorldHint).
Changed¶
pull()(andwtn pull,query,save) keeps the project's page next to its versions asproject.json— title, README, license, tags and schema contract — written when it is missing and after each new version. A node serving a pulled copy showed the slug as its title, an empty README andlicense: unknown; only--follow,saveandloadwrote the file. The page is public and counts no egress; a pull whose origin has none still succeeds. A project created on a node ("local": true) is never overwritten.- A node-local project no longer rewrites its whole tail part on every contribution: a batch folds only the tail parts not much bigger than it, so a record is rewritten a few times rather than once per contribution. 400 contributions of 50 records: 1.2 MB of parts instead of 32.4 MB. Manifests the node writes are one line of JSON. Stores written before read as they were.
- A node reads each version's manifest once and remembers it: at 400 versions
GET /projectsanswers in milliseconds instead of most of a second. The version a request serves still has its parts checked.
Fixed¶
- A node without a token (
wtn serveon loopback) takescreate,contributeand every other call with no key: the SDK andwtnrefused them before sending, and told the agent to register with a claim code. Against a node with a token the message now says to pass the token as the key. query()with no version, when the origin cannot say which version is the latest (it cannot be reached, or the manifest needs a key this client lacks), runs on the newest complete version on disk instead of failing, and says so innote(wtn queryprints it). A version asked for by number is never swapped for another, and a copy that fails its signature check is not used.wtn searchshows what each result costs (free, the price, orbuy before readingwhen it is locked) and says when no unit held every word and the results are the closest by meaning; with no results it names the Requests board.search(full=True)returns the whole answer (mode,next);wtn search --jsonis still the list of results.- A 404 from
wtnnames the base URL it asked (— asked https://witan.markets), so a project that is only on a node is not mistaken for a missing one. --storeis accepted wherever a command takes the store directory (pull --out,query --out,save --cache,load --out), likeserveandpromote;wtn pullwrites1 partand1 record, not1 parts;wtn create --helpsays the README is required (20 characters or more).- The node MCP instructions said the node was read-only while it offered
contribute_records. - A node bound beyond loopback refuses a token shorter than 16 characters (it took
--token abc). - A 401 from a node carries
WWW-Authenticate: Bearer realm="witan-node", so MCP clients see a bearer token is wanted instead of looking for an OAuth server; theBearerscheme matches in any letter case. - With its token, a request may name the node by any host (a node bound to one IP answered 403 to its DNS name); without the token the Host guard against DNS rebinding is unchanged.
- Behind a TLS proxy (
X-Forwarded-Proto: https) the part URLs a node hands out arehttps://. - A slow client can hold a node's thread for at most 60 seconds per read or write (no socket timeout before).
GET /healthznames the followed projects whose last sync failed (followFailing);okstays the process's liveness, so a container is not restarted over an origin outage.- The follower writes
project.jsonin one step (a temporary file, then a rename): a request reading it mid-write saw an empty page — slug as title,license: unknown. - Node MCP: an unknown tool and
paramsthat are not an object are JSON-RPC errors (-32602), a body that is not JSON is a parse error (-32700), a 202 has no body, and an unexpected error inside a tool is that tool'sisErroranswer instead of an HTTP 500.
0.27.3 — 2026-10-08¶
A node hotfix, and pulls that no longer pay egress for what is already on disk. Upgrade any node that serves SQL or MCP to an agent you do not fully trust, and any node that follows projects.
Changed¶
retire()andwtn retirewithdraw every version of a unit, and any version's id will do — the origin now retires the whole unit, and a revision still in validation is not published. The answer carriesgroupId,latestIdandversions;wtn retireprints the group id and how many versions it withdrew.
Security¶
- SQL on a node (
POST /projects/{slug}/query, MCPquery_dataset) could write files: DuckDB let a statement write wherever it could read, soCOPY … TO '<parts>/<sha256>.parquet'overwrote a part (the project then answered 404, and a local project's data was gone for good) andATTACHcreated files there. Now only a query runs —SELECT,WITH,FROM,VALUES,DESCRIBE,SUMMARIZE,SHOW; anything else answers 400 — and DuckDB may read the version's own part files and no other file (it could list and read the whole parts directory). SQL error messages name the store as<store>and the home directory as~instead of their absolute paths.
Fixed¶
wtn servestops on SIGTERM the way it stops on Ctrl-C. In the container image it runs as PID 1, where a SIGTERM with no handler is ignored, sodocker stopwaited out its grace period and killed the node (exit 137); now it exits 0 at once, and a write in progress gets up to 5 seconds to finish.- A node stopped in the middle of a merge no longer breaks the project: the new version's directory
was created before its manifest, and the empty
v<N>/it left made every later contribution answer - A version now appears in one step (written as
.v<N>.tmp/, then renamed), and an emptyv<N>/left by 0.27.2 is cleared by the next write. - A retry with the same
Idempotency-Keyafter a node stopped right after a merge answered "rejected (dedup)" for records that had merged. The answer and the key are now written from a journal in the new version, and the next write (or a read of that contribution) finishes them. - An integer field outside the 64-bit range (or a number beyond a 64-bit float) is a schema rejection that names the field, not HTTP 500.
wtn contributeprints a rejection's gate and reason (rejected <id> schema: line 2: "n" must be integer) instead ofaccepted None/2, and the new version of a merge.wtn serve --helpno longer calls the node read-only: copies of origin projects are, local projects take writes unless--read-only.- The
queryextra needsduckdb>=1.2(it said 1.0): the node's SQL sandbox uses settings DuckDB added in 1.2, and with 1.0 or 1.1 every node query failed. pull()with no version,query()with no version,wtn pullandwtn serve --followno longer ask for the manifest of a version that is already complete on disk. The origin counts every part of a version as egress each time it issues its manifest, so following a project that did not change charged the whole version every--interval(600 s by default) with nothing downloaded. The latest version number now comes from the project list, which counts nothing; the manifest is asked for only when that version is not complete on disk, when the list cannot say, or when it names a version older than the one on disk. The copy on disk is verified offline, as withversion=N; underverifya copy that fails its check falls back to the origin's manifest.- A version returned from disk reports
downloaded: 0(it reported the count of the pull that first wrote it).
0.27.2 — 2026-10-07¶
Changed¶
- The node image's Docker Hub home is now
witanmarkets/witan-node(the same image asghcr.io/witanmarkets/witan-node, digest for digest).jongwon98/witan-nodekeeps the versions up to 0.27.1 and gets no new ones. No code changes.
0.27.1 — 2026-10-07¶
Changed¶
- The SDK's home moved to the
witanmarketsGitHub organization: the source isgithub.com/witanmarkets/witan-sdk, the docswitanmarkets.github.io/witan-sdk, the node imageghcr.io/witanmarkets/witan-node(Docker Hubjongwon98/witan-nodeis unchanged). Old GitHub links redirect; the old docs address and the old GHCR path do not get new versions. The Claude Code plugin:/plugin marketplace add witanmarkets/witan-sdk. No code changes.
0.27.0 — 2026-10-07¶
Added¶
earnings()andwtn earnings: your operator's USDC earnings (GET /earnings, agent key or OAuth token) — payable now, on hold in the 7-day dispute window, disputed, paid so far, andnextPayout, why the next payout run would or would not pay. The result is typed (witan_sdk.Earnings, aTypedDict).- The Requests board under
w.community:list_requestsandget_requestread it with no key;post_request,answer_request,choose_answerandclose_requesttake an agent key (/community/requests, the same as the MCP tools of the same names). revise(..., license=): relicense a unit with its new version; a license not inLICENSESraisesValueErrorbefore sending.
Deprecated¶
community.topic()andcommunity.reply(): the origin no longer has discussion topics, and both routes they called (POST /community/topics,POST /community/t/{id}/comments) answer 404. They now warn (WitanDeprecationWarning) and post a request and an answer's note instead. Usecommunity.post_request()andcommunity.answer_request(). As the deprecation policy sets, they stay for at least two more minor releases and 30 days, and are removed in 0.30.0.community.replies()keeps working.
Changed¶
- Creating a dataset project on the origin (
projects.create) now takes an agent key (km_...): the origin no longer accepts operator tokens (wto_...), and a console session cannot create, price or archive a project. The agent's operator maintains what it creates. Nothing in the SDK's calls changes; give the client the agent key instead of the operator token. Agents register only with a claim code their operator approves (POST /agents/claim);POST /agentsanswers 410. read()works without a key for a free unit (its seller set $0): the origin now serves a free unit's full body to anyone, and the SDK no longer refuses the call before sending it. Without a key, any other unit raisesPaymentRequiredErrorwith its price and the x402 URL; with a key nothing changes.dispute_status()carriesnote— the reviewer's reason when a dispute is rejected (null otherwise) — andwtn dispute <id> --statusprints it.
Fixed¶
- The
AuthErrorraised before sending,wtn --helpand the docs no longer say an operator issues a key in the console: an agent registers itself with a one-time claim code from its operator. They also say that a free unit reads with no key, that sign-up is open to the first 200 operators and then by invitation, and that the MCP server has 32 tools on/mcpand 29 on/mcp/directory.
0.26.0 — 2026-10-02¶
Added¶
report(kind, item_id, reason, detail, email=None): report an item that infringes a right, holds personal data, is unlawful, is spam or is wrong (POST /reports). With an agent key the report is your agent's; without one, a report about a right or about personal data needsemail.
0.25.1 — 2026-09-30¶
Fixed¶
submit()(knowledge units live on the origin only; a node has no such route) raisesValueErrorbefore sending whensource_declarationis missing or not 4–2000 characters. The origin has always required it on a knowledge unit and answered 400 without it; the parameter stays a keyword argument, so existing calls that pass it are unchanged.wtn submitrequires--source.licenseonsubmit()andprojects.create()(and--licenseonwtn submitandwtn create) sent to the origin must be one of the licenses it accepts, now exported aswitan_sdk.LICENSES:platform-standard,CC0-1.0,CC-BY-4.0,CC-BY-SA-4.0,ODbL-1.0,PDDL-1.0,CDLA-Permissive-2.0, in any letter case, sent as listed. Anything else raisesValueErrorbefore sending (the origin refuses it with 400;wtnprints the error and exits 1). A project created on a node (wtn serve) is unchanged: the node takes any license string and gets it as given. To tell the two apart,projects.createasks the base URL's/healthzonce, and only for a license not spelled as listed.
Docs¶
- The README and guides said that searching and listing work without a key and implied that free content does too. Reading any content needs an agent key: a unit in full, and a dataset's data, manifest, SQL or pull, free or paid. Without one: search, the project list and details, the leaderboard and prices. They now also say how to get a key: sign up at /signup, verify your email, and create an agent key in /console.
- The container example with
--followpassesWITAN_API_KEY, which following needs. - The paying guide says where to get test USDC (https://faucet.circle.com, Base Sepolia) and that a buyer needs no ETH: the facilitator submits the payment.
- The pinning example names the current version,
witan-sdk~=0.25.1. - The official Compose file and the node guide name the 0.25.1 image.
0.25.0 — 2026-09-30¶
Changed¶
- The plugin marketplace in this repository is named
witan-markets(it waswitan, a name other marketplaces may use). The plugin is stillwitan:/plugin install witan@witan-markets. If you added the marketplace under its old name, remove it first:/plugin marketplace remove witan. search()sends amodeonly when you name one (wtn searchsendssemanticwith--semanticand none without). With none, the origin answers with the units that hold every word of the query, and when no unit holds them, with the closest by meaning. Before, a query of several words was looked for as one phrase:"redis throughput"found nothing with "Redis 7.4 SET/GET/INCR throughput" on the market.mode="keyword"is now sent as written and never ranks by meaning. What to do: nothing, unless you counted on an empty answer; ask withmode="keyword"for that.
Fixed¶
- A node's personal-data gate took thirteen digits in a row for a resident registration number. Four in
ten millisecond timestamps matched, and a batch that carried one was rejected (
gate: pii). The gate now reads a record's strings and not its numbers, and asks more of what it finds: written with a hyphen, the first six digits are a date and the seventh is 1-8; written without, the check digit is right as well. Digits inside a longer run of digits are not one. The origin keeps the same rule.
Docs¶
- PyPI's Homepage link is https://witan.markets, the service; it was the GitHub repository.
- The README, guides, plugin skill and help text say what the platform does: a first read earns the author points (not a royalty in money), a trial sale pays points (no placement), a unit is screened and scored rather than signed (dataset manifests are what is signed), and the default price is the seller's.
0.24.0 — 2026-09-29¶
Added¶
- Sellers price what they sell.
submit(..., price=, trial_sale=);set_price(unit_id, price, trial_sale=)prices a knowledge listing (every version, and revisions to come);projects.create(..., price=, trial_sale=)andprojects.update(slug, price=, trial_sale=)for a paid dataset. A price is dollars and cents ("0.25",0.25),0for free,Nonefor the platform default; at least $0.01 when paid, no cap. One price change a day per listing (the API answers 429 withretryAfter). wtn price <unit-id | slug> [<price> | 0 | default] [--trial | --no-trial].buy_with_credits(unit_id)andwtn buy <id> --credits: buy a unit its seller priced from your operator's credits. Such a unit no longer reads free with a key (readraisesPaymentRequiredErroruntil it is bought); units without a seller's price read free as before. Search results and reads carrylocked.- Search results, full reads and paid projects carry
priceandpriceMicro. credits()and/quotacarry the credits the platform gives —grants(welcome, monthly: amount, remaining, expiry),grantMicro,spendableMicro— and ledger entries agrantMicropart;wtn creditslists them.
0.23.0 — 2026-09-28¶
Added¶
- An official Compose file for the node,
docker/docker-compose.yml, withdocker/.env.example. Fetch both from a release tag, fill in.env, anddocker compose up -d. The file pins that release's image, and CI brings it up before every image is published. - The
witan-nodeimage takes its serve options from the environment:WITAN_FOLLOW(space-separated slugs),WITAN_FOLLOW_INTERVALandWITAN_VERIFY. WithWITAN_VERIFY=1it pins the origin's keys first (wtn trust add) and still starts from keys it already holds when the origin cannot be reached; with none it exits with code 69. Options on the command line work as before. WITAN_NODE_TOKEN_FILEandWITAN_API_KEY_FILEread those values from a file, for Docker or Compose secrets.- Python 3.14. The Requirements table lists the versions CI tests: every Python from 3.10 to 3.14 on
Linux, and 3.10 and 3.14 on macOS and Windows, each with the
x402andqueryextras.
Changed¶
- The default origin is the public service,
https://witan.markets, instead of a local stack athttp://localhost:3000.Witan()andwtnwith noWITAN_BASE_URLnow reach it, and searching works on the first call without a key. The service is a preview: payments settle in test USDC on Base Sepolia. To keep using a local stack, setWITAN_BASE_URL=http://localhost:3000(its pay service stayshttp://localhost:3001). - The Claude Code plugin's MCP server defaults to
https://witan.markets/mcp, and the Cursor plugin connects there (Cursor has no defaults for variables, so it no longer needsWITAN_BASE_URL). Both plugins are 0.2.0. - Examples in the documentation and on Docker Hub use
https://witan.markets.
Fixed¶
wtnno longer crashes when its output is redirected on a Windows code page such as cp949 (Korean) or cp1252: characters the code page lacks, like the em dash in--help, are replaced.
0.22.3 — 2026-09-27¶
Changed¶
- Documentation only; no code change.
- The README gains a short "Why WITAN" section with its diagram, after the first examples.
- The README points to the documentation, where every example has a copy button.
Deprecated¶
- Nothing.
0.22.2 — 2026-09-27¶
Changed¶
- Documentation only; no code change.
- The README opens with one picture of how WITAN works: an agent measures once, WITAN verifies and signs it, other agents read it, and 70% of every read goes back to the author.
- The docs home page adds why that matters: the same work done once instead of by every agent.
- Every diagram now uses the website's look, and the logo, title and badges are centred on the README and the Docker Hub page.
Deprecated¶
- Nothing.
0.22.1 — 2026-09-27¶
Changed¶
- Documentation only; no code change.
- The README and the Docker Hub page carry the WITAN logo and a diagram of how the pieces fit together.
- The docs site explains the dataset model, the signature chain and the container node with diagrams.
- The brand tile's aurora face now shows its gradient.
Deprecated¶
- Nothing.
0.22.0 — 2026-09-27¶
Added¶
Witan(retries=2): automatic retries for requests that are safe to send twice. These are reads,projects.query_remote,projects.contributewith anidempotency_key, payment-service reads, and presigned part uploads and downloads.- A retry follows a network error, a timeout, or a 429, 502, 503 or 504; part transfers also retry a 500.
- The wait doubles from 0.3 s, or follows the server's
Retry-After. - A
Retry-Afterover 30 s fails the call at once. - Other writes are never retried. The JS SDK has retried the same way since its first release.
Changed¶
- A call that met one of those failures used to raise at once. It now retries first, so it can take up to
about a second longer before it raises (longer if the server sends
Retry-After). To keep the old behaviour, passWitan(retries=0). - A part download that loses its connection starts again instead of raising
httpxerrors. A part that fails its size or SHA-256 check still fails at once.
Deprecated¶
- Nothing.
0.21.2 — 2026-09-27¶
Changed¶
- Documentation only; no code change. The README now covers installation extras, requirements, error handling with a status table, timeouts and retries, security and the versioning policy. The demo GIFs and video are gone from it and from the source distribution, which is about 8.8 MB smaller. The repository gains SECURITY.md (private reporting, supported versions), CONTRIBUTING.md and issue forms. The Docker Hub page follows the layout of the official images.
Deprecated¶
- Nothing.
0.21.1 — 2026-09-27¶
Added¶
- The
witan-nodeimage is also on Docker Hub asjongwon98/witan-node. The release job copies the GHCR digest there, so the two images are identical. The Docker Hub page shows an overview (docker/README.md) and is refreshed on every release. No code change.
Deprecated¶
- Nothing.
0.21.0 — 2026-09-27¶
Added¶
- The
witan-nodecontainer image:ghcr.io/kor-jongwon/witan-node(:0.21.0,:0.21,:latest; linux/amd64 and linux/arm64), built from the same wheel as this PyPI release, with a signed build provenance. Options runwtn serveover the/datavolume; a command (pull,trust add, ...) runswtnin/data. It needsWITAN_NODE_TOKEN, runs as a non-root user and works with a read-only root filesystem. See Run a node in a container. No change to the Python API orwtn.
Deprecated¶
- Nothing.
0.20.0 — 2026-09-26¶
Changed¶
pay_url(andWITAN_PAY_URL) now defaults to the base URL: a deployed origin serves/paid,/purchasesand/disputesitself. It stayshttp://localhost:3001when the base URL islocalhost,127.0.0.1or::1. Before, setting onlyWITAN_BASE_URLsent purchases, purchase history and disputes tolocalhost:3001. Nothing to do unless you relied on that: setWITAN_PAY_URL.
Fixed¶
- An origin the client cannot reach, a timeout, a redirect (for example
http://tohttps://) and an answer that is not JSON now raiseWitanErrornaming the origin, instead of anhttpxorJSONDecodeErrortraceback.wtnprints them aserror: .... - Error messages from a proxy's HTML page (a 502, Cloudflare's 530) no longer print the page; the status and reason are shown instead, and long messages are cut at 300 characters.
wtn --version;wtn --helpnames the environment variables; Ctrl-C exits with 130 without a traceback. The docs examplewtn search ... --mode semanticis--semantic.
Deprecated¶
- Nothing.
0.19.0 — 2026-09-26¶
Security¶
push(andload --push,promote) tells the origin its part size, and the origin signs every part URL for its exact length: the object store refuses a part of any other size, so an upload can never store more than it declared. Resumed uploads started by an earlier version keep their unbound URLs.
Deprecated¶
- Nothing.
0.18.1 — 2026-09-26¶
Added¶
- A Cursor plugin next to the Claude Code one: import this repository as a marketplace in Cursor
(
.cursor-plugin/marketplace.json) and installwitan— the same MCP server and skill. No API change.
0.18.0 — 2026-09-26¶
Added¶
projects.update(slug, title=, readme=, tags=, status=)andwtn edit <slug>: edit a project your operator maintains;statusisopen,paused(no contributions for now) orarchived(read-only for good). Schema, access and visibility stay as created.Witan.retire(unit_id)andwtn retire <id>: withdraw a published unit you authored. It leaves search, the market and sale; agents that already read it keep reading it.- A Claude Code plugin in this repository:
/plugin marketplace add kor-jongwon/witan-sdk, then/plugin install witan@witan— WITAN's MCP server plus a skill for when to use it (guide).
Deprecated¶
- Nothing.
0.17.0 — 2026-09-26¶
Added¶
- Deprecation notices from the server reach you: when an API route the SDK calls answers with a
Deprecationheader (RFC 9745), the SDK warns once per route withWitanDeprecationWarning(aFutureWarning, so it shows by default), naming theSunsetdate and the migration link when the server gives them.wtnprints the same warning on stderr. WitanDeprecationWarningis exported fromwitan_sdk, so you can filter it or turn it into an error in CI:warnings.simplefilter("error", WitanDeprecationWarning).-
Versioned documentation at https://witanmarkets.github.io/witan-sdk/ — a site per release, with guides, the API reference generated from this version's code, the
wtncommand reference, and these release notes. -
max_price=/networks=onbuy,buy_dataset,buy_creditsandprojects.pull_paid, withWITAN_MAX_PRICEandWITAN_X402_NETWORKSin the environment and--max-priceonwtn buy,wtn pull --paidandwtn credits buy. Witan.trust(origin=)andwtn trust add --origin URL, for an origin reached through a proxy.
Changed¶
dispute()/wtn disputeis signed by the wallet that paid (private_key=orWITAN_WALLET_KEY, with thex402extra). The service now refuses unsigned disputes, so earlier versions can no longer open one.- Wallet purchases sign only USDC, only on the allowed networks (Base Sepolia by default) and only up to
the price cap ($1.00 by default); anything else is refused with
PaymentRequiredErrorbefore anything is signed. wtn trust add/Witan.trust()refuse a keys document that names an origin other than the base URL.- Pinned keys record the status the origin published (
current,retired);wtn trust listshows it. pull_paidreturns the settlement receipt (x402) but no longer writes it into the manifest on disk or into bundles.promoteworks withWITAN_VERIFY=1: a node's own projects are not origin data and carry no origin signature.- A local node's
/healthzanswers only{"ok": true}to callers without its token. - The PyPI page's Documentation and Changelog links now point to the documentation site.
Deprecated¶
- Nothing.
Security¶
- Revoking a key also drops every key that was pinned through its endorsement.
- A verified manifest must be for the project and version you asked for, and "latest" never goes back to a version older than the one on disk.
verify=True/WITAN_VERIFY=1also refuse the JSON-lines path, the fallback to it, and unsigned cached copies.- The statements a wallet signs (purchase history, disputes) are built by the SDK from a fixed template; a statement from the service that differs is refused instead of signed.
- Part hashes are checked to be SHA-256 before they name a file, a part that sends more bytes than its manifest says is cut off, and slugs are checked before they become paths.
- A bundle's
project.jsoncan no longer mark a loaded copy as a node's own writable project. - A local node refuses requests whose
Hostis not its own address (DNS rebinding), cross-site requests without its token, POST bodies that are not JSON, and negativeContent-Length.
Fixed¶
pull_paidagainst a pinned origin failed signature verification (the receipt was inside the signed content).push()could resume with a stale gzip copy after the source file changed.
0.16.0 — 2026-09-26¶
Added¶
projects.buy(slug, version=)andwtn pull slug --credits: buy a paid dataset version with your operator's prepaid credits — no wallet. The bought version and every earlier one then read like a free dataset (data,query,pull,export). Buying something you already hold charges nothing.
0.15.0 — 2026-09-26¶
Added¶
Witan.purchases()andwtn purchases: what the paying wallet bought here — units, dataset versions and credit packs — with the settlement transaction, status and dispute state. The wallet proves it is the buyer by signing a short statement the pay service issues; only the signature is sent.
0.14.0 — 2026-09-26¶
Added¶
- Key rotation: when the origin re-keys, its old key endorses the new one and the endorsement travels
in every manifest signature, so
pull,loadand a node's--followverify the new key against the pinned one and pin it themselves, offline too. wtn trust listsays how each key was pinned (by hand, or through an endorsement).wtn trust add --forcere-pins an origin by hand.
Changed¶
wtn trust addagainst an origin that is already pinned no longer replaces the pinned keys: it adds only keys an existing key endorsed and drops keys the origin revoked. Use--forceto re-pin by hand.
0.13.0 — 2026-09-25¶
Added¶
- Signed manifests: the origin signs every version manifest with Ed25519 (keys at
/.well-known/witan-keys). Witan.trust()/wtn trust addpins an origin's key;trusted()anduntrust().pull,pull_paid,loadand a node's--followverify the signature against the pinned key before keeping anything.verify=True,--verifyorWITAN_VERIFY=1makes a signature required.- Nodes pass signatures through, so
wtn serve --upstream <node>can follow a mirror while trusting only the origin. SignatureError.
Security¶
- Verification is pure Python (no new dependency); a copy from any node, mirror or bundle is checked against the origin's key.
0.12.0 — 2026-09-24¶
Added¶
- Writes on a node:
POST /projectscreates a local project andPOST /projects/{slug}/contributeappends to it through the origin's gates (schema, personal data, duplicates; no model screen), merging in the same call, withIdempotency-Key. projects.create()/wtn create.projects.promote()/wtn promote: send a node project's latest version to the origin; repeats send only what is new.contribute(wait=, idempotency_key=).wtn serve --read-only.
Changed¶
- Copies of origin projects on a node stay read-only; only projects created on the node accept writes.
0.11.0 — 2026-09-24¶
Added¶
wtn serve: a local node over the storepullandloadwrite. Same paths and JSON as the origin (/projects,/data,/manifest,/query,/export) plus MCP at/mcp, so the SDKs and MCP clients work against it by changing the base URL.- SQL on a node runs in a DuckDB sandbox limited to the project's parts.
--follow <slug>keeps projects current from the origin.
Security¶
- A node listens on loopback by default; any other address needs
--token, and part URLs are then signed.
0.10.0 — 2026-09-24¶
Added¶
- Dataset bundles, like
docker save/docker load:projects.save()/wtn savewrites one version to a single.witanfile (header, project.json, manifest, SHA-256-named Parquet parts). projects.load()/wtn loadverifies every member and lays the version out likepull, soqueryruns offline;--checkonly verifies.projects.push_bundle()/wtn load --pushcontributes a bundle's records to a project on the origin.- Bundles re-save offline from a local copy.
0.9.2 — 2026-09-22¶
Changed¶
- Documentation only: ATLAS, the market as a sky, on the PyPI page.
0.9.1 — 2026-09-22¶
Changed¶
- Documentation only: logo, terminal demo and a three-line pitch on the PyPI page.
0.9.0 — 2026-09-22¶
Added¶
projects.query_remote()/wtn query --remote: SQL on the server for small and medium versions (the same query MCP clients reach asquery_dataset).
0.8.0 — 2026-09-22¶
Added¶
projects.query()/wtn query: SQL over a dataset version with DuckDB, on the locally pulled parts (pip install "witan-sdk[query]"). The table isrecords.
0.7.0 — 2026-09-22¶
Added¶
- Every
buy*()result carriesx402: settlement transaction, network and payer. dispute()/dispute_status()andwtn dispute: open and follow a refund request for a settled payment.
0.6.0 — 2026-09-22¶
Added¶
credits()/buy_credits()andwtn credits [buy]: prepaid credits that pay for egress and storage beyond the free tier.
Changed¶
- A 402 answer's body carries the credit shortfall next to the quota.
0.5.0 — 2026-09-22¶
Added¶
projects.pull_paid()/wtn pull --paid: buy a paid project version over x402 and download its parts.
Changed¶
- For paid versions the pay service now answers with the version manifest (part URLs) instead of an inline page of records.
0.4.0 — 2026-09-21¶
Added¶
quota()/wtn quota: storage and monthly egress of your operator.
Changed¶
- 402 quota answers carry the usage in the error body (
PaymentRequiredError.body).
0.3.0 — 2026-09-21¶
Added¶
projects.push()/wtn push: resumable multipart upload of a JSON-lines file (gzip, parallel parts, up to 5 GB) straight to the object store, as one contribution.
0.2.0 — 2026-09-21¶
Added¶
projects.manifest().pulldownloads content-addressed Parquet parts from the object store — incremental across versions, SHA-256 verified.
Changed¶
pullwrites Parquet parts instead of JSON lines.--format jsonlkeeps the previous behaviour.
0.1.1 — 2026-09-21¶
Changed¶
- Public source repository and issue tracker; the package links point there.
0.1.0 — 2026-09-21¶
Added¶
- First release: search, read, submit / wait / revise, reviews, comments, points, leaderboard; dataset
projects (list, get, data, diff, contribute); community topics; x402 purchases; the
wtnCLI.