Quickstart Guide

1Sign up and get your API key

Create a free account — no credit card required. You get 100 transaction evaluations per hour on the free plan.

curl -X POST https://api.trust-flow.dev/signup \
  -H "Content-Type: application/json" \
  -d '{"name":"Your Name","email":"you@company.com"}'

You'll receive a response like:

{
  "tenant_id": "2bb15ad9-b207-4018-b9db-e08c814e45cd",
  "api_key": "tf_live_69ca9c8b59fcf70b7edca88aa8d4ae10",
  "plan": "free",
  "message": "Save your API key — it will not be shown again."
}

2Evaluate your first transaction

Send a transaction to POST /v1/evaluate — you'll get back a risk score, a decision (APPROVED / STEP_UP_REQUIRED / DECLINED), and a full breakdown of factors.

curl -X POST https://api.trust-flow.dev/v1/evaluate \
  -H "Authorization: Bearer tf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 349.99,
    "currency": "EUR",
    "category": "electronics",
    "merchant_id": "acme_shop",
    "user_id": "user_demo",
    "merchant_trust_score": 0.85
  }'

pip install trustflow

from trustflow import TrustFlowClient

client = TrustFlowClient(api_key="tf_live_YOUR_KEY")

result = client.evaluate(
    amount=349.99,
    currency="EUR",
    category="electronics",
    merchant_id="acme_shop",
    user_id="user_demo",
    merchant_trust_score=0.85,
)

print(result.decision)      # "APPROVED"
print(result.risk_score)    # 32.5
print(result.sca_required)  # False

npm install @trustflow/sdk

import { TrustFlowClient } from "@trustflow/sdk";

const client = new TrustFlowClient({ apiKey: "tf_live_YOUR_KEY" });

const result = await client.evaluate({
  amount: 349.99,
  currency: "EUR",
  category: "electronics",
  merchantId: "acme_shop",
  userId: "user_demo",
  merchantTrustScore: 0.85,
});

console.log(result.decision);    // "APPROVED"
console.log(result.riskScore);   // 32.5
console.log(result.scaRequired); // false

3Read the response

Every evaluation returns a structured decision. Here's what to look at:

• decision — APPROVED, STEP_UP_REQUIRED, or DECLINED. Route your flow accordingly.
• risk_score — 0 to 100. Higher = riskier.
• sca_required — Boolean. If true, trigger Strong Customer Authentication before completing.
• factors — Array of the 7 risk factors with individual scores. Useful for debugging and explainability.
• trace_id — Save this. Every decision is fully auditable at GET /v1/transactions/{trace_id}.

4Handle the three decision paths

Your agent should branch based on the decision field:

if result.decision == "APPROVED":
    complete_transaction()

elif result.decision == "STEP_UP_REQUIRED":
    # SCA / 3DS / biometric prompt
    user_auth_result = prompt_sca(result.trace_id)
    if user_auth_result.verified:
        complete_transaction()

elif result.decision == "DECLINED":
    show_error(result.reason_text)
    log_for_review(result.trace_id)

5Go further

• Full API Reference — every endpoint, every field
• OpenAPI / Swagger UI — interactive API explorer
• Dashboard — live metrics, usage, and transaction history
• Python SDK on PyPI
• Changelog — what's new in the API