phantasma-sdk-py 2.1.0

Typed Python SDK for the Phantasma blockchain with support for the Phoenix chain update

Phantasma Python SDK

Typed Python SDK for the Phantasma blockchain with support for the Phoenix chain update.

The package provides JSON-RPC access, transaction building and signing, VM script helpers, Ed25519 keys/signatures, and Carbon wire-format support.

The public API uses Python naming conventions, dataclasses, exceptions, and type hints. Fixture tests lock shared VM and Carbon wire formats against reference SDK vectors.

Requirements

• Python 3.11 or newer
• cryptography
• requests

Development uses uv, ruff, mypy, and pytest.

Install

pip install phantasma-sdk-py

For local development:

uv sync --extra dev
just check

Modules

• phantasma_py.crypto: addresses, hashes, WIF keys, Ed25519 signatures
• phantasma_py.vm: VM objects, opcodes, and ScriptBuilder
• phantasma_py.transaction: VM script transaction serialization/signing
• phantasma_py.rpc: JSON-RPC client and typed response dataclasses
• phantasma_py.carbon: Carbon primitives, VM schemas, module call args, token builders, and transaction messages

RPC

from phantasma_py.rpc import PhantasmaRPC

rpc = PhantasmaRPC.mainnet()
account = rpc.get_account("P...")
balance = account.get_token_balance("SOUL", decimals=8)

print(balance.decimal_amount())

JsonRpcClient validates JSON-RPC response ids, propagates RPC errors as RPCError, and accepts endpoints that echo numeric ids as strings.

Keys And Signatures

from phantasma_py.crypto import PhantasmaKeys

keys = PhantasmaKeys.from_wif("...")
signature = keys.sign(b"message")

assert signature.verify(b"message", [keys.address])

Address parsing rejects malformed Base58/checksum data. Address.from_text("NULL") and Address.null() produce the system null address.

VM Scripts

from phantasma_py.crypto import Address, PhantasmaKeys
from phantasma_py.vm import ScriptBuilder

keys = PhantasmaKeys.from_wif("...")

script = (
    ScriptBuilder.begin()
    .allow_gas(keys.address, Address.null(), gas_price=10_000, gas_limit=210_000)
    .call_contract("stake", "GetStake", keys.address)
    .spend_gas(keys.address)
    .end_script()
)

end_script() raises BuilderError if labels or user input are invalid. end_script_with_error() returns (script, error) for callers that prefer an explicit checked path.

VM Script Transactions

from phantasma_py.crypto import PhantasmaKeys
from phantasma_py.transaction import Transaction
from phantasma_py.vm import ScriptBuilder

keys = PhantasmaKeys.from_wif("...")
script = ScriptBuilder.begin().call_interop("Runtime.Time").end_script()

tx = Transaction("mainnet", "main", script, expiration=1_754_000_000)
tx.sign(keys)

raw_hex = tx.to_bytes().hex()

Broadcasting is intentionally separate from signing:

tx_hash = rpc.send_raw_transaction(raw_hex)

Do not run broadcasting examples without explicit credentials, funds, and an endpoint you intend to use.

Carbon

Carbon serialization uses fixed-width little-endian integers, zero-terminated strings, fixed byte types, compact signed Int256 values, and typed transaction payloads. Use serialize() and deserialize() for stable wire round-trips.

from phantasma_py.carbon import (
    Bytes32,
    IntX,
    build_token_info,
    build_token_metadata,
    prepare_standard_token_schemas,
    serialize,
)

owner = Bytes32()
schemas = prepare_standard_token_schemas(shared_metadata=False)
token = build_token_info(
    symbol="ART",
    max_supply=IntX(0),
    is_nft=True,
    decimals=0,
    owner=owner,
    metadata=build_token_metadata(
        {
            "name": "Art Token",
            "icon": "data:image/png;base64,AA==",
            "url": "https://example.invalid/art",
            "description": "Example token metadata",
        }
    ),
    token_schemas=serialize(schemas),
)

payload = serialize(token)

Carbon token and NFT helpers validate required metadata, token symbol casing, standard schema fields, Carbon NFT address packing, and result parsing. Token symbols follow the Carbon token-module rule of uppercase ASCII letters A-Z.

Carbon transaction signing is available without going through RPC:

from phantasma_py.carbon import sign_and_serialize_tx_msg_hex
from phantasma_py.crypto import PhantasmaKeys

keys = PhantasmaKeys.from_wif("...")
raw_hex = sign_and_serialize_tx_msg_hex(tx_msg, keys)

Development

just f          # format and autofix
just f-check    # verify formatting and lint
just typecheck  # strict mypy
just test       # pytest
just build      # package build
just check      # all checks above

The shared Carbon vector fixture in tests/fixtures/carbon_vectors.tsv is copied from the Go SDK and should stay byte-for-byte compatible across SDKs.