API Clients

This guide covers practical usage of the API clients. You’ll learn how to access public game data with AppClient and private player data with UserClient.

📌 Basic Concepts

Regions: STALCRAFT API data is organized by RU, EU, NA, SEA, NEA regions.

Most endpoints require specifying a region, since game data exists independently per region.

🔑 Authentication Types:

• Application Credentials or App Token - For public data (auction, emissions, profiles)

• User Token - For both public and private data (characters, friends, clan membership)

📄 Response Formats:

• Pydantic Models (default) - Typed Python objects with IDE autocompletion

• Raw JSON - Original API response

See also

Official Terminology explains regions, realms, accounts, and characters in detail.

Before You Begin

To follow the examples, you’ll need application credentials or tokens.

See Authentication Guide to register an application and obtain your credentials.

For testing:

Use Demo API (https://dapi.stalcraft.net) with tokens provided in official documentation.

🚀 Getting Started

Important

NEVER include credentials in source code.

Production code SHOULD use environment variables.

Initializing AppClient

Start by creating an AppClient. You can authenticate either with Application Credentials OR with App Token.

App Client Initialization

from scapi import AppClient, Region
import os

# Option 1: Using application credentials
client = AppClient(
  client_id=os.getenv("CLIENT_ID"),
  client_secret=os.getenv("CLIENT_SECRET")
)

# Option 2: Using created app token from OAuthClient
client = AppClient(token=os.getenv("APP_TOKEN"))

# And you can set defaults for this client instance
client = AppClient(
  token=os.getenv("APP_TOKEN"),
  region=Region.EU,  # Default region in requests
  json=True          # Return raw json instead of typed models
)

Making First Requests

Once client initialized, you can call endpoints directly.

API calls are asynchronous (async/await). You need to run them inside an event loop.

Note

For simplicity, examples in guides show only the relevant await calls. Assume they’re inside an async function, typically called from asyncio.run().

If you’re new to async Python, check the official asyncio documentation.

Basic Usage Example

from scapi import AppClient
import asyncio
import os

# Create api client instance with created token
client = AppClient(token=os.getenv("APP_TOKEN"))

async def main():
  # List available api regions
  regions = await client.regions()
  for region in regions:
    print(f"{region.id}: {region.name}")

  # Get emission status
  emission = await client.emission()
  print(f"Current emission: {emission.current_start}")
  print(f"Previous: {emission.previous_start} - {emission.previous_end}")

  # Get public character profile
  profile = await client.profile("ZIV")
  print(f"Character alliance: {profile.alliance}")
  print(f"Clan: {profile.clan.info.name if profile.clan else 'No clan'}")

asyncio.run(main())

Use Different Regions

Region selection follows a priority:

explicit call parameter → client instance default → global Config.REGION.

When you specify a region in a method call, it overrides all defaults.

If omitted, the client checks its own region parameter.

If that’s also unset, it falls back to Config.REGION (which defaults to "ru").

Note

Config contains global defaults applied to all clients unless overridden.

Different Regions Usage

from scapi import AppClient, Region, Config
import os

# Client with default region (EU)
client = AppClient(token=os.getenv("APP_TOKEN"), region=Region.EU)

# Uses client default (EU)
emission = await client.emission()

# Explicit parameter overrides default (SEA)
emission = await client.emission(region=Region.SEA)

# Change config default from (RU) to (NA)
Config.REGION = Region.NA

# Create client with no default region
client = AppClient(token=os.getenv("APP_TOKEN"))

# No client region default → uses Config.REGION (NA)
emission = await client.emission()

Auction Methods

The auction() factory method returns a dedicated endpoint for a specific item.

Chain async methods like lots() or price_history() directly.

Use sort and order parameters to control listing order.

The limit parameter caps results per request (max 200).

Where to Find Item IDs

API uses internal identifiers (like "zyv9") instead of item names.

For production use, the library provides DatabaseLookup, a built-in system that syncs item names to IDs automatically. See Database Lookup for setup and usage.

Usage Example

item = await lookup.find_one("AK-105")
lots = await client.auction(item.id).lots()

For testing or custom solutions reference to official stalcraft-database repository.

Auction Methods Usage

# Target Item ID
ITEM_ID = "zyv9"

# Get active lots
lots = await client.auction(ITEM_ID).lots(limit=3)
print(f"Active latest lots: {lots}")

# With sorting cheapest first
cheapest = await client.auction(ITEM_ID).lots(
  limit=3,
  sort=SortAuction.BUYOUT_PRICE,
  order=Order.ASCENDING,
)
print(f"Cheapest lots: {cheapest}")

# Price history
history = await client.auction(ITEM_ID).price_history(limit=3)
print(f"Historical prices: {history}")

Clan Methods

The clan() factory method returns a dedicated endpoint for a specific clan.

Clan Methods Usage

CLAN_ID = "a552092f-e7c9-4cc3-a256-1e3f525770bf"

# Get public clan information
clan = await client.clan(CLAN_ID).info()
print(f"Clan {clan.name}: Level {clan.level}")
print(f"Members: {clan.member_count}")
print(f"Created: {clan.registration_time}")

Operations Sessions

The operations_sessions() method returns listing including participants, weapons, stats, and other information.

Operations Sessions Usage

# Get recent operation sessions
sessions = await client.operations_sessions(limit=3)
for session in sessions:
  print(f"Map: {session.map}, Duration: {session.duration_seconds // 60} minutes")

# Filter by map and date (ISO format or datetime object)
sessions = await client.operations_sessions(
  map=OperationsMap.SHOCK_THERAPY,
  after="2025-12-01T00:00:00Z",
  limit=3
)
users = [user.username for session in sessions for user in session.participants]
print(f"Shock Therapy users since Dec 2025: {users}")

🔐 UserClient for Private Data

UserClient requires an OAuth user token and provides access to player-specific endpoints while maintaining all AppClient functionality.

Important

User-specific endpoints only return data for the account that owns the token.

You cannot access other players private information.

User Client Usage

from scapi import UserClient

# Initialize with OAuth user token
client = UserClient(token=os.getenv("USER_TOKEN"))

# Public data works identically to AppClient
emission = await client.emission()
lots = await client.auction("zyv9").lots(limit=3)

# User-specific endpoints
characters = await client.characters()
print(f"Characters for this account: {[char.info.name for char in characters]}")

# Friends list for a specific character
friends = await client.friends("YourCharacterName")
print(f"Friends: {friends}")

Clan Methods

Important

This endpoint will fail with a 401 error if the token owner is not a member of the specified clan.

User Clan Methods

try:
  members = await client.clan("a552092f-e7c9-4cc3-a256-1e3f525770bf").members()
  print(f"Clan members: {len(members)}")
  for member in members:
    print(f"  {member.name} - {member.rank}")

except Exception as err:
  print(f"Cannot access members: {err}")

🚫 Basic Error Handling

API errors raise specific exceptions.

Rate limit information is available through the client.

Error Handling

from scapi import AppClient, exceptions
import os

client = AppClient(token=os.getenv("APP_TOKEN"))

try:
  clans = await client.clans()
  print(f"Found {len(clans)} clans.")

except exceptions.RateLimitError:
  print("Too many requests, slow down.")
  print(client.ratelimit)

except exceptions.UnauthorizedError:
  print("Invalid or expired token.")

🚨 Common Issues

Problem	Solution
Rate limit exceeded	Each user token has independent rate limits. Check retry_after or implement exponential backoff.
Data appears outdated	Most endpoints require a region parameter. Data is isolated per region. E.g. auction lots in EU differ from NA.
Clan members endpoint returns 401	The authenticated user must be a member of that clan.

⏩ What’s Next

Continue with:

• Authentication Guide – Register application and get tokens

• Database Lookup – Find items IDs by name