lolzteam-api-java

Full-featured Java client for LOLZTEAM API (Forum + Market). All methods are auto-generated from OpenAPI schemas.

Key Features

Feature	Details
🔗 266 endpoints	Forum (151) + Market (115) — full API coverage
📤 Multipart upload	Typed API for avatars, covers, and file uploads
🌐 Proxy	HTTP / HTTPS / SOCKS5 with URL validation, separate for forum and market
♻️ Auto-retry	429 / 502 / 503 / 504 + network errors, exponential backoff with jitter
🔔 on_retry callback	Real-time monitoring of every retry attempt
🪣 Token-bucket Rate Limiter	Proactive request throttling (Forum: 300/min, Market: 120/min)
🔍 Search Rate Limit	Separate limit for search endpoints (Market: 20/min)
⚡ Code generation	From OpenAPI 3.1 JSON (`codegen/`)
🧪 99 tests	Unit + mock server + live API
🔒 Token safety	Automatic token redaction in `toString()` of all clients
🚀 CI/CD	GitHub Actions: test, build, verify

Quick Start

Maven

<dependency>
    <groupId>com.lolzteam</groupId>
    <artifactId>lolzteam-api</artifactId>
    <version>0.1.0</version>
</dependency>

Gradle

implementation 'com.lolzteam:lolzteam-api:0.1.0'

Minimal Example

import com.lolzteam.LolzteamClient;
import com.fasterxml.jackson.databind.JsonNode;

public class Example {
    public static void main(String[] args) throws Exception {
        LolzteamClient client = LolzteamClient.create("YOUR_TOKEN");

        // Forum API
        JsonNode user = client.forum().usersGet(1L, null);
        System.out.println(user);

        // Market API
        JsonNode items = client.market().categoryAll(null);
        System.out.println(items);
    }
}

Configuration

Full Builder

import com.lolzteam.LolzteamClient;
import java.time.Duration;

LolzteamClient client = LolzteamClient.builder("YOUR_TOKEN")
    // Proxy
    .forumProxy("socks5://127.0.0.1:1080")
    .marketProxy("http://user:pass@proxy.example.com:8080")
    // Retry
    .maxRetries(5)
    .baseDelayMs(1000)
    .maxDelayMs(60_000)
    // Timeout
    .timeout(Duration.ofSeconds(30))
    // Rate limiting
    .forumRateLimit(300)        // 300 req/min
    .marketRateLimit(120)       // 120 req/min
    .marketSearchRateLimit(20)  // 20 searches/min
    // Retry callback
    .onRetry(info -> {
        System.err.printf("⚠️  Retry #%d %s %s (status: %s, delay: %dms)%n",
            info.getAttempt(), info.getMethod(), info.getPath(),
            info.getStatus(), info.getDelayMs());
    })
    .build();

Builder Options

Method	Description	Default
`.proxy(url)`	Shared proxy for both APIs	—
`.forumProxy(url)`	Forum API proxy	—
`.marketProxy(url)`	Market API proxy	—
`.maxRetries(n)`	Maximum retry attempts	`5`
`.baseDelayMs(ms)`	Initial backoff delay	`1000`
`.maxDelayMs(ms)`	Maximum backoff delay	`60000`
`.timeout(dur)`	Request timeout	`30s`
`.forumRateLimit(rpm)`	Forum rate limit (req/min)	`300`
`.marketRateLimit(rpm)`	Market rate limit (req/min)	`120`
`.marketSearchRateLimit(rpm)`	Market search rate limit (req/min)	`20`
`.noRateLimit()`	Disable all rate limiters	—
`.onRetry(cb)`	Callback on each retry	—
`.forumBaseUrl(url)`	Override Forum URL	`https://prod-api.lolz.live`
`.marketBaseUrl(url)`	Override Market URL	`https://prod-api.lzt.market`

Error Handling

import com.lolzteam.LolzteamException;

try {
    JsonNode result = client.forum().usersGet(999999L, null);
} catch (LolzteamException.AuthException e) {
    System.out.println("401 Unauthorized: " + e.getMessage());
} catch (LolzteamException.ForbiddenException e) {
    System.out.println("403 Forbidden: " + e.getMessage());
} catch (LolzteamException.NotFoundException e) {
    System.out.println("404 Not Found: " + e.getMessage());
} catch (LolzteamException.RateLimitedException e) {
    System.out.println("429 Rate Limited (" + e.getAttempts() + " attempts)");
} catch (LolzteamException.RetryExhaustedException e) {
    System.out.println("All " + e.getAttempts() + " attempts exhausted. Last error: " + e.getLastError().getMessage());
} catch (LolzteamException.ConfigException e) {
    System.out.println("Configuration error: " + e.getMessage());
} catch (LolzteamException e) {
    System.out.println("Error: " + e.getMessage());
}

// Helper methods
LolzteamException err = new LolzteamException.ApiException(429, "rate limited");
err.isRetryable();    // true for 429/502/503/504
err.isRateLimit();    // true for 429
err.getStatusCode();  // 429

Error Types

Class	Status	`isRetryable()`	Description
`HttpException`	—	✅ (timeout/connect)	HTTP transport error
`JsonException`	—	❌	JSON parsing error
`ApiException`	`status`	✅ (429/502/503/504)	Generic API error
`AuthException`	401	❌	Invalid token
`ForbiddenException`	403	❌	Access denied
`NotFoundException`	404	❌	Resource not found
`RateLimitedException`	429	✅	Rate limit exceeded
`RetryExhaustedException`	*	—	All retries failed (wraps `lastError`)
`ConfigException`	—	❌	Configuration error

Rate Limiting

Token-bucket algorithm with continuous refill:

// Client automatically throttles requests
LolzteamClient client = LolzteamClient.create("YOUR_TOKEN");
// Forum: 300 req/min (5/sec with burst up to 300)
// Market: 120 req/min (2/sec with burst up to 120)
// Market search: 20 req/min (separate limiter)

// Disable rate limiting:
LolzteamClient client = LolzteamClient.builder("YOUR_TOKEN")
    .noRateLimit()
    .build();

Search endpoints automatically pass through two limiters: the standard limiter + the search limiter.

Retry

Exponential backoff with jitter:

429 — respects Retry-After header (seconds and HTTP-date)
502 / 503 / 504 — transient server errors
timeout / connect — transport network errors

Delay formula: min(base_delay × 2^attempt + random_jitter, max_delay)

Proxy

import com.lolzteam.LolzteamClient;

// Shared proxy for both APIs
LolzteamClient client = LolzteamClient.builder("YOUR_TOKEN")
    .proxy("socks5://127.0.0.1:1080")
    .build();

// Separate proxies
LolzteamClient client = LolzteamClient.builder("YOUR_TOKEN")
    .forumProxy("socks5://127.0.0.1:1080")
    .marketProxy("http://user:pass@proxy.example.com:8080")
    .build();

Supported schemes: http://, https://, socks5://. URLs are validated at client creation time.

Multipart Upload

// Upload avatar
client.forum().usersAvatarUpload("me", "/path/to/avatar.png", 0L, 0L, 256L);

Project Structure

lolzteam-api-java/
├── lolzteam-api/
│   └── src/
│       ├── main/java/com/lolzteam/
│       │   ├── LolzteamClient.java   # Public API: LolzteamClient, Builder
│       │   ├── ApiClient.java        # HTTP client, rate limiter, retry, proxy
│       │   ├── LolzteamException.java # Typed errors with helper methods
│       │   ├── RateLimiter.java      # Token-bucket rate limiter
│       │   ├── RetryConfig.java      # Retry configuration
│       │   ├── RetryInfo.java        # Retry info (for callback)
│       │   ├── forum/
│       │   │   └── ForumApi.java     # Forum API: 151 endpoints (generated)
│       │   └── market/
│       │       └── MarketApi.java    # Market API: 115 endpoints (generated)
│       └── test/java/com/lolzteam/
│           ├── ApiClientTest.java    # 99 tests: builder, proxy, error types, mock server, token safety, reflection
│           └── LiveApiTest.java      # Live API tests
├── codegen/                          # OpenAPI → Java code generator
│   └── src/main/java/com/lolzteam/codegen/
│       └── CodeGenerator.java
├── schemas/                          # OpenAPI 3.1 JSON schemas
│   ├── forum.json
│   └── market.json
├── examples/                         # Usage examples
│   ├── general/                      # Basic usage, proxy, error handling
│   ├── forum/                        # Forum API examples
│   └── market/                       # Market API examples
├── docs/                             # Documentation
│   ├── DOCS_RU.md                    # Full documentation (RU)
│   ├── DOCS_EN.md                    # Full documentation (EN)
│   └── README_EN.md                  # English README
└── .github/workflows/                # CI/CD
    └── ci.yml                        # test + build + verify

📖 Documentation

Document	Description
Full Documentation (RU)	All Forum API + Market API methods, parameters, request bodies
Full Documentation (EN)	Complete API reference in English
README (RU)	Russian version of this README

📚 Examples

All examples are in the examples/ directory. Pass your token as a command-line argument:

# Compile and run (add lolzteam-api JAR to classpath)
javac -cp lolzteam-api.jar examples/general/Basic.java
java -cp .:lolzteam-api.jar examples.general.Basic YOUR_TOKEN

General

Example	Description
Basic	Minimal example — forum + market
ErrorHandling	Handling all error types
Proxy	Shared proxy via Builder
SeparateProxies	Separate proxies for forum and market

Forum API

Example	Description
Activity	Profile, posts, threads, followers
Chatbox	Chat messages, online users, leaderboard
Conversations	Private messages
ForumCategories	Categories, forums, navigation
ForumMisc	Notifications, tags, likes
ForumSearch	Search threads, posts, users
ForumThreads	Threads, followers, navigation
ForumUsers	Users, trophies, profile fields
Notifications	Notification list
Posts	Posts in threads
ProfilePosts	Profile posts and comments

Market API

Example	Description
Arbitrage	Disputes and sales
BatchOperations	Mass bump, statistics
Managing	Item management: price, guarantee, bump
MarketCategories	Categories, platforms, parameters
MarketItem	Account information
MarketProfile	Profile, balance, favorites, cart
MarketSearch	Search with price filters
Monitor	Real-time monitoring of new listings
Orders	Orders and categories
Payments	Balance and payment history
Purchasing	Purchase check, discount request

Code Generation

Code is already generated. Regenerate from fresh schemas:

# Download latest schemas
curl -sL https://raw.githubusercontent.com/AS7RIDENIED/LOLZTEAM/main/Official%20Documentation/forum.json -o schemas/forum.json
curl -sL https://raw.githubusercontent.com/AS7RIDENIED/LOLZTEAM/main/Official%20Documentation/market.json -o schemas/market.json

# Build code generator and run generation
mvn -pl codegen clean package -DskipTests
java -jar codegen/target/lolzteam-codegen-*-jar-with-dependencies.jar \
    schemas/forum.json schemas/market.json \
    lolzteam-api/src/main/java/com/lolzteam

CI/CD

ci.yml — on every push/PR: mvn clean verify (compile, test, javadoc)

License

MIT — see LICENSE.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

lolzteam-api-java

Key Features

Quick Start

Maven

Gradle

Minimal Example

Configuration

Full Builder

Builder Options

Error Handling

Error Types

Rate Limiting

Retry

Proxy

Multipart Upload

Project Structure

📖 Documentation

📚 Examples

General

Forum API

Market API

Code Generation

CI/CD

License

FilesExpand file tree

README_EN.md

Latest commit

History

README_EN.md

File metadata and controls

lolzteam-api-java

Key Features

Quick Start

Maven

Gradle

Minimal Example

Configuration

Full Builder

Builder Options

Error Handling

Error Types

Rate Limiting

Retry

Proxy

Multipart Upload

Project Structure

📖 Documentation

📚 Examples

General

Forum API

Market API

Code Generation

CI/CD

License