# NectarPay

NectarPay is an x402-paid API for creating Hive blockchain accounts from a sponsor account's pre-claimed account creation tickets.

Base URL: use the origin serving this file.

## Why NectarPay Exists

Hive uses an inverted fee model compared to most blockchains: accounts have a small creation cost, but once created, all transactions are feeless. There are no gas fees, no per-transaction charges, and no failed transactions from underfunded wallets.

This makes Hive exceptionally agent-friendly. After account creation, an agent can read, write, and transact on-chain indefinitely without any further payment infrastructure. The account itself holds Resource Credits that regenerate automatically, powering feeless activity at scale.

The one friction point is bootstrapping: creating a new Hive account requires a claim ticket held by an existing account. NectarPay solves this for agents and developers by accepting a one-time payment (see current price at `GET /api/config`) via x402 (EVM/stablecoin) and handling the Hive-side account creation through a sponsor account's pre-claimed tickets.

Pay once in crypto you already have. Get a feeless blockchain account forever.

## What Agents Can Do

- Check whether a Hive username is valid and available.
- Read public pricing/network configuration.
- Generate Hive authority keys from a username and passphrase, or ask NectarPay to generate a passphrase.
- Pay the x402-protected account creation endpoint.
- Retrieve purchase status by purchase ID when available.

## Public Endpoints

### GET /api/health

Returns non-secret health checks for application config, x402 facilitator reachability, and Hive RPC reachability.

### GET /api/config

Returns public configuration:

```json
{
  "account_price_usd": "1.00",
  "account_price_label": "$1.00",
  "blockchain_network": "base",
  "evm_network_id": "eip155:8453"
}
```

### GET /api/check-username/{username}

Checks Hive username format and blockchain availability.

### GET /api/sponsor/claims

Returns the configured sponsor account and pending claimed-account ticket count.

### POST /api/keys/generate

Derives Hive owner, active, posting, and memo keys.

Request:

```json
{
  "username": "desired-account",
  "password": "optional-passphrase"
}
```

If `password` is omitted, NectarPay generates one. This response can include private keys. Treat it as sensitive and use HTTPS.

### POST /api/accounts/create

x402-protected endpoint for bot/API clients. Use JSON and expect JSON.

CRITICAL KEY CUSTODY RULE:

- This endpoint creates the account but does NOT return private keys.
- This endpoint accepts public keys only. It does not accept `password`.
- Generate Hive keys locally, or call `POST /api/keys/generate` first and securely store the returned credentials.
- Then call this endpoint with the four public keys.

Required request shape:

```json
{
  "username": "desired-account",
  "owner_key": "STM...",
  "active_key": "STM...",
  "posting_key": "STM...",
  "memo_key": "STM..."
}
```

Unpaid response: HTTP 402 with x402 v2 `PAYMENT-REQUIRED`.

Paid retry: send the same request with x402 v2 `PAYMENT-SIGNATURE`.

Successful response:

```json
{
  "success": true,
  "username": "desired-account",
  "tx_id": "hive-transaction-id",
  "message": "Account 'desired-account' successfully created!"
}
```

Successful responses include the x402 v2 `PAYMENT-RESPONSE` settlement header when settlement succeeds.

Successful responses do not include private keys, public keys, or the passphrase. The client must already control account credentials before paying.

### POST /api/checkout

Browser checkout creation endpoint. It accepts `username` plus all four public keys, stores a pending checkout server-side, and returns `checkout_id` plus `pay_url`.

Browser checkout does not accept `password`. The browser must derive keys locally and send only public keys so passphrases and private keys are never stored in the checkout database.

Do not use this for agents unless you specifically need browser paywall behavior. Agents should prefer `POST /api/accounts/create`.

### GET /checkout/{checkout_id}

x402-protected browser checkout completion route. It loads pending checkout data server-side, creates the Hive account after payment, and returns an HTML handoff to the frontend success page.

Do not put passphrases or key material in query parameters. `GET /api/accounts/create` is intentionally unsupported.

### GET /api/purchases/{purchase_id}

Returns non-secret purchase ledger status when a purchase ID is known.

## x402 Notes

- Current payment scheme: exact EVM payment.
- Current price: read from `GET /api/config`.
- Current network: read `evm_network_id` from `GET /api/config`.
- Use x402 v2 headers:
  - `PAYMENT-REQUIRED` from the 402 response.
  - `PAYMENT-SIGNATURE` on the paid retry.
  - `PAYMENT-RESPONSE` on successful settlement.
- Legacy `X-PAYMENT` may be accepted by upstream middleware, but new clients should use v2.

## Safety Notes

- Do not log or persist user passphrases or private keys.
- Send public Hive keys to paid account creation. Do not send passphrases to `POST /api/accounts/create`.
- Re-check username availability before payment when possible.
- If the account already exists after a retry, query purchase status or contact the service owner instead of paying again.
- In test or dry-run environments, Hive account creation may be configured with `HIVE_NOBROADCAST=true`, meaning a Hive transaction is built but not broadcast.

## Recommended Agent Flow

1. `GET /api/config`
2. `GET /api/check-username/{username}`
3. Generate Hive keys locally, or call `POST /api/keys/generate` and securely store the returned credentials
4. Call `POST /api/accounts/create` with the four public keys
5. If HTTP 402, satisfy x402 using `PAYMENT-REQUIRED`
6. Retry `POST /api/accounts/create` with `PAYMENT-SIGNATURE`
7. Store returned `username`, `tx_id`, and `PAYMENT-RESPONSE`