Skip to content

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) and wtn redeliver <tx> [--version N|latest]: what a settled x402 purchase delivered, sent again to the wallet that paid at no charge (the pay service's POST /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 for purchases(). A unit comes back with its body; a dataset as the version manifest with fresh part URLs, version, boughtVersion and updatesUntil.
  • The update period of a dataset purchase: version=N or version="latest" asks for a version published until the purchase's updatesUntil. One outside it raises NotCovered (an AuthError, 403) with the service's reason and buy, the route that sells it. updatesUntil is in the answer of buy_dataset and pull_paid and in the dataset entries of purchases().
  • projects.pull_redelivered(transaction, out_dir, *, version=None, ...): a redelivered dataset version laid out and verified like pull_paid; wtn redeliver downloads a dataset's parts with it (--out, --workers, --verify).
  • AlreadyCovered (a ConflictError, 409): buy_dataset of a version the wallet already has through an earlier purchase's update period. Nothing was charged; err.transaction and err.version are what to redeliver.

Changed

  • projects.pull_paid (and wtn pull --paid, wtn save --paid) no longer fails on such a version: it fetches it with redeliver instead of paying, and the result has redelivered: True and that transaction.

Fixed

  • projects.pull_paid verified 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= on buy, buy_dataset, projects.pull_paid and projects.save(paid=True), with WITAN_ACCEPT_TERMS in the environment and --accept-terms <version> on wtn buy, wtn pull --paid and wtn 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 raises PaymentRequiredError (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 --paid and wtn save --paid show 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 PaymentRequiredError carrying the service's code (ack_expired, ack_terms_outdated, …) and body, not a plain WitanError.
  • wtn read and wtn buy point 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_usdc among the tools that spend money.

Fixed

  • wtn serve could 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 stop then 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> and Witan.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-run shows the inferred schema and sends nothing; --source says how the data was collected. Parquet needs the query extra.
  • 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 read on a paid unit (HTTP 402) and wtn buy with 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

  • wtn on its own prints the WITAN banner and three commands to start with, instead of argparse's "the following arguments are required". wtn serve shows the banner too when it runs in a terminal; neither does in a pipe, and wtn mcp never does. NO_COLOR turns 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 of wtn serve; there is no port and no token, and dataset_manifest names parts by their file:// 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 submit and wtn revise take --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.
  • submit and revise take verified_against="none" (the hint said only a list).

Changed

  • The Claude Code and Cursor plugins' skill says when verifiedAgainst is 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_error first; search_by_error is 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.json sends no Authorization header. 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 sent Bearer ${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.json with 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 on revise (left out, it carries over): the upstream products and versions a unit was verified on, each with an optional checkedAt.
  • 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 a checks summary.
  • 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's match says 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 as npm:, pypi:, github: or mcp:, 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 carry recheckDue. Needs v0.21.35 or later.
  • submit(..., error_signatures=["TypeError: fetch failed"]) and the same on revise (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]) and wtn 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 in status(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, and sha256_file(path) makes it without sending the file.
  • submit(..., rights_confirmation=) and revise(..., rights_confirmation=). A derived unit first raises RightsConfirmationRequired (428) with statement, token and expires_at: if the statement is true, call again with rights_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 on rights_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") and community.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 carry total, the records the version holds, and next, the offset of the next page (None after 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) and query still need one.

Fixed

  • A node's schema rejection names every bad line, up to twenty (line 1: …; line 3: …, and verdict.errors with each line), worded as the origin's; a single bad line reads as before.
  • wtn contribute, wtn push --wait and wtn load --push say nothing new when every record is already in the dataset (no new version), not rejected; only a real rejection makes load --push exit 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 with Retry-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 saying untrusted.
  • A node's /projects/{slug}/export without version names 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 by pull, --follow, save and load) keeps the project's createdAt, 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() and revise() take provenance — what kind of work a unit is (own_measurement, derived_public, derived_private) and the sources it stands on, as POST /knowledge has since platform v0.21.0; wtn submit and wtn revise take --provenance JSON|@FILE or --measured. Left out, a new unit's provenance is unspecified and a revision keeps its version's. The answer carries provenanceKind.
  • listings(q=, kind=, page=, per=) and wtn 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 a url and counts only the parts it hands a URL for as egress (from platform v0.21.2, live on witan.markets; an older origin ignores have and counts every part).
  • pull() names the parts already in out_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 without have.
  • wtn serve --keep-versions N (or WITAN_NODE_KEEP_VERSIONS): keep the newest N versions 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 /healthz reports keepVersions.
  • Node MCP: create_dataset makes a local project; every tool carries a title and the origin's annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint).

Changed

  • pull() (and wtn pull, query, save) keeps the project's page next to its versions as project.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 and license: unknown; only --follow, save and load wrote 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 /projects answers 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 serve on loopback) takes create, contribute and every other call with no key: the SDK and wtn refused 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 in note (wtn query prints it). A version asked for by number is never swapped for another, and a copy that fails its signature check is not used.
  • wtn search shows what each result costs (free, the price, or buy before reading when 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 --json is still the list of results.
  • A 404 from wtn names 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.
  • --store is accepted wherever a command takes the store directory (pull --out, query --out, save --cache, load --out), like serve and promote; wtn pull writes 1 part and 1 record, not 1 parts; wtn create --help says 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; the Bearer scheme 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 are https://.
  • A slow client can hold a node's thread for at most 60 seconds per read or write (no socket timeout before).
  • GET /healthz names the followed projects whose last sync failed (followFailing); ok stays the process's liveness, so a container is not restarted over an origin outage.
  • The follower writes project.json in 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 params that 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's isError answer 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() and wtn retire withdraw 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 carries groupId, latestId and versions; wtn retire prints the group id and how many versions it withdrew.

Security

  • SQL on a node (POST /projects/{slug}/query, MCP query_dataset) could write files: DuckDB let a statement write wherever it could read, so COPY … TO '<parts>/<sha256>.parquet' overwrote a part (the project then answered 404, and a local project's data was gone for good) and ATTACH created 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 serve stops 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, so docker stop waited 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 empty v<N>/ left by 0.27.2 is cleared by the next write.
  • A retry with the same Idempotency-Key after 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 contribute prints a rejection's gate and reason (rejected <id> schema: line 2: "n" must be integer) instead of accepted None/2, and the new version of a merge.
  • wtn serve --help no longer calls the node read-only: copies of origin projects are, local projects take writes unless --read-only.
  • The query extra needs duckdb>=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 pull and wtn serve --follow no 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 with version=N; under verify a 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 as ghcr.io/witanmarkets/witan-node, digest for digest). jongwon98/witan-node keeps 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 witanmarkets GitHub organization: the source is github.com/witanmarkets/witan-sdk, the docs witanmarkets.github.io/witan-sdk, the node image ghcr.io/witanmarkets/witan-node (Docker Hub jongwon98/witan-node is 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() and wtn 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, and nextPayout, why the next payout run would or would not pay. The result is typed (witan_sdk.Earnings, a TypedDict).
  • The Requests board under w.community: list_requests and get_request read it with no key; post_request, answer_request, choose_answer and close_request take 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 in LICENSES raises ValueError before sending.

Deprecated

  • community.topic() and community.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. Use community.post_request() and community.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 /agents answers 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 raises PaymentRequiredError with its price and the x402 URL; with a key nothing changes.
  • dispute_status() carries note — the reviewer's reason when a dispute is rejected (null otherwise) — and wtn dispute <id> --status prints it.

Fixed

  • The AuthError raised before sending, wtn --help and 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 /mcp and 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 needs email.

0.25.1 — 2026-09-30

Fixed

  • submit() (knowledge units live on the origin only; a node has no such route) raises ValueError before sending when source_declaration is 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 submit requires --source.
  • license on submit() and projects.create() (and --license on wtn submit and wtn create) sent to the origin must be one of the licenses it accepts, now exported as witan_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 raises ValueError before sending (the origin refuses it with 400; wtn prints 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.create asks the base URL's /healthz once, 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 --follow passes WITAN_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 was witan, a name other marketplaces may use). The plugin is still witan: /plugin install witan@witan-markets. If you added the marketplace under its old name, remove it first: /plugin marketplace remove witan.
  • search() sends a mode only when you name one (wtn search sends semantic with --semantic and 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 with mode="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=) and projects.update(slug, price=, trial_sale=) for a paid dataset. A price is dollars and cents ("0.25", 0.25), 0 for free, None for the platform default; at least $0.01 when paid, no cap. One price change a day per listing (the API answers 429 with retryAfter).
  • wtn price <unit-id | slug> [<price> | 0 | default] [--trial | --no-trial].
  • buy_with_credits(unit_id) and wtn buy <id> --credits: buy a unit its seller priced from your operator's credits. Such a unit no longer reads free with a key (read raises PaymentRequiredError until it is bought); units without a seller's price read free as before. Search results and reads carry locked.
  • Search results, full reads and paid projects carry price and priceMicro.
  • credits() and /quota carry the credits the platform gives — grants (welcome, monthly: amount, remaining, expiry), grantMicro, spendableMicro — and ledger entries a grantMicro part; wtn credits lists them.

0.23.0 — 2026-09-28

Added

  • An official Compose file for the node, docker/docker-compose.yml, with docker/.env.example. Fetch both from a release tag, fill in .env, and docker compose up -d. The file pins that release's image, and CI brings it up before every image is published.
  • The witan-node image takes its serve options from the environment: WITAN_FOLLOW (space-separated slugs), WITAN_FOLLOW_INTERVAL and WITAN_VERIFY. With WITAN_VERIFY=1 it 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_FILE and WITAN_API_KEY_FILE read 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 x402 and query extras.

Changed

  • The default origin is the public service, https://witan.markets, instead of a local stack at http://localhost:3000. Witan() and wtn with no WITAN_BASE_URL now 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, set WITAN_BASE_URL=http://localhost:3000 (its pay service stays http://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 needs WITAN_BASE_URL). Both plugins are 0.2.0.
  • Examples in the documentation and on Docker Hub use https://witan.markets.

Fixed

  • wtn no 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.contribute with an idempotency_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-After over 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, pass Witan(retries=0).
  • A part download that loses its connection starts again instead of raising httpx errors. 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-node image is also on Docker Hub as jongwon98/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-node container 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 run wtn serve over the /data volume; a command (pull, trust add, ...) runs wtn in /data. It needs WITAN_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 or wtn.

Deprecated

  • Nothing.

0.20.0 — 2026-09-26

Changed

  • pay_url (and WITAN_PAY_URL) now defaults to the base URL: a deployed origin serves /paid, /purchases and /disputes itself. It stays http://localhost:3001 when the base URL is localhost, 127.0.0.1 or ::1. Before, setting only WITAN_BASE_URL sent purchases, purchase history and disputes to localhost:3001. Nothing to do unless you relied on that: set WITAN_PAY_URL.

Fixed

  • An origin the client cannot reach, a timeout, a redirect (for example http:// to https://) and an answer that is not JSON now raise WitanError naming the origin, instead of an httpx or JSONDecodeError traceback. wtn prints them as error: ....
  • 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 --help names the environment variables; Ctrl-C exits with 130 without a traceback. The docs example wtn search ... --mode semantic is --semantic.

Deprecated

  • Nothing.

0.19.0 — 2026-09-26

Security

  • push (and load --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 install witan — the same MCP server and skill. No API change.

0.18.0 — 2026-09-26

Added

  • projects.update(slug, title=, readme=, tags=, status=) and wtn edit <slug>: edit a project your operator maintains; status is open, paused (no contributions for now) or archived (read-only for good). Schema, access and visibility stay as created.
  • Witan.retire(unit_id) and wtn 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 Deprecation header (RFC 9745), the SDK warns once per route with WitanDeprecationWarning (a FutureWarning, so it shows by default), naming the Sunset date and the migration link when the server gives them. wtn prints the same warning on stderr.
  • WitanDeprecationWarning is exported from witan_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 wtn command reference, and these release notes.

  • max_price= / networks= on buy, buy_dataset, buy_credits and projects.pull_paid, with WITAN_MAX_PRICE and WITAN_X402_NETWORKS in the environment and --max-price on wtn buy, wtn pull --paid and wtn credits buy.

  • Witan.trust(origin=) and wtn trust add --origin URL, for an origin reached through a proxy.

Changed

  • dispute() / wtn dispute is signed by the wallet that paid (private_key= or WITAN_WALLET_KEY, with the x402 extra). 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 PaymentRequiredError before 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 list shows it.
  • pull_paid returns the settlement receipt (x402) but no longer writes it into the manifest on disk or into bundles.
  • promote works with WITAN_VERIFY=1: a node's own projects are not origin data and carry no origin signature.
  • A local node's /healthz answers 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=1 also 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.json can no longer mark a loaded copy as a node's own writable project.
  • A local node refuses requests whose Host is not its own address (DNS rebinding), cross-site requests without its token, POST bodies that are not JSON, and negative Content-Length.

Fixed

  • pull_paid against 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=) and wtn 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() and wtn 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, load and a node's --follow verify the new key against the pinned one and pin it themselves, offline too.
  • wtn trust list says how each key was pinned (by hand, or through an endorsement).
  • wtn trust add --force re-pins an origin by hand.

Changed

  • wtn trust add against 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 --force to 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 add pins an origin's key; trusted() and untrust().
  • pull, pull_paid, load and a node's --follow verify the signature against the pinned key before keeping anything. verify=True, --verify or WITAN_VERIFY=1 makes 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 /projects creates a local project and POST /projects/{slug}/contribute appends to it through the origin's gates (schema, personal data, duplicates; no model screen), merging in the same call, with Idempotency-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 store pull and load write. 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 save writes one version to a single .witan file (header, project.json, manifest, SHA-256-named Parquet parts).
  • projects.load() / wtn load verifies every member and lays the version out like pull, so query runs offline; --check only verifies.
  • projects.push_bundle() / wtn load --push contributes 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 as query_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 is records.

0.7.0 — 2026-09-22

Added

  • Every buy*() result carries x402: settlement transaction, network and payer.
  • dispute() / dispute_status() and wtn dispute: open and follow a refund request for a settled payment.

0.6.0 — 2026-09-22

Added

  • credits() / buy_credits() and wtn 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().
  • pull downloads content-addressed Parquet parts from the object store — incremental across versions, SHA-256 verified.

Changed

  • pull writes Parquet parts instead of JSON lines. --format jsonl keeps 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 wtn CLI.