Repository Public
1// SP Wallet Core2// File: Sources/SPWalletCore/Domains/NFT/NFTMarketModels.swift3// Description: Models of the NFT market READ API (services/api/src/nft/market/routes.ts, service.ts; packages/nft/src/market.ts).4// One row PER SOURCE: nothing is merged, averaged or picked, and two sources that disagree are two rows and a named5// contradiction. A market value is a marketplace's statement with its source and its date — never chain truth, and a6// collection floor is never the value of an item. There is NO market write: every action is served as unavailable7// with its reason, and that is modelled as served, not assumed.8//9// Author: Simon-Pierre Boucher10// Contact: contact@spboucher.ai11import Foundation1213/** An exact amount of an exactly identified currency. `precision` says how the source gave it. */14public struct NFTMoney: Codable, Sendable, Hashable {15 public let amount: String16 public let currency: NFTCurrency17 /** `exact`: the source gave base units. `source_decimal`: the source gave a decimal number, converted digit by digit. */18 public let precision: String19 public var units: BaseUnits? { try? BaseUnits(amount) }20 /** Exact decimal text in the amount's own currency (no fiat conversion). */21 public var display: String? { units.map { $0.formatted(decimals: currency.decimals) } }22}2324/** One fee line a source reports for an order or a collection — market information, not something this wallet pays. */25public struct NFTMarketFee: Codable, Sendable, Hashable {26 /** `marketplace`, `creator_royalty`, `other`. */27 public let kind: String28 public let bps: Double?29 public let amount: NFTMoney?30 public let recipient: String?31 public let required: Bool?32}3334public struct NFTMarketProtocol: Codable, Sendable, Hashable { public let name: String; public let address: String? }3536public struct NFTMarketListing: Codable, Sendable, Hashable {37 /** The source's own identifier of the order; never a key across sources, and nothing here can act on it. */38 public let orderId: String?39 /** Total asked for `quantity` units. */40 public let price: NFTMoney41 public let quantity: String42 public let seller: String?43 public let venue: String?44 public let `protocol`: NFTMarketProtocol?45 public let createdAt: String?46 public let expiresAt: String?47 public let fees: [NFTMarketFee]?48}4950public struct NFTMarketOffer: Codable, Sendable, Hashable {51 public let orderId: String?52 public let price: NFTMoney53 public let quantity: String54 public let bidder: String?55 public let venue: String?56 /** `item`: an offer on this item; `collection` / `trait`: an offer any matching item could accept. */57 public let scope: String58 public let createdAt: String?59 public let expiresAt: String?60 public let fees: [NFTMarketFee]?61}6263public struct NFTMarketSale: Codable, Sendable, Hashable {64 public let price: NFTMoney65 public let quantity: String66 public let at: String?67 public let tx: String?68 public let buyer: String?69 public let seller: String?70 public let venue: String?71}7273public struct NFTAttribution: Codable, Sendable, Hashable { public let text: String; public let url: String }7475/** What one market source says about itself for one request: the SOURCE and the DATE of every figure of its row. */76public struct NFTMarketSourceStatus: Codable, Sendable, Hashable {77 public let provider: String78 public let name: String79 /** `ok`, `needs_key`, `off`, `not_covered`, `error`. Only `ok` rows carry figures. */80 public let state: String81 /** Stable code when not ok (`provider_rate_limited`, `budget_exhausted`, `not_found`, `chain_not_covered`, `no_api_key`, …) or the failure behind a stale row. */82 public let code: String?83 /** NAME of the server variable that would turn the source on — never a value. */84 public let unlockedBy: String?85 /** True when the row was served from the cache after a failure of the source (at most a day old). */86 public let stale: Bool87 /** Category `market`, with the time the server obtained the answer. */88 public let stamp: NFTSourceStamp?89 /** Attribution the source's terms ask for. */90 public let attribution: NFTAttribution?9192 public var isOK: Bool { state == "ok" }93 /** When the source's answer was obtained; nil when the source gave none. */94 public var fetchedAt: Date? { stamp?.fetchedAt }95}9697/** How a source qualifies a collection. Only `verified`, with the source NAMED, may be shown as a badge: it is that source's statement. */98public struct NFTMarketVerification: Codable, Sendable, Hashable {99 /** `verified`, `not_verified`, `unknown`. */100 public let state: String101 public let providerValue: String?102 public let by: String103}104105public struct NFTMarketRarity: Codable, Sendable, Hashable { public let rank: String; public let outOf: String?; public let method: String; public let calculatedAt: String? }106public struct NFTMarketItemFlags: Codable, Sendable, Hashable { public let suspicious: NFTKnown<Bool>; public let disabled: NFTKnown<Bool>; public let nsfw: NFTKnown<Bool> }107public struct NFTMarketCollectionName: Codable, Sendable, Hashable { public let slug: String; public let name: String? }108109/** One source's view of one item. The five price notions are five fields and are never substituted for one another. */110public struct NFTItemMarket: Codable, Sendable, Hashable {111 public let status: NFTMarketSourceStatus112 /** The item's page on the marketplace: opened outside the app only. */113 public let url: String?114 public let listed: NFTKnown<Bool>115 /** A live asking price. */116 public let ask: NFTKnown<NFTMarketListing>117 public let bestOffer: NFTKnown<NFTMarketOffer>118 /** A sale the source reports. */119 public let lastSale: NFTKnown<NFTMarketSale>120 /** The marketplace's own identifier and name of the collection — never copied into the on-chain collection. */121 public let collection: NFTMarketCollectionName?122 /** A statistic of the collection — never the value of this item. */123 public let collectionFloor: NFTKnown<NFTMoney>124 public let verification: NFTMarketVerification?125 public let flags: NFTMarketItemFlags?126 public let rarity: NFTKnown<NFTMarketRarity>?127}128129/** The rate of one currency from the wallet's own price sources, with ITS source and date. Secondary by construction. */130public struct NFTRate: Codable, Sendable, Hashable {131 public let currency: NFTCurrency?132 public let symbol: String133 /** Exact decimal text; nil when unavailable or withheld. */134 public let usd: String?135 public let cad: String?136 public let source: String137 public let priceAt: String?138 public let stale: Bool139 /** Set when the rate may not be answered to this caller (a licence of the price source). */140 public let withheld: String?141}142143/** One market action and why it cannot be done here. `available` is `false` as served for every action of this version. */144public struct NFTMarketAction: Codable, Sendable, Hashable, Identifiable {145 /** `buy`, `sell`, `create_listing`, `cancel_listing`, `make_offer`, `cancel_offer`, `accept_offer`. */146 public let id: String147 public let available: Bool148 /** `market_writes_not_built`. */149 public let reason: String?150}151152/** What is true about acting on a marketplace's own site with this wallet (shown with every external link). */153public struct NFTExternalNotice: Codable, Sendable, Hashable {154 public let outsideWallet: Bool155 /** `false` as served: the wallet offers no wallet connection. */156 public let walletConnect: Bool157 /** `false` as served: the wallet never exports a key. */158 public let keyExport: Bool159 public let code: String160}161162public struct NFTContradiction: Codable, Sendable, Hashable {163 /** `listed`, `ask`, `collection_floor`, `verification`. */164 public let field: String165 public let providers: [String]166 public let note: String167}168169/** `GET /nfts/market`: the market snapshot of one asset. */170public struct NFTMarketAnswer: Codable, Sendable, Hashable {171 public struct External: Codable, Sendable, Hashable { public let links: [NFTExternalLink]; public let notice: NFTExternalNotice }172 public let key: String173 public let sources: [NFTItemMarket]174 /** Where two `ok` sources say different things about the same notion: named, never resolved. */175 public let contradictions: [NFTContradiction]176 /** Keyed by `NFTCurrency.id`. */177 public let rates: [String: NFTRate]178 public let asOf: Date?179 public let actions: [NFTMarketAction]180 public let external: External?181 /** `state` is `unavailable` as served: an item has no value this wallet can establish from a floor or a single quote. */182 public let value: NFTValuationState?183184 /** True only if the server says an action can be done. No version of the backend does. */185 public var anyActionAvailable: Bool { actions.contains { $0.available } }186}187188/** `GET /nfts/market/listings` and `/offers`: one page per source. A cursor belongs to its source. */189public struct NFTMarketOrders<Item: Codable & Sendable & Hashable>: Codable, Sendable, Hashable {190 public struct Source: Codable, Sendable, Hashable { public let status: NFTMarketSourceStatus; public let items: [Item]; public let cursor: String? }191 public let key: String?192 /** `listings` or `offers`. */193 public let kind: String?194 public let sources: [Source]195 public let rates: [String: NFTRate]196 public let asOf: Date?197 public let actions: [NFTMarketAction]198}199200public struct NFTMarketEvent: Codable, Sendable, Hashable {201 public struct Flags: Codable, Sendable, Hashable { public let washTrade: NFTKnown<Bool> }202 /** `sale`, `list`, `delist`, `offer`, `cancel-offer`, `accept-offer`, `transfer`, `mint`, `unknown`. */203 public let type: String204 /** The source's own event name, kept beside the normalised type. */205 public let providerType: String206 public let at: String?207 public let tx: String?208 public let index: String?209 public let from: String?210 public let to: String?211 public let quantity: String212 public let price: NFTMoney?213 public let venue: String?214 public let orderId: String?215 /** Wash / self trade as the SOURCE reports it — passed through, never filtered. */216 public let flags: Flags?217 public let fees: [NFTMarketFee]?218 public var date: Date? { at.flatMap(ISO8601.parse) }219}220221/** `GET /nfts/market/activity`: market statements, listed apart from the chain's transfers. */222public struct NFTMarketEvents: Codable, Sendable, Hashable {223 public struct Source: Codable, Sendable, Hashable { public let status: NFTMarketSourceStatus; public let events: [NFTMarketEvent]; public let cursor: String? }224 public let key: String?225 public let sources: [Source]226 public let rates: [String: NFTRate]227 public let asOf: Date?228}229230/** The market event types `GET /nfts/market/activity` filters on. */231public enum NFTMarketEventType: String, Sendable, CaseIterable {232 case sale, list, delist, offer, cancelOffer = "cancel-offer", acceptOffer = "accept-offer", transfer, mint, unknown233}234235/** Filters of `GET /nfts/market/activity`. A cursor is a position in ONE source's list: it is only accepted with that source. */236public struct NFTMarketEventQuery: Sendable, Equatable {237 public var provider: String?238 public var cursor: String?239 public var types: [NFTMarketEventType]?240 public var after: Date?241 public var before: Date?242 /** 1…50. */243 public var limit: Int?244 public init(provider: String? = nil, cursor: String? = nil, types: [NFTMarketEventType]? = nil, after: Date? = nil, before: Date? = nil, limit: Int? = nil) {245 self.provider = provider; self.cursor = cursor; self.types = types; self.after = after; self.before = before; self.limit = limit246 }247}248249public struct NFTTraitCount: Codable, Sendable, Hashable { public let value: String; public let count: String }250public struct NFTCollectionTraits: Codable, Sendable, Hashable {251 public struct Category: Codable, Sendable, Hashable { public let type: String; public let values: [NFTTraitCount] }252 /** The stated number of items the counts were computed over. */253 public let total: String254 public let categories: [Category]255 /** True when the server cut the document (at most 40 categories of 12 values). */256 public let truncated: Bool?257}258259public struct NFTCollectionVolume: Codable, Sendable, Hashable {260 public struct Reported: Codable, Sendable, Hashable { public let value: String; public let symbol: String }261 /** `all`, `1d`, `7d`, `30d`. */262 public let interval: String263 public let volume: NFTMoney?264 /** The figure as the source words it when its unit is named by a symbol only: shown as reported, never converted or summed. */265 public let reported: Reported?266 public let sales: String?267}268269/** One source's view of one collection. */270public struct NFTCollectionMarket: Codable, Sendable, Hashable {271 public let status: NFTMarketSourceStatus272 public let slug: String?273 public let name: String?274 public let description: String?275 public let url: String?276 /** Media proxy ids: the marketplace's image URLs stay on the server. */277 public let imageId: String?278 public let bannerId: String?279 public let verification: NFTMarketVerification?280 public let floor: NFTKnown<NFTMoney>281 public let volumes: [NFTCollectionVolume]282 public let listedCount: NFTKnown<String>283 public let owners: NFTKnown<String>284 public let totalSupply: NFTKnown<String>285 public let fees: [NFTMarketFee]?286 /** Trait counts ONLY with a stated item total. */287 public let traits: NFTKnown<NFTCollectionTraits>288 /** What each figure means according to the source, when it says. */289 public let definitions: [String: String]?290}291292public struct NFTCollectionMarketAnswer: Codable, Sendable, Hashable {293 public let key: String?294 public let sources: [NFTCollectionMarket]295 public let rates: [String: NFTRate]296 public let asOf: Date?297}298299/** `GET /nfts/market/traits`: the frequency of each trait value of ONE item, per source, with its denominator, source and date. */300public struct NFTTraitAnswer: Codable, Sendable, Hashable {301 public struct Frequency: Codable, Sendable, Hashable {302 public let count: String303 public let total: String304 /** Exact to a hundredth of a percent, as text. */305 public let percent: String306 }307 public struct Row: Codable, Sendable, Hashable { public let traitType: String; public let value: String; public let frequency: Frequency? }308 public struct Source: Codable, Sendable, Hashable {309 public let provider: String310 public let name: String311 public let computed: Bool312 public let reason: String?313 public let total: String?314 public let fetchedAt: Date?315 public let stale: Bool?316 public let method: String?317 public let rows: [Row]318 }319 public let key: String?320 /** False when no source gives collection-level counts with a stated item total: nothing is computed from a partial sample. */321 public let computed: Bool322 public let reason: String?323 public let sources: [Source]324 public let mutableMetadata: Bool?325}326327/** One market provider slot of the server: on / needs key / off, what it would unlock, and its request budget. */328public struct NFTMarketProvider: Codable, Sendable, Hashable, Identifiable {329 public struct Terms: Codable, Sendable, Hashable { public let url: String; public let readAt: String; public let note: String }330 public struct Window: Codable, Sendable, Hashable { public let used: Int; public let limit: Int; public let date: String? }331 public struct Budget: Codable, Sendable, Hashable {332 public let provider: String?333 public let minute: Window334 public let day: Window335 public let refused: Int336 public let lastRefusedAt: String?337 public let upstreamLimited: Int338 public let lastUpstreamLimitedAt: String?339 }340 public let id: String341 public let name: String342 /** `on`, `needs_key`, `off`. */343 public let state: String344 public let unlockedBy: String?345 public let unlocks: String?346 public let chains: [String]347 /** What leaves the server when the provider is asked: `mint_only`, `contract_and_token_id`, `nothing`, `nothing_until_enabled`. Never the wallet address. */348 public let sends: String349 public let attribution: NFTAttribution?350 public let terms: Terms?351 /** `live`: the adapter was run against the real API; `documentation`: coded against the documented shapes only. */352 public let verification: String?353 public let budget: Budget?354 /** Cache lifetime of each data type, in seconds. */355 public let ttlSeconds: [String: Double]?356}357358public struct NFTMarketProviders: Codable, Sendable, Hashable {359 public let providers: [NFTMarketProvider]360 public let actions: [NFTMarketAction]361 public let notice: NFTExternalNotice?362}363364/**365 `GET /nfts/valuation`: the opt-in "indicative floor-based estimate". Default OFF. It is NOT a valuation and is never added to the366 wallet's total: per collection, the number of items held × the lowest floor a source reports, with that source and its age.367 */368public struct NFTFloorEstimate: Codable, Sendable, Hashable {369 public struct Floor: Codable, Sendable, Hashable { public let provider: String; public let name: String; public let floor: NFTMoney; public let fetchedAt: Date?; public let stale: Bool }370 public struct Used: Codable, Sendable, Hashable { public let provider: String; public let floor: NFTMoney; public let fetchedAt: Date?; public let stale: Bool; public let indicative: NFTMoney }371 public struct Collection: Codable, Sendable, Hashable {372 public let collectionKey: String373 public let chain: String374 public let name: String?375 public let items: Int376 /** Every source's figure, listed beside the one used. */377 public let floors: [Floor]378 public let used: Used?379 /** Why no floor was used (`no_floor_reported`, `market_unavailable`, a source code). */380 public let reason: String?381 }382 public struct Estimate: Codable, Sendable, Hashable {383 public let label: String384 public let method: String?385 public let collections: [Collection]386 public let rates: [String: NFTRate]387 /** Exact decimal text with two decimals; nil when no collection could be counted. */388 public let indicativeUsd: String?389 public let collectionsCounted: Int390 public let collectionsWithoutFloor: Int391 public let itemsWithoutCollection: String?392 public let asOf: Date?393 }394 public let enabled: Bool395 /** `unavailable` as served, whether the estimate is on or off. */396 public let state: String397 public let reason: String?398 /** `true` as served. */399 public let excludedFromWalletTotal: Bool400 public let estimate: Estimate?401}402403public struct NFTFloorEstimateSetting: Codable, Sendable, Hashable { public let enabled: Bool }404