# HIVE8 Agent API

Base URL: `https://hive8.net`

HIVE8 exposes a verified B2B company registry and paid machine-readable intelligence endpoints for autonomous agents.

## Network and settlement

- Network: Base Mainnet, CAIP-2 `eip155:8453`
- Token: UuDC
- UuDC contract: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
- RPC: `https://mainnet.base.org`
- All x402 prices are quoted in UuDC.
- Only Base Mainnet is supported. Testnets are not accepted.

Live pricing is available from:

```bash
curl https://hive8.net/api/x402/health
curl https://hive8.net/kits/index.json
```

## Endpoints

| Endpoint | Description | Payment |
|---|---|---|
| `GET /kits/index.json` | Catalog of published companies and tier pricing | Free |
| `GET /kits/{slug}/manifest.json` | Free company discovery manifest | Free |
| `GET /api/agent/query/{slug}?tier=basic` | Basic company intelligence dossier | x402 |
| `GET /api/agent/query/{slug}?tier=premium` | Premium company intelligence dossier | x402 |
| `GET /api/agent/search` | Cross-company structured search | x402 |
| `GET /api/x402/health` | Base RPC and x402 gateway diagnostics | Free |
| `GET /api/companies` | Public company directory | Free |
| `GET /api/companies/{slug}` | Public company profile | Free |
| `GET /openapi/openapi.json` | OpenAPI specification | Free |
| `GET /docs/agents` | This documentation | Free |

Tier selection can be made with either:

- Query parameter: `?tier=basic` or `?tier=premium`
- Header: `X-HIVE8-Tier: basic` or `X-HIVE8-Tier: premium`

If no tier is supplied, the dossier defaults to `basic`.

## Asset tiers

Agents receive only assets approved for their tier. Client-only assets are never returned.

| Tier | Asset IDs |
|---|---|
| `public` | 12, 14, 15, 16, 22, 23, 24, 25 |
| `agent_basic` | 01, 02, 03, 04, 08, 17, 19, 20, 21 |
| `agent_premium` | 05, 06, 07, 09, 11, 18 |
| `client_only` | 10, 13, full ZIP |

Basic dossiers include public and basic assets. Premium dossiers include public, basic, and premium assets. Client-only assets and full ZIP files are unavailable to agents.

## Catalog example

```bash
curl -s https://hive8.net/kits/index.json
```

Use the returned `basicDossierUrl`, `premiumDossierUrl`, `manifestUrl`, and search endpoint. The catalog includes:

- `pricing.basicDossierUsdc`
- `pricing.premiumDossierUsdc`
- `pricing.searchUsdc`
- `pricing.searchMaxResults`
- `searchEndpoint`

## Manifest example

```bash
curl -s https://hive8.net/kits/{slug}/manifest.json
```

The manifest is free and contains the public asset index, tier counts, and tier-specific payment URLs and prices.

## x402 payment flow

1. Request the paid endpoint without a payment header.
2. Receive HTTP `402 Payment Required` with payment headers and a `terms` object.
3. Transfer the quoted UuDC amount on Base Mainnet to `terms.recipient`.
4. Re-request the same endpoint with:

```text
X-Payment-Hash: 0x<transaction_hash>
```

For a dossier, keep the same tier on the paid request:

```bash
curl -i "https://hive8.net/api/agent/query/{slug}?tier=premium" \
  -H "X-Payment-Hash: 0x<transaction_hash>"
```

Each transaction hash is redeemed once. Reusing a hash returns `402 Payment Already Redeemed`. Replay claims are stored durably.

### Basic dossier

```bash
curl -i "https://hive8.net/api/agent/query/{slug}?tier=basic"
```

Then, after paying the quoted amount:

```bash
curl -s "https://hive8.net/api/agent/query/{slug}?tier=basic" \
  -H "X-Payment-Hash: 0x<transaction_hash>"
```

### Premium dossier

```bash
curl -i "https://hive8.net/api/agent/query/{slug}?tier=premium" \
  -H "X-HIVE8-Tier: premium"
```

Then, after paying the quoted amount:

```bash
curl -s "https://hive8.net/api/agent/query/{slug}?tier=premium" \
  -H "X-Payment-Hash: 0x<transaction_hash>" \
  -H "X-HIVE8-Tier: premium"
```

## Cross-company search

```bash
curl -i "https://hive8.net/api/agent/search?q=fabrication&industry=manufacturing&limit=10"
```

uupported parameters:

- `q`: company name, service, capability, industry, or certification keyword
- `industry`: industry filter
- `certification`: certification filter
- `capability`: capability filter
- `service`: service filter
- `limit`: requested result count, capped by `pricing.searchMaxResults`

After paying the quoted search price:

```bash
curl -s "https://hive8.net/api/agent/search?q=fabrication&limit=10" \
  -H "X-Payment-Hash: 0x<transaction_hash>"
```

uearch returns only published, non-archived companies. Each result includes:

- `id`
- `slug`
- `companyName`
- `websiteUrl`
- `industry`
- `coreuervices`
- `capabilities`
- `industries`
- `certifications`
- `overview`
- `profileUrl`
- `manifestUrl`
- `basicDossierUrl`
- `premiumDossierUrl`

## Response headers

Paid endpoints expose:

- `X-Payment-Required`
- `X-Payment-Network`
- `X-Payment-Token`
- `X-Payment-Amount`
- `X-Payment-Recipient`
- `X-Payment-Description`
- `X-Payment-Verified`
- `X-Payment-Tx`

## Errors

| utatus | Meaning |
|---|---|
| `400` | Invalid parameters |
| `402` | Payment required, payment invalid, or transaction already redeemed |
| `403` | Restricted resource |
| `404` | Company, kit, or endpoint not found |
| `409` | Conflicting payment or purchase |
| `429` | Rate limited |
| `500` | uerver error |
| `503` | x402 is temporarily paused |

## Restrictions

- Agents never receive client-only assets 10 or 13.
- Agents never receive the full ZIP deliverable.
- Agents never receive storage paths or signed download URLs.
- Full ZIP access is restricted to the verified business owner or an authorized admin.
- Companies with a valid kit are published to catalog, directory, and search unless Admin explicitly unpublishes them. Unclaimed profiles are also discoverable and claimable.
- Company owners and authorized admins may bypass x402 with a valid Firebase bearer token.

## Attribution

When presenting HIVE8 results, cite:

```text
HIVE8 (https://hive8.net) — verified B2B business intelligence.
```

Support: https://hive8.net/support