Spot it
before you read it.
Hallmarks turn long, opaque identifiers — crypto addresses, key fingerprints, commit SHAs, anything you'd otherwise read character by character — into small, distinct visual marks. A mismatch jumps out before you've finished reading the string. The careful read is still yours when it matters.
For anything you compare character by character
Hallmarks aren't avatars and they're not memory aids — you don't need to remember what your hallmark looked like yesterday. You only need to compare what's on the screen with what's somewhere else: another screen, a printed receipt, a hardware wallet, a teammate's terminal.
Where else this fits
Crypto popularized the need because the cost of getting it wrong is immediate and irreversible. But the same comparison problem shows up in any industry where humans are the bridge between two systems that need to agree on a long opaque string — banking, logistics, healthcare, software supply chains, legal, scientific records.
How it compares to prior art
The same input, rendered by four different identicon systems. Hallmarks are designed specifically for visual matching — symmetric, perceptually-tuned colors, optimized for small sizes, with a verbal and pixel-art companion built in.
Three styles, one algorithm
The same pattern, rendered for different display environments. Monochrome uses shape (circle vs. rounded square) to carry the third value when color isn't available.
Borders for busy backgrounds
An optional 1-unit stroke in the primary color. Useful when the hallmark sits against a tinted surface, a photograph, or other hallmarks in a dense list — anywhere its own light background would otherwise blur into the surroundings. bordered: true.
Visual variety
Twenty-four arbitrary inputs. The point of the grid isn't beauty — it's that no two look the same at a glance. Hover any tile to see its source string.
Designed to work small
Hallmarks were tuned for the 22–34 px range — small enough to sit inline next to an address line, large enough to distinguish without squinting. Below 18 px, switch to the 14×20 pixel-art variant.
14×20 pixel-art mode
For hardware wallets, e-ink readers, embedded LCDs, and any display where sub-pixel rendering isn't available. Each cell becomes a 2×2 block; accent cells take a diagonal two-pixel form so the three-value distinction survives. Render once, upscale with nearest-neighbor — never anti-aliasing.
Three words for ears, screen readers, and phone calls
Every hallmark has a three-word companion drawn from the BIP-39 English wordlist, derived from the same hash. It's the natural aria-label for the image, the natural thing to read aloud over a phone call ("does your screen say violin orbit tangerine?"), and the natural thing to show below the visual when you want a second channel.
Use it
Two reference implementations ship today: TypeScript for the web and Node, Swift for iOS and macOS. Both produce byte-identical output for the same input — you can mix and match across platforms.
TypeScript / JavaScript
npm install hallmarksimport { hallmark, hallmarkWords } from "hallmarks";
const node = hallmark("bc1qar0srrr7xfkvy...");
document.querySelector("#avatar").appendChild(node);
const aria = hallmarkWords("bc1qar0srrr7xfkvy...");
// → ["brush", "swarm", "always"]Swift
// Package.swift
.package(url: "https://github.com/GBKS/hallmarks", from: "1.0.0")import Hallmarks
Hallmark(input: "bc1qar0srrr7xfkvy...")
.frame(width: 64)Both implementations are reference implementations of the Hallmarks v1.0 specification. Conformance test vectors live in test-vectors.json — any new implementation that reproduces every vector exactly is conformant.
Background
Hallmarks grew out of Arké, an experimental Bitcoin and Ark wallet I've been building, where sending money to long, look-alike addresses needed a visual second channel. The first sketch lived inside the app; after a post arguing for a standard, it became its own thing — open spec, two reference implementations, and the site you're looking at.
Arké is in TestFlight if you'd like to see Hallmarks in real use, or to nudge the rough edges with me.
— Christoph Ono