Setup guides & FAQ

Get your API key

After completing checkout, NodeGhost will automatically send your API key to the email address you used at signup. The key looks like this:

Keep this key private — it controls access to your plan's request quota. If you lose it, contact [email protected] and we'll reissue one.

Using the API

NodeGhost is a drop-in replacement for the OpenAI API. There are three ways to use it depending on how you onboarded.

Path 1 — ng- key (Stripe or USDC)

If you signed up via Stripe or paid with USDC, you have an ng- API key. Register your model endpoint once, then use it like any OpenAI-compatible API:

Path 2 — Native POKT app stake

If you staked a POKT application wallet directly on Shannon mainnet, use the /pokt/ endpoint. Pass your model provider API key as Authorization and specify your provider with X-Endpoint:

Path 3 — Python (ng- key)

Supported model providers

Rate limits

Each plan includes a monthly request quota. Requests reset on the 1st of each month.

1 REQUEST = 1 POKT RELAY = 400,000 COMPUTE UNITS

Home Assistant overview

NodeGhost works as the AI brain for Home Assistant — giving you a genuinely intelligent voice assistant that runs privately, without sending your conversations to Google, Amazon, or Apple.

The full private stack looks like this:

Total cost: $1/month on the Basic plan. Smarter than Alexa, more private than everything.

Install the integration

NodeGhost uses the Extended OpenAI Conversation integration available through HACS (Home Assistant Community Store).

Step 1 — Install HACS

If you don't have HACS installed yet, follow the official guide at hacs.xyz. It adds a community add-on store to your Home Assistant instance.

Step 2 — Install Extended OpenAI Conversation

Add local voice (Whisper + Piper)

For fully private voice — no cloud at any step — install the local speech add-ons. These run entirely on your Home Assistant hardware.

Install Whisper (speech to text)

Install Piper (text to speech)

Repeat the same steps for the "Piper" add-on. Once both are installed, go to Settings → Voice Assistants and set:

Remote access

To use the Home Assistant app and your NodeGhost voice assistant when you're away from home, you need a way to reach your Pi remotely. The free option is a Cloudflare Tunnel.

Option A — Cloudflare Tunnel (free)

Option B — Nabu Casa ($6.50/month)

Nabu Casa provides an easy one-click remote access tunnel. It works alongside NodeGhost — Nabu Casa handles the network tunnel, NodeGhost handles the AI. Go to Settings → Home Assistant Cloud to subscribe.

Run your own AI model through NodeGhost

NodeGhost is a privacy-preserving inference gateway — not a managed model service. Register your own OpenAI-compatible endpoint and route all inference through NodeGhost's infrastructure, giving you complete control over which AI model processes your data while NodeGhost handles auth, rate limiting, and decentralized routing.

This means you can run an open source model like Llama, Mistral, or Qwen on your own server, point NodeGhost at it, and use the same https://nodeghost.ai/v1 endpoint you already know. Your model does the inference. NodeGhost handles everything else.

Why run your own model?

There are several reasons you might want to bring your own endpoint:

• You've fine-tuned a model on proprietary data and need inference for it
• You want complete privacy — no third party sees your prompts at any layer
• You want to use a specific open source model not available through NodeGhost's default backend
• You're building a product on top of your own model and need auth and rate limiting infrastructure
• You want to protect your model endpoint from being exposed publicly

How it works

When you register a custom endpoint, NodeGhost stores it linked to your API key. Every inference request you make is authenticated and rate limited as normal — then forwarded to your endpoint via the POKT network. Your model processes the request and returns the response through NodeGhost back to your application.

Your endpoint is never exposed publicly. All traffic enters through nodeghost.ai/v1 and NodeGhost proxies it to your server privately.

Register your endpoint

Your endpoint must be publicly accessible over HTTPS and OpenAI-compatible. Any server running Ollama, LM Studio, vLLM, or a custom FastAPI wrapper will work.

Step 1 — Run an OpenAI-compatible model server

The most common option is Ollama. Install it on any VPS or server and expose it publicly:

Step 2 — Register your endpoint with NodeGhost

Call the registration endpoint with your ng- API key:

NodeGhost will verify your endpoint is reachable and return a confirmation:

Step 3 — Use NodeGhost as normal

Nothing changes in your application. Keep using https://nodeghost.ai/v1 with your ng- key. NodeGhost silently routes to your registered model endpoint:

Check your routing status

Remove your custom endpoint

To remove your registered endpoint:

Full privacy stack — zero third parties

If complete privacy is your goal — where no third party ever sees the content of your AI requests — this is the architecture that achieves it.

The full stack

Here's every component and who controls it:

What this means for privacy

With this setup your prompts travel from your application to NodeGhost for authentication and routing through the POKT decentralized network, then directly to your own server. The request enters through a gateway with no single point of control — POKT's on-chain verification ensures the routing is transparent and auditable. The model that processes your request runs on hardware you control. No AI company, no cloud provider, no GPU farm ever sees what you're asking.

NodeGhost sees that a request happened — the timestamp and your API key — but never the content. That metadata is used only for rate limiting and is retained for 90 days.

Recommended models for self-hosting

These open source models run well on a modest VPS with 16GB+ RAM:

What is POKT?

POKT is the native token of Pocket Network — the decentralized infrastructure that NodeGhost is built on. Every AI request you make through NodeGhost is routed through the POKT Shannon network, verified on-chain, and settled between gateway operators and node suppliers.

This is what makes NodeGhost fundamentally different from other AI providers — the routing is on-chain and decentralized, so there's no single company that could log, monitor, or sell your requests even if they wanted to.

For most users, POKT is invisible — you just use your ng- API key and pay via Stripe. But if you're crypto-native and want to interact with the network directly, you can stake your own application wallet and pay per relay in POKT tokens.

Stake your app wallet

Advanced users can bypass the Stripe subscription entirely by staking a POKT application wallet directly on Shannon mainnet. This gives you pay-per-relay access at the rate set by each service — for example ai-inference is priced at $0.0004 per relay. Each service has its own relay price, so the cost depends on which service you stake against.

What you'll need

A funded POKT wallet with enough tokens to stake an application. Current minimum is 1,000 POKT. You'll also need pocketd installed on your machine.

Stake your application

Your app-stake-config.yaml should specify the ai-inference service:

Once staked, delegate your application to NodeGhost's gateway address:

Gateway address for reference:

Using the gateway after staking

Once staked and delegated, hit the native POKT endpoint with your model provider's API key as Authorization and your provider URL as X-Endpoint:

Supported providers via X-Endpoint: OpenAI, DeepSeek, Groq, Anthropic, or any OpenAI-compatible self-hosted model. If X-Endpoint is omitted, defaults to https://api.openai.com.

Autonomous AI payments

NodeGhost supports fully autonomous agent onboarding via USDC on the Base network. An AI agent can pay for its own inference credits without any human involvement — no email, no credit card, no signup form.

The payment flow is designed for agents that hold their own crypto wallets and need to autonomously manage their inference budget. Every wallet is screened by AnChain.AI on each payment. NodeGhost does not store wallet addresses or payment history — only a transaction hash is retained to prevent duplicate crediting.

Payment parameters

$10 USDC → $9.70 after 3% fee → 24,250 relays  |  $500 USDC → $485 after fee → 1,212,500 relays

Step 1 — Check eligibility

Before sending payment, call this endpoint to screen your wallet and get exact payment instructions. Always call this first — it confirms your wallet is eligible and returns the current receiving address.

GET /v1/agent/payment-info?wallet=0xYOUR_WALLET&chain=eth

{
  "eligible": true,
  "payment": {
    "send_to": "0xCE8C9AaBA3Eff65516AeA85c5a8375Ff8995f332",
    "network": "Base",
    "token": "USDC",
    "min_payment_usdc": 10,
    "max_payment_usdc": 500,
    "service_fee": "3%",
    "price_per_relay": 0.0004,
    "example_min": "$10 → 24,249 relays after 3% fee",
    "example_max": "$500 → 1,212,500 relays after 3% fee"
  },
  "next_steps": [...]
}

If your wallet is flagged by AnChain.AI risk screening, the response will return eligible: false. Do not send payment if ineligible — it will not be credited.

Step 2 — Send payment

Send USDC to the receiving address on the Base network. NodeGhost automatically polls the Base network every 2 minutes for incoming payments — you do not need to notify NodeGhost or call any endpoint. Once detected, your wallet is re-screened by AnChain.AI, the 3% fee is deducted, and relays are credited automatically.

How NodeGhost matches your payment to an account

NodeGhost identifies which account to credit using this priority order:

• If your ng- key is included in the transaction memo (recommended) — credits that key directly
• If your wallet address has previously paid — credits the existing account linked to that wallet
• If neither — creates a new account for your wallet address and credits it

Optional but recommended: Include your ng- API key in the transaction input data field (hex encoded). This ensures instant matching with no lookup step:

// Convert your ng- key to hex for the transaction data field
const apiKey = 'ng-yourkey';
const hexData = '0x' + Buffer.from(apiKey).toString('hex');
// Use hexData as the transaction input/data field when sending USDC

Payment limits

Step 3 — Confirm credits

NodeGhost credits relays automatically — you don't need to call any endpoint to trigger it. However you can poll this endpoint with your transaction hash to confirm relays have been credited and check your current balance:

POST /v1/agent/payment-status
Content-Type: application/json

{
  "tx_hash": "0xYOUR_TRANSACTION_HASH",
  "api_key": "ng-yourkey"
}

{
  "found": true,
  "tx_hash": "0x...",
  "status": "credited",
  "usdc_amount": 10,
  "fee_amount": 0.3,
  "usdc_after_fee": 9.7,
  "relays_credited": 24249,
  "credited_at": "2026-03-26T04:22:04Z",
  "balance": {
    "relays_used": 0,
    "relays_remaining": 24249,
    "relays_total": 24249
  }
}

{
  "found": true,
  "tx_hash": "0x...",
  "status": "below_minimum",
  "usdc_amount": 5,
  "relays_credited": 0
}

If the transaction is not yet found, the poller runs every 2 minutes — wait and try again. Once status is credited, use your ng- key at https://nodeghost.ai/v1 immediately. 1 relay = 1 request = 400,000 CU.

Full agent payment flow

For autonomous agents, the complete flow from wallet to inference looks like this:

// 1. Check eligibility and get receiving address
GET /v1/agent/payment-info?wallet=0xYOUR_WALLET&chain=eth

// 2. Send USDC on Base to the returned address
// Include ng- key in memo if you have one

// 3. Wait ~2 minutes for auto-detection, then confirm
POST /v1/agent/payment-status { tx_hash, api_key }

// 4. Use your ng- key for inference
POST /v1/chat/completions
Authorization: Bearer ng-yourkey

Hosted models

NodeGhost offers access to hosted open source models routed through the POKT decentralized network. No external API key required — just your ng- key. These models are served by independent node operators on Shannon mainnet, earning POKT relay rewards for every request.

Text generation

Access Llama 3.2 1B Instruct via the POKT decentralized network. No model API key needed — requests are handled by independent POKT node operators. Use pocket_network as the model name.

Example request (curl)

curl https://nodeghost.ai/text-generation/v1/chat/completions \
  -H "Authorization: Bearer ng-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "pocket_network",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 200
  }'

Example request (Python)

from openai import OpenAI

client = OpenAI(
    api_key="ng-your-key-here",
    base_url="https://nodeghost.ai/text-generation/v1"
)

response = client.chat.completions.create(
    model="pocket_network",
    messages=[{"role": "user", "content": "Hello!"}],
    max_tokens=200
)

print(response.choices[0].message.content)

Tools as POKT services

NodeGhost provides AI tools as first-class POKT services. Each tool call is a single relay — flat cost, no tokens consumed, no context window, completely stateless. Tools return structured data only, never raw web content, making them safe and prompt-injection resistant by design.

All tools require a valid ng- API key. Tool calls count against your relay balance — web search costs 1 relay at 50,000 CU, which is cheaper than inference (400,000 CU). This means your relay balance goes further when agents use search than when they run inference.

Web search

Search the web privately via Brave Search. Returns titles, URLs, and snippets. Routed through POKT decentralized network — the search engine never sees the agent's identity or IP address.

POST /v1/tools/search
Authorization: Bearer ng-yourkey
Content-Type: application/json

{
  "query": "your search terms",
  "count": 5
}

{
  "query": "your search terms",
  "count": 3,
  "results": [
    {
      "title": "Result title",
      "url": "https://example.com",
      "snippet": "Brief description of the result..."
    }
  ]
}

Parameters

Also supports GET requests: GET /v1/tools/search?q=your+query&count=5

Using web search as an agent tool

Web search is designed to be called by AI agents via the OpenAI tool calling format. Pass it as a tool definition in your inference request and the model will call it automatically when it needs current information:

curl https://nodeghost.ai/v1/chat/completions \
  -H "Authorization: Bearer ng-yourkey" \
  -H "X-Endpoint-Key: sk-yourmodelkey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model",
    "messages": [{"role": "user", "content": "What is the current price of POKT?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "web_search",
        "description": "Search the web for current information",
        "parameters": {
          "type": "object",
          "properties": {
            "query": {"type": "string", "description": "Search terms"}
          },
          "required": ["query"]
        }
      }
    }]
  }'

Tool discovery

Query this endpoint to discover all available NodeGhost tools, their descriptions, parameters, and endpoints. Designed for autonomous agents that need to discover available capabilities without hardcoded configuration.

GET /v1/tools

{
  "provider": "NodeGhost",
  "description": "Privacy-preserving AI tools routed through POKT",
  "cost": "1 POKT relay per tool call = 400,000 CU",
  "tools": [
    {
      "name": "web-search",
      "description": "Search the web privately via Brave Search...",
      "endpoint": "https://nodeghost.ai/v1/tools/search",
      "method": "POST",
      "parameters": { ... },
      "privacy": "Queries are never logged or stored."
    }
  ]
}

No authentication required for tool discovery. Authentication is required to call individual tools.

Frequently asked questions