Soul Financials API Documentation

curl -X POST https://soul-financialsapi-production.up.railway.app/agents \
  -H "Content-Type: application/json" \
  -d '{"display_name": "my-trading-agent"}'

const res = await fetch('https://soul-financialsapi-production.up.railway.app/agents', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ display_name: 'my-trading-agent' })
});
const agent = await res.json();
console.log(agent.id); // Use this UUID for all subsequent calls

curl -X POST https://soul-financialsapi-production.up.railway.app/wallets/verify \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xYourWalletAddress",
    "chain": "ethereum",
    "message": "I am verifying wallet 0xYourWalletAddress for Soul Financials",
    "signature": "0xYourSignature...",
    "agent_id": "your-agent-uuid"
  }'

const wallet = '0xYourWalletAddress';
const message = `I am verifying wallet ${wallet} for Soul Financials`;
// Sign with ethers.js, viem, or your wallet SDK
const signature = await signer.signMessage(message);

const res = await fetch('https://soul-financialsapi-production.up.railway.app/wallets/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    address: wallet,
    chain: 'ethereum',
    message,
    signature,
    agent_id: agent.id
  })
});

curl -X POST https://soul-financialsapi-production.up.railway.app/agents/{agent_id}/index

await fetch(`https://soul-financialsapi-production.up.railway.app/agents/${agent.id}/index`, {
  method: 'POST'
});
// Wait a few seconds for background processing
await new Promise(r => setTimeout(r, 5000));

curl https://soul-financialsapi-production.up.railway.app/verify/{agent_id}

const res = await fetch(`https://soul-financialsapi-production.up.railway.app/verify/${agent.id}`);
const report = await res.json();

console.log(report.soul_score);     // { value: 650, max: 900, tier: "good" }
console.log(report.graph_health);   // { status: "clean", flags: { high: 0, medium: 0, low: 0 } }
console.log(report.income);         // { total_90d_usdc: "15420.50", ... }
console.log(report.warnings);       // ["10 reputation signals are self-reported"]

curl -X POST https://soul-financialsapi-production.up.railway.app/agents/{agent_id}/reputation \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-platform-api-key" \
  -d '{
    "signals": [{
      "signal_type": "task_completion",
      "signal_value": {
        "task_id": "task-001",
        "description": "Completed data analysis job",
        "amount_usdc": 150
      },
      "signal_timestamp": "2026-02-08T12:00:00Z"
    }]
  }'

await fetch(`https://soul-financialsapi-production.up.railway.app/agents/${agent.id}/reputation`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': platformApiKey
  },
  body: JSON.stringify({
    signals: [{
      signal_type: 'task_completion',
      signal_value: {
        task_id: 'task-001',
        description: 'Completed data analysis job',
        amount_usdc: 150
      },
      signal_timestamp: '2026-02-08T12:00:00Z'
    }]
  })
});

// Before transacting with another agent, check their verification report
const res = await fetch(`https://soul-financialsapi-production.up.railway.app/verify/${otherAgentId}`);
const report = await res.json();

if (report.soul_score.value >= 600 && report.graph_health.status === 'clean') {
  // Safe to transact — good score, no fraud flags
  console.log('Agent is trustworthy');
} else if (report.soul_score.value < 300) {
  // Caution — check warnings before proceeding
  console.log('Proceed with caution:', report.warnings);
}

// Check specific concerns
if (report.graph_health.flags.high > 0) {
  console.log('HIGH SEVERITY fraud flags detected');
}
if (report.income?.confidence_breakdown.tier4_pct > 0.8) {
  console.log('Most income is unverified (Tier 4)');
}

# Quick check from the command line
curl -s https://soul-financialsapi-production.up.railway.app/verify/{other_agent_id} | jq '.soul_score, .graph_health.status, .warnings'