# Hopwire

> Lightning-paid spot market for geographic network capacity. Agents can discover geographic VPN egress and remote browser capacity, pay operators over Lightning, and report demand for undersupplied regions.

## Human dashboard

- Dashboard: https://hopwire.network/
- Machine-readable guide: https://hopwire.network/llms.txt
- API catalog: https://hopwire.network/api-catalog.json
- Registry base URL: open the Machine tab in the dashboard for the active Convex HTTP actions URL.

## Capabilities

- egress: WireGuard tunnel through a provider region.
- browser-cdp: remote Chromium session exposed over Chrome DevTools Protocol.
- browser: legacy alias for browser-cdp.

## Quick start: discover capacity

Replace REGISTRY_BASE_URL with the Convex HTTP actions URL shown in the dashboard Machine tab.

```bash
curl "$REGISTRY_BASE_URL/health"
curl "$REGISTRY_BASE_URL/providers?region=nrt&category=standard-web&capability=egress&max_price_sats_per_minute=200"
curl "$REGISTRY_BASE_URL/demand?region=nrt"
```

## Quick start: record unmet demand

If no provider is available in the desired region, record demand. Operators and orchestrators can provision capacity from this signal.

```bash
curl -X POST "$REGISTRY_BASE_URL/demand" \
  -H "content-type: application/json" \
  -d '{
    "region": "nrt",
    "category": "standard-web",
    "maxPriceSatsPerMinute": 220,
    "requestedBy": "agent_pubkey_or_session_id"
  }'
```

## Provider discovery response

```json
{
  "providers": [
    {
      "_id": "jh...",
      "providerKey": "operator-nrt-01",
      "region": "nrt",
      "status": "active",
      "controlUrl": "https://operator.example.com",
      "capabilities": ["egress", "browser-cdp"],
      "categories": ["standard-web"],
      "pricing": {
        "egressSatsPerMinute": 120,
        "egressSatsPerMb": 5,
        "browserSatsPerMinute": 180
      }
    }
  ]
}
```

## Operator session flow

1. Choose an active provider from /providers.
2. Request a challenge from the provider control plane.
3. Pay the Lightning invoice returned by the provider.
4. Replay the authorization request with the paid preimage.
5. Use the returned WireGuard or browser-CDP session details.

Prototype CLI:

```bash
bun run hopwire -- providers list --region=nrt --category=standard-web --capability=egress
bun run hopwire -- operator challenge --operator-url=http://127.0.0.1:9443 --region=nrt --category=standard-web --capability=egress
bun run hopwire -- operator pay-authorize --operator-url=http://127.0.0.1:9443 --challenge-id=<id> --invoice=<bolt11>
```

## Local requester wallet

Do not put Lightning wallet material in browser code. For requester-side payments, run a local wallet bridge on 127.0.0.1 that talks to the Lexe CLI wallet, then let the dashboard call the bridge for sanitized wallet state and invoice payment.

Prepare a requester wallet with the Lexe CLI:

```bash
lexe init
lexe node-info
```

Start the local bridge:

```bash
bun run wallet:connect
```

This starts the bridge in the background. It exits after the dashboard stops polling it or shortly after the dashboard tab closes.

Planned local bridge endpoints:

```http
GET  http://127.0.0.1:8787/health
GET  http://127.0.0.1:8787/wallet
POST http://127.0.0.1:8787/pay-invoice
GET  http://127.0.0.1:8787/payment/:index
POST http://127.0.0.1:8787/session/end?session=<dashboard-session>
```

## Registry endpoints

- GET /health
- GET /providers
- GET /demand
- GET /snapshot
- POST /demand
- POST /providers/register
- POST /providers/heartbeat
- POST /tunnels/start
- POST /tunnels/meter
- POST /tunnels/finish
- POST /provision/jobs
- POST /provision/jobs/update
- POST /reputation/report

Write endpoints may require Authorization: Bearer <REGISTRY_WRITE_TOKEN> or x-hopwire-registry-token.

## Content usage signals

Content-Signal: ai-train=no, search=yes, ai-input=yes