⌨️ CLI Reference

Command-Line Reference

For technical users who prefer command-line control, want to automate their setup, or are building tooling on top of Arkeo.

🚀

Provider Setup

Run these commands on the server where your blockchain node is running. You'll need Go 1.21+ and a publicly reachable IP with port 3636 open.

Install arkeod

bash

git clone https://github.com/arkeonetwork/arkeo.git
cd arkeo
make install
make tools

Installs the arkeod binary and supporting tools. Verify with arkeod version.

Create a hot wallet

bash

arkeod keys add provider-hot-wallet --keyring-backend test

Creates a dedicated signing key for your sentinel. Use a hot wallet with minimal funds — not your main wallet. Save the mnemonic securely.

Bond your provider service

bash

arkeod tx arkeo bond-provider \
  --from="<your-key>" \
  --fees="200uarkeo" \
  --keyring-backend="test" \
  -b sync -y \
  "$PUBKEY" "$SERVICE" -- "$BOND_AMOUNT"

Variable	Description
$PUBKEY	Your provider bech32 pubkey (arkeopub1...)
$SERVICE	Service name, e.g. `base-mainnet-fullnode`
$BOND_AMOUNT	Amount in uarkeo. `1000000uarkeo` = 1 ARKEO (minimum recommended)

Stakes ARKEO as collateral and registers your provider on-chain. Run once per service you want to offer.

Configure metadata & rates

bash

arkeod tx arkeo mod-provider \
  "$PUBKEY" "$SERVICE" "$SENTINEL_URI" \
  "$NONCE" "$STATUS" \
  "$MIN_DURATION" "$MAX_DURATION" \
  "$SUB_RATES" "$PAYG_RATES" \
  "$SETTLEMENT_DURATION" \
  --from="<your-key>" \
  --fees="200uarkeo" \
  --keyring-backend="test" -y

Variable	Description
$SENTINEL_URI	Your public sentinel URL, e.g. `https://myprovider.com`
$NONCE	Increment by 1 each time you update (start at 1)
$STATUS	`1` = ONLINE, `2` = OFFLINE
$MIN_DURATION	Minimum contract length in blocks
$MAX_DURATION	Maximum contract length in blocks
$SUB_RATES	Subscription rate in uarkeo, e.g. `1uarkeo`
$PAYG_RATES	Pay-as-you-go rate per request, e.g. `200uarkeo`
$SETTLEMENT_DURATION	Blocks after contract end to submit claims (e.g. `1000`)

Sets your sentinel URL, pricing, and contract parameters on-chain. Re-run whenever you update your config.

Configure your sentinel

yaml

# sentinel_config.yaml
provider:
  pubkey: "<your-bech32-pubkey>"
  name: "My Provider"

services:
  - name: base-mainnet-fullnode
    id: 89
    type: base
    rpc_url: http://localhost:8545

api:
  listen_addr: "0.0.0.0:3636"

⚠️Port 3636 must be publicly accessible. Run curl http://YOUR-PUBLIC-IP:3636/metadata.json from an external machine to confirm.

The sentinel reverse-proxies requests to your node and handles billing. See the Arkeo GitHub for the full sentinel config reference.

Verify your provider is live

bash

# Check sentinel is responding
curl https://your-sentinel-url/metadata.json

# Check on-chain registration
arkeod query arkeo show-provider $PUBKEY

# List all online providers
arkeod query arkeo list-providers --output json | \
  jq '.provider[] | select(.status=="ONLINE")'

Claim earnings

bash

arkeod tx arkeo claim-contract-income \
  "$CONTRACT_ID" "$NONCE" "$SIGNATURE" nil \
  --from "$PROVIDER_KEY" \
  --fees="200uarkeo" \
  --keyring-backend="test" -y

⚠️Claims not submitted within the settlement window after contract expiry are lost permanently. Set up a cron job to run this regularly.

Submits accumulated PAYG claims to the chain for settlement. Run on a schedule — daily at minimum, hourly is safer.

📡

Subscriber Setup

Open contracts and query providers directly from the command line. Useful for automation, scripting, or integrating Arkeo into your own tooling.

Find an online provider

bash

# List all online providers
arkeod query arkeo list-providers --output json | \
  jq '.provider[] | select(.status=="ONLINE")'

# Filter by service number (e.g. service 89 = base-mainnet-fullnode)
arkeod query arkeo list-providers --output json | \
  jq '.provider[] | select(.status=="ONLINE" and .service==89)'

# List all available services and their IDs
arkeod query arkeo all-services

Open a contract

bash

arkeod tx arkeo open-contract \
  "$PROVIDER_PUBKEY" "$SERVICE" "$CLIENT_PUBKEY" \
  "$CONTRACT_TYPE" "$DEPOSIT" "$DURATION" \
  "$RATE" "$QPM" "$SETTLEMENT" "$AUTH" "$DELEGATE" \
  --from="$CLIENT_KEY" \
  --fees="200uarkeo" \
  --keyring-backend="test" -y

Variable	Description
$CONTRACT_TYPE	`1` = Subscription, `2` = Pay-as-you-go
$DEPOSIT	Tokens to lock, e.g. `5000000uarkeo`. Unused PAYG deposit is returned.
$DURATION	Contract length in blocks
$RATE	Rate in uarkeo (must match or exceed provider's minimum)
$QPM	Queries per minute limit. `0` = unlimited
$SETTLEMENT	Settlement duration in blocks after contract ends
$AUTH	`0` = open access, `1` = whitelist
$DELEGATE	Delegate pubkey for signing. Use `nil` if none.

Make requests

bash — Subscription

# Subscription: just pass the contract ID — no signing needed
curl "https://PROVIDER-SENTINEL:3636/SERVICE?arkauth=$CONTRACT_ID" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

bash — PAYG (signed)

# 1. Get current nonce
NONCE=$(curl -s "https://PROVIDER:3636/claims?contract_id=$ID&client=$PUBKEY" | jq .highestNonce)
NEXT_NONCE=$((NONCE + 1))

# 2. Sign the claim (message format: CONTRACT_ID:NONCE: — note trailing colon)
MSG="$CONTRACT_ID:$NEXT_NONCE:"
SIG=$(signhere -u "$KEY" -m "$MSG" | tail -n 1)

# 3. Make the request
curl "https://PROVIDER:3636/SERVICE?arkauth=$CONTRACT_ID:$PUBKEY:$NEXT_NONCE:$SIG" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

PAYG requires signing each request. The nonce must increment with every request. Arkauth format: {contractId}:{pubkey}:{nonce}:{sig}

Check your contract

bash

# Show a specific contract
arkeod query arkeo show-contract $CONTRACT_ID

# List all your contracts
arkeod query arkeo list-contracts --output json | \
  jq '.contract[] | select(.client=="$PUBKEY")'

# Check your balance
arkeod query bank balances $ADDRESS

⚡

x402 Setup

x402 lets AI agents pay per-request in USDC — no subscription contract needed on the agent side. You run a lightweight proxy on your server that sits in front of your Arkeo provider endpoint.

💡Want auto-generated code? Use the x402 Setup Wizard → to pick your framework and get copy-paste ready code.

Open a backing Arkeo contract

bash

# Example: open PAYG contract with 10 ARKEO deposit on Base
arkeod tx arkeo open-contract \
  "$PROVIDER_PUBKEY" "base-mainnet-fullnode" "$YOUR_PUBKEY" \
  2 "10000000uarkeo" "5000000" \
  "200" "0" "1000" "0" "nil" \
  --from="$YOUR_KEY" \
  --fees="200uarkeo" \
  --keyring-backend="test" -y

Your x402 proxy uses this PAYG contract to authenticate requests to the Arkeo provider. The proxy signs each request with its delegate key. Save the contract ID — you'll need it in your proxy config.

Install x402 middleware

bash — Node.js / Express

npm install express @x402/express @x402/core @x402/evm

bash — Node.js / Hono

npm install hono @x402/hono @x402/core @x402/evm

bash — Python / FastAPI

pip install fastapi uvicorn x402

bash — Go / Gin

go get github.com/coinbase/x402/go/x402

Test your x402 endpoint

bash

# Should return HTTP 402 Payment Required (expected — means it's working)
curl -i https://your-proxy-url/

# Verify your backing contract is active
arkeod query arkeo show-contract $CONTRACT_ID

# Monitor request usage
curl "https://your-arkeo-provider:3636/claims?contract_id=$CONTRACT_ID&client=$YOUR_PUBKEY"

A 402 response on the bare endpoint is correct — it means the payment wall is working. AI agent clients using the x402 protocol will handle the payment flow automatically.

⚡

Quick Reference

Common commands for day-to-day use.

Show provider

arkeod query arkeo show-provider $PUBKEY

List online providers

arkeod query arkeo list-providers \
  --output json | jq \
  '.provider[] | select(.status=="ONLINE")'

Show contract

arkeod query arkeo show-contract $CONTRACT_ID

List my contracts

arkeod query arkeo list-contracts \
  --output json | jq \
  '.contract[] | select(.client=="$PUBKEY")'

Check balance

arkeod query bank balances $ADDRESS

List all services

arkeod query arkeo all-services

Provider logs (Docker)

docker logs arkeo-data-engine-provider -f

Subscriber logs (Docker)

docker logs arkeo-data-engine-subscriber -f

Sentinel logs (systemd)

journalctl -u sentinel -f

Check open claims

curl http://localhost:3636/open-claims