# GeoCites

AI citation visibility oracle. Queries multiple LLMs and scores how a domain gets cited.

## Discovery

- **AgentCard:** https://staging.geo-cites.com/.well-known/agent-card.json
- **JSON-RPC endpoint (native A2A):** `POST https://staging.geo-cites.com/api/a2a/jsonrpc`
- **SKILL.md (this file):** https://staging.geo-cites.com/.well-known/SKILL.md
- **Human docs:** https://staging.geo-cites.com/agent-docs
- **Contact:** contact@geo-cites.com

## Authentication

Paid skills require an x402 payment. Send the request once; the server replies with a `402 Payment Required` body that includes the canonical `accepts[]` requirements (scheme, network, asset, payTo, amount). Sign an EIP-3009 `TransferWithAuthorization` for the requested amount and retry with the signed payload as the `X-Payment` header (base64-encoded JSON). On settlement the server includes `X-Payment-Response` with the on-chain transaction hash.

Free skills (verify-only proof of wallet, retrieval) require no upfront payment.

## Skills

### `scan` — AI citation scan

Run an AI citation scan for a domain + keyword. Returns per-model citation scores, prominence, and competitor hits.

**REST endpoint:** `POST https://staging.geo-cites.com/api/a2a/scan`
**JSON-RPC method:** `message/send` with `message.skillId = "scan"`
**Payment:** 150000 0x036cbd53842c5426634e7929541ec2318f3dcf7e per request via x402 (base-sepolia, exact)
**Tags:** scan, citation, seo

**Example input:**

```json
{"domain":"example.com","keyword":"example service"}
```

### `audit` — On-page citability audit

HTML / robots / llms.txt audit scoring how easily an AI can cite the page. No LLM calls.

**REST endpoint:** `POST https://staging.geo-cites.com/api/a2a/audit`
**JSON-RPC method:** `message/send` with `message.skillId = "audit"`
**Payment:** 20000 0x036cbd53842c5426634e7929541ec2318f3dcf7e per request via x402 (base-sepolia, exact)
**Tags:** audit, seo

**Example input:**

```json
{"url":"https://example.com"}
```

### `radius` — Geographic citation radius

Ring-based citation radius across competitor markets — N rings × M queries per ring.

**REST endpoint:** `POST https://staging.geo-cites.com/api/a2a/radius`
**JSON-RPC method:** `message/send` with `message.skillId = "radius"`
**Payment:** 500000 0x036cbd53842c5426634e7929541ec2318f3dcf7e per request via x402 (base-sepolia, exact)
**Tags:** radius, geo

**Example input:**

```json
{"domain":"example.com","keyword":"example service","location":"Madrid, Spain","rings":[1,2]}
```

### `full` — Full bundle (scan + radius + audit)

Citation scan and radius bundle with a best-effort page audit. An unreachable page is reported as auditError; scan or radius failure prevents settlement.

**REST endpoint:** `POST https://staging.geo-cites.com/api/a2a/full`
**JSON-RPC method:** `message/send` with `message.skillId = "full"`
**Payment:** 600000 0x036cbd53842c5426634e7929541ec2318f3dcf7e per request via x402 (base-sepolia, exact)
**Tags:** scan, radius, audit, bundle

**Example input:**

```json
{"domain":"example.com","keyword":"example service","location":"Madrid, Spain"}
```

### `watch` — Streaming citation scan

Same as `scan` with model_started, model_done, scan_complete and a terminal payment_settled or payment_failed event. Native A2A clients receive task events on message/stream.

**REST endpoint:** `POST https://staging.geo-cites.com/api/a2a/watch`
**JSON-RPC method:** `message/send` with `message.skillId = "watch"`
**Payment:** 150000 0x036cbd53842c5426634e7929541ec2318f3dcf7e per request via x402 (base-sepolia, exact)
**Tags:** scan, streaming

### `my-receipts` — Wallet receipt retrieval

Verify wallet ownership with a 1 micro-USDC EIP-3009 authorization (never settled), then return paid receipts scoped to that wallet.

**REST endpoint:** `POST https://staging.geo-cites.com/api/a2a/my-receipts`
**JSON-RPC method:** `message/send` with `message.skillId = "my-receipts"`
**Tags:** receipts, verify-only

## Facilitator

This server uses an x402 facilitator to verify and settle payments on-chain. The facilitator URL is encoded in the AgentCard's payment requirements; clients do not need to configure it manually.