---
name: recon-audiences
description: Use for buying a downloadable B2B contact audience from Recon without a Bellaso account — quote a selection, get the buyer's approval at the charge ceiling through Link/Stripe SPT funding, pay, poll, and deliver the CSV and JSON files to the buyer.
---

# Recon audiences — account-free B2B purchase

This skill describes the public guest-purchase protocol any agent can run. The companion client
implements it: `node client.mjs` (same directory as this file). Full protocol reference:
https://www.bellaso.ai/docs/recon-audiences · API base: `https://recon.bellaso.ai` · OpenAPI:
`https://recon.bellaso.ai/openapi.json`

## What a purchase is

A guest purchase needs no Recon signup or manual API key. Each purchase has a private order and
payment record. The agent holds a locally generated secret for private access; the buyer approves
payment through their wallet. The deliverable is a CSV and a JSON file of up to 50 professional contacts.

## The protocol

1. **Discover** — `GET /v1/audiences` returns the offer: schema version, the intake flag, limits,
   bundles, and the current terms version. If `enabled` is false or the endpoint is unreachable,
   purchasing is closed — stop and say so; never substitute a signup.
2. **Quote** — `POST /v1/audiences/quotes` with `targeting`, `bundles` (professional is required;
   `emails` and `phones` optional), and `max_contacts` (1–50). The reply is public data only: real
   candidate count, itemized price lines, one charge ceiling, a 60-minute expiry, the terms version
   and digest. Quotes are free and contain no PII.
3. **Approve** — the buyer approves at most the quoted ceiling through supported Link/Stripe SPT
   funding. The agent never approves on its own, and an arbitrary Stripe account balance is not a
   funding source here.
   First-release rates are 2 cents per delivered professional profile, plus 3 cents for
   company-domain emails and 5 cents for work phones per contact when delivered. The minimum
   order is 50 cents; do not round a smaller selection up to a fee.
4. **Pay and poll** — `POST /v1/audiences/orders` carries the quote ID, the accepted terms version
   and digest, the owner verifier, and `authority: "buyer_delegated"`. Without funding it answers
   HTTP 402. Poll `GET /v1/audiences/orders/{order_id}` until it delivers or definitively fails.
   Fulfillment has a 6-hour deadline. Failure creates a full-refund obligation; provider processing
   can leave that refund pending. Only confirmed successful refunds are settled.
5. **Download** — `GET /v1/audiences/orders/{order_id}/download?format=csv` and `?format=json`.
   Files are generated in memory, re-authorized on every read, available up to 7 days,
   and capped at 20 downloads per order. There is no public or presigned file URL.
   CSV contact-channel cells contain aligned JSON arrays; every phone retains its own DNC flag.
   Missing data at fulfillment refunds automatically. New opt-outs after the order is ready
   are withheld from later downloads without an additional refund.

## Running the client

Requires Node 20+ and Stripe’s Link CLI (`npm install -g @stripe/link-cli`).
Connect the buyer’s Link account with `link-cli auth login`, using the official browser
authorization flow, before buying. Recon does not need the buyer’s Stripe API key.

Download both `client.mjs` and `client-support.mjs` from
`https://www.bellaso.ai/agent/recon-audiences/` into the same local directory.
The support module owns private journaling and file validation; no npm dependencies are required.

- Default is **quote-only**: `node client.mjs --selection selection.json` fetches a quote and
  prints it (JSONL, `phase: "quote"`). Nothing is charged and no Link call or state file is made.
- Purchasing requires an explicit action and a buyer-approved cap:
  `node client.mjs --selection selection.json --quote-id <quote_id> --purchase --max-cents <cents>`.
  Use `--quote-id` for a quote selected in the UI; it reads that exact quote without creating
  another. Omit it only when the buyer has asked the agent to prepare a new selection.
  The client verifies the quote, persists a mode-0600 state file
  (`recon-audience-order-<quote_id>.state.json`, or `--state <path>`) BEFORE any payment attempt,
  then pays through `link-cli mpp pay`. There is no automatic approval — on `approval_pending`
  the client prints only the allowlisted `https://app.link.com/activity/approve/lsrq_*` URL and
  spend-request ID; the buyer approves in Link, then the agent resumes the SAME request:
  `node client.mjs --resume --state <state-file> [--wait seconds]`.
- The owner secret stays local: generated on the buyer's machine, held only in the state file
  and the in-memory `X-Recon-Order-Secret` header — never in argv, URLs, prompts, logs, or
  output. Only the owner *verifier* appears in the order body passed to Link.
- Client output is an allowlisted quote/approval/order/status/download shape — never raw SPT
  material, provider output, payment tokens, or the owner secret.
- On delivery the client writes `recon-audience-<order_id>.csv` and `.json` into `--out <dir>`
  (default: working directory) and reports sanitized paths, row counts, and SHA-256 hashes.
- Test-only flags: `--link-cli <path>` selects a different executable; `--link-test` adds Link
  test mode. Both are no-ops for production use.

## The money rules — never bend these

- Approve at most the quoted ceiling. The final charge settles to delivered bundles; any shortfall
  refunds automatically. The card minimum is 50 cents — below it an order is refused, not rounded up.
- An expired quote can never be charged. Quote again; never reuse an expired ID.
- If a charge outcome is ever ambiguous (timeout, disconnect, unknown status), the rule is
  **do_not_repay**: do not create a second purchase, do not retry payment automatically. Resume the
  same request/Link continuation and poll the same order.
- Never print, log, echo, or embed the owner secret, the verifier's counterpart, SPT material,
  payment tokens, or provider responses anywhere a human or another agent could read them.

## Terms

Each order names the audience terms version and document digest it was quoted
(current: `2026-11-11-audiences-v1`, https://www.bellaso.ai/docs/recon-audiences#terms): lawful B2B
sales and marketing use only; honor TCPA, do-not-call, and opt-out obligations; no resale or
redistribution; no political, donor, financial, or household data; the agent places the order only
with its buyer's explicit approval and never accepts an organization's terms.

## Limits to state honestly

- Emails are company-domain matches only, labelled as such — no verification or deliverability
  promise, never described as opted in.
- Phones are supplier-reported work numbers with do-not-call flags retained; cell numbers are
  never included.
- A quote carries no names, emails, phones, contact IDs, or vendor payloads — only counts,
  company/role samples, price lines, the ceiling, and the terms reference.
