​
Installation

pip install py-1151
Install from PyPI inside your runtime environment or virtual environment so the SDK is available to your application code.

​
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.
The client constructor keeps HTTP configuration separate from business logic. Inject a Session with retry behavior or proxy settings once and reuse it across wallet operations.

​
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.
Wallet instances translate snake_case fields to idiomatic Python attributes while preserving the original payload on raw_data for custom parsing.

​
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.

​
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.
The same keyword arguments are available on wallet.send(...), which simply delegates to client.send_from_wallet.

​
BTC multi-output sends

For Bitcoin, you can send to multiple recipients in a single transaction by passing a mapping for destination and omitting amount: 
# 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",
)
Notes:
  • 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)
The UTXO helper exposes txid, vout, address, amount_btc, confirmations, script, and raw_data.

​
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)
The wallet feed returns the most recent transactions first so you can sync them directly into activity views.

​
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.