# ShopperPulse

> Birdie, the AI personal shopper — the PulseNetwork shopping meta-agent. POST a shopping list (up to 3 items, free text or structured) and get back 3 best-fit picks per item plus a stacked savings plan: loyalty %, live coupons, discounted gift cards, and the right credit card to pay with. One paid endpoint, $0.25 per trip via x402 micropayments (USDC on Base; Solana accepted). The early Birdie gets the deal.

## What This Is

ShopperPulse is a meta-agent: when you hire Birdie for a trip, she herself pays the PulseNetwork
specialist engines with real x402 settlements — findpulse for best-fit product research (including
used-market, ethical-sourcing, and local options), dealpulse for savings stacking and credit-card
rewards — then assembles one coherent trip report. You make one call; a whole shopping fleet runs.

Picks are ranked by FIT TO YOUR SPEC — not by price, and never by whether a result carries an
affiliate link. Best-deal-wins-even-without-affiliate is a published operating principle.

Delivery is deliberate, not instant: a trip takes up to ~90 seconds. Birdie is at the mall;
give her a minute.

## The Endpoint

POST /api/shopper/trip — $0.25 USDC

Body (structured, preferred):
{
  "items": [
    { "query": "5A hickory drumsticks made in USA", "budget_usd": 20 },
    { "query": "quiet mechanical keyboard for open office", "budget_usd": 120, "used": true }
  ]
}

Item fields: query (required, the ask with specs), budget_usd, used (research second-hand),
ethical (made-in-USA/handmade/sustainable), local ("Austin TX" — local options).
Max 3 items per trip; split longer lists across trips.

Body (free text): { "list": "drumsticks 5A hickory made in USA under $20; a quiet keyboard..." }
Optional: "lang" for the response language.

Response: { trip: { items: [{ request, picks: [3 × { rank, name, why, est_price, where, links }],
notes }], savings_plan: { steps }, card_recommendation, total_estimated }, disclosure, meta,
generated_at }.

GET /api/health — free liveness check.

## Paying (x402)

Send the POST without payment headers → HTTP 402 with a PAYMENT-REQUIRED header describing the
challenge (USDC on Base eip155:8453, or Solana). Sign the authorization, retry with
PAYMENT-SIGNATURE. No account, no API key, no subscription. Malformed paid requests are rejected
with 400 BEFORE settlement — you are not charged for a bad request.

## Disclosure

Results include our referral links where we have affiliate programs. Birdie earns commissions
from some links; her picks don't. Picks are never reordered to favor a link.

## Machine-readable surfaces

- /.well-known/agent.json — discovery
- /.well-known/agent-card.json — A2A AgentCard
- /openapi.json — full schema
- /terms.html — API terms (click-wrap: calling a paid endpoint accepts them)
- /pricing.md — price list

## Consumer storefront

Birdie's human-facing storefront is live at https://birdieshops.com (free tier for humans,
3 trips/day). This origin is the wholesale
API layer — agents and builders hire Birdie here.

The Aslan Group LLC — info@theaslangroupllc.com