XRPL Py

https://github.com/xrplf/xrpl-py.git
Admin
A pure Python implementation for interacting with the XRP Ledger, simplifying serialization,...
Tokens:243,479
Snippets:692
Trust Score:9.6
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install and configure pre-commit hooks

Source: https://github.com/xrplf/xrpl-py.git/blob/main/CONTRIBUTING.md

Installs the pre-commit package and sets up the git hooks for linting and checks.

```bash
pip3 install pre-commit
        pre-commit install
```

--------------------------------

### Install Local xrpl-py Package

Source: https://github.com/xrplf/xrpl-py.git/blob/main/RELEASE.md

Install the locally built package using pip to verify its functionality. Replace 'path/to/local/xrpl-py/dist/.whl' with the actual path to the built wheel file.

```bash
pip install path/to/local/xrpl-py/dist/.whl
```

--------------------------------

### Install xrpl-py

Source: https://github.com/xrplf/xrpl-py.git/blob/main/README.md

Install the xrpl-py library using pip. The library supports Python 3.10 and later.

```bash
pip3 install xrpl-py
```

--------------------------------

### Install pyenv

Source: https://github.com/xrplf/xrpl-py.git/blob/main/CONTRIBUTING.md

Installs pyenv using Homebrew for managing Python versions.

```bash
brew install pyenv
```

--------------------------------

### Install Poetry

Source: https://github.com/xrplf/xrpl-py.git/blob/main/CONTRIBUTING.md

Installs Poetry, a dependency management tool for Python, using a curl script.

```bash
curl -sSL https://install.python-poetry.org | python3 -
```

--------------------------------

### Install Poetry dependencies

Source: https://github.com/xrplf/xrpl-py.git/blob/main/CONTRIBUTING.md

Installs project dependencies defined in pyproject.toml using Poetry.

```bash
poetry install
```

--------------------------------

### startswith

Source: https://github.com/xrplf/xrpl-py.git/blob/main/docs/source/xrpl.models.requests.md

Checks if a string starts with a specified prefix. Can also check for a tuple of prefixes and specify start/end positions.

```APIDOC
## startswith(prefix)

### Description
Return True if S starts with the specified prefix, False otherwise. With optional start, test S beginning at that position. With optional end, stop comparing S at that position. prefix can also be a tuple of strings to try.

### Method
N/A (This is a string method, not an API endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **bool** (bool) - True if the string starts with the prefix, False otherwise.

#### Response Example
N/A
```

--------------------------------

### Create a Network Client

Source: https://github.com/xrplf/xrpl-py.git/blob/main/README.md

Use the `xrpl.clients` library to create a network client for connecting to the XRP Ledger. This example connects to the test network.

```python
from xrpl.clients import JsonRpcClient
JSON_RPC_URL = "https://s.altnet.rippletest.net:51234"
client = JsonRpcClient(JSON_RPC_URL)
```

--------------------------------

### Install Python version with pyenv

Source: https://github.com/xrplf/xrpl-py.git/blob/main/CONTRIBUTING.md

Installs a specific Python version (e.g., 3.11.6) using pyenv.

```bash
pyenv install 3.11.6
```

--------------------------------

### Build xrpl-py Package Locally

Source: https://github.com/xrplf/xrpl-py.git/blob/main/RELEASE.md

Use 'poetry build' to create local distribution files for the package. This is a prerequisite for local installation and testing.

```bash
poetry build
```

--------------------------------

### Run xrpld Docker container

Source: https://github.com/xrplf/xrpl-py.git/blob/main/CONTRIBUTING.md

Starts a standalone xrpld node in a Docker container, exposing necessary ports for integration tests.

```bash
docker run \
  --detach \
  --publish 5005:5005 \
  --publish 6006:6006 \
  --volume "$PWD/.ci-config/:/etc/opt/xrpld/" \
  --name xrpld-service \
  rippleci/xrpld:develop --standalone
```

--------------------------------

### startswith(prefix) → bool

Source: https://github.com/xrplf/xrpl-py.git/blob/main/docs/source/xrpl.models.requests.md

Returns True if the string starts with the specified prefix, False otherwise.

```APIDOC
## startswith(prefix) → bool

### Description
Return True if S starts with the specified prefix, False otherwise.
With optional start, test S beginning at that position.
With optional end, stop comparing S at that position.
prefix can also be a tuple of strings to try.
```

--------------------------------

### Generate reference documentation

Source: https://github.com/xrplf/xrpl-py.git/blob/main/CONTRIBUTING.md

Builds the project's reference documentation locally using Sphinx and Poetry.

```bash
# Go to the docs/ folder
cd docs/

# Build the docs
poetry run sphinx-apidoc -o source/ ../xrpl
poetry run make html
```

--------------------------------

### View generated documentation

Source: https://github.com/xrplf/xrpl-py.git/blob/main/CONTRIBUTING.md

Navigates to the directory where the generated HTML documentation is located.

```bash
# Go to docs/_build/html/
cd docs/_build/html/
```

--------------------------------

### Generate Faucet Wallet

Source: https://github.com/xrplf/xrpl-py.git/blob/main/README.md

Creates a wallet from a Testnet faucet. Requires an initialized client.

```python
test_wallet = generate_faucet_wallet(client)
test_account = test_wallet.address
print("Classic address:", test_account)
# Classic address: rEQB2hhp3rg7sHj6L8YyR4GG47Cb7pfcuw
```

--------------------------------

### Remove prefix from string

Source: https://github.com/xrplf/xrpl-py.git/blob/main/docs/source/xrpl.models.requests.md

Use removeprefix() to return a new string with a specified prefix removed if the string starts with that prefix. If the string does not start with the prefix, the original string is returned.

```python
"hello world" .removeprefix("hello ")
```

```python
"hello world" .removeprefix("goodbye ")
```

--------------------------------

### Create Wallet from Seed

Source: https://github.com/xrplf/xrpl-py.git/blob/main/README.md

Create a wallet instance from a given seed using `xrpl.wallet.Wallet.from_seed()`. This is useful if you have a private key or seed phrase.

```python
wallet_from_seed = xrpl.wallet.Wallet.from_seed(seed)
print(wallet_from_seed)
```

--------------------------------

### rsplit(sep=None, maxsplit=-1)

Source: https://github.com/xrplf/xrpl-py.git/blob/main/docs/source/xrpl.models.requests.md

Splits the string into a list of substrings, starting from the end.

```APIDOC
## rsplit(sep=None, maxsplit=-1)

### Description
Return a list of the substrings in the string, using sep as the separator string.

> sep
> : The separator used to split the string.
>   <br/>
>   When set to None (the default value), will split on any whitespace
>   character (including n r t f and spaces) and will discard
>   empty strings from the result.

> maxsplit
> : Maximum number of splits.
>   -1 (the default value) means no limit.

Splitting starts at the end of the string and works to the front.
```

--------------------------------

### Integer Conjugate Example

Source: https://github.com/xrplf/xrpl-py.git/blob/main/docs/source/xrpl.models.transactions.md

Returns the integer itself, as the complex conjugate of any integer is the integer itself.

```python
>>> (10).conjugate()
10
```

--------------------------------

### Get Real Part of Complex Number

Source: https://github.com/xrplf/xrpl-py.git/blob/main/docs/source/xrpl.models.transactions.md

Retrieves the real part of a complex number.

```python
the real part of a complex number
```

--------------------------------

### Using AsyncWebsocketClient for Fee Retrieval

Source: https://github.com/xrplf/xrpl-py.git/blob/main/docs/source/xrpl.asyncio.clients.md

Demonstrates how to use AsyncWebsocketClient with helper functions like get_fee or by making raw requests. This is suitable when not utilizing WebSocket-specific features like subscriptions.

```python
from xrpl.asyncio.clients import AsyncWebsocketClient
from xrpl.asyncio.ledger import get_fee
from xrpl.models import Fee


async with AsyncWebsocketClient(url) as client:
    # using helper functions
    print(await get_fee(client))

    # using raw requests yourself
    print(await client.request(Fee()))
```

--------------------------------

### Get Imaginary Part of Complex Number

Source: https://github.com/xrplf/xrpl-py.git/blob/main/docs/source/xrpl.models.transactions.md

Retrieves the imaginary part of a complex number.

```python
the imaginary part of a complex number
```

--------------------------------

### Integer Methods and Properties

Source: https://github.com/xrplf/xrpl-py.git/blob/main/docs/source/xrpl.models.transactions.md

Documentation for built-in integer methods and properties.

```APIDOC
## Integer Methods and Properties

### `bit_count()`

Number of ones in the binary representation of the absolute value of self. Also known as the population count.

```pycon
>>> bin(13)
'0b1101'
>>> (13).bit_count()
3
```

### `bit_length()`

Number of bits necessary to represent self in binary.

```pycon
>>> bin(37)
'0b100101'
>>> (37).bit_length()
6
```

### `conjugate()`

Returns self, the complex conjugate of any int.

### `denominator`

The denominator of a rational number in lowest terms.

### `imag`

The imaginary part of a complex number.

### `numerator`

The numerator of a rational number in lowest terms.

### `real`

The real part of a complex number.

### `from_bytes(bytes, byteorder='big', signed=False)`

**Class Method**: Returns the integer represented by the given array of bytes.

**Parameters**:
- **bytes**: Holds the array of bytes to convert. The argument must either support the buffer protocol or be an iterable object producing bytes.
- **byteorder**: The byte order used to represent the integer. Defaults to 'big'. Can be 'big', 'little', or `sys.byteorder`.
- **signed**: Indicates whether two’s complement is used to represent the integer. Defaults to False.

### `to_bytes(length=1, byteorder='big', signed=False)`

Returns an array of bytes representing an integer.

**Parameters**:
- **length**: Length of bytes object to use. Defaults to 1.
- **byteorder**: The byte order used to represent the integer. Defaults to 'big'. Can be 'big', 'little', or `sys.byteorder`.
- **signed**: Determines whether two’s complement is used to represent the integer. Defaults to False.
```

--------------------------------

### title

Source: https://github.com/xrplf/xrpl-py.git/blob/main/docs/source/xrpl.models.requests.md

Returns a titlecased version of the string, where words start with an uppercase character and the rest are lowercase.

```APIDOC
## title()

### Description
Return a version of the string where each word is titlecased. More specifically, words start with uppercased characters and all remaining cased characters have lower case.

### Method
N/A (This is a string method, not an API endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### rpartition(sep,)

Source: https://github.com/xrplf/xrpl-py.git/blob/main/docs/source/xrpl.models.requests.md

Partitions the string into three parts using the given separator, starting from the end.

```APIDOC
## rpartition(sep,)

### Description
Partition the string into three parts using the given separator.

This will search for the separator in the string, starting at the end. If
the separator is found, returns a 3-tuple containing the part before the
separator, the separator itself, and the part after it.

If the separator is not found, returns a 3-tuple containing two empty strings
and the original string.
```

--------------------------------

### Get Rational Number Numerator

Source: https://github.com/xrplf/xrpl-py.git/blob/main/docs/source/xrpl.models.transactions.md

Retrieves the numerator of a rational number when expressed in its lowest terms.

```python
the numerator of a rational number in lowest terms
```

--------------------------------

### Get Rational Number Denominator

Source: https://github.com/xrplf/xrpl-py.git/blob/main/docs/source/xrpl.models.transactions.md

Retrieves the denominator of a rational number when expressed in its lowest terms.

```python
the denominator of a rational number in lowest terms
```

--------------------------------

### Convert String to Lowercase

Source: https://github.com/xrplf/xrpl-py.git/blob/main/docs/source/xrpl.models.requests.md

Use lower() to get a copy of the string with all characters converted to lowercase.

```python
string.lower()
```

--------------------------------

### Run integration tests

Source: https://github.com/xrplf/xrpl-py.git/blob/main/CONTRIBUTING.md

Executes integration tests for the project using Poetry, assuming an xrpld node is running.

```bash
poetry run poe test_integration
```

--------------------------------

### Static and Class Methods for OfferCreate

Source: https://github.com/xrplf/xrpl-py.git/blob/main/docs/source/xrpl.models.transactions.md

Static and class methods for creating and decoding OfferCreate transactions.

```APIDOC
## Static and Class Methods for OfferCreate

### from_blob(tx_blob: str)

Decodes a transaction blob.

* **Parameters:**
  **tx_blob** – the tx blob to decode.
* **Returns:**
  The formatted transaction.

### from_dict(value: Dict[str, Any])

Construct a new Transaction from a dictionary of parameters.

* **Parameters:**
  **value** – The value to construct the Transaction from.
* **Returns:**
  A new Transaction object, constructed using the given parameters.
* **Raises:**
  [**XRPLModelException**](xrpl.models.md#xrpl.models.exceptions.XRPLModelException) – If the dictionary provided is invalid.

### from_xrpl(value: str | Dict[str, Any])

Creates a Transaction object based on a JSON or JSON-string representation of data

In Payment transactions, the DeliverMax field is renamed to the Amount field.

* **Parameters:**
  **value** – The dictionary or JSON string to be instantiated.
* **Returns:**
  A Transaction object instantiated from the input.
* **Raises:**
  [**XRPLModelException**](xrpl.models.md#xrpl.models.exceptions.XRPLModelException) – If Payment transactions have different values for
      amount and deliver_max fields
```

--------------------------------

### Get Latest Validated Ledger Sequence

Source: https://github.com/xrplf/xrpl-py.git/blob/main/docs/source/xrpl.asyncio.ledger.md

Retrieves the sequence number of the latest validated ledger.

```APIDOC
## GET /ledger/get_latest_validated_ledger_sequence

### Description
Returns the sequence number of the latest validated ledger.

### Method
GET

### Endpoint
/ledger/get_latest_validated_ledger_sequence

### Parameters
#### Query Parameters
- **client** (Client) - Required - The network client to use to send the request.

### Response
#### Success Response (200)
- **sequence** (int) - The sequence number of the latest validated ledger.

#### Response Example
{
  "sequence": 12345677
}
```

--------------------------------

### Get Latest Open Ledger Sequence

Source: https://github.com/xrplf/xrpl-py.git/blob/main/docs/source/xrpl.asyncio.ledger.md

Retrieves the sequence number of the latest open ledger.

```APIDOC
## GET /ledger/get_latest_open_ledger_sequence

### Description
Returns the sequence number of the latest open ledger.

### Method
GET

### Endpoint
/ledger/get_latest_open_ledger_sequence

### Parameters
#### Query Parameters
- **client** (Client) - Required - The network client to use to send the request.

### Response
#### Success Response (200)
- **sequence** (int) - The sequence number of the latest open ledger.

#### Response Example
{
  "sequence": 12345678
}
```

--------------------------------

### Run unit tests

Source: https://github.com/xrplf/xrpl-py.git/blob/main/CONTRIBUTING.md

Executes all unit tests for the project using Poetry.

```bash
poetry run poe test_unit
```

--------------------------------

### Run faucet tests

Source: https://github.com/xrplf/xrpl-py.git/blob/main/CONTRIBUTING.md

Executes faucet-related tests for the project using Poetry.

```bash
poetry run poe test_faucet
```

--------------------------------

### Request Class Instance Methods

Source: https://github.com/xrplf/xrpl-py.git/blob/main/docs/source/xrpl.models.requests.md

Provides documentation for instance methods available in XRPL-Py Request models.

```APIDOC
## Instance Methods for Request Models

### `is_valid() -> bool`

#### Description
Returns whether this BaseModel is valid.

#### Returns
- bool - Whether this BaseModel is valid.

### `to_dict() -> Dict[str, Any]`

#### Description
Returns the dictionary representation of a Request.

#### Returns
- Dict[str, Any] - The dictionary representation of a Request.

### `validate() -> None`

#### Description
Raises if this object is invalid.

#### Raises
- XRPLModelException - if this object is invalid.
```

--------------------------------

### AMMInfo Request Model

Source: https://github.com/xrplf/xrpl-py.git/blob/main/docs/source/xrpl.models.requests.md

The AMMInfo method gets information about an Automated Market Maker (AMM) instance.

```APIDOC
## AMMInfo Request Model

### Description
The `amm_info` method gets information about an Automated Market Maker (AMM) instance.

### Method
POST

### Endpoint
`/` (websocket endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **method** (RequestMethod) - Required - Must be "amm_info".
- **id** (int | str | None) - Optional - An identifier for the request.
- **api_version** (int) - Optional - The API version to use. Defaults to 2.
- **amm_account** (str | None) - Optional - The address of the AMM pool to look up.
- **asset** (Currency | None) - Optional - One of the assets of the AMM pool to look up.
- **asset2** (Currency | None) - Optional - The other asset of the AMM pool.

### Request Example
```json
{
  "method": "amm_info",
  "params": [
    {
      "amm_account": "0x...",
      "asset": {"currency": "USD", "issuer": "..."},
      "asset2": {"currency": "BTC", "issuer": "..."}
    }
  ]
}
```

### Response
#### Success Response (200)
- **result** (dict) - The result of the AMM info query.
  - **amm** (dict) - Information about the AMM.
    - **account** (str) - The account ID of the AMM.
    - **amount** (str) - The amount of the first asset in the AMM pool.
    - **amount2** (str) - The amount of the second asset in the AMM pool.
    - **asset** (dict) - Details of the first asset.
    - **asset2** (dict) - Details of the second asset.
    - **balance** (str) - The balance of LP tokens.
    - **flags** (int) - Flags associated with the AMM.
    - **last_ledger_sequence** (int) - The last ledger sequence this AMM was updated in.
    - **ledger_entry_type** (str) - The type of ledger entry.
    - **owner_funds** (str) - The owner funds of the AMM.
    - **parent_id** (str) - The parent ID of the AMM.
    - **sequence** (int) - The sequence number of the AMM.
    - **trading_fee** (int) - The trading fee for the AMM.
  - **ledger_hash** (str) - The hash of the ledger.
  - **ledger_index** (int) - The index of the ledger.
  - **status** (str) - The status of the request.

#### Response Example
```json
{
  "result": {
    "amm": {
      "account": "0x...",
      "amount": "1000000",
      "amount2": "500000",
      "asset": {"currency": "USD", "issuer": "..."},
      "asset2": {"currency": "BTC", "issuer": "..."},
      "balance": "1000",
      "flags": 0,
      "last_ledger_sequence": 12345,
      "ledger_entry_type": "AMM",
      "owner_funds": "200000",
      "parent_id": "...",
      "sequence": 1,
      "trading_fee": 1000
    },
    "ledger_hash": "...",
    "ledger_index": 12345,
    "status": "success"
  },
  "id": 1,
  "version": 2
}
```
```

--------------------------------

### WebsocketClient Usage with Helper Functions and Raw Requests

Source: https://github.com/xrplf/xrpl-py.git/blob/main/docs/source/xrpl.clients.md

Demonstrates using WebsocketClient within a context manager for both helper functions like get_fee and raw client requests.

```python
from xrpl.clients import WebsocketClient
from xrpl.ledger import get_fee
from xrpl.models import Fee


with WebsocketClient(url) as client:
    # using helper functions
    print(get_fee(client))

    # using raw requests yourself
    print(client.request(Fee()))
```

--------------------------------

### Publish xrpl-py to PyPI

Source: https://github.com/xrplf/xrpl-py.git/blob/main/RELEASE.md

Publish the package to PyPI using 'poetry publish'. Ensure you have obtained a PyPI publishing token beforehand.

```bash
poetry publish
```

--------------------------------

### Get Transaction Hash

Source: https://github.com/xrplf/xrpl-py.git/blob/main/docs/source/xrpl.models.transactions.md

Hashes the Transaction object in the same way the ledger does. This method is only valid for signed Transaction objects.

```python
get_hash() → str
```

--------------------------------

### Wallet Properties and Methods

Source: https://github.com/xrplf/xrpl-py.git/blob/main/docs/source/xrpl.wallet.md

Accesses properties of the wallet such as its address and private key, and provides methods to get the X-Address.

```APIDOC
## Wallet Properties and Methods

### Property: `address`

#### Description
The XRPL address that publicly identifies this wallet, formatted as a base58 string. This is identical to the `classic_address`.

### Property: `algorithm`

#### Description
Indicates the cryptographic algorithm used to derive the public/private key pair from the seed.

### Property: `classic_address`

#### Description
An alias for the `address` property. It is named `classic_address` to distinguish it from the newer X-Address standard, which includes network information, a destination tag, and the XRPL address.

### Property: `private_key`

#### Description
The private key, represented as a hexadecimal string. This key is used for creating signatures and MUST be kept confidential.

### Method: `get_xaddress()`

#### Description
Retrieves the X-Address for the wallet's account.

#### Parameters
- **tag** (int | None) - Optional - The destination tag for the address. Defaults to `None`.
- **is_test** (bool) - Optional - Specifies whether the address belongs to the test network. Defaults to `False`.

#### Returns
- `str` - The X-Address of the wallet's account.
```

--------------------------------

### Get Latest Validated Ledger Sequence

Source: https://github.com/xrplf/xrpl-py.git/blob/main/docs/source/xrpl.ledger.md

Retrieves the sequence number of the latest validated ledger from the XRP Ledger.

```APIDOC
## GET /ledger/get_latest_validated_ledger_sequence

### Description
Returns the sequence number of the latest validated ledger.

### Method
GET

### Endpoint
/ledger/get_latest_validated_ledger_sequence

### Parameters
#### Query Parameters
- **client** (SyncClient) - Required - The network client to use to send the request.

### Response
#### Success Response (200)
- **sequence** (int) - The sequence number of the latest validated ledger.

### Error Handling
- **XRPLRequestFailureException** - if the rippled API call fails.
```

--------------------------------

### Run individual tests

Source: https://github.com/xrplf/xrpl-py.git/blob/main/CONTRIBUTING.md

Executes specific unit or integration tests by providing file paths.

```bash
# Works for single or multiple unit/integration tests
# Ex: poetry run poe test tests/unit/models/test_response.py tests/integration/transactions/test_account_delete.py
poetry run poe test FILE_PATHS
```
Tokens:
Raw