Client Reference

class artifacts.AsyncArtifactsClient(token=None, *, base_url='https://api.artifactsmmo.com', auto_wait=True, retry=None)[source]

Bases: object

Async SDK client for the Artifacts MMO API.

Use as an async context manager:

async with AsyncArtifactsClient(token="your_token") as client:
    char = client.character("MyChar")
    await char.move(x=0, y=1)    # auto-waits cooldown
    await char.fight()            # auto-waits cooldown
Parameters:

  • token (Optional[str]) – JWT token for authentication. Generate one via client.token.generate(username, password) or pass an existing token.

  • base_url (str) – API base URL. Defaults to the production server.

  • auto_wait (bool) – If True (default), every action automatically sleeps until its cooldown expires. Disable globally here or per-character/per-call.

  • retry (Optional[RetryConfig]) – Custom retry configuration. Defaults to 3 retries with exponential backoff.

property auto_wait: bool

Whether actions automatically sleep until their cooldown expires.

Setting this on the client affects all characters that were created without an explicit per-character override:

client.auto_wait = False   # disable globally
client.auto_wait = True    # re-enable globally
character(name, *, auto_wait=None)[source]

Return a Character controller for name.

Parameters:

  • auto_wait (bool | None) – Override the client-level auto_wait setting for this character. If None (default), the character shares the client reference and will reflect any future changes to client.auto_wait automatically.

  • name (str)

Return type:

Character

async start()[source]

Start the HTTP session (called automatically by __aenter__).

Return type:

None

async close()[source]

Close the HTTP session (called automatically by __aexit__).

Return type:

None

class artifacts.sync_client.ArtifactsClient(token=None, *, base_url='https://api.artifactsmmo.com', auto_wait=True, retry=None)[source]

Bases: object

Synchronous SDK client for the Artifacts MMO API.

No async/await needed – every call blocks until complete:

from artifacts import ArtifactsClient

with ArtifactsClient(token="your_token") as client:
    char = client.character("MyChar")
    info = char.get()
    print(f"{info.name} lv{info.level}")

    char.move(x=0, y=1)          # blocks, auto-waits cooldown
    result = char.fight()         # blocks, auto-waits cooldown
    char.skills.craft(code="iron_sword")
    char.bank.deposit_gold(quantity=100)
Parameters:

  • token (Optional[str]) – JWT token for authentication.

  • base_url (str) – API base URL. Defaults to the production server.

  • auto_wait (bool) – If True (default), every action automatically sleeps until its cooldown expires.

  • retry (Any) – Custom retry configuration.

character(name, *, auto_wait=None)[source]

Return a synchronous SyncCharacter controller for name.

Parameters:

  • name (str)

  • auto_wait (bool | None)

Return type:

SyncCharacter

property auto_wait: bool

Whether actions automatically sleep until their cooldown expires.

Setting this on the client affects all characters that were created without an explicit per-character override:

client.auto_wait = False   # disable globally
client.auto_wait = True    # re-enable globally
property server: _SyncProxy
property token: _SyncProxy
property accounts: _SyncProxy
property my_account: _SyncProxy
property characters: _SyncProxy
property achievements: _SyncProxy
property badges: _SyncProxy
property effects: _SyncProxy
property events: _SyncProxy
property grand_exchange: _SyncProxy
property items: _SyncProxy
property leaderboard: _SyncProxy
property maps: _SyncProxy
property monsters: _SyncProxy
property npcs: _SyncProxy
property resources: _SyncProxy
property tasks: _SyncProxy
property simulation: _SyncProxy
property sandbox: _SyncProxy
close()[source]

Close the HTTP session.

Return type:

None

class artifacts.http.RetryConfig(max_retries=3, base_delay=1.0, max_delay=30.0, retry_on_status=(429, 500, 502, 503, 504), retry_on_cooldown=True)[source]

Configuration for automatic request retries.

Parameters:

  • max_retries (int) – Maximum number of retry attempts (default 3).

  • base_delay (float) – Initial delay in seconds before the first retry (default 1.0).

  • max_delay (float) – Maximum delay cap in seconds for exponential backoff (default 30.0).

  • retry_on_status (tuple[int, ...]) – HTTP status codes that trigger a retry.

  • retry_on_cooldown (bool) – If True, automatically wait and retry on CooldownActiveError (status 499).

artifacts.setup_logging(level=20)[source]

Configure logging for the Artifacts SDK.

Sets up a StreamHandler on the "artifacts" logger with a concise timestamp format. Subsequent calls update the level without adding duplicate handlers.

Parameters:

level (int)

Return type:

None