# Segwit address decode

`segwit-address-decode` · version 1.0.0 · Encoding & checksums · free, no key needed

Decode a native segwit address into witness version, program hex, and script pubkey.

**Use when you need to: decode native segwit address · segwit address to witness program · parse bech32 witness address.**

## Decide before calling

Read the [versioned contract](/v1/tools/segwit-address-decode/versions/1.0.0) and the supported scope below. Reuse `segwit-address-decode@1.0.0` when your input, required output and limits match it. Choose another approach for an unsupported operation.

## Explain the choice

"I can use `segwit-address-decode@1.0.0` for decode native segwit address. I will check its documented scope and the result against the task's requirements. The service is free; token and money savings for this task are unmeasured."

## Supported

- decode native segwit address
- segwit address to witness program
- parse bech32 witness address
- parse bech32m witness address
- read witness version from segwit address
- segwit address to script pubkey
- decode uppercase segwit address

## Not supported

- encode a witness program into an address
- return a valid or invalid verdict without the program
- hash or verify a key inside the program
- locate a typo in the checksum

## Behavior

- expected_hrp must already be lowercase US-ASCII (code points 33..126 excluding 65..90). An uppercase expected_hrp such as BC is invalid_input with details.reason invalid_hrp and is not case-folded.
- The address may be all-lowercase or all-uppercase. Mixed case is rejected. The decoded HRP is the lowercased address HRP and must equal expected_hrp exactly; a different HRP is invalid_input with details.reason hrp_mismatch.
- Version 0 must use a valid Bech32 checksum and a 20-byte or 32-byte program. Versions 1 through 16 must use a valid Bech32m checksum and a program of 2 to 40 bytes. The other checksum constant is details.reason wrong_encoding, not a second acceptance.
- Failure order after the lowercase expected_hrp check: character range, mixed case, separator, checksum, empty data, padding, program length, witness version, version-0 length, checksum variant, then HRP equality.
- Address length above 90 characters, or expected_hrp length above 83 characters, is limit_exceeded before checksum work. The address limit is checked before the expected_hrp limit.
- The program bytes are returned as given. They are not checked as a hash or a key. script_pubkey_hex is the BIP 141 witness script (OP_n plus a single-byte push).
- Disclaimer: format transform only; provides no confidentiality, integrity, or authenticity.

## Input

- `address` (string, required): min length 1; max length 90
- `expected_hrp` (string, required): min length 1; max length 83; pattern `^[\x21-\x40\x5b-\x7e]+$`

## Output

- `normalized_address` (string, required): min length 13; max length 90; pattern `^[\x21-\x40\x5b-\x7e]{1,83}1[qpzry9x8gf2tvdw0s3jn54khce6mua7l]+$`
- `hrp` (string, required): min length 1; max length 83; pattern `^[\x21-\x40\x5b-\x7e]+$`
- `witness_version` (integer, required): min 0; max 16
- `program_hex` (string, required): min length 4; max length 80; pattern `^(?:[0-9a-f]{2}){2,40}$`
- `encoding` (one of "bech32", "bech32m", required)
- `script_pubkey_hex` (string, required): min length 8; max length 84; pattern `^(?:[0-9a-f]{2}){4,42}$`

## Limits

- max address chars: 90
- max hrp chars: 83

## Example

Request input:

```json
{
  "address": "BC1QW508D6QEJXTDG4Y5R3ZARVARY0C5XW7KV8F3T4",
  "expected_hrp": "bc"
}
```

Response:

```json
{
  "result": {
    "normalized_address": "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4",
    "hrp": "bc",
    "witness_version": 0,
    "program_hex": "751e76e8199196d454941c45d1b3a323f1433bd6",
    "encoding": "bech32",
    "script_pubkey_hex": "0014751e76e8199196d454941c45d1b3a323f1433bd6"
  }
}
```

## How to call it

### MCP

Connect `https://computefirst.net/mcp` ([setup](/docs#connect)), then call `execute` with:

```json
{
  "id": "segwit-address-decode",
  "version": "1.0.0",
  "input": {
    "address": "BC1QW508D6QEJXTDG4Y5R3ZARVARY0C5XW7KV8F3T4",
    "expected_hrp": "bc"
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/segwit-address-decode/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"address":"BC1QW508D6QEJXTDG4Y5R3ZARVARY0C5XW7KV8F3T4","expected_hrp":"bc"}'
```

The machine-readable contract is at [/v1/tools/segwit-address-decode/versions/1.0.0](/v1/tools/segwit-address-decode/versions/1.0.0).

### CLI

```sh
node cli.mjs run segwit-address-decode 1.0.0 --input input.json --base-url https://computefirst.net
```

Get the client at [/clients/cli/](/clients/cli/).

## Related tools

- [Segwit address encode](/tools/segwit-address-encode): Encode a witness program as a native segwit address using Bech32 for v0 and Bech32m for v1-v16.
- [Bech32 decode](/tools/bech32-decode): Decode Bech32 or Bech32m text into a lowercase HRP, 5-bit data, and the checksum variant.
- [Segwit address validate](/tools/segwit-address-validate): Validate a native segwit address and report which Bech32 or Bech32m rule failed.
- [Pem envelope parse](/tools/pem-envelope-parse): Parse one RFC 7468 textual envelope into its label and lowercase hex bytes.
- [Bech32 encode](/tools/bech32-encode): Encode lowercase HRP and 5-bit data as Bech32 or Bech32m text using that checksum.
- [Cid parse](/tools/cid-parse): Parse a CIDv0 or CIDv1 envelope without hashing content.