NauticalNotary

Automated maritime document notarization, apostille issuance, and vessel registry cross-validation. Built for ship managers, P&I clubs, and port state control officers who are tired of faxing things to Luxembourg at 3am.

---

What's new in v2.4

• Real-time AIS integration — vessel identity now verified live against AIS transponder data before document signing. Uses the MarineTraffic stream + our own aggregator (see config/ais.yml). Latency is ~1.2s on average, which Dmitri says is fine, personally I think we should cache more aggressively but that's a fight for next sprint
• 163 flag state registries supported (up from 147). Added: Cook Islands, Niue, São Tomé and Príncipe, Comoros, Djibouti, Eritrea, Kiribati, Nauru, Palau, Samoa, Solomon Islands, Tonga, Tuvalu, Vanuatu, Timor-Leste, and a few others — full list in docs/flag-states.md
• IMO DCS compliance badge — NauticalNotary now validates CII rating fields against IMO DCS schema v3.1 before apostille. If you don't know what that means you probably don't need it
• BIMCO SmartCon connector (experimental, do not use in prod yet) — see below
• Apostille batch mode — new --batch-apostille flag, finally

---

Quickstart

pip install nautical-notary

Basic single-document apostille:

naunotary apostille \
  --vessel MMSI:636019847 \
  --registry LR \
  --doc ./bill_of_sale_draft.pdf \
  --output ./apostilled/

New in v2.4 — batch mode:

naunotary apostille \
  --batch-apostille \
  --input-dir ./pending_docs/ \
  --vessel-manifest ./vessels.csv \
  --ais-verify live \
  --output ./apostilled/ \
  --concurrency 4

The --ais-verify live flag pulls real-time position + identity from the AIS stream. Set to cached if you're running offline or the stream is down (happens more than I'd like). Set to skip only if you know what you're doing and have signed the waiver doc that legal sent around in April.

---

AIS Integration

Configure in config/ais.yml:

ais:
  provider: marinetraffic         # or 'aisstream', 'myshiptracking'
  api_key: ${AIS_API_KEY}         # do NOT hardcode here, learned this the hard way
  fallback_provider: aisstream
  cache_ttl_seconds: 90
  timeout_ms: 2000
  strict_mmsi_match: true         # if false we allow IMO fallback — Reza wants this false, I disagree

The aggregator lives in src/ais/aggregator.py. It's a mess right now, I'm refactoring it in CR-2291 but that's blocked on the MarineTraffic webhook migration.

---

IMO DCS Compliance

Documents containing fuel consumption data (MRV, DCS reports) are now validated against IMO DCS schema v3.1 before notarization proceeds. Non-conforming fields will raise a DCSValidationError. To bypass (discouraged):

naunotary apostille ... --skip-dcs-validation

---

BIMCO SmartCon Connector (experimental)

⚠️ This feature is experimental and not covered by our SLA. Do not use for legally binding instruments without reviewing the output manually. Possibly forever. We'll see.

Connects to BIMCO's SmartCon API to embed notarized document hashes into smart charter party contracts. Enable with:

naunotary apostille ... --bimco-smartcon --smartcon-template NYPE2015

Requires BIMCO_CLIENT_ID and BIMCO_CLIENT_SECRET in your environment. The connector currently supports NYPE 2015, GENCON 1994, and BARECON 2017 templates. SUPPLYTIME support is planned but honestly who uses SUPPLYTIME.

Known issues with SmartCon connector:

• Hash embedding sometimes silently fails on contracts > 80 pages (#441 — open since January, no ETA)
• Doesn't handle multipart charter parties yet — Valentina is looking at this
• The BIMCO sandbox environment is flaky on Tuesdays for reasons no one has explained

---

Flag State Coverage

163 flag states as of v2.4. Coverage by region:

Region	States
Europe	38
Asia-Pacific	42
Americas	31
Africa	28
Middle East	14
Pacific Islands	10

Some registries only support partial validation (read-only, no cert issuance). See docs/flag-states.md for the full breakdown including which ones still fax us PDFs.

---

Configuration

Full config reference: docs/configuration.md

cp config/naunotary.example.yml config/naunotary.yml
# fill in your creds, registry endpoints, etc.

---

Development

git clone https://github.com/fastauctionaccess/nautical-notary
cd nautical-notary
python -m venv venv && source venv/bin/activate
pip install -e ".[dev]"
pytest tests/

The integration tests require a running local mock of the AIS aggregator (make mock-ais). Unit tests run fine standalone. CI runs the full suite including registry API mocks; see .github/workflows/ci.yml.

---

License

AGPL-3.0. If you're embedding this in a commercial product, talk to us first. Several P&I clubs already have a commercial license — details in LICENSE.commercial.

---

NauticalNotary is not affiliated with any flag state authority, classification society, or the IMO. Documents produced should be reviewed by a qualified maritime lawyer. We are software people. Нам доверяют корабли, но мы не юристы.