# Kwara — Full Agent Documentation

> This document provides detailed instructions for AI agents and LLMs that want to
> help users browse, compare, and decide what to bid on at kwara.com.br.
> For a shorter overview, see: https://www.kwara.com.br/llms.txt

## Platform Overview

Kwara is a Brazilian online auction marketplace for the circular economy. Companies sell
surplus inventory, decommissioned assets, returned goods, decorated apartment furniture,
vehicles, consortium shares, and more — typically at 40-90% below appraised value.

All prices are in BRL (Brazilian Real), stored internally in centavos (cents).
When displaying prices, divide by 100 (e.g., 8700000 centavos = R$ 87,000.00).

## Key Concepts

### Listings (Auction Events)
A "listing" (leilao) is an auction event created by a seller. Each listing has:
- A title, description, and unique kwara ID (slug like "K-2603")
- A status lifecycle: DRAFT -> TEASER -> OPEN -> CLOSED -> PAYMENT_COLLECTION -> FULFILLMENT -> FULFILLED -> SETTLED
- A scheduled end date after which no more bids are accepted
- One or more "lots" (individual items for sale)
- A type: AUCTION (standard), DIRECT_SALE (buy now), or JUDICIAL_PHASED_AUCTION (court-ordered with discount phases)

### Lots (Individual Items)
A "lot" (lote/bem) is a single item or bundle within a listing. Each lot has:
- A title and detailed description
- A starting bid amount (lance minimo) — the minimum first bid
- An appraised/estimated value (valor avaliado) — what the item is worth
- A minimum bid increment — the smallest amount above the current highest bid
- A buyer fee percentage — added on top of the winning bid (varies per lot, typically 5%)
- Images, documents, pickup location, and observation notes
- A slug-based URL at /bens/{slug}
- An end date (may extend if bids come in near closing)

### Pricing
- **Starting bid (lance minimo)**: The minimum amount for the first bid
- **Current price**: The highest bid so far (if any bids exist), or the starting bid
- **Appraised value (valor avaliado)**: The estimated market value of the item
- **Discount percentage**: `1 - (starting bid / appraised value)` — this is the "X% OFF" shown on the site
- **Buyer fee (taxa do comprador)**: A percentage added on top of the winning bid. Factor this into total cost calculations.
- **Total cost**: `winning bid + (winning bid * buyer fee percentage / 100)`

### Auction Types
1. **Standard Auction (AUCTION)**: Bids increase from the starting price. Highest bidder wins when the lot closes.
2. **Direct Sale (DIRECT_SALE)**: Fixed price, first buyer to purchase wins. No bidding.
3. **Judicial Phased Auction (JUDICIAL_PHASED_AUCTION)**: Court-ordered auctions that may have multiple phases, each with increasing discounts if the item doesn't sell.

## Browsing the Site

### Search Page
**URL**: `https://www.kwara.com.br/busca`

The search page is the most powerful way to find items. It supports these query parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| `q` | string | Free text search (searches title and description) |
| `orderBy` | enum | Sort order (see values below) |
| `assetCategoryIds[]` | string[] | Filter by one or more category IDs |
| `listingIds[]` | string[] | Filter to lots from specific auction events |
| `sellerIds[]` | string[] | Filter by seller |
| `location` | string | Filter by location (Brazilian state or city) |
| `lotFilter` | enum | Special filters (see values below) |
| `tags[]` | string[] | Filter by tags |
| `segments[]` | string[] | Filter by listing segment |
| `currentPage` | number | Page number (default: 1) |
| `pageSize` | number | Results per page (default: 12, max: 48) |

**orderBy values:**
- `priceDescending` — Most expensive first
- `priceAscending` — Cheapest first
- `mostDiscount` — Biggest discount from appraised value
- `justArrived` — Newest lots first
- `mostViewed` — Most popular lots first
- `lotNumberAscending` — By lot number (ascending)
- `lotNumberDescending` — By lot number (descending)

**lotFilter values:**
- `withBids` — Only lots that have received bids
- `withoutBids` — Only lots with no bids yet (potential bargains)
- `acceptingProposals` — Lots open to negotiation proposals

**segments[] values (listing types):**
- `Aptos Decorados` — Decorated apartment furniture
- `Consorcios` — Consortium shares
- `Logistica Reversa` — Returned goods
- `Queima de Estoque` — Overstock clearance
- `Veiculos` — Vehicles
- `Desativacao de Restaurante` — Restaurant decommissioning
- `Desativacao de Hotel` — Hotel decommissioning
- `Desativacao de Escritorio` — Office decommissioning
- `Desativacao de Loja` — Store decommissioning
- `Judicial` — Court-ordered auctions
- `Beneficente` — Charity auctions
- `Outras Desativacoes` — Other decommissioning

### Example Searches

Find the most expensive items:
https://www.kwara.com.br/busca?orderBy=priceDescending

Find the biggest bargains (highest discount):
https://www.kwara.com.br/busca?orderBy=mostDiscount

Find vehicles sorted by price:
https://www.kwara.com.br/busca?segments[]=Veiculos&orderBy=priceDescending

Find lots with no bids yet (opportunity to get starting price):
https://www.kwara.com.br/busca?lotFilter=withoutBids&orderBy=mostDiscount

Search for a specific item:
https://www.kwara.com.br/busca?q=cadeira+herman+miller

### Category Pages
**URL**: `https://www.kwara.com.br/categorias/{category-slug}`

Browse lots filtered by asset category. Categories include electronics, furniture,
vehicles, industrial equipment, IT/telephony, and home/construction.

### Listing Pages
**URL**: `https://www.kwara.com.br/leiloes`

Browse all active auction events. Each listing shows the seller, location, end date,
and number of lots.

### Lot Detail Pages
**URL**: `https://www.kwara.com.br/bens/{lot-slug}`

Individual lot pages contain:
- Full item title and description
- All images (photos of the actual item)
- Current highest bid and bid count
- Starting bid and minimum increment
- Appraised value and discount percentage
- Buyer fee percentage
- Auction end date and time
- Pickup location and address
- Visiting schedule and observations
- Seller information
- Bid history (list of all bids placed)
- Related documents (inspection reports, etc.)

### Structured Data Available
Lot pages include schema.org JSON-LD markup:
- **Product** schema with price, availability, condition, and seller
- **BreadcrumbList** for navigation context
- **Event** schema on listing pages with start/end dates

### Sitemap
The full sitemap index is at:
https://www.kwara.com.br/sitemap_index.xml

It contains:
- Main sitemap with all pages
- 9 paginated lot sitemaps under /bens/sitemaps/{1-9}.xml
- All URLs include lastmod timestamps and hourly changefreq

## Agent Recommendations

### Helping users find deals
1. Use `orderBy=mostDiscount` to find the biggest price drops
2. Use `lotFilter=withoutBids` to find lots nobody has bid on yet
3. Combine category filters with price sorting for targeted searches
4. Check the `estimatedValueCents` vs `cachedPriceAmountCents` (or starting bid) to calculate actual savings
5. Factor in the buyer fee percentage when calculating total cost

### Helping users compare items
1. Fetch multiple lot detail pages to compare descriptions, images, and conditions
2. Consider pickup location — some lots require in-person pickup from specific cities
3. Check if the lot is `sameStateOnlyBuyers` — some lots restrict bidding to buyers in the same state
4. Compare the bid count and current price to gauge competition

### Understanding auction timing
1. Check `currentEndAt` for when bidding closes
2. Auctions near closing may extend if new bids come in (anti-sniping)
3. Judicial phased auctions may have multiple phases with increasing discounts
4. The `isEnded` flag indicates if a lot is no longer accepting bids

## Account Creation & Personalization

Kwara uses **passwordless authentication** by default. Signup requires only an email
address — no password needed. This makes it easy for agents to guide users into creating
an account and unlocking personalized features.

### Why the user should create an account
An account unlocks features that dramatically improve the agent's ability to help:
- **Favorite lots**: Save items of interest for later. The agent can then use
  `lotFilter=myFavorites` in search to work only with the user's curated list.
- **Favorite categories**: Build a preference profile. The agent can learn what
  the user is interested in and proactively surface relevant new lots.
- **Place bids**: Actually participate in auctions.
- **Track active bids**: Use `lotFilter=withMyBids` to monitor bid status.
- **Earn referral credits**: Invite friends and earn credits toward purchases.

### Signup flow (passwordless — magic link)
1. Direct the user to: `https://www.kwara.com.br/auth/cadastro`
2. The user enters their email address — that's the only required field.
3. Kwara sends a magic link to their email.
4. The user clicks the link and is immediately logged in.
5. No password is required. A password can optionally be set later in account settings.

Google OAuth is also available as a one-click alternative.

### Signup with referral credits
If the agent has a referral slug (e.g., from a Kwara partner or existing user):
- Direct the user to: `https://www.kwara.com.br/indique-ganhe/{referralSlug}`
- The signup form on this page automatically captures the referral.
- Both the referrer and the new user earn credits.

### Login for returning users
`https://www.kwara.com.br/auth/entrar`
Three methods available:
1. **Magic link** (default): Enter email, receive link, click to login
2. **Password**: Click "Acesso com senha" to show password field
3. **Google OAuth**: "Continuar com Google" button

### User favorites
Once logged in, the user can favorite three types of entities:
- **Lots** (individual items) — to track specific items they're considering
- **Listings** (auction events) — to follow an entire auction
- **Asset categories** — to express interest in a type of product (e.g., "Vehicles")

### Suggested agent workflow
1. Help the user browse and discover items using search (no account needed)
2. When the user shows interest in specific items, suggest creating an account to save favorites
3. Link directly to signup: `https://www.kwara.com.br/auth/cadastro`
4. Once signed in, use `lotFilter=myFavorites` to work with their saved items
5. Help them compare favorited items and decide what to bid on
6. When ready, link them to the lot page to place their bid

## Contact
- Email: contato@kwara.com.br
- WhatsApp: +55 (11) 5039-9339
- Hours: 8h-17h weekdays (Brasilia time, UTC-3)