Skip to main content
KiteMarket-API is an independent Java 11/MIT SDK without a dependency on the proprietary market-core. The original KiteMarketApi supplies read-only queries and post-commit notifications. The v1.1 adds separate services for extension registration and restricted player-confirmed requests. See downloads for runtimes, public interfaces and examples. Query signatures below remain applicable to v1.0.0. V1.1 DTOs and services need matching host and SDK versions; always select the public SDK that matches the host plugin version.

Reference the SDK

Project examples reference SDK Maven coordinates on GitHub Packages. Direct GitHub Releases downloads remain a fallback. Both provide the same public interfaces without the proprietary trading core.

GitHub Packages

Reference both SDKs with compileOnly/provided. Public Packages downloads need a classic PAT with read:packages. Confirm that the required version has been uploaded before using it.

Packages reference configuration

SDK coordinates, Gradle, Maven, user-level credentials and authentication checks.

Release-download fallback

Release-file downloads do not require a Packages Token and can provide a fallback compile dependency for offline development.

Release downloads and runtime requirements

SDK file downloads, plugin dependencies and the SDK bundling restriction.

Runtime requirements

Add depend: [KiteMarket] to plugin.yml. If your plugin also works without the market, use softdepend, but load classes referencing the API only after confirming the host exists. Do not bundle, shade or relocate the SDK. KiteMarket supplies the unique runtime interface classes; duplicate copies can prevent service lookup. The SDK JAR is not a server plugin.

Wait for registration, then query asynchronously

depend guarantees load order, not a connected database. Reacquire the service on ServiceRegisterEvent and discard results from unloaded or replaced services. The runnable examples/api-java project in the public repository handles delayed registration, failures and bounded recent-event deduplication without adding player commands. Queries return CompletableFuture. Never get() or join() on the main, Folia region or entity thread. Callbacks do not promise a player scheduling context; GUI updates, player messages and inventory access need separate appropriate scheduling. Report failures as unavailable rather than inventing zero balances or empty markets.

Queries and results

Pagination requires offset >= 0 and 1 <= limit <= 100, with at most 256 search characters. History pagination follows stored audit rows; unknown internal kinds become OTHER instead of exposing raw records.

Amounts and prices

Amounts use long integer minor units. At CurrencyView.getPrecision() == 2, 128 means 1.28; format with currency.display(amount).toPlainString(). Timestamps are Unix milliseconds and tax rates are basis points. For single-item fixed-price SELL and procurement BUY, getUnitPrice() is the price per item; for AUCTION, it is the starting amount for the entire lot. V1.1 additionally requires checking getLotMode(): BUNDLE uses a whole-bundle amount, quantity one and indivisible purchase. Single-item sales allow partial purchases. Multiply the unit price by the quantity purchased with overflow checking, for example using Math.multiplyExact.

Minimum purchase quantity

OrderView.getMinimumPurchaseQuantity() is fixed when published and defaults to 1. SELL orders accept a minimum from 1 to the published quantity; other types use 1. A purchase must be positive, no greater than the remainder, and at least min(getMinimumPurchaseQuantity(), getRemaining()). A remainder below the minimum must be bought in full. The original constructor remains available with a default of 1; the new overload appends long minimumPurchaseQuantity. Snapshots do not replace final quantity, funds and revision checks by the core. History and notifications report the actual amount of each transaction.

Immutable DTOs

Standalone DTOs live under com.kitemc.market.api.model: CurrencyView, OrderView, WalletView, ClaimAssetView, HistoryEntry, TradeSummary, ItemSummary and enums. Fields and nested lists, sets and maps are immutable. Optional samples are display summaries and cannot recreate or claim assets. Results exclude raw audit JSON, serialized item bytes, exact-sample fingerprints, license credentials, execution tokens and recovery evidence. Missing historical amounts remain null rather than becoming zero. RECORDED does not prove an external side effect succeeded; PENDING_REVIEW needs investigation. Item matching and transaction submission are handled by the host plugin, outside the public query API.

V1.1 lot, fee and business-condition summaries

Both older OrderView constructors remain available with SINGLE defaults. Do not recalculate old fees using current configuration or treat original lot quantities as available stock.

Post-commit notifications

MarketCommittedEvent is asynchronous and non-cancellable, reporting committed BUY, SUPPLY and AUCTION_WON only. getTrade() exposes order/operation IDs, type, item and income recipients, quantity, currency, gross, tax and net income. There is no raw getPayload().

Deduplication and re-querying

Node polling can delay or miss a notification, historical entries before startup are not replayed, and multiple nodes may see the same event. Deduplicate by network UUID plus event ID; IDs need not be consecutive. Persist your own long-term deduplication when required. Notifications are not evidence for issuing replacement money or items; re-query authoritative state after downtime.

V1.1 extensions and player-confirmed requests

Obtain two separate services through ServicesManager; the original KiteMarketApi remains read-only: Requests only support CREATE/BUY/SUPPLY/BID/CANCEL, bound to the player session, owner plugin, order and policy revisions, and expiry. There is no public confirm() or commit(), arbitrary minting, inventory mutation, administrator repair or unattended remote trading. Bundles describe real inventory slots and quantities; the host captures and rechecks actual items at confirmation.

Extension providers and their owner

Register extensions with an actually enabled Plugin owner. Owner disable unregisters them automatically. Closing an old registration handle cannot remove a newer registration with the same ID; call changed(owner) after rule changes to invalidate quotes based on the old revision. Rules and reviews run outside database/market locks at QUOTE or PLAYER_CONFIRM. They can allow continuation or reject, but cannot rewrite prices, fees, recipients or selected inventory, or loosen core rules. Exceptions reject the current transaction and disable the failing provider. Identity callbacks asynchronously read cloned native items. A batch identifies at most 128 distinct property fingerprints, including nested contents. Reduce the selection beyond that boundary; do not guess vendor IDs from names or lore. Container extension results are labeled auxiliary summaries and cannot change actual escrow, admission or claim contents.

Open host confirmation from a player action

Start from an explicit player action. The host opens its confirmation page in the proper player scheduling context. Quotes bind the owner, player session, order/policy revisions and short expiry. Disconnects, node changes, owner disable, expiry, changed rules and reuse require a new quote rather than edited old fields. Sales, bids and supply reference only real inventory slots 0..35 and quantities, never serialized items, fabricated asset IDs or item-removal callbacks. Bundles use MarketRequest.createBundle(...) with RequestLot parts. Slots cannot repeat across parts; each part has identical properties, different parts may mix, and the lot quantity is one. Batch listings obtain protected confirmation individually and handle each result.

Fees and completion states

RequestQuote.getListingFee(), getBuyerFee() and getChargedAmount() use the host’s actual fee snapshot and currency minor units. Gross is the transaction total, tax is total seller fees, and net is seller income. Buyer budgets include buyer fees. A bid’s charged amount may be only additional reserved funds: do not debit gross again. Only WriteResult.Status.SUCCEEDED denotes core success. REJECTED, CANCELLED, EXPIRED and PENDING_REVIEW mean rejection, cancellation, expiry and review respectively. A generated quote or completed future does not prove player confirmation. Once submission begins, discard(...) cannot reverse the transaction; never replay unknown results automatically. Once an economy extension has entered an external call, a slow response is neither cancelled nor discarded as failure. The host retains UNKNOWN and late evidence. Providers are idempotent by operationId; extension registration supplies no arbitrary minting ability.

Complete v1.1 SDK and runnable examples

Extension SPIs, restricted requests, fee quotes, lifecycle and actual example source.

Extending the player interface?

Use the separate UI SDK to receive current page snapshots and return registered host actions. KiteMarket still owns permissions, quotes, final inventory checks and confirmation. Neither SDK permits arbitrary currency creation, item removal, confirmation bypass or remote transaction writes. Configuration themes and Java IA renderers require no official DLC. Third parties may use, freely distribute or independently sell their own themes. Real IA example adapter code targets Java 21, independently of the two Java 11 SDKs.