Bitnow Control Plane (API-Driven) Skill

This skill describes end-to-end operational workflows for the Bitnow network, strictly from an API usage perspective.

• - Wallet-based authentication (signature flow)
• On-chain balance top-up and verification via API
• Consumer API key lifecycle (create, list, revoke)
• Model inference via API key
• Query balance and usage via HTTP API

Assumptions:

• - A gateway HTTP API exists (e.g. https://gateway-test.bitnow.ai)
• All workflows are CLI-, Curl or script-oriented, no UI assistance
• Support chain is base sepolia, chain id is 8453

Replace all <BASE_URL> with the actual gateway URL as needed.

1. Wallet-based registration & session (API focus)

Note: The message signing must be performed by the user using their EVM address and can only initiate or verify, not produce signatures. if you have no wallet address, you need to create your own one, and store it safely.

Typical API sequence:

1. 1. Request a SIWE-style login challenge and message:

   curl -sS -X POST "<BASE_URL>/v1/auth/wallet/challenge" \
     -H "Content-Type: application/json" \
     -d '{
       "wallet_address": "<EVM_WALLET_ADDRESS>",
       "chain_id": "8453"
     }'
   

   {
     "message": "Sign-In With Ethereum message...",
     "nonce": "random-nonce",
     "wallet_address": "0x...",
     "chain_id": "8453"
   }
   

1. 2. User signs the message off-chain (with their wallet).
2. Submit the signed message to the gateway for verification:

   curl -sS -X POST "<BASE_URL>/v1/auth/wallet/verify" \
     -H "Content-Type: application/json" \
     -d '{
       "wallet_address": "<EVM_WALLET_ADDRESS>",
       "nonce": "random-nonce",
       "signature": "<WALLET_SIGNATURE>"
     }'
   

   {
     "login_token": "sess-...",
     "expires_at": "2025-01-01T00:00:00Z",
     "consumer": {
       "id": "consumer-uuid",
       "wallet_address": "0x..."
     },
     "session": {
       "id": "session-uuid"
     }
   }
   

1. 4. The login_token (starting with sess-) is used as a session token:

Check:

• - Session token is present and sent in the Authorization: Bearer sess-... header during all subsequent calls requiring authentication.

2. On-chain Top-up Flow (API Verification)

Top-up is performed on-chain (USDC to a ConsumerDeposit contract), tracked by off-chain indexers. The API lets you verify the result.
you can use your own endpoint, also you can use this default one: INLINECODE7

• - User transfers USDC to the ConsumerDeposit contract with proper calldata.
• Backend credits the consumer balance after L1/L2 tx confirmation (indexer-driven).
• USDC address is: 0x10065E7b353371DD2e12348e7094cC774638EbEB
• ConsumerDeposit contract address is: 0xB0E9ebf19AB710d3353c7F637DC55329d9727dCc

Verify balance via API:

CODEBLOCK4

Sample response:

CODEBLOCK5

For troubleshooting:

• - Compare on-chain transaction hash with API-observed balance_usdc value to detect indexer or sync problems.

3. Consumer API Key Lifecycle (API-only)

Consumers use API keys to access models without a session.

3.1 Create API Key

Requires a valid session token (login_token from section 1).

CODEBLOCK6

Sample response (save the api_key securely; only returned once!):

CODEBLOCK7

3.2 List API Keys

CODEBLOCK8

3.3 Revoke API Key

CODEBLOCK9

The key status will be set to revoked; subsequent calls using that key will fail with an auth error.

3.4 Declare a Parent (Child → Parent Relationship)

Use this to let a child account declare a parent. This requires a wallet signature over a structured message. The signature must be produced by the child wallet.

Endpoint:

CODEBLOCK10

Notes:

• - issued_at is Unix seconds. It must be within the last 5 minutes and not more than 1 minute in the future.
• The signed message must be exactly:

Success response (201):

CODEBLOCK12

Common errors:

• - 400 INVALID_REQUEST invalid body
• INLINECODE15 issued_at out of window
• INLINECODE17 parent not found
• INLINECODE18 cannot declare yourself
• INLINECODE19 signature not from child wallet
• INLINECODE20 parent already declared

4. Model Inference API Usage

With a valid CONSUMER_API_KEY, models can be queried.

4.1 List Available Models

CODEBLOCK13

Verify model existence before usage (check returned list).

4.2 Completion/Chat Endpoint

CODEBLOCK14

API error handling:

• - 401: Invalid/expired key; check Authorization header
• INLINECODE23: Insufficient balance
• INLINECODE24: Model not found (check MODEL_NOT_FOUND)
• Review returned JSON fields error.code, INLINECODE27

5. Query Balance and Usage (API)

5.1 Balance Query

(refer to section 2, /v1/balance endpoint)

5.2 Usage Metrics

Usage is exposed via a consumer-scoped endpoint:

CODEBLOCK15

The response is proxied from the Registry and typically includes fields like:

• - id – usage record id
• INLINECODE30 / created_at – when the call was recorded
• INLINECODE32 – model name (e.g. gpt-4o-mini)
• INLINECODE34 – prompt token count
• INLINECODE35 – completion token count
• INLINECODE36 – cost in USDC for this call
• INLINECODE37 – optional, which consumer API key was used

A typical workflow might aggregate usage per model or timeframe to analyze cost and token usage.

6. Supplier/Provider API Workflows (Advanced)

For upstream providers only:

• - Register API key provider (upstream key vaulted via Key Vault):

  curl -sS -X POST "<BASE_URL>/v1/suppliers/api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "wallet_address": "<SUPPLIER_WALLET>",
      "provider": "openai",
      "api_key": "sk-upstream-...",
      "models": ["gpt-4o", "gpt-4o-mini"],
      "price_per_million_tokens": "2.50",
      "max_requests_per_hour": 3600
    }'
  

• - Register GPU node (per-wallet GPU supplier):

  curl -sS -X POST "<BASE_URL>/v1/suppliers/gpu" \
    -H "Content-Type: application/json" \
    -d '{
      "wallet_address": "<SUPPLIER_WALLET>",
      "models": ["gpt-4o", "claude-3-5-sonnet-20241022"],
      "price_per_million_tokens": "5.00",
      "max_requests_per_hour": 1000,
      "endpoint": {
        "base_url": "https://gpu-node.example.com",
        "backend_type": "openai_http",
        "timeout": 30000,
        "auth_type": "bearer",
        "auth_value": "upstream-node-token",
        "health_endpoint": "/healthz"
      }
    }'
  

• - Update GPU node config:

  curl -sS -X PATCH "<BASE_URL>/v1/suppliers/gpu/<ID>" \
    -H "Content-Type: application/json" \
    -d '{
      "models": ["gpt-4o", "gpt-4o-mini"],
      "price_per_million_tokens": "4.50",
      "max_requests_per_hour": 2000,
      "endpoint": {
        "base_url": "https://gpu-node.example.com",
        "backend_type": "openai_http",
        "timeout": 45000,
        "auth_type": "bearer",
        "auth_value": "rotated-node-token",
        "health_endpoint": "/healthz"
      }
    }'
  

• - Query provider/model metadata as needed:

  curl -sS -X GET "<BASE_URL>/v1/metadata/providers"
  curl -sS -X GET "<BASE_URL>/v1/metadata/models"
  

7. Usage Guidelines for AI Agents

When handling Bitnow network operational support, follow these best practices:

1. 1. Map user questions directly to the appropriate API workflow without reference to UI.

1. 2. Provide concrete curl commands tailored to the user's configuration (<BASE_URL>, <CONSUMER_API_KEY>, etc).
2. When troubleshooting:

1. 4. Be concise, focus on actionable commands and next steps.
2. Only provide background technical details if specifically requested.