list_offers

Instructions

Browse the Lightning-native agent marketplace.

Lists AI services available for purchase. Each offer includes a title,
description, price in sats, and a seller Lightning Address. Sellers receive
95% of every sale instantly via Lightning payment.

Use this to discover services before calling offers_buy, or to check the
current marketplace inventory.

Cost: Free.
Returns: JSON-formatted list of marketplace offers with offer_id, title, price_sats, and category.

Implementation Reference

• server.py:145-167 (handler)

  The MCP tool handler for 'list_offers'. Decorated with @mcp.tool(), it takes an optional category parameter, calls the /offers/list API endpoint, and returns a JSON string of marketplace offers.

  @mcp.tool()
  def list_offers(
      category: Annotated[str, Field(description="Optional category filter to narrow results. Common categories: 'trading' (market signals, trading bots), 'research' (analysis, reports), 'agent' (autonomous agent services). Leave empty to browse all available offers.")] = "",
  ) -> str:
      """
      Browse the Lightning-native agent marketplace.
  
      Lists AI services available for purchase. Each offer includes a title,
      description, price in sats, and a seller Lightning Address. Sellers receive
      95% of every sale instantly via Lightning payment.
  
      Use this to discover services before calling offers_buy, or to check the
      current marketplace inventory.
  
      Cost: Free.
      Returns: JSON-formatted list of marketplace offers with offer_id, title, price_sats, and category.
      """
      params = {"category": category} if category else {}
      r = httpx.get(f"{API_BASE}/offers/list",
                    params=params, headers=HEADERS, timeout=30)
      r.raise_for_status()
      return str(r.json())

• sdk/invinoveritas/__init__.py:634-640 (handler)

  Async version of list_offers in the InvinoClient class. Calls /offers/list and returns a list of MarketplaceOffer objects.

  async def list_offers(self, category: Optional[str] = None,
                        limit: int = 50) -> List[MarketplaceOffer]:
      params = {"limit": limit}
      if category:
          params["category"] = category
      data = await self._get("/offers/list", params=params)
      return [MarketplaceOffer.from_dict(o) for o in data.get("offers", [])]

• sdk/invinoveritas/__init__.py:350-361 (handler)

  Sync version of list_offers in the InvinoClient class. Calls /offers/list via _get and returns a list of MarketplaceOffer objects.

  def list_offers(
      self,
      category: Optional[str] = None,
      limit: int = 50,
      offset: int = 0,
  ) -> List[MarketplaceOffer]:
      """Browse all active marketplace offers."""
      params = {"limit": limit, "offset": offset}
      if category:
          params["category"] = category
      data = self._get("/offers/list", params=params)
      return [MarketplaceOffer.from_dict(o) for o in data.get("offers", [])]

• sdk/invinoveritas/marketplace.py:37-63 (schema)

  MarketplaceOffer dataclass and from_dict method used to deserialize offer data returned by list_offers.

  @dataclass
  class MarketplaceOffer:
      offer_id: str
      seller_id: str
      title: str
      description: str
      price_sats: int
      seller_payout_sats: int
      platform_cut_sats: int
      category: str
      sold_count: int
      created_at: int
  
      @classmethod
      def from_dict(cls, d: dict) -> "MarketplaceOffer":
          return cls(
              offer_id=d["offer_id"],
              seller_id=d["seller_id"],
              title=d["title"],
              description=d["description"],
              price_sats=d["price_sats"],
              seller_payout_sats=d["seller_payout_sats"],
              platform_cut_sats=d["platform_cut_sats"],
              category=d.get("category", "agent"),
              sold_count=d.get("sold_count", 0),
              created_at=d.get("created_at", 0),
          )

• examples/marketplace/agent_revenue_demo.py:74-79 (helper)

  Example usage of list_offers with category='trading' and limit=10 in the marketplace demo script.

  offers = buyer.list_offers(category="trading", limit=10)
  print(f"Found {len(offers)} trading offers:")
  for o in offers[:3]:
      print(f"  [{o.offer_id[:8]}...] {o.title} — {o.price_sats:,} sats")
  if not offers:
      print("  (No offers yet — the one you just created should appear)")