Python SDK

​

Installation

pip install py-1151

​

Initialising the client

from py_1151 import Client

client = Client(
    api_key="sk_live_...",
    timeout=15,            # optional, defaults to 30 seconds
)

• Use base_url="https://staging-api.example" to point at alternative environments.
• Pass a configured requests.Session via session= to reuse connections, retries, or proxies.

​

Wallet management

wallet = client.create_wallet(
    name="first_wallet",
    network="tron",
    testnet=False,
    metadata={"customer_id": "cust_123", "environment": "staging"},
)
print(wallet.id, wallet.address, wallet.metadata)

fetched = client.get_wallet(wallet.id)
print(fetched.last_used, fetched.metadata)

• Wallet objects expose properties: id, wallet_name, address, network, testnet, last_used, metadata, and raw_data.
• client.get_wallet(wallet_id) accepts a wallet ID (w_<uuid>), wallet address, or wallet name when retrieving data.
• If the resource does not exist the SDK returns a wallet object with None fields so you can branch on wallet.id.

​

Deleting wallets

client.delete_wallet(wallet.id)

# when you only have the address available
client.delete_wallet(wallet.address)

• delete_wallet returns None on success and raises requests.HTTPError for missing or unauthorized wallets.
• Pass either the wallet ID (w_<uuid>) or the on-chain address to remove the wallet.

​

Sending payments

success, tx_id = wallet.send(
    amount=125.0,
    destination="TDZpQzZ3...",
    asset="TRX",
    metadata={"invoice": "INV-42", "customer_id": "cust_123"},
)

if not success:
    print("Transfer failed:", tx_id)

• For ERC-20 and TRC-20 assets ensure the wallet holds enough native token to pay gas or energy.
• Include a metadata mapping to persist identifiers alongside the transaction; it is accessible later through the API or SDK helpers.
• The tuple captures both success state and the transaction hash or provider error message.
• client.send_from_wallet(wallet_id, ...) accepts a wallet ID or address; the wallet.send(...) helper reads the ID from the instance.

​

Custom ERC-20 by contract

success, tx_id = client.send_from_wallet(
    wallet_id=wallet.id,
    amount=12.5,
    destination="0xA1b02d8c67b0FDCF4E379855868DeB470E169cfB",
    eth_erc20_contract="0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    eth_fee=65_000,
)

• For Ethereum, provide either asset or eth_erc20_contract (not both).
• amount is in token units for ERC-20 transfers.

​

Tuning network fees

success, tx_id = client.send_from_wallet(
    wallet_id=wallet.id,
    amount=0.05,
    destination="0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    asset="ETH",
    btc_fee="high",                  # optional BTC fee tier or sat/vByte string
    eth_fee=120_000,                  # gas limit override
    eth_max_priority_fee_per_gas=2_000_000_000,  # wei
    eth_max_fee_per_gas=3_500_000_000,           # wei
    metadata={"invoice": "INV-42"},
)

• btc_fee accepts the provider tiers ("low", "normal", "high") or a custom sat/kByte value; the SDK forwards the string as-is.
• eth_fee overrides the gas limit; defaults are 21,000 for ETH and 65,000 for ERC-20 transfers.
• eth_max_priority_fee_per_gas and eth_max_fee_per_gas map to the EIP-1559 fields in wei—ensure the max fee is greater than or equal to the priority fee.
• Include metadata when you want the transaction record to carry your internal references.
• Skip any of the parameters to let the API choose the recommended values.

​

BTC multi-output sends

# From a Wallet instance
success, tx_id = wallet.send(
    destination={
        "tb1qaddr1...": 0.004,
        "tb1qaddr2...": 0.006,
    },
    asset="BTC",
    btc_fee="normal",
)

# From a Client instance
success, tx_id = client.send_from_wallet(
    wallet_id=wallet.id,
    destination={
        "tb1qaddr1...": 0.004,
        "tb1qaddr2...": 0.006,
    },
    asset="BTC",
    btc_fee="low",
)

• Provide exactly one shape: either destination as a string with amount, or a mapping for destination without amount.
• Multi-output is currently supported only for BTC.

​

Listing UTXOs

utxos = client.get_utxos(wallet_id="w_btc_wallet")
for utxo in utxos:
    print(utxo.txid, utxo.amount_btc)

​

Retrieving transactions

tx_by_id = client.get_transaction("tx_2c4f2b01-5f49-4c66-b379-a9e0c7df8f5e")
print(tx_by_id.asset, tx_by_id.amount, tx_by_id.success)

tx_by_hash = client.get_transaction(
    "0x3f9d0b55c8122df4d6d2b41cb6c90a3f7bf8f4f8d4f3c7d1a5b2c3d4e5f6a7b8"
)
print(tx_by_hash.associated_wallet)

• get_transaction accepts either the 1151 transaction ID (tx_<uuid>) or the on-chain transaction hash.
• Transaction objects expose id, direction, asset, amount, destination, success, metadata, and raw_data for the original payload.

transactions = client.get_wallet_transactions(wallet_id=wallet.id)
# or use the wallet helper
transactions = wallet.transactions()

for tx in transactions:
    print(tx.id, tx.created_at, tx.metadata)

​

Error handling

import requests

try:
    client.delete_wallet("non-existent")
except requests.HTTPError as exc:
    print(exc.response.status_code, exc.response.json())

• Non-2xx responses raise requests.HTTPError after calling response.raise_for_status().
• Timeouts raise requests.Timeout.
• For /wallet/send, inspect the (success, tx_id) tuple even when the HTTP status is 200.
• Wrap calls in try/except blocks to provide actionable feedback to operators when something goes wrong.