barter-sdk 1.0.2

[ B A R T E R ]
barter-sdk — Python SDK for the Proof of Trade Protocol

What is Barter?

Credit scores exist for fiat. Barter builds the equivalent for crypto wallets — but instead of trusting a central authority, every score point comes from a real, cryptographically verified trade settled on the Bitcoin Lightning Network.

When two parties complete a trade, the Lightning payment reveals a SHA256 preimage. That preimage is submitted on-chain as irrefutable proof. The smart contract verifies it, updates both parties' soulbound trust scores, and mints BTR-Credit reward tokens. No fake reviews, no self-attestation, no gaming — just math and commerce.

This SDK lets you read trust scores, execute trades, check compliance flags, and build applications on top of Barter — all in Python.

Install

pip install barter-sdk

That's it. Python 3.8+ required.

Try It in 30 Seconds

import btr

# Connect to the protocol (read-only, no keys needed)
client = btr.BarterClient(network="sepolia")

# Look up any wallet's trust score
score = client.trust.get_score("0x742d35Cc6634C0532925a3b844Bc9e7595f3F9a0")
print(f"Trust score: {score}")

# Get full trust profile
profile = client.trust.get_profile("0x742d35Cc6634C0532925a3b844Bc9e7595f3F9a0")
print(f"Score: {profile.score}")
print(f"Trades completed: {profile.trade_count}")
print(f"Unique counterparties: {profile.unique_counterparties}")
print(f"Completion rate: {profile.completion_rate}%")

# Run compliance analysis — detect wash trading, velocity anomalies, isolation
report = client.compliance.full_report("0x742d35Cc6634C0532925a3b844Bc9e7595f3F9a0")
print(f"Risk level: {report.risk_level}")
print(f"Flags: {report.flags}")
print(f"24h velocity: {report.velocity.trades_24h} trades")
print(f"Network isolation: {report.cluster.isolation_score}")

Output:

Trust score: 347
Score: 347
Trades completed: 18
Unique counterparties: 12
Completion rate: 94.2%
Risk level: low
Flags: []
24h velocity: 0 trades
Network isolation: 0.0

Use Cases

1. Marketplace trust gating

Gate access to high-value listings based on seller reputation:

import btr

client = btr.BarterClient()

def can_list_premium(seller_address: str) -> bool:
    """Only allow sellers with score >= 200 and 5+ counterparties."""
    profile = client.trust.get_profile(seller_address)
    return profile.score >= 200 and profile.unique_counterparties >= 5

# Check before allowing a listing
if can_list_premium("0xSellerAddress..."):
    print("Approved for premium listings")
else:
    print("Build more trade history first")

2. Counterparty screening before settlement

Screen a counterparty for anomalies before agreeing to trade:

import btr

client = btr.BarterClient()

def screen_counterparty(address: str) -> dict:
    """Run full compliance check before accepting a trade."""
    report = client.compliance.full_report(address)

    return {
        "address": address,
        "risk_level": report.risk_level,
        "flags": [str(f) for f in report.flags],
        "velocity_elevated": report.velocity.is_elevated,
        "isolation_score": report.cluster.isolation_score,
        "recommendation": "BLOCK" if report.risk_level == "high" else "PROCEED",
    }

result = screen_counterparty("0xSuspiciousWallet...")
print(result)
# {'address': '0x...', 'risk_level': 'high', 'flags': ['High velocity: 11 tx/day',
#  'Isolated: only 2 counterparties'], 'recommendation': 'BLOCK'}

3. Execute a full trade lifecycle

Propose, accept, and settle a trade — end to end:

import os
import btr

# Write operations need a private key
client = btr.BarterClient(
    rpc_url=os.environ["ALCHEMY_RPC_URL"],
    private_key=os.environ["DEPLOYER_PRIVATE_KEY"],
)

# Step 1: Propose a trade with a Lightning payment hash
trade_id = client.trade.propose(
    counterparty="0xCounterpartyAddress...",
    payment_hash="0xabc123...def456",  # SHA256 hash of the Lightning preimage
    amount_sats=50_000,
    category="digital-goods",
    description="Logo design commission",
)
print(f"Trade proposed: {trade_id}")

# Step 2: Counterparty accepts the trade
receipt = client.trade.accept(trade_id)
print(f"Accepted in block {receipt['blockNumber']}")

# Step 3: After Lightning payment settles, submit the preimage
receipt = client.trade.settle(trade_id, preimage="0xdeadbeef...")
print(f"Settled in block {receipt['blockNumber']}")
# Both parties' BTR-Trust scores increase, BTR-Credit tokens minted

4. Analytics dashboard — trade network visualization

import btr

client = btr.BarterClient()

def wallet_summary(address: str) -> dict:
    """Build a dashboard-ready summary for any wallet."""
    profile = client.trust.get_profile(address)
    compliance = client.compliance.full_report(address)
    credit = client.credit.balance_of(address)
    trades = client.trade.list_by_address(address)

    return {
        "address": address,
        "score": profile.score,
        "level": "A" if profile.score >= 700 else "B" if profile.score >= 400 else "C",
        "trades": len(trades),
        "completion_rate": f"{profile.completion_rate}%",
        "counterparties": profile.unique_counterparties,
        "btr_credit": credit,
        "risk": compliance.risk_level,
        "flags": len(compliance.flags),
    }

Architecture

Your App
  │
  ▼
btr.BarterClient
  ├── client.trust       → BTR-Trust (Soulbound ERC-721/5192) — scores, profiles
  ├── client.trade       → BarterCore — propose, accept, settle, dispute
  ├── client.credit      → BTR-Credit (ERC-20) — balances, rewards
  └── client.compliance  → On-chain analysis — velocity, isolation, flags
          │
          ▼
    Ethereum Sepolia (via Web3.py + Alchemy/Infura RPC)
          │
          ▼
    Bitcoin Lightning Network (payment settlement layer)

API Reference

Client

import btr

client = btr.BarterClient(
    rpc_url="https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY",  # optional
    network="sepolia",                                          # default
    private_key="0x...",                                        # for write ops
)

Read-only operations (scores, profiles, balances, compliance) need no private key. Write operations (propose, accept, settle, dispute) require a private key.

Trust — client.trust

TrustProfile fields:

class TrustProfile:
    address: str
    score: int                        # Soulbound trust score
    unique_counterparties: int        # Distinct addresses traded with
    member_since: datetime | None     # First trade timestamp
    trade_count: int                  # Total trades
    completion_rate: float            # % of trades successfully settled
    last_trade_at: datetime | None    # Most recent trade

Trade — client.trade

Trade lifecycle:

[ Proposed ] → [ Accepted ] → [ Settled ]  ← preimage submitted
     │              │
     │              └→ [ Disputed ]
     │
     └→ [ Expired ]  (after 7 days)

Trade fields:

class Trade:
    trade_id: str
    party_a: str               # Proposer
    party_b: str               # Counterparty
    payment_hash: str          # SHA256 hash for HTLC verification
    amount_sats: int           # Trade amount in satoshis
    category: str              # goods, services, labor, digital, financial
    description: str           # Human-readable description
    status: TradeStatus        # proposed | accepted | settled | disputed | expired
    created_at: datetime
    settled_at: datetime | None

Credit — client.credit

BTR-Credit is minted automatically when trades settle. Amount = min(10000, max(1, sats / 1000)).

Compliance — client.compliance

What gets flagged:

ComplianceReport fields:

class ComplianceReport:
    address: str
    flags: list[AnomalyFlag]
    velocity: VelocityReport
    cluster: ClusterReport
    risk_level: str            # "low" | "medium" | "high"
    generated_at: datetime

Error Handling

All SDK-specific errors inherit from btr.BarterError:

import btr

try:
    client.trade.propose(
        counterparty="not-a-valid-address",
        payment_hash="0xabc",
        amount_sats=500,  # below 1000 minimum
    )
except btr.InvalidAddressError:
    print("Bad address format")
except btr.InsufficientAmountError:
    print("Minimum trade is 1,000 sats")
except btr.SelfTradeError:
    print("Cannot trade with yourself")
except btr.PreimageMismatchError:
    print("SHA256(preimage) doesn't match payment hash")
except btr.BarterError as e:
    print(f"Protocol error: {e}")

Smart Contracts

The SDK interacts with three contracts deployed on Ethereum Sepolia:

Key protocol parameters:

Configuration

Environment variables

Using a .env file

# .env
ALCHEMY_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/your-key
DEPLOYER_PRIVATE_KEY=0xYourPrivateKey

from dotenv import load_dotenv
load_dotenv()

import btr
client = btr.BarterClient()  # picks up env vars automatically

Links

• GitHub: github.com/TheBarmaEffect/barter-protocol
• Live Frontend: thebarmaeffect.github.io/barter-protocol
• PyPI: pypi.org/project/barter-sdk
• Smart Contracts: contracts/
• JS/TS SDK: @thebarmaeffect/barter-sdk
• React SDK: @thebarmaeffect/barter-react

License

MIT