Introduction

This package exposes wallet API functions and useful utility functions for handling NFTs within the Portal ecosystem. The following functions this package exposes are:

• getAllOwnedNfts
• getOwnedNftsInCollection
• claimNft
• transferNft

Examples with API

getAllOwnedNfts

getAllOwnedNfts literally gets all NFTS owned by the calling agent.

To use getAllOwnedNfts in production, it is simply a matter of calling it like below. By default, this searches for owned NFTs within Entrepot market place, which will contain Portal NFT collections as well in the future.

import { useAuthentication } from '@nft-portal/providers';
import { getAllOwnedNfts } from '@nft-portal/wallet';

// An authenticated agent of your choice. You are not restricted
// to using Portal's method of authentication
const { agent } = useAuthentication(); 

const res = await getAllOwnedNfts(agent);

// prints out a list of NFTs owned by the user the agent represents
console.log(res); 

An override exists to specify which NFT collection registry you want to search. Here, you have the option of using Portal's NFT collection registries.

This is particularly useful for testing within our staging environment.

import { useAuthentication } from '@nft-portal/providers';
import { getAllOwnedNfts } from '@nft-portal/wallet';

// An authenticated agent of your choice. You are not restricted
// to using Portal's method of authentication
const { agent } = useAuthentication(); 

// Portal's staging environment NFT collection registry which contains
// a list of staging NFT canisters.
const STAGING_COLLECTION_REGISTRY = 'aaaaa-aa'

const res = await getAllOwnedNfts(agent, {
  nftCollectionRegistryCid: STAGING_COLLECTION_REGISTRY,
});

// prints out a list of NFTs owned by the user in the staging environment
console.log(res); 

getOwnedNftsInCollection

If you only want to get the NFTs belonging to one particular channel you would use getOwnedNftsInCollection.

import { useAuthentication } from '@nft-portal/providers';
import { getOwnedNftsInCollection } from '@nft-portal/wallet';

// An authenticated agent of your choice. You are not restricted
// to using Portal's method of authentication
const { agent } = useAuthentication(); 

// NOTE: the NFT collection canister is a separated entity to the Channel canister. Your channel
// will create an NFT collection canister and it is this canister which is used for this api.
const nftCollectionCid = 'aaaaa-aa'

const res = await getOwnedNftsInCollection(agent, nftCollectionCid);

// prints out a list of NFTs owned by the user in that one particular NFT Collection, regardless of staging
// or production environment.
console.log(res); 

Claim NFT

import { useAuthentication } from '@nft-portal/providers';
import { claimNft } from '@nft-portal/wallet';
import React from 'react';

import { SolidButton } from './Buttons';

export const ClaimButton = () => {
  const { agent } = useAuthentication();

  const CHANNEL_CANISTER_ID = 'aaaaa-aa';
  // Here you add the content ID the NFT is allocated to.
  const contentId = 'e5915008-468d-4a2d-ae20-f4d24674debd';
  const onClick = async () => {
    try {
      const res = await claimNft(agent, CHANNEL_CANISTER_ID_TWO, contentId);
      // Prints out the tokenId of the claimed NFT
      console.log(res);
    } catch (e) {
      // Will fail if there are no NFTs left to claim, if the user already has an NFT (limited 1 per person)
      // or if the channel is not configured to give out NFTs for free.
      console.error(e);
    };
  }
  return (
    <SolidButton
      onClick={onClick}
      label="Claim your free NFT"
    />
  );
};

This function is a wrapper around one of the @nft-portal/portal-sdk clients.

Transfer NFT

If you own an NFT you are able to transfer it to someone else.

import { useAuthentication } from '@nft-portal/providers';
import { transferNft } from '@nft-portal/wallet';
import React from 'react';

import { SolidButton } from './Buttons';

export const TransferButton = () => {
  const { agent } = useAuthentication();

  const NFT_COLLECTION_CANISTER_ID = '4nwps-saaaa-aaaaa-aabjq-cai';
  const DESTINATION_WALLET_ID = 'bd1aa50ba7ca2a89f2d88e04c08e65fdbf40f82471cbd356e86429212cd020de';

  // This token id can be retrieved from the existing "get" wallet endpoints
  const TOKEN_ID = 'vjnut-gakor-uwiaa-aaaaa-aaaak-maqca-aaaaa-a'

  const onClick = async () => {
    try {
      const res = await transferNft({
        agent,
        nftCollectionCid: NFT_COLLECTION_CANISTER_ID,
        tokenId: TOKEN_ID,
        to: DESTINATION_WALLET_ID,
      });
      // The response will simply be the amount transfered, which for NFTs
      // will always be 1.
      console.log(res);
    } catch (err) {
      console.error(err);
    }
  }
  return (
    <SolidButton
      onClick={onClick}
      label="Transfer your NFT"
    />
  );
};

NFT wallet example

Below is one way to make a in app NFT wallet.

import { HttpAgent } from '@dfinity/agent';
import { useEffect, useState } from 'react';

import { getAllOwnedNfts } from '../apis';
import { NftDetails } from '../types';

export const useWallet = (agent: HttpAgent) => {
  const [nfts, setNfts] = useState<NftDetails[]>([]);
  const [isLoading, setIsLoading] = useState(false);
  const [isError, setIsError] = useState(false);

  useEffect(() => {
    const fetchNfts = async () => {
      setIsError(false);
      setIsLoading(true);

      try {
        const nfts = await getAllOwnedNfts(agent);
        setNfts(nfts);
      } catch (error) {
        setIsError(true);
      }
      setIsLoading(false);
    };
    fetchNfts();
  }, [agent]);

  return {
    nfts,
    isLoading,
    isError,
  };
};