> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reconifyhq.com/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Reconify's API reference is read-only for customer data. Do not invent endpoints or authentication behavior beyond the OpenAPI contract.
> The public OpenAPI document contains only the documented external /v2 contract.
# Monitoring stablecoin operations
> Monitor payments, payouts, transfers, deposits, and other financial operations involving stablecoins.
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:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
flow
reference
```
For example, consider a payment where an order is paid using USDC.
Your application may first send:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
payment.initiated
reference: order-123
↓
payment.succeeded
reference: order-123
↓
order.fulfilled
reference: order-123
```
You attach the blockchain transaction to:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
payment.succeeded
reference: order-123
```
Reconify observes:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
✓ 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:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Successful blockchain transaction
≠
Successful financial operation
```
## Example: submitted event and onchain observation differ
Your system sends:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
payout.succeeded
amount: 100.00 USD
recipient: wallet_B
```
The attached transaction contains:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Observed:
98 USDC → wallet_B
```
Reconify retains both pieces of evidence.
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
flow
operation_reference
```
as the accepted event.
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"
}
}'
```
```json Response theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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.
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Your application
↓
Provider
↓
Blockchain
↓
Your ledger
```
Reconify can retain evidence from each layer without treating them as interchangeable.
## Source lifecycle
Reconify accepts the source and schedules its lookup.
Reconify records normalized blockchain evidence including execution, finality, and recognized stablecoin transfers.
When the transaction has not reached the required finality, Reconify continues bounded polling.
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:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
source: not_found
```
does not automatically mean:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.
View the on-chain source API.
Learn how events are attached to financial operations.