Pilot Program

The DPX pilot is designed so that every scenario — including failures — is visible, traceable, and recoverable before you move real money. Sandbox mode gives you full fee math and settlement simulation with zero on-chain commitment.

Sandbox mode

Add ?sandbox=true to any pricing endpoint. You get:

Real fee calculations using live oracle data
A mock quoteId and settlement reference
Simulated ESG redistribution amounts
No wallet interaction, no token transfer, no on-chain transaction

# Full quote in sandbox — real math, mock settlement
curl "https://stability.untitledfinancial.com/quote?amountUsd=1000000&hasFx=true&esgScore=75&sandbox=true"

# Check stability before a large sandbox settlement
curl "https://stability.untitledfinancial.com/reliability"

# Get live ESG score (sandbox flag not needed — always live data)
curl "https://esg.untitledfinancial.com/esg-score"

Sandbox responses are identical in shape to production responses. The only differences:

Field	Sandbox	Production
`quoteId`	Mock UUID prefixed `sandbox_`	Real UUID, on-chain verifiable
`settlementRef`	Mock reference	On-chain tx hash on Base
`onChain`	`false`	`true` after settlement executes
`esgRedistribution.txHash`	`null`	Storacha IPFS CID

Transaction lifecycle

Every settlement moves through a defined set of states. If anything goes wrong, the quoteId is your recovery key.

QUOTED → VERIFYING → EXECUTING → CONFIRMED → REDISTRIBUTING → COMPLETE
                                     ↓
                                  FAILED → REFUNDED

States explained

State	What it means	What you can do
`QUOTED`	Fee quote returned, quoteId issued	Quote valid for 300 seconds. Pass quoteId to settlement call.
`VERIFYING`	Oracle confirming fees match on-chain enforcement	Wait — takes 1–3 seconds. Do not resubmit.
`EXECUTING`	Transaction submitted to Base mainnet	Wait for block confirmation (~2 seconds on Base).
`CONFIRMED`	Settlement tx included in a block	Safe to notify counterparty. TxHash is available.
`REDISTRIBUTING`	ESG fee being distributed to impact pools	Automatic. Completes within 1 block after settlement.
`COMPLETE`	All components settled and ESG redistributed	Final state. IPFS receipt available.
`FAILED`	Transaction reverted or oracle unreachable	See error scenarios below. Funds not moved.
`REFUNDED`	Failed settlement — funds returned to sender	Confirmed by on-chain event. No action needed.

Tracking a settlement

By quoteId

The quoteId returned by /quote is your reference for the entire lifecycle.

# Check settlement status by quoteId
curl "https://stability.untitledfinancial.com/settlement/{quoteId}"

Response includes current state, txHash (once EXECUTING), and ESG redistribution receipts (once REDISTRIBUTING).

On-chain via Basescan

Every confirmed settlement is visible at basescan.org with the Base mainnet tx hash. Search by:

Transaction hash (0x...)
Sender wallet address
DPXSettlementRouter contract address: (address published once deployed)

Via oracle health

# Check if oracle is live and processing
curl "https://stability.untitledfinancial.com/health"

# Check current peg deviation — flag if > 50 bps
curl "https://stability.untitledfinancial.com/reliability"

Error scenarios

The oracle is unreachable

Symptom: /quote or /reliability returns a network error or 5xx.

What happens to funds: Nothing. No settlement is submitted without a valid quote response. If the oracle goes down after EXECUTING has started, the transaction is either already in the mempool (safe) or not yet submitted (no risk).

Recovery:

Check /health — if down, wait and retry. Fly.io restarts automatically within 30–60 seconds.
If you need to proceed urgently, query /reliability directly — the peg stability data is cached and may still respond.
Do not resubmit with a new amount. The original quoteId is still valid for 300 seconds from issue time.

The quote expired (> 300 seconds)

Symptom: Settlement call returns QUOTE_EXPIRED.

What happens to funds: Nothing. Expired quotes are rejected before any on-chain transaction is initiated.

Recovery: Request a new quote via /quote with the same parameters. The new quote will reflect current oracle pricing.

Settlement transaction reverted

Symptom: State moves to FAILED. On-chain tx shows reverted.

What happens to funds: The transaction reverted — funds were never transferred. The sender’s wallet balance is unchanged (minus Base gas, typically < $0.05).

Common causes and fixes:

Cause	How to identify	Fix
Fee mismatch	Oracle fee changed between quote and execution	Re-quote and resubmit
Insufficient token balance	Sender wallet has less DPX than settlement amount + fees	Top up wallet before retrying
Router not approved	ERC-20 approval not granted to `DPXSettlementRouter`	Call `approve(routerAddress, amount)` on DPX token first
Stability check failed	`isHealthy: false` on `/reliability`	Wait for oracle to restore stability, then retry

Funds appear stuck — settlement shows EXECUTING but no tx hash

Symptom: Status shows EXECUTING for more than 30 seconds. No tx hash returned.

What’s likely happening: Transaction is in the Base mempool, waiting for inclusion. Base typically confirms in 2 seconds — if it takes longer, network congestion is unusual but possible.

What to do:

Wait up to 60 seconds before taking action.
Check basescan.org for the sender wallet address — if the transaction appears as pending, it is in the mempool and will confirm.
Do not resubmit. Resubmitting creates a duplicate transaction risk. The first one will resolve.
If no pending tx on Basescan after 60 seconds, the submission may have failed silently — check /settlement/{quoteId} for state update.

ESG redistribution didn’t appear

Symptom: Settlement is CONFIRMED but esgRedistribution shows no IPFS receipt.

What happened: The redistribution call happens in a separate transaction after settlement confirmation. It is automatic but separate.

What to do:

Wait for one additional block (~2 seconds on Base).
Re-query /settlement/{quoteId} — the esgRedistribution.txHash and IPFS CID will appear once the redistribution transaction confirms.
If after 5 minutes there’s no receipt, contact partner@untitledfinancial.com with the quoteId — we can trace the redistribution tx manually.

Peg deviation alert — should I settle?

Symptom: /reliability returns peg.deviationBps >= 50 or stability.currentScore < 70.

Decision framework:

Stability Score	Peg Deviation	Recommendation
≥ 90	< 20 bps	Proceed — oracle fully healthy
70–89	20–49 bps	Proceed with monitoring — elevated but within tolerance
< 70	≥ 50 bps	Delay if possible — oracle is flagging instability
Any	≥ 100 bps	Do not settle — wait for oracle confirmation of peg restoration

For large settlements (> $1M), always call /reliability first and check isHealthy. The oracle provides 30–90 day early warning signals precisely for this purpose.

Pilot checklist

Before settling real funds for the first time:

Test the full flow in sandbox mode with your target amount and ESG score
Confirm the /reliability stability score is ≥ 90 and isHealthy: true
Verify your DPX wallet has sufficient balance (settlement amount + fees + gas reserve)
Grant ERC-20 approval to DPXSettlementRouter for at least the settlement amount
Record the quoteId before submitting — this is your recovery key
Have the oracle health endpoint bookmarked: https://stability.untitledfinancial.com/health
Have Basescan open with your wallet address ready to verify tx inclusion

Monitoring during a pilot

Set up a simple peg alert using n8n or a cron script:

# Peg monitor — run every 5 minutes
curl -s "https://stability.untitledfinancial.com/reliability" | \
  python3 -c "import sys,json; d=json.load(sys.stdin); \
  print('ALERT' if d['peg']['deviationBps']>=50 else 'OK', d['peg']['deviationBps'], 'bps')"

Or use the n8n workflow template — the peg alert workflow is pre-built.

Getting pilot support

Contact partner@untitledfinancial.com with:

Your quoteId for any transaction you want traced
The error or state you’re seeing
The endpoint and parameters you called

Response time during beta: 1–2 business days. For urgent settlement issues during a live pilot, include “URGENT” in the subject line.

Request pilot access →