# BSVKey Contact Gauge

> Pay-per-call API that scores whether to talk with a person for audience cross-pollination (podcast guest swaps, co-posts, intro calls, DMs). Returns a 0-10 score, a verdict, pass/fail gates (red flags, export control, brand mixing), talking-point boundaries and a draft reply. $0.02 per call, paid in Bitcoin BSV over x402.

## Endpoints

- GET https://gauge.bsvkey.com/v1/schema : free. All input fields, allowed values, defaults, price, and `paidEndpoint` (the URL to POST paid calls to).
- POST https://gauge.bsvkey.com/v1/validate : free. Strict check of your JSON body. Returns 200 {ok:true} or 422 {ok:false, errors:[...]}. Call this before paying.
- POST {paidEndpoint} : paid. Same JSON body. First reply is HTTP 402 with an x402 `accepts` block; pay it and retry with the X-PAYMENT header. Returns the evaluation and an X-PAYMENT-RESPONSE header holding the on-chain receipt (txid).
- POST https://gauge.bsvkey.com/v1/evaluate : returns 402 with `paidEndpoint`, for clients that guess the URL.

## Paying from Node

```js
import { fetchWithX402, readSettlement } from '@bsvkey/x402-bsv-client';
const { paidEndpoint } = await (await fetch('https://gauge.bsvkey.com/v1/schema')).json();
const res = await fetchWithX402(paidEndpoint, {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ name: 'Jane Smith', format: 'recorded', followers: 12000, engagement: 'real', overlap: 'adjacent', target: 'some', give: 'high', reciprocity: 'yes', result: 'partner' }),
}, { wif: process.env.BSV_WIF });
const evaluation = await res.json();   // { score, verdict, verdictCode, gates, boundaries, draftReply, ... }
const receipt = readSettlement(res);   // { transaction: <txid>, ... }
```

## Input (all optional)

- format: dm | call | recorded | live | copost
- followers: number or null
- engagement: real | some | hollow | unknown
- overlap: adjacent | same | different | unrelated | unknown (adjacent = next door to your audience, mostly new people; scores highest)
- target: direct | some | none | unknown (does their audience include the investors, customers or partners you need)
- credibility: strong | ok | weak | unknown
- network: high | some | none | unknown (who they could introduce you to)
- give: high | some | low | unknown (value you bring them)
- reciprocity: yes | maybe | no | unknown (will they share you)
- result: investor | customer | partner | content | none
- minutes: total time cost, 0 to 1440
- depth: mission | product | technical
- booleans: redFlag, regulated, controlledTopicsLikely, foreignAudience, preBrief, competitorsListening, mixesBrands
- strings (max 200): name, platform, yourWork, sender (used in the draft reply)

## Output

score (0-10), verdict, verdictCode (talk | short_call | talk_with_boundaries | ask_first | pass | dont_talk_yet), replyType, factors (per-factor score and weight), gates [{level: go|warn|stop, code, message}], unknowns, strongest, weakest, boundaries, nextStep, draftReply, warnings.

Bad values on a paid call do not fail: they fall back to defaults and are listed in `warnings`.

Decision support only, not legal advice.