NFT Schema Docs

markdoc/partials/nft-data/Bids.md

@@ -0,0 +1,25 @@
+## Bids
+
+On the Goldsky platform, users have the ability to view top bids -— these are the highest ongoing propositions for any NFT in a given collection.
+
+Currently, top bids from the Blur marketplace are incorporated into the platform. We are constantly looking to expand our marketplace coverage and include various bid types.
+
+The array containing the top bids can be located in the field `top_bids` in the Collection Table, available in the "NFT by..." queries, and also direct in the Collections by Wallet query.
+
+**Key Information on Bids**:
+
+Field | Description | Type(s)
+--- | --- | ---
+`marketplace_id` | Single, distinct identifier of the NFT marketplace where the top bid is placed | `string`
+`value` | The top bid's monetary amount in the relevant currency | `int`/`null`
+`payment_token` | Information about the currency used | `payment_token`
+
+**Payment Token Information**:
+
+Field | Description | Type(s)
+--- | --- | ---
+`payment_token_id` | Single, distinct identifier of the token type related to the collection | `string`
+`name` | Title of the token | `string`/`null`
+`symbol` | Short sign of the token | `string`/`null`
+`address` | The contract address of the collection's associated ERC-20 token | `string`/`null`
+`decimals` | The base number of decimals for the token value in the collection | `int`

markdoc/partials/nft-data/Collections.md

@@ -0,0 +1,41 @@
+## Collections
+
+The Goldsky platform offers comprehensive insights into the collection associated with a particular NFT. Notably, these collections are often tied to specific NFT marketplaces. The Collection Table, which is embedded within the NFT Table, includes a variety of fields. Presently, the Goldsky platform encompasses collections from a range of platforms like OpenSea, Trove, and MagicEden.
+
+Here are the details encapsulated in the Collection Table available within NFT responses and core Collection queries:
+
+Field | Description | Type(s)
+--- | --- | ---
+`collection_id` | Distinct identifier for a particular collection | `string` / `null`
+`name` | Title of the collection | `string` / `null`
+`description` | Brief about the collection | `string` / `null`
+`image_url` | URL leading to the collection's logo or main image | `string` / `null`
+`banner_image_url` | URL leading to the collection's banner image | `string` / `null`
+`category` | Category of the collection, if available | `string` / `null`
+`is_nsfw` | Flag indicating if the collection is marked as NSFW | `boolean` / `null`
+`external_url` | URL of the external website or resource linked to the collection | `string` / `null`
+`twitter_username` | The Twitter handle linked to the collection | `string` / `null`
+`discord_url` | The Discord server linked to the collection | `string` / `null`
+`instagram_url` | Instagram URL for the collection | `string` / `null`
+`medium_username` | Medium.com username associated with the collection | `string` / `null`
+`telegram_url` | Telegram URL for the collection | `string` / `null`
+`marketplace_pages` | Array of objects referencing the collection's page(s) on a marketplace | see below
+`metaplex_mint` | Unique metaplex mint ID, only for Solana NFTs that are part of a verified metaplex collection | `string` / `null`
+`metaplex_first_verified_creator` | Identifier to group by the initial verified creator address when a verified metaplex collection is not available | `string` / `null`
+`spam_score` | Spam rating of the NFT collection, ranges from 0-100 (100 signifies high likelihood of being spam) | `int` / `null`
+`floor_prices` | Array of minimum prices for the collection, one for each marketplace | `[Floor price model]`
+`top_bids` | Array of highest bids for the collection, one for each marketplace | `[Top bid model]`
+`chains` | Array of chains included in the collection | `[chain:string]`
+`top_contracts` | Array of contracts linked to this collection | `[contract_id:string]`
+
+**Marketplace Page Details**:
+```
+[{
+`marketplace_id`: string,
+`marketplace_name`: string,
+`marketplace_collection_id`: string,
+`nft_url`: string / null,
+`collection_url`: string,
+`verified`: boolean / null
+}]
+```

markdoc/partials/nft-data/Floor-Price.md

@@ -0,0 +1,34 @@
+## Floor Price
+
+A floor price is the minimum listed price for an NFT within a specific collection—this often applies to a specific NFT marketplace.
+
+The Goldsky platform provides insights into the floor price of NFT collections across various chains, currently including:
+
+- Ethereum: Live
+- Polygon: Live
+
+The platform encompasses floor prices from multiple marketplaces such as CryptoPunks, Tensor, Blur, OpenSea, X2Y2, LooksRare, and Magic Eden.
+
+Please note, marketplaces like LooksRare and Blur might display the "global floor price", representing the lowest price across several marketplaces.
+
+We are continually working to cover more chains and marketplaces.
+
+You can locate the `floor_prices` array in the `floor_prices` field within the Collection Table for "NFT by..." queries, and it is also accessible directly in the Collections by Wallet query.
+
+**Comprehensive Floor Price Details**:
+
+Field | Description | Type(s)
+--- | --- | ---
+`marketplace_id` | Distinct identifier of the NFT marketplace tied to the floor price | `string`
+`value` | The floor price's monetary amount in the relevant currency | `int`/`null`
+`payment_token` | Details about the applicable currency | `payment_token`
+
+**Payment Token Information**:
+
+Field | Description | Type(s)
+--- | --- | ---
+`payment_token_id` | Distinct identifier of the token type associated with the collection | `string`
+`name` | Title of the token | `string` / `null`
+`symbol` | Short representation of the token | `string` / `null`
+`address` | The contract address of the ERC-20 token related to the collection | `string` / `null`
+`decimals` | The base number of decimals for the token value associated with the collection | `int`

markdoc/partials/nft-data/Listings.md

@@ -0,0 +1,55 @@
+## Listings
+
+The Goldsky platform includes details of active and historical listings on NFT marketplaces.
+
+Currently supported live marketplaces:
+
+- MagicEden: Live
+- CryptoPunks: Live
+- Tensor: Live
+- Blur: Live
+- OpenSea: Live
+- LooksRare: Live
+- X2Y2: Live
+
+More marketplaces will be covered in the near future.
+
+**Listing Table**:
+
+Field | Description | Type(s)
+--- | --- | ---
+id | Unique identifier of the listing | string
+permalink | Link to the marketplace listing | string
+bundle_item_number | If the listing is part of a bundle, the NFT's position in the bundle | int / null
+listing_timestamp | Datetime of the listing | string
+expiration_timestamp | Expiration datetime of the listing | string / null
+seller_address | Owner wallet address | string
+auction_type | Auction type, if applicable. Possible values are: dutch (AKA decreasing price auction) | string / null
+quantity | Original listing quantity | int
+quantity_remaining | Remaining listing quantity | int
+price | Total price of the listing | int
+marketplace_id | Unique identifier of the NFT marketplace associated with the listing | string
+collection_id | Unique identifier for a specific collection | string / null
+nft_id | Unique identifier for an NFT | string
+payment_token | Detail on the token used for the listing | payment_token / null
+
+**Listing Event Table**:
+
+Field | Description | Type(s)
+--- | --- | ---
+id | Unique identifier of the listing event | string
+event_type | Generic type of event, one of: listing_added, listing_modified, listing_removed | string
+event_reason | More detailed reason (if available); one of: listing_cancelled, listing_expired, ownership_changed, quantity_changed, price_changed | string / null
+event_timestamp | Datetime of the event as processed | string
+listing_id | Unique identifier of the listing from the Listing Table | string
+... | (Additional fields from the Listing Table) | 
+
+**Payment Token Table**:
+
+Field | Description | Type(s)
+--- | --- | ---
+payment_token_id | Unique identifier of the token type relevant to the collection | string
+name | Name of the token | string / null
+symbol | Symbol of the token | string / null
+address | Contract address of the ERC-20 token associated with the collection | string / null
+decimals | Base number of decimals of the token value associated with the collection | int

markdoc/partials/nft-data/NFT.md

@@ -0,0 +1,159 @@
+## NFT
+
+The Goldsky platform presents detailed, normalized data related to NFTs in the form of the NFT Table. This table consists of the following fields:
+
+Field | Description | Type(s)
+--- | --- | ---
+`nft_id` | Distinct identifier for an NFT | `string`
+`chain` | The blockchain's name where the NFT exists | `string`
+`contract_address` | Address of the contract related to the NFT | `string`
+`token_id` | ID of the NFT's token on its contract. Null for Solana and Bitcoin NFTs | `string` / `null`
+`name` | The name of the NFT, obtained from its metadata | `string` / `null`
+`description` | Description of the NFT, derived from its metadata | `string` / `null`
+`previews` | Set of URLs leading to resized preview images of the media | see below
+`image_url` | URL leading to the cached image file | `string` / `null`
+`image_properties` | Properties of the image, if available | see below
+`video_url` | URL leading to the cached video file | `string` / `null`
+`video_properties` | Properties of the video, if available | see below
+`audio_url` | URL leading to the cached audio file | `string` / `null`
+`audio_properties` | Properties of the audio, if available | see below
+`model_url` | URL leading to the cached 3D model file | `string` / `null`
+`model_properties` | Properties of the model, if available | see below
+`other_url` | URL leading to the cached file for other media types such as PDFs | `string` / `null`
+`other_properties` | Properties of the file, if available | see below
+`background_color` | Background color of the NFT, as per its metadata | `string` / `null`
+`external_url` | External URL, as per the NFT’s metadata | `string` / `null`
+`created_date` | Date and time of NFT minting in timestamp format (e.g., 2021-07-03T23:45:00) | `string` / `null`
+`status` | Status of the NFT, either 'minted', or 'burned' | `string`
+`token_count` | Known quantity of this NFT | `int` / `null`
+`owner_count` | Known number of owners of this NFT | `int` / `null`
+`owners` | Array of top owners of this NFT | see below
+`last_sale` | Details on the most recent sale involving this NFT | `last_sale` / `null`
+`first_created` | Details of the first creation of this NFT | see below
+`contract` | Type of contract information for this NFT | see below
+`collection` | Information associated with this NFT's collection | `Collection model`
+`rarity` | Information on this NFT's rarity | `Rarity model`
+`royalty` | Array of royalty details, by source | see below
+`extra_metadata` | JSON field containing additional custom metadata fields | see below
+
+**Previews**:
+```
+{
+`image_small_url`: string / null,
+`image_medium_url`: string / null,
+`image_large_url`: string / null,
+`image_opengraph_url`: string / null,
+`blurhash`: string / null,
+`predominant_color`: string / null
+}
+```
+
+**Image Properties**:
+```
+{
+`width`: int / null,
+`height`: int / null,
+`size` : int / null,
+`mime_type`: str / null
+}
+```
+
+**Video Properties**:
+```
+{
+`width`: int / null,
+`height`: int / null,
+`duration`: float / null,
+`video_coding`: str / null,
+`audio_coding`: str / null,
+`size`: int / null,
+`mime_type`: str / null
+}
+```
+
+**Audio Properties**:
+```
+{
+`duration`: float / null,
+`audio_coding`: str / null,
+`size`: int / null,
+`mime_type`: str / null
+}
+```
+
+**Model Properties**:
+```
+{
+`size`: int / null,
+`mime_type`: str / null
+}
+```
+
+**Other Properties**:
+```
+{
+`size`: int / null,
+`mime_type`: str / null
+}
+```
+
+**Owners**:
+```
+[{
+`owner_address`: string,
+`quantity`: int,
+`first_acquired_date`: string,
+`last_acquired_date`: string
+}]
+```
+
+**First Created**:
+```
+{
+`minted_to: string / null,
+quantity: int / null,
+timestamp: string / null,
+block_number: int / null,
+transaction: string / null,
+transaction_initiator: string / null
+}
+```
+
+**Contract**:
+```
+{
+type:string,
+name:string / null,
+symbol:string / null,
+deployed_by: string / null,
+deployed_via_contract: string / null
+}
+```
+
+**Royalty**:
+```
+[{
+source: string,
+total_creator_fee_basis_points: int,
+recipients: [{
+address: string,
+percentage: float,
+basis_points: int
+}]
+}]
+```
+
+**Extra Metadata**:
+```
+{
+attributes: [{
+trait_type:string,
+value:string,
+display_type:string / null
+}],
+...,
+image_original_url:string / null,
+animation_original_url:string / null,
+metadata_original_url:string / null
+}
+```

markdoc/partials/nft-data/Rarity.md

@@ -0,0 +1,13 @@
+## Rarity
+
+The Goldsky platform adopts the OpenRarity standard to derive a consistent and mathematically-based rarity score for NFTs.
+
+Currently, our system lends support to ERC-721 and Metaplex non-fungible token standards. We are working towards providing support for ERC-1155 in the near future.
+
+**Rarity Score Details**:
+
+Field | Description | Type(s)
+--- | --- | ---
+`rank` | Rarity rank—determined in relation to the scores of all other NFTs within the same collection | `int` / `null`
+`score` | The calculated raw rarity score | `float` / `null`
+`unique_attributes` | The count of unique attributes or traits, if any, possessed by this NFT | `int` / `null`

markdoc/partials/nft-data/Sales.md

@@ -0,0 +1,43 @@
+## Sales
+
+The Goldsky platform offers in-depth details on the sale of NFTs, which are included within the NFT and transfer tables.
+
+In NFT responses, sale information can be found in the `last_sale` field, and transfer responses are included in the `sale_details` field.
+
+**NFT Sale Table** (embedded within the NFT Table):
+
+Field | Description | Type(s)
+--- | --- | ---
+`from_address` | Address from where the NFT was sold | `string` / `null`
+`to_address` | Address where the NFT was acquired | `string` / `null`
+`quantity` | Quantity of NFTs transacted. Null if `is_bundle_sale` is `true` | `int` / `null`
+`timestamp` | Date and time of the NFT sale | `string`
+`transaction` | Unique identifier of the transaction involving the NFT sale | `string`
+`marketplace_id` | Identifier of the marketplace where the sale happened | `string`
+`marketplace_name` | Name of the marketplace where the sale happened | `string`
+`is_bundle_sale` | Indicates whether the sale was a bundle sale | `boolean`
+`payment_token` | Details about the token used in the NFT sale. Null if `is_bundle_sale` is `true` | `payment_token` / `null`
+`unit_price` | Individual unit price of an item within the NFT sale. Null if `is_bundle_sale` is `true` | `int` / `null`
+`total_price` | Total price of the NFT sale. Null if `is_bundle_sale` is `true` | `int` / `null`
+`unit_price_usd_cents` | Price of an individual item within the NFT sale, in USD cents, at the time of the transaction. Null if `is_bundle_sale` is `true` | `int` / `null`
+
+**Transfer Sale Details Table** (embedded within the transfer Table):
+
+Field | Description | Type(s)
+--- | --- | ---
+`marketplace_id` | Identifier of the marketplace where the sale happened | `string` / `null`
+`marketplace_name` | Name of the marketplace where the sale took place | `string`
+`is_bundle_sale` | Indicates whether the sale was a bundle sale | `boolean`
+`payment_token` | Details about the token used in the NFT sale. Null if `is_bundle_sale` is `true` | `payment_token` / `null`
+`unit_price` | Individual unit price of an item within the NFT sale. Null if `is_bundle_sale` is `true` | `int` / `null`
+`total_price` | Total price of the NFT sale. Null if `is_bundle_sale` is `true` | `int` / `null`
+
+**Payment Token Details**:
+
+Field | Description | Type(s)
+--- | --- | ---
+`payment_token_id` | Unique identifier of the token type utilized in the sale | `string`
+`name` | Name of the token | `string` / `null`
+`symbol` | Symbol of the token | `string` / `null`
+`address` | Contract address of the token used in the sale (null for the native ETH token) | `string` / `null`
+`decimals` | Base number of decimals of the token value involved in the NFT sale | `int`