Data Ingestion

Submit transactions, fiat events, and screening results via API. No chain indexer or built-in screening required — feed your own data into the same 50-rule monitoring engine.

Overview

The data ingestion endpoints let you use Overvoid's monitoring, alerting, and case management without relying on the on-chain indexer or built-in sanctions screening. This is useful when:

Your transactions originate off-chain or on a chain we don't index
You use your own KYC/AML provider (Chainalysis, Elliptic, TRM Labs, etc.)
You need to backfill historical transaction data for monitoring
You want to ingest fiat wire/ACH events alongside crypto transactions

Oracle vs API: Two Integration Paths

Overvoid offers two ways to integrate compliance into your product. You can use one or both depending on your architecture.

How compliance actually works: Nearly all compliance enforcement is post-transaction. Transactions happen, then your monitoring system detects suspicious patterns, generates alerts, triggers investigations, and takes action (freeze the wallet, file a SAR, escalate to law enforcement). This is true across both traditional finance and crypto — banks, exchanges, and digital asset platforms all work this way. The oracle's canTransfer() check is analogous to a sanctions list screen (is this wallet currently flagged?) — it checks status that was set by previous compliance decisions, not a replacement for post-transaction monitoring. The heavy lifting is always in the monitoring, case management, and SAR workflow.

	On-Chain Oracle	API Ingestion
How it works	ComplianceOracle stores compliance status on-chain — the result of screening and monitoring decisions made off-chain. Tokens and DeFi hooks can read this status. Our chain indexer watches for transfers and feeds them into the monitoring engine.	You submit transactions and screening results to the REST API. The same 50-rule monitoring engine runs against your data. No smart contracts or chain indexer required.
Best for	On-chain status lookups — DeFi protocols and tokens that want to check whether a wallet is currently flagged or has expired compliance credentials, similar to how USDC/USDT check a blacklist	Off-chain monitoring — exchanges, payment processors, fintechs, or anyone who wants transaction monitoring, case management, and SAR filing without deploying contracts
Transaction data	Automatically indexed from supported chains (Sepolia, Arb Sepolia, Base Sepolia)	You submit via `POST /monitoring/transfers` — works for any chain, fiat rails, or internal ledger
Screening	Built-in Yente (OpenSanctions) + OFAC SDN screening runs automatically on entity onboarding and rescreening cycles	Submit results from your own provider (Chainalysis, Elliptic, TRM, etc.) via `POST /monitoring/screening`
Compliance workflow	Post-transaction: the indexer picks up transfers, the monitoring engine runs rules, generates alerts, creates cases. If a wallet needs to be frozen, the oracle status is updated and future transfers are blocked.	Post-transaction: same monitoring engine, same alerts, same case management and SAR workflow. You decide how to enforce in your own system (freeze account, block withdrawals, etc.).
Can combine?	Yes. Use the oracle for on-chain status and the API for additional off-chain data (fiat events, external screening, transactions on unsupported chains). Both feed into the same post-transaction monitoring engine, case management, and SAR workflow.

TL;DR: Both paths feed into the same post-transaction monitoring engine. The oracle publishes compliance status on-chain so protocols can read it. The API lets you bring your own data without touching the chain. Use whichever fits your architecture, or both.

Ingest Transaction

Submit a single transaction. The system stores it and optionally runs the full 50-rule monitoring engine. Works for both on-chain and off-chain transactions.

curl -X POST https://api.overvoid.io/v1/monitoring/transfers \
  -H "Authorization: Bearer cusd_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_address": "0xaaaa...aaaa",
    "to_address": "0xbbbb...bbbb",
    "amount": "50000000000",
    "timestamp": "2026-03-25T12:00:00Z",
    "chain_id": 11155111,
    "run_monitoring": true
  }'

Field	Type	Required	Description
`from_address`	string	Yes	Sender address or identifier
`to_address`	string	Yes	Recipient address or identifier
`amount`	string	Yes	Transaction amount (string to handle uint256)
`timestamp`	datetime	Yes	When the transaction occurred (ISO 8601)
`chain_id`	int	No	Chain ID (omit or 0 for off-chain)
`tx_hash`	string	No	Transaction hash (auto-generated if omitted)
`entity_id`	uuid	No	Entity ID (resolved from wallet if omitted)
`asset`	string	No	Asset label (e.g. "USDC", "USDT") — metadata only
`reference`	string	No	External reference ID
`run_monitoring`	bool	No	Run the 50-rule engine (default: true). Set false for backfill.

Response:

{
  "id": "1b750534-a93b-4f24-bf9b-8d756066d301",
  "tx_hash": "0xc795c07a0384996b67423919a88e4bf894be668d7dcf8faf07d2d2720b1a55dc",
  "monitored": true,
  "alerts_triggered": 1
}

Deduplication: same (chain_id, tx_hash, log_index) returns the existing record without re-processing.

Batch Ingest Transactions

Submit up to 1,000 transactions in a single request. Useful for backfilling historical data. Duplicates are skipped automatically.

curl -X POST https://api.overvoid.io/v1/monitoring/transfers/batch \
  -H "Authorization: Bearer cusd_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transactions": [
      {"from_address": "0xaaa...","to_address": "0xbbb...","amount": "1000","timestamp": "2026-03-25T14:00:00Z","chain_id": 1},
      {"from_address": "0xaaa...","to_address": "0xbbb...","amount": "2000","timestamp": "2026-03-25T14:01:00Z","chain_id": 1}
    ],
    "run_monitoring": true
  }'

{
  "ingested": 5,
  "skipped": 0,
  "alerts_triggered": 1
}

Ingest Fiat Event

Submit wire, ACH, card, and check events. These feed into fiat rules (24-26, 34-38), card rules (39-44), and check rules (45-50).

curl -X POST https://api.overvoid.io/v1/monitoring/fiat-events \
  -H "Authorization: Bearer cusd_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "event_type": "wire_in",
    "amount": 25000.00,
    "currency": "USD",
    "counterparty_name": "Goldman Sachs",
    "counterparty_bank": "GS Bank",
    "reference": "WIRE-001",
    "event_timestamp": "2026-03-25T09:00:00Z"
  }'

Field	Type	Description
`entity_id`	uuid	Entity this event belongs to
`event_type`	string	`wire_in`, `wire_out`, `ach_in`, `ach_out`, `card_load`, `card_purchase`, `card_atm`, `card_refund`, `check_deposit`, `check_purchase`
`amount`	number	Amount in specified currency
`currency`	string	ISO currency code (default: USD)
`counterparty_name`	string	Name of the counterparty bank/entity
`event_timestamp`	datetime	When the fiat event occurred (ISO 8601)
`card_type`	string?	Card events only: `credit`, `debit`, `prepaid`
`merchant_category_code`	string?	4-digit MCC (e.g. 5411, 7995)
`merchant_country`	string?	ISO 3166-1 alpha-2 country code
`check_type`	string?	Check events only: `personal`, `business`, `cashier`, `money_order`
`check_number`	string?	Check sequence number
`deposit_method`	string?	Check deposits only: `teller`, `atm`, `rdc_mobile`, `rdc_desktop`

Ingest External Screening Result

Submit screening results from your own KYC/AML provider instead of using the built-in Yente/OFAC screening. Results are stored as compliance checks and can optionally trigger compliance flag recomputation.

curl -X POST https://api.overvoid.io/v1/monitoring/screening \
  -H "Authorization: Bearer cusd_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "check_type": "sanctions",
    "provider": "chainalysis",
    "result": "pass",
    "score": 0.0,
    "details": {"match_count": 0, "lists_checked": ["OFAC", "EU"]},
    "update_compliance_status": false
  }'

Field	Type	Description
`entity_id`	uuid	Entity being screened
`check_type`	string	`kyb`, `ubo`, `aml`, `sanctions`, `pep`, `adverse_media`
`provider`	string	Provider name (e.g. "chainalysis", "elliptic", "internal")
`result`	string	`pass`, `fail`, `review`, `error`
`score`	float	Match score 0.0-1.0 (optional)
`details`	object	Provider-specific response data (optional)
`update_compliance_status`	bool	If true, recomputes compliance flags and pushes to oracle (default: false)

Response:

{
  "id": "3ada8b7f-f6ee-4a74-8feb-968bb0bb86f3",
  "entity_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "check_type": "sanctions",
  "result": "pass",
  "compliance_status_updated": false
}

When update_compliance_status is true, the system recomputes compliance flags using the DecisionAggregator and dispatches on-chain updates to all active wallets for the entity.