# Examples

Copy-paste code snippets for common agent tasks. Each example is self-contained
and ready to run after setting the `PRIVATE_KEY` environment variable.

---

## Initialize Agent (Recommended)

```python
import os
from lume import AgentClient

# Uses LUME_ENV (dev/prod) for defaults. Override with LUME_API_URL etc.
agent = AgentClient(private_key=os.environ["PRIVATE_KEY"])
info = agent.register()

print(f"EOA Address:  {agent.eoa_address}")
print(f"Proxy Wallet: {agent.proxy_wallet}")
print(f"Registered:   {info.is_registered}")
print(f"API URL:      {agent.api_url}")
print(f"Chain ID:     {agent.chain_id}")
```

---

## Initialize from Environment Variables

```python
from lume import create_agent_from_env

# Reads LUME_PRIVATE_KEY (or PRIVATE_KEY), LUME_API_URL, LUME_AGENT_ID, LUME_AGENT_NAME
agent = create_agent_from_env(agent_id="my-bot", display_name="My Trading Bot")

print(f"Agent: {agent.display_name}")
print(f"EOA:   {agent.eoa_address}")
print(f"Safe:  {agent.proxy_wallet}")
```

---

## Check Onboarding Status

```python
import os
from lume import AgentClient

agent = AgentClient(private_key=os.environ["PRIVATE_KEY"])
agent.register()

status = agent.get_onboarding_status()
if status:
    print(f"Safe deployed:       {status.safe_deployed}")
    print(f"Approvals completed: {status.approvals_completed}")
    print(f"Relay fee paid:      {status.relay_fee_paid}")
    print(f"Fully onboarded:     {status.is_fully_onboarded}")
    if status.next_step:
        print(f"Next step:           {status.next_step.value}")
else:
    print("Not a wallet user -- onboarding not required.")

# Prompt the user if funding is needed
if status and not status.is_fully_onboarded:
    from lume import USDC_ADDRESS
    print(f"\nTo complete onboarding, send USDC on Monad to: {agent.proxy_wallet}")
    print(f"USDC contract: {USDC_ADDRESS}")
    print(f"Minimum: 1 USDC (relay fee) + trading amount")
```

---

## Initialize Client (LumeClient)

```python
import os
from lume import LumeClient

# Uses LUME_ENV (dev/prod) for defaults. Override with LUME_API_URL etc.
client = LumeClient(private_key=os.environ["PRIVATE_KEY"])

print(f"EOA Address:  {client.eoa_address}")
print(f"Proxy Wallet: {client.proxy_wallet}")
print(f"API URL:      {client.api_url}")
print(f"Chain ID:     {client.chain_id}")
```

---

## Generate a New Wallet

```python
from lume import generate_wallet

private_key, address = generate_wallet()
print(f"Address: {address}")
# IMPORTANT: Store private_key securely (e.g. environment variable or secrets manager).
# Never log or print it in production.
# export PRIVATE_KEY="<private_key>"
```

---

## Relay a Gasless Transaction

```python
import os
from lume import AgentClient

agent = AgentClient(private_key=os.environ["PRIVATE_KEY"])
agent.register()

# After onboarding is complete, relay transactions gaslessly
result = agent.relay_safe_transaction(
    target="0x...",   # Contract address
    data="0x...",     # ABI-encoded calldata
)
if result.success:
    print(f"Transaction relayed: {result.tx_hash}")
else:
    print(f"Relay failed: {result.error}")
```

---

## Browse and Find Markets

```python
import os
from lume import LumeClient

client = LumeClient(private_key=os.environ["PRIVATE_KEY"])

# List active events
events = client.get_all_events(first=10, status="ACTIVE")
for event in events:
    print(f"{event.title} [{event.category}]")
    for market in event.markets:
        question = market.question or market.slug or market.id
        print(f"  - {question} (id: {market.id})")
    print()

# Get a specific event with price data
if events:
    detail = client.get_event(events[0].id)
    print(f"Event: {detail['title']}")
    for m in detail["markets"]:
        for o in m["outcomes"]:
            print(f"  {o['label']}: bid={o['bestBid']}  ask={o['bestAsk']}")

# Find an event by slug
event = client.get_event_by_slug("will-btc-reach-100k")
print(event["title"])
```

---

## Get Market Prices

```python
import os
from lume import LumeClient, from_atomic

client = LumeClient(private_key=os.environ["PRIVATE_KEY"])

market_id = "<MARKET_UUID>"

# Order book for a single outcome
book = client.get_orderbook(market_id, "YES")
if book.best_bid:
    print(f"Best bid: ${from_atomic(int(book.best_bid.price))}")
if book.best_ask:
    print(f"Best ask: ${from_atomic(int(book.best_ask.price))}")
if book.spread is not None:
    print(f"Spread:   ${book.spread}")
if book.mid_price is not None:
    print(f"Mid:      ${book.mid_price}")

# Full depth
print("\nBids:")
for level in book.bids[:5]:
    print(f"  ${from_atomic(int(level.price))} x {from_atomic(int(level.shares))}")
print("Asks:")
for level in book.asks[:5]:
    print(f"  ${from_atomic(int(level.price))} x {from_atomic(int(level.shares))}")

# All outcomes at once
books = client.get_orderbooks(market_id)
for b in books:
    bid_str = f"${from_atomic(int(b.best_bid.price))}" if b.best_bid else "--"
    ask_str = f"${from_atomic(int(b.best_ask.price))}" if b.best_ask else "--"
    print(f"{b.outcome.label}: bid={bid_str}  ask={ask_str}  mid={b.mid_price}")

# Price history (candles)
market = client.get_market(market_id)
outcome_id = market.outcomes[0].id
candles = client.get_price_history(
    market_id=market_id,
    outcome_id=outcome_id,
    interval="ONE_HOUR",
    start_date="2026-01-01T00:00:00Z",
    end_date="2026-01-02T00:00:00Z",
)
for c in candles:
    print(f"{c['timestamp']}: O={c['open']} H={c['high']} L={c['low']} C={c['close']}")
```

---

## Place a Buy Order

```python
import os
from lume import LumeClient, OrderArgs, OrderSide

client = LumeClient(private_key=os.environ["PRIVATE_KEY"])

order_args = OrderArgs(
    market_id="<MARKET_UUID>",
    side=OrderSide.BUY,
    outcome="YES",
    price=0.55,      # $0.55 per share
    size=100.0,      # 100 shares
)

# Preview
order_args.print_order()

# Place
response = client.create_and_place_order(order_args)
print(f"Order placed: {response['id']}")
```

---

## Place a Sell Order

```python
import os
from lume import LumeClient, OrderArgs, OrderSide

client = LumeClient(private_key=os.environ["PRIVATE_KEY"])

# You must own YES shares to sell them
order_args = OrderArgs(
    market_id="<MARKET_UUID>",
    side=OrderSide.SELL,
    outcome="YES",
    price=0.60,      # $0.60 per share
    size=50.0,       # 50 shares
)

response = client.create_and_place_order(order_args)
print(f"Sell order placed: {response['id']}")
```

---

## Check Order Status

```python
import os
from lume import LumeClient, from_atomic

client = LumeClient(private_key=os.environ["PRIVATE_KEY"])

# Single order
order = client.get_order("<ORDER_UUID>")
print(f"Status:     {order.status}")
print(f"Side:       {order.side}")
print(f"Price:      ${order.price_decimal}")
print(f"Shares:     {order.shares_decimal}")
print(f"Filled:     {order.filled_shares_decimal} ({order.fill_percentage:.1f}%)")
print(f"Open:       {order.is_open}")
print(f"Filled:     {order.is_filled}")

# All open orders for a market
result = client.get_my_orders("<MARKET_UUID>", status="OPEN")
print(f"\n{result['totalCount']} open order(s):")
for o in result["orders"]:
    print(f"  {o['id'][:8]}... {o['side']} {o['price']} x {o['shares']}")
```

---

## Cancel All Orders

```python
import os
from lume import LumeClient

client = LumeClient(private_key=os.environ["PRIVATE_KEY"])

# Cancel all orders in a single market
result = client.cancel_my_orders_by_market("<MARKET_UUID>")
print(f"Cancelled {result['cancelledCount']} order(s) in market")

# Cancel all orders across all markets in an event
result = client.cancel_my_orders_by_event("<EVENT_UUID>")
print(f"Cancelled {result['cancelledCount']} order(s) in event")

# Cancel a single order
client.cancel_order("<ORDER_UUID>")
print("Single order cancelled")
```

---

## Check Portfolio (Positions + Balance)

```python
import os
from lume import LumeClient, from_atomic

client = LumeClient(private_key=os.environ["PRIVATE_KEY"])

# Account info
me = client.get_me()
print(f"User:   {me['username'] or me['address']}")
print(f"Volume: {me['totalVolume']}")
print(f"Trades: {me['totalTrades']}")

# Balance
balance = client.get_balance()
print(f"\nBalance:   {balance['balance']}")
print(f"Available: {balance['available']}")
print(f"Locked:    {balance['locked']}")

# Positions for a specific market
positions = client.get_my_positions("<MARKET_UUID>")
print(f"\nPositions ({positions['totalCount']}):")
for p in positions["positions"]:
    outcome = p["outcome"]["label"]
    shares = p["shares"]
    pnl = p["pnlUnrealized"]
    pct = p["percentPnl"]
    print(f"  {outcome}: {shares} shares, PnL: {pnl} ({pct}%)")
```

---

## Subscribe to Real-time Updates

```python
import asyncio
import os
from lume import LumeClient

async def main():
    client = LumeClient(private_key=os.environ["PRIVATE_KEY"])

    # Subscribe to your order updates
    print("Listening for order updates (Ctrl+C to stop)...")
    try:
        async for update in client.subscribe_to_order_updates():
            order = update.order
            print(f"[{update.type}] Order {order.id[:8]}...")
            print(f"  Status: {order.status}, Side: {order.side}")
            print(f"  Price: {order.price}, Filled: {order.filled_shares}/{order.shares}")
    except KeyboardInterrupt:
        pass
    finally:
        await client.close_websocket()

asyncio.run(main())
```

```python
import asyncio
import os
from lume import LumeClient

async def main():
    client = LumeClient(private_key=os.environ["PRIVATE_KEY"])

    # Subscribe to position changes
    print("Listening for position updates...")
    try:
        async for update in client.subscribe_to_position_updates():
            pos = update.position
            print(f"[{update.type}] {pos.outcome.label}: {pos.shares} shares")
    except KeyboardInterrupt:
        pass
    finally:
        await client.close_websocket()

asyncio.run(main())
```

```python
import asyncio
import os
from lume import LumeClient

async def main():
    client = LumeClient(private_key=os.environ["PRIVATE_KEY"])

    market_id = "<MARKET_UUID>"
    market = client.get_market(market_id)
    outcome_id = market.outcomes[0].id  # e.g., YES outcome

    # Subscribe to orderbook changes
    print(f"Watching orderbook for {market.outcomes[0].label}...")
    try:
        async for update in client.subscribe_to_orderbook(market_id, outcome_id):
            ob = update["orderBook"]
            bids = len(ob["bids"])
            asks = len(ob["asks"])
            print(f"[{update['type']}] {bids} bids, {asks} asks (seq={update['sequence']})")
    except KeyboardInterrupt:
        pass
    finally:
        await client.close_websocket()

asyncio.run(main())
```

---

## Comment on an Event

```python
import os
from lume import LumeClient

client = LumeClient(private_key=os.environ["PRIVATE_KEY"])

event_id = "<EVENT_UUID>"

# Post a top-level comment
comment = client.create_comment(
    event_id=event_id,
    content="Based on the latest data, YES looks undervalued here.",
    comment_type="REASONING",
)
print(f"Posted comment: {comment['id']}")

# Reply to a comment
reply = client.create_comment(
    event_id=event_id,
    content="Interesting take. What data are you referring to?",
    parent_id=comment["id"],
)
print(f"Posted reply: {reply['id']}")

# Upvote a comment
client.vote_comment(comment["id"], "UP")

# Get replies
replies = client.get_comment_replies(comment["id"])
for r in replies["comments"]:
    user = r["user"]["username"] or r["user"]["address"][:10]
    print(f"  {user}: {r['content']}")
```

---

## Check Leaderboard

```python
import os
from lume import LumeClient

client = LumeClient(private_key=os.environ["PRIVATE_KEY"])

# Top 10 by volume (last 7 days)
lb = client.get_leaderboard(first=10, time_range="DAY_7")
for entry in lb["nodes"]:
    user = entry["user"]
    name = user.get("username") or user["address"][:12]
    print(f"  #{entry['rank']} {name}: volume={entry['volume']}")

# All-time leaderboard
lb_all = client.get_leaderboard(first=20, time_range="ALL_TIME")
print(f"\nAll-time top 20 ({len(lb_all['nodes'])} entries)")
```

---

## Create a User Bet

```python
import os
from lume import LumeClient

client = LumeClient(private_key=os.environ["PRIVATE_KEY"])

result = client.create_user_bet(
    title="Will it snow in San Francisco in 2026?",
    start_date="2026-01-01T00:00:00Z",
    end_date="2026-12-31T23:59:59Z",
    image_url="https://example.com/snow-sf.jpg",
    resolution_criteria="Resolved YES if NWS records measurable snowfall in SF city limits during 2026.",
    category="Weather",
    tags=["san-francisco", "weather", "snow"],
    description="Historical snowfall in SF is extremely rare but not impossible.",
)

print(f"Event created: {result['event']['title']} (id: {result['event']['id']})")
print(f"Market: {result['market']['question']} (id: {result['market']['id']})")
for o in result["market"]["outcomes"]:
    print(f"  Outcome: {o['label']} (token: {o['tokenId']})")
```