near-langchain-tx-builder

LangChain tools for building and simulating NEAR transactions before execution.

Features

• Build transfer transactions
• Build function-call transactions
• Batch multiple actions into one transaction
• Simulate transactions before sending (validation + account checks + optional RPC preflight)
• Estimate gas and rough transaction cost in NEAR
• Reusable transaction templates
• Clear, structured error messages

Install

pip install near-langchain-tx-builder

Quick Start (LangChain)

from near_langchain_tx_builder import get_near_transaction_tools

tools = get_near_transaction_tools()

# Tool names:
# - near_build_transfer_tx
# - near_build_function_call_tx
# - near_build_batch_tx
# - near_estimate_tx_gas
# - near_simulate_tx
# - near_apply_tx_template
# - near_list_tx_templates

Manual Usage

from near_langchain_tx_builder import NEARTransactionBuilder

builder = NEARTransactionBuilder()

tx = builder.build_transfer_tx(
    signer_id="alice.near",
    receiver_id="bob.near",
    amount_near="1.5",
    network="mainnet",
)

estimate = builder.estimate_gas(tx)
simulation = builder.simulate_transaction(tx, check_accounts=False)

Transaction Templates

Built-in templates:

• simple_transfer
• ft_transfer
• nft_transfer
• contract_call

Example:

tx = builder.apply_template(
    template_name="ft_transfer",
    signer_id="alice.near",
    receiver_id="usdc.fakes.testnet",
    variables={
        "method_name": "ft_transfer",
        "args": {"receiver_id": "bob.near", "amount": "1000000"},
        "deposit_near": "0.000000000000000000000001",
        "gas_tgas": 30,
    },
    network="testnet",
)

Error Handling

Methods raise NEARTxBuilderError with machine-readable codes:

• invalid_account_id
• invalid_amount
• invalid_action
• rpc_error
• simulation_error

Notes on Simulation

NEAR RPC does not provide a full dry-run for unsigned arbitrary state-changing transactions. This package simulates via:

• strict local validation,
• optional account existence checks,
• gas/cost estimation using RPC gas price,
• optional preflight call_function for likely view-compatible calls.

License

MIT

Reliability

• NEAR RPC fallback endpoints with retries/backoff
• Improved RPC error details for easier debugging
• CI workflow (tests + build)