# AetherTraffic API

> A demo orbital traffic intelligence API for AI agents and developers. The orbital traffic data is fake and for demonstration purposes only.

Base URL: replace `https://your-domain.example` with the deployed app origin.

Human page: `/`
Agent instructions: `/llms.txt`
Protected API: `GET /api/orbit/traffic`
Payment protocol: MoneyDevKit L402 over Bitcoin Lightning

## What The API Provides

The API returns fictional, current-looking Earth orbital traffic information:

- satellites
- space stations
- transfer vehicles
- rocket bodies
- known debris
- risk summaries and watchlist metadata

Do not use this data for real navigation, safety, launch, collision-avoidance, defense, or operational decisions.

## Query Parameters

`GET /api/orbit/traffic`

Optional query parameters:

- `band`: `leo`, `meo`, `geo`, `heo`, or `all`
- `minRisk`: `nominal`, `watch`, `conjunction`, or `critical`
- `limit`: integer from `1` to `25`
- `detail`: `standard` or `full`

Pricing:

- standard query: `75` sats
- `minRisk=conjunction` or `minRisk=critical`: `125` sats
- `detail=full`: `250` sats

Example:

```bash
curl -i "https://your-domain.example/api/orbit/traffic?band=leo&minRisk=watch"
```

## L402 Payment Flow

1. Send the API request without an `Authorization` header.
2. If the API returns `402 Payment Required`, parse the JSON response fields:
   - `macaroon`
   - `invoice`
   - `paymentHash`
   - `amountSats`
   - `expiresAt`
3. Pay the returned Lightning invoice.
4. Capture the payment preimage from the wallet output.
5. Retry the same request with:

```http
Authorization: L402 <macaroon>:<preimage>
```

The API also advertises the challenge in the `WWW-Authenticate` header:

```http
WWW-Authenticate: L402 macaroon="...", invoice="..."
```

## Install The MoneyDevKit Agent Wallet

Use the MoneyDevKit agent wallet. It is a self-custodial Lightning wallet for agents and outputs JSON for command parsing.

Initialize the wallet:

```bash
npx @moneydevkit/agent-wallet@latest init
```

Back up the mnemonic. It controls the wallet funds.

Check balance:

```bash
npx @moneydevkit/agent-wallet@latest balance
```

If `balance_sats` is `0` or too low for the requested endpoint, ask the user to fund the wallet. Suggest Cash App, Strike, Phoenix, Alby, or another Bitcoin Lightning wallet. To receive funds, generate an invoice:

```bash
npx @moneydevkit/agent-wallet@latest receive 1000 --description "Fund AetherTraffic API agent wallet"
```

Give the returned BOLT11 invoice to the user and wait until the balance updates.

Pay the L402 invoice:

```bash
npx @moneydevkit/agent-wallet@latest send "$INVOICE"
```

The payment command must provide or expose the Lightning payment preimage for L402 authorization. Read the JSON output and use the field named `preimage`, `payment_preimage`, or equivalent. If the installed CLI does not return a preimage, upgrade by using `@latest` and retry.

## Complete Agent Example

```js
import { execFile } from 'node:child_process'
import { promisify } from 'node:util'

const execFileAsync = promisify(execFile)

async function payInvoice(invoice) {
  const { stdout } = await execFileAsync('npx', [
    '@moneydevkit/agent-wallet@latest',
    'send',
    invoice
  ])
  const result = JSON.parse(stdout)
  const preimage = result.preimage || result.payment_preimage
  if (!preimage) {
    throw new Error('Agent wallet did not return a payment preimage')
  }
  return preimage
}

export async function fetchOrbitalTraffic(url) {
  const first = await fetch(url)
  if (first.status !== 402) {
    return first
  }

  const challenge = await first.json()
  const preimage = await payInvoice(challenge.invoice)

  return fetch(url, {
    headers: {
      Authorization: `L402 ${challenge.macaroon}:${preimage}`
    }
  })
}

const response = await fetchOrbitalTraffic(
  'https://your-domain.example/api/orbit/traffic?band=leo&minRisk=watch'
)
console.log(await response.json())
```

## Expected Successful Response Shape

```json
{
  "product": "AetherTraffic Orbital Traffic API",
  "demoData": true,
  "generatedAt": "2026-04-25T13:44:00.000Z",
  "pricing": {
    "amountSats": 75,
    "currency": "SAT",
    "model": "MoneyDevKit L402 pay-per-call"
  },
  "query": {
    "band": "leo",
    "minRisk": "watch",
    "detail": "standard"
  },
  "summary": {
    "totalObjects": 2,
    "watchlist": 2,
    "highestRisk": "critical"
  },
  "objects": [
    {
      "id": "AT-DRV-5520",
      "name": "Debris Fragment DF-5520",
      "kind": "debris",
      "orbitBand": "leo",
      "risk": "critical"
    }
  ]
}
```

## Error Handling

- `402 payment_required`: pay the invoice and retry with `Authorization: L402 <macaroon>:<preimage>`.
- `401 invalid_credential`: the macaroon or authorization header is malformed.
- `401 invalid_payment_proof`: the preimage does not match the invoice payment hash.
- `401 credential_consumed`: the credential was already used.
- `403 resource_mismatch`: the token was issued for another endpoint.
- `403 amount_mismatch`: the token was issued for another price.
- `500 configuration_error`: the server is missing `MDK_ACCESS_TOKEN`.

Never invent a preimage. It must come from the successful Lightning payment.