Getting Started with FraudTwin#

FraudTwin can be used directly as a Python library. This tutorial generates a small, deterministic payment world entirely in memory.

1. Install FraudTwin#

Install FraudTwin in your Python environment before importing it. The command below is shown for reference and is intentionally not executed by this tutorial.

pip install fraudtwin

If FraudTwin is already imported, restart the kernel after installation so the notebook loads the newly installed version.

2. Generate a payment world#

The default is in-memory generation, so no temporary directories or command-line wrappers are needed.

import fraudtwin

data = fraudtwin.generate()

print(data.run_id)

RUN-19652188a1efbe6c

3. Inspect the generated data#

The result contains reproducibility metadata and typed Python objects. You can inspect counts without reading files or calling the CLI.

print("Entities:")
for name, count in data.manifest.entity_counts.items():
    print(f"  {name}: {count:,}")

print("Events (non-zero):")
for name, count in data.manifest.event_counts.items():
    if count:
        print(f"  {name}: {count:,}")

Entities:
  customers: 10
  institutions: 3
  accounts: 15
  cards: 12
  merchants: 3
  devices: 12
  pix_keys: 8
  behavior_profiles: 10
Events (non-zero):
  payments: 100
  payment_events: 433
  ledger_entries: 176
  card_lifecycle_events: 337
  pix_lifecycle_events: 71
  CARD_PAYMENT_INITIATED: 63
  CARD_AUTHORIZATION_REQUESTED: 63
  CARD_AUTHORIZED: 50
  CARD_DECLINED: 13
  CARD_REVERSED: 3
  CARD_CAPTURED: 47
  CARD_CLEARED: 47
  CARD_SETTLED: 47
  CARD_REFUNDED: 4
  PIX_INITIATED: 12
  PIX_VALIDATED: 12
  PIX_AUTHORIZED: 11
  PIX_SUBMITTED: 11
  PIX_SETTLED: 11
  PIX_RECEIVED: 11
  PIX_REJECTED: 1
  PIX_RETURN_REQUESTED: 1
  PIX_RETURNED: 1

for payment in data.behavior.payments[:3]:
    print(
        {
            "payment_id": payment.payment_id,
            "rail": payment.payment_rail,
            "amount": payment.amount,
            "status": payment.current_status,
        }
    )

{'payment_id': 'PAY-00000001', 'rail': 'ACCOUNT_TRANSFER', 'amount': 15.29, 'status': 'COMPLETED'}
{'payment_id': 'PAY-00000002', 'rail': 'PIX', 'amount': 21.7, 'status': 'RECEIVED'}
{'payment_id': 'PAY-00000003', 'rail': 'CARD', 'amount': 15.63, 'status': 'SETTLED'}

4. Use the ML dataset#

The minimal configuration also builds point-in-time ML rows. The returned dataset can be used directly as a Polars DataFrame.

data.require_dataset().frame.head()

shape: (5, 53)

dataset_row_id	payment_id	event_id	customer_id	account_id	prediction_time	business_event_time	event_time	source_available_at	feature_available_at	label_available_at	label	fraud_truth	amount	payment_rail	payment_type	merchant_id	card_id	device_id	online	transaction_count_1m	transaction_count_5m	transaction_count_1h	transaction_count_24h	transaction_count_7d	transaction_count_30d	transaction_amount_1h	transaction_amount_24h	transaction_amount_7d	avg_transaction_amount_30d	max_transaction_amount_7d	amount_vs_customer_avg	distinct_merchants_1d	distinct_merchants_30d	new_merchant_flag	merchant_fraud_rate_historical	distinct_countries_24h	new_country_flag	device_age_days	new_device_flag	trusted_device_flag	device_customer_count_30d	customers_per_device_24h	account_age_days	balance	available_balance	credit_limit	credit_utilization	days_since_last_payment	confirmed_fraud_count_90d	fraud_loss_365d	days_since_last_confirmed_fraud	split
str	str	str	str	str	datetime[μs, UTC]	datetime[μs, UTC]	datetime[μs, UTC]	datetime[μs, UTC]	datetime[μs, UTC]	datetime[μs, UTC]	str	bool	f64	str	str	str	str	str	bool	i64	i64	i64	i64	i64	i64	f64	f64	f64	f64	f64	f64	i64	i64	bool	f64	i64	bool	f64	bool	bool	i64	i64	f64	f64	f64	f64	f64	f64	i64	f64	f64	str
"DSR-4f7f1bad7761f562f65b8f73"	"PAY-00000002"	"EVT-00000002"	"CUS-000004"	"ACC-000014"	2026-01-01 11:37:02 UTC	2026-01-01 11:37:00 UTC	2026-01-01 11:37:00 UTC	2026-01-01 11:37:02 UTC	2026-01-01 11:37:02 UTC	null	null	null	21.7	"PIX"	"TRANSFER"	null	null	"DEV-000008"	false	0	0	2	10	10	10	72.28	304.24	304.24	30.424	52.16	0.713253	3	3	false	0.0	1	false	264.0	false	true	3	3	1377.0	11811.43	11811.43	17564.01	0.327521	0.021551	0	0.0	-1.0	"train"
"DSR-9b9062191b591fc98c6c11fb"	"PAY-00000003"	"EVT-00000003"	"CUS-000004"	"ACC-000014"	2026-01-01 12:21:05 UTC	2026-01-01 12:21:00 UTC	2026-01-01 12:21:00 UTC	2026-01-01 12:21:05 UTC	2026-01-01 12:21:05 UTC	null	null	null	15.63	"CARD"	"PURCHASE"	"MER-000002"	"CARD-000008"	"DEV-000005"	true	0	0	1	11	11	11	21.7	325.94	325.94	29.630909	52.16	0.52749	3	3	false	0.0	1	false	596.0	false	true	1	1	1377.0	11789.73	11789.73	17564.01	0.328756	0.030613	0	0.0	-1.0	"train"
"DSR-8a8b9f485f29945b45bea7b8"	"PAY-00000004"	"EVT-00000004"	"CUS-000002"	"ACC-000011"	2026-01-01 07:54:05 UTC	2026-01-01 07:54:00 UTC	2026-01-01 07:54:00 UTC	2026-01-01 07:54:05 UTC	2026-01-01 07:54:05 UTC	null	null	null	29.24	"CARD"	"PURCHASE"	"MER-000003"	"CARD-000009"	"DEV-000006"	true	0	0	1	4	4	4	43.22	142.82	142.82	35.705	44.97	0.818933	2	2	false	0.0	1	false	613.0	false	true	1	1	86.0	13798.73	13798.73	17960.11	0.231701	0.04103	0	0.0	-1.0	"train"
"DSR-4333e36023f21475b9fdb6e4"	"PAY-00000005"	"EVT-00000005"	"CUS-000006"	"ACC-000008"	2026-01-01 14:33:02 UTC	2026-01-01 14:33:00 UTC	2026-01-01 14:33:00 UTC	2026-01-01 14:33:02 UTC	2026-01-01 14:33:02 UTC	null	null	null	24.08	"PIX"	"TRANSFER"	null	null	"DEV-000006"	false	0	0	0	3	3	3	0.0	68.39	68.39	22.796667	30.26	1.056295	2	2	false	0.0	1	false	614.0	true	true	2	2	1815.0	3285.01	3285.01	35090.72	0.906385	0.08544	0	0.0	-1.0	"train"
"DSR-e78d4b792de2395482d0990d"	"PAY-00000006"	"EVT-00000006"	"CUS-000002"	"ACC-000011"	2026-01-01 19:18:05 UTC	2026-01-01 19:18:00 UTC	2026-01-01 19:18:00 UTC	2026-01-01 19:18:05 UTC	2026-01-01 19:18:05 UTC	null	null	null	25.82	"CARD"	"PURCHASE"	"MER-000003"	"CARD-000012"	"DEV-000002"	true	0	0	0	11	11	11	0.0	369.74	369.74	33.612727	53.34	0.768161	3	3	false	0.0	1	false	287.0	false	true	2	2	87.0	13575.87	13575.87	17960.11	0.24411	0.057697	0	0.0	-1.0	"validation"

5. Count generated cases#

These counts are payment cases: a payment linked to a fraud record is counted as fraud, and the remaining payments are counted as non-fraud. The ML dataset may contain fewer point-in-time rows, and its labels can be unavailable when no fraud workflow is enabled.

total_cases = len(data.behavior.payments)
fraud_payment_ids = {record.payment_id for record in data.behavior.fraud_records}
fraud_cases = len(fraud_payment_ids)
non_fraud_cases = total_cases - fraud_cases
ml_points = data.require_dataset().frame.height

print(f"Payment cases: {total_cases}")
print(f"Fraud cases: {fraud_cases}")
print(f"Non-fraud cases: {non_fraud_cases}")
print(f"ML dataset points: {ml_points}")

Payment cases: 100
Fraud cases: 0
Non-fraud cases: 100
ML dataset points: 91

That is the complete basic workflow: install the package, generate data, inspect the returned Python objects, and understand the generated case counts.

Record the generated shape and tutorial contract.#

summary = {
    "payments": len(data.behavior.payments),
    "events": len(data.behavior.payment_events),
}
print(summary)
assert summary["payments"] >= 0

{'payments': 100, 'events': 433}

Inspect stable payment identities.#

ids = [item.payment_id for item in data.behavior.payments]
assert len(ids) == len(set(ids))
print({"unique_payment_ids": len(ids)})

{'unique_payment_ids': 100}

Compare event-time coverage.#

times = [event.event_time for event in data.behavior.payment_events]
print(
    {
        "first_event": min(times).isoformat() if times else None,
        "last_event": max(times).isoformat() if times else None,
    }
)

{'first_event': '2026-01-01T00:11:00+00:00', 'last_event': '2026-01-01T23:56:00+00:00'}

Record the generated shape and tutorial contract.#

summary = {
    "payments": len(data.behavior.payments),
    "events": len(data.behavior.payment_events),
}
print(summary)
assert summary["payments"] >= 0

{'payments': 100, 'events': 433}

Inspect stable payment identities.#

ids = [item.payment_id for item in data.behavior.payments]
assert len(ids) == len(set(ids))
print({"unique_payment_ids": len(ids)})

{'unique_payment_ids': 100}