Pricing Configuration - Quick Start Guide

5-Minute Overview

The pricing configuration system provides a centralized, validated way to manage all premium endpoint pricing in StellarMind.

Key Files

File	Purpose
`src/pricing.config.js`	Centralized pricing configuration
`src/pricing.validator.js`	Validation logic
`src/server.js`	Updated to use pricing config
`tests/pricing.validator.test.js`	Unit tests
`tests/pricing.integration.test.js`	Integration tests

How It Works

1. Configuration

All pricing is defined in one place:

// src/pricing.config.js
export const pricingConfig = {
  endpoints: {
    'GET /api/premium/research': {
      price: '$0.01',
      agent: 'research-bot',
      description: 'Research Agent',
      emoji: '🔬',
    },
    // ... more endpoints
  },
};

2. Validation

Configuration is validated at startup:

// src/server.js
const pricingValidation = validateAll(pricingConfig, {
  network: config.network,
  payTo: config.serverAddress,
});

if (!pricingValidation.valid) {
  console.error('❌ FATAL: Pricing configuration validation failed');
  process.exit(1);
}

3. Usage

Pricing is used throughout the application:

// Get price for endpoint
const price = pricingConfig.getPrice('GET /api/premium/research');

// Generate x402 middleware config
const x402Config = pricingConfig.getX402Config(config);

// Get all pricing info for status endpoint
const allPricing = pricingConfig.getAllPricingInfo();

Common Tasks

Change a Price

Before:

// In src/server.js - HARDCODED
'GET /api/premium/research': {
  accepts: {
    scheme: 'exact',
    price: '$0.01',  // ← Change here
    // ...
  },
},

After:

// In src/pricing.config.js
'GET /api/premium/research': {
  price: '$0.02',  // ← Change here
  agent: 'research-bot',
  description: 'Research Agent',
  emoji: '🔬',
},

This single change automatically updates:

✅ x402 middleware configuration
✅ Status endpoint output
✅ Broadcast events
✅ All pricing lookups

Add a New Premium Endpoint

Add to src/pricing.config.js:

'GET /api/premium/translate': {
  price: '$0.02',
  agent: 'translator-bot',
  description: 'Translation Agent',
  emoji: '🌐',
},

Add endpoint handler in src/server.js:

app.get('/api/premium/translate', async (req, res) => {
  try {
    const text = req.query.text || '';
    const priceInfo = pricingConfig.getEndpointInfo('GET /api/premium/translate');
    const cost = priceInfo.price.slice(1);
    broadcast({ type: 'agent_call', agent: `${priceInfo.emoji} Translator Agent`, agentId: 'translator-bot', input: text.substring(0, 100), cost, timestamp: new Date().toISOString() });
    const result = await runTranslate(text);
    broadcast({ type: 'agent_response', agent: `${priceInfo.emoji} Translator Agent`, agentId: 'translator-bot', resultPreview: result.substring(0, 150), cost, timestamp: new Date().toISOString() });
    res.json({ agent: 'translator-bot', result, model: MODEL_LABELS.translate, cost: `${cost} USDC`, paidVia: 'x402' });
  } catch (err) {
    res.status(500).json({ error: 'Translator agent temporarily unavailable', details: err.message });
  }
});

The x402 middleware will automatically protect this endpoint with the configured price.

Query Pricing Information

import { pricingConfig } from './src/pricing.config.js';

// Get price for specific endpoint
pricingConfig.getPrice('GET /api/premium/research');
// '$0.01'

// Get all premium endpoints
pricingConfig.getPremiumEndpoints();
// ['GET /api/premium/research', 'GET /api/premium/summarize', ...]

// Get endpoint info
pricingConfig.getEndpointInfo('GET /api/premium/research');
// { price: '$0.01', agent: 'research-bot', description: '...', emoji: '🔬' }

// Get all pricing info
pricingConfig.getAllPricingInfo();
// [{ endpoint: '...', price: '...', agent: '...', ... }, ...]

// Lookup by agent
pricingConfig.byAgent['research-bot'];
// { endpoint: 'GET /api/premium/research', price: '$0.01', ... }

// Lookup by price
pricingConfig.byPrice['$0.01'];
// [{ endpoint: 'GET /api/premium/research', agent: 'research-bot' }, ...]

Running Tests

Unit Tests

node tests/pricing.validator.test.js

Output:

✅ Price validation tests passed
✅ Endpoint validation tests passed
✅ Endpoint info validation tests passed
✅ Pricing config validation tests passed
✅ x402 compatibility validation tests passed
✅ Comprehensive validation tests passed
✅ Error formatting tests passed
✅ throwIfInvalid tests passed

==================================================
✅ All pricing validator tests passed!
==================================================

Integration Tests

node tests/pricing.integration.test.js

Output:

✅ Pricing config structure tests passed
✅ Pricing consistency tests passed
✅ Pricing maps tests passed
✅ Getter methods tests passed
✅ x402 configuration generation tests passed
✅ Single source of truth tests passed
✅ Pricing config validation tests passed
✅ Price distribution tests passed
✅ Endpoint naming convention tests passed

==================================================
✅ All pricing integration tests passed!
==================================================

Pricing Summary:
  Total Endpoints: 4
  Unique Agents: 4
  Price Points: 3
  Total Revenue per Call: $0.10

Price Format Rules

Prices must follow the format: $X.XX

✅ Valid prices:

$0.01 - Minimum price
$0.05 - Five cents
$1.00 - One dollar
$99.99 - Maximum reasonable price

❌ Invalid prices:

0.01 - Missing $
$0.1 - Only 1 decimal place
$0.001 - 3 decimal places
$-0.01 - Negative price
$0.00 - Zero price

Endpoint Format Rules

Endpoints must follow the format: METHOD /api/premium/name

✅ Valid endpoints:

GET /api/premium/research
POST /api/premium/analyze
PUT /api/premium/code
DELETE /api/premium/summarize
PATCH /api/premium/translate

❌ Invalid endpoints:

GET /api/research - Missing /premium/
GET /premium/research - Missing /api/
GET /api/premium/ - Missing name
INVALID /api/premium/research - Invalid HTTP method

Agent Name Rules

Agent names must be alphanumeric with hyphens.

✅ Valid agent names:

research-bot
summary-bot
analyst-bot
code-bot
translator-bot

❌ Invalid agent names:

research bot - Contains space
research_bot - Contains underscore
research.bot - Contains period
ResearchBot - Contains uppercase (use lowercase)

Error Handling

Validation Fails at Startup

If pricing configuration is invalid, the server will fail to start with a clear error message:

❌ FATAL: Pricing configuration validation failed
❌ Pricing configuration validation failed:

Errors:
  1. Invalid price for 'GET /api/premium/research': Price must be in format '$X.XX', got '0.01'
  2. Duplicate agent: 'research-bot' used in multiple endpoints

Common Errors

Error	Solution
`Price must be in format '$X.XX'`	Use `$X.XX` format (e.g., `$0.01`)
`Price cannot be negative`	Use positive price (e.g., `$0.01`)
`Price cannot be zero`	Use minimum price of `$0.01`
`Endpoint must match pattern`	Use `METHOD /api/premium/name` format
`Missing 'agent'`	Add `agent` field with agent name
`Duplicate agent`	Use unique agent names
`Agent name must be alphanumeric`	Use alphanumeric with hyphens (e.g., `research-bot`)

For more error examples, see PRICING_ERROR_EXAMPLES.md.

Status Endpoint

The /api/status endpoint now includes detailed pricing information:

curl http://localhost:3001/api/status | jq '.x402.pricing'

Output:

[
  {
    "endpoint": "GET /api/premium/research",
    "price": "$0.01",
    "agent": "research-bot",
    "description": "Research Agent - Web research and information gathering",
    "emoji": "🔬"
  },
  {
    "endpoint": "GET /api/premium/summarize",
    "price": "$0.01",
    "agent": "summary-bot",
    "description": "Summary Agent - Text summarization and condensing",
    "emoji": "📝"
  },
  {
    "endpoint": "GET /api/premium/analyze",
    "price": "$0.05",
    "agent": "analyst-bot",
    "description": "Analysis Agent - Deep analysis and insights",
    "emoji": "📊"
  },
  {
    "endpoint": "GET /api/premium/code",
    "price": "$0.03",
    "agent": "code-bot",
    "description": "Code Agent - Code generation and debugging",
    "emoji": "💻"
  }
]

Best Practices

Always validate before deploying - Run tests to ensure pricing is valid
Use consistent price points - Stick to common prices like $0.01, $0.05, $0.10
Document price changes - Keep a changelog of pricing modifications
Review pricing regularly - Ensure prices reflect actual costs
Test in staging first - Deploy pricing changes to staging before production
Monitor pricing consistency - Check logs for validation errors
Use version control - Track pricing changes in git
Get code review - Have pricing changes reviewed by another team member

Troubleshooting

Server Won't Start

Check the error message for pricing validation failures:

npm start
# Look for: ❌ FATAL: Pricing configuration validation failed

Pricing Not Updating

Verify you edited src/pricing.config.js (not src/server.js)
Restart the server
Check /api/status endpoint to verify pricing

Tests Failing

Run tests to identify issues:

node tests/pricing.validator.test.js
node tests/pricing.integration.test.js

Documentation

Full documentation: PRICING_REFACTOR.md
Error examples: PRICING_ERROR_EXAMPLES.md
Refactoring summary: REFACTORING_SUMMARY.md
Unit tests: tests/pricing.validator.test.js
Integration tests: tests/pricing.integration.test.js

Support

For questions or issues:

Check PRICING_ERROR_EXAMPLES.md for common errors
Review PRICING_REFACTOR.md for detailed documentation
Run tests to verify configuration
Check server logs for validation errors

Next Steps

✅ Review pricing configuration in src/pricing.config.js
✅ Run tests to verify everything works
✅ Deploy to staging environment
✅ Test pricing in staging
✅ Deploy to production
✅ Monitor pricing consistency in logs
✅ Update API documentation

Last Updated: May 26, 2026 Version: 1.0.0

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Pricing Configuration - Quick Start Guide

5-Minute Overview

Key Files

How It Works

1. Configuration

2. Validation

3. Usage

Common Tasks

Change a Price

Add a New Premium Endpoint

Query Pricing Information

Running Tests

Unit Tests

Integration Tests

Price Format Rules

Endpoint Format Rules

Agent Name Rules

Error Handling

Validation Fails at Startup

Common Errors

Status Endpoint

Best Practices

Troubleshooting

Server Won't Start

Pricing Not Updating

Tests Failing

Documentation

Support

Next Steps

FilesExpand file tree

PRICING_QUICK_START.md

Latest commit

History

PRICING_QUICK_START.md

File metadata and controls

Pricing Configuration - Quick Start Guide

5-Minute Overview

Key Files

How It Works

1. Configuration

2. Validation

3. Usage

Common Tasks

Change a Price

Add a New Premium Endpoint

Query Pricing Information

Running Tests

Unit Tests

Integration Tests

Price Format Rules

Endpoint Format Rules

Agent Name Rules

Error Handling

Validation Fails at Startup

Common Errors

Status Endpoint

Best Practices

Troubleshooting

Server Won't Start

Pricing Not Updating

Tests Failing

Documentation

Support

Next Steps