---
title: "Getting Started"
description: "Install the package and decode your first string. Every encoding answers the same two calls"
canonical_url: "https://encodings.agntn.dev/guide"
---
# Getting Started

> Install the package and decode your first string. Every encoding answers the same two calls

<warning title="Pre-1.0">

The API and the tool list can still move. Pin exact versions if you build on it now.

</warning>

<caution title="Not audited">

This code has never had a security audit. Do not use it in production, with real funds or with sensitive data. It is meant for agents, puzzles and local experiments only. It comes as is, without warranty of any kind, and the authors are not liable for any loss, as the MIT license states. Anything that matters wants an audited library.

</caution>

## Why this exists

Paste a base58 string into a chat and ask what it says. The model will tell you. Confidently. It reads the shape, not the bytes, and for base58 the shape tells you nothing. Encodings are arithmetic, and a language model is bad at arithmetic it can't see.

So the model should call something that does the arithmetic. `@agntn/encodings` is that something. Same thing in your TypeScript, your terminal and your agent.

Every codec here is written from its spec. RFC 4648 for base16, base32 and base64. RFC 9285 for base45. BIP173 and BIP350 for bech32. The reference code where the reference code is the spec, like basE91. No `@scure/base`, no `bs58`, no codec library underneath. The one dependency is `@agntn/hashes`, for the double SHA-256 behind Base58Check.

## Install

```bash
pnpm add @agntn/encodings
```

Node.js 26 or newer. The library itself touches nothing from `node:*`, which is why this site runs it in your browser.

## First calls

```ts
import { decode, encode, identify } from "@agntn/encodings";

encode("base64", "hello world!");
// "aGVsbG8gd29ybGQh"

decode("base64", "aGVsbG8gd29ybGQh").bytes;
// Uint8Array(12), "hello world!" in UTF-8

identify("JBSWY3DPEBLW64TMMQ======")[0];
// { encoding: "base32", confidence: 0.593, text: "Hello World", … }
```

`encode` takes a string, read as UTF-8, or a `Uint8Array`. `decode` always gives bytes back. Plus `details` for whatever the text carried besides data. A bech32 prefix, a witness version, a uuencode file name. Don't know the encoding? `identify` tries them all and shows its reasoning.

## Pick your door

- [Encoding and decoding](https://encodings.agntn.dev/guide/encoding) for the two calls, the codec objects and the subpaths.
- [Checksums](https://encodings.agntn.dev/guide/checksums) for Base58Check, bech32 and segwit addresses, where a typo gets caught.
- [Identify](https://encodings.agntn.dev/guide/identify) for the mystery string somebody just sent you.
- [Code pages](https://encodings.agntn.dev/guide/code-pages) for EBCDIC, DOS 437, Latin-1 and the mojibake they leave behind.
- [RLP](https://encodings.agntn.dev/guide/rlp) for Ethereum transactions, taken apart and put back together.
- [OpenPGP armor](https://encodings.agntn.dev/guide/armor) for the `-----BEGIN PGP` blocks around keys and signatures.
- [CLI](https://encodings.agntn.dev/guide/cli) and [Agents](https://encodings.agntn.dev/guide/agents) for the terminal and for MCP, local or on this site, Pi, OMP and the AI SDK.
- [Every encoding](https://encodings.agntn.dev/encodings) for the whole registry, sortable.


## Sitemap

See the full [sitemap](https://encodings.agntn.dev/sitemap.md) for all pages.
