Getting Started

This guide shows you how to connect and perform your first actions in just a few minutes.

Connecting

There are two ways to use the SDK:

Simple (synchronous) — recommended for beginners:

from artifacts import ArtifactsClient

with ArtifactsClient(token="your_token") as client:
    # all your code here
    pass

Async — for advanced users or multi-character bots:

import asyncio
from artifacts import AsyncArtifactsClient

async def main():
    async with AsyncArtifactsClient(token="your_token") as client:
        # all your code here (use await)
        pass

asyncio.run(main())

Tip

In the sync version, you do not need to write await. The SDK takes care of that for you.

List Your Characters

from artifacts import ArtifactsClient

with ArtifactsClient(token="your_token") as client:
    characters = client.my_account.get_characters()
    for c in characters:
        print(f"{c.name} — level {c.level} — HP {c.hp}/{c.max_hp}")

Control a Character

# Pick a character
char = client.character("MyChar")

# View its info
info = char.get()
print(f"{info.name} is at ({info.x}, {info.y})")
print(f"HP: {info.hp}/{info.max_hp}")
print(f"Gold: {info.gold}")

Move and Fight

# Go to (0, 1) — that's where the chickens are!
char.move(x=0, y=1)

# Fight the monster on the tile
result = char.fight()
fight = result.fight

print(f"Result: {fight.result.value}")  # "win" or "loss"
print(f"Turns: {fight.turns}")
print(f"+{fight.characters[0].xp} XP")
print(f"+{fight.characters[0].gold} gold")

# Rest if HP is low
updated = result.characters[0]
if updated.hp < updated.max_hp * 0.5:
    rest = char.rest()
    print(f"+{rest.hp_restored} HP restored")

Note

The SDK automatically waits for cooldowns between actions. You don’t need to manage anything!

Browse Game Data

The client gives you access to all public game data:

# Monster info
chicken = client.monsters.get("chicken")
print(f"{chicken.name} — level {chicken.level} — HP {chicken.hp}")

# Search for items
items = client.items.get_all(min_level=1, max_level=5, size=5)
for item in items.data:
    print(f"{item.name} (level {item.level})")

# Explore the map
maps = client.maps.get_all(content_type="monster", size=5)
for m in maps.data:
    print(f"({m.x}, {m.y}) — {m.content.code if m.content else '?'}")

Quick Reference

What you want to do	Code
Connect	ArtifactsClient(token="...")
Pick a character	client.character("Name")
Move	char.move(x=0, y=1)
Fight	char.fight()
Rest	char.rest()
View character info	char.get()
Game data	client.monsters.get("chicken")

Next Step

Head to Your Character to learn everything about character actions.