0
# XRPL-PY
1

2
A complete Python library for interacting with the XRP Ledger blockchain, providing transaction creation, account management, cryptographic operations, and comprehensive XRPL protocol support. The library offers both synchronous and asynchronous interfaces for building applications that can send transactions, query ledger data, and interact with the decentralized exchange built into the XRPL.
3

4
## Package Information
5

6
- **Package Name**: xrpl-py
7
- **Language**: Python
8
- **Installation**: `pip install xrpl-py`
9
- **Requires**: Python >=3.8.1
10

11
## Core Imports
12

13
```python
14
import xrpl
15
```
16

17
Common imports for working with XRPL:
18

19
```python
20
from xrpl import (
21
    account, clients, models, transaction, utils, wallet,
22
    CryptoAlgorithm, XRPLException
23
)
24
from xrpl.clients import JsonRpcClient
25
from xrpl.models.transactions import Payment
26
from xrpl.models.amounts import IssuedCurrencyAmount
27
from xrpl.wallet import Wallet
28
```
29

30
Asynchronous versions:
31

32
```python
33
from xrpl import asyncio as xrpl_asyncio
34
from xrpl.asyncio.clients import AsyncJsonRpcClient
35
```
36

37
## Basic Usage
38

39
```python
40
from xrpl.clients import JsonRpcClient
41
from xrpl.wallet import Wallet
42
from xrpl.models.transactions import Payment
43
from xrpl import transaction
44

45
# Connect to XRPL testnet
46
client = JsonRpcClient("https://s.altnet.rippletest.net:51234")
47

48
# Create or load a wallet
49
wallet = Wallet.create()
50
print(f"Wallet address: {wallet.address}")
51

52
# Create a payment transaction
53
payment_tx = Payment(
54
    account=wallet.address,
55
    destination="rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
56
    amount="1000000"  # 1 XRP in drops
57
)
58

59
# Sign and submit the transaction
60
response = transaction.submit_and_wait(payment_tx, client, wallet)
61
print(f"Transaction result: {response.result}")
62

63
# Query account information
64
account_info = account.get_balance(wallet.address, client)
65
print(f"Account balance: {account_info} drops")
66
```
67

68
## Architecture
69

70
The xrpl-py library is organized around several key concepts:
71

72
- **Clients**: Network interfaces for connecting to XRPL nodes via JSON-RPC or WebSocket
73
- **Models**: Type-safe data structures for transactions, requests, amounts, and responses
74
- **Transactions**: Complete lifecycle management including creation, signing, and submission
75
- **Accounts**: Query and manage account state, balances, and transaction history
76
- **Wallets**: Cryptographic key management and address derivation
77
- **Core**: Low-level cryptographic operations, address encoding, and binary serialization
78
- **Utils**: Helper functions for common operations like unit conversions and time formatting
79

80
The library provides both synchronous and asynchronous versions of most operations, extensive transaction type support for all XRPL features, robust utility functions, and comprehensive model classes for type-safe XRPL interactions.
81

82
## Capabilities
83

84
### Core Cryptographic Operations
85

86
Low-level cryptographic functions, address encoding/decoding, binary transaction encoding, and fundamental XRPL constants and types.
87

88
```python { .api }
89
from xrpl.core.keypairs import generate_seed, derive_keypair, sign
90
from xrpl.core.addresscodec import encode_classic_address, decode_classic_address
91
from xrpl.core.binarycodec import encode, decode
92
from xrpl import CryptoAlgorithm, XRPLException
93
```
94

95
[Core Operations](./core.md)
96

97
### Account Management
98

99
Query account information, balances, transaction history, and verify account existence on the ledger.
100

101
```python { .api }
102
from xrpl import account
103

104
def does_account_exist(address: str, client, ledger_index: str = "validated") -> bool: ...
105
def get_balance(address: str, client, ledger_index: str = "validated") -> int: ...
106
def get_account_root(address: str, client, ledger_index: str = "validated") -> dict: ...
107
def get_next_valid_seq_number(address: str, client, ledger_index: str = "current") -> int: ...
108
```
109

110
[Account Management](./accounts.md)
111

112
### Transaction Management
113

114
Create, sign, submit, and manage XRPL transactions with full support for all transaction types including payments, offers, escrows, NFTs, AMM operations, and cross-chain bridges.
115

116
```python { .api }
117
from xrpl import transaction
118

119
def sign(transaction, wallet, multisign: bool = False): ...
120
def submit(transaction, client, fail_hard: bool = False): ...
121
def sign_and_submit(transaction, client, wallet, autofill: bool = True, check_fee: bool = True): ...
122
def submit_and_wait(transaction, client, wallet, autofill: bool = True, check_fee: bool = True): ...
123
def autofill(transaction, client): ...
124
```
125

126
[Transaction Management](./transactions.md)
127

128
### Network Clients
129

130
Connect to XRPL networks using JSON-RPC or WebSocket protocols with both synchronous and asynchronous interfaces.
131

132
```python { .api }
133
from xrpl.clients import JsonRpcClient, WebsocketClient
134
from xrpl.asyncio.clients import AsyncJsonRpcClient, AsyncWebsocketClient
135

136
class JsonRpcClient:
137
    def __init__(self, url: str): ...
138
    def request(self, request): ...
139

140
class WebsocketClient:
141
    def __init__(self, url: str): ...
142
    def send(self, request): ...
143
```
144

145
[Network Clients](./clients.md)
146

147
### Ledger Operations
148

149
Query ledger state information including current fees, ledger sequences, and network status.
150

151
```python { .api }
152
from xrpl import ledger
153

154
def get_fee(client, max_fee_xrp: str = None) -> str:
155
    """Get current base fee and reserve amounts from the network."""
156

157
def get_latest_open_ledger_sequence(client) -> int:
158
    """Get the latest open (not yet validated) ledger sequence number."""
159

160
def get_latest_validated_ledger_sequence(client) -> int:
161
    """Get the latest validated ledger sequence number."""
162
```
163

164
[Ledger Operations](./ledger.md)
165

166
### Data Models and Types
167

168
Comprehensive type-safe models for transactions, requests, amounts, currencies, and all XRPL data structures.
169

170
```python { .api }
171
from xrpl.models.transactions import Payment, OfferCreate, TrustSet
172
from xrpl.models.amounts import IssuedCurrencyAmount, Amount
173
from xrpl.models.currencies import IssuedCurrency, XRP
174
from xrpl.models.requests import AccountInfo, Ledger, Tx
175

176
class Payment(Transaction):
177
    destination: str
178
    amount: Amount
179
    ...
180
```
181

182
[Data Models](./models.md)
183

184
### Wallet Operations
185

186
Create, manage, and operate XRPL wallets including key generation, address derivation, and testnet funding.
187

188
```python { .api }
189
from xrpl.wallet import Wallet, generate_faucet_wallet
190

191
class Wallet:
192
    address: str
193
    public_key: str
194
    private_key: str
195
    seed: str
196
    
197
    @classmethod
198
    def create(cls, algorithm: CryptoAlgorithm = CryptoAlgorithm.ED25519) -> "Wallet": ...
199
    @classmethod
200
    def from_seed(cls, seed: str, algorithm: CryptoAlgorithm = CryptoAlgorithm.ED25519) -> "Wallet": ...
201
```
202

203
[Wallet Operations](./wallets.md)
204

205
### Utility Functions
206

207
Helper functions for unit conversions, time formatting, string encoding, NFT operations, and transaction analysis.
208

209
```python { .api }
210
from xrpl.utils import (
211
    xrp_to_drops, drops_to_xrp,
212
    ripple_time_to_datetime, datetime_to_ripple_time,
213
    str_to_hex, hex_to_str,
214
    get_balance_changes, get_nftoken_id
215
)
216

217
def xrp_to_drops(xrp) -> str: ...
218
def drops_to_xrp(drops) -> Decimal: ...
219
def ripple_time_to_datetime(ripple_time: int) -> datetime: ...
220
```
221

222
[Utility Functions](./utils.md)
223

224
## Exceptions
225

226
```python { .api }
227
# Base exception
228
class XRPLException(Exception): ...
229

230
# Module-specific exceptions
231
class XRPLRequestFailureException(XRPLException): ...
232
class XRPLModelException(XRPLException): ...
233
class XRPLReliableSubmissionException(XRPLException): ...
234
class XRPLFaucetException(XRPLException): ...
235
class XRPLAddressCodecException(XRPLException): ...
236
class XRPLBinaryCodecException(XRPLException): ...
237
class XRPLKeypairsException(XRPLException): ...
238
class XRPRangeException(XRPLException): ...
239
class XRPLTimeRangeException(XRPLException): ...
240
```
241

242
## Constants
243

244
```python { .api }
245
from xrpl import CryptoAlgorithm
246

247
class CryptoAlgorithm(str, Enum):
248
    ED25519 = "ed25519"
249
    SECP256K1 = "secp256k1"
250
```