Skip to content

Quickstart

This guide walks you through the core PrimeStamp workflow: creating an identity, stamping a document, and verifying it.

1. Create a Signing Identity

A signing identity is an Ed25519 key pair. The private key signs your stamps; the public key lets others verify your authorship.

With the CLI

primestamp identity generate -o my-identity.json

This creates my-identity.json containing your key pair. Keep this file secure -- anyone with the private key can sign stamps as you.

With the Python API

from primestamp import KeyPair

key_pair = KeyPair.generate()

print(f"Public key:  {key_pair.public_key_hex}")
print(f"Private key: {key_pair.private_key_hex}")

To restore a key pair later from a saved private key:

key_pair = KeyPair.from_hex("your_private_key_hex_string")

2. Stamp a Document

With the CLI

# Basic stamp with default settings (Bitcoin + Ethereum anchors)
primestamp stamp document.pdf -k my-identity.json

# Use a preset for preconfigured settings
primestamp stamp document.pdf -k my-identity.json -p standard

# Specify output location
primestamp stamp document.pdf -k my-identity.json -o document.stamp.json

# Include a Prime-Space fingerprint for partial proofs
primestamp stamp document.pdf -k my-identity.json -p archival --fingerprint

With the Python API

from primestamp import StampEngine, KeyPair

# Create engine with a new identity
engine = StampEngine.with_new_identity()

# Stamp from a string
stamp = engine.create_stamp(
    "This is my important document content.",
    preset="standard",
)

# Stamp from bytes
stamp = engine.create_stamp(
    b"\x89PNG\r\n...",
    preset="archival",
)

# Stamp from a file path
from pathlib import Path
stamp = engine.create_stamp(
    Path("document.pdf"),
    preset="standard",
)

# Save the stamp to disk
engine.save_stamp(stamp, "document.stamp.json")

What does a preset control?

Presets configure the storage backend, encryption, blockchain anchors, and trust threshold all at once. See Presets for details on each level.

3. Verify a Stamp

With the CLI

# Verify stamp structure and signature
primestamp verify document.stamp.json

# Verify stamp AND check content hash against the original file
primestamp verify document.stamp.json -f document.pdf

The output shows a table of checks: signature validity, content hash match, trust score, and overall result.

With the Python API

from primestamp import StampEngine

engine = StampEngine()

# Load a stamp from disk
stamp = engine.load_stamp("document.stamp.json")

# Full verification with content check
result = engine.verify_stamp(stamp, b"This is my important document content.")

print(f"Valid:          {result.is_valid}")
print(f"Signature OK:   {result.signature_valid}")
print(f"Content match:  {result.content_hash_valid}")
print(f"Trust score:    {result.trust_score}/{result.trust_threshold}")
print(f"Trust met:      {result.trust_met}")

For a quick boolean check:

matches = engine.verify_content(stamp, b"This is my important document content.")
print(f"Content matches: {matches}")

4. Use Convenience Functions

PrimeStamp provides module-level functions for quick one-off operations:

from primestamp import create_stamp, verify_stamp, hash_document

# Hash a document
doc_hash = hash_document("My document content")
print(f"SHA3-256: {doc_hash}")

# Create a stamp without an engine instance
stamp = create_stamp(
    "My document content",
    private_key="your_private_key_hex",
    preset="casual",
)

# Verify without an engine instance
result = verify_stamp(stamp, "My document content")
print(f"Valid: {result.is_valid}")

5. Inspect a Stamp

With the CLI

# Human-readable summary
primestamp info document.stamp.json

# Raw JSON output
primestamp info document.stamp.json --json

With the Python API

engine = StampEngine()
stamp = engine.load_stamp("document.stamp.json")

print(f"Stamp ID:   {stamp.stamp_id}")
print(f"Created:    {stamp.created_at}")
print(f"Algorithm:  {stamp.document.plaintext_hash.algorithm.value}")
print(f"Hash:       {stamp.document.plaintext_hash.value}")
print(f"Signed:     {stamp.author.signature is not None}")
print(f"Anchors:    {[a.value for a in stamp.anchoring.requested_anchors]}")

6. Generate a Prime-Space Fingerprint

Fingerprints enable partial proofs -- proving properties of a document without revealing its full contents.

from primestamp import generate_fingerprint, compare_fingerprints

# Generate a fingerprint
content = b"My document content goes here..."
fp = generate_fingerprint(content)

print(f"Merkle root:  {fp.merkle_root}")
print(f"Chunks:       {fp.chunk_count}")
print(f"Shadow scales: {list(fp.shadows.keys())}")
print(f"Entropy:      {fp.frequency.entropy:.2f}")

# Compare two documents structurally
fp1 = generate_fingerprint(b"Document version 1")
fp2 = generate_fingerprint(b"Document version 1 with edits")

similarities = compare_fingerprints(fp1, fp2)
for scale, sim in sorted(similarities.items()):
    print(f"Scale {scale}: {sim * 100:.1f}% similar")

7. Verification URLs

Every stamp gets a public verification URL that anyone can use to confirm document integrity without installing PrimeStamp.

The format is:

https://primestamp.io/verify/{stamp_id}

For example, after stamping a document:

stamp = engine.create_stamp("My document content", preset="standard")
print(f"Verify at: https://primestamp.io/verify/{stamp.stamp_id}")

The verification URL is shown automatically:

  • CLI: Displayed in the stamp result panel after primestamp stamp.
  • Web Dashboard: Shown as a clickable link after stamp creation.
  • Mobile & Desktop Apps: Available via "Share Verification Link" or "Open in Browser" buttons.
  • QR Codes: Encoded in the QR data payload alongside the stamp ID and hash.

Self-Hosted Verification Portal

If you run a self-hosted PrimeStamp deployment, set the PRIMESTAMP_BASE_URL environment variable to override the default URL:

export PRIMESTAMP_BASE_URL=https://verify.mycompany.com

All apps and the CLI will use your custom base URL for verification links.

Next Steps