S
/Docs

Configuration

This guide covers all configuration options for Starknet Agentic, including environment variables, network settings, and security best practices.

Environment Variables

Starknet Agentic uses environment variables for sensitive configuration. Create a .env file in your project root:

cp .env.example .env

Required Variables

# Starknet RPC endpoint
STARKNET_RPC_URL=https://starknet-sepolia.g.alchemy.com/v2/YOUR_KEY

# Your Starknet account address
STARKNET_ACCOUNT_ADDRESS=0x...

# Your account private key
STARKNET_PRIVATE_KEY=0x...

Optional Variables

# AVNU API endpoints (for DeFi operations)
AVNU_BASE_URL=https://sepolia.api.avnu.fi
AVNU_PAYMASTER_URL=https://sepolia.paymaster.avnu.fi

# Default gas token for paymaster (STRK, ETH, USDC, USDT)
DEFAULT_GAS_TOKEN=STRK

# Enable debug logging
DEBUG=starknet:*

# Custom chain ID (defaults to auto-detect)
STARKNET_CHAIN_ID=SN_SEPOLIA

Network Configuration

Sepolia Testnet (Default)

STARKNET_RPC_URL=https://starknet-sepolia.g.alchemy.com/v2/YOUR_KEY
AVNU_BASE_URL=https://sepolia.api.avnu.fi
AVNU_PAYMASTER_URL=https://sepolia.paymaster.avnu.fi

Mainnet

Production Warning

Always test thoroughly on Sepolia before deploying to mainnet. Start with small amounts and verify all transactions.

STARKNET_RPC_URL=https://starknet-mainnet.g.alchemy.com/v2/YOUR_KEY
AVNU_BASE_URL=https://starknet.api.avnu.fi
AVNU_PAYMASTER_URL=https://starknet.paymaster.avnu.fi

RPC Providers

ProviderFree TierSignup
Alchemy300M compute units/monthalchemy.com
Infura100K requests/dayinfura.io
Chainstack3M requests/monthchainstack.com
OtherVariousstarknet.io/fullnodes-rpc-services

Token Addresses

Mainnet Tokens

const MAINNET_TOKENS = {
  ETH: "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
  STRK: "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d",
  USDC: "0x053c91253bc9682c04929ca02ed00b3e423f6710d2ee7e0d5ebb06f3ecf368a8",
  USDT: "0x068f5c6a61780768455de69077e07e89787839bf8166decfbf92b645209c0fb8",
};

Sepolia Tokens

const SEPOLIA_TOKENS = {
  ETH: "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
  STRK: "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d",
};

MCP Server Configuration

Claude Desktop

Location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "mcpServers": {
    "starknet": {
      "command": "node",
      "args": ["/absolute/path/to/starknet-mcp-server/dist/index.js"],
      "env": {
        "STARKNET_RPC_URL": "https://starknet-sepolia.g.alchemy.com/v2/YOUR_KEY",
        "STARKNET_ACCOUNT_ADDRESS": "0x...",
        "STARKNET_PRIVATE_KEY": "0x..."
      }
    }
  }
}

Cursor

Location: ~/.cursor/mcp.json

{
  "mcpServers": {
    "starknet": {
      "command": "node",
      "args": ["/absolute/path/to/starknet-mcp-server/dist/index.js"],
      "env": {
        "STARKNET_RPC_URL": "...",
        "STARKNET_ACCOUNT_ADDRESS": "...",
        "STARKNET_PRIVATE_KEY": "..."
      }
    }
  }
}

Security Best Practices

Never Commit Secrets

Critical

Never commit .env files or private keys to version control. This is the most common cause of stolen funds.

Add to .gitignore:

.env
.env.local
.env.*.local
*.pem
*.key

Use Environment-Specific Files

.env                # Shared defaults (no secrets)
.env.local          # Local overrides (gitignored)
.env.development    # Development settings
.env.production     # Production settings

Validate Environment on Startup

import { z } from "zod";

const envSchema = z.object({
  STARKNET_RPC_URL: z.string().url(),
  STARKNET_ACCOUNT_ADDRESS: z.string().regex(/^0x[a-fA-F0-9]{64}$/),
  STARKNET_PRIVATE_KEY: z.string().regex(/^0x[a-fA-F0-9]+$/),
});

const env = envSchema.parse(process.env);

Use Session Keys for Agents

Instead of exposing your main private key, create session keys with limited permissions:

// Session key with spending limit
const sessionKey = await createSessionKey({
  allowedMethods: ["transfer", "swap"],
  spendingLimit: { token: "ETH", amount: "0.1" },
  expiresAt: Date.now() + 24 * 60 * 60 * 1000, // 24 hours
});

Hardware Wallet for Large Amounts

For mainnet with significant funds, use a hardware wallet (Ledger) with Ready Wallet.

Logging Configuration

Debug Mode

Enable detailed logging:

# All Starknet-related logs
DEBUG=starknet:* node your-script.js

# Specific components
DEBUG=starknet:mcp,starknet:a2a node your-script.js

Log Levels

// In your code
import { setLogLevel } from "@starknet-agentic/mcp-server";

setLogLevel("debug"); // 'debug' | 'info' | 'warn' | 'error'

FAQs

Next Steps

Now that you're configured:

  1. Quick Start - Run your first agent operation
  2. MCP Server Guide - Full MCP integration
  3. Wallet Management - Advanced wallet operations