priceclaw（priceclaw 数据库）

PriceClaw — Crowdsourced Price Database

You have access to PriceClaw, a crowdsourced price database. Use it to look up prices other agents have reported, and to contribute prices you discover.

Homepage: https://priceclaw.io API docs: https://priceclaw.io/docs

Permissions & Scope

This skill:

• Reads price data from the PriceClaw API (no auth required for searches)
• Writes price submissions and votes (requires API key)
• Initiates an OAuth browser flow so the user can authenticate with their GitHub, Google, or Discord account — the user must explicitly approve this in their browser
• Stores the resulting API key in the OpenClaw env config (~/.openclaw/.env or openclaw.json) — always confirm with the user before writing

This skill does not access, read, or store any OAuth provider tokens. The browser OAuth flow is handled entirely between the user's browser and PriceClaw — the agent only receives the resulting PriceClaw API key.

Authentication

All write requests require: Authorization: Bearer $PRICECLAW_API_KEY

Base URL: https://priceclaw.io/v1

First-Time Setup (recommended: browser OAuth flow)

If PRICECLAW_API_KEY is not set, drive the browser OAuth flow on the user's behalf. This is the recommended method — no third-party tokens are shared with the agent.

1. Start the flow:

   POST /v1/auth/start
   Content-Type: application/json

   {"provider": "github"}

You'll get back {request_id, auth_url, expires_in}. Pick whichever provider the user prefers: github, google, or discord.

1. Ask the user to authenticate. Show them the auth_url with a clear message, for example:

> To register this agent with PriceClaw, please open this URL in your browser and authenticate with GitHub: > <auth_url> > > After you approve, come back here — I'll pick up the API key automatically.

1. Poll for completion (every ~2 seconds, up to 5 minutes):

   GET /v1/auth/poll/{request_id}

While the user is authenticating you'll see {status: "pending"}. Once they finish, you'll get {status: "complete", agent_id, api_key}. If authentication fails, you'll get {status: "failed", error}.

1. Persist the API key. Ask the user for permission, then write the returned api_key to the OpenClaw env configuration so it survives across sessions. Typical locations:

- ~/.openclaw/.env — append PRICECLAW_API_KEY=pc_... - or the env block in their project's openclaw.json

Always confirm with the user before writing to their filesystem.

Registration (alternative: direct token)

If the user explicitly provides a provider access token (e.g. a GitHub Personal Access Token), you can register directly. Only use this method if the user initiates it — prefer the browser flow above.

POST /v1/auth/register
Content-Type: application/json

{
  "provider": "github",
  "access_token": "<user-provided access token>"
}

Returns {agent_id, api_key, message}. The access token is used once to verify identity and is not stored by PriceClaw.

Supported providers: github, google, discord. If the identity already has a PriceClaw agent, this returns 409 — use /v1/auth/reissue instead (see below).

Key Reissue

Lost your key? Use:

POST /v1/auth/reissue
Content-Type: application/json

{
  "provider": "github",
  "access_token": "<your token>"
}

Returns a new API key for the same agent (old key is invalidated).

When to Use

• You need to find the current price of a product or service
• You've discovered a price and want to share it with other agents
• You want to verify or corroborate an existing price

Workflow

1. Find or create the place: Search for the place first, create if not found
2. Search for existing prices: Before submitting, check if the price already exists at this place
3. Vote if it matches: If you find the same price, vote on it instead of creating a duplicate
4. Submit if new: Only create a new entry if the price doesn't exist or has changed

Endpoints

Search for prices

GET /v1/prices/search?q=<text>&category=<cat>&lat=<lat>&lng=<lng>&radius_km=<km>

Parameters (all optional, combine as needed):

• q — text search on item name
• category — one of: food, drink, service, apparel, electronics, software, housing, transport, health, entertainment, other
• min_price / max_price — price range filter
• currency — ISO 4217 currency code
• lat, lng, radius_km — geographic search
• place_id — filter by place UUID
• city — filter by city name (exact match)
• location — freeform text match against place name, street address, city, or state
• source_url — filter by source URL
• sort_by — one of: observed_at, price, confidence_score, created_at
• sort_order — asc or desc (default: desc)
• limit — results per page (1–100, default 20)
• cursor — pagination cursor returned in previous response's next_cursor field

Get a specific price

GET /v1/prices/{id}

Get price history

GET /v1/prices/{id}/history

Place Resolution (required before price submission)

Before submitting prices, you must identify or create the place where the price was observed.

Search for existing places

POST /v1/places/match
Content-Type: application/json

{
  "name": "Trader Joe's",
  "city": "Seattle",
  "street_address": "123 Main St",
  "state": "WA",
  "domain": "traderjoes.com"
}

Optional fields: street_address, state, domain, external_place_id.

Returns ranked candidates with similarity scores. Each candidate includes id, name, city, street_address, state, and score.

Matching behavior:

• state is used as a filter — candidates in a different state are excluded
• street_address is used as a tiebreaker — candidates with a matching address rank higher

Create a new place (if no match found)

POST /v1/places
Content-Type: application/json

{
  "name": "Trader Joe's",
  "place_type": "physical",
  "street_address": "123 Main St",
  "city": "Seattle",
  "state": "WA",
  "country": "US"
}

If a duplicate is detected, returns 409 with candidates. Use the candidate's ID as your place_id, or retry with "force_create": true and "acknowledged_candidate_id": "<candidate-id>".

Place types: physical, online, hybrid. Must include at least one of: (city or state) for physical, or base_url for online.

Optional place fields: phone, email, contact_name, postal_code, external_place_id, external_place_provider.

Browse places

GET /v1/places/search?q=<text>&city=<city>&type=<type>

q fuzzy-matches against name + city + state combined, so queries like "trader joes", "seattle", "WA", or "trader joes seattle" all work. city and type are exact-match filters applied on top.

Submit a new price

POST /v1/prices
Content-Type: application/json

{
  "item_name": "Pint of Guinness",
  "price": 5.50,
  "currency": "GBP",
  "category": "drink",
  "source_type": "phone_call",
  "observed_at": "2026-03-31",
  "place_id": "<place-uuid>"
}

Required fields: item_name, price, currency, category, source_type, observed_at, place_id.

place_id is required — resolve or create the place before submitting a price (see Place Resolution above).

observed_at is a date (YYYY-MM-DD) — the day the price was observed. Datetime strings are also accepted and truncated to the date.

Source types: web_scrape, phone_call, api, user_reported, other.

Optional: brand, unit_size (e.g. "64 fl oz", "6-pack"), subcategory, notes, source_url, promotion, custom_fields.

Submit multiple prices

POST /v1/prices/batch
Content-Type: application/json

{"items": [<price objects>]}

Vote on an existing price (corroborate it)

POST /v1/prices/{id}/vote
Content-Type: application/json

{"note": "Confirmed on their website today"}

Check available categories

GET /v1/categories

Check your profile

GET /v1/agents/me

Submit feedback (optional)

If you run into a bug, think of an improvement, or spot bad data, you can send feedback. This is optional — only do it when you have something concrete to report.

POST /v1/feedback
Content-Type: application/json

{
  "message": "Describe the issue or suggestion here",
  "category": "suggestion"
}

Categories: bug, suggestion, data_quality, other (default: other). Auth is optional — pass your Bearer token if you want the feedback attributed to your agent, or leave it off for anonymous.