STOPBOT SmartURLs V2 - Go

This is a Go SmartURLs client for the STOPBOT V2 API.

It receives a SmartURLs keyname, requests a redirect decision from STOPBOT, and performs either a direct redirect or JavaScript browser verification before redirecting the visitor.

Features

• Uses the STOPBOT V2 endpoint: https://api.stopbot.net/services/shorterlink
• Handles V2 flat response fields such as redirectTo, blockAccess, jsResponse, and uniqueCode
• Supports JavaScript browser verification through /rsc/rjs.json?token=...
• Uses signed verification tokens to avoid exposing API credentials
• Embeds the responsive error page template into the compiled binary
• Supports .env configuration
• Supports Nginx reverse proxy deployment

Requirements

• Go 1.26.5 or later as the minimum supported version
• A STOPBOT API key
• A SmartURLs keyname created from the STOPBOT panel

Install Go Securely

For production builds, use the latest stable patch release of Go from the official Go download page:

https://go.dev/dl/

This project can build with Go 1.26.5 or later, but the safest choice is to use the newest stable Go release available at the time you build it. Go patch releases often include security fixes and bug fixes, including fixes for the standard library packages used by web applications.

Recommended rules:

• Use the latest stable Go version from go.dev/dl.
• Do not use release candidate, beta, or old archived Go versions for production.
• Update Go regularly when new stable patch releases are published.
• Prefer the official Go installer or archive if your operating system package manager provides an old Go version.
• After installing or updating Go, verify it:

go version

On Windows PowerShell:

go version

The output should show a stable Go release, not a beta or release candidate.

STOPBOT Panel Configuration

Before using this client, create or configure your SmartURLs key in the STOPBOT panel:

1. Sign in to panel.stopbot.net.
2. Open the SmartURLs or Shortlink section.
3. Create a new SmartURLs key, or open an existing one.
4. Configure the redirect destination and protection rules from the panel.
5. Copy the SmartURLs keyname.

The keyname is the value used in your public SmartURLs URL.

Allowed keyname characters:

A-Z a-z 0-9 . _ -

The maximum length is 64 characters.

For example, if the panel shows a SmartURLs page like:

https://panel.stopbot.net/shortlink-swWV8j

then the keyname is:

swWV8j

After deploying this Go client to your domain, visitors should access:

https://your-domain.example/swWV8j

This client sends swWV8j to the STOPBOT V2 API as the keyname parameter.

Important notes:

• The API key configured in .env or STOPBOT_API_KEY must belong to the same STOPBOT account that owns the SmartURLs keyname.
• Do not expose your API key in frontend JavaScript, public repositories, logs, screenshots, or support messages.
• Use the full public domain URL only for visitors. Use only the keyname when configuring or testing this Go client.

Install

Clone this repository and copy the example environment file:

cp .env.example .env

Edit .env and set your values:

STOPBOT_API_KEY=your_api_key
SMARTURLS_ADDR=:8080
STOPBOT_API_ENDPOINT=https://api.stopbot.net/services/shorterlink
SMARTURLS_SIGNING_KEY=change_this_random_secret
SMARTURLS_TRUST_PROXY_HEADERS=false

SMARTURLS_SIGNING_KEY is used to sign the local browser verification token. Think of it as a private password used only by this SmartURLs application.

It is not your STOPBOT API key, and it does not need to be configured in the STOPBOT panel. The value only needs to stay the same on your own server.

Why it is needed:

• When STOPBOT asks this client to run browser verification, this app creates a temporary local token.
• That token contains the SmartURLs keyname, the STOPBOT uniqueCode, and an expiry time.
• SMARTURLS_SIGNING_KEY signs the token so visitors cannot edit or fake it.
• When the browser calls /rsc/rjs.json?token=..., this app checks the signature before calling STOPBOT again.

Use a long random value, for example:

SMARTURLS_SIGNING_KEY=change_this_to_a_long_random_secret_value

Recommended characters:

A-Z a-z 0-9 _ - . @ # %

Use at least 32 characters. Avoid spaces, quotes, backslashes, and characters that are special in shell or .env files, such as $, &, |, <, >, and ;.

Good examples:

SMARTURLS_SIGNING_KEY=V7sK9qT2mN4xP8rA6dF3hJ5uL0wZ1yBc
SMARTURLS_SIGNING_KEY=stopbot_v2_verify_2026_Xk9Pq7Lm4Rt2

You can create your own random text. Keep it private and do not commit it to GitHub. If it is empty, the application falls back to the API key as the signing secret, but using a separate value is recommended.

Do not commit .env.

Build

Go binaries are OS-specific. Build the binary for the operating system and CPU architecture where SmartURLs will run.

If you build on the same machine that will run SmartURLs, use the normal build commands below. If you build on a different machine, use the cross-compilation examples.

Windows

go test ./...
go build -o smarturls.exe .

Linux and macOS

go test ./...
go build -o smarturls .
chmod +x smarturls

Cross-Compile For Another OS

Use cross-compilation when you build on one OS but deploy to another OS.

Build Linux binary from Windows PowerShell

$env:GOOS="linux"
$env:GOARCH="amd64"
go build -o smarturls .
Remove-Item Env:\GOOS
Remove-Item Env:\GOARCH

Build Windows binary from Linux or macOS

GOOS=windows GOARCH=amd64 go build -o smarturls.exe .

Build Linux binary from Linux or macOS

GOOS=linux GOARCH=amd64 go build -o smarturls .
chmod +x smarturls

Common target values:

Target OS	GOOS	GOARCH	Output name
Linux server 64-bit Intel/AMD	linux	amd64	smarturls
Linux server ARM64	linux	arm64	smarturls
Windows 64-bit Intel/AMD	windows	amd64	smarturls.exe
macOS Apple Silicon	darwin	arm64	smarturls
macOS Intel	darwin	amd64	smarturls

If your hosting server is Linux, build a Linux binary even if you develop on Windows.

The template/message.html file is embedded into the executable at build time. After changing the template, rebuild the binary.

Run

Windows

.\smarturls.exe

Linux and macOS

./smarturls

For development, you can run without building:

go run .

By default, the application listens on:

http://localhost:8080

Example request:

http://localhost:8080/swWV8j

Deployment

Nginx is the recommended reverse proxy for production.

Keep the Go application listening on a local address and proxy all public requests through Nginx.

Example .env:

SMARTURLS_ADDR=127.0.0.1:8080
SMARTURLS_TRUST_PROXY_HEADERS=true

Example Nginx server block:

server {
    listen 80;
    server_name your-domain.example;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

After changing the configuration, test and reload Nginx:

sudo nginx -t
sudo systemctl reload nginx

Enable SMARTURLS_TRUST_PROXY_HEADERS=true only when SmartURLs is always behind your trusted reverse proxy and cannot be accessed directly.

SMARTURLS_TRUST_PROXY_HEADERS compatibility:

Deployment	Works with SMARTURLS_TRUST_PROXY_HEADERS?	Notes
Nginx	Yes	Requires X-Forwarded-For and X-Forwarded-Proto.
Apache	Yes	Requires mod_proxy, ProxyAddHeaders, and X-Forwarded-Proto.
Microsoft IIS	Yes	Requires ARR/URL Rewrite and HTTP_X_FORWARDED_PROTO.
Caddy	Yes	reverse_proxy sends common proxy headers automatically.
systemd	Not by itself	systemd only runs the app. Use this setting only if another reverse proxy is in front of the app.

Full deployment guides:

• Nginx
• Apache
• Microsoft IIS
• Caddy
• Run With systemd

JavaScript Verification Flow

When the V2 API returns jsResponse=1, this client renders a hidden browser check page.

The browser calls the local verification route:

/rsc/rjs.json?token=...

The token is signed by the server and contains the keyname, the API uniqueCode, and an expiry timestamp.

The Go server verifies the token, then calls STOPBOT V2 with:

js=1&keyname={keyname}&code={uniqueCode}

This keeps the STOPBOT API key server-side and avoids using the original keyname alone as the verification reference.

Configuration

Environment variable	Default	Description
STOPBOT_API_KEY	required	STOPBOT API key
SMARTURLS_ADDR	:8080	Server listening address
STOPBOT_API_ENDPOINT	https://api.stopbot.net/services/shorterlink	Full HTTPS API endpoint
SMARTURLS_SIGNING_KEY	API key fallback	Private local secret used to protect browser verification tokens
SMARTURLS_TRUST_PROXY_HEADERS	false	Trust client IP headers from Cloudflare or a reverse proxy

Existing operating-system environment variables take precedence over values in .env.

License

This project is released under the CC0 1.0 Universal license.