# QuerySpigot A2A interface

QuerySpigot supports synchronous A2A 1.0 JSON-RPC requests for three company operations.
It returns direct Messages and creates no persistent tasks or conversation history.
Text messages return free instructions. Company purchases require one structured data part.

- Card: `GET /.well-known/agent-card.json`
- Messages: `POST /a2a`
- REST documentation: `/docs`
- Protocol version: `A2A-Version: 1.0`
- Streaming, push notifications, extended cards, and conversation contexts are unsupported.
- Agent-card signatures and ERC-8004 registration are separate from this interface.

## Try a free request

Use this request without a wallet. It returns usage instructions and does not purchase company data.

```sh
curl --fail-with-body 'https://api.queryspigot.com/a2a' \
  -H 'Content-Type: application/json' \
  -H 'A2A-Version: 1.0' \
  --data '{"jsonrpc":"2.0","id":"help-1","method":"SendMessage","params":{"message":{"messageId":"help-1","role":"ROLE_USER","parts":[{"text":"How do I use QuerySpigot?"}]}}}'
```

Use `https://testnet.queryspigot.com/a2a` for Base Sepolia. The request above is free on both networks.

## Request company data

Example request:

```json
{
  "jsonrpc": "2.0",
  "id": "lookup-1",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "lookup-1",
      "role": "ROLE_USER",
      "parts": [{"data": {
        "operation": "lookup",
        "input": {"company_number": "100001"}
      }}]
    }
  }
}
```

Send `Content-Type: application/json` and the extension header described below.
Use `search` with `input` containing `q` and optional `limit`, `status`, and `eircode`.
Use `resolve` with `input` containing `name` or `company_number` and optional `address` and `eircode`.
The REST validation limits and result schemas apply to all three operations.
Successful results appear in `result.message.parts[0].data`, including source and snapshot information.

## HTTP x402 v1

Extension URI: `https://queryspigot.com/docs/a2a.md#http-x402-v1`

Activate the extension for every structured request:

```http
A2A-Extensions: https://queryspigot.com/docs/a2a.md#http-x402-v1
```

1. Send the structured A2A request without payment.
2. Read the HTTP 402 response and its `PAYMENT-REQUIRED` header.
3. Check the quoted price, network, asset, receiver, and REST resource against your spending policy.
4. Sign the quoted x402 v2 authorization with your wallet runtime.
5. Retry the same A2A request with `PAYMENT-SIGNATURE`.
6. Check `PAYMENT-RESPONSE` and the resulting A2A Message.

The quote identifies the underlying REST resource, not `/a2a`. Do not replace its resource URL.
Prices match REST: mainnet lookup/search 0.01 USDC, resolution 0.02 USDC.
Base Sepolia lookup/search cost 0.001 test USDC; resolution costs 0.002 test USDC.

The adapter reuses the gateway's saved REST response and receipt on identical payment retries.
Payment binds to the mapped operation and inputs. Message IDs and JSON-RPC IDs do not authorize another purchase.
Equivalent structured objects use deterministic request serialization. Changed operations or inputs cannot reuse a completed payment for different data.
After a timeout, retry the same input and payment. Do not sign a fresh authorization until the previous outcome is known.
The adapter does not add a second settlement or hold signing keys.

This QuerySpigot extension uses HTTP x402 v2. It does not implement the task-based A2A x402 extension from google-agentic-commerce.
Generic A2A clients can read the card and request text help. Purchases require a client that handles this HTTP payment exchange.
HTTP payment and service errors retain the REST status and body. Protocol errors use JSON-RPC errors.

## Limits

The adapter accepts one message part, a 16 KiB body, and message IDs of at most 128 bytes.
It permits eight concurrent gateway calls, with a 65-second timeout and a 1 MiB response limit.
The existing shared company-origin rate limit also applies.
Remote files, arbitrary URLs, batch requests, notifications without IDs, tasks, and conversations are unsupported.
No LLM interprets text or chooses whether to spend.

## Local checks

The local Compose adapter listens at `http://localhost:8083/a2a`.
The REST gateway listens at `http://localhost:8082`.
The adapter listener cannot serve company REST routes directly.