Skip to content

Kotlin Installation Guide

This guide walks you through installing and setting up the OpenLibX402 Kotlin SDK with coroutines support.

Prerequisites

Kotlin and JDK

OpenLibX402 Kotlin SDK requires: - Kotlin 1.9.0 or higher - JDK 11 or higher

macOS

1
2
3
4
5
6
7
8
# Using Homebrew
brew install openjdk@11
brew install kotlin

# Or use SDKMAN!
curl -s "https://get.sdkman.io" | bash
sdk install java 11.0.20-tem
sdk install kotlin

Ubuntu/Debian

1
2
3
4
5
6
sudo apt-get update
sudo apt-get install openjdk-11-jdk

# Install Kotlin
curl -s "https://get.sdkman.io" | bash
sdk install kotlin

Windows

Download and install: - JDK from Oracle or Adoptium - Kotlin from kotlinlang.org

Verify Installation

1
2
3
4
5
java -version
# Should show: openjdk version "11.0.x" or higher

kotlin -version
# Should show: Kotlin version 1.9.x or higher

Build Tool

Choose either Gradle or Maven. Gradle is recommended for Kotlin projects.

macOS: 

1
brew install gradle

Ubuntu/Debian: 

1
sdk install gradle 8.4

Windows: Download from Gradle's website and add to PATH.

Verify: 

1
2
gradle -version
# Should show: Gradle 7.x or higher

Maven

macOS: 

1
brew install maven

Ubuntu/Debian: 

1
sudo apt-get install maven

Verify: 

1
2
mvn -version
# Should show: Apache Maven 3.6.x or higher

Installation Methods

Add to your build.gradle.kts:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
plugins {
    kotlin("jvm") version "1.9.20"
    kotlin("plugin.serialization") version "1.9.20"
}

repositories {
    mavenCentral()
}

dependencies {
    // OpenLibX402 packages
    implementation("org.openlibx402:openlibx402-core:0.1.0")
    implementation("org.openlibx402:openlibx402-client:0.1.0")

    // Kotlin coroutines
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")

    // Kotlinx serialization
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0")

    // Kotlinx datetime
    implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.4.1")

    // Optional: Logging
    implementation("io.github.microutils:kotlin-logging-jvm:3.0.5")
    implementation("ch.qos.logback:logback-classic:1.4.11")
}

kotlin {
    jvmToolchain(11)
}

Install dependencies:

1
gradle build

Option 2: Gradle Groovy DSL

Add to your build.gradle:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
plugins {
    id 'org.jetbrains.kotlin.jvm' version '1.9.20'
    id 'org.jetbrains.kotlin.plugin.serialization' version '1.9.20'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.openlibx402:openlibx402-core:0.1.0'
    implementation 'org.openlibx402:openlibx402-client:0.1.0'

    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3'
    implementation 'org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0'
    implementation 'org.jetbrains.kotlinx:kotlinx-datetime:0.4.1'
}

Option 3: Maven

Add to your pom.xml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
<project>
    <properties>
        <kotlin.version>1.9.20</kotlin.version>
        <kotlinx.coroutines.version>1.7.3</kotlinx.coroutines.version>
        <kotlinx.serialization.version>1.6.0</kotlinx.serialization.version>
    </properties>

    <dependencies>
        <!-- OpenLibX402 -->
        <dependency>
            <groupId>org.openlibx402</groupId>
            <artifactId>openlibx402-core</artifactId>
            <version>0.1.0</version>
        </dependency>
        <dependency>
            <groupId>org.openlibx402</groupId>
            <artifactId>openlibx402-client</artifactId>
            <version>0.1.0</version>
        </dependency>

        <!-- Kotlin stdlib -->
        <dependency>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-stdlib</artifactId>
            <version>${kotlin.version}</version>
        </dependency>

        <!-- Coroutines -->
        <dependency>
            <groupId>org.jetbrains.kotlinx</groupId>
            <artifactId>kotlinx-coroutines-core</artifactId>
            <version>${kotlinx.coroutines.version}</version>
        </dependency>

        <!-- Serialization -->
        <dependency>
            <groupId>org.jetbrains.kotlinx</groupId>
            <artifactId>kotlinx-serialization-json</artifactId>
            <version>${kotlinx.serialization.version}</version>
        </dependency>

        <!-- DateTime -->
        <dependency>
            <groupId>org.jetbrains.kotlinx</groupId>
            <artifactId>kotlinx-datetime</artifactId>
            <version>0.4.1</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.jetbrains.kotlin</groupId>
                <artifactId>kotlin-maven-plugin</artifactId>
                <version>${kotlin.version}</version>
                <executions>
                    <execution>
                        <id>compile</id>
                        <phase>compile</phase>
                        <goals>
                            <goal>compile</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <compilerPlugins>
                        <plugin>kotlinx-serialization</plugin>
                    </compilerPlugins>
                </configuration>
                <dependencies>
                    <dependency>
                        <groupId>org.jetbrains.kotlin</groupId>
                        <artifactId>kotlin-maven-serialization</artifactId>
                        <version>${kotlin.version}</version>
                    </dependency>
                </dependencies>
            </plugin>
        </plugins>
    </build>
</project>

Install dependencies:

1
mvn clean install

Option 4: Local Installation (Development)

For local development or testing unreleased versions:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Clone repository
git clone https://github.com/openlibx402/openlibx402.git
cd openlibx402

# Install core package
cd packages/kotlin/openlibx402-core
gradle publishToMavenLocal

# Install client package
cd ../openlibx402-client
gradle publishToMavenLocal

Then use in your project with the same Gradle/Maven configuration as above.

Quick Start

Create a New Kotlin Project with Gradle

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
mkdir my-x402-app
cd my-x402-app

# Initialize Gradle project
gradle init --type kotlin-application --dsl kotlin

# Or with specific settings
gradle init \
    --type kotlin-application \
    --dsl kotlin \
    --test-framework kotlintest \
    --package com.example \
    --project-name my-x402-app

Edit build.gradle.kts to add OpenLibX402 dependencies:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
plugins {
    kotlin("jvm") version "1.9.20"
    kotlin("plugin.serialization") version "1.9.20"
    application
}

group = "com.example"
version = "1.0.0"

repositories {
    mavenCentral()
}

dependencies {
    // OpenLibX402
    implementation("org.openlibx402:openlibx402-core:0.1.0")
    implementation("org.openlibx402:openlibx402-client:0.1.0")

    // Kotlin coroutines
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")

    // Kotlinx serialization
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0")

    // Kotlinx datetime
    implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.4.1")

    // Testing
    testImplementation(kotlin("test"))
}

kotlin {
    jvmToolchain(11)
}

application {
    mainClass.set("com.example.AppKt")
}

tasks.test {
    useJUnitPlatform()
}

Create Your First Application

Create src/main/kotlin/com/example/App.kt:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
package com.example

import kotlinx.coroutines.runBlocking
import org.openlibx402.client.X402AutoClient
import org.openlibx402.core.errors.X402Error
import org.p2p.solanaj.core.Account

suspend fun main() {
    // Create Solana account
    val account = Account()
    println("Public Key: ${account.publicKey}")

    // Create client with DSL
    val client = X402AutoClient(account) {
        rpcUrl = "https://api.devnet.solana.com"
        maxPaymentAmount = "1.0"
        allowLocal = true  // Development only
    }

    client.use {
        try {
            // Make payment-enabled request
            val response = it.get("https://api.example.com/data")
            println("Success: ${response.body?.string()}")
        } catch (e: X402Error) {
            when (e) {
                is X402Error.InsufficientFunds -> {
                    println("Insufficient funds!")
                    println("Required: ${e.requiredAmount}")
                    println("Available: ${e.availableAmount}")
                }
                else -> {
                    println("Error: ${e.message}")
                }
            }
        }
    }
}

// For gradle run compatibility
fun main() = runBlocking {
    main()
}

Build and Run

1
2
3
4
5
6
7
8
# Build
gradle build

# Run
gradle run

# Or with arguments
gradle run --args="argument1 argument2"

Run as JAR

1
2
3
4
5
# Build JAR
gradle jar

# Run JAR
java -jar build/libs/my-x402-app-1.0.0.jar

Verify Installation

Create a test file to verify everything is working:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
import org.openlibx402.core.models.PaymentRequest
import org.openlibx402.client.X402Client
import kotlinx.datetime.Clock
import kotlin.time.Duration.Companion.minutes

fun main() {
    println("OpenLibX402 Kotlin SDK installed successfully!")
    println("Core version: 0.1.0")
    println("Client version: 0.1.0")

    // Test imports
    println("PaymentRequest: ${PaymentRequest::class.simpleName}")
    println("X402Client: ${X402Client::class.simpleName}")

    // Test kotlinx libraries
    println("Current time: ${Clock.System.now()}")
    println("Duration: ${5.minutes}")

    println("\nAll imports working!")
}

Run: 

1
gradle run

Expected output: 

1
2
3
4
5
6
7
8
OpenLibX402 Kotlin SDK installed successfully!
Core version: 0.1.0
Client version: 0.1.0
PaymentRequest: PaymentRequest
X402Client: X402Client
Current time: 2025-11-05T10:30:00Z
Duration: 5m
All imports working!

Package Structure

OpenLibX402 Kotlin SDK is split into two packages:

Core Package (openlibx402-core)

Provides core functionality: - Payment models (PaymentRequest, PaymentAuthorization) as data classes - Sealed class error hierarchy (X402Error) - Blockchain integration (SolanaPaymentProcessor) - kotlinx.serialization support - kotlinx.datetime integration

When to use: - Building custom payment logic - Integrating with existing HTTP clients - Creating middleware or frameworks

Client Package (openlibx402-client)

Provides HTTP client implementations with coroutines: - X402Client - Manual payment control with suspend functions - X402AutoClient - Automatic payment handling with DSL builder

When to use: - Making HTTP requests with payments - Quick integration with automatic payments - Coroutine-based applications

Typical Setup

Most applications need both packages plus Kotlin dependencies:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
dependencies {
    // Both core and client
    implementation("org.openlibx402:openlibx402-core:0.1.0")
    implementation("org.openlibx402:openlibx402-client:0.1.0")

    // Kotlin coroutines (required)
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")

    // Kotlinx serialization (required)
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0")

    // Kotlinx datetime (required)
    implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.4.1")
}

IDE Setup

  1. Open Project:
  2. File → Open → Select your build.gradle.kts or project directory

  3. IntelliJ will automatically detect Gradle and import dependencies

  4. Refresh Dependencies:

  5. Click the "Load Gradle Changes" icon in the toolbar

  6. Or: View → Tool Windows → Gradle → Click refresh icon

  7. Enable Kotlin Plugin:

  8. IntelliJ comes with Kotlin plugin pre-installed

  9. File → Settings → Plugins → Verify "Kotlin" is enabled

  10. Verify:

  11. Check that dependencies appear in External Libraries
  12. Try auto-complete for import org.openlibx402.*
  13. Coroutine support should be available

Android Studio

  1. Same as IntelliJ IDEA - Android Studio is built on IntelliJ

  2. Additional Setup for Android: 

    1
2
3
4
5
    android {
    kotlinOptions {
        jvmTarget = "11"
    }
}

VS Code

  1. Install Extensions:
  2. Kotlin Language
  3. Gradle for Java

  4. Extension Pack for Java

  5. Open Project:

  6. File → Open Folder → Select project directory

  7. VS Code will detect build.gradle.kts automatically

  8. Refresh:

  9. Command Palette (Cmd/Ctrl+Shift+P) → "Gradle: Refresh Dependencies"

Eclipse

  1. Install Kotlin Plugin:
  2. Help → Eclipse Marketplace → Search "Kotlin"

  3. Install "Kotlin Plugin for Eclipse"

  4. Import Gradle Project:

  5. File → Import → Gradle → Existing Gradle Project

  6. Select project directory

  7. Update Dependencies:

  8. Right-click project → Gradle → Refresh Gradle Project

Troubleshooting

"Unresolved reference: openlibx402"

Solution: Refresh dependencies: 

1
2
3
gradle build --refresh-dependencies
# or
mvn clean install -U

"Kotlin compiler version mismatch"

Cause: Mismatched Kotlin versions.

Solution: Ensure all Kotlin dependencies use the same version: 

1
2
3
4
5
6
val kotlinVersion = "1.9.20"

plugins {
    kotlin("jvm") version kotlinVersion
    kotlin("plugin.serialization") version kotlinVersion
}

"Unsupported class file major version"

Cause: Using Java 8 or older.

Solution: Upgrade to Java 11 or higher: 

1
2
java -version  # Check current version
sdk install java 11.0.20-tem  # Install Java 11

Coroutines Not Working

Cause: Missing coroutines dependency.

Solution: Add kotlinx-coroutines: 

1
2
3
dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
}

Serialization Plugin Error

Cause: Missing serialization plugin.

Solution: Add plugin to build.gradle.kts: 

1
2
3
plugins {
    kotlin("plugin.serialization") version "1.9.20"
}

Gradle Daemon Issues

Symptoms: Slow builds or stuck processes.

Solution: Restart Gradle daemon: 

1
2
gradle --stop
gradle build

Environment Setup

Solana Account

For development, you can use a test account:

1
2
# Set environment variable
export SOLANA_SECRET_KEY="your-base64-encoded-key"

In Kotlin: 

1
2
3
val keyString = System.getenv("SOLANA_SECRET_KEY")
val secretKey = java.util.Base64.getDecoder().decode(keyString)
val account = Account(secretKey)

Network Configuration

Devnet (Testing): 

1
2
3
4
val client = X402Client(
    walletAccount = account,
    rpcUrl = "https://api.devnet.solana.com"
)

Mainnet (Production): 

1
2
3
4
val client = X402Client(
    walletAccount = account,
    rpcUrl = "https://api.mainnet-beta.solana.com"
)

Coroutine Dispatcher Configuration

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.asCoroutineDispatcher
import java.util.concurrent.Executors

// Custom dispatcher for payment operations
val paymentDispatcher = Executors.newFixedThreadPool(4)
    .asCoroutineDispatcher()

// Use in client operations
withContext(paymentDispatcher) {
    client.get(url)
}

Next Steps

Now that you have OpenLibX402 Kotlin SDK installed:

  1. Client Quickstart - Build your first payment-enabled client with coroutines
  2. Basic Usage Examples - Learn common patterns with suspend functions
  3. API Reference - Explore the full API
  4. Error Handling - Master sealed class error handling

Version Updates

Check for updates: 

1
2
3
4
5
# Gradle
gradle dependencyUpdates

# Or check Maven Central
https://search.maven.org/artifact/org.openlibx402/openlibx402-core

Update to latest version in your build.gradle.kts: 

1
2
3
4
dependencies {
    implementation("org.openlibx402:openlibx402-core:LATEST_VERSION")
    implementation("org.openlibx402:openlibx402-client:LATEST_VERSION")
}

Support