---
name: rtie-agentic-commerce
description: Build AI agents that browse listings, monitor live auctions, place bids, and execute buy-now checkout on RTIE's agentic commerce layer.
version: "0.1.0"
---

# RTIE Agentic Commerce

RTIE's agentic commerce layer lets AI agents participate in live auctions, place bids, and execute purchases — always with human-in-the-loop confirmation for financial actions.

This is part of the **agentic AI primitive** in RTIE. It works across vAuction verticals and any operator tenant that enables the `auctions` module.

## Available MCP tools (vertical-bundle — requires operator workspace)

| Tool | Purpose | Confirmation required |
|---|---|---|
| `listing_browse` | Browse active listings | No |
| `listing_get` | Get listing details | No |
| `auction_list_live` | Live auctions with real-time prices | No |
| `auction_get_high_bid` | Current high bid on a listing | No |
| `auction_place_bid` | Place a bid | **Yes — human confirmation** |
| `listing_buy_now` | Buy-now checkout | **Yes — human confirmation** |

## Browsing listings

```typescript
// MCP: listing_browse
// Filter by auction mode and limit results
await mcp.callTool("listing_browse", {
  mode: "live_auction",   // "fixed" | "timed_auction" | "live_auction"
  limit: 20,
});
// → [{ listing_id, title, current_price_cents, ends_at, ... }, ...]

// MCP: listing_get
await mcp.callTool("listing_get", { listing_id: "lst_abc123" });
// → { listing_id, title, description, current_price_cents, buy_now_price_cents, ... }
```

## Monitoring a live auction

```typescript
// Get current high bid
await mcp.callTool("auction_get_high_bid", { listing_id: "lst_abc123" });
// → { amount_cents: 5000, bidder_id: "usr_xyz", bid_at: "2026-06-11T..." }

// Watch all live auctions (returns snapshot — poll or use presence subscription)
await mcp.callTool("auction_list_live");
// → [{ listing_id, title, current_price_cents, bidder_count, ends_in_seconds }, ...]
```

## Placing a bid (requires human confirmation)

The `auction_place_bid` MCP tool is annotated with `requiresHumanConfirmation: true`. The MCP client (Claude Code, Cursor, etc.) must pause and ask the user before executing.

```typescript
// MCP: auction_place_bid
await mcp.callTool("auction_place_bid", {
  listing_id: "lst_abc123",
  amount_cents: 5500,        // bid in cents
});
// Returns:
// { success: true, bid_id: "bid_xyz", new_high_bid_cents: 5500 }
// or:
// { success: false, reason: "outbid", current_high_cents: 5600 }
```

**Agent pattern** — bid strategy loop:

```
1. auction_get_high_bid → get current price
2. If price < max_budget: auction_place_bid (with human confirmation)
3. If outbid: re-evaluate (agent decides whether to re-bid)
4. If auction closes: check result via get_winning_bid
```

## Buy-now checkout (requires human confirmation)

```typescript
// MCP: listing_buy_now
await mcp.callTool("listing_buy_now", {
  listing_id: "lst_abc123",
});
// → { checkout_url: "https://checkout.vauction.ai/..." }
// Redirect user to checkout_url to complete payment
```

## Managing auctions (operator/seller tools)

These tools are used by agents acting on behalf of sellers/operators:

```typescript
// Create an auction
await mcp.callTool("create_auction", {
  title: "Vintage Baseball Card — Mickey Mantle 1952",
  roomId: "room_xyz",         // optional: link to a live room
  starting_price_cents: 10000,
  reserve_price_cents: 50000,
});

// Open bidding
await mcp.callTool("start_auction", { auctionId: "auc_abc" });

// Close and resolve winner
await mcp.callTool("close_auction", { auctionId: "auc_abc" });  // destructive

// Get winning bid
await mcp.callTool("get_winning_bid", { auctionId: "auc_abc" });
// → { bidder_id, amount_cents, won_at }
```

## SDK usage (backend servers)

```typescript
import { createClient } from "@rtie/sdk";

const rtie = createClient({ apiKey: process.env.RTIE_API_KEY! });

// Browse
const listings = await rtie.listings.browse({ mode: "live_auction" });

// Place bid (server-side, no human confirmation required here)
const result = await rtie.auctions.placeBid(listingId, {
  amountCents: 5500,
  bidderId: "usr_abc123",     // server must validate authorization
});
```

## Action Engine integration

Pair auctions with the Action Engine to run bid-velocity rules:

```json
{
  "name": "Boost engagement when bidding slows",
  "signalType": "bid_velocity",
  "conditions": [{ "field": "payload.bids_per_minute", "op": "lt", "value": 2 }],
  "actionType": "ui_event",
  "actionConfig": { "event": "show_scarcity_nudge", "target": "room" }
}
```

Full docs: https://docs.rtie.ai/modules/auctions