> ## Documentation Index
> Fetch the complete documentation index at: https://www.kitemc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reference the market SDK

> GitHub Packages setup for Gradle and Maven, with Release-file downloads as a fallback.

<h2 id="reference-the-sdk">
  Reference the SDK
</h2>

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.

<h2 id="github-packages">
  GitHub Packages
</h2>

| SDK | Maven coordinates |
| - | - |
| Read-only market API | `com.kitemc:kitemarket-api:1.0.0` |
| UI SDK | `com.kitemc:kitemarket-ui-api:1.0.0` |

The registry is `https://maven.pkg.github.com/kitemc/KiteMarket`. The release workflow uploads both SDKs, sources, Javadoc and POM files after the corresponding stable release.

Check the [public repository](https://github.com/KiteMC/KiteMarket)'s Packages list for the version before using it. The configuration below does not mean the version has already been uploaded. Runtime plugins, examples and language/configuration bundles remain on GitHub Releases.

<h3 id="download-authentication">
  Download authentication
</h3>

GitHub's Maven/Gradle registry requires authentication even for public packages. Locally, use a **personal access token (classic)** with `read:packages` and your GitHub username. Read-only downloads do not need `write:packages`.

Store credentials in the user-level `~/.gradle/gradle.properties`, never in project files or Git:

```properties theme={null}
gpr.user=YOUR_GITHUB_USERNAME
gpr.key=YOUR_CLASSIC_PAT_WITH_READ_PACKAGES
```

<h3 id="gradle-kotlin-dsl">
  Gradle Kotlin DSL
</h3>

```kotlin theme={null}
repositories {
    maven("https://repo.papermc.io/repository/maven-public/")
    maven {
        name = "GitHubKiteMarket"
        url = uri("https://maven.pkg.github.com/kitemc/KiteMarket")
        credentials {
            username = providers.gradleProperty("gpr.user")
                .orElse(providers.environmentVariable("GITHUB_ACTOR")).orNull
            password = providers.gradleProperty("gpr.key")
                .orElse(providers.environmentVariable("GITHUB_TOKEN")).orNull
        }
        content {
            includeModule("com.kitemc", "kitemarket-api")
            includeModule("com.kitemc", "kitemarket-ui-api")
        }
    }
}
dependencies {
    compileOnly("com.kitemc:kitemarket-api:1.0.0")
    compileOnly("com.destroystokyo.paper:paper-api:1.16.5-R0.1-SNAPSHOT")
}
tasks.withType<JavaCompile>().configureEach {
    options.release.set(11)
}
```

Alternatively, provide the same download credentials through `GITHUB_ACTOR`/`GITHUB_TOKEN` environment variables. Retain the project's existing Paper/Bukkit compile dependency and registry.

<h3 id="maven">
  Maven
</h3>

In a Maven project's `pom.xml`, add the registry and dependency:

```xml theme={null}
<repositories>
  <repository>
    <id>github-kitemarket</id>
    <url>https://maven.pkg.github.com/kitemc/KiteMarket</url>
  </repository>
</repositories>
<dependencies>
  <dependency>
    <groupId>com.kitemc</groupId>
    <artifactId>kitemarket-api</artifactId>
    <version>1.0.0</version>
    <scope>provided</scope>
  </dependency>
</dependencies>
```

Add a matching server in the user-level `~/.m2/settings.xml`, reading credentials from environment variables. If the file exists, merge only the `server` entry:

```xml theme={null}
<settings>
  <servers>
    <server>
      <id>github-kitemarket</id>
      <username>${env.GITHUB_ACTOR}</username>
      <password>${env.GITHUB_TOKEN}</password>
    </server>
  </servers>
</settings>
```

<h3 id="check-authentication-and-the-version">
  Check authentication and the version
</h3>

For `401`/`403`, check the token type, scopes, expiry and username. For `404`, also check the coordinates and whether the version is published.

GitHub's [Gradle](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-gradle-registry) and [Maven](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry) documentation defines registry authentication.

<h2 id="release-download-fallback">
  Release-download fallback
</h2>

For offline development or when Packages authentication is unavailable, download the matching `KiteMarket-API-1.0.0.jar` directly from [GitHub Releases](https://github.com/KiteMC/KiteMarket/releases) and manage it as a compile-only dependency.

Release-file downloads do not require a Packages Token. The public repository provides interface sources, Javadoc and runnable examples. This fallback does not change the runtime requirements below.

<h2 id="runtime-requirements">
  Runtime requirements
</h2>

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.

<Columns cols={2}>
  <Card title="Market queries and notifications" href="/en/kitemarket/api#wait-for-registration-then-query-asynchronously">
    Service registration, asynchronous queries, immutable DTOs and post-commit notifications.
  </Card>

  <Card title="Java UI example" href="/en/kitemarket/ui-development/java#java-example-github-packages">
    Compile dependencies for the UI SDK, Paper and ItemsAdder.
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.