OASIS Learn/Module 4
Intermediate ⏱ 30 min

NFTs & Wallet — Multi-Chain Digital Assets

OASIS wraps every blockchain's NFT standard behind one API. Create collections, mint tokens, place GeoNFTs on the real-world map, and import existing Web3 assets — without touching a single private key in your app code.

What you'll learn

  • How the OASIS provider-agnostic NFT layer works
  • Create a WEB4 NFT collection and mint tokens into it
  • Load and collect NFTs for an avatar
  • Create and collect GeoNFTs (location-anchored NFTs on the world map)
  • Bridge existing Web3 NFTs into the OASIS
  • Send tokens via the multi-chain wallet

How OASIS NFTs Work

Traditional NFTs are chain-specific. An NFT on Solana doesn't exist on Ethereum, and vice versa. OASIS introduces the WEB4 NFT — a chain-agnostic digital asset record that the platform can represent on any supported provider (Solana, Ethereum, EOSIO, Holochain, or OASIS' own storage) based on your configuration.

From your app's perspective you always call the same API regardless of which chain is backing the NFT. The OASIS routing layer handles minting on the configured provider, IPFS metadata pinning and cross-chain bridging transparently.

🔗
Supported NFT providers

Solana (via Metaplex), Ethereum/EVM (ERC-721/1155), EOSIO, Holochain, IPFS + OASIS native storage. The active provider is set in your OASIS node config or passed per-request as providerType.

Creating an NFT Collection

A collection groups related NFTs — like all items in your game, or all editions of a limited drop. Create it once; mint into it repeatedly.

create-collection.js
import { oasis } from './oasis.js';

const { result: collection } = await oasis.nft.createWeb4NFTCollectionAsync({
  name:        'Founders Weapons',
  description: 'Legendary weapons for OASIS Founders NFT holders',
  symbol:      'FWPN',
  imageUrl:    'https://myapp.com/assets/collection-banner.png',
  maxSupply:   1000,               // 0 = unlimited
  royaltyBps:  500,                // 5% secondary royalty (basis points)
  mintedByAvatarId: avatarId       // who created the collection
});

console.log('Collection ID:', collection.id);
console.log('On-chain address:', collection.mintAddress);

Minting NFTs

Import an NFT definition into the OASIS — this triggers minting on the configured provider and returns the on-chain address.

mint-nft.js
// Mint a single WEB4 NFT into an existing collection
const { result: nft } = await oasis.nft.importWeb4NFTAsync({
  importedByAvatarId: avatarId
}, {
  // NFT metadata
  title:          'Sword of Light #001',
  description:    'A legendary blade forged in the first age of Our World.',
  imageUrl:       'https://myapp.com/assets/sword-of-light.png',
  animationUrl:   'https://myapp.com/assets/sword-glow.mp4',  // optional
  collectionId:   collection.id,
  attributes: [
    { traitType: 'Rarity',  value: 'Legendary' },
    { traitType: 'Element', value: 'Light'     },
    { traitType: 'Damage',  value: '250-300'   }
  ],
  externalUrl:  'https://myapp.com/items/sword-001',
  quantity:     1                     // 1 = unique; >1 = semi-fungible
});

console.log('Minted NFT ID:', nft.oasisNFTId);
console.log('Mint address:',  nft.mintAddress);
console.log('Metadata URI:',  nft.metadataUri);

Loading NFTs

javascript
// All WEB4 NFTs owned by the logged-in avatar
const { result: myNFTs } = await oasis.nft.loadAllWeb4NFTsForAvatarAsync({ avatarId });

myNFTs.forEach(nft => {
  console.log(`${nft.title} — ${nft.mintAddress}`);
});

// All WEB4 NFTs across all avatars (admin / marketplace view)
const { result: allNFTs } = await oasis.nft.loadAllWeb4NFTsAsync();

// Look up by mint wallet address (useful for verifying ownership)
const { result: byWallet } = await oasis.nft.loadAllWeb3NFTsForMintAddressAsync({
  mintWalletAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
});

Collecting (Transferring) an NFT

When a user earns or purchases an NFT, call collectNFTAsync to transfer it to their avatar's wallet.

javascript
const result = await oasis.nft.collectNFTAsync({
  oasisNFTId:    nft.oasisNFTId,  // the NFT to transfer
  avatarId,                       // recipient avatar
  providerType:  'Solana'         // optional; defaults to node config
});

if (!result.isError) {
  console.log('NFT transferred!', result.result?.transactionId);
}

GeoNFTs — Location-Anchored Assets

A GeoNFT is an NFT placed at a real-world GPS coordinate on the OASIS Our World map. Players must physically travel to (or virtually visit) that location to collect it. This enables location-based games, treasure hunts, city-wide scavenger hunts and real-world brand activations.

geo-nft.js
// Place a GeoNFT on the world map
const { result: geoNFT } = await oasis.nft.importWeb4NFTAsync({
  importedByAvatarId: avatarId
}, {
  title:       'Hidden Treasure of London',
  description: 'Find this cache near Tower Bridge!',
  imageUrl:    'https://myapp.com/assets/treasure-chest.png',
  isGeoNFT:    true,
  lat:          51.5055,     // Tower Bridge, London
  lng:         -0.0754,
  collectRadius: 50        // metres — how close a player must be to collect
});

// Load all GeoNFTs on the map (public — no auth needed)
const { result: mapNFTs } = await oasis.nft.loadAllGeoNFTsAsync();

// Player collects a nearby GeoNFT
await oasis.nft.collectGeoNFTAsync({
  oasisNFTId: geoNFT.oasisNFTId,
  avatarId,
  playerLat:  51.5056,
  playerLng: -0.0755
  // Server validates player is within collectRadius
});
🗺️
Real-world use case — city-wide treasure hunt

A tourist board placed 50 GeoNFTs across their city, each representing a historic landmark. Players who visit all 50 locations and collect the NFTs receive a "City Explorer" badge NFT and a real discount at local restaurants (verified by showing their OASIS wallet). Footfall to lesser-known landmarks increased 3×.

Bridging Web3 NFTs into OASIS

Already have NFTs on Solana, Ethereum or another chain? Import them into the OASIS unified layer so they appear in the avatar's wallet alongside WEB4 NFTs.

javascript
// Import an existing Web3 NFT by its on-chain mint address
const { result: bridged } = await oasis.nft.importWeb3NFTAsync({
  mintAddress:    'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
  providerType:   'Solana',
  avatarId
});

console.log('Bridged NFT:', bridged.title, bridged.oasisNFTId);

Wallet — Sending Tokens

The OASIS wallet layer abstracts over every chain's token standard. Send any supported token without knowing which chain it lives on.

wallet.js
// Send a token to another avatar (must be authenticated)
const result = await oasis.wallet.sendTokenAsync({
  toAvatarId:    recipientAvatarId,     // or toWalletAddress for raw chain transfer
  amount:        10.5,
  token:         'OLAND',               // token symbol (OLAND, SOL, ETH, SEEDS…)
  providerType:  'Solana',
  memo:          'Quest reward payment'
});

if (!result.isError) {
  console.log('Transaction ID:', result.result?.transactionId);
}

Exporting NFTs

Export a WEB4 NFT to a standard JSON file (useful for cold-storage backups or marketplace listings):

javascript
// Export NFT metadata to JSON
const { result: exported } = await oasis.nft.exportWeb4NFTAsync({
  oasisNFTId: nft.oasisNFTId
});

// Export directly to a file path (server-side)
await oasis.nft.exportWeb4NFTToFileAsync({
  oasisNFTId:       nft.oasisNFTId,
  fullPathToExportTo: '/exports/sword-of-light-001.json'
});

NFT & Wallet API Quick Reference

← Previous
Karma & Reputation