Skip to main content

🚀 Quick Start: Test Your New Payment Modules

Build Status: ✅ SUCCESS
Ready to Deploy: YES

Step 1: Start the Development Harness​

cd /Users/johnmcmahon/workspace/2025/valkyr/ValkyrAI
make harness-up APP=valkyrai

This starts:

  • ValkyrAI Core (port 8080)
  • PostgreSQL Database
  • Redis Cache
  • Logging stack

Check status:

make harness-status

Step 2: Create Integration Accounts​

For Crypto Buy/Sell (Coinbase Sandbox)​

curl -X POST http://localhost:8080/v1/integrationaccount \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "name": "Coinbase Sandbox Dev",
    "provider": "coinbase",
    "apiKey": "YOUR_COINBASE_SANDBOX_KEY",
    "password": "YOUR_COINBASE_SANDBOX_SECRET",
    "accountType": "sandbox",
    "status": "active"
  }'

Get your Coinbase Sandbox credentials:

  1. Go to https://sandbox.coinbase.com
  2. Create free account
  3. Generate API credentials
  4. Copy API Key and Secret

For MasterCard AgentPay​

curl -X POST http://localhost:8080/v1/integrationaccount \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "name": "MasterCard AgentPay Sandbox",
    "provider": "mastercard",
    "apiKey": "YOUR_MASTERCARD_API_KEY",
    "password": "YOUR_MASTERCARD_SECRET",
    "accountType": "sandbox",
    "status": "active"
  }'

Step 3: Create a Test Workflow​

Workflow: Buy Bitcoin​

curl -X POST http://localhost:8080/v1/workflow \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "name": "Buy Bitcoin on Coinbase",
    "description": "Test crypto buying via Coinbase Sandbox",
    "active": true,
    "tasks": [
      {
        "taskOrder": 1,
        "name": "Buy 0.01 BTC",
        "description": "Purchase small amount of Bitcoin",
        "execModules": [
          {
            "moduleOrder": 1,
            "className": "com.valkyrlabs.workflow.modules.payment.CryptoBuySellModule",
            "moduleType": "payment.crypto.buy_sell",
            "moduleData": {
              "exchange_platform": "coinbase",
              "action": "buy",
              "cryptocurrency": "BTC",
              "fiat_currency": "USD",
              "amount": 0.01,
              "order_type": "market",
              "integration_account_id": "INTEGRATION_ACCOUNT_ID_FROM_STEP_2",
              "risk_controls": {
                "velocity_check": true,
                "max_single_order_usd": 1000,
                "max_daily_volume_usd": 5000
              }
            }
          }
        ]
      }
    ]
  }'

Response (copy the workflow ID):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Buy Bitcoin on Coinbase",
  "status": "active"
}

Step 4: Execute the Workflow​

curl -X POST http://localhost:8080/v1/vaiworkflow/550e8400-e29b-41d4-a716-446655440000/execute \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
  "workflowId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "EXECUTING",
  "executionId": "exec-123",
  "startTime": "2025-10-19T22:30:00Z"
}

Step 5: Monitor Execution in Real-Time​

WebSocket Subscription (Coming Soon™)​

const ws = new WebSocket(
  "ws://localhost:8080/v1/vaiworkflow/subscribe/550e8400-e29b-41d4-a716-446655440000"
);

ws.onmessage = (event) => {
  const update = JSON.parse(event.data);
  console.log("Workflow update:", update);
  // {
  //   taskId: "task-1",
  //   status: "COMPLETED",
  //   eventLog: [
  //     { status: "OK", message: "Starting crypto buy/sell order" },
  //     { status: "OK", message: "Risk validation passed" },
  //     { status: "OK", message: "Order submitted to Coinbase" },
  //     { status: "OK", message: "Order successful" }
  //   ],
  //   stateOutput: {
  //     "crypto.order.result": {
  //       orderId: "cb-order-123",
  //       status: "filled",
  //       price: "42500.00"
  //     }
  //   }
  // }
};

Polling Alternative (Works Now)​

curl -X GET http://localhost:8080/v1/vaiworkflow/550e8400-e29b-41d4-a716-446655440000/status \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Step 6: Check Execution Results​

curl -X GET http://localhost:8080/v1/vaiworkflow/550e8400-e29b-41d4-a716-446655440000/state \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
  "workflowId": "550e8400-e29b-41d4-a716-446655440000",
  "state": {
    "crypto.order.result": {
      "exchange": "coinbase",
      "action": "buy",
      "cryptocurrency": "BTC",
      "amount": 0.01,
      "orderPrice": "42500.00",
      "totalUSD": "425.00",
      "orderId": "cb-order-uuid-123",
      "status": "filled",
      "filledAt": "2025-10-19T22:30:45Z"
    }
  },
  "tasks": [
    {
      "taskId": "task-1",
      "name": "Buy 0.01 BTC",
      "status": "COMPLETED",
      "eventLog": [
        { "status": "OK", "message": "Starting crypto buy/sell order" },
        { "status": "OK", "message": "Amount validation: 0.01 BTC = $425.00" },
        { "status": "OK", "message": "Risk control check passed (max: $1000)" },
        { "status": "OK", "message": "Calling Coinbase API" },
        {
          "status": "OK",
          "message": "Order successful - ID: cb-order-uuid-123"
        }
      ]
    }
  ]
}

Step 7: Test Payment Module (MasterCard)​

Create Payment Workflow​

curl -X POST http://localhost:8080/v1/workflow \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "name": "Process Credit Card Payment",
    "description": "Test MasterCard payment via AgentPay",
    "active": true,
    "tasks": [
      {
        "taskOrder": 1,
        "name": "Charge Card",
        "execModules": [
          {
            "moduleOrder": 1,
            "className": "com.valkyrlabs.workflow.modules.payment.MasterCardAgentPayModule",
            "moduleType": "payment.mastercard.agentpay",
            "moduleData": {
              "integration_account_id": "MASTERCARD_INTEGRATION_ID",
              "amount": 99.99,
              "currency": "USD",
              "merchantId": "YOUR_MERCHANT_ID",
              "webhookUrl": "https://webhook.example.com/payment",
              "velocity_check": true,
              "max_daily_volume_usd": 10000,
              "max_single_transaction_usd": 5000
            }
          }
        ]
      }
    ]
  }'

🛠️ Troubleshooting​

"Integration Account Not Found"​

Error: Integration account with ID not found

Solution: Verify integration account ID from Step 2, ensure it's active

"Risk Control Violation"​

Error: Transaction exceeds daily volume limit

Solution:

  • Check risk_controls.max_daily_volume_usd setting
  • Review workflow state for today's totals
  • Increase limit if appropriate

"Exchange API Error"​

Error: Coinbase API returned 401 Unauthorized

Solution:

  • Verify API key in integration account
  • Check if Coinbase sandbox credentials are correct
  • Ensure API key has required permissions

Connection Refused on localhost:8080​

Error: connect ECONNREFUSED 127.0.0.1:8080

Solution:

# Check if harness is running
make harness-status

# Start harness if not running
make harness-up APP=valkyrai

# Or check logs
docker logs valkyr-valkyrai

📊 Module Status Dashboard​

ModuleStatusCompiledTestedProduction Ready
CryptoBuySellModule✅ Ready✅ Yes⏳ Soon⏳ After testing
MasterCardAgentPayModule✅ Ready✅ Yes⏳ Soon⏳ After testing

🧪 Advanced Testing​

Test with Different Crypto Platforms​

Kraken:

{
  "exchange_platform": "kraken",
  "action": "buy",
  "cryptocurrency": "ETH",
  "fiat_currency": "EUR",
  "amount": 1.5
}

Binance:

{
  "exchange_platform": "binance",
  "action": "sell",
  "cryptocurrency": "USDT",
  "fiat_currency": "USDT",
  "amount": 100
}

Test Limit Orders​

{
  "order_type": "limit",
  "price_limit_usd": 40000,
  "time_in_force": "post_only"
}

Test Error Handling​

Try these to verify error handling:

  • Invalid cryptocurrency: "cryptocurrency": "FAKE"
  • Negative amount: "amount": -100
  • Unsupported platform: "exchange_platform": "unsupported"

Expected: Orders fail gracefully with error messages in eventLog

📚 Documentation Links​

  • Crypto Setup Guide: CRYPTO_BUYSELL_MODULE.md
  • Form Configuration: CRYPTO_FORM_GUIDE.md
  • Implementation Details: CRYPTO_IMPLEMENTATION_SUMMARY.md
  • Build Report: BUILD_REPORT_2025-10-19.md
  • MasterCard Guide: MASTERCARD_AGENTPAY_MODULE.md

🎯 Next After Testing​

Once you've verified the modules work:

  1. Deploy to Staging

    make harness-down
    # Deploy to staging environment

  2. Test with Real Sandbox Funds

    • Create real Coinbase sandbox account
    • Link real bank account (for testing only)
    • Run full transaction workflows

  3. Build Foundation Modules

    • MapModule (transform data fields)
    • FilterModule (conditional filtering)
    • SortModule (data sorting)
    • These unlock complex multi-API pipelines

  4. Connect Multiple APIs

    • Workflow: Get price from Coingecko → Buy if price < $40k → Send notification

💡 Tips & Tricks​

Rerun a Workflow​

curl -X POST http://localhost:8080/v1/vaiworkflow/550e8400-e29b-41d4-a716-446655440000/execute \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

View Integration Accounts​

curl http://localhost:8080/v1/integrationaccount \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Export Workflow Definition​

curl http://localhost:8080/v1/workflow/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" | jq . > workflow-backup.json

Enable Debug Logging​

Set in logback.xml:

<logger name="com.valkyrlabs.workflow.modules.payment" level="DEBUG" />

Happy Testing! 🎉

For issues or questions, check the documentation or logs:

docker logs valkyr-valkyrai | tail -100

Last Updated: October 19, 2025