Geocaching Events

1 Overview

A geocache is a physical container hidden at a real-world location. This NIP defines event kinds for geocaching on Nostr. Users create, share, and log geocaches in a decentralized manner. No company owns the cache database.

The system uses five event kinds. A listing (kind 37516) describes one cache. A found log (kind 7516) records a successful visit. A comment log (kind 1111, per NIP-22) records failures, notes, and maintenance reports. A verification event (kind 7517) gives cryptographic proof of physical presence. A curation list (kind 37517) groups caches into themed collections.

The submitter owns the listing and maintains its core details. The community adds context through logs. Together the events show the current state and validity of each cache.

2 Geocache Listing — Kind 37516

A listing is an addressable event (see NIP-01) of kind 37516. It carries all information about the cache and all information relevant to finding it. The required data is the name, the location (g), the difficulty (D) and terrain (T) scores, and the size (S).

{
  "kind": 37516,
  "content": <cache description>,
  "tags": [
    ["d", <cache-identifier>],
    ["name", <cache-name>],
    ["g", <geohash>],
    ["D", <1-5>],
    ["T", <1-5>],
    ["S", <size>],
    ["t", <type>],
    ["n", <type-modifier>],
    ["hint", <plaintext hint>],
    ["mission", <key quest mission>],
    ["image", <image-url>],
    ["r", <relay-url>],
    ["verification", <verification-pubkey-hex>]
  ]
}

The content field contains the cache description and any additional information about the cache.

Cache types are determined by individual clients. Each client decides which cache types it supports, based on its implementation needs. The submitter owns the listing. The submitter maintains the core details. Community logs provide context on the current state and validity of the cache.

The mission tag ("Key Quest")

A mission tag states a task that finders must complete to legitimately claim the cache. Examples: a passphrase, a riddle answer, or an item to bring. A treasure must not include more than one mission tag. If multiple are present, clients should use the first and ignore the rest.

When a mission is present, clients should restrict found-log submission to finders who have proof of physical presence. That proof is typically the verification key from the cache location (§6). A client may record a completed mission as a NIP-GD Good Deed event whose a tag references the cache.

3 Found Log — Kind 7516

A found log is a regular event of kind 7516. It records one successful visit to one geocache. The content holds the log message.

{
  "kind": 7516,
  "content": <log message>,
  "tags": [
    ["a", "37516:<pubkey>:<d-tag>"]
  ]
}

4 Comment Logs — Kind 1111

Non-found logs use comment events of kind 1111, following the NIP-22 comment structure. These events capture failures, notes, and status information about the cache via human reporting. In the NIP-22 threading model the geocache listing is both the root content and the parent content.

{
  "kind": 1111,
  "content": <log message>,
  "tags": [
    ["A", "37516:<pubkey>:<d-tag>"],
    ["K", "37516"],
    ["P", <cache-owner-pubkey>],
    ["a", "37516:<pubkey>:<d-tag>"],
    ["k", "37516"],
    ["p", <cache-owner-pubkey>],
    ["t", <log-type>]
  ]
}

The uppercase A/K/P tags mark the root. The lowercase a/k/p tags mark the parent. Both follow NIP-22. For these top-level comments, root and parent are identical: they reference the listing coordinate (37516:<pubkey>:<d-tag>), the kind 37516, and the cache owner's pubkey.

An image tag with photos from the visit is optional on comment logs too. The cache owner can officially retire a cache with the archived value in the t tag. This preserves the cache's history without fully deleting it.

5 Verification Event — Kind 7517

A verification event is a regular event of kind 7517. It provides cryptographic proof that someone physically located a geocache. The cache's verification private key signs this event — not the finder's key.

{
  "kind": 7517,
  "content": "Geocache verification for <finder-npub>",
  "tags": [
    ["a", "<finder-pubkey-hex>:<geocache-naddr>"]
  ]
}

The content must follow the static format "Geocache verification for <finder-npub>". Here <finder-npub> is the NIP-19 encoded public key (npub) of the person who found the cache.

The single required a tag is a composite identifier. It contains the finder's pubkey in hex format, then a colon, then the naddr of the geocache being verified.

A finder creates this event after obtaining the cache's verification private key, typically via a QR code at the cache location. The event must be signed by that verification private key. The finder can then deliver it in three ways:

1. Embed it in the verification tag of the found log (kind 7516) as a JSON string.
2. Publish it to relays as a standalone event.
3. Both embed and publish, for redundancy.

6 Verified Finds

A cache with a verification tag can prove that a finder physically located it. The proof is a kind 7517 event signed by the cache's verification key.

Verification process (finder side)

1. Obtain the cache's verification private key, typically via a QR code at the cache location.
2. Create a verification event (kind 7517). Sign it with this key.
3. Embed the verification event in your log entry.

Validation (verifier side)

To validate a verified find, perform four checks:

1. Check that the verification event is signed by the expected verification public key.
2. Verify that the finder pubkey in the a tag matches the log author.
3. Confirm that the geocache naddr in the a tag correctly references the target cache.
4. Validate the event signature with standard Nostr verification.

7 Type Modifiers

A listing may include one or more n tags that classify the geocache with additional type modifiers. The t cache-type tag describes how a cache is found. The n modifiers describe how the cache behaves once published — its lifecycle, claim semantics, or prize nature.

The mission tag is also a type modifier in the broader sense. It uses its own dedicated tag because it carries a payload: the mission text. Clients should treat mission and n modifiers consistently for display purposes, such as badges and filters.

Rules

1. Each modifier value belongs to exactly one category.
2. A geocache should include at most one n tag per category. If multiple values from the same category are present, clients should use the first occurrence and ignore the rest.
3. Modifiers from different categories compose freely. Any combination is valid unless a specific modifier's definition states otherwise.
4. Clients should ignore n values they do not recognize. This allows forward compatibility as new modifiers are defined.

Claim semantics: first-to-find

The first verified found log — a kind 7516 event with a valid embedded kind 7517 — constitutes the exclusive claim. Subsequent verified found logs remain valid records of physical presence at the location. They do not constitute additional claims. Once any valid verified found log exists, clients should render the listing as effectively archived: hide the find-submission affordances and display the winning finder prominently.

Determine the provisional winner, before lock-in, with these rules:

• The winning log is the verified found log with the earliest created_at value.
• Break ties on created_at by ascending lexicographic comparison of the event id.
• All verified logs are evidence of physical presence — QR access was required to produce them. The exclusive claim goes only to the earliest one.

Locking in the winner (the F tag). Once the listing creator has confirmed the claim, the creator should publish a new revision of the listing that does both of these things: it archives the listing by adding ["t", "archived"], and it locks the winner in by appending an F tag:

["t", "archived"],
["F", <winner-pubkey-hex>]

• The F value is the winning finder's pubkey in lowercase hex. To recover the specific winning log, query for verified found logs whose a tag references this treasure and whose author matches the F pubkey.
• At most one F tag should be present. If multiple are present, clients should use the first.
• When an F tag is present, clients must attribute the exclusive claim to the pubkey in the F tag — regardless of which verified found log currently appears earliest. created_at is author-supplied and forgeable. The lock protects the claim from a later log with a forged earlier timestamp.

Forward compatibility

Future revisions of this NIP, or supplementary NIPs, may define new modifiers. New categories may also be introduced. Clients implementing this NIP should ignore unknown n values rather than reject the event.

8 Curation Lists — Kind 37517

A curation list is an addressable event of kind 37517. It groups geocaches into a curated collection. Clients may present these as adventures, trails, treasure hunts, or any other themed experience.

{
  "kind": 37517,
  "content": <full description>,
  "tags": [
    ["d", <list-identifier>],
    ["title", <list-title>],
    ["description", <short summary>],
    ["image", <banner-image-url>],
    ["g", <geohash>],
    ["theme", <page-theme>],
    ["map", <map-style>],
    ["a", "37516:<pubkey>:<d-tag>"],
    ["a", "37516:<pubkey>:<d-tag>"]
  ]
}

The content field contains the full description of the list — rules, tips, narrative, or any other context the creator wants to provide.

Cross-author references. A curation list can reference any public geocache, regardless of author. The a tags use the standard NIP-01 addressable event coordinates (<kind>:<pubkey>:<d-tag>). One list can span geocaches from multiple creators.

9 Client Guidelines

For the best geocaching experience, a client that implements this NIP should:

• Support hint encoding, such as ROT13, to prevent spoilers.
• Determine cache status from recent log patterns. Multiple DNF entries and/or maintenance notes indicate an issue with the cache.
• Publish logs to the relays listed in the cache's r tags, when available.
• Validate geohash precision before accepting a cache submission: at least 8 characters, and at least 9 for micro caches.

10 Worked Example

One cache, one find, one failure, one collection. The owner hides a verified treasure in Oslo. A finder scans the QR code and posts a verified found log. Another visitor strikes out and posts a DNF comment.

{
  "kind": 37516,
  "content": "High-security treasure requiring physical verification!",
  "tags": [
    ["d", "verified-treasure-1748619568669"],
    ["name", "Verified Treasure"],
    ["g", "u4x"], ["g", "u4xsu6"], ["g", "u4xsu6ry"],
    ["D", "3"],
    ["T", "2"],
    ["S", "small"],
    ["t", "traditional"],
    ["hint", "Look for the secret code"],
    ["verification", "6805d4e5c0df48b4…f34f1c07"]
  ]
}

{
  "kind": 7517,
  "content": "Geocache verification for npub1qc0lc5lxnhxnf…qd8h2z3",
  "tags": [
    ["a", "0461fcbecc4c3374…35a474dd:naddr1qqxnzd3e8q6n2dfk8…qfgrf8"]
  ],
  "pubkey": "6805d4e5c0df48b4…f34f1c07",   // the cache's verification pubkey
  "created_at": 1672531200,
  "sig": "a1b2c3d4e5f67890…cdef12"
}

{
  "kind": 7516,
  "content": "Found it! Great hiding spot.",
  "tags": [
    ["a", "37516:0461fcbecc4c3374…35a474dd:verified-treasure-1748619568669"],
    ["verification", "{\"kind\":7517,\"content\":\"Geocache verification for npub1qc0…\",…}"]
  ]
}

-- a less lucky visitor reports a DNF --
{
  "kind": 1111,
  "content": "Searched for 30 minutes but couldn't find it. Maybe it's missing?",
  "tags": [
    ["A", "37516:0461fcbe…74dd:verified-treasure-1748619568669"],
    ["K", "37516"],
    ["P", "0461fcbe…74dd"],
    ["a", "37516:0461fcbe…74dd:verified-treasure-1748619568669"],
    ["k", "37516"],
    ["p", "0461fcbe…74dd"],
    ["t", "dnf"]
  ]
}

-- the owner groups this cache into a themed hunt --
{
  "kind": 37517,
  "content": "Explore the festival grounds and find all hidden treasures!",
  "tags": [
    ["d", "ren-fest-hunt-1748619568670"],
    ["title", "Texas Ren Fest Treasure Hunt"],
    ["description", "Find all the hidden treasures at the festival!"],
    ["g", "9vk"], ["g", "9vk5b7"],
    ["theme", "adventure"],
    ["map", "adventure"],
    ["a", "37516:0461fcbe…74dd:first-treasure-1748619568668"],
    ["a", "37516:0461fcbe…74dd:verified-treasure-1748619568669"]
  ]
}

For a first-to-find art drop, the listing adds ["n", "first-to-find"] and ["n", "art"], plus a verification tag. After the first verified log arrives, the owner republishes the listing with ["t", "archived"] and ["F", <winner-pubkey-hex>] to lock the claim (§7).

11 Version History

NIP-CC is young. It landed in 2026 and received one major revision two weeks later:

• 20262026-06Major update by Chad Curtis (#2365): aligned the spec with the modern "NIP-GC" implementation — verification events, type modifiers (first-to-find, art), the F lock-in tag, missions, and curation lists.
• Origin2026-05-28fiatjaf merged the initial "add NIP-CC: geocaching" spec: listings, found logs, and comment logs.

12 See Also

• NIP-01 — addressable events, the d tag, a tag coordinates, and single-letter tag indexing used throughout.
• NIP-22 — the comment structure (A/K/P and a/k/p) that kind 1111 logs follow.
• NIP-19 — the npub and naddr encodings used in verification events.
• NIP-52 — calendar events; another way to attach real-world activity to Nostr.
• NIP-73 — external content IDs, useful for referencing off-Nostr cache databases.