Monitoring stablecoin operations

Stablecoins can be part of many financial operations: a customer payment, merchant payout, wallet deposit, withdrawal, treasury transfer, or settlement. Reconify monitors these operations using your business events as the source of truth for what should happen, and on-chain observations as additional evidence of what actually happened on the blockchain. For example:

payment.initiated
        ↓
payment.succeeded
        ↓
order.fulfilled

These events belong to one financial operation. Reconify evaluates the operation as a whole rather than treating an on-chain transaction as the payment outcome.

On-chain evidence does not replace your business events.A successful USDC transaction can prove that tokens moved on-chain. It does not by itself prove that an order was paid, a merchant was credited, a withdrawal completed, or another expected business outcome occurred.

When to use stablecoin monitoring

Use stablecoin monitoring when one of Reconify’s supported flows includes an on-chain stablecoin movement. Common examples include:

Supported flow	Stablecoin operation it can represent
`payment_to_wallet`	Payment initiated → payment succeeded or failed → wallet credited
`payment_to_order`	Payment initiated → payment succeeded or failed → order fulfilled
`wallet_to_wallet`	Wallet debited → wallet credited
`wallet_to_payout`	Payout initiated → wallet debited → payout succeeded or failed; failed payouts can require a wallet refund

The stablecoin transaction is one part of the operation.

Start with your monitoring events

Send the events representing the meaningful states of your financial operation as you normally would. Events belonging to the same operation use the same:

flow
reference

For example, consider a payment where an order is paid using USDC. Your application may first send:

{
  "flow": "payment_to_order",
  "type": "payment.initiated",
  "occurred_at": "2026-09-09T10:00:00Z",
  "amount": "100.00",
  "currency": "USD",
  "reference": "order-123",
  "entity_id": "order-123"
}

Later, when your system records the successful payment:

{
  "flow": "payment_to_order",
  "type": "payment.succeeded",
  "occurred_at": "2026-09-09T10:01:00Z",
  "amount": "100.00",
  "currency": "USD",
  "reference": "order-123",
  "entity_id": "order-123"
}

Your application can then send the supported fulfillment event:

{
  "flow": "payment_to_order",
  "type": "order.fulfilled",
  "occurred_at": "2026-09-09T10:02:00Z",
  "amount": "100.00",
  "currency": "USD",
  "reference": "order-123",
  "entity_id": "order-123"
}

Reconify uses these events to understand what your system says happened. You can then attach blockchain evidence to the relevant event.

Which event should receive the on-chain source?

Attach an on-chain source to the event whose claim can be verified using blockchain activity. For example:

Supported event	Attach an on-chain source when…	Why
`payment.initiated`	No transaction exists yet.	This event starts the payment flow.
`payment.succeeded`	The event records a payment claim associated with the transaction.	This is the supported terminal payment event.
`wallet.debited`	The event records an outgoing wallet movement.	This is the supported debit event.
`wallet.credited`	The event records receipt into the wallet.	This is the supported credit event.
`payout.succeeded`	The event records a completed payout claim.	This is the supported terminal payout event.
`order.fulfilled`	Never; it records a business outcome.	It is not a blockchain claim.

payment.failed, payout.failed, payout.initiated, and wallet.refunded are also supported where their flow permits them. Attach a source only when that event makes the on-chain claim you want to inspect. Do not attach it to an unrelated downstream event just because both belong to the same operation. The rule is simple:

Attach blockchain evidence to the event that makes the on-chain claim.

Do not attach the blockchain source to an unrelated downstream event just because both belong to the same operation.

What Reconify observes

After you attach an on-chain source, Reconify inspects the blockchain transaction or address activity and records normalized evidence. Depending on the source and network, this can include:

whether the transaction exists;
transaction execution status;
finality;
containing block;
token transfers;
recognized stablecoin;
exact atomic amount;
token decimals;
sending address;
receiving address;
network;
transaction reference;
unrecognized token activity.

For recognized stablecoins, Reconify separates stablecoin transfers from unrelated token transfers found in the same transaction. Phase-one reviewed networks are:

ethereum-mainnet
ethereum-sepolia
solana-mainnet
solana-devnet

The reviewed stablecoin registry currently includes supported Circle USDC and Paxos USDP deployments. Unsupported token contracts are not treated as recognized stablecoin evidence.

How Reconify evaluates the operation

There are two different layers involved in stablecoin monitoring.

1. Your monitoring events

These describe the expected business operation. For example:

payment.initiated
payment.succeeded
order.fulfilled

Reconify uses these events, your flow definition, and monitoring rules to determine whether the expected operation completed. In phase one, on-chain evidence is stored and displayed separately; it does not evaluate payment success, amount, recipient, conversion, or create findings.

2. On-chain evidence

This tells Reconify what was observed on the blockchain for a specific event. For example:

Event:
payout.succeeded

Claim:
100 USDC sent to wallet B

On-chain evidence:
✓ Transaction found
✓ Transaction finalized
✓ USDC recognized
✓ 100 USDC transferred
✓ Recipient is wallet B

On-chain evidence remains separate from the business event. You can compare the two during an investigation, but phase one does not automatically reconcile them. It does not create a new business event.

Example: successful stablecoin payment

Consider an order for $100 paid using USDC. Reconify may receive:

payment.initiated
reference: order-123
        ↓
payment.succeeded
reference: order-123
        ↓
order.fulfilled
reference: order-123

You attach the blockchain transaction to:

payment.succeeded
reference: order-123

Reconify observes:

Network         ethereum-mainnet
Asset           USDC
Amount          100 USDC
Execution       succeeded
Finality        finalized
Recipient       0xmerchant...
Transaction     0x8b7c...

Your submitted events and the blockchain evidence remain separate. In phase one, Reconify does not automatically evaluate the on-chain amount or recipient against the event.

✓ Payment initiated
✓ Transaction exists
✓ Transaction finalized
✓ USDC transfer observed
✓ Your order.fulfilled event received

These are separate observations. Phase one does not automatically compare the event amount or recipient with the on-chain transfer.

Example: blockchain succeeds but the operation fails

Suppose a payment_to_wallet operation has a successful USDC transfer, but the wallet.credited event is never received. Reconify may observe:

Blockchain
✓ 100 USDC transferred
✓ Transaction finalized

Application
✕ wallet.credited not received

The blockchain transaction succeeded. The financial operation did not complete as expected. This distinction is important when monitoring stablecoin payments.

Successful blockchain transaction
            ≠
Successful financial operation

Example: submitted event and onchain observation differ

Your system sends:

payout.succeeded
amount: 100.00 USD
recipient: wallet_B

The attached transaction contains:

Observed:
98 USDC → wallet_B

Reconify retains both pieces of evidence.

Submitted event
100.00 USD reported by the event

On-chain observation
98 USDC observed on-chain

This evidence remains separate for investigation. Phase one does not automatically evaluate the amount or open a finding from the difference.

Register a transaction source

After the monitoring event has been accepted, register its blockchain source using the event ID as source_event_id. The source must use the same:

flow
operation_reference

as the accepted event.

curl --fail-with-body -sS -X POST "https://api.reconifyhq.com/v2/onchain-sources" \
  -H "Authorization: Bearer $RECONIFY_API_KEY" \
  -H "Idempotency-Key: onchain-src-order-123" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "payment_to_order",
    "operation_reference": "order-123",
    "source_event_id": "evt_01J8M4R7K2EXAMPLE",
    "kind": "transaction",
    "locator": {
      "network": "ethereum-mainnet",
      "transaction_reference": "0x8b7c6d5e4f3a2109876543210fedcba9876543210fedcba9876543210fedcba9"
    }
  }'

{
  "id": "src_01J8M4R7K2ONCHAIN",
  "status": "queued",
  "duplicate": false
}

Source registration is asynchronous and normally returns 202.

Choosing a source

Reconify supports different ways of locating the blockchain activity associated with an event.

Source kind	Use when	Locator
`transaction`	You already know the blockchain transaction	`network` + `transaction_reference`
`address_reference`	You expect funds at an address but do not know the transaction	`network` + `receiving_address` + bounded time window; requires a source revision that supports discovery
`provider_payment`	A provider manages the stablecoin transaction	`integration_ref` + provider transaction ID or reference; records provider context for a later handoff

Transaction

Use transaction whenever your system knows the transaction hash or signature. This is the preferred source when available because the blockchain activity is unambiguous.

Address discovery

Use address_reference when you know where funds should arrive but do not yet know which transaction contains the transfer. It is a supported source-registration shape; direct lookup requires a certified source revision with address-discovery capability.

{
  "flow": "payment_to_order",
  "operation_reference": "order-123",
  "source_event_id": "evt_01J8M4R7K2EXAMPLE",
  "kind": "address_reference",
  "locator": {
    "network": "solana-mainnet",
    "receiving_address": "7YwhL...reviewed-address",
    "window_start": "2026-09-09T10:00:00Z",
    "window_end": "2026-09-09T11:00:00Z"
  }
}

Always provide the narrowest reasonable time window. Do not mix transaction locator fields with address locator fields.

Provider-managed stablecoin payments

If a provider such as a payment or custody platform manages the transfer, continue using the provider integration workflow. Provider evidence and blockchain evidence can both participate in the same operation. For example:

Your application
      ↓
Provider
      ↓
Blockchain
      ↓
Your ledger

Reconify can retain evidence from each layer without treating them as interchangeable.

Source lifecycle

Queued

Reconify accepts the source and schedules its lookup.

Observed

Reconify records normalized blockchain evidence including execution, finality, and recognized stablecoin transfers.

Pending

When the transaction has not reached the required finality, Reconify continues bounded polling.

Finalized

Once the observation reaches finality, polling stops.

Source observation can also terminate as:

failed_onchain
not_found
source_issue
unsupported

These statuses describe the blockchain source, not the business operation. For example:

source: not_found

does not automatically mean:

payment.failed

Reconify evaluates the financial operation separately.

Before you start

Use an organization API key with the write scope.
Submit the monitoring event before registering its on-chain source.
Use exactly the same flow and operation_reference.
Set source_event_id to the accepted monitoring event.
Use a stable Idempotency-Key when registering the source.
Reuse the same idempotency key and body when retrying a transient failure.

The endpoint is:

POST /v2/onchain-sources

The operation is also available through the /v1 compatibility route for integrations already using that API version.

Failure handling

Response	Meaning	Action
`202`	Source accepted and queued	No action required.
`200`	The same idempotent request was already accepted	Treat as success.
`400`	Invalid request	Correct the payload or idempotency header.
`401` / `403`	Invalid credentials or scope	Correct the API key.
`409`	Idempotency key used with different content	Investigate the producer.
`422`	Source does not match the referenced event	Correct the event, flow, or operation reference.
`503`	Temporary registration failure	Retry with backoff using the same key and body.

Keep business outcomes separate from blockchain evidence

A useful way to model stablecoin monitoring is:

Business events = what should happen

Blockchain evidence = what happened on-chain

Reconify operation = whether the complete expected financial outcome occurred

This lets the supported monitoring model keep business events separate from blockchain observations when a stablecoin transfer is part of a payment, payout, wallet movement, or another operation represented by one of the four public flows.

API reference

View the on-chain source API.

Monitoring events

Learn how events are attached to financial operations.

Getting started

Start monitoring

Understand monitoring

Troubleshoot and support

Agent tooling

Examples

When to use stablecoin monitoring

Start with your monitoring events

Which event should receive the on-chain source?

What Reconify observes

How Reconify evaluates the operation

1. Your monitoring events

2. On-chain evidence

Example: successful stablecoin payment

Example: blockchain succeeds but the operation fails

Example: submitted event and onchain observation differ

Register a transaction source

Choosing a source

Transaction

Address discovery

Provider-managed stablecoin payments

Source lifecycle

Before you start

Failure handling

Keep business outcomes separate from blockchain evidence

API reference

Monitoring events

​When to use stablecoin monitoring

​Start with your monitoring events

​Which event should receive the on-chain source?

​What Reconify observes

​How Reconify evaluates the operation

​1. Your monitoring events

​2. On-chain evidence

​Example: successful stablecoin payment

​Example: blockchain succeeds but the operation fails

​Example: submitted event and onchain observation differ

​Register a transaction source

​Choosing a source

​Transaction

​Address discovery

​Provider-managed stablecoin payments

​Source lifecycle

​Before you start

​Failure handling

​Keep business outcomes separate from blockchain evidence

API reference

Monitoring events

When to use stablecoin monitoring

Start with your monitoring events

Which event should receive the on-chain source?

What Reconify observes

How Reconify evaluates the operation

1. Your monitoring events

2. On-chain evidence

Example: successful stablecoin payment

Example: blockchain succeeds but the operation fails

Example: submitted event and onchain observation differ

Register a transaction source

Choosing a source

Transaction

Address discovery

Provider-managed stablecoin payments

Source lifecycle

Before you start

Failure handling

Keep business outcomes separate from blockchain evidence