# Greenhead Labs

> Public pay-per-call XRPL data and Grok AI. No accounts, JWT, or sessions. Pay XRP or RLUSD on XRPL mainnet (xrpl:0), then retry with X-Payment-Txid set to the validated Payment hash.

## How to pay

1. `GET https://x402.greenhead.io/.well-known/x402` (free). Read `payTo`, `network` (`xrpl:0`), and the endpoint price.
2. Submit an XRPL Payment of that XRP amount, or 0.01 RLUSD, to `payTo`.
3. Wait until the Payment is validated.
4. Retry the same HTTP request with `X-Payment-Txid: <64-hex transaction hash>`.
5. Each hash can be used once. There are no API keys, JWT, cookies, or IP allowlists.

Base (optional): when catalog `networks` includes `eip155:8453`, pay USDC on Base to `payment.base.payTo` and retry with `PAYMENT-SIGNATURE` (x402 PaymentPayload, facilitator verify+settle). catalog priceXrp maps 1:1 to USDC face value (0.002 XRP SKU → 0.002 USDC = 2000 atomic). Not a live XRP/USD FX feed. Prove route: `GET /v1/base/ping`.

`GET /` is a plain HTML index for crawlers. x402 clients should use `GET /.well-known/x402`.

Optional campaign attribution: pass query `campaign=<tag>`, or set XRPL `DestinationTag` / a UTF-8 Payment memo. Successful paid calls echo it on the receipt.

## JS client

`npm i @greenhead/x402-fetch` — `@greenhead/x402-fetch`. Wraps `fetch`: HTTP 402 → your `pay` hook (XRPL Payment to `payTo` for `priceDrops`) or a prepaid `paymentTxid` → retry with `X-Payment-Txid`. This package does not sign. Source: https://github.com/GreenheadLabs/x402/tree/main/packages/x402-fetch

```js
import { x402Fetch } from "@greenhead/x402-fetch";

const res = await x402Fetch("https://x402.greenhead.io/v1/xrpl/listings", {
  pay: async ({ payTo, priceDrops }) => {
    // XRPL Payment of priceDrops drops to payTo on xrpl:0; return validated 64-hex hash
    return txid;
  },
});
```

Prepaid: `x402Fetch(url, { paymentTxid: "<64-hex>" })`. curl still works if you skip the client.

## Free discovery files

- Catalog JSON: https://x402.greenhead.io/.well-known/x402
- OpenAPI: https://x402.greenhead.io/openapi.json
- HTML docs: https://x402.greenhead.io/docs
- Markdown docs: https://x402.greenhead.io/docs.md
- llms.txt: https://x402.greenhead.io/llms.txt
- agents.txt: https://x402.greenhead.io/agents.txt
- agents.json: https://x402.greenhead.io/agents.json
- Skill: https://x402.greenhead.io/skills/x402/SKILL.md
- Status: https://x402.greenhead.io/status
- Health: https://x402.greenhead.io/health
- Receipt lookup: https://x402.greenhead.io/v1/receipts/{txid}
- Metrics: https://x402.greenhead.io/api/metrics

## Payment error codes

Failed payment verification returns JSON with stable `error` and `code` fields (same string). Retry only when `retryable` is true.

- `payment_required` — HTTP 402, retryable. Missing X-Payment-Txid. Pay the listed amount to catalog payTo, then retry with the validated Payment hash.
- `payment_lookup_failed` — HTTP 402, retryable. XRPL lookup failed: transaction not found, RPC error, or unexpected ledger response.
- `payment_underpaid` — HTTP 402 (aliases: insufficient_amount, payment_insufficient). Payment delivered less than the endpoint price (XRP drops or RLUSD).
- `payment_wrong_payTo` — HTTP 402 (aliases: destination_mismatch). Payment Destination does not match catalog payTo / GHL_AP_WALLET.
- `payment_already_used` — HTTP 402. This X-Payment-Txid has already been redeemed. Send a new Payment.
- `payment_not_validated` — HTTP 402, retryable (aliases: payment_pending). Transaction exists but is not yet validated on the XRP Ledger. Wait and retry.
- `payment_pending` — HTTP 402, retryable (aliases: payment_not_validated). Alias of payment_not_validated. Transaction is in flight / not validated yet.
- `payment_timeout` — HTTP 504, retryable. Timed out waiting for the XRPL RPC while looking up X-Payment-Txid.
- `payment_wallet_unconfigured` — HTTP 503, retryable. GHL_AP_WALLET is not set. Probes without a txid return 503; paid retries return 402.
- `invalid_payment_txid` — HTTP 402. X-Payment-Txid is not a 64-character hexadecimal XRPL transaction hash.
- `payment_hash_mismatch` — HTTP 402. Ledger transaction hash does not match X-Payment-Txid.
- `payment_failed_on_ledger` — HTTP 402. Referenced transaction did not result in tesSUCCESS.
- `not_a_payment` — HTTP 402. X-Payment-Txid must reference an XRPL Payment transaction.
- `unsupported_asset` — HTTP 402. Payment must deliver XRP or RLUSD.
- `invalid_payment_signature` — HTTP 402. PAYMENT-SIGNATURE is missing, not base64 JSON, or is not an x402 PaymentPayload.
- `facilitator_auth_failed` — HTTP 503, retryable. CDP facilitator Authorization is missing or JWT mint failed. Set CDP_API_KEY_ID + CDP_API_KEY_SECRET (Secret API key, ECDSA ES256 PEM from portal.cdp.coinbase.com/access/api) or X402_FACILITATOR_BEARER. Ed25519 keys mint as EdDSA; ES256 PEM is the usual CDP x402 Secret API key.
- `facilitator_verify_failed` — HTTP 402, retryable. CDP/x402 facilitator POST /verify rejected the Base payment payload.
- `facilitator_settle_failed` — HTTP 402, retryable. CDP/x402 facilitator POST /settle failed after verify. Retry only after checking the settlement id.

## Payment receipt

On a paid success, the JSON body includes `receipt` and the response header `X-Payment-Receipt` is base64 JSON with: `txid`, `endpoint` (method + path), `amount`, `asset`, `network`, `timestamp`, `payTo`, and optional `campaign`.

CFO verify (no payment required): `GET https://x402.greenhead.io/v1/receipts/{txid}` returns thin JSON only:

`{ "txid", "redeemed", "endpoint", "payer", "pay_to", "amount_drops", "internal", "redeemed_at", "status" }`

`status` is `settled` (this instance redeemed the hash), `unused` (validated Payment to `payTo` not yet redeemed), or `unknown`. Lookup never returns webhook secrets or wallet keys.

Meters: `GET https://x402.greenhead.io/api/metrics` — `as_of`, `paid_calls` (h24/d7/d30), `revenue` (drops/xrp/usd_mark/mark_xrp_usd), `unique_payers` (external/internal), `by_endpoint`, `receipt_redeem_success_rate`.

## Paid endpoints

### GET /v1/xrpl/settlement

Paid XRPL Payment attestation by query txid. Distinct from free GET /v1/receipts/:txid. Fail-closed: invalid, missing, unvalidated, or non-Payment hashes return 4xx without redeeming X-Payment-Txid. 75,000 drops (0.075 XRP).

- Price: 0.075 XRP or 0.01 RLUSD (issuer rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De)
- Network: `xrpl:0`
- Auth: header `X-Payment-Txid` = validated Payment hash to `payTo` from the catalog

Query:
  - `txid`: 64-character XRPL transaction hash to attest (required)

Unauthenticated example (expect 402):

```bash
curl -i https://x402.greenhead.io/v1/xrpl/settlement
```

### GET /v1/xrpl/token

Token info for an XRPL issued currency: issuer details, DEX/AMM price in XRP, holder metrics, and liquidity.

- Price: 0.01 XRP or 0.01 RLUSD (issuer rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De)
- Network: `xrpl:0`
- Auth: header `X-Payment-Txid` = validated Payment hash to `payTo` from the catalog

Query:
  - `issuer`: XRPL classic address of the token issuer (required)
  - `currency`: Currency code (3-char, hex, or UTF-8 name) (required)

Unauthenticated example (expect 402):

```bash
curl -i https://x402.greenhead.io/v1/xrpl/token
```

### GET /v1/xrpl/listings

Recent XRPL token launches from GeckoTerminal / First Ledger, sorted by launch date descending.

- Price: 0.002 XRP or 0.01 RLUSD (issuer rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De)
- Network: `xrpl:0`
- Auth: header `X-Payment-Txid` = validated Payment hash to `payTo` from the catalog

Query:
  - `limit`: Max listings to return (default 50, max 100)

Unauthenticated example (expect 402):

```bash
curl -i https://x402.greenhead.io/v1/xrpl/listings
```

### GET /v1/xrpl/orderbook

XRPL DEX order book for a currency pair (bids and asks, plus mid price).

- Price: 0.01 XRP or 0.01 RLUSD (issuer rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De)
- Network: `xrpl:0`
- Auth: header `X-Payment-Txid` = validated Payment hash to `payTo` from the catalog

Query:
  - `base`: Base asset: XRP or CODE:issuer / CODE.issuer / CODE+issuer (required)
  - `quote`: Quote asset: XRP or CODE:issuer / CODE.issuer / CODE+issuer (required)

Unauthenticated example (expect 402):

```bash
curl -i https://x402.greenhead.io/v1/xrpl/orderbook
```

### GET /v1/xrpl/portfolio

Wallet token holdings on XRPL, including XRP balance and estimated XRP values.

- Price: 0.02 XRP or 0.01 RLUSD (issuer rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De)
- Network: `xrpl:0`
- Auth: header `X-Payment-Txid` = validated Payment hash to `payTo` from the catalog

Query:
  - `address`: XRPL classic address of the wallet (required)

Unauthenticated example (expect 402):

```bash
curl -i https://x402.greenhead.io/v1/xrpl/portfolio
```

### POST /v1/ai/chat

Grok chat completions (model grok-3-mini) via https://api.x.ai/v1/chat/completions. Requires GROK_API_KEY.

- Price: 0.05 XRP or 0.01 RLUSD (issuer rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De)
- Network: `xrpl:0`
- Auth: header `X-Payment-Txid` = validated Payment hash to `payTo` from the catalog

JSON body:
  - `messages`: Chat messages array (required unless prompt is set)
  - `prompt`: Optional prompt string used as a single user message

Unauthenticated example (expect 402):

```bash
curl -i -X POST -H 'Content-Type: application/json' https://x402.greenhead.io/v1/ai/chat
```

### POST /v1/xrpl/amm-score

Fetch AMM pool data, then score pool quality 0-100 via Grok (grok-3-mini) for a sniper bot.

- Price: 0.05 XRP or 0.01 RLUSD (issuer rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De)
- Network: `xrpl:0`
- Auth: header `X-Payment-Txid` = validated Payment hash to `payTo` from the catalog

JSON body:
  - `issuer`: XRPL classic address of the token issuer (required)
  - `currency`: Currency code (3-char, hex, or UTF-8 name) (required)
  - `poolXrp`: Claimed XRP in the AMM pool (required)

Unauthenticated example (expect 402):

```bash
curl -i -X POST -H 'Content-Type: application/json' https://x402.greenhead.io/v1/xrpl/amm-score
```

### GET /v1/xrpl/trending

Top 10 XRPL tokens by 24h volume from xrpl.to.

- Price: 0.05 XRP or 0.01 RLUSD (issuer rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De)
- Network: `xrpl:0`
- Auth: header `X-Payment-Txid` = validated Payment hash to `payTo` from the catalog


Unauthenticated example (expect 402):

```bash
curl -i https://x402.greenhead.io/v1/xrpl/trending
```

### POST /v1/ai/trade-advice

XRPL buy/skip/watch advice via Grok chat completions (grok-3-mini).

- Price: 0.05 XRP or 0.01 RLUSD (issuer rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De)
- Network: `xrpl:0`
- Auth: header `X-Payment-Txid` = validated Payment hash to `payTo` from the catalog

JSON body:
  - `messages`: Chat messages array (optional if prompt or token fields are set)
  - `prompt`: Optional prompt string describing the token or trade

Unauthenticated example (expect 402):

```bash
curl -i -X POST -H 'Content-Type: application/json' https://x402.greenhead.io/v1/ai/trade-advice
```

### POST /v1/ai/risk-score

Fetch XRPL token data, then score risk 0-100 via Grok (grok-3-mini).

- Price: 0.05 XRP or 0.01 RLUSD (issuer rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De)
- Network: `xrpl:0`
- Auth: header `X-Payment-Txid` = validated Payment hash to `payTo` from the catalog

JSON body:
  - `issuer`: XRPL classic address of the token issuer (required)
  - `currency`: Currency code (required)
  - `poolXrp`: XRP in the AMM pool (required)
  - `poolTokens`: Token units in the AMM pool (required)

Unauthenticated example (expect 402):

```bash
curl -i -X POST -H 'Content-Type: application/json' https://x402.greenhead.io/v1/ai/risk-score
```

### POST /v1/ai/sentiment

Sentiment as positive/neutral/negative with a 0-100 confidence score via Grok (grok-3-mini).

- Price: 0.05 XRP or 0.01 RLUSD (issuer rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De)
- Network: `xrpl:0`
- Auth: header `X-Payment-Txid` = validated Payment hash to `payTo` from the catalog

JSON body:
  - `text`: Text to analyze (required)

Unauthenticated example (expect 402):

```bash
curl -i -X POST -H 'Content-Type: application/json' https://x402.greenhead.io/v1/ai/sentiment
```

### POST /v1/ai/grok

Grok text via the xAI Responses API (default model grok-4.6). Requires GROK_API_KEY.

- Price: 0.05 XRP or 0.01 RLUSD (issuer rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De)
- Network: `xrpl:0`
- Auth: header `X-Payment-Txid` = validated Payment hash to `payTo` from the catalog

JSON body:
  - `input`: Prompt string or messages array (required unless prompt/messages is set)
  - `prompt`: Alias for input
  - `messages`: Chat messages array forwarded as input
  - `model`: Optional model name (default grok-4.6)

Unauthenticated example (expect 402):

```bash
curl -i -X POST -H 'Content-Type: application/json' https://x402.greenhead.io/v1/ai/grok
```

### POST /v1/ai/image

Generate an image with Grok Imagine. Requires GROK_API_KEY.

- Price: 0.05 XRP or 0.01 RLUSD (issuer rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De)
- Network: `xrpl:0`
- Auth: header `X-Payment-Txid` = validated Payment hash to `payTo` from the catalog

JSON body:
  - `prompt`: Image prompt (required)
  - `model`: Optional model (default grok-imagine-image-quality)

Unauthenticated example (expect 402):

```bash
curl -i -X POST -H 'Content-Type: application/json' https://x402.greenhead.io/v1/ai/image
```

### POST /v1/ai/video

Start a Grok Imagine video generation. Requires GROK_API_KEY.

- Price: 0.05 XRP or 0.01 RLUSD (issuer rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De)
- Network: `xrpl:0`
- Auth: header `X-Payment-Txid` = validated Payment hash to `payTo` from the catalog

JSON body:
  - `prompt`: Video prompt (required)
  - `model`: Optional model (default grok-imagine-video)

Unauthenticated example (expect 402):

```bash
curl -i -X POST -H 'Content-Type: application/json' https://x402.greenhead.io/v1/ai/video
```

### GET /v1/ai/video

Poll a Grok Imagine video job by request_id. Requires GROK_API_KEY.

- Price: 0.05 XRP or 0.01 RLUSD (issuer rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De)
- Network: `xrpl:0`
- Auth: header `X-Payment-Txid` = validated Payment hash to `payTo` from the catalog

Query:
  - `request_id`: xAI video request_id (required unless passed as /v1/ai/video/:requestId)

Unauthenticated example (expect 402):

```bash
curl -i https://x402.greenhead.io/v1/ai/video
```

### POST /v1/ai/tts

Grok text-to-speech. Returns audio. Requires GROK_API_KEY.

- Price: 0.05 XRP or 0.01 RLUSD (issuer rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De)
- Network: `xrpl:0`
- Auth: header `X-Payment-Txid` = validated Payment hash to `payTo` from the catalog

JSON body:
  - `text`: Text to speak (required)
  - `voice_id`: Optional voice (default eve)
  - `language`: Optional language (default en)

Unauthenticated example (expect 402):

```bash
curl -i -X POST -H 'Content-Type: application/json' https://x402.greenhead.io/v1/ai/tts
```

### POST /v1/xrpl/wallet-score

Wallet trust/risk score 0-100 from XRPL age, tx count, trust lines, and balance via Grok. 2000 drops.

- Price: 0.002 XRP or 0.01 RLUSD (issuer rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De)
- Network: `xrpl:0`
- Auth: header `X-Payment-Txid` = validated Payment hash to `payTo` from the catalog

JSON body:
  - `address`: XRPL classic address (required)

Unauthenticated example (expect 402):

```bash
curl -i -X POST -H 'Content-Type: application/json' https://x402.greenhead.io/v1/xrpl/wallet-score
```

### POST /v1/xrpl/token-risk

Rug-pull probability from AMM liquidity, holder concentration, and issuer trust lines via Grok. 2000 drops.

- Price: 0.002 XRP or 0.01 RLUSD (issuer rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De)
- Network: `xrpl:0`
- Auth: header `X-Payment-Txid` = validated Payment hash to `payTo` from the catalog

JSON body:
  - `currency`: Token currency code (required)
  - `issuer`: XRPL classic address of the token issuer (required)

Unauthenticated example (expect 402):

```bash
curl -i -X POST -H 'Content-Type: application/json' https://x402.greenhead.io/v1/xrpl/token-risk
```

### POST /v1/grok/market-summary

Plain-English XRPL daily market digest from the top 10 GeckoTerminal pools via Grok. 3000 drops. Body optional.

- Price: 0.003 XRP or 0.01 RLUSD (issuer rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De)
- Network: `xrpl:0`
- Auth: header `X-Payment-Txid` = validated Payment hash to `payTo` from the catalog


Unauthenticated example (expect 402):

```bash
curl -i -X POST -H 'Content-Type: application/json' https://x402.greenhead.io/v1/grok/market-summary
```

### GET /v1/base/ping

Prove route for Base mainnet USDC x402 (eip155:8453). HTTP 200 after facilitator verify+settle. Priced as the cheapest SKU (0.002 face → 2000 USDC atomic when Base is enabled).

- Price: 0.002 XRP or 0.01 RLUSD (issuer rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De)
- Network: `xrpl:0`
- Auth: header `X-Payment-Txid` = validated Payment hash to `payTo` from the catalog


Unauthenticated example (expect 402):

```bash
curl -i https://x402.greenhead.io/v1/base/ping
```