NFT Endpoints

Description of endpoints used to get data related to posts on the DeSo blockchain

Please make sure you've read Data: API so you are familiar with the following types referenced in this documentation:

• ProfileEntryResponse

• PostEntryResponse

• BalanceEntryResponse

• NFTEntryResponse

• NFTCollectionResponse

Get NFTs For User

POST /api/v0/get-nfts-for-user

Get NFTs that a user owns, optionally filtering on for-sale status and pending (NFT transferred) status.

Endpoint implementation in backend.

Example usages in frontend: - Make request to Get NFTs For User - Use GetNFTsForUser to get NFTs to display in a gallery on a user's profile

Request Body

Name	Type	Description
UserPublicKeyBase58Check*	String	Public key for user who owns NFTs
ReaderPublicKeyBase58Check	String	Public key of the reader
IsForSale	Boolean	- If true, only return NFTs that are for sale. - If false, only return NFTs that are not for sale. - If not provided, return NFTs regardless of for sale status
IsPending	Boolean	- If IsForSale is provided, this value is ignored. - Otherwise, if true, only return NFTs that are pending acceptance (NFTs that have been transferred but not accepted). - If false, only return NFTs that are not pending acceptance. If not provided, return NFTs regardless of pending status

200: OK Successfully retrieved the requested NFTs owned by the provided user

Sample Response

{
  "NFTsMap": { // Map of Post Hash Hex to an object containing a PostEntryResponse AND an NFTEntryResponse.
    "4bd205ec36bb13e76620b48ffc601340562c3ad7fa61b5343f0d9edc6ff6e2f8": {
      "PostEntryResponse": <PostEntryesponse>, // PostEntryResponse of the post that is an NFT owned by UserPublicKeyBase58Check
      "NFTEntryResponses": [<NFTEntryResponse>, <NFTEntryResponse>]// NFTEntryResponses describe the serial numbers of this NFT. There may be multiple for a given post if a user owns multiple NFTs
    },
  }
}

Response Field Descriptions

400: Bad Request

Get NFT Bids For User

POST /api/v0/get-nft-bids-for-user

Get active bids for a user.

Endpoint implementation in backend.

Example usages in frontend: - Make request to Get NFT Bids For User - Use GetNFTBidsForUser to show a user their outstanding bids when they view their own profile

Request Body

Name	Type	Description
UserPublicKeyBase58Check*	String	Public key for user whose bids we want to find
ReaderPublicKeyBase58Check	String	Public key of the reader

200: OK Successfully retrieved all NFT bids for a given user

Sample Response

{
   {
  "NFTBidEntries": [
    {
      "PublicKeyBase58Check": "BC1YLhtBTFXAsKZgoaoYNW8mWAJWdfQjycheAeYjaX46azVrnZfJ94s", // Public key of the user who submitted this bid
      "PostHashHex": "43b943880ff21f67b92941553233b9d0e6bcf7c56e9a533416873d4d0798d290", // Hex of Post hash of the post that is an NFT.
      "SerialNumber": 85, // Serial number on which this bid was submitted.
      "BidAmountNanos": 1000000000, // Amount of DeSo bid (in nanos)
      "HighestBidAmountNanos": 1000000000, // Highest bid amount currently on this serial number
      "LowestBidAmountNanos": 0, // Lowest bid amount currently on this serial number
      "BidderBalanceNanos": 5000000000 // DeSo balance of the bidder
    }
  ],
  "PostHashHexToPostEntryResponse": {
    "43b943880ff21f67b92941553233b9d0e6bcf7c56e9a533416873d4d0798d290": <PostEntryResponse>
  },
  "PublicKeyBase58CheckToProfileEntryResponse": {
    "BC1YLgF9Tt85ADrL4QiyX6xSGwGrqFWnLr9b5Mt8hfdk54Tg1JJzi9e": <ProfileEntryResponse>
  }
}

Response Field Descriptions

400: Bad Request

Get NFT Bids For NFT Post

POST /api/v0/get-nft-bids-for-nft-post

Get all bids for all serial numbers of a given NFT post.

Endpoint implementation in backend.

Example usages in frontend: - Make request to Get NFT Bids For NFT Post - Use GetNFTBidsForNFTPost to show all active bids on all serial numbers of an NFT collection

Request Body

Name	Type	Description
PostHashHex*	String	Hex of Post hash for which we want to fetch bids
ReaderPublicKeyBase58Check	String	Public key of the reader

200: OK Successfully retrieved all bids on all serial numbers for the given post

Sample Response

{
  "BidEntryResponses": [ // Array of BidEntryResponses which represents all the bids on all serial numbers of NFTs with the provided PostHashHex.
    {
      "PublicKeyBase58Check": "BC1YLhtBTFXAsKZgoaoYNW8mWAJWdfQjycheAeYjaX46azVrnZfJ94s", // Public key of user who submitted bid
      "ProfileEntryResponse": <ProfileEntryResponse>,  // ProfileEntryResponse of user who submitted bid.
      "SerialNumber": 85, // Serial number on which this bid was submitted.
      "BidAmountNanos": 1000000000, // Amount of DeSo bid (in nanos).
      "BidderBalanceNanos": 5000000000 // DeSo balance of the bidder.
    }
  ],
  "NFTEntryResponses": [<NFTEntryResponse>, <NFTEntryResponse>, ...],// NFT entry responses for each serial number. There will be one for each serial number.
  "PostEntryResponse": <PostEntryResponse> // PostEntryResponse of the post that is an NFT.
}

Response Field Descriptions

400: Bad Request

Get NFT Showcase

POST /api/v0/get-nft-showcase

Get summaries of all NFTs included in the NFT showcase.

Endpoint implementation in backend.

Example usage in frontend: - Make request to Get NFT Showcase - Use GetNFTShowcase to fetch all the NFTs to display in the NFT showcase

Request Body

Name	Type	Description
ReaderPublicKeyBase58Check	String	Public key of the reader

200: OK Successfully retrieved NFT Collection Responses for all NFT posts in the current NFT showcase

Sample Response

{
  "NFTCollections": [<NFTCollectionResponse>, <NFTCollectionResponse>,...]
}

Response Field Descriptions

400: Bad Request

Name	Type	Description
NFTCollections	NFTCollectionResponse[]	Array of objects representing all the NFTs in the current NFT Showcase

Get Next NFT Showcase

POST /api/v0/get-next-nft-showcase

Get the time the next NFT showcase drop so it can be advertised to users

Endpoint implementation in backend.

Example usages in frontend: - Make request to Get Next NFT Showcase - Use GetNextNFTShowcase to show users the time at which the next NFT showcase drops

200: OK Successfully retrieved the timestamp at which the next NFT showcase will drop

Sample Response

{
  "NextNFTShowcaseTstamp": 109872497124 // Time the next NFT showcase will drop
}

Response Field Descriptions

400: Bad Request

Name	Type	Description
NextNFTShowcaseTstamp	uint64	Time the next NFT showcase will drop

Get NFT Collection Summary

POST /api/v0/get-nft-collection-summary

Get an NFTCollectionResponse that summarizes a single NFT post

Endpoint implementation in backend.

Example usages in frontend: - Make request to Get NFT Collection Summary - Use GetNFTCollectionSummary to a summary of the current state of the NFT collection and each serial number

Request Body

Name	Type	Description
PostHashHex*	String	Hex of Post hash for which we want to fetch a NFTCollectionResponse
ReaderPublicKeyBase58Check	String	Public key of the reader

200: OK Successfully retrieved the NFT Collection for the requested post

Sample Response

{
  "NFTCollectionResponse": {
    "ProfileEntryResponse": <ProfileEntryResponse>, // ProfileEntryResponse of the creator of the NFT
    "PostEntryResponse": <PostEntryResponse>, // PostEntryResponse of the post that is an NFT
    "HighestBidAmountNanos": 2000000000, // Highest bid amount currently on any serial number of this Post
    "LowestBidAmountNanos": 0, // Lowest bid amount currently on any serial number of this Post
    "HighestBidAmountNanos": 35000000000, // Highest buy now price currently on any serial number of this Post
    "LowestBidAmountNanos": 0, // Lowest buy now price currently on any serial number of this Post
    "NumCopiesForSale": 1, // Number of serial numbers currently for sale of this NFT post.
    "NumCopiesBuyNow": 1, // Number of serial numbers currently for sale as "Buy Now" NFTs - this means a user can purchase the NFT at the BuyNowPriceNanos without requiring an accept NFT bid transaction from the owner.
    "AvailableSerialNumbers": [15] // Array of integers representing the set of all serial numbers that are for sale of this NFT post.
  },
  SerialNumberToNFTEntryResponse: { // Map of serial number to NFT Entry Response
    1: <NFTEntryResponse>,
    2: <NFTEntryResponse>,
  }
}

Response Field Descriptions

400: Bad Request

Get NFT Entries For Post Hash

POST /api/v0/get-nft-entries-for-nft-post

Gets an NFTEntryResponse for each serial number of this NFT post.

Endpoint implementation in backend.

Example usages in frontend: - Make request to Get NFT Entries for Post Hash

Request Body

Name	Type	Description
PostHashHex*	String	Hex of Post hash for which we want to fetch all NFTEntryResponse objects
ReaderPublicKeyBase58Check	String	Public key of the reader

200: OK Successfully retrieved NFTEntryResponse objects for all serial numbers of the NFT post

Sample Response

{
  "NFTEntryResponses": [<NFTEntryResponse>, <NFTEntryResponse>, ...] // There will be one NFT Entry response for each serial number.
}

Response Field Descriptions

400: Bad Request

Name	Type	Description
NFTEntryResponses	[]	An array of objects representing the current state of each serial number of the NFT post