# MaiGuard

> Real-time fraud scoring and AML monitoring API for payment platforms operating in African markets.

MaiGuard provides real-time fraud scoring and AML monitoring for payment platforms in African markets. Base API: https://api.maiguard.com (all paths under /v1/).

## What MaiGuard does

- Real-time transaction scoring with riskScore (0–100) and decisions: ALLOW, REVIEW, BLOCK
- Configurable rules and rule sets (velocity, thresholds, AML conditions, tenant lists)
- Behavioral biometrics and device fingerprinting via JavaScript SDK
- Entity graph analysis linking customers, devices, IPs, and counterparties
- Customer onboarding (KYC/KYB context) and PEP/sanctions screening
- Shadow mode for testing rules in production without affecting live decisions
- Case manager workflows for analyst review

## Integration surfaces

| Channel | Use case | Rate limit (default) |
|---------|----------|----------------------|
| REST API | Synchronous scoring | 1,000/min per tenant |
| Browser SDK | Behavioral biometrics, deviceSessionId | Confirm with MaiGuard |
| Webhooks | Inbound ingestion + outbound alerts | 1,000/min per tenant path |
| Database sync | Scheduled pulls from PG/MySQL/Mongo | Min 5 min between syncs |
| AWS SQS | High-throughput async ingestion | AWS queue quotas |
| File import | Batch backfill (CSV/JSON/JSONL) | 5 imports/hour per tenant |

Global guard: 100 requests/min per IP across all endpoints.

## Key endpoints

- POST /v1/transactions/score — synchronous transaction scoring
- POST /v1/transactions/batch-score — batch scoring (10/min per tenant)
- POST /v1/webhooks/transactions/:path — inbound webhook ingestion
- POST /v1/transactions/import — bulk file import
- PUT /v1/customers/:customerId/onboard — customer onboarding

## JavaScript SDK (Browser)

CDN (current): https://cdn.maiguard.com/sdk/v1/maiguard.min.js

Quick start:
1. Add script: <script src="https://cdn.maiguard.com/sdk/v1/maiguard.min.js"></script>
2. const sentinel = MaiGuard.init('pk_live_<your-key>');
3. sentinel.watch();
4. sentinel.onReady((deviceSessionId) => { ... });
5. Include deviceSessionId (must start with ds_) in score requests

## Documentation

- Home: https://maiguard.com/en/
- Docs: https://maiguard.com/en/docs
- API Reference: https://maiguard.com/en/api-reference
- SDK Docs: https://maiguard.com/en/sdk-docs
- Developers Hub: https://maiguard.com/en/developers
- Glossary: https://maiguard.com/en/docs/glossary
- AI Assist: https://maiguard.com/en/docs/ai-assist
- Coverage: https://maiguard.com/en/coverage
- OpenAPI: https://maiguard.com/openapi.yaml
- AI Context (JSON): https://maiguard.com/ai-context.json
- Agent tool schema: https://maiguard.com/schemas/agent-score-transaction.json
- MCP server: @maiguard/mcp (packages/maiguard-mcp in repo)
- Blog: https://maiguard.com/en/blog
- Fraud & AML Operator Guide: https://maiguard.com/en/guides/fraud-aml-african-fintech

## Blog (technical articles)

- Real-time fraud scoring: https://maiguard.com/en/blog/real-time-fraud-scoring
- Shadow mode testing: https://maiguard.com/en/blog/shadow-mode-testing
- AML for Nigerian fintechs: https://maiguard.com/en/blog/aml-nigerian-fintechs (product capability; not regulatory certification)

## Canonical field names

- deviceSessionId (camelCase) — device session from Browser SDK
- userId — stable customer ID (must match customerId in onboarding)
- riskScore — 0–100, higher = riskier
- decision — ALLOW | REVIEW | BLOCK

## Multi-tenancy

Every call is scoped to the tenant implied by the API key or JWT. Do not send tenantId in request bodies.