diff --git a/packages/streams/README.md b/packages/streams/README.md
new file mode 100644
index 000000000000..86a8e90d36f4
--- /dev/null
+++ b/packages/streams/README.md
@@ -0,0 +1,24 @@
+# Agoric Streams
+
+The Agoric Streams package uses CosmJS and a homegrown WebSocket event querier to consume the Agoric chain's data publication sources in a flexible, future-proof way.
+
+The MVP of this package is to provide the following API to off-chain clients:
+
+```js
+const src = makeStreamSourceFromURL('https://devnet.agoric.net/network-config');
+const stream = E(src).streamFromStoragePath('mailbox.agoric1...');
+for await (const mailbox of iterateLatest(stream)) {
+  console.log(`here's a mailbox object`, mailbox);
+}
+```
+
+## Behind the scenes
+
+- the network config contains enough information to obtain Tendermint RPC nodes for a given Agoric network
+- each stream uses periodic state polling which can be triggered expediently with a Tendermint `state_change` event produced by the included `x/swingset` `SetStorageAndNotify` implementation.
+- There is an initial option to choose the level of integrity:
+  a. release data immediately without validation,
+  b. release data only after proving it was validated,
+  c. release data optimistically, but crash the stream in the future if a provably wrong value was ever released
+- published (string) values are automatically unmarshalled.  Options allow specifying your own unserializer
+- the `iterateRecent` adapter transforms a "stream" (converging on the [SharableSubscription](https://github.com/Agoric/agoric-sdk/pull/5418#discussion_r886253328) representation) into a local async iterator that produces only the last queried value (with no history reconstruction)