Python SDK

Introduction

The supra-python-sdk provides a seamless interface for interacting with the Supra-L1 network. It offers comprehensive support for Move VM operations and transactions, enabling developers to both build on-chain and submit MoveVM-based transactions with ease.

Key Features

• Complete Move VM Support - Full compatibility with Move VM operations

• On-chain Data Queries - Efficient methods to query blockchain state

• Transaction Management - Submit and manage transactions seamlessly

• Cryptographic Operations - Built-in support for ED25519 and multi-signature operations

• Token Operations - Native support for token creation and management

• BCS Serialization - Efficient Binary Canonical Serialization support

For detailed API documentation of all modules, see the Official Python SDK Reference and for some more reference examples, you can check official examples repo here.

---

Installation

Install via pip:

python -m pip install supra-sdk

Verify installation:

import supra_sdk
print(supra_sdk.__version__)

---

Quick Start

Initialize the Client

import asyncio
from supra_sdk.account import Account
from supra_sdk.clients.rest import SupraClient

async def main():
    # Initialize client with RPC endpoint
    client = SupraClient("https://rpc-testnet.supra.com")
    
    # Create a new account
    account = Account.generate()
    print(f"Address: {account.address()}")
    print(f"Private Key: {account.private_key.hex()}")
    
    # Close client when done
    await client.close()

if __name__ == "__main__":
    asyncio.run(main())

Request Testnet Tokens

async def get_testnet_tokens():
    client = SupraClient("https://rpc-testnet.supra.com")
    account = Account.generate()
    
    # Request tokens from faucet
    tx_hash = await client.faucet(account.address())
    
    if tx_hash:
        print(f"Faucet successful! Tx: {tx_hash}")
        # Optionally wait for confirmation
        await client.wait_for_faucet(tx_hash)
    
    await client.close()

Submit Your First Transaction

from supra_sdk.transactions import EntryFunction, TransactionArgument, TransactionPayload
from supra_sdk.type_tag import TypeTag, StructTag
from supra_sdk.bcs import Serializer
from supra_sdk.account import Account
from supra_sdk.clients.rest import SupraClient
from supra_sdk.account_address import AccountAddress

async def transfer_coins():
    client = SupraClient("https://rpc-testnet.supra.com")
    sender = Account.generate()
    recipient = Account.generate()
    
    # Fund sender account
    await client.faucet(sender.address())
    
    # Create transfer payload
    payload = EntryFunction.natural(
        "0x1::coin",
        "transfer",
        [TypeTag(StructTag.from_str("0x1::supra_coin::SupraCoin"))],
        [
            TransactionArgument(recipient.address(), Serializer.struct),
            TransactionArgument(100_000, Serializer.u64),
        ],
    )
    
    # Create and submit signed transaction
    signed_txn = await client.create_signed_transaction(
        sender, 
        TransactionPayload(payload)
    )
    
    result = await client.submit_signed_transaction(signed_txn)
    print(f"Transaction Hash: {result}")
    
    await client.close()

---

API Reference - SupraClient

SupraClient is the main interface for interacting with the Supra blockchain.

Constructor

SupraClient(base_url: str, client_config: Optional[ClientConfig] = None)

Parameters:

• base_url: RPC endpoint URL

• client_config: Optional configuration for the client

Example:

client = SupraClient("https://rpc-testnet.supra.com")

Core Methods

faucet(address: AccountAddress, wait_for_faucet: bool = True) -> Optional[str]

Request testnet tokens from the faucet.

Parameters:

• address: Recipient address

• wait_for_faucet: Whether to wait for transaction confirmation (default: True)

Returns: Transaction hash or None if failed

Example:

tx_hash = await client.faucet(account.address())

# Or without waiting
tx_hash = await client.faucet(account.address(), wait_for_faucet=False)
if tx_hash:
    await client.wait_for_faucet(tx_hash)

wait_for_faucet(tx_hash: str) -> None

Wait for faucet transaction to complete.

Parameters:

• tx_hash: Faucet transaction hash

create_signed_transaction(sender: Account, payload: TransactionPayload) -> SignedTransaction

Create a signed transaction ready for submission.

Parameters:

• sender: Account signing the transaction

• payload: Transaction payload (EntryFunction, Script, etc.)

Returns: Signed transaction object

Example:

payload = EntryFunction.natural(...)
signed_txn = await client.create_signed_transaction(account, TransactionPayload(payload))

submit_signed_transaction(signed_transaction: SignedTransaction) -> str

Submit a signed transaction to the blockchain.

Parameters:

• signed_transaction: Signed transaction object

Returns: Transaction hash

---

API Reference - Account

Account class manages cryptographic keys and signing operations.

Creating Accounts

from supra_sdk.account import Account

# Generate new random account
account = Account.generate()

# Load from private key hex string
account = Account.load_key("0x1234...private_key_hex")

# Save account to file
account.store("./my_account.json")

# Load account from file
account = Account.load("./my_account.json")

---

API Reference - Token Clients

SupraTokenClient

High-level client for fungible token operations.

Constructor

from supra_sdk.clients import SupraTokenClient

token_client = SupraTokenClient(supra_client)

Key Methods

create_collection(account: Account, name: str, description: str, uri: str) -> str

Create a new token collection.

Example:

await token_client.create_collection(
    account,
    "My Collection",
    "Collection description",
    "https://example.com/collection"
)

create_token(account: Account, collection_name: str, name: str, description: str, supply: int, uri: str, royalty_points_numerator: int) -> str

Mint a new token in a collection.

Example:

await token_client.create_token(
    account,
    "My Collection",
    "Token #1",
    "First token",
    supply=1,
    uri="https://example.com/token/1",
    royalty_points_numerator=5  # 5% royalty
)

offer_token(sender: Account, receiver: AccountAddress, creator: AccountAddress, collection_name: str, token_name: str, property_version: int, amount: int) -> str

Offer a token to another account.

claim_token(receiver: Account, sender: AccountAddress, creator: AccountAddress, collection_name: str, token_name: str, property_version: int) -> str

Claim an offered token.

get_token_balance(owner: AccountAddress, creator: AccountAddress, collection_name: str, token_name: str, property_version: int) -> int

Get token balance for an account.

get_collection(creator: AccountAddress, collection_name: str) -> dict

Get collection data.

get_token_data(creator: AccountAddress, collection_name: str, token_name: str) -> dict

Get token metadata.

---

API Reference - Transactions

Creating Transaction Payloads

from supra_sdk.transactions import (
    EntryFunction,
    TransactionArgument,
    TransactionPayload
)
from supra_sdk.type_tag import TypeTag, StructTag
from supra_sdk.bcs import Serializer

# Create an entry function payload
payload = EntryFunction.natural(
    "0x1::coin",  # Module
    "transfer",   # Function
    [TypeTag(StructTag.from_str("0x1::supra_coin::SupraCoin"))],  # Type args
    [
        TransactionArgument(recipient_address, Serializer.struct),
        TransactionArgument(amount, Serializer.u64),
    ]  # Arguments
)

# Wrap in TransactionPayload
tx_payload = TransactionPayload(payload)

EntryFunction

natural(module: str, function: str, ty_args: list[TypeTag], args: list[TransactionArgument]) -> EntryFunction (static)

Create an entry function with natural argument encoding.

Parameters:

• module: Module identifier (e.g., "0x1::coin")

• function: Function name

• ty_args: Type arguments

• args: Function arguments as TransactionArgument objects

TransactionArgument

TransactionArgument(value: Any, serializer: Callable)

Wraps an argument with its serializer function.

Common serializers from Serializer:

• Serializer.u8, Serializer.u64, Serializer.u128, Serializer.u256

• Serializer.bool

• Serializer.struct (for addresses and complex types)

• Serializer.str (for strings)

---

API Reference - Type System

TypeTag & StructTag

from supra_sdk.type_tag import TypeTag, StructTag

# Parse struct type from string
coin_type = StructTag.from_str("0x1::supra_coin::SupraCoin")

# Use in type arguments
type_arg = TypeTag(coin_type)

# Complex nested types
token_type = StructTag.from_str(
    "0x3::token::Token<0x1::supra_coin::SupraCoin>"
)

StructTag

from_str(type_tag: str) -> StructTag (static)

Parse a struct type from string representation.

Example:

# Simple type
simple = StructTag.from_str("0x1::coin::Coin")

# Generic type with type parameters
generic = StructTag.from_str("0x1::coin::Coin<0x1::supra_coin::SupraCoin>")

---

API Reference - BCS Serialization

Binary Canonical Serialization (BCS) is the format used by Move VM.

Serializer

from supra_sdk.bcs import Serializer

serializer = Serializer()
serializer.u64(12345)
serializer.str("Hello")
serializer.bool(True)

# Get serialized bytes
data = serializer.output()

Deserializer

from supra_sdk.bcs import Deserializer

deserializer = Deserializer(data)
number = deserializer.u64()
text = deserializer.str()
flag = deserializer.bool()

Common Serialization Methods

• u8(value: int), u16(value: int), u32(value: int), u64(value: int)

• u128(value: int), u256(value: int)

• bool(value: bool)

• str(value: str)

• struct(value: Serializable)

• sequence(values: list, encoder: Callable)

---

NFT Collection Example:

This example demonstrates how to create and manage an NFT collection using the Supra Python SDK.

Create a common.py file in the same directory as the below file to import RPC_NODE_URL.

import asyncio
import json
from examples.common import RPC_NODE_URL
from supra_sdk.account import Account
from supra_sdk.clients import SupraTokenClient
from supra_sdk.clients.rest import SupraClient


async def main():
    supra_client = SupraClient(RPC_NODE_URL)
    token_client = SupraTokenClient(supra_client)

    alice = Account.generate()
    bob = Account.generate()

    collection_name = "Alice's"
    token_name = "Alice's first token"
    property_version = 0

    print(f"Alice account address: {alice.address()}")
    print(f"Bob account address: {bob.address()}")

    await supra_client.faucet(alice.address())
    await supra_client.faucet(bob.address())

    print("\n=== Creating Collection and Token ===")
    await token_client.create_collection(
        alice, collection_name, "Alice's simple collection", "https://supra.com"
    )

    await token_client.create_token(
        alice,
        collection_name,
        token_name,
        "Alice's simple token",
        1,
        "https://supra.dev/img/temp.jpeg",
        0,
    )

    collection_data = await token_client.get_collection(
        alice.address(), collection_name
    )
    print(
        f"Alice's collection: {json.dumps(collection_data, indent=4, sort_keys=True)}"
    )
    balance = await token_client.get_token_balance(
        alice.address(), alice.address(), collection_name, token_name, property_version
    )
    print(f"Alice's token balance: {balance}")
    token_data = await token_client.get_token_data(
        alice.address(), collection_name, token_name
    )
    print(f"Alice's token data: {json.dumps(token_data, indent=4, sort_keys=True)}")

    print("\n=== Transferring the token to Bob ===")
    await token_client.offer_token(
        alice,
        bob.address(),
        alice.address(),
        collection_name,
        token_name,
        property_version,
        1,
    )
    await token_client.claim_token(
        bob,
        alice.address(),
        alice.address(),
        collection_name,
        token_name,
        property_version,
    )

    alice_balance = token_client.get_token_balance(
        alice.address(), alice.address(), collection_name, token_name, property_version
    )
    bob_balance = token_client.get_token_balance(
        bob.address(), alice.address(), collection_name, token_name, property_version
    )
    [alice_balance, bob_balance] = await asyncio.gather(*[alice_balance, bob_balance])
    print(f"Alice's token balance: {alice_balance}")
    print(f"Bob's token balance: {bob_balance}")

    print("\n=== Transferring the token back to Alice using MultiAgent ===")
    await token_client.direct_transfer_token(
        bob, alice, alice.address(), collection_name, token_name, 0, 1
    )
    alice_balance = token_client.get_token_balance(
        alice.address(), alice.address(), collection_name, token_name, property_version
    )
    bob_balance = token_client.get_token_balance(
        bob.address(), alice.address(), collection_name, token_name, property_version
    )
    [alice_balance, bob_balance] = await asyncio.gather(*[alice_balance, bob_balance])
    print(f"Alice's token balance: {alice_balance}")
    print(f"Bob's token balance: {bob_balance}")

    await supra_client.close()


if __name__ == "__main__":
    asyncio.run(main())

---