🛡️ ShieldTrade API Documentation

Overview

ShieldTrade is a transaction security gateway that analyzes, authorizes, and controls transaction execution before value moves.

Core Services

Service	Port	Description
Gateway	3002	Main ingress, authentication, normalization
Policy Engine	3003	Deterministic hard-gate + tenant policy evaluation
Decision Orchestrator	3004	Orchestrates evaluation pipeline
EVM Simulator	3005	Smart contract execution simulation
Risk Engine	3006	Advisory risk assessment (advisory only)
Execution Service	3007	Authorization claim and submission
Reconciliation Service	3008	Finality checks and recovery monitoring
Intent Service	3009	x402 protocol parsing

Main Flow

1. Client → POST /v1/transactions (with JWT)
2. Gateway → Validate + Persist
3. Gateway → Capability Resolver (get plan)
4. Gateway → Decision Orchestrator (evaluate)
5. Decision Orchestrator → Policy Engine (hard gate + tenant policy)
6. Decision Orchestrator → Risk Engine (advisory assessment)
7. Decision Orchestrator → EVM Simulator (if crypto_onchain)
8. Decision Orchestrator → Return DecisionResult
9. Gateway → Issue Authorization (if ALLOW/WARN)
10. Execution Service → Settlement Dispatch (to PSP)
11. Reconciliation Service → Finality Check (from blockchain)
        

Sample Request

POST /v1/transactions
Authorization: Bearer <your-jwt-token>
Content-Type: application/json

{
  "idempotencyKey": "tx-demo-001",
  "railType": "crypto_onchain",
  "sourceAsset": "ETH",
  "destinationAsset": "ETH",
  "sourceAmountMinor": 1000000000000000000,
  "evmTransaction": {
    "from": "0x1234567890123456789012345678901234567890",
    "to": "0x0987654321098765432109876543210987654321",
    "value": "0xde0b6b3a7640000",
    "chainId": 31337
  }
}
        

Decision Outcomes

• ALLOW - Transaction approved, proceed to execution
• WARN - Transaction flagged, requires review
• BLOCK - Transaction blocked (hard gate, non-overridable)
• CHALLENGE - User verification required
• REVIEW - Manual review required

⚠️ Security Invariants

• Hard gate BLOCK cannot be overridden by any component
• Risk Engine is ADVISORY only - cannot authorize or execute
• Unknown settlement outcome never triggers blind duplicate payment
• Decision and execution are separate boundaries