### Run Setup Script

Source: https://github.com/colombia-blockchain/snowrail/blob/main/backend/docs/QUICKSTART.md

Executes the setup script to install dependencies, create the .env file, and build the API.

```bash
./scripts/setup.sh
```

--------------------------------

### Start Frontend Application (Bash)

Source: https://github.com/colombia-blockchain/snowrail/blob/main/README.md

Commands to navigate to the frontend directory, install dependencies, and start the frontend development server. The frontend will be available at http://localhost:3000.

```bash
cd frontend
npm install
npm run dev
```

--------------------------------

### Start Backend Application (Bash)

Source: https://github.com/colombia-blockchain/snowrail/blob/main/README.md

Commands to navigate to the backend directory, install dependencies, run database migrations, and start the backend development server. The backend will be available at http://localhost:4000.

```bash
cd backend
npm install
npx prisma migrate dev --name init
npm run dev
```

--------------------------------

### Start Frontend Development Server

Source: https://github.com/colombia-blockchain/snowrail/blob/main/docs/DEPLOYMENT.md

This command starts the frontend development server. It requires Node.js and npm. After installation, the frontend will be available at http://localhost:3000, with API requests proxied to the backend.

```bash
cd frontend

# Install dependencies
npm install

# Start development server
npm run dev
```

--------------------------------

### Start the API

Source: https://github.com/colombia-blockchain/snowrail/blob/main/backend/docs/QUICKSTART.md

Starts the x402 Payment API using npm. The output indicates successful initialization, payment address, network, price per request, and server status with health and test endpoints.

```bash
npm start
```

--------------------------------

### CI/CD Workflow for Payment API Testing

Source: https://github.com/colombia-blockchain/snowrail/blob/main/backend/docs/TESTING.md

This YAML configuration defines a GitHub Actions workflow for testing the Payment API. It checks out the code, sets up Node.js, installs dependencies, builds the project, starts the API, waits for it to be ready, and then tests its health and payment requirement endpoints.

```yaml
# .github/workflows/test.yml
name: Test Payment API

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm install

      - name: Build
        run: npm run build

      - name: Start API
        run: npm start &
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          PAY_TO_ADDRESS: "0x0000000000000000000000000000000000000000"

      - name: Wait for API
        run: sleep 5

      - name: Test health endpoint
        run: curl -f http://localhost:3000/health

      - name: Test payment requirement
        run: |
          curl -X POST http://localhost:3000/process \
            -H "Content-Type: application/json" \
            -d '{"message":{"parts":[{"kind":"text","text":"test"}]}}' \
            | grep -q "Payment Required"
```

--------------------------------

### Start SnowRail Backend and Frontend Applications

Source: https://github.com/colombia-blockchain/snowrail/blob/main/docs/AGENT_INTERFACE.md

Instructions for starting both the backend and frontend applications of the SnowRail system using npm commands. This is necessary for accessing the Web Dashboard.

```bash
# Terminal 1: Backend
cd backend && npm run dev

# Terminal 2: Frontend
cd frontend && npm run dev
```

--------------------------------

### Clean and Rebuild Project

Source: https://github.com/colombia-blockchain/snowrail/blob/main/backend/docs/QUICKSTART.md

Commands to clean the project, reinstall dependencies, and rebuild the API, useful for resolving build failures.

```bash
npm run clean
npm install
npm run build
```

--------------------------------

### Build and Start API in Production Mode (Bash)

Source: https://github.com/colombia-blockchain/snowrail/blob/main/backend/docs/README.md

Commands to build the application for production and start the server.

```bash
npm run build
npm start
```

--------------------------------

### TypeScript/JavaScript Integration Example

Source: https://github.com/colombia-blockchain/snowrail/blob/main/docs/AGENT_INTERFACE.md

Provides a practical TypeScript example demonstrating how an agent can integrate with the SnowRail API, including handling payment requirements.

```APIDOC
## Integration Example - TypeScript/JavaScript

### Description
This example shows a TypeScript class `SnowRailAgent` that interacts with the SnowRail API, covering capability discovery and payroll execution with payment handling.

### Code Example
```typescript
import { ethers } from 'ethers';

class SnowRailAgent {
  private endpoint: string;
  private wallet: ethers.Wallet;

  constructor(endpoint: string, wallet: ethers.Wallet) {
    this.endpoint = endpoint;
    this.wallet = wallet;
  }

  async discoverCapabilities() {
    const response = await fetch(`${this.endpoint}/api/agent/identity`);
    if (!response.ok) {
      throw new Error(`Failed to discover capabilities: ${response.statusText}`);
    }
    return await response.json();
  }

  async executePayroll() {
    // Attempt to execute payroll without initial payment
    let response = await fetch(`${this.endpoint}/api/payroll/execute`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
        // Other headers might be needed depending on exact API spec
      },
      body: JSON.stringify({ /* initial request payload if any */ })
    });

    // Handle 402 Payment Required response
    if (response.status === 402) {
      const paymentDetails = await response.json();
      const { metering } = paymentDetails;
      
      // Create payment authorization using EIP-3009
      const authorization = await this.createPaymentAuth(metering);
      
      // Retry the request with the payment authorization
      response = await fetch(`${this.endpoint}/api/payroll/execute`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-PAYMENT': JSON.stringify(authorization) // Include authorization in header
        },
        body: JSON.stringify({ /* retry request payload */ })
      });
    }

    if (!response.ok) {
      throw new Error(`Payroll execution failed: ${response.statusText}`);
    }

    return await response.json();
  }

  private async createPaymentAuth(metering: any): Promise<string> {
    // Placeholder for EIP-3009 signature generation
    // This would involve using the agent's wallet to sign a transfer authorization.
    console.warn("createPaymentAuth: EIP-3009 signature generation not implemented.");
    // Example structure (actual implementation needed):
    const { price, asset, chain } = metering;
    const amount = ethers.utils.parseUnits(price, 6); // Assuming USDC has 6 decimals
    const currentTimestamp = Math.floor(Date.now() / 1000);
    const deadline = currentTimestamp + 3600; // 1 hour validity
    
    // Replace with actual EIP-3009 signing logic
    const authorization = {
      from: this.wallet.address,
      to: 'TREASURY_ADDRESS', // Get this from SnowRail or config
      value: amount.toString(),
      validAfter: currentTimestamp,
      validBefore: deadline,
      nonce: ethers.utils.randomBytes(8) // Generate a nonce
    };

    // Sign the authorization hash or structure as per EIP-3009 spec
    // const signature = await this.wallet.signMessage(ethers.utils.arrayify(ethers.utils.keccak256(ethers.utils.defaultAbiCoder.encode(['address', 'address', 'uint256', 'uint256', 'uint256', 'bytes32'], [authorization.from, authorization.to, authorization.value, authorization.validAfter, authorization.validBefore, authorization.nonce]))));
    
    // Return the signed authorization payload (format depends on API expectation)
    return JSON.stringify(authorization); // Placeholder return
  }
}

// Example Usage:
// const provider = new ethers.providers.Web3Provider(window.ethereum);
// const signer = provider.getSigner();
// const agentWallet = new ethers.Wallet('YOUR_PRIVATE_KEY', provider);
// const snowrailAgent = new SnowRailAgent('YOUR_SNOWRAIL_API_ENDPOINT', agentWallet);

// async function main() {
//   try {
//     const capabilities = await snowrailAgent.discoverCapabilities();
//     console.log('SnowRail Capabilities:', capabilities);
//     const result = await snowrailAgent.executePayroll();
//     console.log('Payroll Execution Result:', result);
//   } catch (error) {
//     console.error('Error interacting with SnowRail:', error);
//   }
// }
// main();
```
```

--------------------------------

### Start API in Development Mode (Bash)

Source: https://github.com/colombia-blockchain/snowrail/blob/main/backend/docs/README.md

Command to start the API server for development purposes.

```bash
npm run dev
```

--------------------------------

### SnowRail Agent Integration Example in TypeScript

Source: https://github.com/colombia-blockchain/snowrail/blob/main/docs/AGENT_INTERFACE.md

Provides a TypeScript class example for integrating with SnowRail. It demonstrates how an agent can discover capabilities and execute payroll, including handling the 402 Payment Required response and retrying with payment authorization.

```typescript
import { ethers } from 'ethers';

class SnowRailAgent {
  private endpoint: string;
  private wallet: ethers.Wallet;

  async discoverCapabilities() {
    const response = await fetch(`${this.endpoint}/api/agent/identity`);
    return await response.json();
  }

  async executePayroll() {
    // 1. Try without payment
    let response = await fetch(`${this.endpoint}/api/payroll/execute`, {
      method: 'POST'
    });

    if (response.status === 402) {
      // 2. Get payment requirements
      const { metering } = await response.json();
      
      // 3. Create payment authorization
      const authorization = await this.createPaymentAuth(metering);
      
      // 4. Retry with payment
      response = await fetch(`${this.endpoint}/api/payroll/execute`, {
        method: 'POST',
        headers: {
          'X-PAYMENT': JSON.stringify(authorization)
        }
      });
    }

    return await response.json();
  }

  private async createPaymentAuth(metering: any) {
    // Implement EIP-3009 signature
    // ...
  }
}
```

--------------------------------

### QuickNode RPC Provider Configuration

Source: https://github.com/colombia-blockchain/snowrail/blob/main/backend/docs/RPC_CONFIGURATION.md

Example environment variable configuration for using QuickNode as an RPC provider. Replace YOUR_TOKEN with your actual QuickNode token.

```env
RPC_URL=https://your-endpoint.base-sepolia.quiknode.pro/YOUR_TOKEN/
```

--------------------------------

### Initialize Database with Prisma

Source: https://github.com/colombia-blockchain/snowrail/blob/main/docs/DEPLOYMENT.md

This command initializes the backend database using Prisma. It installs dependencies, runs database migrations with an 'init' name, and generates the Prisma client. This is crucial for setting up the database schema.

```bash
cd backend

# Install dependencies
npm install

# Run Prisma migrations
npx prisma migrate dev --name init

# Generate Prisma client
npx prisma generate
```

--------------------------------

### Install EigenX CLI

Source: https://github.com/colombia-blockchain/snowrail/blob/main/backend/docs/deployment/DEPLOYING_TO_TEE.md

Installs the EigenX command-line interface. This script is available for macOS/Linux and Windows systems.

```bash
curl -fsSL https://eigenx-scripts.s3.us-east-1.amazonaws.com/install-eigenx.sh | bash
```

```powershell
curl -fsSL https://eigenx-scripts.s3.us-east-1.amazonaws.com/install-eigenx.ps1 | powershell -
```

--------------------------------

### Project Structure Overview

Source: https://github.com/colombia-blockchain/snowrail/blob/main/backend/docs/README.md

Illustrates the directory and file layout of the x402-developer-starter-kit. Key directories include `src/` for source code and `tests/` for testing utilities. Important files include `server.ts`, `MerchantExecutor.ts`, `package.json`, and `.env.example`.

```tree
x402-developer-starter-kit/
├── src/
│   ├── server.ts                     # Express server and endpoints
│   ├── ExampleService.ts             # Example service logic (replace with your own)
│   ├── MerchantExecutor.ts           # Payment verification & settlement helpers
│   ├── x402Types.ts                  # Shared task/message types
│   └── tests/integration/testClient.ts  # Test client for development
├── package.json
├── tsconfig.json
├── .env.example
├── README.md
├── TESTING.md
└── tests/scripts/test-request.sh

```

--------------------------------

### Configure Backend Environment Variables (Bash)

Source: https://github.com/colombia-blockchain/snowrail/blob/main/README.md

Steps to copy the example environment file, and set required variables for backend configuration. This includes network, treasury contract address, private key, and RPC URL for Avalanche. These variables are crucial for the backend to interact with the smart contract and the network.

```bash
cd backend
cp env.example .env
# Edit .env with your contract address and keys

# Required variables:
NETWORK=fuji
TREASURY_CONTRACT_ADDRESS=0xYourContractAddress
PRIVATE_KEY=0xYourPrivateKey
RPC_URL_AVALANCHE=https://api.avax-test.network/ext/bc/C/rpc
```

--------------------------------

### Run Full Test Suite with npm (Bash)

Source: https://github.com/colombia-blockchain/snowrail/blob/main/backend/docs/TESTING.md

Initiates the comprehensive test suite for the payment API using the npm test command, which typically includes payment signing and request processing.

```bash
npm test
```

--------------------------------

### Deploy Smart Contract (Bash)

Source: https://github.com/colombia-blockchain/snowrail/blob/main/README.md

Commands to navigate to the contracts directory, install dependencies, set private key and router address environment variables, and deploy the smart contract to the Fuji testnet. Ensure you replace '0xYourPrivateKey' with your actual private key.

```bash
cd contracts
npm install
export PRIVATE_KEY=0xYourPrivateKey
export ROUTER_ADDRESS_FUJI=0x688d21b0B8Fc35968A1940f5A36D66A0f522E5B3
npm run deploy:fuji
```

--------------------------------

### Get Operational Statistics

Source: https://github.com/colombia-blockchain/snowrail/blob/main/docs/AGENT_INTERFACE.md

Retrieves real-time operational statistics for the agent system, including payroll processing metrics and system uptime.

```APIDOC
## GET /api/agent/stats

### Description
Monitor real-time system metrics.

### Method
GET

### Endpoint
/api/agent/stats

### Parameters

### Request Body

### Request Example
```bash
curl http://localhost:4000/api/agent/stats
```

### Response
#### Success Response (200)
- **summary** (object) - Summary statistics of payroll processing.
  - **totalPayrolls** (number) - Total number of payrolls processed.
  - **totalPaidPayrolls** (number) - Number of payrolls successfully paid.
  - **totalProcessingPayrolls** (number) - Number of payrolls currently being processed.
  - **totalFailedPayrolls** (number) - Number of payrolls that failed.
- **amounts** (object) - Financial overview.
  - **totalPaid** (number) - Total amount paid.
  - **totalProcessing** (number) - Total amount currently being processed.
  - **currency** (string) - The currency of the amounts.
- **recipients** (object) - Statistics related to recipients.
  - **total** (number) - Total number of recipients.
- **system** (object) - System information.
  - **uptime** (string) - The duration the system has been running.
  - **timestamp** (string) - The current timestamp (ISO 8601 format).

#### Response Example
```json
{
  "summary": {
    "totalPayrolls": 10,
    "totalPaidPayrolls": 8,
    "totalProcessingPayrolls": 1,
    "totalFailedPayrolls": 1
  },
  "amounts": {
    "totalPaid": 10000.00,
    "totalProcessing": 1000.00,
    "currency": "USD"
  },
  "recipients": {
    "total": 100
  },
  "system": {
    "uptime": "5h 30m 15s",
    "timestamp": "2025-12-04T00:00:00Z"
  }
}
```
```

--------------------------------

### Install and Run x402 Facilitator Server

Source: https://github.com/colombia-blockchain/snowrail/blob/main/backend/docs/FACILITATOR_README.md

Provides commands to compile and run the x402 Facilitator Server using npm. Includes options for a standard build and run, or a development mode that automatically recompiles and restarts the server.

```bash
# Compile TypeScript
npm run build

# Run facilitator
npm run facilitator

# Or in development mode (recompiles and runs)
npm run facilitator:dev
```

--------------------------------

### Test Client Configuration (Environment Variables)

Source: https://github.com/colombia-blockchain/snowrail/blob/main/backend/docs/TESTING.md

Lists essential environment variables required for configuring the test client, including API keys, payment addresses, network settings, and optional client private keys.

```env
# Required for the API
OPENAI_API_KEY=your_openai_api_key
PAY_TO_ADDRESS=0xYourMerchantAddress
NETWORK=base-sepolia

# Optional for testing with payments
CLIENT_PRIVATE_KEY=your_test_wallet_private_key
API_URL=http://localhost:3000
```

--------------------------------

### Change API Port

Source: https://github.com/colombia-blockchain/snowrail/blob/main/backend/docs/QUICKSTART.md

Modifies the .env file to change the port the API runs on, useful if the default port (3000) is occupied.

```env
PORT=3001
```

--------------------------------

### Get Recent Activity

Source: https://github.com/colombia-blockchain/snowrail/blob/main/docs/AGENT_INTERFACE.md

Retrieves a list of recent agent activities, specifically payroll execution history, including links to Arweave receipts for verification.

```APIDOC
## GET /api/agent/activity

### Description
View payroll execution history with Arweave receipts.

### Method
GET

### Endpoint
/api/agent/activity

### Parameters

### Request Body

### Request Example
```bash
curl http://localhost:4000/api/agent/activity
```

### Response
#### Success Response (200)
- **activity** (array) - A list of recent payroll activities.
  - **id** (string) - The unique identifier for the activity (e.g., payroll ID).
  - **status** (string) - The current status of the activity (e.g., PAID, PROCESSING, FAILED).
  - **totalAmount** (string) - The total amount processed for this activity.
  - **currency** (string) - The currency of the total amount.
  - **recipientCount** (number) - The number of recipients involved in this activity.
  - **createdAt** (string) - The timestamp when the activity was created (ISO 8601 format).
  - **arweave** (object) - Details about the Arweave receipt.
    - **url** (string) - The URL to access the Arweave receipt.
    - **txId** (string) - The transaction ID on the Arweave network.
    - **status** (string) - The status of the Arweave receipt (e.g., Immutable • Verifiable • Compliance-Ready).
  - **payments** (array) - Details of individual payments within this activity.
- **stats** (object) - Summary statistics for the activities.
  - **totalPayrolls** (number) - The total number of payrolls.
  - **totalPaid** (number) - The total amount paid across all payrolls.
  - **totalRecipients** (number) - The total number of recipients.

#### Response Example
```json
{
  "activity": [
    {
      "id": "pay_xxx",
      "status": "PAID",
      "totalAmount": "1000.00",
      "currency": "USD",
      "recipientCount": 10,
      "createdAt": "2025-12-04T00:00:00Z",
      "arweave": {
        "url": "https://arweave.net/txId",
        "txId": "arweave-transaction-id",
        "status": "Immutable • Verifiable • Compliance-Ready"
      },
      "payments": [...] 
    }
  ],
  "stats": {
    "totalPayrolls": 5,
    "totalPaid": 5000.00,
    "totalRecipients": 50
  }
}
```
```

--------------------------------

### Check Port Usage

Source: https://github.com/colombia-blockchain/snowrail/blob/main/backend/docs/QUICKSTART.md

Utility to check if a specific port is already in use, helpful for diagnosing connection issues. Default port is 3000.

```bash
lsof -i :3000
```

--------------------------------

### Get Agent Identity Card

Source: https://github.com/colombia-blockchain/snowrail/blob/main/docs/AGENT_INTERFACE.md

Retrieves SnowRail's capabilities, protocols, and available resources. This is useful for discovering the agent's functionalities and how to interact with it programmatically.

```APIDOC
## GET /api/agent/identity

### Description
Discover SnowRail's capabilities, protocols, and available resources.

### Method
GET

### Endpoint
/api/agent/identity

### Parameters

### Request Body

### Request Example
```bash
curl http://localhost:4000/api/agent/identity
```

### Response
#### Success Response (200)
- **erc8004Version** (string) - The version of the ERC-8004 standard supported.
- **agent** (object) - Details about the agent.
  - **id** (string) - The unique identifier of the agent.
  - **name** (string) - The display name of the agent.
  - **description** (string) - A brief description of the agent's purpose.
  - **version** (string) - The version of the agent software.
  - **capabilities** (array) - A list of capabilities supported by the agent.
  - **protocols** (array) - A list of communication protocols supported by the agent.
  - **networks** (array) - A list of blockchain networks the agent operates on.
  - **validation** (object) - Information about the agent's validation mechanism.
    - **type** (string) - The type of validation (e.g., SMART_CONTRACT).
    - **address** (string) - The address of the validation contract.
    - **chainId** (number) - The chain ID of the network.
- **metering** (object) - Information about metered resources and their pricing.
  - **resources** (array) - A list of metered resources.
    - **id** (string) - The identifier of the resource.
    - **price** (string) - The price of the resource.
    - **asset** (string) - The currency asset for the price.
    - **chain** (string) - The blockchain network for the resource.
    - **description** (string) - A description of the resource.

#### Response Example
```json
{
  "erc8004Version": "1.0",
  "agent": {
    "id": "snowrail-treasury-v1",
    "name": "SnowRail Treasury Agent",
    "description": "Autonomous treasury orchestration",
    "version": "1.0.0",
    "capabilities": [
      "treasury_management",
      "cross_border_payments",
      "payroll_execution",
      "crypto_to_fiat_bridge",
      "x402_payments",
      "onchain_settlement",
      "permanent_receipts"
    ],
    "protocols": ["x402", "erc8004", "eip3009", "rail_api", "arweave"],
    "networks": ["avalanche", "avalanche-fuji"],
    "validation": {
      "type": "SMART_CONTRACT",
      "address": "0x...",
      "chainId": 43113
    }
  },
  "metering": {
    "resources": [
      {
        "id": "payroll_execute",
        "price": "1",
        "asset": "USDC",
        "chain": "avalanche",
        "description": "Execute international payroll"
      }
    ]
  }
}
```
```

--------------------------------

### Test Client Programmatic Usage (TypeScript)

Source: https://github.com/colombia-blockchain/snowrail/blob/main/backend/docs/TESTING.md

Demonstrates how to import and use the `TestClient` class in TypeScript for programmatically interacting with the payment API, including checking health and sending requests with or without payment.

```typescript
import { TestClient } from '../tests/integration/testClient.js';

const client = new TestClient(privateKey);

// Check health
await client.checkHealth();

// Send request without payment
const response1 = await client.sendRequest('What is 2+2?');

// Send request with payment
const response2 = await client.sendPaidRequest('Tell me a joke!');
```

--------------------------------

### GET /health

Source: https://github.com/colombia-blockchain/snowrail/blob/main/backend/docs/TESTING.md

Verifies if the API is running and configured properly. It returns the status, service name, version, and payment configuration details.

```APIDOC
## GET /health

### Description
Checks the health status of the x402 payment API. Returns information about the service, version, and payment network configuration.

### Method
GET

### Endpoint
/health

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl http://localhost:3000/health
```

### Response
#### Success Response (200)
- **status** (string) - The health status of the API (e.g., "healthy").
- **service** (string) - The name of the service.
- **version** (string) - The version of the service.
- **payment** (object) - Details about the payment configuration.
  - **address** (string) - The payment address.
  - **network** (string) - The blockchain network being used.
  - **price** (string) - The cost for the service.

#### Response Example
```json
{
  "status": "healthy",
  "service": "x402-payment-api",
  "version": "1.0.0",
  "payment": {
    "address": "0xYourAddress...",
    "network": "base-sepolia",
    "price": "$0.10"
  }
}
```
```

--------------------------------

### Create and Configure New Application with EigenX

Source: https://github.com/colombia-blockchain/snowrail/blob/main/backend/docs/deployment/DEPLOYING_TO_TEE.md

Initializes a new application project using a specified template and configures environment variables. Applications can be created from templates for TypeScript, Python, Go, or Rust.

```bash
# Create from template (typescript | python | golang | rust)
eigenx app create my-app typescript
cd my-app

# Configure environment variables
cp .env.example .env
# Edit .env with your configuration
```

--------------------------------

### Test API Request

Source: https://github.com/colombia-blockchain/snowrail/blob/main/backend/docs/QUICKSTART.md

Runs a script to test the API by sending a request. Expected output is a '402 Payment Required' response with payment details.

```bash
./tests/scripts/test-request.sh
```

--------------------------------

### Build and Run Docker Container (Bash)

Source: https://github.com/colombia-blockchain/snowrail/blob/main/backend/docs/README.md

Commands to build a Docker image for the application and run it as a container, using environment variables from a .env file.

```bash
# Build the image
docker build -t x402-starter .

# Run the container (make sure .env has the required variables)
docker run --env-file .env -p 3000:3000 x402-starter
```

--------------------------------

### Base Mainnet Public RPC Configuration

Source: https://github.com/colombia-blockchain/snowrail/blob/main/backend/docs/RPC_CONFIGURATION.md

Example environment variable configuration for using the public RPC endpoint for Base Mainnet. Not recommended for production environments.

```env
RPC_URL=https://mainnet.base.org
```

--------------------------------

### Prisma Database Initialization and Migration (Bash)

Source: https://context7.com/colombia-blockchain/snowrail/llms.txt

This set of bash commands outlines the process for setting up the database schema and running migrations for the SnowRail project using Prisma. It includes installing dependencies, generating the Prisma client, and applying migrations for development and production environments.

```bash
# Install dependencies
cd backend
npm install

# Setup Prisma provider (auto-detects PostgreSQL)
npm run prisma:setup

# Generate Prisma client
npx prisma generate

# Run migrations (development)
npx prisma migrate dev --name init

# Run migrations (production)
npm run prisma:migrate:deploy

# Push schema without migrations (development)
npx prisma db push

# Seed database (if needed)
npx tsx scripts/seed-database.ts

```

--------------------------------

### Infura RPC Provider Configuration

Source: https://github.com/colombia-blockchain/snowrail/blob/main/backend/docs/RPC_CONFIGURATION.md

Example environment variable configuration for using Infura as an RPC provider. Replace YOUR_PROJECT_ID with your actual Infura Project ID.

```env
RPC_URL=https://base-sepolia.infura.io/v3/YOUR_PROJECT_ID
```

--------------------------------

### Configure Backend to Use Local Facilitator

Source: https://github.com/colombia-blockchain/snowrail/blob/main/backend/docs/FACILITATOR_README.md

Illustrates how to configure a backend application to utilize the locally running x402 Facilitator Server by setting the X402_FACILITATOR_URL environment variable.

```bash
# Use local facilitator
X402_FACILITATOR_URL=http://localhost:3001
```

--------------------------------

### Alchemy RPC Provider Configuration

Source: https://github.com/colombia-blockchain/snowrail/blob/main/backend/docs/RPC_CONFIGURATION.md

Example environment variable configuration for using Alchemy as an RPC provider. Replace YOUR_API_KEY with your actual Alchemy API key.

```env
RPC_URL=https://base-sepolia.g.alchemy.com/v2/YOUR_API_KEY
```

--------------------------------

### Configure Test Client Private Key

Source: https://github.com/colombia-blockchain/snowrail/blob/main/backend/docs/TESTING.md

This snippet shows how to add the test wallet's private key to the environment variables file (.env). This is necessary for tests that involve making paid requests, ensuring the test client can sign transactions.

```env
CLIENT_PRIVATE_KEY=0x1234...your_test_wallet_private_key
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/colombia-blockchain/snowrail/blob/main/backend/docs/QUICKSTART.md

Edits the .env file to set required and optional environment variables for the API. Requires an OpenAI API key and a wallet address for payments.

```env
OPENAI_API_KEY=sk-your-openai-api-key
PAY_TO_ADDRESS=0xYourWalletAddress
PORT=3000
NETWORK=base-sepolia
PRIVATE_KEY=your_private_key
X402_DEBUG=true
```

--------------------------------

### Run Backend Tests (Bash)

Source: https://github.com/colombia-blockchain/snowrail/blob/main/README.md

Commands to navigate to the backend directory and execute its tests using npm.

```bash
cd backend
npm test
```

--------------------------------

### Get Operational Statistics via REST API

Source: https://github.com/colombia-blockchain/snowrail/blob/main/docs/AGENT_INTERFACE.md

Retrieve real-time operational statistics for the agent, such as total payrolls, amounts processed, and system uptime. This is crucial for monitoring agent performance.

```bash
curl http://localhost:4000/api/agent/stats
```

--------------------------------

### Development Environment Configuration (Bash)

Source: https://github.com/colombia-blockchain/snowrail/blob/main/README.md

Sets up environment variables for the development environment using the Fuji Testnet. Includes configurations for the server port, Avalanche network details, contract address, private key, database connection, and Rail API sandbox credentials. Optional Arweave configuration is also included.

```bash
# Server
PORT=4000

# Network
NETWORK=fuji
RPC_URL_AVALANCHE=https://api.avax-test.network/ext/bc/C/rpc

# Contract
TREASURY_CONTRACT_ADDRESS=0xcba2318C6C4d9c98f7732c5fDe09D1BAe12c27be
PRIVATE_KEY=0x...

# Database
DATABASE_URL="file:./prisma/dev.db"

# Rail API (Sandbox)
RAIL_API_BASE_URL=https://sandbox.layer2financial.com/api
RAIL_AUTH_URL=https://auth.layer2financial.com/oauth2/ausbdqlx69rH6OjWd696/v1/token
RAIL_CLIENT_ID=0oaomrdnngvTiszCO697
RAIL_CLIENT_SECRET=your_secret_here

# Arweave (optional)
ARWEAVE_JWK="{"kty":"RSA","n":"..."}"
```

--------------------------------

### Base Sepolia Public RPC Configuration

Source: https://github.com/colombia-blockchain/snowrail/blob/main/backend/docs/RPC_CONFIGURATION.md

Example environment variable configuration for using the public RPC endpoint for Base Sepolia testnet. Not recommended for production environments.

```env
RPC_URL=https://sepolia.base.org
```

--------------------------------

### SnowRail Agent: Discover Capabilities (Python)

Source: https://github.com/colombia-blockchain/snowrail/blob/main/docs/AGENT_INTERFACE.md

Provides a method to discover the capabilities of a SnowRail agent by making a GET request to the agent's identity endpoint. This is a prerequisite for understanding what actions the agent can perform.

```python
import requests

class SnowRailAgent:
    def __init__(self, endpoint: str, private_key: str):
        self.endpoint = endpoint
        # ... other initializations ...
    
    def discover_capabilities(self):
        response = requests.get(f"{self.endpoint}/api/agent/identity")
        return response.json()
```

--------------------------------

### Get Recent Activity via REST API

Source: https://github.com/colombia-blockchain/snowrail/blob/main/docs/AGENT_INTERFACE.md

Fetch the recent payroll execution history, including status, amounts, and Arweave receipt details. This endpoint provides insights into past payroll operations.

```bash
curl http://localhost:4000/api/agent/activity
```