Buy API Key (Model Hub)

Pay NARA via AgentX call_service to get an LLM API key (Claude, GPT, Gemini, etc.) from the Nara Model Hub.

Prerequisites

1. A wallet at ~/.config/nara/id.json (create with npx naracli wallet create if needed)
2. Sufficient NARA balance (check with npx naracli balance)
3. AgentX CLI installed (npm install -g agentx-cli or use npx agentx-cli)

Configuration

Variable	Value
Model Hub URL	https://model-api.nara.build
RPC (mainnet)	https://mainnet-api.nara.build/

IMPORTANT: Before starting, fetch the latest configuration from the /402 endpoint:

curl -s https://model-api.nara.build/402 | jq .x402

This returns the current rate, rate_description, service_id, agentx_program_id, and models. Always use these live values instead of hardcoded ones.

Step-by-Step Flow

Step 0: Fetch live config from /402

curl -s https://model-api.nara.build/402 | jq .x402

Extract from the response:

• service_id — needed for Step 2
• rate / rate_description — current NARA-to-CU exchange rate
• models — available model list for Step 4

Step 1: Check wallet and balance

npx naracli@latest address
npx naracli@latest balance -r https://mainnet-api.nara.build/

Ensure balance >= the amount you want to spend. Use rate from Step 0 to calculate CU.

Step 2: Call service on AgentX (pay NARA)

npx agentx-cli \
  -r https://mainnet-api.nara.build/ \
  -w ~/.config/nara/id.json \
  service call 1 --amount <NARA_AMOUNT>

• Use service_id from Step 0
• --amount in NARA — use rate from Step 0 to calculate how much CU you'll get
• This creates an escrow on-chain and returns a tx signature
• Note the tx signature from the output

Step 3: Charge -- exchange tx for API key

Use the Python helper or curl to call the charge endpoint. The request requires ed25519 signature authentication.

Using Python:

import json, time, urllib.request, urllib.error

# Config
WALLET_PATH = "~/.config/nara/id.json"  # expand with os.path.expanduser
BASE_URL = "https://model-api.nara.build"
TX_SIG = "<tx-signature-from-step-2>"
ADDRESS = "<your-wallet-address>"

# 1. Build signing message
ts = str(int(time.time()))
message = f"address={ADDRESS}&ts={ts}&tx={TX_SIG}"

# 2. Sign with ed25519 (nacl)
from nacl.signing import SigningKey
import os
with open(os.path.expanduser(WALLET_PATH)) as f:
    secret = bytes(json.load(f))
sk = SigningKey(secret[:32])
sig = sk.sign(message.encode()).signature

# 3. Base58 encode signature
ALPHABET = b'123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
def b58encode(data):
    n = int.from_bytes(data, 'big')
    r = []
    while n > 0:
        n, rem = divmod(n, 58)
        r.append(ALPHABET[rem:rem+1])
    for b in data:
        if b == 0: r.append(b'1')
        else: break
    return b''.join(reversed(r)).decode()

sign_b58 = b58encode(sig)

# 4. Call charge endpoint
url = f"{BASE_URL}/model-hub-api/charge?address={ADDRESS}&tx={TX_SIG}&ts={ts}&sign={sign_b58}"
req = urllib.request.Request(url)
try:
    with urllib.request.urlopen(req) as resp:
        result = json.loads(resp.read())
        print(json.dumps(result, indent=2))
        # result.data.api_key is your new API key
        # result.data.balance_added is the CU credited
except urllib.error.HTTPError as e:
    print(f"Error {e.code}: {json.loads(e.read())}")

Step 4: Use the API key

The returned api_key can be used with OpenAI-compatible endpoints:

curl https://model-api.nara.build/v1/chat/completions \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-from-step-0>",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Use the models list from Step 0 /402 response for available model names.

Other Endpoints

Check balance and API key

GET /model-hub-api/user/info?address=<addr>&ts=<ts>&sign=<sign>

Returns: { api_key, balance, balance_unit, api_base }

Reset API key

GET /model-hub-api/user/reset-key?address=<addr>&ts=<ts>&sign=<sign>

Deletes old key and creates a new one.

Payment info (X402)

GET /402

Returns payment method details, supported models, and endpoint documentation.

Pricing

Pricing is dynamic. Always check the /402 endpoint for the current rate and rate_description.

The minimum charge is 1 CU worth of NARA (calculated from the current rate). The 2% platform fee is deducted by AgentX escrow.

Troubleshooting

• "charge amount too small": Send enough NARA to get at least 1 CU (check current rate via /402)
• "transaction already processed": Each call_service tx can only be used once
• "service_id mismatch": Make sure you used the service_id from /402
• "ServiceCall caller does not match": The address param must match the caller in the tx
• "transaction not found": Wait a few seconds for the tx to confirm, then retry