# Cashback for agents

> Give your AI agent a tracked link and a wallet. It shops, the cashback attaches to your account, and you approve every payout.

**Concept API. The endpoints, package and keys described here are illustrative. Nothing here is live.**

- Base URL: https://api.dotrewards.demo
- MCP package: @dotrewards/mcp
- HTML page: https://dotrewards.xyz/agents

## Quickstart

1. **Link your agent.** In your account, open Settings → Agents and approve a new agent. You choose its scopes and a spending cap, and get a revocable key.
2. **Add the MCP server.** Point any MCP client at the package (npx -y @dotrewards/mcp) or paste the config below. No SDK to install.
3. **Ask your agent to shop.** The agent calls create_cashback_link before it checks out. Cashback tracks to you automatically.

## MCP server

Works with Claude, ChatGPT, Cursor and any client that speaks MCP. Add the `dotrewards` server to your client's config:

```json
{
  "mcpServers": {
    "dotrewards": {
      "command": "npx",
      "args": ["-y", "@dotrewards/mcp"],
      "env": {
        "DOTREWARDS_API_KEY": "drk_test_…"
      }
    }
  }
}
```

### Tools

- `search_stores({ query, category? })`: Find stores by name, category or shopping intent. Each result carries the current rate and an agent_ready flag.
- `get_rate({ merchant })`: Current cashback rate for one merchant, including any upsized offer.
- `create_cashback_link({ merchant, intent? })`: Returns a tracked link. Cashback attaches to the user who linked the agent.
- `get_wallet()`: Read-only balance, pending cashback and the per-agent ledger. There is no withdraw tool.

## REST API

Not using MCP? Call the same endpoints directly. Base URL `https://api.dotrewards.demo`, authenticated with your agent key as a bearer token.

- `POST /v1/links`: Create a tracked cashback link
- `GET /v1/stores`: Search stores and rates
- `GET /v1/rates/{merchant}`: Current rate for one merchant
- `GET /v1/wallet`: Balance and per-agent ledger

Request:

```bash
curl -X POST https://api.dotrewards.demo/v1/links \
  -H "Authorization: Bearer $DOTREWARDS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant": "booking-com",
    "intent": "hotel"
  }'
```

Response:

```json
{
  "id": "lnk_8f3a2c",
  "url": "https://drw.ds/l/…",
  "merchant": "booking-com",
  "rate": "Up to 7%",
  "tracked_for": "usr_demo",
  "agent": "agt_travel_bot"
}
```

## Webhooks

Each request carries a `Dotrewards-Signature` header, an HMAC-SHA256 of the raw body.

- `cashback.tracked`: The merchant reported an order made through your link. Cashback is pending.
- `cashback.confirmed`: The order cleared the return window. Cashback is payable, with your approval.

## Agent wallet

- Every agent gets its own spend and cashback ledger, plus a monthly cap you set.
- Agents can read the wallet. Only you can withdraw from it.
- Spending caps: links stop being issued once the cap is reached.
- You approve payouts: withdrawals need your sign-off in the app.

## FAQ

**Who gets the cashback?** You do. Every link is tied to the person who approved the agent (the tracked_for field). Cashback is credited to that person's account, never to the agent or the developer who built it.

**Can agents withdraw?** No. An agent key can create links and read the wallet. There is no withdraw tool or endpoint, and payouts only move after you approve them in the app.

**Which stores work with agents?** Stores flagged agent-ready accept tracked purchases started through the API or MCP. In this demo that is 18 stores, and search_stores returns an agent_ready flag for each. Browse them on the stores page.

**How does attribution work?** create_cashback_link returns a short URL carrying a click ID tied to your user and the calling agent. When the agent checks out through it, the merchant reports the order (cashback.tracked) and later confirms it once the return window closes (cashback.confirmed).

**Is it free?** In this concept, yes. Linking an agent costs nothing, and cashback is a share of the commission merchants already pay for referred sales.

---

Concept demo. Store names and logos belong to their respective owners. Cashback rates shown are illustrative only.