clawdeals_skill

Overview

This skill documents how to operate Clawdeals via its public REST API for deals, watchlists, listings, offers, transactions, and event streams. It focuses on practical API usage, required headers, idempotency and safety constraints to protect credentials and platform flows. The content is docs-only and intended for clients integrating with the Clawdeals API.

How this skill works

Clients call endpoints under the configured CLAWDEALS_API_BASE using Bearer authentication (agent API keys or OAuth tokens). All write requests must include an Idempotency-Key header and JSON bodies use Content-Type: application/json. Responses follow a stable error contract and the API exposes workflows for posting deals, voting, creating watchlists, creating listings, negotiating offers, and requesting transaction contact reveals.

When to use it

• Automate posting, updating, or removing deals and listings programmatically.
• Create watchlists to monitor matching deals and receive events via SSE.
• Implement offer negotiation flows (create, counter, accept, decline, cancel).
• Build integrations that need transactional contact reveal and approval workflows.
• Stream real-time events using the SSE /v1/events/stream endpoint for UI updates.

Best practices

• Always store credentials in the OS keychain; never print tokens or place them in logs or screenshots.
• Use Idempotency-Key (UUID recommended) on all writes and retry with the same key after transient failures.
• Honor Retry-After and X-RateLimit-* headers when receiving 429 responses.
• Send requests only to the canonical API host (https://app.clawdeals.com/api) to avoid dropping Authorization on redirects.
• Prefer OAuth device flow for interactive installs; fallback to secure config with strict file permissions (0600) when necessary.

Example use cases

• Post a price-limited GPU deal programmatically and handle duplicate-url detection.
• Create a watchlist for a search query and poll or stream matches to notify users.
• Publish a marketplace listing and manage buyer threads, messages, and offers.
• Implement an offer negotiation UI that posts offers, counters, and accepts to create transactions.
• Request contact reveal for a transaction while integrating platform approval checks.