v0.3.18

Python SDK v0.3.18

Stable Release — This is the stable release of Story Protocol Python SDK v0.3.18.

PyPI: https://pypi.org/project/story-protocol-python-sdk/0.3.18/

---

Overview

This release adds is_registered and get_balance, introduces Group methods add_ips_to_group and remove_ips_from_group, and adds batch operations for IP registration, revenue claiming, and mint-and-register with PIL terms.

---

Key Changes

IPAsset Module

is_registered — Check if an IP is registered (#192)

IPAsset.is_registered(ip_id) checks whether an IP ID is registered on-chain.

is_registered = story_client.IPAsset.is_registered(ip_id)
# Returns True or False

batch_register — Batch register multiple NFTs as IPs (#198)

IPAsset.batch_register registers multiple NFTs as IP assets in batch, with optional metadata. Uses multicall for both metadata and non-metadata registrations.

response = story_client.IPAsset.batch_register(
    args=[
        {"nft_contract": nft_contract_1, "token_id": 1},
        {"nft_contract": nft_contract_2, "token_id": 2, "ip_metadata": {...}},
    ]
)
# Returns: tx_hash, spg_tx_hash (if metadata), results (ip_id, token_id, nft_contract)

batch_mint_and_register_ip_asset_with_pil_terms — Batch mint and register IPs with PIL terms (#201)

IPAsset.batch_mint_and_register_ip_asset_with_pil_terms mints NFTs from collections, registers them as IPs, and attaches PIL terms in one multicall.

response = story_client.IPAsset.batch_mint_and_register_ip_asset_with_pil_terms(
    args=[
        {
            "spg_nft_contract": nft_collection,
            "terms": [license_terms_template],
            "allow_duplicates": True,
        },
        {
            "spg_nft_contract": nft_collection,
            "terms": [license_terms_template],
            "ip_metadata": {"ip_metadata_uri": "...", "ip_metadata_hash": "0x..."},
            "recipient": recipient_address,
            "allow_duplicates": True,
        },
    ]
)
# Returns: tx_hash, results (ip_id, token_id, spg_nft_contract, license_terms_ids)

StoryClient

get_balance — Get native token (IP) balance (#192)

StoryClient.get_balance(address) returns the native token (IP) balance in wei for an address.

balance = story_client.get_balance(account.address)
# Returns balance in wei (int)

Group Module

add_ips_to_group — Add IPs to a group (#196)

Group.add_ips_to_group adds a list of IP IDs to a group.

response = story_client.Group.add_ips_to_group(
    group_ip_id=group_ip_id,
    ip_ids=[ip_id_1, ip_id_2, ip_id_3],
    max_allowed_reward_share_percentage=100,  # optional, default 100
)

remove_ips_from_group — Remove IPs from a group (#196)

Group.remove_ips_from_group removes a list of IP IDs from a group.

response = story_client.Group.remove_ips_from_group(
    group_ip_id=group_ip_id,
    ip_ids=[ip_id_1, ip_id_2],
)

Royalty Module

batch_claim_all_revenue — Batch claim revenue from multiple ancestor IPs (#199)

Royalty.batch_claim_all_revenue claims revenue from child IPs for multiple ancestor IPs in one or more transactions. Uses multicall when possible. Claimed tokens are aggregated, optionally transferred to the wallet, and WIP tokens are unwrapped to native tokens if requested.

response = story_client.Royalty.batch_claim_all_revenue(
    ancestor_ips=[
        {
            "ip_id": ancestor_ip_id_1,
            "claimer": claimer_address,
            "child_ip_ids": [child_ip_1, child_ip_2],
            "royalty_policies": [royalty_policy_address],
            "currency_tokens": [wip_token_address],
        },
        {
            "ip_id": ancestor_ip_id_2,
            "claimer": claimer_address,
            "child_ip_ids": [...],
            "royalty_policies": [...],
            "currency_tokens": [...],
        },
    ],
    claim_options={
        "auto_transfer_all_claimed_tokens_from_ip": True,
        "auto_unwrap_ip_tokens": True,
    },
    options={"use_multicall_when_possible": True},
)
# Returns: tx_hashes, receipts, claimed_tokens

---

Other Changes

• CODEOWNERS — Updated maintenance and ownership configuration. (#194)

---

Migration Guide

• No breaking changes. Existing APIs remain compatible.
• Use IPAsset.is_registered(ip_id) to check IP registration.
• Use StoryClient.get_balance(address) for native token balance.
• Use Group.add_ips_to_group and Group.remove_ips_from_group for group membership.
• Use IPAsset.batch_register for batch IP registration.
• Use IPAsset.batch_mint_and_register_ip_asset_with_pil_terms for batch mint-and-register with PIL terms.
• Use Royalty.batch_claim_all_revenue for batch revenue claiming across multiple ancestor IPs.