> ## Documentation Index
> Fetch the complete documentation index at: https://grailx.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Watermarking

> How invisible watermarks work in SQR — embedding, scanning, and the full lifecycle.

SQR encodes short messages into images using invisible frequency-domain watermarking. The watermark survives printing, photographing, compression, and moderate cropping.

## How it works

1. A unique 5-character ID (e.g. `A1B2C`) is generated for each record
2. The ID is encoded into the image's frequency domain using a spread-spectrum technique
3. The watermarked image looks identical to the original — the difference is imperceptible
4. To verify, a photo of the watermarked image is decoded to recover the embedded ID

## Embed a watermark

### Via record creation (recommended)

When you create a record, the watermark is embedded automatically:

```bash theme={null}
curl -X POST https://yys-sqr-render-bsbe.onrender.com/api/records \
  -H "Authorization: Bearer $SQR_KEY" \
  -F template_id=pharma \
  -F 'metadata={"product_name":"Aspirin"}' \
  -F image=@label.jpg
```

The response includes `watermarked_image` (base64) — decode and save it:

```python theme={null}
import base64

response = create_record(...)
img_bytes = base64.b64decode(response["watermarked_image"])
with open("label_watermarked.jpg", "wb") as f:
    f.write(img_bytes)
```

### Standalone embed

If you just want to embed a message without creating a record:

```bash theme={null}
curl -X POST https://yys-sqr-render-bsbe.onrender.com/api/embed \
  -H "Content-Type: application/json" \
  -d '{
    "image": "base64-encoded-image...",
    "message": "A1B2C"
  }'
```

<Warning>
  The message is limited to 5 characters. This is by design — shorter payloads are more robust against degradation.
</Warning>

## Scan a watermark

To decode a watermark from a photograph:

```bash theme={null}
curl -X POST https://yys-sqr-render-bsbe.onrender.com/api/scan \
  -H "Content-Type: application/json" \
  -d '{
    "image": "base64-encoded-photo...",
    "corners": [[10,10], [500,10], [500,500], [10,500]]
  }'
```

The `corners` parameter defines the four corners of the label in the photo, allowing SQR to correct for perspective distortion.

## Scan via record endpoint

Once you have the decoded watermark ID, look up the record:

```bash theme={null}
curl https://yys-sqr-render-bsbe.onrender.com/api/records/SQR-A1B2C
```

And log the scan event:

```bash theme={null}
curl -X POST https://yys-sqr-render-bsbe.onrender.com/api/records/SQR-A1B2C/scan \
  -H "Content-Type: application/json" \
  -d '{"scanner_address": "0xabc..."}'
```

## Best practices

* Use high-resolution source images (1000px+ on the shortest side)
* Avoid heavy JPEG compression on the watermarked output
* When printing, use at least 300 DPI
* For scanning, photograph the label straight-on with good lighting