# 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.
- Hosted cards carry an ES256 JWS signature. Public keys: `GET /.well-known/jwks.json`.
- ERC-8004 owner registration remains pending.

## 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.

## Security and card signatures

The card declares `securitySchemes: {}` and `securityRequirements: []`.
Discovery, public keys, and text instructions require no account or API key.
Structured company purchases still require the negotiated HTTP x402 extension and a valid payment.
The payment signature is a payment authorization, not an API key.

Hosted cards use ES256 JWS signatures under A2A 1.0 section 8.4.
The protected header contains `alg`, `typ`, `kid`, and an HTTPS `jku` for the public JWKS.
Clients must trust the expected QuerySpigot domain before they retrieve that key set.
An arbitrary card with its own arbitrary key URL does not establish provider identity.

To verify a card:

1. Fetch the card and the public JWKS from the expected QuerySpigot HTTPS origin.
2. Select the public key that matches the protected `kid`. Require `alg: ES256`.
3. Remove `signatures` and apply A2A protobuf field-presence rules.
4. Canonicalize the result with RFC 8785 and verify the detached JWS signature.

Empty security maps and lists are omitted from the signature payload under these rules.
Explicit optional capability flags, including `streaming: false`, remain in that payload.
A signature covers the published service description. It does not certify data accuracy, customer revenue, or legal-business identity.
Local development can use unsigned cards. Hosted startup requires a valid signing key.