Skip to content

Getting started 🚀

Quick start

Package separated into main modules which can be imported from aiosteampy namespace:

  • session - Steam Session management and auth tokens negotiation.
  • guard - Steam Guard/Mobile Authenticator (2FA) functionality.
  • client - abstract container for Steam domains implementations (Market, Trade Offers, etc.).

Session

SteamSession provides functionality to log into user account using either credentials or QR. When the login process has been finalized web auth cookies can be obtained to enable interaction with SteamCommunity domains like Confirmations (see guard), Market, TradeOffers, Profile and Inventory (see client). Methods serialize and deserialize allows to dump/load SteamSession into/from JSON-safe dict.

Demonstrative example of using SteamSession to log into account with credentials, obtaining web cookies and finally dump session into file:

import asyncio
import json

from aiosteampy.session import SteamSession, GuardConfirmationRequired


async def login_with_credentials():
    session = SteamSession()

    account_name = input("Input login: ")
    password = input("Input password: ")

    try:
        await session.with_credentials(account_name, password)
    except GuardConfirmationRequired as e:
        if e.email_code:
            code = input("Code from Steam has been sent to your email. Paste it here: ")
            await session.submit_auth_code(code, "email")
        elif e.device_code:
            code = input("Input code from Mobile Device Authenticator: ")
            await session.submit_auth_code(code, "device")
        else:
            input(
                ("Steam requests device or email confirmation. "
                 "Click on the link from email or mobile application and press enter.")
            )

    await session.finalize()

    print("Access token: ", session.access_token)
    print("Refresh token: ", session.refresh_token)

    await session.obtain_cookies()

    print("Web cookies obtained!")

    await session.transport.close()

    session_dump = session.serialize()

    with open(f"./{account_name}.session.json", "w") as f:
        json.dump(session_dump, f, indent=2)


asyncio.run(login_with_credentials())

Session can then be loaded from a dump. Although not verified for expiration, tokens and cookies will be restored:

with open(f"./{account_name}.session.json", "r") as f:
    session = SteamSession.deserialize(json.load(f))

Guard

SteamGuard embodies Steam Mobile Authenticator functionality from mobile app. Can activate account 2FA (similar to using SDA), generate auth codes, sign auth requests made with other SteamSession by QR, handle Steam Confirmations. Eventually, guard requires session with mobile app platform.

Here we're using SteamGuard to activate Authenticator and dump SteamGuardAccount data into a file then:

import json
import asyncio

from aiosteampy.session import SteamSession, Platform
from aiosteampy.guard import SteamGuard, SmsConfirmationRequired, EmailConfirmationRequired


async def enable_two_fa():
    session = SteamSession(..., platform=Platform.MOBILE)

    guard = SteamGuard(session)

    try:
        guard.enable()
    except SmsConfirmationRequired as e:
        code = input(f"Guard activation code has been sent to your phone ({e.phone_hint}). Paste it here: ")
    except EmailConfirmationRequired:
        code = input("Guard activation code has been sent to your email. Paste it here: ")

    await guard.finalize(code)

    # Exported guard account contains secrets that cannot be retrieved once more
    # therefore, data must be saved ASAP to prevent loss of access to a user's Steam account
    guard_account = guard.export_account()
    with open(f"./{session.account_name or session.steam_id}.guard.json", "w") as f:
        json.dump(guard_account.serialize(), f)

    await guard.transport.close()


asyncio.run(enable_two_fa())

Client

SteamClient composes all Steam domains implementations: Market, Trade Offers, Inventory, Profile, Wallet and more. Each domain is responsible for related functionality. For example, Market domain contain methods allow to retrieve and buy listings from Steam Market, place buy and sell orders. Trade Offers provides methods to send, accept or deny offers and so on.

There is also a SteamPublicClient entity in aiosteampy.client namespace that allows interaction with Steam from unauthenticated (anonymous) user perspective.

Using SteamClient with authenticated SteamSession to get current user inventory items:

import asyncio

from aiosteampy.session import SteamSession
from aiosteampy.client import SteamClient, AppContext, App


async def get_inventory():
    session = SteamSession(...)

    client = SteamClient(session)

    # use predefined apps and their contexts
    cs2_default_inv = await client.inventory.get(AppContext.CS2)
    print("CS2 items: ", cs2_default_inv.items)

    cs2_trade_protected_inv = await client.inventory.get(AppContext.CS2_PROTECTED)
    print("CS2 trade protected items: ", cs2_trade_protected_inv.items)

    # create new App and AppContext
    BongoCatApp = App(3419430, "Bongo Cat")
    BongoCatDefault = BongoCatApp.with_context(2)

    bongo_cat_inv = await client.inventory.get(BongoCatDefault)
    print("Bongo Cat items: ", bongo_cat_inv.items)

    await client.transport.close()


asyncio.run(get_inventory())

Retrieving item orders histogram from SteamMarket with an unauthenticated client:

import asyncio

from aiosteampy.client import SteamPublicClient, App


async def get_histogram():
    client = SteamPublicClient()

    # Glock-18 | Fully Tuned (Field-Tested)
    histogram = await client.market.get_orders_histogram(176611887)

    print("Get histogram: ", histogram)

    await client.transport.close()


asyncio.run(get_histogram())

Public

SteamPublicClient encompasses all domain methods that can be done without a need to be authenticated. Smiply, it allows us to interact with Steam domains without a need to do a login:

import asyncio

from aiosteampy.client import SteamPublicClient, App


async def get_market_listings():
    client = SteamPublicClient()

    listings = await client.market.get_listings(
        "FAMAS | Rapid Eye Movement (Field-Tested)",
        App.CS2,
    )

    print(listings.listings)


asyncio.run(get_market_listings())

Fetching price history of an item works similarly — no login needed:

import asyncio

from aiosteampy.client import SteamPublicClient, App


async def get_price_history():
    client = SteamPublicClient()

    entries = await client.market.get_price_history(
        "Collector's Bonk! Atomic Punch",
        App.TF2,
    )

    for e in entries:
        print(e.date, e.price_raw, e.daily_volume)


asyncio.run(get_price_history())

Each PriceHistoryEntry contains:

  • price — price in cents (int)
  • price_raw — raw price as returned by Steam (float)
  • date — sale date (datetime)
  • daily_volume — number of sales on that day (int)

An empty list is returned when Steam has no history for the item.

More examples

Below are more comprehensive examples to help understand how things work.

Do work

from aiosteampy.client import SteamClient, AppContext

client = SteamClient(...)

# get inventory of the current user
my_inventory = await client.inventory.get(AppContext.CS2)
first_item = my_inventory.items[0]

# fetch listings for this item class
listings = await client.market.get_listings(first_item.description)
first_listing = listings.listings[0]

# buy first listing
wallet_info = await client.market.buy_listing(first_listing)
print("Remaining balance: ", wallet_info.balance)

# let's increase price for about 20%
my_price = int(first_listing.converted.price * 1.2)

# place sell order on a market
listing_id = await client.market.place_sell_listing(first_item, price=my_price)

# hmm, we've changed our idea and want to cancel sell listing
await client.market.cancel_sell_listing(listing_id)

Do another work

from aiosteampy.client import SteamClient, AppContext
from aiosteampy.id import SteamID

client = SteamClient(...)

# get inventory of the current user
my_inventory = await client.inventory.get(AppContext.CS2)
# get all Nova Mandrel items from inventory 
gifts = list(filter(lambda i: "Nova Mandrel" in i.description.name, my_inventory.items))

partner = SteamID(123456789)  # partner, which is in a friends list

# make and confirm trade, fetch and return trade offer
trade_offer_id = await client.trade.send(
    partner,
    gifts,
    message="Gift for my friend!",
)

trade = await client.trade.get(trade_offer_id)

# wait some time to give partner a time to react

if trade.accepted:
    print("yeeahs")
elif trade.declined:
    print("Bbut wmhhy?")
elif trade.active:
    await client.trade.cancel(trade)  # haha, we revoke our gift

Catch errors

from aiosteampy.client import SteamClient, EResultError
from aiosteampy.transport import NetworkError

client = SteamClient(...)

try:
    await client.profile.set_alias("my_awesome_alias")
    notifications = await client.notifications.get()
except NetworkError:
    print("Need to pay my internet bills :(")
except EResultError as e:
    print(f"Steam response with error ({e.result} | {e.msg} | {e.data}), what a surprise!")