OASIS Learn/Module 14
Intermediate ⏱ 35 min WEB5

GeoNFTs & AR Location Services

GeoNFTs are NFTs anchored to real-world GPS coordinates — discoverable via augmented reality at their exact location. GeoHotSpots are location-based triggers without an NFT: spawn points, portals, checkpoints. Together they power the OASIS AR layer used by Our World.

What you'll build

  • Mint a GeoNFT and anchor it to a GPS coordinate
  • Query GeoNFTs within a radius of the player's location
  • Create a GeoHotSpot (spawn point, checkpoint, portal)
  • Trigger mission objectives when a player enters a hotspot radius
  • Use the OASIS Unity SDK to display GeoNFTs in AR
📦
API references

GeoNFTs-API.md ↗ · GeoHotSpots-API.md ↗ · npm: @oasisomniverse/web5-api ↗

Minting a GeoNFT

A GeoNFT is created in two steps: mint the NFT (Module 4 pattern), then anchor it to a coordinate.

mint-geonft.js
import { oasis4, star } from './star.js';

// 1. Mint the base NFT
const { result: nft } = await oasis4.nft.mint({
  avatarId,
  title:       'Crimson Key Fragment #001',
  description: 'One of three key fragments hidden across London.',
  imageUrl:    'https://cdn.oasisomniverse.one/keys/crimson-001.png',
  providerType: 'SolanaOASIS',
});

// 2. Anchor to a GPS coordinate
const { result: geoNft } = await star.geoNfts.anchor({
  nftId:       nft.id,
  latitude:    51.5081,    // Trafalgar Square, London
  longitude:   -0.1281,
  altitude:    0,
  radiusMetres: 50,         // visible within 50m
  discoveryKarmaReward: 100,
  hint:        'Near the lion statues…',
});

console.log('GeoNFT anchored at:', geoNft.latitude, geoNft.longitude);

Querying Nearby GeoNFTs

nearby-geonft.js
// Get GeoNFTs within 500m of the player
const { result: nearby } = await star.geoNfts.getNearby({
  latitude:     playerLat,
  longitude:    playerLng,
  radiusMetres: 500,
  includeCollected: false,   // hide already-collected ones
});

console.log(`${nearby.length} GeoNFTs nearby:`);
nearby.forEach(g => {
  const dist = g.distanceMetres.toFixed(0);
  console.log(`  ${g.title}  ${dist}m away  karma=${g.discoveryKarmaReward}`);
});

Collecting a GeoNFT

collect-geonft.js
// Player taps a GeoNFT in AR — collect it
const { result, isError, message } = await star.geoNfts.collect({
  geoNftId: geoNft.id,
  avatarId,
  latitude:  playerLat,
  longitude: playerLng,
});

if (isError) {
  // e.g. "Player is 120m away — must be within 50m"
  console.error('Cannot collect:', message);
} else {
  console.log('Collected! Karma awarded:', result.karmaAwarded);
}

GeoHotSpots — Location Triggers

hotspot.js
// Create a mission checkpoint hotspot
const { result: hotspot } = await star.geoHotSpots.create({
  name:         'Citadel Entrance',
  hotSpotType:  'MissionCheckpoint',
  latitude:     51.5033,
  longitude:    -0.1195,
  radiusMetres: 30,
  missionId:    crimsonKeyMissionId,
  objectiveIndex: 0,              // auto-complete objective 0 on entry
  karmaReward:  10,
});

Displaying GeoNFTs in Unity AR

In a Unity project using the OASIS SDK, the OASISGeoManager component handles all of this automatically:

csharp
// Unity C# — attach to your AR scene manager
using NextGenSoftware.OASIS.API.ONODE.WebAPI.Controllers;

public class ARWorldManager : MonoBehaviour
{
    async void Start()
    {
        // Fetch nearby GeoNFTs and spawn AR prefabs at their GPS coords
        var nearby = await OASISGeoManager.Instance
            .GetNearbyGeoNFTsAsync(radiusMetres: 500);

        foreach (var geoNft in nearby)
            OASISGeoManager.Instance.SpawnARObject(geoNft);
    }
}
💡
Our World is the production reference

The Our World AR game uses GeoNFTs and GeoHotSpots at every point of interest worldwide. Its Unity integration is the most complete example of the OASIS AR layer in production.

Next steps